[gnuastro-commits] master ace4160 017/113: New --mcolisbrightness option for MakeProfiles

[Mohammad Akhlaghi]

branch: master
commit ace41609e53e902a9fac1db62425bfa0df101466
Author: Mohammad Akhlaghi <akhlaghi@gnu.org>
Commit: Mohammad Akhlaghi <akhlaghi@gnu.org>

    New --mcolisbrightness option for MakeProfiles
    
    It might happen that the user knows the total brightness of the profiles
    they want and don't want to go through the trouble of converting the
    magnitude to brightness (sum of pixel values). With this commit, they can
    do this by using the new `--mcolisbrightness' option.
    
    Also, I noticed that the configuration file to help use NoiseChisel in 3D
    was not installed in the previous commits. With this commit,
    `astnoisechisel-3d.conf' is also installed.
    
    Finally, a notice was added in the book on how to define a shell alias for
    MakeProfiles and NoiseChisel to automatically call them along with their 3D
    configuration files.
---
 NEWS                        |  4 ++
 bin/mkprof/args.h           | 15 +++++++-
 bin/mkprof/main.h           |  1 +
 bin/mkprof/oneprofile.c     |  6 ++-
 bin/mkprof/ui.c             | 10 ++++-
 bin/mkprof/ui.h             |  1 +
 bin/noisechisel/Makefile.am |  2 +-
 doc/gnuastro.texi           | 92 +++++++++++++++++++++++++++++++++++++++++++--
 8 files changed, 122 insertions(+), 9 deletions(-)

diff --git a/NEWS b/NEWS
index 964206a..9a81069 100644
--- a/NEWS
+++ b/NEWS
@@ -30,6 +30,10 @@ GNU Astronomy Utilities NEWS                          -*- 
outline -*-
   from the center. It can be used to build any other radial profile that is
   not supported by MakeProfiles.
 
+  MakeProfiles: with the new `--mcolisbrightness' ("mcol-is-brightness")
+  option, the `--mcol' values of the catalog will be interpretted as total
+  brightness (sum of pixel values), not magnitude.
+
 ** Removed features
 
 ** Changed features
diff --git a/bin/mkprof/args.h b/bin/mkprof/args.h
index 41bcff1..dafea6a 100644
--- a/bin/mkprof/args.h
+++ b/bin/mkprof/args.h
@@ -244,6 +244,19 @@ struct argp_option program_options[] =
       GAL_OPTIONS_NOT_SET
     },
     {
+      "mcolisbrightness",
+      UI_KEY_MCOLISBRIGHTNESS,
+      0,
+      0,
+      "mcol is total brightness, not magnitude.",
+      ARGS_GROUP_PROFILES,
+      &p->mcolisbrightness,
+      GAL_OPTIONS_NO_ARG_TYPE,
+      GAL_OPTIONS_RANGE_0_OR_1,
+      GAL_OPTIONS_NOT_MANDATORY,
+      GAL_OPTIONS_NOT_SET
+    },
+    {
       "shift",
       UI_KEY_SHIFT,
       "INT[, ...]",
@@ -280,7 +293,7 @@ struct argp_option program_options[] =
       &p->zeropoint,
       GAL_TYPE_FLOAT32,
       GAL_OPTIONS_RANGE_ANY,
-      GAL_OPTIONS_MANDATORY,
+      GAL_OPTIONS_NOT_MANDATORY,
       GAL_OPTIONS_NOT_SET
     },
     {
diff --git a/bin/mkprof/main.h b/bin/mkprof/main.h
index 64b7ccb..8ff9c37 100644
--- a/bin/mkprof/main.h
+++ b/bin/mkprof/main.h
@@ -145,6 +145,7 @@ struct mkprofparams
   char                *mcol;  /* Magnitude column.                        */
   char                *tcol;  /* Truncation of the profiles.              */
   uint8_t       mforflatpix;  /* mcol is flat pixel value (f is 4 or 5).  */
+  uint8_t  mcolisbrightness;  /* mcol is total brightness, not magnitude. */
   gal_data_t         *crpix;  /* CRPIX FITS header keywords.              */
   gal_data_t         *crval;  /* CRVAL FITS header keywords.              */
   gal_data_t         *cdelt;  /* For CDELTi FITS header keywords.         */
diff --git a/bin/mkprof/oneprofile.c b/bin/mkprof/oneprofile.c
index 2d6fcef..a512247 100644
--- a/bin/mkprof/oneprofile.c
+++ b/bin/mkprof/oneprofile.c
@@ -523,8 +523,10 @@ oneprof_set_prof_params(struct mkonthread *mkp)
   int tp=p->tunitinp;
   size_t id=mkp->ibq->id, ndim=p->ndim;
 
-  /* Fill the most basic dimension and profile agnostic parameters. */
-  mkp->brightness = pow( 10, (p->zeropoint - p->m[id]) / 2.5f );
+  /* Fill the most basic profile agnostic parameters. */
+  mkp->brightness = ( p->mcolisbrightness
+                      ? p->m[id]
+                      : pow( 10, (p->zeropoint - p->m[id]) / 2.5f ) );
   mkp->ibq->ispsf = p->kernel ? 1 : oneprofile_ispsf(p->f[id]);
   mkp->func       = mkp->ibq->func = p->f[id];
 
diff --git a/bin/mkprof/ui.c b/bin/mkprof/ui.c
index a9b47c5..2289423 100644
--- a/bin/mkprof/ui.c
+++ b/bin/mkprof/ui.c
@@ -197,7 +197,7 @@ ui_initialize_options(struct mkprofparams *p,
 
   /* Default program parameters. */
   p->cp.type=GAL_TYPE_FLOAT32;
-
+  p->zeropoint=NAN;
 
   /* Modify the common options for this program. */
   for(i=0; !gal_options_is_last(&cp->coptions[i]); ++i)
@@ -592,6 +592,14 @@ ui_read_check_only_options(struct mkprofparams *p)
               "coordinate columns");
     }
 
