[gnuastro-commits] master 76073059: Arithmetic: options to add metadata (name, units, comment) in output

[Mohammad Akhlaghi]

branch: master
commit 760730593d97012e23a7b8dd5ebba81685b7df25
Author: Mohammad Akhlaghi <mohammad@akhlaghi.org>
Commit: Mohammad Akhlaghi <mohammad@akhlaghi.org>

    Arithmetic: options to add metadata (name, units, comment) in output
    
    Until now, after a user finished their desired operations on an image and
    generated and output with Arithmetic, if they wanted to add metadata to the
    image, they would have to use a separate call to the Fits program and add
    them. This extra command was annoying and could even discourage adding
    metadata.
    
    With this commit, the Arithmetic program has three new options to add a
    name ('--metaname'), unit ('--metaunit') and a comment ('--metacomment') to
    the output HDU.
---
 NEWS                        | 16 ++++++++++++++++
 bin/arithmetic/args.h       | 39 +++++++++++++++++++++++++++++++++++++++
 bin/arithmetic/arithmetic.c | 14 ++++++++++++++
 bin/arithmetic/main.h       |  3 +++
 bin/arithmetic/ui.c         |  3 +++
 bin/arithmetic/ui.h         |  5 ++++-
 doc/gnuastro.texi           | 22 ++++++++++++++++++++++
 7 files changed, 101 insertions(+), 1 deletion(-)

diff --git a/NEWS b/NEWS
index d24b1d4f..075de726 100644
--- a/NEWS
+++ b/NEWS
@@ -42,6 +42,22 @@ See the end of the file for license conditions.
        sampling (to make the final distribution less descrete). See the
        example in the book for selecting random star magnitudes based on
        Gaia's observed magnitude distribution.
+   - New options to add metadata (standard FITS keywords) to your output
+     for easy understanding of the data in the future, or by your
+     colleagues if you share the output). Until now, to have this feature,
+     you needed to call Fits on the output of Arithmetic (for setting the
+     HDU name to "my-sum" for example):
+         astarithmetic img-a.fits img-b.fits + --output=sum.fits
+         astfits sum.fits --write=EXTNAME,"my-sum"
+     But with the following commands, you can add important metadata to the
+     output of Arithmetic in the same command and simplify your scripts:
+       --metaname: Metadata name of the output (FITS keyword: 'EXTNAME').
+       --metaunit: Unit of the output's pixels (FITS keyword: 'BUNIT').
+       --metacomment: Description of the data (FITS keyword: 'COMMENT').
+     Like the following for the example above:
+         astarithmetic img-a.fits img-b.fits + --metaname="my-sum" \
+                       --output=sum.fits
+
 
   Crop:
    --oneelemstdout: when a crop has a single pixel and this option is
diff --git a/bin/arithmetic/args.h b/bin/arithmetic/args.h
index 1e03af64..5b3d4b26 100644
--- a/bin/arithmetic/args.h
+++ b/bin/arithmetic/args.h
@@ -113,6 +113,45 @@ struct argp_option program_options[] =
       GAL_OPTIONS_NOT_MANDATORY,
       GAL_OPTIONS_NOT_SET
     },
+    {
+      "metaname",
+      UI_KEY_METANAME,
+      "STR",
+      0,
+      "Internal name (FITS images: EXTNAME keyword).",
+      GAL_OPTIONS_GROUP_OUTPUT,
+      &p->metaname,
+      GAL_TYPE_STRING,
+      GAL_OPTIONS_RANGE_ANY,
+      GAL_OPTIONS_NOT_MANDATORY,
+      GAL_OPTIONS_NOT_SET
+    },
+    {
+      "metaunit",
+      UI_KEY_METAUNIT,
+      "STR",
+      0,
+      "Internal units (FITS images: BUNIT keyword).",
+      GAL_OPTIONS_GROUP_OUTPUT,
+      &p->metaunit,
+      GAL_TYPE_STRING,
+      GAL_OPTIONS_RANGE_ANY,
+      GAL_OPTIONS_NOT_MANDATORY,
+      GAL_OPTIONS_NOT_SET
+    },
+    {
+      "metacomment",
+      UI_KEY_METACOMMENT,
+      "STR",
+      0,
+      "Internal comments (FITS images: COMMENT keyword).",
+      GAL_OPTIONS_GROUP_OUTPUT,
+      &p->metacomment,
+      GAL_TYPE_STRING,
+      GAL_OPTIONS_RANGE_ANY,
+      GAL_OPTIONS_NOT_MANDATORY,
+      GAL_OPTIONS_NOT_SET
+    },
 
     {0}
   };
diff --git a/bin/arithmetic/arithmetic.c b/bin/arithmetic/arithmetic.c
index 3f306615..5722633d 100644
--- a/bin/arithmetic/arithmetic.c
+++ b/bin/arithmetic/arithmetic.c
@@ -1578,6 +1578,18 @@ reversepolish(struct arithmeticparams *p)
     }
   else
     {
+      /* If the user has requested a name, units or comments for the FITS
+         file, insert them into the dataset here. */
+      if(p->metaname)
+        { if(data->name) free(data->name);
+          gal_checkset_allocate_copy(p->metaname, &data->name); }
+      if(p->metaunit)
+        { if(data->unit) free(data->unit);
+          gal_checkset_allocate_copy(p->metaunit, &data->unit); }
+      if(p->metacomment)
+        { if(data->comment) free(data->comment);
+          gal_checkset_allocate_copy(p->metacomment, &data->comment); }
+
       /* Put a copy of the WCS structure from the reference image, it
          will be freed while freeing 'data'. */
       data->wcs=p->refdata.wcs;
@@ -1587,6 +1599,8 @@ reversepolish(struct arithmeticparams *p)
                         "ARITHMETIC", 0);
       else
         gal_fits_img_write(data, p->cp.output, NULL, PROGRAM_NAME);
