[gnuastro-commits] master 1b3d007 1/2: Table: --colmetadata is new name for recently added --metaupdate

[Mohammad Akhlaghi]

branch: master
commit 1b3d007de8b1dcca7ad3b2febc210b5508256236
Author: Mohammad Akhlaghi <mohammad@akhlaghi.org>
Commit: Mohammad Akhlaghi <mohammad@akhlaghi.org>

    Table: --colmetadata is new name for recently added --metaupdate
    
    We recently added the '--metaupdate' option to add/update column metadata
    to the Table program. But it isn't always a case of updating meta data,
    infact based on early experience, it will mostly be used for columns that
    have no metadata.
    
    With this commit, to avoid confusing new users, the name of the new option
    is now called '--colmetadata'.
---
 NEWS              | 10 +++++-----
 bin/table/args.h  |  6 +++---
 bin/table/main.h  |  2 +-
 bin/table/table.c |  8 ++++----
 bin/table/ui.c    |  8 ++++----
 bin/table/ui.h    |  2 +-
 doc/gnuastro.texi | 32 ++++++++++++++++----------------
 7 files changed, 34 insertions(+), 34 deletions(-)

diff --git a/NEWS b/NEWS
index 54c7481..3725e03 100644
--- a/NEWS
+++ b/NEWS
@@ -44,11 +44,11 @@ See the end of the file for license conditions.
      columns will be appended with a '-N' (where 'N' is a counter for the
      file that is used to append columns). The default behavior is to avoid
      multiple columns having the same name.
-   - New '--metaupdate' option to add/update the column metadata (name,
-     units or comments) just before writing the output. This is a very
-     useful feature in combination with column arithmetic or column
-     concatenation because it will allow you to update the new column
-     metadata in the same command. See the manual for more.
+   - New '--colmetadata' option to add/update column metadata (name, units
+     or comments) just before writing the output. This is a very useful
+     feature in combination with column arithmetic or column concatenation
+     because it will allow you to update the new column metadata in the
+     same command. See the manual for more.
 
   Library:
    - Spectral lines library: SiIII, OIII, CIV, NV and rest of Lyman series.
