diff --git a/pyglance/glance/compare.py b/pyglance/glance/compare.py
index 86868fc2e611d14ee700e2df75baffbf8adab82b..3335c81e32b705b676cf28b65d4e01e6c58ef803 100644
--- a/pyglance/glance/compare.py
+++ b/pyglance/glance/compare.py
@@ -1173,17 +1173,39 @@ def inspect_stats_library_call (afn, var_list=[ ], options_set={ }, do_document=
def main():
import optparse
usage = """
-%prog [options]
+%prog [options]
+or
+%prog <command> [options]
+
run "%prog help" to list commands
-examples:
+run "%prog help <command>" for details on calling a command
+
+Most commands that load data for analysis allow you to specify variable names to be analyzed.
+If you want to specify an epsilon and missing value you can do so using the syntax:
+
+ varname:epsilon:missing
+
+If you would rather use the default epsilon or missing value, simply omit those values or
+omit the :: entirely. If you do not specify a missing value, but the variable has a
+'_FillValue' attribute Glance will load that attribute and use it as the missing value.
+
+ varname:epsilon:
+ varname::missing
+ varname::
+ varname
+
+Variable names may be specified as python regular expressions. This means you can use .*
+to represent "whatever other text is there" or $ to represent the end of the variable.
+
+ image.*
+ .*prof_retr.*::-999
+ HT$
-glance info A.hdf
-glance stats A.hdf B.hdf '.*_prof_retr_.*:1e-4' 'nwp_._index:0'
-glance plotDiffs A.hdf B.hdf
-glance reportGen A.hdf B.hdf
-glance gui
-glance inspectStats A.hdf
+If your variable name or regular expression has a space in it, put the name inside
+single quotes.
+ 'Cloud Mask'
+ 'Aerosol COD$'
"""
# set the options available to the user on the command line
@@ -1218,7 +1240,12 @@ glance inspectStats A.hdf
def info(*args):
"""list information about a list of files
- List available variables for comparison.
+ Given a file (or list of files), print out the names of the available variables in the file(s).
+
+ Examples:
+
+ glance info A.hdf
+ glance info B.h5 C.nc
"""
problems = 0
for fn in args:
@@ -1238,18 +1265,17 @@ glance inspectStats A.hdf
return problems
def stats(*args):
- """create statistics summary of variables
- Summarize difference statistics between listed variables.
- If no variable names are given, summarize all common variables.
- Variable names can be of the form varname:epsilon:missing to use non-default epsilon or missing value.
- Variable names can be regular expressions, e.g. 'image.*' or '.*prof_retr.*::-999'
- Either epsilon or missing can be empty to stay with default.
- If _FillValue is an attribute of a variable, that will be used to find missing values where no value is given.
- Run with -v to get more detailed information on statistics.
+ """summarize the statistical differences between two files
+ Print statistical summaries of the difference between the variables in two files. If no variable names are
+ given, this command will summarize all variables that can be matched by name and shape between the two files.
+
+ Run with -v to get more detailed information about the statistics being reported.
+
Examples:
- glance stats hdffile1 hdffile2
- glance stats --epsilon=0.00001 A.hdf B.hdf baseline_cmask_seviri_cloud_mask:0.002:
- glance -w stats --epsilon=0.00001 A.hdf A.hdf imager_prof_retr_abi_total_precipitable_water_low::-999
+
+ glance stats A.hdf B.hdf
+ glance stats --epsilon=0.00001 C.nc B.hdf baseline_cmask_seviri_cloud_mask:0.002:
+ glance -w stats A.hdf D.h5 imager_prof_retr_abi_.*::-999 'nwp__.__index:0:'
"""
if len(args) < 2:
LOG.warn("Expected two paths to files to compare. "
@@ -1288,27 +1314,29 @@ glance inspectStats A.hdf
return status_result
def plotDiffs(*args) :
- """generate a set of images comparing two files
- This option creates a set of graphical comparisons of variables in the two given hdf files.
- The images detailing the differences between variables in the two hdf files will be
- generated and saved to disk.
- Variables to be compared may be specified after the names of the two input files. If no variables
- are specified, all variables that match the shape of the longitude and latitude will be compared.
- Specified variables that do not exist, do not match the correct data shape, or are the longitude/latitude
- variables will be ignored.
- The user may also use the notation variable_name:epsilon:missing_value to specify the acceptible epsilon
- for comparison and the missing_value which indicates missing data. If one or both of these values is absent
- (in the case of variable_name:epsilon: variable_name::missing_value or just variable_name) the default value
- of 0.0 will be used for epsilon and no missing values will be analyzed.
- The created images will be stored in the provided path, or if no path is provided, they will be stored in
- the current directory.
- The longitude and latitude variables may be specified with --longitude and --latitude
- If no longitude or latitude are specified the pixel_latitude and pixel_longitude variables will be used.
+ """create a set of images comparing two files
+ Create and save images comparing variables in two files. Variables to be compared may be specified after
+ the names of the two input files. If no variable names are given, this command will create plots for all
+ variables that can be matched by name and shape between the two files.
+
+ If latitude and longitude data are present in the file and specified in the call options, the variables
+ will be plotted on a map. The longitude and latitude variable names may be specified with --longitude
+ and --latitude command line options. If no longitude or latitude names are specified Glance will attempt
+ to use pixel_longitude and pixel_latitude.
+
+ If you would rather plot the data without a map, use the --nolonlat option.
+
+ The created images will be saved at the provided output path in subdirectories named for each variable
+ analyzed. If no output path is provided, output will be saved in the current directory.
+
Examples:
- glance plotDiffs A.hdf B.hdf variable_name_1:epsilon1: variable_name_2 variable_name_3:epsilon3:missing3 variable_name_4::missing4
+
+ glance plotDiffs A.hdf B.hdf
+ glance plotDiffs C.nc D.h5 variable_name_1:epsilon1: variable_name_2 variable_name_3:epsilon3:missing3
glance --outputpath=/path/where/output/will/be/placed/ plotDiffs A.hdf B.hdf
glance plotDiffs --longitude=lon_variable_name --latitude=lat_variable_name A.hdf B.hdf variable_name
"""
+
# set the options so that a report will not be generated
options.imagesOnly = True
@@ -1318,29 +1346,32 @@ glance inspectStats A.hdf
return
def reportGen(*args) :
- """generate a report comparing two files
- This option creates a report comparing variables in the two given hdf files.
- An html report and images detailing the differences between variables in the two hdf files will be
- generated and saved to disk. The images will be embedded in the report or visible as separate .png files.
- Variables to be compared may be specified after the names of the two input files. If no variables
- are specified, all variables that match the shape of the longitude and latitude will be compared.
- Specified variables that do not exist, do not match the correct data shape, or are the longitude/latitude
- variables will be ignored.
- The user may also use the notation variable_name:epsilon:missing_value to specify the acceptible epsilon
- for comparison and the missing_value which indicates missing data. If one or both of these values is absent
- (in the case of variable_name:epsilon: variable_name::missing_value or just variable_name) the default value
- of 0.0 will be used for epsilon and no missing values will be analyzed.
- The html report page(s) and any created images will be stored in the provided path, or if no path is provided,
- they will be stored in the current directory.
- If for some reason you would prefer to generate the report without images, use the --reportonly option. This
- option will generate the html report but omit the images. This may be significantly faster, depending on
- your system, but the differences between the files may be quite a bit more difficult to interpret.
- The longitude and latitude variables may be specified with --longitude and --latitude
- If no longitude or latitude are specified the pixel_latitude and pixel_longitude variables will be used.
+ """create a report comparing two files
+ Generate an html report comparing the variables in two files. Variables to be compared may be specified after
+ the names of the two input files. If no variable names are given, this command will create reports for all
+ variables that can be matched by name and shape between the two files.
+
+ If latitude and longitude data are present in the file and specified in the call options, the variable
+ comparison plots will be drawn on a map. The longitude and latitude variable names may be specified with
+ --longitude and --latitude command line options. If no longitude or latitude names are specified Glance
+ will attempt to use pixel_longitude and pixel_latitude.
+
+ If you would rather analyze the data without trying to place it on a map, use the --nolonlat option.
+
+ The created reports and images will be saved at the provided output path in subdirectories named for
+ each variable analyzed. If no output path is provided, output will be saved in the current directory.
+ Created images will be embedded in the report or visible as separate .png files.
+
+ If you would prefer to generate the report without images, use the --reportonly option. This option will
+ generate the html report but omit the images. This may be significantly faster, depending on your system,
+ but the differences between the files may be more difficult to interpret.
+
Examples:
+
+ glance reportGen A.hdf C.nc
glance reportGen A.hdf B.hdf variable_name_1:epsilon1: variable_name_2 variable_name_3:epsilon3:missing3 variable_name_4::missing4
- glance --outputpath=/path/where/output/will/be/placed/ reportGen A.hdf B.hdf
- glance reportGen --longitude=lon_variable_name --latitude=lat_variable_name A.hdf B.hdf variable_name
+ glance --outputpath=/path/where/output/will/be/placed/ reportGen A.hdf D.h5
+ glance reportGen --longitude=lon_variable_name --latitude=lat_variable_name D.h5 C.nc variable_name
glance reportGen --imagesonly A.hdf B.hdf
"""
@@ -1357,18 +1388,17 @@ glance inspectStats A.hdf
return reportGen_library_call(a_path, b_path, args[2:], tempOptions)
def inspectStats(*args):
- """create statistics summary of variables from one file
- Summarize data on variables in a file.
- If no variable names are given, summarize all variables.
- Variable names can be of the form varname::missing to use non-default missing value.
- Variable names can be regular expressions, e.g. 'image.*' or '.*prof_retr.*::-999'
- Missing can be empty to stay with default.
- If _FillValue is an attribute of a variable, that will be used to find missing values where no value is given.
- Run with -v to get more detailed information on the statistics provided.
+ """create statistics summary of one file
+ Print statistical summaries of the variables in a file. If no variable names are given, this
+ command will summarize all variables found in the file.
+
+ Run with -v to get more detailed information about the statistics being reported.
+
Examples:
+
glance inspectStats A.hdf
glance inspectStats A.hdf baseline_cmask_seviri_cloud_mask
- glance -w inspectStats A.hdf imager_prof_retr_abi_total_precipitable_water_low::-999
+ glance -w inspectStats B.nc imager_prof_retr_abi_total_precipitable_water_low::-999
"""
if len(args) < 1:
@@ -1403,35 +1433,32 @@ glance inspectStats A.hdf
fileForOutput.close()
def inspectReport(*args) :
- """inspect the contents of a file
- This option creates a report and or images examining variables in a file.
-
- An html report and images detailing the variables in the file will be generated and saved to disk.
- The images will be embedded in the report or visible as separate .png files.
-
- Variables to be compared may be specified after the name of the input file. If no variables
- are specified, all variables that match the shape of the longitude and latitude will be compared.
- Specified variables that do not exist or do not match the lon/lat data shape will be ignored.
-
- The user may also use the notation variable_name::missing_value to specify the missing_value which indicates
- fill data. If this value is absent (in the case of variable_name:: or just variable_name) glance with attempt
- to load the missing value from the file (if none is found, the inspection may fail).
-
- The html report and any created images will be stored in the provided path, or if no path is provided,
- they will be stored in the current directory.
-
- If for some reason you would prefer to generate the report without images, use the --reportonly option. This
- option will generate the html report but omit the images. This may be significantly faster, depending on
- your system, however the information may be more difficult to interpret.
-
- The longitude and latitude variables may be specified with --longitude and --latitude
- If no longitude or latitude are specified the pixel_latitude and pixel_longitude variables will be used by default.
- If no longitude or latitude mappings are desired, the --nolonlat option will disable spatial mapping.
-
+ """create a report to inspect the contents of one file
+
+ Generate an html report examining the variables in a file. Variables to be analyzed may be specified after
+ the name of the input file. If no variable names are given, this command will create reports for all
+ variables in the file.
+
+ If latitude and longitude data are present in the file and specified in the call options, the variable
+ plots will be drawn on a map. The longitude and latitude variable names may be specified with
+ --longitude and --latitude command line options. If no longitude or latitude names are specified Glance
+ will attempt to use pixel_longitude and pixel_latitude.
+
+ If you would rather analyze the data without trying to place it on a map, use the --nolonlat option.
+
+ The created reports and images will be saved at the provided output path in subdirectories named for
+ each variable analyzed. If no output path is provided, output will be saved in the current directory.
+ Created images will be embedded in the report or visible as separate .png files.
+
+ If you would prefer to generate the report without images, use the --reportonly option. This option will
+ generate the html report but omit the images. This may be significantly faster, depending on your system,
+ but the results may be more difficult to interpret.
+
Examples:
+
glance inspect_report A.hdf variable_name_1:: variable_name_2 variable_name_3::missing3 variable_name_4::missing4
- glance --outputpath=/path/where/output/will/be/placed/ inspect_report A.hdf
- glance inspect_report --longitude=lon_variable_name --latitude=lat_variable_name A.hdf variable_name
+ glance --outputpath=/path/where/output/will/be/placed/ inspect_report C.nc
+ glance inspect_report --longitude=lon_variable_name --latitude=lat_variable_name D.h5 variable_name
glance inspect_report --reportonly A.hdf
"""
@@ -1446,9 +1473,10 @@ glance inspectStats A.hdf
return inspect_library_call(clean_path(args[0]), args[1:], tempOptions)
def colocateData(*args) :
- """colocate data in two files
+ """colocate data from two files
- This option colocates data in the two given input files and saves it to separate output files.
+ Colocates data in the two given input files and saves it to separate output files.
+
Data will be colocated based on its corresponding longitude and latitude. Multiple matches may be
made between a data point in file A and those in file B if they are within the longitude/latitude epsilon.
Points from each file that could not be matched and the number of duplicate matches will also be
@@ -1472,6 +1500,7 @@ glance inspectStats A.hdf
(replacing "originalFileName" with the names of your input files).
Examples:
+
glance colocateData A.hdf B.hdf variable_name_1 variable_name_2 variable_name_3::missing3
glance colocateData --outputpath=/path/where/output/will/be/placed/ A.nc B.nc
glance colocateData --longitude=lon_variable_name --latitude=lat_variable_name A.hdf B.hdf variable_name
@@ -1502,18 +1531,21 @@ glance inspectStats A.hdf
# statement at the beginning of this module. (It had to be moved into this module to pre-empt other use statempents
# from imports of other glance modules.)
def gui (*args) :
- """start the glance graphical user interface
+ """start the Glance graphical user interface
- This option launches the graphical user interface for glance. This interface includes only some of the basic
- functionality of glance and may be expanded in the future.
+ This option launches the graphical user interface for Glance. This interface includes only some of the
+ functionality of the command line version of Glance and may be expanded in the future.
- Files to be loaded as File A and File B may be specified on the command line.
- The various output related arguments (quiet, verbose, debug, etc.) may be used if desired.
+ Files to be loaded may be specified on the command line or loaded inside the GUI.
+
+ The various logging related arguments (quiet, verbose, debug, etc.) may be used if desired.
Examples:
+
glance gui
- glance gui A.nc
- glance gui A.nc B.hdf
+ glance gui -w
+ glance gui A.hdf
+ glance gui A.hdf C.nc
"""
LOG.debug("Launching Glance GUI")
@@ -1527,23 +1559,32 @@ glance inspectStats A.hdf
def help(command=None):
"""print help for a specific command or list of commands
e.g. help stats
- """ # TODO, need to double check that this still works with the lowercase names?
+ """
print_all_summary = False
+
+ # check to see if the user specified a command to get info on
if command is None:
print_all_summary = True
+
+ # if the user did specify a command, just print that one
else:
if (command.lower() in lower_locals):
- print lower_locals[command.lower()].__doc__
+ split_doc = lower_locals[command.lower()].__doc__.split('\n')
+ print
+ for line in split_doc[1:] :
+ print line
else :
print_all_summary = True
# print out a list of summaries for each command
if print_all_summary :
+ print ("\nAvailable commands in Glance:")
+
# print first line of docstring
for cmd in commands:
ds = commands[cmd].__doc__.split('\n')[0]
- print "%-16s %s" % (cmd,ds)
+ print "\t%-16s %s" % (cmd,ds)
# all the local public functions are considered part of glance, collect them up
commands.update(dict(x for x in locals().items() if x[0] not in prior))
diff --git a/pyglance/glance/config_organizer.py b/pyglance/glance/config_organizer.py
index bace8de23d460bfd8b10077f3dcf618d75e96bea..8c927253611d963d277913d19bfe5c0714f8bd73 100644
--- a/pyglance/glance/config_organizer.py
+++ b/pyglance/glance/config_organizer.py
@@ -433,19 +433,19 @@ def set_up_command_line_options (parser) :
# message related options
parser.add_option('-q', '--quiet', dest="quiet",
- action="store_true", default=False, help="only error output")
+ action="store_true", default=False, help="only log error output")
parser.add_option('-v', '--verbose', dest="verbose",
- action="store_true", default=False, help="enable more informational output")
+ action="store_true", default=False, help="enable logging of more detailed informational output")
parser.add_option('-w', '--debug', dest="debug",
- action="store_true", default=False, help="enable debug output")
+ action="store_true", default=False, help="enable logging of debug output (warning: this will generate far more messages)")
parser.add_option('-n', '--version', dest='version',
- action="store_true", default=False, help="view the glance version")
+ action="store_true", default=False, help="print the Glance version")
# data options for setting variable defaults
parser.add_option('-e', '--epsilon', dest=EPSILON_KEY, type='float', default=0.0,
help="set default epsilon value for comparison threshold")
parser.add_option('-m', '--missing', dest=OPTIONS_FILL_VALUE_KEY, type='float', default=None,
- help="set default missing-value")
+ help="set default missing-data value")
# longitude and latitude related options
parser.add_option('-o', '--longitude', dest=OPTIONS_LON_VAR_NAME_KEY, type='string',
@@ -459,26 +459,26 @@ def set_up_command_line_options (parser) :
# output generation related options
parser.add_option('-p', '--outputpath', dest=OPTIONS_OUTPUT_PATH_KEY, type='string', default='./',
- help="set path to output directory")
+ help="set path to the output directory")
parser.add_option('-i', '--imagesonly', dest=OPTIONS_NO_REPORT_KEY,
action="store_true", default=False,
- help="generate only image files (no html report)")
+ help="generate only the images (no html report)")
parser.add_option('-r', '--reportonly', dest=OPTIONS_NO_IMAGES_KEY,
action="store_true", default=False,
- help="generate only html report files (no images)")
+ help="generate only the html report (no images)")
parser.add_option('-c', '--configfile', dest=OPTIONS_CONFIG_FILE_KEY, type='string', default=None,
- help="set optional configuration file")
+ help="set a configuration file to load (optional)")
# should pass/fail be tested?
parser.add_option('-x', '--doPassFail', dest=DO_TEST_PASSFAIL_KEY,
- action="store_true", default=False, help="should the comparison test for pass/fail (currently only affects stats)")
+ action="store_true", default=False, help="test for pass/fail while comparing data (only affects analysis where data is compared)")
# whether or not to do multiprocessing
parser.add_option('-f', '--fork', dest=DO_MAKE_FORKS_KEY,
action="store_true", default=False, help="start multiple processes to create images in parallel")
parser.add_option('--parsable', dest=PARSABLE_OUTPUT_KEY,
- action="store_true", default=False, help="format output to be programmatically parsed. 'info' only")
+ action="store_true", default=False, help="format output to be programmatically parsed. (only affects 'info')")
def convert_options_to_dict (options) :
"""