cf_reader improve algorithm property documentation

io/teca_cf_reader.cxx

@@ -82,35 +82,56 @@ void teca_cf_reader::get_properties_description(
 
     opts.add_options()
         TECA_POPTS_GET(std::vector<std::string>, prefix, file_names,
-            "paths/file names to read")
+            "An explcict list of files to read. If specified takes precedence"
+            " over --files_regex. Use one of --files_regex or --file_names")
         TECA_POPTS_GET(std::string, prefix, files_regex,
-            "a regular expression that matches the set of files "
-            "comprising the dataset")
+            "A POSIX basic regular expression that matches the set of files to process."
+            " Only the final component in a path may conatin a regular expression."
+            " Use one of --files_regex or --file_names ")
         TECA_POPTS_GET(std::string, prefix, x_axis_variable,
             "name of variable that has x axis coordinates (lon)")
         TECA_POPTS_GET(std::string, prefix, y_axis_variable,
             "name of variable that has y axis coordinates (lat)")
         TECA_POPTS_GET(std::string, prefix, z_axis_variable,
-            "name of variable that has z axis coordinates ()")
+            "name of variable that has z axis coordinates (). If left empty the"
+            " output mesh will be 2D.")
         TECA_POPTS_GET(std::string, prefix, t_axis_variable,
-            "name of variable that has t axis coordinates (time)")
+            "name of variable that has time axis coordinates (time). Set to an empty"
+            " string to enable override methods (--filename_time_template, --t_values)"
+            " or to disable time coordinates completely")
         TECA_POPTS_GET(std::string, prefix, t_calendar,
-            "name of variable that has the time calendar (calendar)")
+            "An optional calendar override. May be one of: standard, Julian,"
+            " proplectic_Julian, Gregorian, proplectic_Gregorian, Gregorian_Y0,"
+            " proplectic_Gregorian_Y0, noleap, no_leap, 365_day, 360_day. When the"
+            " override is provided it takes precedence over the value found in the"
+            " file. Otherwise the calendar is expected to be encoded in the data"
+            " files using CF2 conventions.")
         TECA_POPTS_GET(std::string, prefix, t_units,
-            "a std::get_time template for decoding time from the input filename")
+            "An optional CF2 time units specification override declaring the"
+            " units of the time axis and a reference date and time from which the"
+            " time values are relative to. If this is provided it takes precedence"
+            " over the value found in the file. Otherwise the time units are"
+            " expected to be encouded in the files using the CF2 conventions")
         TECA_POPTS_GET(std::string, prefix, filename_time_template,
-            "name of variable that has the time unit (units)")
+            "An optional std::get_time template string for decoding time from the input"
+            " file names. If no calendar is specified the standard calendar is used. If"
+            " no units are specified then \"days since %Y-%m-%d 00:00:00\" where Y,m,d"
+            " are determined from the filename of the first file. Set t_axis_variable to"
+            " an empty string to use.")
         TECA_POPTS_GET(std::vector<double>, prefix, t_values,
-            "name of variable that has t axis values set by the"
-            "the user if the file doesn't have time variable set ()")
+            "An optional explicit list of double precision values to use as the"
+            " time axis. If provided these take precedence over the values found"
+            " in the files. Otherwise the variable pointed to by the t_axis_variable"
+            " provides the time values. Set t_axis_variable to an empty string"
+            " to use.")
         TECA_POPTS_GET(int, prefix, periodic_in_x,
-            "the dataset has apriodic boundary in the x direction (0)")
+            "the dataset has a periodic boundary in the x direction (0)")
         TECA_POPTS_GET(int, prefix, periodic_in_y,
-            "the dataset has apriodic boundary in the y direction (0)")
+            "the dataset has a periodic boundary in the y direction (0)")
         TECA_POPTS_GET(int, prefix, periodic_in_z,
-            "the dataset has apriodic boundary in the z direction (0)")
+            "the dataset has a periodic boundary in the z direction (0)")
         TECA_POPTS_GET(int, prefix, max_metadata_ranks,
-            "set the max number of ranks for reading metadata (1024)")
+            "set the max number of MPI ranks for reading metadata (1024)")
         ;
 
     global_opts.add(opts);
@@ -819,8 +840,8 @@ teca_metadata teca_cf_reader::get_output_metadata(
 
             TECA_STATUS("The time axis will be infered from file names using "
                 "the user provided template \"" << this->filename_time_template
-                << "\" with the \"" << t_calendar << "\" in units \"" << t_units
-                << "\"")
+                << "\" with the \"" << t_calendar << "\" calendar in units \""
+                << t_units << "\"")
 
             // create a teca variant array from the times
             size_t n_t_vals = t_values.size();

io/teca_cf_reader.h

@@ -67,7 +67,8 @@ class teca_cf_reader : public teca_algorithm
 
     // describe the set of files comprising the dataset. This
     // should contain the full path and regex describing the
-    // file name pattern
+    // file name pattern. only the final component of a path
+    // can contain a regex.
     TECA_ALGORITHM_PROPERTY(std::string, files_regex)
 
     // set if the dataset has periodic boundary conditions
@@ -84,14 +85,20 @@ class teca_cf_reader : public teca_algorithm
     TECA_ALGORITHM_PROPERTY(std::string, z_axis_variable)
     TECA_ALGORITHM_PROPERTY(std::string, t_axis_variable)
 
-    // time calendar and time unit if the user wants to
-    // specify them
+    // Override the calendar and time unit. When these are specified
+    // their values take precedence over the values found in the file.
     TECA_ALGORITHM_PROPERTY(std::string, t_calendar)
     TECA_ALGORITHM_PROPERTY(std::string, t_units)
 
     // a way to infer time from the filename if the time axis is not
-    // stored in the file itself. strftime format codes are used.
-    // For example for the files:
+    // stored in the file itself. std::get_time format codes are used.
+    // If a calendar is not specified then the standard calendar is
+    // used. If time units are not specified then the time units will
+    // be "days since %Y-%m-%d 00:00:00" where Y,m, and d are computed
+    // from the filename of the first file. set t_axis_variable to an
+    // empty string to use.
+    //
+    // For example, for the list of files:
     //
     //      my_file_20170516_00.nc
     //      my_file_20170516_03.nc
@@ -102,8 +109,8 @@ class teca_cf_reader : public teca_algorithm
     //      my_file_%Y%m%d_%H.nc
     TECA_ALGORITHM_PROPERTY(std::string, filename_time_template)
 
-    // time values to use instead if time variable doesn't
-    // exist.
+    // an explicit list of double precision time values to use.
+    // set t_axis_variable to an empty string to use.
     TECA_ALGORITHM_VECTOR_PROPERTY(double, t_value)
 
     // set/get the number of ranks used to read the time axis.