TSTool-Vol2-CommandReference - Laserfiche WebLink

DISCHRG", SkipRowsAfterComments="1",LocationID="ADATUNCO",Provider="DWR", DataType="GAGE_HT,DISCHRG",Interval=15Minute,Units="ft,cfs",Alias="%L%T") Example of Column Names Read from the File The following simple example of annual county population data illustrates a format that allows reading column names from the file. In this case, the rows and columns have been transposed from the original format to be compatible with this command and in the command example shown in the figure below the “County” heading is replaced with “Year” to more clearly indicate the contents. County,COLORADO,Adams,Alamosa,Arapahoe,Archuleta,Baca,Bent,Boulder,Broomfield,Chaffee,… 2000,4338793,366660,15132,491134,10027,4514,5991,296018,0,16294,2229,9386,… 2001,4456408,360389,15314,502567,10532,4486,5911,282794,41529,16382,2195,9479,… …etc.. The following dialog is used to edit the command and illustrates the syntax for the command. ReadDelimitedFile2 ReadDelimitedFile() Command Editor when Reading Column Names from the File 299 ReadDelimitedFile () Command TSTool Documentation Command Reference – ReadDelimitedFile () -6 The following example command file retrieves population forecast data from the State of Colorado’s website, transposes the rows and columns using a Python script, and reads the time series data. The Python script is not provided with this example but generates output as shown in the above data file example. StartLog(LogFile="DOLA-county-pop.TSTool.log") # This command file retrieves population data from the Colorado State Demographer # website and processes the data into time series for use in analysis. # # First retrieve the data from the DOLA web site. WebGet(URI="http://www.dola.state.co.us/dlg/demog/population/forecasts/counties1yr.csv", LocalFile="DOLA-counties1yr.csv") # # Transpose the rows/columns to match TSTool time series notation with dates in the # first column. SetProperty(PropertyName="ScriptDir",PropertyType=String, RunPython(InputFile="${InstallDir}\python\table\transpose-csv.py", Arguments="\"${WorkingDir}\DOLA-counties1yr.csv\" \"${WorkingDir}\DOLA-counties1yr-trans.csv\"",Interpreter="Python") # # Read into time series from the delimited CSV file. # Define column names dynamically based on the first non-comment line in the file ReadDelimitedFile(InputFile="DOLA-counties1yr-trans.csv",Delim iter=",", ColumnNames="Year,FC[2:]",DateTimeColumn="Year",ValueColumn="FC[2:]", LocationID="FC[2:]",Provider="DOLA",DataType="Population",Interval=Year,Units="Persons", Alias="%L-pop") 300 Command Reference: ReadHecDss() Read time series from a HEC-DSS File Version1 0.00.01, 2011-05-15 The ReadHecDss() command reads time series from a HEC-DSS file. See the HEC-DSS Input Type Appendix for information about how time series properties are assigned using HEC-DSS file data. Current limitations for the command include: • Irregular time series cannot be read. • HEC-DSS uses times through 2400. However, TSTool will convert this to 0000 of the next day. Year, month, and day data are not impacted. The following dialog is used to edit the command and illustrates the syntax for the command. In the future, it is envisioned that choices for A – F parts will be made available using data from the file. ReadHecDss ReadHecDss() Command Editor 301 Command Reference – ReadHecDss() -1 ReadHecDss() Command TSTool Documentation The command syntax is as follows: ReadHecDss(Parameter=Value,…) Command Parameters Parameter Description Default InputFile The name of the HEC-DSS input file to read, surrounded by double quotes to protect whitespace and special characters. None – must be specified. A The A part (basin name) to match, using * as a wildcard. The location part of the TSTool time series identifier is set to A:B. Match all. B The B part (location) to match, using * as a wildcard. The location part of the TSTool time series identifier is set to A:B. Match all. C The C part (parameter) to match, using * as a wildcard. The TSTool data type is set to this value. Match all. E The E part (interval) to match, using * as a wildcard. Match all. F The F part (scenario) to match, using * as a wildcard. Match all. Pathname The HEC-DSS pathname for a time series, as specified in the HEC-DSS documentation. Currently wildcards are not allowed. If specified, this will be used instead of the A-F parameters. Use the A-F parameters. InputStart Starting date/time to read data, in precision consistent with data. Read all data. InputEnd Ending date/time to read data, in precision consistent with data. Read all data. Location The location to assign for the time series identifier. Use %A … %F to indicate the Apart … Fpart (D part is not available). The assignment will impact the Alias assignment. This is useful when only Bpart is desired as the location identifier. Apart:Bpart (%A:%B). Alias Alias to assign to the output time series. See the LegendFormat property described in the TSView Time Series Viewing Tools appendix. For example, %L is full location, %T is data type (parameter in HECDSS notation), %I is interval, and %Z is scenario. None is assigned. However, if the location contains periods that are in conflict with time series identifier conventions, the alias is set to the identifier with periods, and the periods are replaced with spaces in the full time series identifier. A sample command file is as follows: ReadHecDss(InputFile="sample.dss",InputStart="1992-01-01", InputEnd="1992-12-31",Alias="%L_%T_%Z") Command Reference – ReadHecDss() -2 302 Command Reference – ReadHydroBase() -1 Command Reference: ReadHydroBase() Read time series from a HydroBase database Version 10.12.00, 2012-09-28 The ReadHydroBase() command reads one or more time series from the HydroBase database (see the HydroBase Datastore Appendix). It is designed to utilize query criteria to process large numbers of time series, for example for a specific water district and data type. The Data type, Data interval, and Where command parameters and input fields are similar to those from the main TSTool interface. However, whereas the main TSTool interface first requires a query to find the matching time series list and then an interactive select for specific time series identifiers, the ReadHydroBase() command reads the time series list and the corresponding data for the time series. This can greatly shorten command files and simplify command logic, especially when processing many time series. The command supports the old-style input name selection (which corresponds to selecting HydroBase via the TSTool login dialog) and the new-style datastore convention (which corresponds to datastore configuration files). In the future, support for the input name may be phased out; however, this will require resolving how the HydroBase selection dialog is migrated to support datastores. Consequently, both approaches are currently supported during the transition. Data for the location (station, structure, well, etc.) and time series metadata, as shown in the main TSTool interface, are set as time series properties. For example, the latdecdeg and longdecdeg values from the HydroBase vw_CDSS_StationMeasType view are available as time series properties of the same name. These properties can be transferred to a table with the CopyTimeSeriesPropertiesToTable() command and processed further with other table commands. Time series corresponding to diversion records, which also include observations for reservoirs and wells, are handled as follows: 1. Daily diversion (DivTotal and DivClass) and reservoir release (RelTotal and RelClass) time series have their values automatically carried forward to fill data within irrigation years (November to October). HydroBase only stores full months of daily diversion record data when nonzero observations or non-zero filled values occur in a month. Therefore, this filling action should only provide additional zero values in an irrigation year where a diversion or release was recorded. Irrigation years with no observations remain as missing after the read. 2. Daily, monthly, and yearly diversion and reservoir release time series optionally can be filled by the ReadHydroBase() command using diversion comments, which indicate when irritation years should be treated as missing. See the FillUsingDivComments parameter below. Note that diversion comments should not conflict with more detailed records and provide additional information. The separate FillUsingDivComments() command also is available for filling but may be phased out in the future. 3. It also may be appropriate to use infrequent data types (IDivTotal, IDivClass, IRelTotal, and IRelClass) to supply data; however, because such values typically are annual values, additional decisions must be made for how to distribute the values to monthly and daily time series. These data, if available, are not automatically folded into the diversion records by TSTool. 303 ReadHydroBase() Command TSTool Documentation Command Reference – ReadHydroBase() -2 4. See the FillHistMonthAverage(), FillPattern(), and other commands, which can be used to fill (estimate) values in data gaps after the initial time series are read. The following dialog is used to edit the command and illustrates the syntax for the command. Two options are available for matching time series, based on historical software requirements. The following example illustrates how to read a single time series by specifying the time series identifier. This approach is essentially equivalent to using the ReadTimeSeries() command but offers HydroBase-specific parameters such as FillUsingDivComments, which are not available in the more general ReadTimeSeries() command. ReadHydroBase_TSID ReadHydroBase() Command Editor to Read a Single Time Series 304 TSTool Documentation ReadHydroBase() Command Command Reference – ReadHydroBase() -3 The following figure illustrates how to query multiple time series. ReadHydroBase_Multiple ReadHydroBase() Command Editor to Read Multiple Time Series The command syntax is as follows: ReadHydroBase(Parameter=Value,…) The following older command syntax is updated to the above syntax when a command file is read: TS Alias = ReadHydroBase(Parameter=Value,…) 305 ReadHydroBase() Command TSTool Documentation Command Reference – ReadHydroBase() -4 Command Parameters Parameter Description Default InputName The HydroBase database connection input name to use for the database connection, as initialized by the OpenHydroBase()command or the HydroBase login dialog shown when TSTool starts. When using this approach the TSID will end in ~HydroBase~InputName. The input name approach for specifying a HydroBase database connection may be phased out in the future in favor of the datastore approach. Use the default HydroBase connection. DataStore The HydroBase datastore name to use for the database connection, as per datastore configuration files (see HydroBase Datastore appendix). When using this approach the TSID will end in ~DataStore. The datastore approach is being phased in as a more flexible design. Configuring a datastore with name HydroBase will take precedence over InputName=HydroBase. Use the default (legacy InputName) HydroBase connection, if available. DataType The data type to be queried, as documented in the HydroBase Datastore appendix. None – must be specified. Interval The data interval for the time series, as documented in the HydroBase Datastore appendix (e.g. Day, Month, Year), consistent with the DataType selection. None – must be specified. TSID When reading a single time series, the time series identifier to read. If specified, this parameter will override the WhereN parameters. Use WhereN parameters to read multiple time series. WhereN When reading 1+ time series, the “where” clauses to be applied. The filters matche 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. 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 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. FillUsing DivComments Indicate whether to fill diversion and reservoir release time series using diversion comments. False FillUsing DivComments Flag If specified as a single character, data flags will be enabled for the time series and each filled value will be tagged 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. 306 TSTool Documentation ReadHydroBase() Command Command Reference – ReadHydroBase() -5 Parameter Description Default IfMissing Indicate the action to be taken if the requested time series is missing, one of: • Ignore – ignore the time series (do not warn and the time series will not be available) • Warn – generate a failure for the command Warn A sample command file is as follows (read all reservoir releases to structure 0300905): ReadHydroBase(DataType="DivClass",Interval="Day", Where1="District;Equals;3", Where2="Structure ID;Equals;905",Where3="SFUT;Contains;s:2 ") 307 ReadHydroBase() Command TSTool Documentation Command Reference – ReadHydroBase() -6 This page is intentionally blank. 308 Command Reference: ReadMODSIM() Read time series from a MODSIM output file Version 10.00.00, 2011-03-28 The ReadMODSIM() command reads one or more time series from a MODSIM file. MODSIM is a node/link model used to simulate river basins (see the MODSIM Input Type Appendix). Specify a node/link name and data type to read a single time series – if not specified all time series from the file will be read. An alias can be assigned to each time series. The following dialog is used to edit the command and illustrates the syntax. When a file is selected, the available data types are listed, based on the file extension (the types are not read from the file). ReadMODSIM ReadMODSIM() Command Editor 309 Command Reference – ReadMODSIM() -1 ReadMODSIM() Command TSTool Documentation The command syntax is as follows: ReadMODSIM(Parameter=Value,…) The following older command syntax is updated to the above syntax when a command file is read: TS Alias = ReadMODSIM(Parameter=Value,…) Command Parameters Parameter Description Default InputFile The name of the MODSIM 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 A time series identifier pattern to filter the read – this is constructed in the editor dialog from individual identifier parts – the location and data type are specified and used in the time series identifier. None – must be specified to match a single time series. 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: ReadMODSIM(Alias=”BIGTOM”, InputFile="BIGTOM17.RES",TSID="GREELEYCBT..STOR_TRG..") Command Reference – ReadMODSIM() -2 310 Command Reference – ReadNrcsAwdb() -1 Command Reference: ReadNrcsAwdb() Read 1+ time series from the NRCS AWDB web service Version 10.13.00, 2012-11-07 The ReadNrcsAwdb() command reads one or more time series from the Natural Resources Conservation Service (NRCS) Air and Water Database (AWDB) web service (see the NRCS AWDB Datastore Appendix), including SNOTEL and Snow Course data. The NRCS AWDB web service allows station lists to be filtered, both as a convenience and to ensure 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 element (data type) will return all available elements for a location. Specifying a list of elements (separated by commas) will return only stations and time series that have data for the requested elements. 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 HUCs) is not provided due to performance issues. Additional query features will be enabled as web service integration is enhanced. ReadNrcsAwdb ReadNrcsAwdb() Command Editor 311 ReadNrcsAwdb() Command TSTool Documentation Command Reference – ReadNrcsAwdb() -2 The command syntax is as follows: ReadNrcsAwdb(Parameter=Value,…) Command Parameters Parameter Description Default DataStore The NRCS AWDB datastore to use for queries. None – must be specified. Interval The data interval (“duration” in NRCS AWDB terms) to query. The Irregular interval is used for instantaneous data. None – must be specified. Stations A list of station identifiers to read, separated by commas. Do not limit the query to a station list. States A list of state codes (e.g., AL), separated by commas. Do not limit the query to a state list. Networks A list of data network codes (e.g., SNTL), separated by commas. Do not limit the query to a network list. HUCs A list of 8-digit hydrologic unit codes, separated by commas. Do not limit the query to a HUC list. 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. This feature is not finalized, pending resolution of a web service issue. Do not limit the query to a bounding box. Counties A list of county names, separated by commas. The state must be specified. Do not limit the query to a county list. Elements Data element codes for the stations (e.g., WTEQ for snow water equivalent), separated by commas. All available elements are returned. ElevationMin Minimum station elevation, feet. Do not limit the query based on elevation minimum. ElevationMax Maximum station elevation, feet. Do not limit the query based on elevation maximum. InputStart The start of the period to read data – specify if the period should be different from the global query period. Specify to the precision of the data using the format YYYY-MM-DD hh:mm. 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. Specify to the precision of the data using the format YYYY-MM-DD hh:mm. 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 alternative to the time series identifier (TSID). None – must be specified. 312 Command Reference: ReadPatternFile() Read the pattern file to be used with FillPattern() commands Version 08.16.04, 2008-09-19 The ReadPatternFile() command reads pattern time series to be used with FillPattern() commands (see the FillPattern() command for more information ). The patterns indicate whether a month is wet, dry, or average, although any number of characterizations can be used. One or more patterns can be included in each pattern file, similar to StateMod time series files (see the StateMod Input Type appendix), and multiple pattern files can be used, if appropriate. The following example illustrates the file format. See also the AnalyzePattern() command, which can be used to generate the file. # Years Shown = Water Years # Missing monthly data filled by the Mixed Station Method, USGS 1989 # Time series identifier = 09034500.CRDSS_USGS.QME.MONTH.1 # Description = COLORADO RIVER AT HOT SULPHUR SPRINGS, CO. # -e-b----------eb------eb------eb------eb------eb------eb------eb------eb------eb------eb------eb------eb------eb--------e 10/1908 -9/1996 ACFT WYR 1909 09034500 AVG AVG AVG WET WET AVG AVG AVG WET WET WET WET 1910 09034500 WET WET WET WET WET WET AVG AVG AVG AVG AVG AVG 1911 09034500 AVG AVG WET AVG AVG AVG AVG WET WET WET AVG WET 1912 09034500 WET WET WET WET WET AVG AVG WET WET WET WET WET ...ommitted... The following dialog is used to edit the command and illustrates the command syntax. ReadPatternFile ReadPatternFile() Command Editor The command syntax is as follows: ReadPatternFile(Parameter=Value,…) Command Parameters Parameter Description Default PatternFile The path to the pattern file, which can be absolute or relative to the working directory. None – must be specified. A sample command file is as follows: ReadPatternFile(PatternFile="fill.pat") 313 Command Reference – ReadPatternFile() -1 ReadPatternFile() Command TSTool Documentation This page is intentionally blank. Command Reference – ReadPatternFile() -2 314 Command Reference – ReadPropertiesFromFile -1 Command Reference: ReadPropertiesFromFile() Read one or more time series processor properties from a file Version 10.12.00, 2012-08-02 The ReadPropertiesToFile() command reads the values of one or more time series processor properties from a file. The corresponding WritePropertiesToFile() command can be used to write properties to a file. Processor properties include global defaults such as InputStart, InputEnd, OutputStart, OutputEnd, OutputYearType, WorkingDir, and also user-defined properties set with the SetProperty() command. Internally, properties have a name and a value, which is of a certain type (string, integer, date/time, etc.). Examples of using the command include: • creating tests to verify that properties are being set • passing information from another program, such as a Python script, to TSTool • reading persistent information from a previous use, such as the date/time that data were last downloaded from a web service A number of property formats are supported as listed in the following table. Property File Formats Format Description NameValue Simple format, all properties handled as text: PropertyName=PropertyValue PropertyName=”Property value, quoted if necessary” NameTypeValue Same as NameValue format, with non-primitive objects treated as simple constructors: PropertyName=PropertyValue DateTimeProperty=DateTime(“2010-10-01 12:30”) NameTypeValue Python Similar to the NameTypeValue format, however, objects are represented using “Pythonic” notation, to allow the file to be used directly by Python scripts: PropertyName=”PropertyValue” DateTimeProperty=DateTime(2010,10,1,12,30) The format of the file currently is not required when reading the file because the command detects the format for each property and creates an appropriate object type. If this becomes an issue, the command may be enhanced to add a parameter to specify the format (similar to the WritePropertiesToFile() command). 315 ReadPropertiesFromFile() Command TSTool Documentation Command Reference – ReadPropertiesFromFile() -2 The following dialog is used to edit this command and illustrates the syntax of the command. ReadPropertiesFromFile ReadPropertiesFromFile() Command Editor The command syntax is as follows: ReadPropertiesFromFile(Parameter=Value,…) Command Parameters Parameter Description Default InputFile The property file to read, as an absolute path or relative to the command file. None – must be specified. IncludeProperty The names of properties to read, separated by commas. If not specified, all processor properties will be written. 316 Command Reference – ReadRccAcis() -1 Command Reference: ReadRccAcis() Read time series from the RCC ACIS web services Version 10.11.00, 2012-06-28 The ReadRccAcis() command reads one or more time series from the Regional Climate Center (RCC) Applied Climate Information System (ACIS) web services, in particular to provide access to daily historical and real-time values from the National Climatic Data Center (NCDC). Features and limitations of ACIS are described in the RCC ACIS Data Store appendix. Because web services are used to access a remote database, there may be some delay in retrieving data. For data intensive processes, it may be advisable to mine the data, save to a local file or database, and then perform additional processing using the local data. The following dialog is used to edit the command and illustrates the syntax for the command when reading a single time series. This is appropriate when a specific site is being processed. ReadRccAcis_Single ReadRccAcis() Command Editor for Reading Single Time Series 317 ReadRccAcis() Command TSTool Documentation Command Reference – ReadRccAcis() -2 The following dialog is used to edit the command and illustrates the syntax for the command when reading multiple time series. This is appropriate when performing bulk processing. Mouse over the Where data entry fields to see information about choices. ReadRccAcis ReadRccAcis() Command Editor for Reading Multiple Time Series The command syntax is as follows: ReadRccAcis(Parameter=Value,…) Command Parameters Parameter Description Default DataStore The name of the RCC ACIS data store from which to read. None – must be specified. DataType The data type to be queried, as documented in the RCC ACIS Data Store appendix. For example, use pcpn to request precipitation data (for the older version 1 ACIS, the “Variable Major” number is used, for example 4 for precipitation). None – must be specified. Interval The data interval for the time series. Currently only daily time series can be requested. None – must be specified. SiteID Used when reading a single time series. The site ID should be specified using the station type and site identifier (e.g., COOP:052454). The station type can be determined by first querying the time series using the TSTool main interface or using the WhereN parameter and reviewing the resulting time series identifiers in returned time series. Omitting the station type will assume the If not specified, the WhereN filters are used. 318 TSTool Documentation ReadRccAcis() Command Command Reference – ReadRccAcis() -3 Parameter Description Default ACIS identifier, which is internal to the ACIS system and not typically used by users. Specifying the SiteID will override the WhereN parameter. WhereN Used when reading 1+ time series. The “where” clauses to be applied to filter the list of stations, 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., and a gap in numbering will result 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). None – must be specified. 319 ReadRccAcis() Command TSTool Documentation Command Reference – ReadRccAcis() -4 This page is intentionally blank. 320 Command Reference – ReadReclamationHDB() -1 Command Reference: ReadReclamationHDB() Read time series from a Reclamation HDB database Version 10.20.00, 2013-04-21 The ReadReclamationHDB()