TSTool-Vol2-CommandReference - Laserfiche WebLink

the command may be updated to allow the option of returning other data intervals, including irregular (which would have only non-missing values but typically must be converted to a regular interval to use with other commands). 365 ReadUsgsNwisGroundwater() Command TSTool Documentation Command Reference – ReadUsgsNwisGroundwater() -2 The following dialog is used to edit the command and illustrates the syntax. Some choices are provided as a convenience. However, full listing of choices (such as all the thousands of wells that are available) is not provided due to performance issues. Additional query features will be enabled as web service integration is enhanced. ReadUsgsNwisGroundwater ReadUsgsNwisGroundwater() Command Editor 366 TSTool Documentation ReadUsgsNwisGroundwater() Command Command Reference – ReadUsgsNwisGroundwater() -3 The command syntax is as follows: ReadUsgsNwisGroundwater(Parameter=Value,…) Command Parameters Parameter Description Default Sites A list of site numbers to read, separated by commas. None – one of the locational parameters must be provided to constrain the query. States A list of state codes (e.g., AL), separated by commas. None – see above. HUCs A list of hydrologic unit codes, separated by commas. See the limitations on the NWIS site for more information. None – see above. BoundingBox A bounding box consisting of west longitude, south latitude, east longitude, and north latitude, separated by spaces. Longitudes in the western hemisphere are negative. None – see above. Counties A list of Federal Information Processing Standards (FIPS) county codes, separated by commas. None – see above. Parameters Data parameter codes for the stations (e.g., 72019 for depth to water level), separated by commas. All available parameters are returned. SiteStatus Filter for stations, one of: • All – all stations are returned • Active – only active stations are returned • Inactive – only inactive stations are returned All SiteTypes Site types to return, separated by commas. All available site types are returned. Agency Agency code to return (e.g., USGS). All available agencies are returned. Interval The interval to use for the created time series. Groundwater measurements in NWIS may be recorded for the day or may have more precise date/time. Using an interval of Day results in a regular interval time series that is easier to process by other commands, but may not be suitable when values change significantly within a day. None – must be specified. InputStart The start of the period to read data – specify if the period should be different from the global query period. Use the global query period. InputEnd The end of the period to read data – specify if the period should be different Use the global query period. 367 ReadUsgsNwisGroundwater() Command TSTool Documentation Command Reference – ReadUsgsNwisGroundwater() -4 Parameter Description Default from the global query period. 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. Format The data format for output, one of: • JSON – JavaScript Object Notation (currently used only for downloads but will not result in time series in TSTool) • RDB – tab-delimited format (also see ReadUsgsNwisRDB() command; currently used only for downloads but will not result in time series in TSTool). • WaterML – XML format (also see the ReadWaterML() command). WaterML OutputFile The name of the output file to create. The path to the file can be absolute or relative to the working directory. No output file will be created. 368 Command Reference – ReadUsgsNwisInstantaneous() -1 Command Reference: ReadUsgsNwisInstantaneous() Read 1+ time series from the USGS NWIS Instantaneous Values web service Version 10.13.00, 2012-10-30 The ReadUsgsNwisInstantaneous() command reads one or more time series from the United States Geological Survey (USGS) National Water Information System (NWIS) Instantaneous Values web service (see the UsgsNwisInstantaneous Datastore Appendix). The command provides parameters to constrain the web service query and also allows the result to be saved as an output file. For example, if WaterML is chosen as the time series format, a WaterML file can be saved and can be read later using the ReadWaterML() command. See also the WebGet() command, which also can be used to retrieve data files from the USGS website. The USGS NWIS web service allows station and time series data type information to be filtered, both as a convenience and to maintain reasonable web service performance. Many of the choices that are available for limiting queries allow 0+ values to be provided. For example, specifying no requested parameter will return all available parameters for a location. Specifying a list of parameters (separated by commas) will return only the requested parameters. The data interval for returned time series is set to 15Min. A check is performed to ensure that data line up with this interval. If the data do not line up, values are set by rounding time and warnings will be generated. Another option is to save the time series as a WaterML file and then use ReadWaterML() command, which allows the time series interval to be specified. USGS codes are used in order to generate a unique time series identifier (TSID). For example, the TSID data type is formed from the parameter code. The numerical codes currently are used to ensure uniqueness but in the future the string name may be allowed as an option. In order to have more humanfriendly identifiers for time series, one strategy is to request only a specific parameter and then use the alias to specify a text equivalent to the numeric codes. For example, specify Parameters=00060 (for streamflow discharge) and and assign the alias with Alias=%L.Streamflow. 369 ReadUsgsNwisInstantaneous() Command TSTool Documentation Command Reference – ReadUsgsNwisInstantaneous () -2 The following dialog is used to edit the command and illustrates the syntax. Note that some choices are provided as a convenience. However, full listing of choices (such as all the thousands of streamflow stations that are available) is not provided due to performance issues. Additional query features will be enabled as web service integration is enhanced. ReadUsgsNwisInstantaneous ReadUsgsNwisInstantaneous() Command Editor 370 TSTool Documentation ReadUsgsNwisInstantaneous() Command Command Reference – ReadUsgsNwisInstantaneous () -3 The command syntax is as follows: ReadUsgsNwisInstantaneous(Parameter=Value,…) Command Parameters Parameter Description Default Sites A list of site numbers to read, separated by commas. None – one of the locational parameters must be provided to constrain the query. States A list of state codes (e.g., AL), separated by commas. None – see above. HUCs A list of hydrologic unit codes, separated by commas. See the limitations on the NWIS site for more information. None – see above. BoundingBox A bounding box consisting of west longitude, south latitude, east longitude, and north latitude, separated by spaces. Longitudes in the western hemisphere are negative. None – see above. Counties A list of Federal Information Processing Standards (FIPS) county codes, separated by commas. None – see above. Parameters Data parameter codes for the stations (e.g., 00060 for stream discharge), separated by commas. All available parameters for the sites are returned. SiteStatus Filter for stations, one of: • All – all stations are returned • Active – only active stations are returned • Inactive – only inactive stations are returned All SiteTypes Site types to return, separated by commas. All available site types are returned. Agency Agency code to return (e.g., USGS). All available agencies are returned. InputStart The start of the period to read data to 15-minute precision – specify if the period should be different from the global query period. Use the global query period. InputEnd The end of the period to read data to 15-minute precision – specify if the period should be different from the global query period. Use the global query period. 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 None – must be specified. 371 ReadUsgsNwisInstantaneous() Command TSTool Documentation Command Reference – ReadUsgsNwisInstantaneous () -4 Parameter Description Default alternative to the time series identifier (TSID). Format The data format for output, one of: • JSON – JavaScript Object Notation (currently used only for downloads but will not result in time series in TSTool) • RDB – tab-delimited format (also see ReadUsgsNwisRDB() command; currently used only for downloads but will not result in time series in TSTool). • WaterML – XML format (also see the ReadWaterML() command). WaterML OutputFile The name of the output file to create. The path to the file can be absolute or relative to the working directory. No output file will be created. 372 Command Reference – ReadUsgsNwisRdb() -1 Command Reference: ReadUsgsNwisRdb() Read a single time series from a USGS NWIS RDB file Version 10.05.00, 2012-02-27 The ReadUsgsNwisRdb() command reads a single time series from a USGS NWIS RDB file (see the UsgsNwisRdb Input Type Appendix) and assigns an alias to the result. This command replaces the older ReadUsgsNwis() command – legacy ReadUsgsNwis() commands are automatically translated to ReadUsgsNwisRdb() commands. Currently only the daily streamflow format is supported and the file being read must contain only one time series. The data type is assigned as Streamflow, with units CFS. See also the WebGet() command, which can be used to retrieve data files from the USGS website. See also the ReadUsgsNwisDaily() and ReadWaterML() commands. The following dialog is used to edit the command and illustrates the syntax. ReadUsgsNwisRdb ReadUsgsNwisRdb() Command Editor 373 ReadUsgsNwisRdb() Command TSTool Documentation Command Reference – ReadUsgsNwisRdb() -2 The command syntax is as follows: ReadUsgsNwisRdb(Parameter=Value,…) The following legacy command syntax is updated to the above syntax when a command file is read: TS Alias = ReadUsgsNwis (Parameter=Value,…) Command Parameters Parameter Description Default InputFile The name of the USGS NWIS RDB file to read, surrounded by double quotes. The path to the file can be absolute or relative to the working directory. 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). None – must be specified. InputStart The start of the period to read data – specify if the period should be different from the global query period. Use the global query period. InputEnd The end of the period to read data – specify if the period should be different from the global query period. Use the global query period. A sample command file is as follows: ReadUsgsNwisRdb(Alias=”ts1”,InputFile="G03451500.txt") 374 Command Reference – ReadWaterML() -1 Command Reference: ReadWaterML() Read 1+ time series from a WaterML file Version 10.13.00, 2012-10-31 The ReadWaterML() command reads one or more time series from a WaterML XML time series file (see the WaterML Input Type Appendix). WaterML version 1.1 is supported. WaterML files can be created using the ReadUsgsNwisDaily(), ReadWaterOneFlow() , and WriteWaterML() commands, and can be saved from web sites that provide WaterML using the WebGet() command. This command may be enhanced in the future to read a subset of the time series in the WatermL file (currently all time series in the file are read), and additional WaterML versions may be supported. The following dialog is used to edit the command and illustrates the syntax. ReadWaterML ReadWaterML() Command Editor 375 ReadWaterML() Command TSTool Documentation Command Reference – ReadWaterML() -2 The command syntax is as follows: ReadWaterML(Parameter=Value,…) Command Parameters Parameter Description Default InputFile The name of the WaterML file to read. The path to the file can be absolute or relative to the working directory. 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 is assigned. Interval The data interval for the file, necessary because WaterML 1.1 does not have a data element indicating the interval (time step for the data) and using irregular by default would be inefficient for data management. This issue is being further evaluated. None – must be specified. RequireData ToMatchInterval Indicate whether the date/time for each data value must align with the interval: • True – For example, if Interval=15Min for USGS instantaneous data, then values a warning will be generated. • False – Date/times that do not align result in time series values being assigned using a truncated date/time. For example, USGS groundwater web service values read with Interval=Day will be assigned to the nearest day (by ignoring more precise time information). This parameter and the Interval parameter will continue to be evaluated. True Parameter is not used for irregular data. InputStart The start of the period to read data – specify if the period should be different from the global query period. Use the global query period. InputEnd The end of the period to read data – specify if the period should be different from the global query period. Use the global query period. 376 Command Reference – ReadWaterOneFlow() -1 Command Reference: ReadWaterOneFlow() Read 1+ time series from a WaterOneFlow web service Version 10.06.00, 2012-03-29 This command is under development. The ReadWaterOneFlow() command reads one or more time series from WaterOneFlow web service (see the WaterOneFlow Data Store Appendix) and optionally assigns an alias to the time series. WaterML version 1.0 is supported for time series transfer; however, the WaterML response currently cannot be saved to a file (and therefore output cannot be used with the ReadWaterML() command). The following dialog is used to edit the command and illustrates the syntax. Need to generate screen shot. ReadWtaerOneFlow ReadWaterOneFlow() Command Editor 377 ReadWaterOneFlow() Command TSTool Documentation Command Reference – ReadWaterOneFlow() -2 The command syntax is as follows: ReadWaterOneFlow(Parameter=Value,…) Command Parameters Parameter Description Default 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 is assigned. InputStart The start of the period to read data – specify if the period should be different from the global query period. Use the global query period. InputEnd The end of the period to read data – specify if the period should be different from the global query period. Use the global query period. 378 Command Reference: RelativeDiff() Create a relative difference time series Version 10.00.01, 2011-05-15 A RelativeDiff() command creates a new relative difference time series, computed by subtracting the time series and then dividing by one of the time series. This is useful when analyzing the relative magnitudes of two time series over time. Most of the properties for the new time series are the same as the first time series. The alias for the result can be referenced by other commands. The divisor can be either of the time series. The result is set to missing if either time series value is missing or the divisor is zero. The following dialog is used to edit the command and illustrates its syntax. RelativeDiff RelativeDiff() Command Editor 379 Command Reference – RelativeDiff() -1 RelativeDiff() Command TSTool Documentation The command syntax is as follows: RelativeDiff(Parameter=Value,…) The following older command syntax is updated to the above syntax when a command file is read: TS Alias = RelativeDiff(Parameter=Value,…) Command Parameters Parameter Description Default TSID1 The time series identifier or alias for the first time series. None – must be specified. TSID2 The time series identifier or alias for the second time series (subtracted from the first). None – must be specified. Divisor Indicates whether the first time series is the divisor (DivideByTS1) or the second time series is the divisor (DivideByTS2). 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). None – must be specified. A sample command file to process data from the State of Colorado’s HydroBase database is as follows: StartLog(LogFile="Example_Relative Diff.log") SetOutputPeriod(OutputStart="01/1912",OutputEnd="12/1998") # (1912-1998) RIO GRANDE AT ALAMOSA, CO. DWR Streamflow Monthly ReadTimeSeries(Alias=”Alamosa”,"08223000.DWR.Streamflow.Month~Hyd roBase") # (1890-1998) RIO GRANDE NEAR DEL NORTE, CO. DWR Streamflow Monthly ReadTimeSeries(TSID="08220000.USGS.Streamflow.Month~HydroBase", Alias=”DelNorte”) RelativeDiff(TSID1="DelNorte",TSID2="Ala mosa", Divisor=DivideByTS1,Alias=”RelativeDiff”) Command Reference – RelativeDiff() -2 380 TSTool Documentation RelativeDiff() Command The input time series for the command are shown in the following figure: relativeDiff_GraphData Data for the RelativeDiff() Command 381 Command Reference – RelativeDiff() -3 RelativeDiff() Command TSTool Documentation The results of processing the commands are shown in the following figure: relativeDiff_Graph Results of the RelativeDiff() Command Command Reference – RelativeDiff() -4 382 Command Reference: RemoveFile() Remove a file Version 09.02.00, 2009-04-03 The RemoveFile() command removes a file from the file system. This command is used in testing software to remove results files before attempting to regenerate the results. A failure will be generated if the file exists and cannot be removed (e.g., due to file permissions or being locked by another process). Even read-only files may be removed by this command, depending on how the operating system and computer environment handle access permissions. The following dialog is used to edit the command and illustrates the syntax for the command. RemoveFile RemoveFile() Command Editor 383 Command Reference – RemoveFile() -1 RemoveFile() Command TSTool Documentation The command syntax is as follows: RemoveFile(Parameter=Value,…) Command Parameters Parameter Description Default InputFile The name of the file to delete. None – must be specified. IfNotFound Indicate action if the file is not found, one of: • Ignore – ignore the missing file (do not warn). • Warn – generate a warning (use this if the file truly is expected and a missing file is a cause for concern). • Fail – generate a failure (use this if the file truly is expected and a missing file is a cause for concern). Ignore The following example command file illustrates how to remove a file: RemoveFile(InputFile="Results/output.dv") Command Reference – RemoveFile() -2 384 Command Reference – RemoveTableRowsFromDataStore() -1 Command Reference: RemoveTableRowsFromDataStore() Remove rows from a datastore table Version 10.18.00, 2013-02-26 The RemoveTableRowsFromDataStor e() removes rows from a database datastore table by executing an SQL DELETE statement. If database datastore support is not specifically provided by TSTool, a generic datastore can be used (see the Generic Database DataStore appendix). This command cannot be used with web service datastores and use with Excel datastores has not been tested. This command is useful in particular for bulk data processing such as to remove records in a table before (re)loading in bulk (see WriteTableToDataStore() command). General constraints are as follows: • the table or views being processed must be writeable by the user specified for the database connection (some databases restrict direct access to data and/or require using stored procedures) • currently, only the ability to delete all rows is supported (see RemoveAllRows command parameter); in the future functionality will be implemented to delete rows matching rows in a TSTool table The following dialog is used to edit the command and illustrates the syntax for the command. RemoveTableRowsFromDataStore RemoveTableRowsFromDataStore() Command 385 RemoveTableRowsFromDataStore() Command TSTool Documentation Command Reference – RemoveTableRowsFromDataStore() -2 The command syntax is as follows: RemoveTableRowsFromDataStore(Parameter=Value,…) Command Parameters Parameter Description Default DataStore The name of a database datastore to process. None – must be specified. DataStoreTable The name of the database table or view being processed. None – must be specified. RemoveAllRows Indicate whether all rows should be removed (True) or only a subset (False). False is the default as a safeguard and future enhancements will enable removing only rows that match TSTool table rows or a constraint. False – only rows matching TSTool table are removed. 386 Command Reference – ReplaceValue() -1 Command Reference: ReplaceValue() Replace time series data value(s) Version 10.06.00, 2012-03-22 The ReplaceValue() command replaces a range of values in a time series with a constant value, sets the values to missing, or removes the values (if an irregular time series). If the missing value indicator is a number in the range, missing values also will be replaced. The time series data flag can be checked in place of or addition to checking the numerical values. This command is useful for filtering out erroneous data values. See also the CheckTimeSeries() command, which provides for a variety of checks and also allows values to be set to missing or removed. The following dialog is used to edit the command and illustrates the syntax of the command: ReplaceValue ReplaceValue() Command Editor 387 ReplaceValue() Command TSTool Documentation Command Reference – ReplaceValue() -2 The command syntax is as follows: ReplaceValue(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 processed. • AllTS – all time series before the command. • EnsembleID – all time series in the ensemble will be processed. • FirstMatchingTSID – the first time series that matches the TSID (single TSID or TSID with wildcards) will be processed. • LastMatchingTSID – the last time series that matches the TSID (single TSID or TSID with wildcards) will be processed. • 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 if TSList=*TSID. EnsembleID The ensemble to be processed, if processing an ensemble. Required if TSList=EnsembleID. MinValue The minimum value to replace. The minimum value and/or MatchFlag must be specified. MaxValue The maximum value to replace. If not specified, only data values that exactly match the minimum value will be replaced. MatchFlag The flag to match. If specified in addition to MinValue, then the value and flag must be matched in order to perform the replacement. A case-sensitive comparison is made and the data value flag must exactly match MatchFlag. In the future additional flexibility may be added to match a substring, etc. If Action=SetMissing, the original data flag value will remain. Specifying SetFlag will result in the original data flag being modified. The minimum value and/or MatchFlag must be specified. NewValue The new data value. Required, unless the Action parameter is 388 TSTool Documentation ReplaceValue() Command Command Reference – ReplaceValue() -3 Parameter Description Default specified. Action An additional action to take with values that are matched: • Remove – remove the data points. This can only be specified for irregular interval time series and will be interpreted as SetMissing for regular interval time series. • SetMissing – set values to missing. No additional action is taken and the NewValue parameter must be specified. SetStart The date/time to start filling, if other than the full time series period. Check the full period. SetEnd The date/time to end filling, if other than the full time series period. Check the full period. AnalysisWindow Start The starting date/time within the calendar year to replace data. The window CANNOT cross calendar year boundaries (this may be allowed in the future). Use multiple commands if necessary. Process each full year. AnalysisWindow End The ending date/time within the calendar year to replace data. Process each full year. SetFlag A string to assign to data values that are replaced. Do not assign a string flag. A sample command file to process from the State of Colorado’s HydroBase database is as follows: # 08235700 -ALAMOSA RIVER BELOW CASTLEMAN GULCH NEAR JASPER 08235700.DWR.Streamflow.Month~HydroBase ReplaceValue(TSList=AllTS,MinValue=-100000,MaxValue=0,NewValue=0) 389 ReplaceValue() Command TSTool Documentation Command Reference – ReplaceValue() -4 This page is intentionally blank. 390 Command Reference: ResequenceTimeSeriesData() Resequence time series data (shuffle years of data) Version 10.00.01, 2011-05-15 The ResequenceTimeSeriesData() command resequences data in time series by shifting/shuffling/repeating values from one year to another, creating new time series for each time series. For example, January 1950 might be shifted to January 1990. This command is useful for generating synthetic time series by resequencing historical data. The following constraints apply to the command as currently implemented: 1. Processing by default occurs by calendar year, with the sequence specified as calendar years. If an alternate output year type is used (see the OutputYearType parameter). The OutputStart year is considered to be consistent with the output year type. 2. The sequence of years must currently be supplied as a column of years in a table (rows of years may be added in a future enhancement). 3. Full start and end years are required, matching the output year type. 4. Currently the command can only be applied to month interval data. For a daily data interval, several technical issues must be resolved before the feature can be implemented: a. If a short year (i.e., non-leap year with 365 days) is transferred to a long year (i.e., a leap year with 366 days), the first day after the short year is used for the 366th day during the transfer. What to do if the year being transferred is the last in the data set and no more years are available for the 366th day – repeat the last day? b. If a long year (i.e., leap year with 366 days) is transferred to a short year (i.e., a non-leap year with 365 days), the 366th day in the leap year is not transferred. 5. The original period is by default retained in the output time series. For example, if the original data are 1937 to 1997, the resequenced data will also be in a time series with a period 1937 to 1997. The OutputStart parameter can be used to shift the start year of output. The command is designed to work with a table that provides sequence information. For example, see the ReadTableFromDelimitedFile() command and the example shown below. 39 1 Command Reference – ResequenceTimeSeriesData() -1 ResequenceTimeSeriesData() Command TSTool Documentation The following dialog is used to edit the command and illustrates the syntax of the command. ResequenceTimeSeriesData ResequenceTimeSeriesData() Command Editor The command syntax is as follows: ResequenceTimeSeriesData(Parameter=Value,…) Command Parameters Parameter Description Default TSList Indicates the list of time series