[gnuastro-commits] master 644ca1f: MakeNoise: new --bgisbrightness option to interpret --background

[Mohammad Akhlaghi]

branch: master
commit 644ca1f2661fbdedc1708eb78dbf53a0436fc5be
Author: Mohammad Akhlaghi <mohammad@akhlaghi.org>
Commit: Mohammad Akhlaghi <mohammad@akhlaghi.org>

    MakeNoise: new --bgisbrightness option to interpret --background
    
    Until now, the value to the '--background' option would always be
    interpretted as a magnitude. But the magnitude always needs a zeropoint and
    in some scenarios (raw tests), we already have the background value in
    brightness. Hence converting the background value to magnitudes was just an
    extra annoying step.
    
    With this commit, MakeNoise has the new '--bgisbrightness' option to let
    the user inform the program that the value given to '--background' should
    be interpreted as brightness, not magnitude.
---
 NEWS               |  5 +++++
 bin/mknoise/args.h | 13 +++++++++++++
 bin/mknoise/main.h |  1 +
 bin/mknoise/ui.c   | 14 +++++++++-----
 bin/mknoise/ui.h   | 13 +++++++------
 doc/gnuastro.texi  | 34 +++++++++++++++++++++++++---------
 6 files changed, 60 insertions(+), 20 deletions(-)

diff --git a/NEWS b/NEWS
index 29c4912..074a7b3 100644
--- a/NEWS
+++ b/NEWS
@@ -69,6 +69,11 @@ See the end of the file for license conditions.
      value: '--minvx', '--maxvx', '--minvy', '--maxvy', '--minvz',
      '--maxvz'.
 
+  MakeNoise:
+   --bgisbrightness: new option to say that the value of '--background'
+     (used to simulate Poisson noise) should be interpretted as brightness,
+     not magnitude.
+
   Table:
    - New '--noblank' option will remove all rows in output table that have
      atleast one blank value in the specified columns. For example if
diff --git a/bin/mknoise/args.h b/bin/mknoise/args.h
index 980da68..eda7581 100644
--- a/bin/mknoise/args.h
+++ b/bin/mknoise/args.h
@@ -83,6 +83,19 @@ struct argp_option program_options[] =
       GAL_OPTIONS_NOT_MANDATORY,
       GAL_OPTIONS_NOT_SET
     },
+    {
+      "bgisbrightness",
+      UI_KEY_BGISBRIGHTNESS,
+      0,
+      0,
+      "Background is brightness, not magnitude.",
+      GAL_OPTIONS_GROUP_OPERATING_MODE,
+      &p->bgisbrightness,
+      GAL_OPTIONS_NO_ARG_TYPE,
+      GAL_OPTIONS_RANGE_0_OR_1,
+      GAL_OPTIONS_NOT_MANDATORY,
+      GAL_OPTIONS_NOT_SET
+    },
 
 
 
diff --git a/bin/mknoise/main.h b/bin/mknoise/main.h
index 68f8be0..3f357f9 100644
--- a/bin/mknoise/main.h
+++ b/bin/mknoise/main.h
@@ -48,6 +48,7 @@ struct mknoiseparams
   double    instrumental;    /* Standard deviation constants.            */
   double       zeropoint;    /* Zeropoint magnitude of image.            */
   double  background_mag;    /* Background in magnitudes.                */
+  uint8_t bgisbrightness;    /* Background is brightness, not magnitude. */
   uint8_t        envseed;    /* ==1, generate a random seed.             */
 
   /* Internal */
diff --git a/bin/mknoise/ui.c b/bin/mknoise/ui.c
index b5a8596..c299288 100644
--- a/bin/mknoise/ui.c
+++ b/bin/mknoise/ui.c
@@ -227,13 +227,15 @@ ui_read_check_only_options(struct mknoiseparams *p)
           "must be given to identify the noise level");
 
 
-  /* If a background magnitude is given (and the user hasn't given a
-     '--sigma'), the zeropoint is necessary. */
-  if( isnan(p->sigma) && !isnan(p->background_mag) && isnan(p->zeropoint) )
+  /* If a background magnitude is given ('--bgbrightness' hasn't been
+     called), the zeropoint is necessary. */
+  if( !isnan(p->background_mag) && p->bgisbrightness==0 && isnan(p->zeropoint) 
)
     error(EXIT_FAILURE, 0, "no zeropoint magnitude given. When the noise is "
           "identified by the background magnitude, a zeropoint magnitude "
           "is mandatory. Please use the '--zeropoint' option to specify "
-          "a zeropoint magnitude");
+          "a zeropoint magnitude. Alternatively, if your background value "
+          "is in units of brightness (which doesn't need a zeropoint), "
+          "please use '--bgisbrightness'");
 }
 
 
@@ -312,7 +314,9 @@ ui_preparations(struct mknoiseparams *p)
      pixels independently, brightness and flux are the same (flux is
      multiplied by the area of one pixel (=1) to give brightness).*/
   if( !isnan(p->background_mag) )
