Skip to content

TSTool / Command / ReadTimeSeriesList

Overview

The ReadTimeSeriesList command reads one or more time series using location identifiers from a table, an example of which is shown below as a comma-separated value file (tables can also be read from Excel, delimited file, datastore, or other source):

# Example list file.  Comments start with the # character.
# Column headings can be specified in the first non-comment row using quotes.
“Structure ID”,”Structure Name”
500501,Ditch 501
500502,Ditch 502
# Invalid ID (see IfNotFound parameter)
509999,Ditch 9999

The command typically is used when reading time series from a single source and can streamline processing in the following situations:

  • A list of identifiers may have been generated from a database query
  • A list of identifiers may have been extracted from a model data set

TSTool uses the location identifiers in the table with the command parameters and internally creates a list of time series identifiers. The time series are of the standard form (information in brackets is optional for basic use):

[LocationType:]Location.DataSource.DataType.Interval[.Scenario]~DataStore[~InputName]

TSTool then queries each time series using the time series identifier. See also the ReadTimeSeries command, which performs essentially the same functionality but only reads one time series. Refer to the appendices for each datastore and file input type to understand specific time series identifier conventions.

Although it is possible to specify a datastore or input type that reads from files by also using the InputName parameter, this may not be appropriate because the ReadTimeSeriesList command can only specify one input file name and the file will be reopened for each time series read. Instead, read commands for specific file formats should be used because these commands typically are optimized to read multiple time series from the files. Use the SetInputPeriod command to set the period to read.

Command Editor

The following dialog is used to edit the command and illustrates the syntax of the command for time series identifier parts.

ReadTimeSeriesList

ReadTimeSeriesList Command Editor for Time Series Identifier Parts Parameters (see also the full-size image)

The following dialog is used to edit the command and illustrates the syntax of the command for time series properties.

ReadTimeSeriesList TimeSeriesProperties

ReadTimeSeriesList Command Editor for Time Series Propeties Parameters (see also the full-size image)

The following dialog is used to edit the command and illustrates the syntax of the command for parameters if the time series is not found.

ReadTimeSeriesList IfNotFound

ReadTimeSeriesList Command Editor for Parameters if Time Series is Not Found (see also the full-size image)

The following dialog is used to edit the command and illustrates the syntax of the command for parameters used in checks.

ReadTimeSeriesList Check

ReadTimeSeriesList Command Editor for Parameters Used in Checks (see also the full-size image)

Command Syntax

The command syntax is as follows:

ReadTimeSeriesList(Parameter="Value",...)

Command Parameters

Parameter                                                Description Default                           
TableID
required		 The identifier for the table that provides the list of location identifiers. Can be specified using processor ${Property}. None – must be specified.
LocationTypeColumn The column in the table containing the location type to use in time series identifiers. Specify LocationTypeColumn or LocationType. May or may not be required, depending on the datastore or input type.
LocationType The location type in the time series identifier. Specify LocationTypeColumn or LocationType. May or may not be required, depending on the datastore or input type.
LocationColumn
required		 The column in the table containing the location identifiers to use in time series identifiers. None – must be specified.
DataSourceColumn The column in the table containing the data source to use in time series identifiers. Specify DataSourceColumn or DataSource. May or may not be required, depending on the datastore or input type.
DataSource The data source(s) in the time series identifier, separated by commas. For example, if using the State of Colorado’s HydroBase, USGS indicates that data are from the United States Geological Survey and DWR are from the Division of Water Resources. If multiple data sources are specified, each will be tried until a time series is found. This is enabled because sometimes data collection sites change ownership. Specify DataSourceColumn or DataSource. May or may not be required, depending on the datastore or input type
DataTypeColumn The column in the table containing the data type to use in time series identifiers. Specify DataTypeColumn or DataType. Data type is often required
DataType The data type in the time series identifier. For example, if using the State of Colorado’s HydroBase, DivTotal is used for diversion totals. Specify DataTypeColumn or DataType. Data type is often required
Interval Data interval in the time series identifier, using standard values such as 15Minute, 6Hour, Day, Month, Year. None – must be specified.
Scenario Scenario in the time series identifier. Usually not required.
DataStore The data store (or input type) in the time series identifier. Refer to the datastore and input type appendices or the TSTool main GUI for options. None – must be specified.
InputName The input name in the time series identifier, when a file name is required. Generally only required when reading from a file.
Alias Time series alias to assign, using a combination of % specifiers and literal strings. No alias is assigned.
ColumnProperties Column names and matching time series property name to set, using syntax:
Column1:Property1,Column2:Property2
Specify * for the column name to set all column values as properties. Specify * for the property value to use the column name for the time series property.		 No time series properties will be set from the table.
Properties String properties to be assigned to the time series using syntax
Property1:Value1,Property2:Value2
IfNotFound Indicates how to handle missing time series, one of:
  • Warn – generate fatal warnings and do not include in output.
  • Ignore – generate non-fatal warnings and do not include in output.
  • Default – generate non-fatal warnings and create empty time series for those that could not be found. This requires that a SetOutputPeriod command be used before the command to define the period for default time series.
 Warn
DefaultUnits Default units when IfNotFound=Default. Blank – no units.
DefaultOutputStart Specify the output period start when a default time series is read, using date/time string or ${Property}. Uses global output start.
DefaultOutputEnd Specify the output period start when a default time series is read, using date/time string or ${Property}. Uses global output end.
TimeSeriesCountProperty The name of the processor property to set with the total count of time series processed, including read and defaulted time series. Can be specified using processor ${Property}.
TimeSeriesReadCountProperty The name of the processor property to set with the count of time series read (not defaulted). Can be specified using processor ${Property}.
TimeSeriesDefaultCountProperty The name of the processor property to set with the count of time series that were defaulted. Can be specified using processor ${Property}.
TimeSeriesIndex1Property The name of the time series property to set with the index position (1+) for the time series read from the list, essentially a running count of read time series. Can be specified using processor ${Property}.

Examples

See the automated tests.

A sample command file to read monthly diversion time series from the State of Colorado’s HydroBase database is as follows:

# Read monthly diversion total from HydroBase for the structures in the list
# file. The data source is set to DWR because data source is saved in HydroBase.
ReadTimeSeriesList(TableID=”Diversions.csv",LocationColumn=”WDID”,DataSource=DWR,DataType=DivTotal,Interval=Month,InputType=HydroBase,IfNotFound=Default)

Troubleshooting

See Also