TSTool-Vol2-CommandReference - Laserfiche WebLink

filled value as follows: • If FillUsingCIUFlag=Auto is specified, the CIU value (H, I, or N) from HydroBase is used for the flag. • Else if FillUsingCIUFlag is specified, tag filled values with the specified character. The flag can then be used later to label graphs, etc. The flag will be appended to existing flags if necessary. No flag is assigned. RecalcLimits Indicate whether the original data limits for the time series should be recalculated after the zero values are set. Zero values are included in the monthly and annual averages. See the discussion above related to CIU – time series that are impacted by CIU always have their limits recalculated. False (additional zeros are not considered in the original data averages). Command Reference – FillUsingDiversionComments() -4 216 TSTool Documentation FillUsingDiversionComments() Command A sample commands file to fill diversion time series from the State of Colorado’s HydroBase is as follows: # 0100506 -PUTNAM DITCH 0100506.DWR.DivTotal.Month~HydroBase # 0100503 -RIVERSIDE CANAL 0100503.DWR.DivTotal.Month~HydroBase # 0100501 -EMPIRE DITCH 0100501.DWR.DivTotal.Month~HydroBase FillUsingDiversionComments(TSID ="*",RecalcLimits=True) The following example fills one time series and labels the values with the flag. # Set the date to cause comments NOT to automatically extend the period. # setOutputPeriod(195 0-01,1989-06) # 0100713 -PIONEER DITCH 0100713.DWR.DivTotal.Month~HydroBase FillUsingDiversionComments(TSID="*",FillFlag="Auto",RecalcLimits=False) The corresponding graph created with data flags as labels is shown below (note the D symbols on the right). It may be necessary to change the graph properties to display the data labels above the point in order to see labels at the bottom of the graph. fillUsingDiversionComment_Graph Example Graph Showing Fill Flag (D labels indicate additional zero values) 21 7 Command Reference – FillUsingDiversionComments() -5 FillUsingDiversionComments() Command TSTool Documentation This page is intentionally blank. Command Reference – FillUsingDiversionComments() -6 218 Command Reference – FormatDateTimeProperty() -1 Command Reference: FormatDateTimeProperty() Format a date/time property as a new string property Version 10.16.00, 2013-01-15 The FormatDateTimePropert y() command creates a new global string property by formatting an existing date/time property. These properties are accessible to commands using ${Property} notation. A formatted date/time string is useful when specifying filenames more dynamically. Date/time properties will by default be formatted using the ISO 8061 format (e.g., YYYY-MM-DD hh:mm:ss). Support for properties varies by command and command documentation should be consulted. This command should not be confused with the SetTimeSeriesProperty() command, which sets a property on specific time series. The following dialog is used to edit this command and illustrates the syntax of the command. FormatDateTimeProperty FormatDateTimeProperty() Command Editor The command syntax is as follows: FormatDateTimeProperty(Parameter=Value,…) Command Parameters Parameter Description Default PropertyName The name of the string property to be created. None – must be specified. DateTimePropertyName The name of the existing date/time property to be formatted. None – must be specified. FormatterType The date/time formatter type, which defines the format specifiers, one of: • C – the C programming language strftime() function, which has been widely copied (described below). • MS – Microsoft convention (currently not supported but may be added in the future). C 219 FormatDateTimeProperty() Command TSTool Documentation Command Reference – FormatDateTimeProperty() -2 Parameter Description Default Format The format string for the formatter, which defines how date/time data parts are formatted into the new string property. The string is interpreted by the formatter as follows: • Formatter=Strftime – The string can contain literal characters and format specifiers that start with the % character. None – must be specified. The following table lists the supported formatting strings for FormatterType=C: Supported C (Strftime) Formatting Specifiers Format Specifier Description %a Weekday abbreviation (e.g., Sun) %A Weekday (e.g., Sunday). %b Month abbreviation (e.g., Jan). %B Month (e.g., January). %d Day (01-31). %H Hour (00-23). %I Hour (01-12). %j Day of year (001-366). %m Month (01-12). %M Minute (00-59). %p AM, PM (noon=PM, midnight=AM). %S Second (00-59). %y Year (00-99). %Y Year (0000-9999). %Z Time zone (e.g., MST). A sample command file is as follows: SetProperty(PropertyName="DateTimeProp",PropertyType=DateTime, PropertyValue="CurrentToSecond") FormatDateTimePrope rty(PropertyName="DateTimePropString", DateTimePropertyName="DateTimeProp",Format="%Y-%m-%dT%H:%M:%S") 220 Command Reference – FormatTableString () -1 Command Reference: FormatTableString() Format a string column in a table, using other columns as input Version 10.21.00, 2013-06-26 The FormatTableString() used zero or more table columns as input and formats an output table column. For example, it may be necessary to concatenate information from several columns to create an identifier. It can also be used to assign a literal string to a column. See also the ManipulateTableString() command. Formatting occurs as follows: • The data types for input columns control the type of formatting that can be done. For example, columns containing floating-point numbers must use the format specifiers for floating-point numbers. • Format specifiers are consistent with the C programming language. • Missing values in input will result in blanks in output. The following dialog is used to edit the command and illustrates the syntax of the command. FormatTableString FormatTableString() Command Editor 221 FormatTableString() Command TSTool Documentation Command Reference – FormatTableString() -2 The command syntax is as follows: FormatTableString(Parameter=Value,…) Command Parameters Parameter Description Default TableID The identifier for the table to process. None – must be specified. InputColumns The names of one or more input columns. Values from the columns will be formatted according to the Format parameter. Input columns can be omitted if the format string is a literal value. Required if format specifiers are given. Format The format specifier string used to format the data values. See the editor dialog for examples and refer to “sprintf” documentation on the internet for further explanation. Specify as many format specifiers as input columns. All other characters will be transferred to the output string. None – must be specified. OutputColumn The name of the column to receive the output. None – must be specified. 222 Command Reference: Free() Free (remove) time series from memory Version 09.10.01, 2010-11-18 The Free() command frees (removes) the selected time series from memory. The time series will therefore not be available for use after that line in the command file. This command is useful for discarding temporary time series needed for data manipulation (e.g., so that they are not written in output and are not available for interactive plots). Freed time series are also removed from any ensembles that reference the time series. Rather than freeing time series, it may be more appropriate to use the SelectTimeSeries() command, which can be used in conjunction with some commands to select time series and then operate on the selected time series. This approach allows selective use of time series and minimized the need for Free() commands. Many commands also use a TSList parameter to indicate which time series should be operated on by a command. The following dialog is used for editing the command and illustrates the command syntax. Free Free() Command Editor 223 Command Reference – Free () -1 Free() Command TSTool Documentation The command syntax is as follows: Free(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 (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 FreeEnsembleIfEmpty Indicate whether to free the ensemble from which time series were removed, if the ensemble is empty (has no time series remaining after the Free() command). True A sample command file is as follows: Free(TSList=AllMatchingTSID,TSID="40*") Command Reference – Free () -2 224 Command Reference – FreeTable () -1 Command Reference: FreeTable() Free a table Version 10.16.01, 2013-02-14 The FreeTable() command frees a table. The table will not be available for subsequent commands, although a new table with the same name can be created and used with subsequent commands. This command is useful, for example, when looping through blocks of commands where logic is repeated and the table contents are recreated. The following dialog is used to edit the command and illustrates the syntax of the command. FreeTable FreeTable() Command Editor The command syntax is as follows: FreeTable(Parameter=Value,…) Command Parameters Parameter Description Default TableID The identifier for the original table. None – must be specified. 225 FreeTable() Command TSTool Documentation Command Reference – FreeTable() -2 This page is intentionally blank. 226 Command Reference – FTPGet() -1 Command Reference: FTPGet() Retrieve file(s) from a remote system using file transfer protocol (FTP) Version 10.01.00, 2011-11-15 The FTPGet() command retrieves one or more files from a remote system using file transfer protocol (FTP). The retrieval is not recursive to child folders. The following dialog is used to edit the command and illustrates the syntax for the command. FTPGet FTPGet() Command Editor 227 FTPGet() Command TSTool Documentation Command Reference – FTPGet() -2 The command syntax is as follows: FTPGet(Parameter=Value,…) Command Parameters Parameter Description Default RemoteSite The address of the remote site, for example: ftp.acme.com Global properties can be used with the ${Property} syntax. None – must be specified. Login The FTP login to use. anonymous Password The FTP password to use. anonymous RemoteFolder The folder on the remote site, for example: /outgoing/data Global properties can be used with the ${Property} syntax. Root folder (/). FilePattern The pattern to use to determine which files should be transferred. Simple patterns are used, where * is a wildcard. Global properties can be used with the ${Property} syntax. Retrieve all files in the RemoteFolder. DestinationFolder The folder to receive the files, can be relative to the working directory. Global properties can be used with the ${Property} syntax. None – must be specified. TransferMode The transfer mode: • ASCII – for text files • Binary – for binary files Binary RetryCount The number of times to retry the login if it fails (e.g., due to busy site). 3 RetryWait The amount of time to wait between retries, seconds. 3 228 Command Reference – InsertTimeSeriesIntoEnsemble () -1 Command Reference: InsertTimeSeriesIntoEnsemble () Insert 1+ time series into an existing ensemble Version 10.13.00, 2012-10-25 The InsertTimeSeriesIntoEnsemble() command inserts 1+ time series into an ensemble. The time series must have the same interval and data units as the time series in the ensemble. For example, use the command to insert scenario time series into an ensemble. The following dialog is used to edit the command and illustrates the syntax for the command. InsertTimeSeriesIntoEnsemble InsertTimeSeriesIntoEnsemble () Command Editor 229 InsertTimeSeriesIntoEnsemble () Command TSTool Documentation Command Reference – InsertTimeSeriesIntoEnsemble() -2 The command syntax is as follows: InsertTimeSeriesIntoEnsemble (Parameter=Value,…) Command Parameters Parameter Description Default TSList Indicates the list of time series to be added to the ensemble, one of: • AllMatchingTSID – all time series that match the TSID (single TSID or TSID with wildcards). • AllTS – all time series before the command. • EnsembleID – all time series in the ensemble. • FirstMatchingTSID – the first time series that matches the TSID (single TSID or TSID with wildcards). • LastMatchingTSID – the last time series that matches the TSID (single TSID or TSID with wildcards). • 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 processed, using the * wildcard character to match multiple time series. Required when TSList=*TSID EnsembleID The ensemble from which to retrieve time series, if inserting time series from an ensemble. Required when TSList=EnsembleID. EnsembleID2 The identifier for the ensemble that is receiving the time series. None – must be specified. A sample command file to create an ensemble from user-defined time series is as follows: # Test inserting time series into an ensemble from year interval time series NewPatternTimeSeries(Alias="ts1",NewTSID="ts1..Flow.Year", SetStart="1960",SetEnd="2000",Units="ACFT", PatternValues="1,2, 5,8,,20") NewPatternTimeSeries(Alias="ts2",NewTSID="ts2..Flow.Year", SetStart="1950",SetEnd="2005",Units="ACFT", PatternValues="2,4,10,16,,40") NewEnsemble(TSList=AllTS, NewEnsembleID="TestEnsemble", NewEnsembleName="Test Ensemble") InsertTimeSeriesIntoEnsemble(Ensemble2=”TestEnsemble”) 230 Command Reference: LagK() Lag and attenuate (route) a time series Version 10.00.00, 2011-03-28 The LagK() command can be used to lag and attenuate an input time series, resulting in a new time series. The time series identifier for the new time series is the same as the original time series with “routed” appended to the scenario. The command is commonly used to route an instantaneous flow time series through a stretch of river (reach). Lag and K routing is a common routing method that combines the concepts of: 1. Lagging the inflow to simulate travel time in a reach and, 2. Attenuating the wave to simulate the storage-outflow relationship for the reach (see Figure 1). Inflows Lagged Inflows Outflows (lagged and attenuated) Q Time Figure 1: Lag and K Routing At its fundamental level, the method solves the continuity equation using an approach similar to Muskingum routing (assuming that the Muskingum parameter representing wave storage is negligible). The governing equation for this routing method is given as: t Q Q S in out ΔΔ − = where: Qin = instantaneous inflow [rate] lagged appropriately, Qout = instantaneous outflow [rate] lagged appropriately, ΔS = change in storage in the reach [volume], Δt = time difference. 231 Command Reference – LagK() -1 LagK() Command TSTool Documentation The relationship assumes an outflow-storage relationship of the form: S = k ⋅ Qout, where: k = attenuation for the outflow [time]. To ensure accurate results, k should be larger or equal to Δt/2. For discrete time steps these relationships translate into: 2 , 2 1 2 1 1 1 2 2 k t t k O t I I S O Δ ≥ + Δ − Δ + + = where: I1 and I2 are the lagged inflows into the reach at the previous and current time step, respectively, O1 and O2 are the outflows out of the reach at the previous and current time step, respectively, S1 is the storage within the reach at the previous time step, defined as S1 = k⋅O1, and Δt is the time difference between the two time steps. In the case that either I1 , I2 or O1 are missing, these values will be set in the following order: 1. Use data from an observed time series (see ObsTSID parameter below). 2. Use the nearest value in the input time series (see FillNearest parameter below). 3. Use the nearest value in the observed time series (see FillNearest parameter and the ObsTSID parameter below). 4. Use a defined default flow value (see DefaultFlow parameter below). By default, the identifier of the resulting time series is the same as the original input time series, with the data subtype set to “routed” (e.g., Streamflow becomes Streamflow-routed) Command Reference – LagK() -2 232 TSTool Documentation LagK() Command The following dialog is used to edit the command and illustrates the syntax for the command: LagK LagK() Command Editor Values for Lag and K can usually be established by comparing routed flows to downstream observations. Alternatively, the Lag can be estimated using the reach length and wave speed in the reach. Without any other information, K can be set to Lag/2. The command syntax is as follows: LagK(Parameter=Value,…) The following older command syntax is updated to the above syntax when a command file is read: TS Alias = LagK(Parameter=Value,…) Command Parameters Parameter Description Default TSID Identifier or alias for the time series to be routed. It is assumed that this series describes an instantaneous flow. Due to the lagging, the first data values required for the computation of O2 are not available within this time series and are therefore set to values set in the InflowStates parameter. See also the ObsTSID time series, and the FillNearest and DefaultFlow parameters. None – must be specified. ObsTSID Identifier or alias for an observed time series. If specified, the None 233 Command Reference – LagK() -3 LagK() Command TSTool Documentation Parameter Description Default missing values in the TSID time series will be taken from the observed time series if non-missing. ObsTSID can be used in conjunction with FillNearest to substitute a missing value in the TSID time series with the nearest non-missing value in ObsTSID. Alias The alias to assign to the time series, as a literal string or using the special formatting characters listed by the command editor. The alias is a short identifier used by other commands to locate time series for processing, as an alternative to the time series identifier (TSID). None – must be specified. FillNearest If set to True, then when a missing data value is found anywhere in the lagged period, a replacement value will be determined by searching forward and back in time in the input time series to find the nearest non-missing value. The maximum search window depends on the interval of the TSID time series: • <= Seconds: 1000 intervals • Minute, Hour: 1 day • Day: 1 Week • > Day: 1 interval only The assumption is that a flow value close in time will be representative of the missing value and will not result in significant errors. This option has lower precedence than specifying the ObsTSID data. It can also find non-missing data in the ObsTSID if ObsTSID is defined (lower precedence). Both options have a higher precedence than DefaultFlow. False DefaultFlow A flow value in the units of the input time series that is substituted for missing values in the input time series. This has the lowest precedence of all missing data substitutions. It will be applied at any time in the lagged period. 0 Lag Lag time for the modeled reach in the units of the TSID time series base interval. For example, if the input time series is 10 minutes, the units of Lag are assumed to be minutes. The Lag value is not required to be evenly divisible by the time step interval; values in the time series between time steps will be linearly interpolated. Required K Attenuation factor to be applied to the wave. The units of K are time, and like the Lag value, it is assumed to have the same units as the input time series. Required InflowStates Comma-delimited list of default inflow values prior to the start of the time series. The order of the values is earliest to latest. The array must specify (Lag/multiplier) + 1 values; i.e., a 10 minute interval with a LAG of 30 must be provided with 30/10 + 1 = 4 inflow carryover values. Note: Specifying values that are not consistent with the Lag and K parameters will result in oscillation! 0 for each value OutflowStates Comma-delimited list of default outflow values prior to the start of the time series. See InflowStates for details. 0 for each value A sample command file is as follows (commands to read time series are omitted): LagK(Alias=”LKPN6routed”,TSID=LKPN6.USGS.QIN.1HOUR,Lag=3,K=2,FillNearest=true) Command Reference – LagK() -4 234 Command Reference – LookupTimeSeriesFromTable() -1 Command Reference: LookupTimeSeriesFromTable() Crate new time series by using an input time series and a lookup table Version 10.05.00, 2012-02-12 The LookupTimeSeriesFromTable() command uses an input time series and lookup table to create the output time series. Examples of using this command include: • Converting reservoir elevation to storage, surface area, seepage, or other values • Converting river stage to discharge • Converting a time series to category values In many cases the lookup table will apply throughout the analysis period. However, it is possible that the table will change over time (e.g., as a stream channel changes or a reservoir fills with silt). In these cases, the command allows for an effective date to be specified – the table then is applicable on and after the specified date/time, until another effective date is encountered. The values in the table should be sorted in ascending order prior to lookup. This command currently does not handle rating table shifts; however, this capability may be added in the future. The following dialog is used to edit the command and illustrates the syntax of the command: LookupTimeSeriesFromTable LookupTimeSeriesFromTable() Command Editor 235 LookupTimeSeriesFromTable() Command TSTool Documentation Command Reference – LookupTimeSeriesFromTable() -2 The command syntax is as follows: LookupTimeSeriesFromTable(Parameter=Value,…) Command Parameters Parameter Description Default TSID The time series identifier or alias for the time series used as input. None – must be specified. NewTSID The time series identifier for the time series being created. Use the Edit button to edit the time series identifier parts. None – must be specified. Alias The alias to assign to the time series, as a literal string or using the special formatting characters listed by the command editor. The alias is a short identifier used by other commands to locate time series for processing, as an alternative to the time series identifier (TSID). No alias. TableID The lookup table identifier. None – must be specified. Table TSIDColumn Table column name that is used to match the time series identifier for processing. This parameter currently is not supported but will be enabled in the future. If not specified, it is assumed that the entire lookup table applies. Table TSIDFormat The specification to format the time series identifier to match the TableTSIDColumn column. This parameter currently is not supported but will be enabled in the future. Time series alias if available, or otherwise the time series identifier. Table Value1Column Table column name for data values that correspond to the input time series (TSID). None – must be specified. Table Value2Column Table column name for data values that correspond to the output (new) time series identifier (NewTSID). None – must be specified. Units The data units to assign to the new time series. No data units will be assigned. Effective DateColumn Table column name for the effective date. This parameter currently is not supported but will be enabled in the future. The lookup data apply to the entire period. LookupMethod Indicate how to select the value to use for output: • Interpolate – interpolate between points if input values do not exactly align with table values; if Transformation=Log, then interpolation will use the transformed values • PreviousValue – pick the previous (lower) value in the table (exact matches use the lookup table value) • NextValue – pick the next (higher) value in the table (exact matches use the lookup table value) Interpolate OutOfRange LookupMethod Indicate the value to use when estimating values that are outside the range of the rating table: SetMissing 236 TSTool Documentation LookupTimeSeriesFromTable() Command Command Reference – LookupTimeSeriesFromTable() -3 Parameter Description Default • Extrapolate – use the two known values at the end of the table to extrapolate; if Transformation=Log, then extrapolation will use the transformed values • SetMissing – set output to missing • UseEndValue – use the data value on the end OutOfRange Notification Indicate the notification to generate when a value is outside the range of the lookup table: • Ignore – do not generate warning or failure message • Warn – generate a warning message • Fail – generate a failure message Ignore Transformation Indicates how to transform the data before interpolation, used when LookupMethod=Interpolate and OutOfRangeMethod=Extrapolate). Specify as None to compare raw values or Log (for log10) to transform values before interpolation and extrapolation. If the Log option is used, zero and negative values are replaced with the value specified by the LEZeroLogValue parameter value for analysis (missing data values are ignored in the analysis). None (no transformation). LEZero LogValue Value to use for data values less than or equal to zero when using a log transformation. .0010 AnalysisStart The date/time to start the analysis. Analyze the full period. AnalysisEnd The date/time to end the analysis. Analyze the full period. 237 LookupTimeSeriesFromTable() Command TSTool Documentation Command Reference – LookupTimeSeriesFromTable() -4 This page is intentionally blank. 238 Command Reference – ManipulateTableString () -1 Command Reference: ManipulateTableString() Manipulate string a string column in a table Version 10.21.00, 2013-06-14 The ManipulateTableString() command manipulates a string column in a table. For example, it may be necessary to manipulate strings in a table in order to match time series identifier parts, so that lookups can occur. The input is specified by: • a table column name (InputColumn1) • either a second input column name (InputColumn2) or a constant string value (InputValue2) • optionally, some operators require an additional input value (InputValue3) The result is placed in the output column (OutputColumn). Missing/blank input will be considered as empty strings when formatting the output. The output column can be the same as an existing table column. The following dialog is used to edit the command and illustrates the syntax of the command (in this case illustrating how the contents of column String2 are prepended to the contents of a column named String1 and placed in the output column String3). ManipulateTableString ManipulateTableString() Command Editor 239 ManipulateTableString() Command TSTool Documentation Command Reference – ManipulateTableString() -2 The command syntax is as follows: ManipulateTableString(Parameter=Value,…) Command Parameters Parameter Description Default TableID The identifier for the table to process. None – must be specified. InputColumn1 The name of a column containing strings, as the first input. None – must be specified. Operator The operation to perform on the input strings: • Append – append the second input to the first input • Prepend – prepend the second input before the first input • Replace – replace in the second input in the first input, with the third input • ToDate – convert the first input to a DateTime object with date precision • ToDateTime – convert the first input to a DateTime object • ToDouble – convert the first input to a double precision object • ToInteger – convert the first input to an integer object None – must be specified. InputColumn2 The name of a column containing strings, as the second input. Required if a second input value is needed and InputValue2 is not specified. InputValue2 A string constant, as the second input. Required if a second input value is needed and InputColumn2 is not specified. InputValue3 A string constant, as the third input. Required if a third input