-    p->background=pow(10, (p->zeropoint-p->background_mag)/2.5f);
+    p->background = ( p->bgisbrightness
+                      ? p->background_mag
+                      : pow(10, (p->zeropoint-p->background_mag)/2.5f) );
 
 
   /* Allocate the random number generator: */
diff --git a/bin/mknoise/ui.h b/bin/mknoise/ui.h
index a604d8d..86976c6 100644
--- a/bin/mknoise/ui.h
+++ b/bin/mknoise/ui.h
@@ -33,16 +33,17 @@ along with Gnuastro. If not, see 
<http://www.gnu.org/licenses/>.
 /* Available letters for short options:
 
    a c d f g j k l m n p r t u v w x y
-   A B C E G H J L O Q R W X Y
+   A C E G H J L O Q R W X Y
 */
 enum option_keys_enum
 {
   /* With short-option version. */
-  UI_KEY_SIGMA        = 's',
-  UI_KEY_INSTRUMENTAL = 'i',
-  UI_KEY_BACKGROUND   = 'b',
-  UI_KEY_ZEROPOINT    = 'z',
-  UI_KEY_ENVSEED      = 'e',
+  UI_KEY_SIGMA          = 's',
+  UI_KEY_INSTRUMENTAL   = 'i',
+  UI_KEY_BACKGROUND     = 'b',
+  UI_KEY_ZEROPOINT      = 'z',
+  UI_KEY_ENVSEED        = 'e',
+  UI_KEY_BGISBRIGHTNESS = 'B',
 
   /* Only with long version (start with a value 1000, the rest will be set
      automatically). */
diff --git a/doc/gnuastro.texi b/doc/gnuastro.texi
index b340996..aebca5e 100644
--- a/doc/gnuastro.texi
+++ b/doc/gnuastro.texi
@@ -18155,7 +18155,8 @@ $ astmknoise [OPTION ...] InputImage.fits
 One line examples:
 
 @example
-## Add noise with a standard deviation of 100 to image:
+## Add noise with a standard deviation of 100 to image.
+## (this is independent of the pixel value: not Poission noise)
 $ astmknoise --sigma=100 image.fits
 
 ## Add noise to input image assuming a background magnitude (with
@@ -18172,16 +18173,20 @@ This is done for future reproducibility.
 
 @table @option
 
-@item -s FLT
-@item --sigma=FLT
-The total noise sigma in the same units as the pixel values.
-With this option, the @option{--background}, @option{--zeropoint} and 
@option{--instrumental} will be ignored.
-With this option, the noise will be independent of the pixel values (which is 
not realistic, see @ref{Photon counting noise}).
-Hence it is only useful if you are working on low surface brightness regions 
where the change in pixel value (and thus real noise) is insignificant.
-
 @item -b FLT
 @itemx --background=FLT
-The background pixel value for the image in units of magnitudes, see 
@ref{Photon counting noise} and @ref{Brightness flux magnitude}.
+The background value (per pixel) that will be added to each pixel value 
(internally) to estimate Poisson noise, see @ref{Photon counting noise}.
+By default the units of this value are assumed to be in magnitudes, hence a 
@option{--zeropoint} is also necessary.
+But if the background is in units of brightness, you need add 
@option{--bgisbrightness}, see @ref{Brightness flux magnitude}
+
+Internally, the value given to this option will be converted to brightness 
(@mymath{b}, when @option{--bgisbrightness} is called, the value will be used 
directly).
+Assuming the pixel value is @mymath{p}, the random value for that pixel will 
be taken from a Gaussian distribution with mean of @mymath{p+b} and standard 
deviation of @mymath{\sqrt{p+b}}.
+With this option, the noise will therefore be dependent on the pixel values: 
according to the Poission noise model, as the pixel value becomes larger, its 
noise will also become larger.
+This is thus a realistic way to model noise, see @ref{Photon counting noise}.
+
+@item -B
+@itemx --bgisbrightness
+The value given to @option{--background} should be interpretted as brightness, 
not as a magnitude.
 
 @item -z FLT
 @itemx --zeropoint=FLT
@@ -18191,6 +18196,17 @@ The zero point magnitude used to convert the value of 
@option{--background} (in
 @itemx --instrumental=FLT
 The instrumental noise which is in units of flux, see @ref{Instrumental noise}.
 
+@item -s FLT
+@item --sigma=FLT
+The total noise sigma in the same units as the pixel values.
+With this option, the @option{--background}, @option{--zeropoint} and 
@option{--instrumental} will be ignored.
+With this option, the noise will be independent of the pixel values (which is 
not realistic, see @ref{Photon counting noise}).
+Hence it is only useful if you are working on low surface brightness regions 
where the change in pixel value (and thus real noise) is insignificant.
+
+Generally, @strong{usage of this option is discouraged} unless you understand 
the risks of not simulating real noise.
+This is because with this option, you will not get Poisson noise (the common 
noise model for astronomical imaging), where the noise varies based on pixel 
value.
+Use @option{--background} for adding Poission noise.
+
 @item -e
 @itemx --envseed
 @cindex Seed, Random number generator