TSTool-Vol2-CommandReference - Laserfiche WebLink

the relativeDiff() command. DivisorTSID – Time series identifier for time series to divide another time series. See the divide() command. ExtremeToAdjust – Indicates whether the maximum or minimum value in a time series should be adjusted. See the adjustExtremes() command. ExtremeValue – The threshold value when adjusting extreme values. See the adjustExtremes() command. FillDirection – Indicate which direction (Foreward or Backward) filling should occur. See the fillProrate() and fillRepeat() commands. FillEnd – A DateTime that indicates the end of a fill process. FillFlag – A character flag used to indicate when time series values are filled. See the fillhistMonthAverage(), fillHistYearAverage(), fillMOVE2(), fillProrate(), and fillRegression() commands. FillNearest – Indicate whether missing data values should be filled with the nearest non-missing value. See the lagK() command. FillStart – A DateTime that indicates the start of fill process. FillUsingCIU – Indicate whether missing data values should be filled using “currently in use” (CIU) data from HydroBase. Additional zeros will be included in data. See the fillUsingDiversionComments() command. FillUsingCIUFlag – A character flag used to indicate when time series values are filled with CIU information (see FillUsingCIU). See the fillUsingDiversionComments() command. FillUsingDivComments – Indicate whether missing data values should be filled using diversion comments from HydroBase. Additional zeros will be included in data. See the readHydroBase() and TS Alias = readHydroBase() commands. Also see the fillUsingDiversionComments() command. 25 Command Glossary -3 Command Glossary TSTool Documentation FillUsingDivCommentsFlag – A character flag used to indicate when time series values are filled. See the readHydroBase(), and TS Alias = readHydroBase() commands. HandleMissingHow – Indicate how to handle missing data values when processing time series. For example, when adding time series, missing values can be ignored or can result in a missing value in the result. See the add(), cumulate(), and subtract() commands. HandleMissingTSHow – Indicate how to handle missing time series during processing. See the createFromList() command. ID – The identifier to match in a file. See the createFromList() command. IDCol – The column number (or name) to be read from a delimited file. See the createFromList() command. IgnoreLEZero – Indicate whether values less than or equal to zero should be ignored when computing historical averages for time series. See the setIgnoreLEZero() command. IncludeMissingTS – Indicate whether missing time series (e.g., from a query or read) should automatically be included using default information. See the setIncludeMissingTS() command. IndependentTSID – Time series identifier for the independent time series being processed. See the fillFromTS(), fillMOVE2(), fillProrate(), fillRegression(), setFromTS(), and setMax() commands. InflowStates – The inflow states (initial states) when routing a flow time series. See the lagK() command. InitialValue – Indicate an initial value needed for computations. See the fillProrate() and newTimeSeries() commands. InputEnd – A DateTime that indicates the end of a file read or a database query. InputFile, InputFile1, InputFile2 – The name of an input file to read, used by many commands. InputName – The input name to use when forming a TSID. See the createFromList() command. InputStart – A DateTime that indicates the start of file read or a database query. InputType – The input type to use when forming a TSID. See the createFromList() command. Intercept – The intercept to be enforced when determining a line of best fit. See the fillRegression() command. Interval – The data interval to use when forming a TSID. See the createFromList(), readHydroBase(), and shiftTimeByInterval() commands. Command Glossary -4 26 TSTool Documentation Command Glossary K – The attenuation factor used when routing a flow time series. See the lagK() command. Lag – The lag term for routing a flow time series. See the lagK() command. Length – The length of a time series trace. See the createTraces() command. ListFile – The name of an input or output list (delimited) file to be written or read, specified using a relative or absolute path. See the createFromList() command. LogFile – The name of the log file, specified using a relative or absolute path. See the setLogFile() command. LogFileLevel – The level for messages printed to the log file. See the setDebugLevel() and setWarningLevel() commands. MatchDataType – Indicate whether the data type part of a TSID should be matched when comparing time series identifiers. See the compareTimeSeries() command. MatchLocation – Indicate whether the location part of a TSID (Alias) should be matched when comparing time series identifiers. See the compareTimeSeries() command. MaxIntervals – The maximum number of intervals to process, typically used to limit a fill or analysis procedure. See the adjustExtremes(), fillInterpolate(), and fillRepeat() commands. MaxValue – The maximum value in an analysis. See the normalize() and replaceValue() commands. Method – A method used when processing data, used to more specifically control how a command functions. See the analyzePattern() and disaggregate() commands. MinValue – The minimum value in an analysis. See the normalize() and replaceValue() commands. MinValueHow – Indicate how to determine the minimum value in an analysis. See the normalize() command. MissingValue – A numerical value used for missing data in time series. See the writeStateMod() command. MonthTSID – Time series identifier for a monthly time series. See the newDayTSFromMonthAndDayTS() command. MonthValues – Monthly values used for filling, etc. See the setConstant() command. MultiplierTSID – Time series identifier for the time series to multiply the main time series. See the multiply() command. 27 Command Glossary -5 Command Glossary TSTool Documentation Multiplier – Value(s) to multiply time series value(s) by when processing. See the shiftTimeByInterval() command. NewDataType – The data type for a new time series, typically used where the data type must be explicitly defined and is not determined from a TSID. See also NewTSID. See the changeInterval() command. NewInterval – The data interval for a new time series, typically used where the interval must be explicitly defined and is not determined from a TSID. See also NewTSID. See the changeInterval() command. NewTimeScale – The new time scale (ACCM for accumulated data, INST for instantaneous data, MEAN for mean data) for a time series. See the changeInterval() command. NewTSID – The new time series identifier for a time series, used with commands that create new time series. See the copy() and newDayTSFromMonthAndDayTS() commands. NewUnits – The new data units for a time series. See the converDataUnits(), TS Alias = readDateValue(), TS Alias = readMODSIM(), TS Alias = readNWSCard(), and TS Alias = readRiverWare() commands. NewValue – The new value in an analysis. See the replaceValue() and setDataValue() commands. NumEquations – Number of equations to use when analyzing data (typically one or monthly equations). See the fillMOVE2() and fillRegression() commands. ObsTSID – The time series identifier for an observed time series. See the lagK() command. OdbcDSN – The Open Database Connectivity (ODBC) Data Source Name (DNS) for a database connection. See the openHydroBase() command. OldTimeScale – The old time scale (ACCM for accumulated data, INST for instantaneous data, MEAN for mean data) for a time series. See the changeInterval() command. OutflowStates – The outflow states (initial states) when routing a flow time series. See the lagK() command. OutputEnd – A DateTime that indicates the end of output. OutputFile – The name of an output file to be written, specified using a relative or absolute path. OutputStart – A DateTime that indicates the start of output. OutputYearType – Indicate the type of year (e.g., calendar year, water year) for output. See the setOutputYearType() command. PatternFile – The file name for a pattern file. See setPatternFile() command. Command Glossary -6 28 TSTool Documentation Command Glossary PatternID – An identifier for a pattern (e.g., WET, DRY, AVG). See the analyzePattern() and fillPattern() commands. Percentile – Percentile value(s) used when analyzing time series. See the analyzePattern() command. Pos – The position in the time series list. See the deselectTimeSeries() and selectTimeSeries() commands. pP – Used with the ARMA() command. Precision – The precision (number of digits after the decimal point) used when comparing values or formatting values for output. See the compareTimeSeries(), writeRiverWare(), and writeStateMod() commands. QueryEnd – A DateTime that indicates the end of a database query. The InputEnd parameter is preferred and is used in new commands. QueryStart – A DateTime that indicates the start of database query. The InputStart parameter is preferred and is used in new commands. qQ – Used with the ARMA() command. Read24HourAsDay – Indicate that a time series with data interval 24Hour should be automatically read as Day. See the readNwsCard() and TS Alias = readNwsCard() commands. ReadEnd – A DateTime that indicates the end of a file read. See the readNWSCard() command. The InputEnd parameter is preferred. ReadStart – A DateTime that indicates the start of file read. See the readNWSCard() command. The InputStart parameter is preferred. RecalcLimits – Recalculate the data limits for a time series, usually when supplemental raw data are being supplied after an initial read. See the fillUsingDiversionComments() command (used with the State of Colorado’s HydroBase input type). ReferenceDate – The starting date for a time series trace. See the createTraces() command. Reset – A DateTime field that indicates when to reset data values in a manipulation. For example, a time series may be set to zero at the start of each year when used with the cumulate() command. See the cumulate() command. RunMode – Typically used to indicate whether the command should be processed in batch mode, via the GUI, or both. See the openHydroBase(), processTSProduct(), and setWorkingDir() commands. Scale – A scale factor to be applied to data. See the writeRiverWare() command. ScaleValue – A numerical value used for scaling time series. See the scale() command. 29 Command Glossary -7 Command Glossary TSTool Documentation Scenario – The scenario to use when forming a TSID. See the createFromList() command. ScreenLevel – The level for messages printed to the screen (console). See the setDebugLevel() and setWarningLevel() commands. SelectAllFirst – Indicate whether to select all time series before processing the command. See the deselectTimeSeries()command. SearchStart – A DateTime that indicates the search start date/time in an analysis. See the newStatisticYearTS() command. SetEnd – A DateTime that indicates the end of a set process. Set_scale – See the writeRiverWare() command. SetStart – A DateTime that indicates the start of set process. Set_units – See the writeRiverWare() command. ShiftDataHow – Indicate how to shift time series traces. See the createTraces() command. SpecifyWeightsHow – Indicate how to specify weights when processing time series. See the TS Alias = weighTimeSeries() command. Statistic – A statistic to evaluate. See the newStatisticYearTS() command. SubtractTSID – Time series identifiers for time series to subtract. See the subtract() command. Suffix – The suffix to be automatically applied to the name of a file. See the setLogFile() command. TestValue – A test value used in an analysis. See the newStatisticYearTS() command. Timeout – The timeout when running an external program, after which processing will continue. See the runProgram() command. Tolerance – A value (or values) used to indicate an allowable error/difference. See the compareTimeSeries() command. TransferHow – Indicate how to transfer data during processing, either according to the date/time or sequentially. The latter can be used when time series do not align on date/time (e.g., due to a shift, leap year, etc.). See the setFromTS() command. Transformation – Indicate whether the time series data should be transformed before processing. See the fillInterpolate(), fillMOVE2() , and fillRegression() commands. TSID – Time series identifier, which is used to uniquely identify a time series. In full notation, this consists of a string similar to the following: Location.DataSource.DataType.Interval.Scenario~InputType~InputName. In abbreviated form, the InputType and InputName are often omitted. The InputType and InputName are typically used only by read and write commands. Because a TSID may be long (especially when file Command Glossary -8 30 TSTool Documentation Command Glossary names are used for the InputName), an Alias may be assigned to the time series. The TSID parameter is typically used in commands for the time series that is being processed. See also Alias. TSID – When used as a command parameter the time series identifier indicates the time series to be processed. The TSID or alias can typically be specified. See also Alias. TSID1 – Time series identifier for the first daily time series in a command. See the fillDayTSFrom2MonthTSAnd1DayTS() command. TSID2 – Time series identifier for the first daily time series in a command. See the fillDayTSFrom2MonthTSAnd1DayTS() command. TSID_D1 – Time series identifier for the first time series in a command. See the TS Alias = relativeDiff() command. TSID_D2 – Time series identifier for the second daily time series in a command. See the fillDayTSFrom2MonthTSAnd1DayTS() command. TSID_M1 – Time series identifier for the first monthly time series in a command. See the fillDayTSFrom2MonthTSAnd1DayTS() command. TSID_M2 – Time series identifier for the second monthly time series in a command. See the fillDayTSFrom2MonthTSAnd1DayTS() command. TSList – Indicates how the list of time series is determined. Typical values are AllTS (process all time series), AllMatchingTSID (process all time series having identifiers that match the TSID parameter), SelectedTS (process all time series that have been selected with the selectTimeSeries() and deselectTimeSeries() commands). This parameter is being phased in to allow more flexibility when processing time series. TSProductFile – The name of a time series product (TSProduct) file. See the processTSProduct() command. Units – The data units for a time series. See the newTimeSeries(), TS Alias = readNWSRFSFS5Files(), and writeRiverWare() commands. Version – Indicates the file version, to allow the software to handle different data formats. See the readStateModB() command. View – Indicate whether a product should be graphically previewed (as opposed to simply writing an output file). See the processTSProduct() command. UseStoredProcedures – Indicates whether stored procedures should be used (versus straight SQL calls). This is being used to transition HydroBase queries to stored procedures. See the openHydroBase() command. 31 Command Glossary -9 Command Glossary TSTool Documentation WarnIfDifferent – Indicates whether a warning should be generated if data differences are detected. See the compareTimeSeries() and compareFiles() commands. WarnIfSame – Indicates whether a warning should be generated if data differences are NOT detected. See the compareTimeSeries() and compareFiles() commands. Weight –Weight(s) used when processing time series. See the TS Alias = weighTimeSeries() command. Where1, Where2 – Input filter information used when reading/querying data. See the readHydroBase() command. Year – Specify year(s) of interest. See the TS Alias = weighTimeSeries() command. Command Glossary -10 32 Command Reference – # -1 Command Reference: # Comment line Version 10.12.00, 2012-09-10 The # command indicates single-line comments. Commands can be converted to and from # comments by right-clicking on a command in TSTool and selecting from the popup menu. See also the /* and */comment block commands, which are used to comment multiple commands. The following table lists annotation tags that can be placed in comments to provide additional information to software that processes the commands, using notation similar to the following: #@expectedStatus Failure Command # Comment Tags Parameter Command that Uses Description @expectedStatus Failure @expectedStatus Warning RunCommands() Used to help the test framework know if an error or warning is expected, in which case a passing test can occur even if the command status is not “success”. @os Windows @os UNIX CreateRegressionTest CommandFile() Used to filter out test command files that are not appropriate for the operating system. Linux is included in UNIX. @readOnly TSTool main interface and command editors Indicates that the command file should not be edited. TSTool will update old command syntax to current syntax when a command file is loaded. However, this tag will cause the software to warn the user when saving the command file, so that they can cancel. This tag is often used with templates to protect the template from mistakenly being edited and saved in TSTool (TSTool does not currently allow editing templates within the interface). @testSuite ABC CreateRegressionTest CommandFile() Used to filter out test command files that are not appropriate for the operating system. 33 # Command TSTool Documentation Command Reference – # -2 The following dialog is used to edit the command and illustrates the command syntax: Comment # Command Editor The command syntax is as follows: # Some text A sample command file is as follows: ## Some comments… # 34 Command Reference – /* -1 Command Reference: /* Comment block start Version 10.12.00, 2011-09-10 The /* command starts a multi-line comment block and is useful for inserting long comments or temporarily commenting out blocks of commands. See also the */and # commands. Commands between the /* and */are not converted to comments but are skipped during processing. See also the # comment documentation for information about comment @annotations. The following dialog is used to edit the command and illustrates the command syntax: CommentBlockStart /* Command Editor The command syntax is as follows: /* A sample command file is as follows: /* SomeCommentedOutCommands()… */35 /* Command TSTool Documentation Command Reference – /* -2 This page is intentionally blank. 36 Command Reference: */Comment block end Version 08.17.00, 2008-10-01 The */command ends a multi-line comment block and is useful for inserting long comments or temporarily commenting out blocks of commands. See also the /* and # commands. Commands between the /* and */are not converted to comments but are skipped during processing. The following dialog is used to edit the command and illustrates the command syntax: CommentBlockEnd */Command Editor The command syntax is as follows: */A sample command file is as follows: /* SomeCommentedOutCommands()… */37 Command Reference – */-1 */Command TSTool Documentation This page is intentionally blank. Command Reference – */-2 38 Command Reference: Time Series Identifier (TSID) Read a single time series given the time series identifier Version 09.00.03, 2009-01-15 A time series identifier (TSID) command reads a single time series. In order to read the time series from a persistent format (database, file, or web site), the TSID must contain the input type, and if necessary, the input name. For example, a TSID command for the State of Colorado’s StateMod model file format is of the form: LocationID…Interval~StateMod~Filename Refer to the StateMod Input Type appendix for a full description of the file format. Appendices are available for all input types. A TSID command for a StateMod file is generated as follows: 1. Select the StateMod input type and appropriate time step in the main TSTool window. 2. Press the Get Time Series List button to list time series. A dialog will prompt for the StateMod file and after selection the first year of data from the file will be read to get a list of identifiers. The interval that is specified (Month or Day) indicates whether the file is a monthly or daily format. The time series will be listed in the time series list in TSTool. 3. Select one or more time series from the list and copy to commands. The following dialog is used to edit the command and illustrates the syntax of the command. Limited checks are done while editing the command. However, once committed, TSTool will attempt to read the time series metadata and will issue a warning if unable to read the data. Time series identifiers that include filenames should typically be adjusted to a relative path to allow the files to be moved to another location and run without errors. Use the Remove Working Directory button to remove the working directory (or Add Working Directory) to add it. TSID_StateMod TSID Command Editor for a Time Series Read From a StateMod File 39 Command Reference – TSID -1 TSID Command TSTool Documentation The following example is for a TSID for the State of Colorado’s HydroBase database. In this case there is no filename in the identifier and therefore no need to adjust to a relative path. TSID TSID Command Editor for a Time Series Read From the HydroBase Database After executing the command, the time series will have the identifier as originally requested, with no alias being assigned. Use the TS Alias = ReadTimeSeries() command to assign an alias to the time series, or use one of the specific read commands. A sample command file to read time series from a StateMod file is as follows. In this case the absolute paths have been adjusted to relative paths using the command editor dialog. Note also that the data source and data type are not required because this information is not stored in the StateMod file. 09303000...MONTH~StateMod~whiteT.rih 09303400...MONTH~StateMod~whiteT.rih A sample command file to read time series from the State of Colorado’s HydroBase database is as follows: # 06754000 -SOUTH PLATTE RIVER NEAR KERSEY 06754000.DWR.Streamflow.Month~HydroBase # 06758500 -SOUTH PLATTE RIVER NEAR WELDONA 06758500.DWR.Streamflow.Month~HydroBase Command Reference – TSID -2 40 Command Reference: Add() Add one or more time series to a time series (or ensemble) Version 09.09.01, 2010-10-18 The Add() command adds regular interval time series. The receiving time series will be set to the sum of itself and all indicated time series. See also the NewTimeSeries() command, which can create an empty time series to receive a sum. If an ensemble is being processed, another ensemble can be added, a single time series can be added to all time series in the ensemble, or a list of time series can be added to the ensemble (the number in the list must match the number of time series in the ensemble). This command will generate an error if the time series do not have compatible units. If the units are compatible but are not the same (e.g., IN and FT), then the units of the part will be converted to the units of the sum before addition. Missing data in the parts can be ignored (do not set the sum to missing) or can result in missing values in the sum. The user should consider the implications of ignoring missing data. Time series being added must have the same data interval. The following dialog is used to edit the command and illustrates the syntax of the command. Add Add() Command Editor The command syntax is as follows: Add(Parameter=Value,…) 41 Command Reference – Add() -1 Add() Command TSTool Documentation Command Parameters Parameter Description Default TSID The time series identifier or alias for the time series to receive the sum. TSID or EnsembleID must be specified. EnsembleID The ensemble to receive the sum, if processing an ensemble. TSID or EnsembleID must be specified. AddTSList Indicates how the list of time series is specified, one of: • AllTS – all time series before the command. • AllMatchingTSID – all time series that match the AddTSID (single TSID or TSID with wildcards) will be added. • EnsembleID – the time series from ensemble will be added. • LastMatchingTSID – the last time series that matches the TSID (single TSID or TSID with wildcards) will be added. • SelectedTS – the time series are those selected with the SelectTimeSeries() command. • SpecifiedTSID – the specified list of time series given by the AddTSID parameter. AllTS (the time series receiving the sum will not be added to itself) AddTSID If the AddTSList parameter is SpecifiedTSID, provide the list of time series identifiers (or alias) to add, separated by commas. If the AddTSList parameter is AllMatchingTSID, FirstMatchingTSID, or LastMatchingTSID, specify a single TSID or a TSID with wildcards. Must be specified if TSList= SpecifiedTSID, ignored otherwise. AddEnsembleID If the EnsembleID parameter is specified, providing an ensemble ID will add the ensembles. Use if an ensemble is being added to another ensemble. Handle MissingHow Indicates how to handle missing data in a time series, one of: • IgnoreMissing – create a result even if missing data are encountered in one or more time series – this option is not as rigorous as the others • SetMissingIfOtherMissing – set the result missing if any of the other time series values is missing • SetMissingIfAnyMissing – set the result missing if any time series value involved is missing IgnoreMissing IfTSListToAdd IsEmpty Action if time series list to add is empty. Fail A sample command file to add two time series from the State of Colorado’s HydroBase is as follows: # 0100501 -EMPIRE DITCH 0100501.DWR.DivTotal.Month~HydroBase # 0100503 -RIVERSIDE CANAL 0100503.DWR.DivTotal.Month~HydroBase Add(TSID="0100501.DWR.DivTotal.Month",TSList="SpecifiedTSID", AddTSID="0100503.DWR.DivTotal.Month",HandleMissingHow=IgnoreMissing) Command Reference – Add() -2 42 Command Reference: AddConstant() Add a constant value to all data values in a time series (or ensemble) Version 09.10.01, 2010-11-18 The AddConstant() command adds a constant value to each data value in a time series (or ensemble of time series) within the specified period. This command is useful, for example, when a time series needs to be adjusted for a constant bias. Another example is to adjust a reservoir total volume time series by the dead pool storage in order to compute the active storage (or inverse). Missing data values will remain missing in the result. The following dialog is used to edit the command and illustrates the syntax of the command. AddConstant AddConstant() Command Editor 43 Command Reference – AddConstant() -1 AddConstant() Command TSTool Documentation The command syntax is as follows: AddConstant(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. TSID or EnsembleID must be specified. EnsembleID The ensemble to be modified, if processing an ensemble. TSID or EnsembleID must be specified. ConstantValue The data value to add to the time series. None – must be specified. AnalysisStart The date/time to start analyzing data. Full period. AnalysisEnd The date/time to end analyzing data. Full period. A sample commands file to process data from the State of Colorado’s HydroBase is as follows: # 2003536 -CONTINENTAL RES 2003536.DWR.ResMeasStorage.Day~HydroBase AddConstant(TSList=AllMatchingTSID,TSID="2003536.DWR.Res MeasStorage.Day", ConstantValue=5000) CommandReference/AddConstant/Example_AddConstant_HydroBase.TSTool Command Reference – AddConstant() -2 44 Command Reference: AdjustExtremes() Adjust the extreme values in time series data Version 09.10.01, 2010-11-18 The AdjustExtremes()command adjusts extreme values in time series (e.g., to remove negative values from a time series that can only have values greater than or equal to zero), while preserving “mass”. The following dialog is used to edit the command and illustrates the syntax of the command. AdjustExtremes AdjustExtremes() Command Editor The command syntax is as follows: AdjustExtremes(Parameter=Value,…) 45 Command Reference – AdjustExtremes()