diff --git a/bin/table/args.h b/bin/table/args.h
index f273fd5..6d92d34 100644
--- a/bin/table/args.h
+++ b/bin/table/args.h
@@ -155,13 +155,13 @@ struct argp_option program_options[] =
       GAL_OPTIONS_NOT_SET
     },
     {
-      "metaupdate",
-      UI_KEY_METAUPDATE,
+      "colmetadata",
+      UI_KEY_COLMETADATA,
       "STR,STR[,STR,STR]",
       0,
       "Update output metadata (name, unit, comments).",
       GAL_OPTIONS_GROUP_OUTPUT,
-      &p->metaupdate,
+      &p->colmetadata,
       GAL_TYPE_STRING,
       GAL_OPTIONS_RANGE_ANY,
       GAL_OPTIONS_NOT_MANDATORY,
diff --git a/bin/table/main.h b/bin/table/main.h
index 3898512..1295401 100644
--- a/bin/table/main.h
+++ b/bin/table/main.h
@@ -104,7 +104,7 @@ struct tableparams
   gal_list_str_t *catcolumnhdu;  /* HDU/extension for the catcolumn.    */
   gal_list_str_t  *catcolumns;  /* List of columns to concatenate.      */
   uint8_t    catcolumnrawname;  /* Don't modify name of appended col.   */
-  gal_data_t      *metaupdate;  /* Update column metadata.              */
+  gal_data_t     *colmetadata;  /* Set column metadata.                 */
 
   /* Internal. */
   struct column_pack *outcols;  /* Output column packages.              */
diff --git a/bin/table/table.c b/bin/table/table.c
index 53db49a..52aac8c 100644
--- a/bin/table/table.c
+++ b/bin/table/table.c
@@ -677,14 +677,14 @@ table_catcolumn(struct tableparams *p)
 
 
 void
-table_metaupdate(struct tableparams *p)
+table_colmetadata(struct tableparams *p)
 {
   char **strarr;
   gal_data_t *meta, *col;
   size_t counter, *colnum;
 
   /* Loop through all the given updates and implement them. */
-  for(meta=p->metaupdate;meta!=NULL;meta=meta->next)
+  for(meta=p->colmetadata;meta!=NULL;meta=meta->next)
     {
       /* If the given column specifier is a name (not parse-able as a
          number), then this condition will fail. */
@@ -713,7 +713,7 @@ table_metaupdate(struct tableparams *p)
       /* If a match was found, then 'col' should not be NULL. */
       if(col==NULL)
         error(EXIT_FAILURE, 0, "no column found for '%s' (given to "
-              "'--metaupdate'). Columns can either be specified by "
+              "'--colmetadata'). Columns can either be specified by "
               "their position in the output table (integer counter, "
               "starting from 1), or their name (the first column "
               "found with the given name will be used)", meta->name);
@@ -785,7 +785,7 @@ table(struct tableparams *p)
   if(p->catcolumnfile) table_catcolumn(p);
 
   /* If column metadata should be updated, do it just before writing. */
-  if(p->metaupdate) table_metaupdate(p);
+  if(p->colmetadata) table_colmetadata(p);
 
   /* Write the output. */
   gal_table_write(p->table, NULL, p->cp.tableformat, p->cp.output,
diff --git a/bin/table/ui.c b/bin/table/ui.c
index 7c66f6b..7a37c8d 100644
--- a/bin/table/ui.c
+++ b/bin/table/ui.c
@@ -277,13 +277,13 @@ ui_read_check_only_options(struct tableparams *p)
     error(EXIT_FAILURE, 0, "'--head' and '--tail' options cannot be "
           "called together");
 
-  /* If '--metaupdate' is given, make sure none of the given options have
+  /* If '--colmetadata' is given, make sure none of the given options have
      more than three values. */
-  if(p->metaupdate)
-    for(tmp=p->metaupdate;tmp!=NULL;tmp=tmp->next)
+  if(p->colmetadata)
+    for(tmp=p->colmetadata;tmp!=NULL;tmp=tmp->next)
       if(tmp->size>3)
         error(EXIT_FAILURE, 0, "at most three values can be given to each "
-              "call of '--metaupdate' ('-m') after the original columns "
+              "call of '--colmetadata' ('-m') after the original columns "
               "name or number. But %zu strings have been given", tmp->size);
 }
 
diff --git a/bin/table/ui.h b/bin/table/ui.h
index 14f776c..cb90461 100644
--- a/bin/table/ui.h
+++ b/bin/table/ui.h
@@ -62,7 +62,7 @@ enum option_keys_enum
   UI_KEY_CATCOLUMNS      = 'C',
   UI_KEY_CATCOLUMNHDU    = 'u',
   UI_KEY_CATCOLUMNFILE   = 'L',
-  UI_KEY_METAUPDATE      = 'm',
+  UI_KEY_COLMETADATA     = 'm',
 
   /* 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 24d36be..13aa6fa 100644
--- a/doc/gnuastro.texi
+++ b/doc/gnuastro.texi
@@ -3090,15 +3090,15 @@ Right now, you know this.
 But in one hour, you'll start doubting your self: going through your command 
history, trying to answer this question: ``which magnitude corresponds to which 
filter?''.
 You should never torture your future-self (or colleagues) like this! So, let's 
rename these confusing columns in the matched catalog.
 
-Fortunately, with the @option{--metaupdate}, you can correct the column 
metadata of final table (just before it is written).
+Fortunately, with the @option{--colmetadata}, you can correct the column 
metadata of final table (just before it is written).
 For example by adding two calls to the previous command, we write the filter 
name in the magnitude column name and description.
 
 @example
 $ asttable cat/xdf-f160w.fits -hCLUMPS --output=both-mags.fits \
            --catcolumnfile=cat/xdf-f105w-on-f160w-lab.fits \
            --catcolumnhdu=CLUMPS --catcolumns=MAGNITUDE \
-           --metaupdate=MAGNITUDE,MAG-F160w,log,"Magnitude in F160W." \
-           --metaupdate=MAGNITUDE-1,MAG-F105w,log,"Magnitude in F105W."
+           --colmetadata=MAGNITUDE,MAG-F160w,log,"Magnitude in F160W." \
+           --colmetadata=MAGNITUDE-1,MAG-F105w,log,"Magnitude in F105W."
 $ asttable both-mags.fits -i
 @end example
 
@@ -3127,13 +3127,13 @@ $ asttable color-cat.fits -i
 
 The name of the column produced by arithmetic column is @command{ARITH_1}!
 This is natural: Arithmetic has no idea what the modified column is!
-So you can use @option{--metaupdate} to give a proper metadata like the 
example below.
+So you can use @option{--colmetadata} to give a proper metadata like the 
example below.
 Since this is the final table (we want to store it in @file{cat/}), we'll also 
give it a clear name and use the @option{--range} option to only print columns 
with a signal-to-noise ratio (@code{SN} column) above 5.
 
 @example
 $ asttable both-mags.fits --range=SN,5,inf -c1,2,RA,DEC \
            -cMAG-F160W,MAG-F105W -c'arith MAG-F105W MAG-F160W -' \
-           --metaupdate=ARITH_1,F105W-F160W,log,"Magnitude difference" \
+           --colmetadata=ARITH_1,F105W-F160W,log,"Magnitude difference" \
            --output=cat/mags-with-color.fits
 $ asttable cat/mags-with-color.fits -i
 @end example
@@ -3157,9 +3157,9 @@ $ aststatistics cat/mags-with-color.fits -cF105W-F160W \
 We won't go much deeper into the Statistics program here, but there is so much 
more you can do with it, please see @ref{Statistics} later.
 
 Let's finish this section of the tutorial with a useful tip on modifying 
column metadata.
-Above, updating/changing column metadata was done with the 
@option{--metaupdate} in the same command that produced the newly created Table 
file.
+Above, updating/changing column metadata was done with the 
@option{--colmetadata} in the same command that produced the newly created 
Table file.
 But in many sitations, the table is already made and you just want to update 
the metadata of one column.
-In such cases using @option{--metaupdate} is over-kill (wasting CPU/RAM energy 
or time if the table is large) because it will load the full table data and 
metadata into memory, just change the metadata and write it back into a file.
+In such cases using @option{--colmetadata} is over-kill (wasting CPU/RAM 
energy or time if the table is large) because it will load the full table data 
and metadata into memory, just change the metadata and write it back into a 
file.
 
 In scenarios when the table's data doesn't need to be changed, it is much more 
efficient to use basic FITS keyword editing to modify column metadata.
 The FITS standard for tables stores the column names in the @code{TTYPE} 
header keywords, so let's have a look:
@@ -9287,7 +9287,7 @@ By nature, column arithmetic changes the values of the 
data within the column.
 So the old column meta data can't be used any more.
 By default the new column created for the arithmetic operation will be given 
generic metadata (for example its name will be @code{ARITH_1}, which is hardly 
useful!).
 But meta data are critically important and it is good practice to always have 
short, but descriptive, names for each columns, units and also some comments 
for more explanation.
-To add metadata to a column, you can use the @option{--metaupdate} option that 
is described in @ref{Invoking asttable}.
+To add metadata to a column, you can use the @option{--colmetadata} option 
that is described in @ref{Invoking asttable}.
 
 Finally, since the arithmetic expressions are a value to @option{--column}, it 
doesn't necessarily have to be a separate option, so the commands above are 
also identical to the command below (note that this only has one @option{-c} 
option).
 Just be very careful with the quoting!
@@ -9523,7 +9523,7 @@ Also note that no operation (for example row selection, 
arithmetic or etc) is ap
 If the appended columns have a name, the column names of each file will be 
appended with a @code{-N}, where @code{N} is a counter starting from 1 for each 
appended file.
 This is done because when concatenating columns from multiple tables (more 
than two) into one, they may have the same name, and its not good practice to 
have multiple columns with the same name.
 You can disable this feature with @option{--catcolumnrawname}.
-To have full control over the concatenated column names, you can use the 
@option{--metaupdate} option described below.
+To have full control over the concatenated column names, you can use the 
@option{--colmetadata} option described below.
 
 For example, let's assume you have two catalogs of the same objects (same 
number of rows) in different filters.
 Such that @file{f160w-cat.fits} has a @code{MAGNITUDE} column that has the 
magnitude of each object in the @code{F160W} filter and similarly 
@file{f105w-cat.fits}, also has a @code{MAGNITUDE} column, but for the 
@code{F105W} filter.
@@ -9532,8 +9532,8 @@ You can use column concatenation like below to import the 
@code{MAGNITUDE} colum
 @example
 asttable f160w-cat.fits --output=both.fits \
   --catcolumnfile=f105w-cat.fits --catcolumns=MAGNITUDE \
-  --metaupdate=MAGNITUDE,MAG-F160W,log,"Magnitude in F160W" \
-  --metaupdate=MAGNITUDE-1,MAG-F105W,log,"Magnitude in F105W"
+  --colmetadata=MAGNITUDE,MAG-F160W,log,"Magnitude in F160W" \
+  --colmetadata=MAGNITUDE-1,MAG-F105W,log,"Magnitude in F105W"
 @end example
 
 @item -u STR/INT
@@ -9661,7 +9661,7 @@ Only print the given number of rows from the 
@emph{bottom} of the final table.
 See @option{--head} for more.
 
 @item -m STR/INT,STR[,STR[,STR]]
-@itemx --metaupdate=STR/INT,STR[,STR[,STR]]
+@itemx --colmetadata=STR/INT,STR[,STR[,STR]]
 Update a column's metadata just before writing the final table (after all 
other operations are done, for example column arithmetic, or column 
concatenation).
 The first value (before the first comma) given to this option can either be a 
counter (positive integer, counting from 1), or a name (the column's name in 
the output if this option wasn't called).
 This option can be very useful in conjunction with column arithmetic (see 
@ref{Column arithmetic}), or column concatenation (appending multiple columns 
from different tables, for more see @option{--catcolumnfile}).
@@ -9674,13 +9674,13 @@ Here are three examples
 
 @table @option
 
-@item --metaupdate=MAGNITUDE,MAG_F160W
+@item --colmetadata=MAGNITUDE,MAG_F160W
 This will convert name of the original @code{MAGNITUDE} column to 
@code{MAG_F160W}, leaving the unit and comments unchanged.
 
-@item --metaupdate=3,MAG_F160W,mag
+@item --colmetadata=3,MAG_F160W,mag
 This will convert name of the third column of the final output to 
@code{MAG_F160W} and the units to @code{mag}, while leaving the comments 
untouched.
 
-@item --metaupdate=MAGNITUDE,MAG_F160W,mag,"Magnitude in F160W filter"
+@item --colmetadata=MAGNITUDE,MAG_F160W,mag,"Magnitude in F160W filter"
 This will convert name of the original @code{MAGNITUDE} column to 
@code{MAG_F160W}, and the units to @code{mag} and the comments to 
@code{Magnitude in F160W filter}.
 Note the double quotations around the comment string, they are necessary to 
preserve the white-space characters within the column comment from the 
command-line, into the program (otherwise, upon reaching a white-space 
character, the shell will consider this option to be finished and cause 
un-expected behavior).
 @end table
@@ -9690,7 +9690,7 @@ Look into that file's metadata (with @command{asttable 
temp.fits -i}) to see the
 Recall that when a name is given, this option will update the metadata of the 
first column that matches, so if you have multiple columns with the same name, 
you can call this options multiple times with the same first argument to change 
them all.
 
 Finally, if you already have a FITS table by other means (for example by 
downloading) and you merely want to update the column metadata and leave the 
data intact, it is much more efficient to directly modify the respective FITS 
header keywords with @code{astfits}, using the keyword manipulation features 
described in @ref{Keyword manipulation}.
-@option{--metaupdate} is mainly intended for scenarios where you want to edit 
the data so it will always load the full/partial dataset into memory, then 
write out the resulting datasets with updated/correced metadata.
+@option{--colmetadata} is mainly intended for scenarios where you want to edit 
the data so it will always load the full/partial dataset into memory, then 
write out the resulting datasets with updated/correced metadata.
 @end table