TSTool-Vol2-CommandReference - Laserfiche WebLink

quality control checks for other software tools. TSTool internally maintains a working directory that is used to convert relative paths to absolute paths to locate files. The working directory is by default the location of the last command file that was opened. The external program may assume that the working directory is the location from which TSTool software was started (or the installation location if started from a menu). Therefore, it may be necessary to run TSTool in batch mode from the directory where the external software’s data files exist, use absolute paths to files, or use the ${WorkingDir} property in the command line. Use \” in the command line or arguments to surround whitespace. Some operating systems may have limitations on command line length. The following dialog is used to edit the command and illustrates the command syntax. RunProgram RunProgram() Command Editor when Specifying Command Line 411 Command Reference – RunProgram() -1 RunProgram() Command TSTool Documentation The command syntax is as follows: RunProgram(Parameter=Value…) Command Parameters Parameter Description Default CommandLine The full program command line, with arguments. If the program executable is found in the PATH environment variable, then only the program name needs to be specified. Otherwise, specify an absolute path to the program or run TSTool from a command shell the same directory. The ${WorkingDir} property can be used in the command line to indicate the working directory (command file location) when specifying file names. For Windows, it may be necessary to place a \” at the start and end of the command line, if a full command line is specified. Must be specified if the Program parameter is not specified. The Program parameter will be used if both are specified. Program The name of the program to run. Program arguments are specified using the ProgramArg# parameter(s). See the CommandLine parameter for more information about parameter formatting and locating the executable. Must be specified if the CommandLine parameter is not specified. ProgramArg1, ProgramArg2, etc. Command like arguments used with Program. If necessary, use ${WorkingDir} to specify the working directory to locate files. No arguments will be used with Program. UseCommandShell If specified as False, the program will be run without using a command shell. A command shell is needed if the program is a script (batch file), a shell command, or uses >, |, etc. True, using cmd.exe /C on Windows and /bin/sh –c on UNIX/Linux. Timeout The timeout in seconds – if the program has not yet returned, the process will be ended. Zero indicates no timeout. This behavior varies and is being enhanced. No timeout. ExitStatus Indicator By default, the program exit status is determined from the process that is run. Normally 0 means success and non-zero indicates an error. However, the program may not exit with a nonzero exit status when an error occurs. If the program instead uses an output string like STOP 3 to indicate the status, use this parameter to indicate the leading string, which is followed by the exit status (e.g., STOP). Determine the exit status from the process exit value. Command Reference – RunProgram() -2 412 TSTool Documentation RunProgram() Command The following figure illustrates how a command would be entered using the program name and parts, and use the command shell to run. Note that the output redirection character “>” is entered as a program argument. The echo program on Windows is actually internal to the cmd.exe command shell and therefore must be run using the command shell (the default behavior). RunProgram_Program RunProgram() Command Editor when Specifying Program and Arguments 413 Command Reference – RunProgram() -3 RunProgram() Command TSTool Documentation The following figure illustrates how a command can be run without a command shell and using the program output to determine the exit status. The testecho.exe program is a compiled executable and can therefore be run without a command shell. Because the standard output is being evaluated for the exit value, the output cannot be redirected to a file with > (this would result in no output being available to TSTool to evaluate), and > is only recognized if running with a command shell in any case. The following approach is suitable, for example, when running a compiled model or data analysis tool. However, if the tool is run using a script or batch file, then a command shell must be used. RunProgram_Program _ExitStatusIndicator RunProgram() Command Editor when Specifying Program, Arguments, and Exit Status Indicator Command Reference – RunProgram() -4 414 Command Reference – RunPython() -1 Command Reference: RunPython() Run a Python script Version 10.12.00, 2012-07-19 The RunPython() command runs a Python script, waiting until execution is finished before processing additional commands. Python is a powerful scripting language that is widely used (see http://www.python.org). This command allows Python scripts to be run using a variety of Python interpreters, as shown in the following table. It is assumed that Python is installed in the standard directory for the distribution. New versions of Python will reside in similar locations to those shown below. RunPython() Supported Python Interpreters Interpreter (Website) Language, Program Name (Example Install Home) Comments IronPython (ironpython.net) .NET, ipy (C:\Program Files\IronPython 2.6) Useful for integrating with .NET applications, in particular to manipulate Microsoft Office software data files. Can use .NET assembly code (but this code in a Python script is only recognized by IronPython). Integration can occur within a running .NET application (essentially extending the functionality of the .NET application). Version 2.6 requires .NET 2.0. Version 2.6.1 requires .NET 4.0. Jython (www.jython.org) Java, jython (C:\jython2.5.1) Useful for integrating with Java applications, such as TSTool. Can use Java code (but this code in a Python script is only recognized by Jython). Jython embedded (www.jython.org) Java (C:\jython2.5.1, but must use the installer option to create a JAR file in order to embed – this is the file that is distributed with TSTool). Useful for integrating with Java applications, such as TSTool. Can use Java code (but this code in a Python script is only recognized by Jython). Integration can occur within a running Java application (essentially extending the functionality of the Java application). Python (www.python.org) C, python (C:\Python25) The original Python interpreter, which defines the Python language specification. Python implementations have similar file organization, with the main executable (or batch file) residing in the main install folder. Core functionality is typically completely handled within the interpreter code and/or Python code included in the Lib folder under the main installation folder. Extended capabilities such as third-party add-ons are made available as module libraries that are installed in the Lib\sitepackages folder. These folders are typically automatically included in the Python path and will be found when import statements are used in Python scripts. The folder for the main Python script that is run to start an execution is also typically included in the Python path by the interpreter at runtime. If any additional Python modules needed to be found, they can be added to the Python path at runtime (see the PythonPath command parameter below). 415 RunPython() Command TSTool Documentation Command Reference – RunPython() -2 If the embedded Jython is used, then there may be no reliance on any other software if the core Python capabilities can be used. However, if third-party packages are used, it may be best to install them with the Jython distribution (e.g., in Lib\site-packages) so that the packages can be used for independent testing prior to use in the embedded interpreter. For example, perform a typical Jython install (e.g., into C:\Jython2.5.1), install the third-party packages into this location (using the installer for the package or directly copying into the Lib\site-packages folder), and then specify the PythonPath=C:\Jython2.5.1\Lib\site-packages) command parameter. If a non-embedded approach is used, then IronPython, Jython, or Python must be installed on the computer for the appropriate Interpreter command parameter value. The interpreter program will be found if the installation folder is defined in the PATH environment variable, or use the Program command parameter to specify the full path to the interpreter program to run. The script is then run by running the following (see full parameter descriptions below): Program InputFile Arguments The following dialog is used to edit the command and illustrates the command syntax. RunPython RunPython() Command Editor 416 TSTool Documentation RunPython() Command Command Reference – RunPython() -3 The command syntax is as follows: RunPython(Parameter=Value,…) Command Parameters Parameter Description Default Interpreter The Python interpreter to run, one of: • IronPython • Jython • JythonEmbedded • Python Global properties can be used with the ${Property} syntax. None – must be specified. Program The Python interpreter program to run. Specify as a full path to the installed program, or only the program name (in which case the path to the program must be included in the PATH environment variable). Global properties can be used with the ${Property} syntax. Determined based on the Interpreter parameter: • IronPython: ipy • Jython: jython • Python: python PythonPath Additional locations for modules, to be added to the Python path. Specify paths separated by ; or :. For embedded Jython, the sys.path is updated prior to running the script. For non-embedded interpreters, the JYTHONPATH environment variable is updated for the interpreter, which results in sys.path being updated. Global properties can be used with the ${Property} syntax. None – the core Python capabilities are available. InputFile The Python script to run, specified as an absolute path or relative to the command file. See the Arguments parameter for information about using properties to specify the location. Global properties can be used with the ${Property} syntax. None – must be specified. Arguments Arguments to pass to the script, such as the names of files to process. Use the ${WorkingDir} property to specify the location of the command file. Use ${InstallDir} for the TSTool install folder. Use \” to surround arguments that include spaces. Separate arguments by a space. Global properties can be used with the ${Property} syntax. None – arguments are optional. The following command example illustrates how to run a Python script. RunPython(InputFile="Data/readwritefile.py", Interpreter="JythonEmbedded",Arguments="${WorkingDir}/Data/readwritefile.txt ${WorkingDir}/Results/Test_Ru nPython_Interpreter=JythonEmbedded_out.txt") 417 RunPython() Command TSTool Documentation Command Reference – RunPython() -4 The corresponding Python script is as follows: ## Test command for running Python script from TSTool # import sys import os print "start of script" print 'os.getcwd()="' + os.getcwd() + '"' infile = None outfile = None if ( len(sys.argv) < 3 ): print "Error. Expecting input file name as first command line argument, output file name as second." sys.exit(1) else:infile = sys.argv[1] outfile = sys.argv[2] print 'Input file to process is "' + infile + '"' print 'Output file to create is "' + outfile + '"' inf=open(infile,'r') outf=open(outfile,'w') for line in inf: outf.write("out: " + line) inf.close() outf.close() print "end of script" The data file is as follows: Line 1 (first line) Line 2 Line 3 Line 4 Line 5 (last line) The output file is as follows: out: Line 1 (first line) out: Line 2 out: Line 3 out: Line 4 out: Line 5 (last line) The following example illustrates the use of double quotes to surround Python script command-line arguments, to ensure that spaces and equal sign characters are properly handled: # Retrieve the MEI (ENSO) index WebGet(URI="http://www.esrl.noaa.gov/psd/data/correlation/mei.data",LocalFile="mei.data") # Convert the MEI data file to a CSV file that can be read by TSTool RunPython(Interpret er="Python",InputFile="mei2csv.py",Arguments="\"InputFile=${WorkingDir}/mei.data\" \"OutputFile=${WorkingDir}/mei.csv\" \"LogFile=${WorkingDir}/mei2csv.log\"") 418 Command Reference – Scale () -1 Command Reference: Scale() Scale time series data values by a constant value Version 10.12.00, 2012-08-13 The Scale() command scales each non-missing value in the specified time series. The value to use for scaling can be specified as a constant, monthly values, or special values that indicate to scale by the number of days in the month. The following dialog is used to edit the command and illustrates the command syntax. Scale Scale() Command Editor The command syntax is as follows: Scale(Parameter=Value,…) Command Parameters Parameter Description Default TSList Indicates the list of time series to be processed, one of: • AllMatchingTSID – all time series that match the TSID (single TSID or TSID with wildcards) will be modified. • AllTS – all time series before the command. • EnsembleID – all time series in the ensemble will be modified. • FirstMatchingTSID – the first time series that matches the TSID (single TSID or TSID with wildcards) will be AllTS 419 Scale() Command TSTool Documentation Command Reference – Scale () -2 Parameter Description Default modified. • LastMatchingTSID – the last time series that matches the TSID (single TSID or TSID with wildcards) will be modified. • SelectedTS – the time series are those selected with the SelectTimeSeries() command. TSID The time series identifier or alias for the time series to be modified, using the * wildcard character to match multiple time series. Required if TSList=*TSID EnsembleID The ensemble to be modified, if processing an ensemble. Required if TSList=EnsembleID ScaleValue One of the following: • The numerical value to scale to the time series. • DaysInMonth to indicate a scale of the number of days in the month. • DaysInMonthInverse to indicate a scale of the inverse of the number of days in the month. None – must be specified. MonthValues Monthly scale values, the fist being for January. Use ScaleValue. AnalysisStart The date/time to start analyzing data. Full period is analyzed. AnalysisEnd The date/time to end analyzing data. Full period is analyzed. NewUnits New data units for the resulting time series. Do not change the units. The following example scales a precipitation time series from the State of Colorado’s HydroBase by a factor of 3.5: # 1458 -CENTER 4 SSW 1458.NOAA.Precip.Month~HydroB ase Scale(TSList=AllMatchingTSID,TSID="1458.NOAA.Precip.Month",ScaleValue=3.5) The following example scales a monthly streamflow time series with units of ACFT (volume per month) in order to convert the data to average CFS flow values (note that two scale commands are required because the DaysInMonthInverse value cannot currently be combined with a numerical value in one command). See also the ConvertDataUnits() command for simple units conversions. # 06754000 -SOUTH PLATTE RIVER NEAR KERSEY 06754000.DWR.Streamflow.Month~HydroBase Scale(TSList=AllMatchingTSID, TSID="06754000.DWR.Streamflow.Month", ScaleValue=.5042) Scale(TSList=AllMatchingTSID,TSID="06754000.DWR.Streamflow.Month", ScaleValue=DaysInMonthInverse,NewUnits="CFS") 06754000.DWR.Streamflow.Month~ HydroBase 420 Command Reference – SelectTimeSeries() -1 Command Reference: SelectTimeSeries() Select time series for additional processing Version 10.12.00, 2012-10-25 The SelectTimeSeries() command selects output time series, as if done interactively, to indicate which time series should be operated on by following commands. The command minimizes the need for the Free() command, when used in conjunction with other commands that use a time series list based on selected time series (TSList=SelectedTS). See also the DeselectTimeSeries() command. The following dialog is used to edit the command and illustrates the command syntax. SelectTimeSeries SelectTimeSeries() Command Editor The command syntax is as follows: SelectTimeSeries(Parameter=Value,…) 421 SelectTimeSeries() Command TSTool Documentation Command Reference – SelectTimeSeries() -2 Command Parameters Parameter Description Default TSList Indicates the list of time series to be processed, one of: • AllMatchingTSID – all time series that match the TSID (single TSID or TSID with wildcards) will be modified. • AllTS – all time series before the command. • EnsembleID – all time series in the ensemble will be modified (see the EnsembleID parameter). • LastMatchingTSID – the last time series that matches the TSID (single TSID or TSID with wildcards) will be modified. • TSPosition – time series specified by position in the results list (see TSPosition parameter below). AllTS TSID The time series identifier or alias for the time series to be modified, using the * wildcard character to match multiple time series. Required if TSList=*TSID EnsembleID The ensemble to be modified, if processing an ensemble. Required if TSList=EnsembleID TSPosition A list of time series positions (1+) in output, separated by commas. Ranges can be specified as Start-End. Required if TSList=TSPosition DeselectAllFirst Indicates whether all time series should be deselected before selecting the specified time series: True or False. False PropertyName Name of user-defined property to check. PropertyCriterion Criterion to evaluate to determine which properties match. Required if PropertyName is specified. PropertyValue Value to check against the property value, using criterion. Required if PropertyName is specified. A sample command file is as follows: NewPatternTimeSeries(Alias="401234",NewTSID="401234..Precip.Day", Description="Example data",SetStart="2000-01-01",SetEnd="2000-12-31", Units="IN",PatternValues="0,1,3,0,0,0") SelectTimeSeries(TSList=AllMatchingTSID,TSID="40*",DeselectAllFirst=True) 422 Command Reference: SetAutoExtendPeriod() Set whether time series periods should automatically be extended to the output period Version 08.16.03, 2008-07-29 By default, the time series period is extended to include the output period, if specified, when a time series is read. See also the SetOutputPeriod() command. If the extended period subsequently contains missing data, it can be filled with other commands. The SetAutoExtendPeriod() command can be used to change this setting if it is not desirable (e.g., for performance reasons). The following dialog is used to edit the command and illustrates the command syntax. SetAutoExtendPeriod SetAutoExtendPeriod() Command Editor The command syntax is as follows: SetAutoExtendPeriod(Parameter=Value,… ) Command Parameters Parameter Description Default AutoExtendPeriod Indicate whether the period of time series should automatically be extended to the output period when time series are read, True or False. None – must be specified. The default is True if this command is not used. A sample command file is as follows: SetAutoExtendPeriod(AutoExtendPeriod=False) 423 Command Reference – SetAutoExtendPeriod() -1 SetAutoExtendPeriod() Command TSTool Documentation This page is intentionally blank. Command Reference – SetAutoExtendPeriod() -2 424 Command Reference: SetAveragePeriod() Set the period used to compute historical averages Version 08.16.03, 2008-07-29 The SetAveragePeriod() command sets the period that is used to compute historic averages used with the FillHistMonthAverage() and FillHistYearAverage() commands. If the averaging period is not specified, the available period is used. Use a SetAveragePeriod() command if a subset of the data should be used to compute averages. The following dialog is used to edit this command and illustrates the command syntax. SetAveragePeriod SetAveragePeriod() Command Editor 425 Command Reference – SetAveragePeriod() -1 SetAveragePeriod() Command TSTool Documentation The command syntax is as follows: SetAveragePeriod(Parameter=Value,…) Command Parameters Parameter Description Default AverageStart The date for the start of the averaging period. The precision of the date should agree with that of time series to be processed, and is limited to monthly and yearly precision. None – must be specified. AverageEnd The date for the end of the averaging period. The precision of the date should agree with that of time series to be processed, and is limited to monthly and yearly precision. None – must be specified. A sample command file is as follows: SetAveragePeriod(1950-01,2002-12) Command Reference – SetAveragePeriod() -2 426 Command Reference: SetConstant() Set time series data to a single or monthly constant values Version 08.15.00, 2008-05-11 The SetConstant() command sets the values of a time series to a single or monthly constant values. The following dialog is used to edit the command and illustrates the command syntax: SetConstant SetConstant() Command Editor 427 Command Reference – SetConstant() -1 SetConstant() Command TSTool Documentation The command syntax is as follows: SetConstant(Parameter=Value,…) Command Parameters Parameter Description Default TSList Indicates the list of time series to be processed, one of: • AllMatchingTSID – all time series that match the TSID (single TSID or TSID with wildcards) will be modified. • AllTS – all time series before the command. • EnsembleID – all time series in the ensemble will be modified. • LastMatchingTSID – the last time series that matches the TSID (single TSID or TSID with wildcards) will be modified. • SelectedTS – the time series are those selected with the SelectTimeSeries() command. AllTS TSID The time series identifier or alias for the time series to be modified, using the * wildcard character to match multiple time series. Required if TSList=*TSID. EnsembleID The ensemble to be modified, if processing an ensemble. Required if TSList=EnsembleID. ConstantValue The constant value to use as the data value. None – must be specified, or specify monthly values. MonthValues Monthly values to use as the data values. Twelve values can be specified, separated by commas. If the time series data interval is less than monthly, each date/time will be set for a specific month. None – must be specified, or specify a constant value. SetStart The starting date/time for the data set. Set data for the full period. SetEnd The ending date/time for the data set. Set data for the full period. A sample command file to process a time series from the State of Colorado’s HydroBase is as follows (only the early period is set to zero): # 08235700 -ALAMOSA RIVER BELOW CASTLEMAN GULCH NEAR JASPER 08235700.DWR.Streamfl ow.Month~HydroBase SetConstant(TSList=AllMatchingTSID,TSID="08235700.DWR.Streamflow.Month", ConstantValue=0,SetEnd="1950-01") Command Reference – SetConstant() -2 428 Command Reference: SetDataValue() Set a data value at a single date/time Version 08.16.04, 2008-09-12 The SetDataValue() command sets a single data value in a time series. Consequently, it can be used to condition a value for subsequent filling (e.g., with FillRepeat()) or to "hard-code" data that may not be available in files or databases. It is good practice to insert comments when editing data to explain the edits. See also the SetConstant() command. The following dialog is used to edit the command and illustrates the syntax of the command. SetDataValue SetDataValue() Command Editor 429 Command Reference – SetDataValue() -1 SetDataValue() Command TSTool Documentation The command syntax is as follows: SetDataValue(Parameter=Value,…) Command Parameters Parameter Description Default TSList Indicates the list of time series to be processed, one of: • AllMatchingTSID – all time series that match the TSID (single TSID or TSID with wildcards) will be modified. • AllTS – all time series before the command. • EnsembleID – all time series in the ensemble will be modified. • FirstMatchingTSID – the first time series that matches the TSID (single TSID or TSID with wildcards) will be modified. • LastMatchingTSID – the last time series that matches the TSID (single TSID or TSID with wildcards) will be modified. • SelectedTS – the time series are those selected with the SelectTimeSeries() command. AllTS TSID The time series identifier or alias for the time series to be modified, using the * wildcard character to match multiple time series. Required if TSList=*TSID. EnsembleID The ensemble to be modified, if processing an ensemble. Required if TSList=EnsembleID. SetDateTime The date/time at which the data value should be set. Specify the date/time precision according to the time series that is being manipulated. None – must be specified. NewValue The new data value. None – must be specified. A sample command file to process data from the State of Colorado’s HydroBase database is as follows: # 08235700 -ALAMOSA RIVER BELOW CASTLEMAN GULCH NEAR JASPER 08235700.DWR.Streamflow.Month~HydroBase SetDataValue(TSList=AllMatchingTSID,TSID=”08235700.DWR.Streamflow.Month”, SetDateTime=”1950-01”,NewValue=550) Command Reference – SetDataValue() -2 430 Command Reference: SetDebugLevel() Set level for debug messages Version 08.16.00, 2008-07-08 The setDebugLevel() command sets the debug levels for screen and log file diagnostic messages. This command can be used multiple times with different debug level (e.g., to isolate a problem). Currently the debug level applies to all components. In the future logging control may be grouped by component. Levels are not completely consistent but the following guidelines can be followed: 0 = no messages 1 = important messages generated in applications 2 = important messages generated in commands 3+ = messages generated in commands that may explain other problems 10+ = messages in processing code that may still be useful to end users 30+ = low-level messages, for example generated while reading from files or databases The following dialog is used to edit this command and illustrates the command syntax. SetDebugLevel SetDebugLevel() Command Editor 431 Command Reference – SetDebugLevel() -1 SetDebugLevel() Command TSTool Documentation The command syntax is as follows: SetDebugLevel(Parameter=Value,…) Command Parameters Parameter Description Default ScreenLevel The debug level for the screen (0+). Keep previous setting. LogFileLevel The debug level for the log file (0+). Keep previous setting. A sample command file is as follows: SetDebugLevel(ScreenLevel=0,LogFileLe vel=10) . Command Reference – SetDebugLevel() -2 432 Command Reference: SetFromTS() Set time series data using another time series Version 10.00.01, 2011-05-11 The SetFromTS() command sets data in a dependent time series by transferring values from an independent time series. A period can be specified to limit the period that is processed. See also the FillFromTS() command, which will transfer values only when the dependent time series has missing data. Only data values are transferred – time series header information (e.g., data type, alias) will not be modified. If multiple time series or an ensemble is being processed, the number of independent time series must be one or the same number as the time series being filled. The following dialog is used to edit the command and illustrates the command syntax. SetFromTS SetFromTS() Command Editor 433 Command Reference – SetFromTS() -1 SetFromTS() Command TSTool Documentation The command syntax is as follows: SetFromTS(Parameter=Value,…) Command Parameters Parameter Description Default TSList Indicates the list of time series to be processed, one of: • AllMatchingTSID – all time series that match the TSID (single TSID or TSID with wildcards) will be modified. • AllTS – all time series before the command. • EnsembleID – all time series in the ensemble will be modified. • FirstMatchingTSID – the first time series that matches the TSID (single TSID or TSID with wildcards) will be modified. • LastMatchingTSID – the last time series that matches the TSID (single TSID or TSID with wildcards) will be modified. • SelectedTS – the time series are those selected with the SelectTimeSeries() command. AllTS TSID The time series identifier or alias for the time series to be modified, using the * wildcard character to match multiple time series. Required when TSList=*TSID EnsembleID The ensemble to be modified, if processing an ensemble. Required when TSList=EnsembleID. Independent TSList Indicates how to determine the list of independent time series (see the explanation of TSList). AllTS Independent TSID The time series identifier or alias for the independent time series (see the explanation of TSID).