TSTool-Vol2-CommandReference - Laserfiche WebLink

command reads one or more time series from a Reclamation HDB database: • a single time series (which can be part of an ensemble), indicated by the individual time series identifier: o a “real” time series (observations) o a “model” time series (output from a model) • all time series in an ensemble, indicated by the ensemble identifier: o ensemble trace time series are stored as “model” time series – individual ensemble trace time series can be queried by specifying the appropriate “hydrologic indicator” (which is set to the ensemble time series sequence number from TSTool time series) See the WriteReclamationHDB() command documentation for information about writing the time series that are read by this command. See the Reclamation HDB Data Store Appendix for more information about the database features and limitations. When reading a single time series or ensemble, the choices presented to the user cascade to allow only valid choices. 321 ReadReclamationHDB() Command TSTool Documentation Command Reference – ReadReclamationHDB() -2 The following dialog is used to edit the command and illustrates the syntax of the command when reading “real” or “model” data using filters. This approach can be used when reading one or more time series in bulk. Where criteria should be specified in sequential order without intervening blank specifiers. ReadReclamationHDB ReadReclamationHDB() Command Editor When Using Filters to Read 1+ Time Series 322 TSTool Documentation ReadReclamationHDB() Command Command Reference – ReadReclamationHDB() -3 The following figure illustrates reading a single “real” time series (note that the model parameters are not specified). ReadReclamationHDB_Real ReadReclamationHDB() Command Editor to Read a Single Real Time Series 323 ReadReclamationHDB() Command TSTool Documentation Command Reference – ReadReclamationHDB() -4 The following figure illustrates reading a single “model” time series, in which case model parameters are specified in addition to the site and data type parameters. ReadReclamationHDB_Model ReadReclamationHDB() Command Editor to Read a Single Model Time Series 324 TSTool Documentation ReadReclamationHDB() Command Command Reference – ReadReclamationHDB() -5 The following figure illustrates reading n ensemble of “model” time series, in which case ensemble/model parameters are specified in addition to the site and data type parameters. ReadReclamationHDB_Ensemble ReadReclamationHDB() Command Editor to Read an Ensemble of Model Time Series The command syntax is as follows: ReadReclamationHDB(Parameter=Value,…) Command Parameters Parameter Description Default DataStore Reclamation HDB data store name indicating database from which to read time series. None – must be specified. Interval The data interval to read (Hour, Day, Month, Year, Irregular). Irregular is used for instantaneous data and internally results in data with date/times to minute precision. 2Hour, 3Hour, 4Hour, 6Hour, 12Hour, and 24Hour can also be included, but how can HDB be queried to limit choices to these intervals? This interval is important because it tells TSTool how to allocate None – must be specified. 325 ReadReclamationHDB() Command TSTool Documentation Command Reference – ReadReclamationHDB() -6 Parameter Description Default memory for data values, and iterate through data. Use the following parameter when reading 1+ time series using filters DataType The data type to read as ObjectType – DataTypeCommonName. The object type is shown to help with selections. * can be specified to read all data types. None – must be specified. WhereN The “where” clauses to be applied when querying data, which match the values in the Where fields in the TSTool main interface. The parameters should be specified as Where1, Where2, etc., with no intervening gaps in numbering. All clauses are joined as “and” and are therefore cumulative in limiting the query. The format of each parameter value is: “Item;Operator;Value” Where Item indicates a data field to be filtered on, Operator is the type of constraint, and Value is the value to be checked when querying. If not specified, the query will not be limited and very large numbers of time series may result from the query (which may require a long time to perform the query). Use the following parameters when reading a single time series or an ensemble of time series. Site CommonName The site common name for the time series location; used with the data type common name to determine the site_datatype_id in the database. None – must be specified unless SiteDataTypeID is specified. DataType CommonName The data type common name for the time series; used with the site common name to determine the site_datatype_id in the database. None – must be specified unless SiteDataTypeID is specified. SiteDataTypeID The site_datatype_id value to match the time series. If specified, the value will be used instead of the site_datatype_id determined from SiteCommonName and DataTypeCommonName. Use the following parameters when reading a single model time series. ModelName The model name for the time series; used with the model run name, hydrologic indicator(s), and model run date to determine the model_run_id in the database. None – must be specified unless ModelRunID is specified. ModelRunName The model run name for the time series; used with the model name, hydrologic indicator(s), and model run date to determine the model_run_id in the database. None – must be specified unless ModelRunID is specified. ModelRunDate The model run date (timestamp) to use for the time series; used with the model name, model run name, None – must be specified unless 326 TSTool Documentation ReadReclamationHDB() Command Command Reference – ReadReclamationHDB() -7 Parameter Description Default and hydrologic indicator(s) to determine the model_run_id in the database. The run date should be specified using the format YYYY-MM-DD hh:mm (zero-padded with hour 0-23, minute 0-59, seconds and hundredths of seconds will default to 0). Need to implement tests to make sure this is properly handled, including formatting and listing existing values. ModelRunID is specified. Hydrologic Indicator The hydrologic indicator(s) to use for the time series; used with the model name, model run name, and model run date to determine the model_run_id in the database. None – must be specified unless ModelRunID is specified. ModelRunID The model_run_id value to match the time series. If specified, the value will be used instead of the model_run_id determined from ModelName , ModelRunName, ModelRunDate, and HydrologicIndicator. Use the following parameters when reading an ensemble of model time series. EnsembleName The name of the ensemble to write. The TSList=EnsembleID and EnsembleID parameters also should be specified. Must be specified if writing an ensemble. EnsembleTraceID Indicate how to identify time series trace identifiers. This parameter may be implemented in the future. The HDB trace number is used for the TSTool ensemble trace sequence number. EnsembleModelName The model name corresponding to the ensemble. Must be specified if writing an ensemble. EnsembleModel RunDate When writing an ensemble, the model run date for the ensemble, specified using format: • YYYY-MM-DD hh:mm (zero-padded with hour 0-23) • ${TS:property} – use a run date from a time series property, truncated to minute Need to implement tests to make sure this is properly handled, including formatting and listing existing values. If not specified, the ensemble identifier in HDB will not include the model run date. The following parameters are always appropriate. InputStart Start of the period to query, specified in format YYYY-MM-DD HH, with a precision appropriate for the interval. Read all available data. InputEnd End of the period to query, specified in format YYYY-MM-DD HH, with a precision appropriate for the interval. Read all available data. Alias Indicate an alias to assign to time series, which can result in shorter identifiers for time series when referenced with other commands. No alias is assigned. 327 ReadReclamationHDB() Command TSTool Documentation Command Reference – ReadReclamationHDB() -8 This page is intentionally blank. 328 Command Reference – ReadRiversideDB() -1 Command Reference: ReadRiversideDB() Read time series from a RiversideDB database Version 10.06.00, 2012-04-04 The ReadRiversideDB() command reads one or more time series from a RiversideDB database (see the Riverside Data Store Appendix for more information). It is designed to utilize query criteria to process large numbers of time series. The RiversideDB design is highly consistent with TSTool conventions and therefore time series properties in RiversideDB, including time series identifier information, map closely to TSTool internal data representations. The following dialog is used to edit the command and illustrates the syntax for the command. ReadRiversideDB ReadRiversideDB() Command Editor The Data type, Data interval, and Where input fields are similar to those from the main TSTool interface. However, whereas the interactive interface first requires a query to find the matching time series list and then an interactive select for specific time series identifiers, the ReadRiversideDB() command reads all matching time series in one step. This can greatly shorten command files and simplify command logic, especially when processing large amounts of data. It may be necessary to specify more criteria where a single time series is needed. 329 ReadRiversideDB() Command TSTool Documentation Command Reference – ReadRiversideDB() -2 The command syntax is as follows: ReadRiversideDB(Parameter=Value,…) Command Parameters Parameter Description Default DataStore The data store name, indicating the RiversideDB database to query. None – must be specified. DataType The data type to be queried, determined from time series that are available in the database. None – must be specified. Interval The data interval for the time series, determined from time series that are available in the database matching the DataType. None – must be specified. WhereN The “where” clauses to be applied when querying data, matching the values in the Where fields in the command editor dialog and the TSTool main interface. The parameters should be named Where1, Where2, etc., with a gap resulting in the remaining items being ignored. The format of each value is: “Item;Operator;Value” Where Item indicates a data field to be filtered on, Operator is the type of constraint, and Value is the value to be checked when querying. If not specified, the query will not be limited and very large numbers of time series may be queried. InputStart Start of the period to query, specified as a date/time with a precision that matches the requested data interval. Read all available data. InputEnd End of the period to query, specified as a date/time with a precision that matches the requested data interval. Read all available data. 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). MissingValue Value to use to indicate missing data values within the time series. -999 is the default for historical reasons; however, NaN (not a number) is being phased in and should be specified if possible. Null values in the database will be converted to the missing data value. -999 330 Command Reference: ReadRiverWare() Read a single time series from a RiverWare file Version 10.00.00, 2011-03-28 The ReadRiverWare() command reads a single time series from a RiverWare file (see the RiverWare Input Type Appendix) and assigns an alias to the result. The following dialog is used to edit the command and illustrates the command syntax. ReadRiverWare ReadRiverWare() Command Editor 331 Command Reference – ReadRiverWare() -1 ReadRiverWare() Command TSTool Documentation The command syntax is as follows: ReadRiverWare(Parameter=Value,…) The following older command syntax is updated to the above syntax when a command file is read: TS Alias = ReadRiverWare(Parameter=Value,…) Command Parameters Parameter Description Default InputFile The name of the RiverWare 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. Units The units for the time series. The data values will be converted to these units. TSTool by default understands certain units abbreviations and attempting to convert to or from unknown units may not be possible. The ability to handle user-defined units is being evaluated. See the Scale() and ConvertDataUnits() commands. Use the units read from the file. This parameter is not yet enabled. 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: ReadRiverWare(Alias=”ts1”,InputFile="SouthHolstonData.SOGPoolElevation") Command Reference – ReadRiverWare() -2 332 Command Reference: ReadStateCU() Read time series from a StateCU time series or report File Version 09.07.02, 2010-08-20 The ReadStateCU() command reads all the time series in a StateCU time series file (e.g., frost dates) or report file (e.g., IWR, WSL) (see the StateCU Input Type Appendix). The following dialog is used to edit the command and illustrates the syntax for the command. ReadStateCU ReadStateCU() Command Editor 333 Command Reference – ReadStateCU() -1 ReadStateCU() Command TSTool Documentation The command syntax is as follows: ReadStateCU(Parameter=Value,…) Command Parameters Parameter Description Default InputFile The name of the StateCU time series or report file to read, surrounded by double quotes. None – must be specified. InputStart The starting date/time to read, specified to a precision (month or year) that matches the data file. Read all the data. InputEnd The ending date/time to read, specified to a precision (month or year) that matches the data file. Read all the data. TSID A time series identifier pattern that will be used to filter the list of time series that are read. See the figure above for examples. Read all time series. NewScenario A new scenario to use for the TSID. This is useful when reading data from multiple model runs that otherwise would have the same TSIDs. No scenario. AutoAdjust Indicate whether to automatically adjust time series identifiers to use a dash “-” instead of period “.” in the data type, necessary because StateCU data types (e.g., crop types that include CU method) have a period that interferes with the normal TSID convention. True CheckData Indicate whether to check the data for integrity after reading. Currently only the irrigation practice time series can be checked, to verify that the acreage totals are the sum of the parts. True A sample commands file is as follows: ReadStateCU(InputFile="Data\ym2004.iwr") Command Reference – ReadStateCU() -2 334 Command Reference: ReadStateCUB() Read time series from a StateCU binary output time series file Version 08.17.00, 2008-10-02 The ReadStateCUB() command reads time series from a StateCU binary output time series file (see the StateCUB Input Type Appendix). The actual reading occurs as the commands are being processed. For this reason and because the number of time series in the binary file is usually large, if any other commands reference the StateCU binary file time series, the time series identifiers must be specified manually or use wildcards in identifiers (identifiers are not available to list in dialogs). Only data types that contain floating point numbers will be read. The following dialog is used to edit the command and illustrates the syntax for the command. ReadStateCUB ReadStateCUB() Command Editor 335 Command Reference – ReadStateCUB() -1 ReadStateCUB() Command TSTool Documentation The command syntax is as follows: ReadStateCUB(Parameter=Value,…) Command Parameters Parameter Description Default InputFile The name of the StateCU binary time series 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. TSID Time series identifier pattern to filter the read. Read all time series. InputStart The starting date/time to read data, specified to Month precision. Read all data. InputEnd The ending date/time to read data, specified to Month precision. Read all data. The following example command file illustrates how to read all CU Shortage time series: ReadStateCUB(InputFile="Data\farmers.BD1",TSID="*.*. CU Shortage.*.*") The following example illustrates how to read all time series from a binary file with debug turned on to echo all information that is read. StartLog(LogFile="commands.TSTool.log") SetDebugLevel(LogFileLevel=1) ReadStateCUB(InputFile="Data\farmers.BD1") Command Reference – ReadStateCUB() -2 336 Command Reference: ReadStateMod() Read all the time series from a StateMod time series file Version 09.05.03, 2009-11-17 The ReadStateMod() command reads all the time series in a StateMod time series file (see the StateMod Input Type Appendix). Single time series can be read by using time series identifier (TSID) commands. Water rights files also can be read and converted to time series – this is useful for visualization, water supply analysis, and is used to test well right processing. Considering all water rights for a location based on the administration number results in a step function of decree over time. Monthly and yearly time series use calendar year and a right is active if it is turned on anywhere in the month or year. Free water rights (e.g., those having administration numbers > 90000.00000 are treated like other rights and therefore may not impact the results in the current period because the corresponding appropriation date is in the future (additional parameters may be added in the future to allow more ways to process these rights). If processing well rights and multiple years of parcel data are processed, this command executes the same logic as the StateDMI MergeWellRights() command. The following dialog is used to edit the command and illustrates the syntax for the command. ReadStateMod ReadStateMod() Command Editor 337 Command Reference – ReadStateMod() -1 ReadStateMod() Command TSTool Documentation The command syntax is as follows: ReadStateMod(Parameter=Value,…) Command Parameters Parameter Description Default InputFile The name of the StateMod time series file to read, surrounded by double quotes. The path to the file can be absolute or relative to the working directory. Global property values can be inserted using the syntax ${PropertyName} (see also the SetProperty() command). 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. Specify to a precision that matches the data. If reading water rights, the output time series will start on this date. Use the global query period or if not specified read all data. The default for water rights is the date of the first right. InputEnd The end of the period to read data – specify if the period should be different from the global query period. Specify to a precision that matches the data. If reading water rights, the output time series will end on this date. Use the global query period or if not specified read all data. The default for water rights is the date of the last right. Alias The alias to assign to the time series that are read. Use the format choices and other characters to define a unique alias. No alias is assigned. Interval When reading a water right file, specify the interval for the resulting time series, one of Day, Month, or Year. Year Spatial Aggregation When reading a water right file, indicate how time series are to be aggregated spatially, one of: • Location – aggregate by the station identifier. • Parcel – (only used with well rights) aggregate based on the parcel number and parcel year. • None – do not aggregate spatially, which will result in constant value time series for each water right. Location ParcelYear When processing a well water right file, indicate the year of parcel data to process. Parcel configurations change from year to year, and a single year of parcel data can be processed if desired. Process all parcel years. A sample command file is as follows: ReadStateMod(InputFile="ym2004.ddh") Command Reference – ReadStateMod() -2 338 Command Reference: ReadStateModB() Read time series from a StateMod binary output time series file Version 09.06.00, 2010-01-05 The ReadStateModB() command reads time series from a StateMod binary output time series file (see the StateModB Input Type Appendix). The identifiers (or aliases) from the time series will be available as choices when editing other commands. If this causes performance issues due to the large number of time series that may be read, limit the time series that are read using the TSID parameter. The following dialog is used to edit the command and illustrates the syntax for the command. ReadStateModB ReadStateModB() Command Editor 339 Command Reference – ReadStateModB() -1 ReadStateModB() Command TSTool Documentation The command syntax is as follows: ReadStateModB(Parameter=Value,…) Command Parameters Parameter Description Default InputFile The name of the StateMod binary time series file to read, surrounded by double quotes. The path to the file can be absolute or relative to the working directory. Global property values can be inserted using the syntax ${PropertyName} (see also the SetProperty() command). None – must be specified. TSID Time series identifier pattern to filter the read. Use periods to indicate separate TSID parts and use * to match patterns within the parts. Read all time series. InputStart The starting date/time to read data, specified to Day or Month precision based on whether a daily or monthly model run. Read all data. InputEnd The ending date/time to read data, specified to Day or Month precision based on whether a daily or monthly model run. Read all data. Version StateMod version number using the form NN.NN (padded with leading zero for version 9) corresponding to the file, necessary because the file version number (and consequently parameters) cannot be automatically detected in older versions. Changes in binary file format occurred with version 9.01 and 9.69, mainly to add new data types. The StateMod file version for version 11+ is automatically detected. Detect from the file if possible. Alias The alias to assign to the time series that are read. Use the format choices and other characters to define a unique alias. No alias is assigned. The following example command file illustrates how to read all Available_Flow time series for identifiers starting with 44 (e.g., to extract all such time series for a water district): ReadStateModB(InputFile="..\StateMod\ym2002b.b43",TSID="44*.*.Available_Flow.*") The following example illustrates how to read all time series from a binary file that was created with StateMod version 9.53. As shown in the example, debug can be turned on for the log file to evaluate issues with the file format. StartLog(LogFile="commands.TSTool.log") SetDebugLevel(0,1) ReadStateModB(InputFile="COLOFB.B43",Version="09.53") Command Reference – ReadStateModB() -2 340 Command Reference – ReadTableFromDataStore() -1 Command Reference: ReadTableFromDataStore() Read a table from a datastore Version 10.21.00, 2013-06-21 The ReadTableFromDataStore() command executes a database query for a datastore that is associated with a database, and places the result in a TSTool table, which can subsequently be processed with other TSTool commands. This command cannot be used with web service datastores because the underlying software relies on a database to perform the query. If database datastore support is not specifically provided by TSTool, a generic datastore can be used (see the Generic Database DataStore appendix). This command is useful when the database can provide results with a simple query and tight integration with TSTool is not required or has not been implemented. The query can be specified in the following ways: • Specify a single table/view to query: o the list of tables is filtered to remove internal database tables; however, this capability varies by database product and in some cases internal tables will be listed o the query is constructed from the provided database table/view name and column names o the output can be sorted by specifying column names o “where” clauses currently are not supported but may be added in the future o the top N rows of the result can be returned to allow “peeking” at tables (may not be available for all database software) • Specify a SQL select statement: o SQL must be valid for the database (syntax may vary based on database software) o Use ${Property} notation to insert processor property values set with SetPropety(). o SQL syntax is not checked for validity and therefore error messages from the database may be more difficult to interpret • Specify an SQL select statement in a file: o Similar to the above option; however, the SQL statement is read from a file o Useful if the SQL statement is also used by other tools • Specify a procedure to run: o Available procedures are listed and can be selected o Currently, only procedures that do not require parameters can be run General constraints on the query are as follows: • the table, views, and procedures being queried must be readable (some databases restrict direct access to data and require using stored procedures) • the resulting table in TSTool will have columns with names that match the database query results • data types for columns will closely match the database results: o data will be treated as strings if unable to match the database column type o the precision of floating point numbers for displays is defaulted to 6 digits o null values in the database will transfer to null values in the TSTool table and will display as blank table cells o date/time columns in the database will be represented as such in the TSTool table; however, it may not be possible to limit the precision of the date/time (i.e., hours, minutes, and seconds may be shown with default zero values in output) 341 ReadTableFromDataStore() Command TSTool Documentation Command Reference – ReadTableFromDataStore() -2 Future enhancements will add additional features to intelligently map database results to TSTool tables. The following dialog is used to edit the command and illustrates the syntax for the command, in this case reading a small table from the State of Colorado’s HydroBase. ReadTableFromDataStore_Table ReadTableFromDataStore() Command Editor When Querying a Single Table The corresponding output table is as shown below: ReadTableFromDataStore_Results Example ReadTableFromDataStore() Command Output Table 342 TSTool Documentation ReadTableFromDataStore() Command Command Reference – ReadTableFromDataStore() -3 The following example illustrates using an SQL query string, in this case to read diversion records for a specific structure in HydroBase: ReadTableFromDataStore_SQL ReadTableFromDataStore() Command Editor When Specifying a SQL Query String 343 ReadTableFromDataStore() Command TSTool Documentation Command Reference – ReadTableFromDataStore() -4 The command syntax is as follows: ReadTableFromDataStore(Parameter=Value,…) Command Parameters Parameter Description Default DataStore The name of a database datastore to read. None – must be specified. DataStoreTable The name of the database table or view to read when querying a single table or view. If specified, do not specify Sql or SqlFile. None. DataStoreColumns When reading a single table/view, the names of the columns to read, separated by commas. All columns from DataStoreTable are read. OrderBy When reading a single table/view, a list of column names separated by commas to control the order of output. Default database