+
+      /* Let the user know that the job is done. */
       if(!p->cp.quiet)
         printf(" - Write (final): %s\n", p->cp.output);
     }
diff --git a/bin/arithmetic/main.h b/bin/arithmetic/main.h
index 6d2aa4f0..c0eeddae 100644
--- a/bin/arithmetic/main.h
+++ b/bin/arithmetic/main.h
@@ -82,6 +82,9 @@ struct arithmeticparams
   char          *globalhdu;  /* Single HDU for all inputs.              */
   uint8_t      onedasimage;  /* Write 1D outputs as an image not table. */
   uint8_t     onedonstdout;  /* Write 1D outputs on stdout, not table.  */
+  char           *metaname;  /* FITS name (EXTNAME keyword) of output.  */
+  char           *metaunit;  /* FITS name (BUNIT keyword) of output.    */
+  char        *metacomment;  /* FITS comment of output.                 */
 
   /* Operating mode: */
   int        wcs_collapsed;  /* If the internal WCS is already collapsed.*/
diff --git a/bin/arithmetic/ui.c b/bin/arithmetic/ui.c
index cd453887..a58f2c28 100644
--- a/bin/arithmetic/ui.c
+++ b/bin/arithmetic/ui.c
@@ -520,7 +520,10 @@ freeandreport(struct arithmeticparams *p, struct timeval 
*t1)
   /* Free the simple strings. */
   free(p->cp.output);
   if(p->wcshdu) free(p->wcshdu);
+  if(p->metaname) free(p->metaname);
+  if(p->metaunit) free(p->metaunit);
   if(p->globalhdu) free(p->globalhdu);
+  if(p->metacomment) free(p->metacomment);
 
   /* If there are any remaining HDUs in the hdus linked list, then
      free them. */
diff --git a/bin/arithmetic/ui.h b/bin/arithmetic/ui.h
index 952a882e..00e5d187 100644
--- a/bin/arithmetic/ui.h
+++ b/bin/arithmetic/ui.h
@@ -32,7 +32,7 @@ along with Gnuastro. If not, see 
<http://www.gnu.org/licenses/>.
 
 /* Available letters for short options:
 
-   a b c d e f i j k l m n p r t u v x y z
+   a b d e f i j k l m p r t v x y z
    A B C E G H J L Q R X Y
 */
 enum option_keys_enum
@@ -43,6 +43,9 @@ enum option_keys_enum
   UI_KEY_ONEDONSTDOUT    = 's',
   UI_KEY_WCSFILE         = 'w',
   UI_KEY_WCSHDU          = 'W',
+  UI_KEY_METANAME        = 'n',
+  UI_KEY_METAUNIT        = 'u',
+  UI_KEY_METACOMMENT     = 'c',
 
   /* 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 76561897..f84f4ba6 100644
--- a/doc/gnuastro.texi
+++ b/doc/gnuastro.texi
@@ -16765,6 +16765,28 @@ For more, see the description of @option{--wcsfile}.
 Use the environment for the random number generator settings in operators that 
need them (for example @code{mknoise-sigma}).
 This is very important for obtaining reproducible results, for more see 
@ref{Generating random numbers}.
 
+@item -n STR
+@itemx --metaname=STR
+Metadata (name) of the output dataset.
+For a FITS image or table, the string given to this option is written in the 
@code{EXTNAME} or @code{TTYPE1} keyword (respectively).
+
+If this keyword is present in a FITS extension, it will be printed in the 
table output of a command like @command{astfits image.fits} (for images) or 
@command{asttable table.fits -i} (for tables).
+This metadata can be very helpful for yourself in the future (when you have 
forgotten the details), so its recommended to use this option for files that 
should be archived or shared with colleagues.
+
+@item -u STR
+@itemx --metaunit=STR
+Metadata (units) of the output dataset.
+For a FITS image or table, the string given to this option is written in the 
@code{BUNIT} or @code{TTYPE1} keyword respectively.
+In the case of tables, recall that the Arithmetic program only outputs a 
single column, you should use column arithmetic in Table for more than one 
column (see @ref{Column arithmetic}).
+For more on the importance of metadata, see the description of 
@option{--metaname}.
+
+@item -c STR
+@itemx --metacomment=STR
+Metadata (comments) of the output dataset.
+For a FITS image or table, the string given to this option is written in the 
@code{COMMENT} or @code{TCOMM1} keyword respectively.
+In the case of tables, recall that the Arithmetic program only outputs a 
single column, you should use column arithmetic in Table for more than one 
column (see @ref{Column arithmetic}).
+For more on the importance of metadata, see the description of 
@option{--metaname}.
+
 @item -O
 @itemx --onedasimage
 Write final dataset as a FITS image/array even if it has a single dimension.