+  /* The zeropoint magnitude is only necessary when `mcolisbrightness' is
+     not called.  */
+  if( p->mcolisbrightness==0 && isnan(p->zeropoint) )
+    error(EXIT_FAILURE, 0, "no zeropoint magnitude given. A zeropoint "
+          "magnitude is necessary when `--mcolisbrightness' is not called "
+          "(i.e., when the contents of `--mcol' must be interpretted as "
+          "a magnitude, not brightness).");
+
   /* Make sure no zero value is given for the `--naxis' option (only when
      it is necessary). */
   if(p->dsize && p->backname==NULL)
diff --git a/bin/mkprof/ui.h b/bin/mkprof/ui.h
index d75b774..2a7b791 100644
--- a/bin/mkprof/ui.h
+++ b/bin/mkprof/ui.h
@@ -59,6 +59,7 @@ enum option_keys_enum
   /* Only with long version. */
   UI_KEY_PSFINIMG        = 1000,
   UI_KEY_MAGATPEAK,
+  UI_KEY_MCOLISBRIGHTNESS,
   UI_KEY_MODE,
   UI_KEY_CCOL,
   UI_KEY_FCOL,
diff --git a/bin/noisechisel/Makefile.am b/bin/noisechisel/Makefile.am
index a0dd0cb..5a9c83b 100644
--- a/bin/noisechisel/Makefile.am
+++ b/bin/noisechisel/Makefile.am
@@ -40,4 +40,4 @@ EXTRA_DIST = main.h authors-cite.h args.h ui.h clumps.h 
detection.h     \
 
 ## The configuration file (distribute and install).
 ## NOTE: the man page is created in doc/Makefile.am
-dist_sysconf_DATA = astnoisechisel.conf
+dist_sysconf_DATA = astnoisechisel.conf astnoisechisel-3d.conf
diff --git a/doc/gnuastro.texi b/doc/gnuastro.texi
index 1b41a40..7d84107 100644
--- a/doc/gnuastro.texi
+++ b/doc/gnuastro.texi
@@ -4749,10 +4749,10 @@ command-line or in the configuration files. In any 
case, it will be
 immediately read (before parsing the rest of the options on the
 command-line, or lines in a configuration file).
 
-Note that by definition, later options on the command-line still take
-precedence over those in these in any configuration file, including the
-file(s) given to this option. Also see @option{--lastconfig} and
-@option{--onlyversion} on how this option can be used for reproducible
+Note that by definition, later calls to a single-valued option on the
+command-line still take precedence over those of any configuration file,
+including the file(s) given to this option. Also see @option{--lastconfig}
+and @option{--onlyversion} for how this option can be used for reproducible
 results.
 
 @item -S
@@ -12266,6 +12266,51 @@ $ astnoisechisel --help | grep check
 @end example
 @end cartouche
 
+When working on 3D datacubes, the tessellation options need three values
+and updating them every time can be annoying/buggy. To simplify the job,
+NoiseChisel also installs a @file{astnoisechisel-3d.conf} configuration
+file (see @ref{Configuration files}). You can use this for default values
+on datacubes. For example, if you installed Gnuastro with the prefix
+@file{/usr/local} (the default location, see @ref{Installation directory}),
+you can benefit from this configuration file by running NoiseChisel like
+the example below.
+
+@example
+$ astnoisechisel cube.fits                                      \
+                 --config=/usr/local/etc/astnoisechisel-3d.conf
+@end example
+
+@cindex Shell alias
+@cindex Alias (shell)
+@cindex Shell startup
+@cindex Startup, shell
+To further simplify the process, you can define a shell alias in any
+startup file (for example @file{~/.bashrc}, see @ref{Installation
+directory}). Assuming that you installed Gnuastro in @file{/usr/local}, you
+can add this line to the startup file (you may put it all in one line, it
+is broken into two lines here for fitting within page limits).
+
+@example
+alias astnoisechisel-3d="astnoisechisel
+                    --config=/usr/local/etc/astnoisechisel-3d.conf"
+@end example
+
+@noindent
+Using this alias, you can call NoiseChisel with the name
+@command{astnoisechisel-3d} (instead of @command{astnoisechisel}). It will
+automatically load the 3D specific configuration file first, and then parse
+any other arguments, options or configuration files. You can change the
+default values in this 3D configuration file by calling them on the
+command-line as you do with @command{astnoisechisel}@footnote{Recall that
+for single-invocation options, the last command-line invocation takes
+precedence over all previous invocations (including those in the 3D
+configuration file). See the description of @option{--config} in
+@ref{Operating mode options}.}. For example:
+
+@example
+$ astnoisechisel-3d --numchannels=3,3,1 cube.fits
+@end example
+
 In the sections below, NoiseChisel's options are classified into three
 general classes to help in easy navigation. @ref{General NoiseChisel
 options} mainly discusses the options relating to input and those that are
@@ -14812,6 +14857,32 @@ file.
 $ astmkprof --config=/usr/local/etc/astmkprof-3d.conf catalog.txt
 @end example
 
+@cindex Shell alias
+@cindex Alias, shell
+@cindex Shell startup
+@cindex Startup, shell
+To further simplify the process, you can define a shell alias in any
+startup file (for example @file{~/.bashrc}, see @ref{Installation
+directory}). Assuming that you installed Gnuastro in @file{/usr/local}, you
+can add this line to the startup file (you may put it all in one line, it
+is broken into two lines here for fitting within page limits).
+
+@example
+alias astmkprof-3d="astmkprof --config=/usr/local/etc/astmkprof-3d.conf"
+@end example
+
+@noindent
+Using this alias, you can call MakeProfiles with the name
+@command{astmkprof-3d} (instead of @command{astmkprof}). It will
+automatically load the 3D specific configuration file first, and then parse
+any other arguments, options or configuration files. You can change the
+default values in this 3D configuration file by calling them on the
+command-line as you do with @command{astmkprof}@footnote{Recall that for
+single-invocation options, the last command-line invocation takes
+precedence over all previous invocations (including those in the 3D
+configuration file). See the description of @option{--config} in
+@ref{Operating mode options}.}.
+
 Please see @ref{Sufi simulates a detection} for a very complete tutorial
 explaining how one could use MakeProfiles in conjunction with other
 Gnuastro's programs to make a complete simulated image of a mock galaxy.
@@ -15058,6 +15129,19 @@ scaled up based on the oversampling scale in your 
configuration files (see
 @ref{Configuration files}) unless you have accounted for oversampling in
 your catalog.
 
+@item --mcolisbrightness
+The value given in the ``magnitude column'' (specified by @option{--mcol},
+see @ref{MakeProfiles catalog}) must be interpretted as brightness, not
+magnitude. The zeropoint magnitude (value to the @option{--zeropoint}
+option) is ignored and the given value must have the same units as the
+input dataset's pixels.
+
+Recall that the total profile magnitude or brightness that is specified
+with in the @option{--mcol} column of the input catalog is not an
+integration to infinity, but the actual sum of pixels in the profile (until
+the desired truncation radius). See @ref{Profile magnitude} for more on
+this point.
+
 @item --magatpeak
 The magnitude column in the catalog (see @ref{MakeProfiles catalog})
 will be used to find the brightness only for the peak profile pixel,