TSTool-Vol2-CommandReference - Laserfiche WebLink

time series NewEnsemble(TSList=AllTS,NewEnsembleID="TestEnsemble",NewEnsembleName="Test Ensemble") # Compute the statistic NewStatisticTimeSeriesFromEnsemble(Alias=”Mean”,EnsembleID="TestEnsemble", NewTSID="Test..Streamflow.Month.Mean",Statistic=Mean) The following figure illustrates the results: 262 TSTool Documentation NewStatisticTimeSeriesFromEnsemble() Command Command Reference – NewStatisticTimeSeriesFromEnsemble() -5 NewStatisticTimeSeriesFromEnsemble_Table NewStatisticTimeSeriesFromEnsemb le() Command Results 263 NewStatisticTimeSeriesFromEnsemble() Command TSTool Documentation Command Reference – NewStatisticTimeSeriesFromEnsemble() -6 This page is intentionally blank. 264 Command Reference – NewStatisticYearTS() -1 Command Reference: NewStatisticYearTS() Create a new yearly time series containing a statistic determined from each year of the input time series Version 10.12.00, 2012-07-16 The NewStatisticYearTS() command creates a new yearly time series, where each yearly value in the resulting time series contains a statistic determined from the sample of points from the corresponding year in the original time series. For example, if the original time series has a daily time step, then the sample that is analyzed will contain 365 or 366 values (depending on leap year). Calendar years are used by default; however, the OutputYearType parameter can be used to specify that different year types are analyzed. Other commands (e.g., ChangeInterval()) can produce a similar result for a limited number of statistics, for example converting a monthly time series to an annual total or mean. See also the NewStatisticTimeSeries(), NewStatisticTimeSeriesFromEnsemble(), CalculateTimeSeriesStatistic(), and CheckTimeSeries() commands. For hourly and finer interval, values are considered to be in a year when the year in the date/time matches the year of interested. This may lead to some issues if the last value in a year is actually recorded at hour 0 or later of the following year. The following dialog is used to edit the command and illustrates the syntax for the command. NewStatisticYearTS NewStatisticYearTS() Command Editor 265 NewStatisticYearTS() Command TSTool Documentation Command Reference – NewStatisticYearTS() -2 The command syntax is as follows: NewStatisticYearTS(Parameter=value,…) The following older command syntax is updated to the above syntax when a command file is read: TS Alias = NewStatisticYearTS (Parameter=value,…) Command Parameters Parameter Description Default TSID The time series identifier (or alias) of the time series to analyze. 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. NewTSID The time series identifier to be assigned to the new time series, which is useful to avoid confusion with the original time series. Use the same identifier as the original time series, with an interval of Year and a scenario matching the statistic. Statistic See the Available Statistics table below. None – must be specified. TestValue A test value used when analyzing the statistic. This parameter is required for some statistics and not used for others. See the statistics table below. AllowMissing Count The number of missing values allowed in the source interval(s) in order to produce a result. If an analysis window is specified (default is to analyze full years), then missing values outside of the analysis window are not considered as missing. Gaps at the end of the time series will be considered missing if within the analysis window. Allow any number of missing values. Minimum SampleSize The minimum sample size in order to compute the statistic. No minimum, although the statistic may have requirements. OutputYearType The output year type. For example, an output year type of NovToOct spans November of the previous calendar year to October of the current calendar year. All other parameters should still be specified in calendar year and the AnalysisWindowStart can have a month that is prior to the AnalysisWindowEnd month. Calendar AnalysisStart The starting date/time for the analysis using calendar dates (e.g., 2001-01-01), with precision consistent with Analyze the full period, extending the 266 TSTool Documentation NewStatisticYearTS() Command Command Reference – NewStatisticYearTS() -3 Parameter Description Default the time series interval. This will limit the data being analyzed at the ends of the time series and controls the length of the output time series. The analysis period is typically set to align with years consistent with the output year type. period to include full years. AnalysisEnd The ending date/time for the analysis using calendar dates (e.g., 2001-01-01) , with precision consistent with the time series interval. This will limit the data being analyzed at the ends of the time series and controls the length of the output time series. The analysis period is typically set to align with years consistent with the output year type. Analyze the full period, extending the period to include full years. Analysis WindowStart The calendar date/time for the analysis start within each year. Specify using the format MM, MM-DD, MM-DD hh, or MM-DD hh:mm, consistent with the time series interval precision. A year of 2000 will be used internally to parse the date/time. Use this parameter to limit data processing within the year, for example to analyze only a season. Data will be considered missing only if missing within this analysis window. If specifying for other than calendar year, the analysis window start month may be greater than the analysis window end month. Analyze the full year. Analysis WindowEnd Specify date/time for the analysis end within each year. See AnalysisWindowStart for details. Analyze the full year. SearchStart Within the analysis window, this indicates the starting date/time for the search. Specify using the format MM, MM-DD, MM-DD hh, or MM-DD hh:mm, consistent with the time series interval precision. A year of 2000 will be used internally to parse the date/time. This parameter is useful in cases where the processing considers seasonal aspects of the analysis window; for example, use when determining frost dates (when temperature is less than or equal to freezing) to ensure that the search starts from the middle of the normal growing season. Searches move forward in time except for the following statistics, in which case SearchStart will be the start of the search window, but will be the last value checked: DayOfLast*, MonthOfLast*. Use the analysis window start and end. Search forward for most statistics. Search backward for DayOfLast* and MonthOfLast* statistics. Available Statistics The following statistics are computed from a sample determined using the analysis window. If no analysis window is specified, then the default is to analyze complete years, where the years correspond to the OutputYearType. For example, for OutputYearType=NovToDec, November 1, 2000 to October 31, 2001 from the input corresponds to output year 2001. Statistic Description Limitations DayOfCentroid The day of the year (1-366) that is the centroid Input time series must be 267 NewStatisticYearTS() Command TSTool Documentation Command Reference – NewStatisticYearTS() -4 Statistic Description Limitations of the values, computed as sum(DayOfYear*value)/sum(values). daily or smaller interval. DayOfFirstGE Julian day of the year (1-366, relative to the start of the OutputYearType) for the first data value >= TestValue. Searches start at the start of the analysis window and move forward. Input time series must be daily or smaller interval. DayOfFirstGT Similar to DayOfFirstGE, for values > TestValue. Input time series must be daily or smaller interval. DayOfFirstLE Similar to DayOfFirstGE, for values <= TestValue. Input time series must be daily or smaller interval. DayOfFirstLT Similar to DayOfFirstGE, for values < TestValue. Input time series must be daily or smaller interval. DayOfLastGE Julian day of the year (1-366, relative to the start of the OutputYearType) for the last data value >= TestValue. Searches start at the start of the analysis window and move backward. Input time series must be daily or smaller interval. DayOfLastGT Similar to DayOfLastGE, for values > TestValue. Input time series must be daily or smaller interval. DayOfLastLE Similar to DayOfLastGE, for values <= TestValue. Input time series must be daily or smaller interval. DayOfLastLT Similar to DayOfLastGE, for values < TestValue. Input time series must be daily or smaller interval. DayOfMax Julian day of the year (1-366, relative to the start of the OutputYearType) for the first maximum value in the time series. Input time series must be daily or smaller interval. DayOfMin Julian day of the year (1-366, relative to the start of the OutputYearType) for the first minimum value in the time series. Input time series must be daily or smaller interval. GECount Count of values in a year >= TestValue. GEPercent Percent of values in a year >= TestValue, based on the total number of points in the year. GTCount Count of values in a year > TestValue. GTPercent Percent of values in a year > TestValue, based on the total number of points in the year. LECount Count of values in a year <= TestValue. LEPercent Percent of values in a year <= TestValue, based on the total number of points in the year. LTCount Count of values in a year < TestValue. LTPercent Percent of values in a year < TestValue, based on the total number of points in the year. Max Maximum value in a year. Mean Mean of values in a year. Min Minimum value in a year. MissingCount Number of missing values in a year. MissingPercent Percent of missing values in a year. 268 TSTool Documentation NewStatisticYearTS() Command Command Reference – NewStatisticYearTS() -5 Statistic Description Limitations MonthOfCentroid The month of the year (1-12) that is the centroid of the values, computed as sum(MonthOfYear*value)/sum(values). Input time series must be monthly or smaller interval. MonthOfFirstGE Month the year (1-12, relative to the start of the OutputYearType) for the first data value >= TestValue. Searches start at the start of the analysis window and move forward. Input time series must be monthly or smaller interval. MonthOfFirstGT Similar to DayOfFirstGE, for values > TestValue. Input time series must be monthly or smaller interval. MonthOfFirstLE Similar to DayOfFirstGE, for values <= TestValue. Input time series must be monthly or smaller interval. MonthOfFirstLT Similar to DayOfFirstGE, for values < TestValue. Input time series must be monthly or smaller interval. MonthOfLastGE Month of the year (1-12, relative to the start of the OutputYearType) for the last data value >= TestValue. Searches start at the end of the analysis window and move backward. Input time series must be monthly or smaller interval. MonthOfLastGT Similar to DayOfLastGE, for values > TestValue. Input time series must be monthly or smaller interval. MonthOfLastLE Similar to DayOfLastGE, for values <= TestValue. Input time series must be monthly or smaller interval. MonthOfLastLT Similar to DayOfLastGE, for values < TestValue. Input time series must be monthly or smaller interval. MonthOfMax Month of the year (1-12, relative to the start of the OutputYearType) for the first maximum value in the time series. Input time series must be monthly or smaller interval. MonthOfMin Month of the year (1-12, relative to the start of the OutputYearType) for the first minimum value in the time series. Input time series must be monthly or smaller interval. NonMissingCount Number of non-missing values in a year. NonMissingPercent Percent of non-missing values in a year. Total Total of values in a year. 269 NewStatisticYearTS() Command TSTool Documentation Command Reference – NewStatisticYearTS() -6 Example The following example commands file computes the last spring frost date for 28 degrees and 32 degrees, searching backwards from June 30 each year, and the first fall frost date for 32 and 28 degrees, searching forwards from July 1 each year: StartLog(LogFile="FrostDates_HydroBase.log") SetOutputPeriod(OutputStart="1950-01",OutputEnd="2004-12") # 3553 -GREELEY UNC 3553.NOAA.TempMin.Day~HydroBase NewStatisticYearTS(TSID="3553.NOAA.TempMin.Day",Alias=”3553_FrostDateL28S”, NewTSID="3553.NOAA.FrostDateL28S.Year", Statistic=DayOfLastLE,TestValue=28,SearchStart="06/30") NewStatisticYearTS(TSID="3553.NOAA.TempMin.Day",Alias=” FrostDateL32S”, NewTSID="3553.NOAA.FrostDateL32 S.Year", Statistic=DayOfLastLE,TestValue=32,SearchStart="06/30") NewStatisticYearTS(TSID="3553.NOAA.TempMin.Day",Alias=”3553_FrostDateF32F”, NewTSID="3553.NOAA.FrostDateF32F.Year", Statistic=DayOfFir stLE,TestValue=32,SearchStart="07/01") NewStatisticYearTS(TSID="3553.NOAA.TempMin.Day",Alias=”3553_FrostDateF28F”, NewTSID="3553.NOAA.FrostDateF28F.Year", Statistic=DayOfFirstLE,TestValue=28,SearchSt art="07/01") Free(TSID="*.*.TempMin.*") WriteStateCU(OutputFile="Results/Test.FrostDates") 270 Command Reference: NewTable () Create a new table Version 09.04.02, 2009-07-28 The NewTable() command creates a table with named columns, each of which is a specified data type. Tables are used to hold information about data objects, such as statistics for time series. Commands like CalculateTimeSeriesStatistic() can add information to tables. Tables can be written as final data products or artifacts of processing. Characteristics of the table are as follows: • Each column can only contain a single data type • The default precision for numbers for display and output is 2 digits after the decimal – additional formatting features may be available in write commands and may be added later • Tables are referenced using the TableID • Cells in tables are referenced using the column name and cell values that identify rows (such as time series identifiers) The following dialog is used to edit the command and illustrates the syntax for the command. NewTable NewTable () Command Editor 271 Command Reference – NewTable () -1 NewTable () Command TSTool Documentation The command syntax is as follows: NewTable (Parameter=Value,…) Command Parameters Parameter Description Default TableID Identifier for the table – should be unique among tables that are defined. None – must be specified. Columns The column names and data types are defined using the format ColumnName,DataType; ColumnName,DataType. Column names can contain spaces; however, simple short names are generally handled better by display features and minimize errors in referencing the columns. Data types are specified using the following strings: • datetime – date and time • double – double precision number • float – single precision number • integer – integer (-2147483648 to 2147483647) • short – short integer (-32768 to 32767) • string – Unicode string No columns will be defined. Command Reference – NewTable() -2 272 Command Reference – NewTimeSeries() -1 Command Reference: NewTimeSeries() Create a new time series Version 10.21.00, 2013-06-10 The NewTimeSeries() command creates a new time series and assigns it an alias. This time series then can be manipulated with other commands. The command is useful, for example, to create a new time series to receive the results of a series of manipulations, rather than having the results accumulate in the first time series. See also the NewPatternTimeSeries()command, which initializes a time series with a repeating pattern of values. Subsequent manipulation of the time series may require use of the SetTimeSeriesProperty() and other commands to ensure that the new time series properties are as desired. The following dialog is used to edit the command and illustrates the syntax for the command. The new time series identifier, which provides critical information including the data interval, is edited by pressing the Edit button. NewTimeSeries NewTimeSeries() Command Editor The command syntax is as follows: NewTimeSeries(Parameter=Value,…) The following older command syntax is updated to the above syntax when a command file is read: 273 NewTimeSeries() Command TSTool Documentation Command Reference – NewTimeSeries() -2 TS Alias = NewTimeSeries(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). None – must be specified. NewTSID The time series identifier of the new time series. The editor dialog formats the identifier from its parts. None – must be specified with at least minimal information (location, data type, and interval). Description The description for the time series, used in output. Blank. SetStart The start of the time series data period. Use the start from SetOutputPeriod(). SetEnd The end of the time series data period. Use the end from SetOutputPeriod(). Units Data units for the time series. Blank. MissingValue Value for missing data values. -999 is the default for historical reasons; however, NaN (not a number) is being phased in and should be specified if possible. -999 InitialValue The value to initialize the time series. Initialize the time series to missing data. InitialFunction The function to use to initialize time series data values. This parameter can be used to generate data for testing to simplify visual inspection of results. • DATE_YYYY – 4-digit year • DATE_YYYYMM – and month • DATE_YYYYMMDD – year, month, and day • DATE_YYYYMMDD_hh – year, month, and day, with decimal as hour • DATE_YYYYMMDD_hhmm – year, month, and day, with decimal as hour and minute • RANDOM_0_1 – random number >= 0 and < 1 • RANDOM_0_1000 – random number >= 0 and < 1000 Initialize the time series to missing data. The example command file shown below creates a new time series and initializes it to a constant of 20 CFS. Uncommenting the first command would allow the SetStart and SetEnd parameters to be removed from the NewTimeSeries() command. The interval (Month below) must match a recognized type but the other parts of the identifier such as data type are user-defined. #SetOutputPeriod(OutputStart="1950-01",OutputEnd="2002-12") NewTimeSeries(Alias=”station1”,NewTSID="Station1.MyModel.Streamflow.Month", Description="Example Description",SetStart="1950-01", SetEnd="2002-12",Units="CFS",InitialValue=20) 274 Command Reference: NewTreeView() Create a new tree view using a definition file Version 09.07.00, 2010-07-20 The NewTreeView() command creates a tree view, which is a hierarchical listing of time series. The resulting view is dispayed in the Views section of the TSTool Results area and provides interactive access to data. The view is defined using a simple text file, as shown in the following example: # Test data for displaying a tree view of time series results Label: Top-level label TS: ts1* Label: Second-level label TS: ts2* Label: Another second-level label TS: ts3* Tree view definition files have the following characteristics: • Comments are indicated by lines starting with #. • Indentations indicate the level (branch) in the tree: o Use the tab character to indicate indentation o The indentation on one row cannot be more than 1 greater than the previous row • The content for the tree is indicated by keywords: o Label: indicates that the string following the colon will be used to label a branch. 􀂃 A single top-level label is required o TS: indicates that a time series identifier pattern will be used to identify time series in the tree. Wildcard conventions follow rules consistent with the TSList=AllMatchingTSID ,TSID=… command parameters. The following figure illustrates the resulting view that is displayed in TSTool for the above example, using contrived data. The time series in the tree view can be selected and a pop-up menu can be used to generate graphs. Consequently, the view allows the results of processing to be presented in a way that is more customized than a simple list. It is envisioned that additional functionality will be implemented, for example to output the view as HTML with navigation links. NewTreeView_Results Example of Tree View in TSTool Results 275 Command Reference – NewTreeView() -1 NewTreeView() Command TSTool Documentation The following dialog is used to edit the command and illustrates the syntax of the command. NewTreeView NewTreeView() Command Editor The command syntax is as follows: NewTreeView(Parameter=Value,…) Command Parameters Parameter Description Default ViewID Identifier to assign to the view, which allows the view to be used with other commands. None – must be specified. InputFile The name of the view definition file to read, as an absolute path or relative to the command file location. None – must be specified. Command Reference – NewTreeView () -2 276 Command Reference: Normalize() Create a normalized time series Version 10.00.01, 2011-05-15 The Normalize() command creates a new normalized time series from an existing time series, assigning an alias to the result. Normalized time series are useful for analyzing trends and relationships and for allowing time series with different units to be plotted or analyzed together. For example, the range of data values can be normalized to the range 0 to 1. The alias that is assigned to the time series can be referenced by other commands. The following dialog is used to edit the command and illustrates the syntax of the command. Normalize Normalize() Command Editor The command syntax is as follows: Normalize(Parameter=Value,…) The following older command syntax is updated to the above syntax when a command file is read: TS Alias = Normalize(Parameter=Value,…) Command Parameters Parameter Description Default TSID The time series identifier or alias for the time series to be normalized. 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 None – must be specified. 277 Command Reference – Normalize() -1 Normalize() Command TSTool Documentation Parameter Description Default an alternative to the time series identifier (TSID). MinValue Method Indicates how to determine the minimum data value to process, one of: • MinFromTS – get the minimum value from the time series (typical) • MinZero – use zero (e.g., if negative values are to be ignored) None – must be specified. MinValue The minimum normalized value (e.g., 0). None – must be specified. MaxValue The maximum normalized value (e.g., 1). None – must be specified. A sample command file to process data from the State of Colorado’s HydroBase database is as follows: # 06730500 -BOULDER CREEK AT MOUTH, NEAR LONGMONT, CO. 06730500.USGS.Streamflow.Month~HydroBase Normalize(TSID="06730500.USGS.Strea mflow.Month",Alias=”NormalizedTS”, MinValueMethod=MinFromTS,MinValue=0.0,MaxValue=1.0) The results are as follows: Normalize_Graph Results of Normalize() Command Command Reference – Normalize() -2 278 Command Reference – OpenHydroBase() -1 Command Reference: OpenHydroBase() Open a connection to a HydroBase database Version 10.13.00, 2012-09-13 This command will be phased out in the future. Instead, define HydroBase datastores (see the HydroBase Datastore appendix), where the datastore name is equivalent to the InputName parameter. The OpenHydroBase() command opens a connection to a HydroBase database, allowing data to be read from the database (e.g., with ReadHydroBase() commands and time series identifiers that have ~HydroBase input types). This command is not typically used for interactive sessions but may be inserted to run in batch only mode to allow a specific database and commands files to be distributed. It may also be used in cases where time series are read from different HydroBase databases, perhaps to compare the contents of the databases – in this case two OpenHydroBase() commands would be used. When connecting to a SQL Server database, a connection will be tried for SQL Server (Express) and older MSDE databases. If both fail, a warning will be shown. The following dialog is used to edit this command and illustrates the command syntax. The Database type is used to control settings for parameters and is not itself a parameter. OpenHydroBase OpenHydroBase() Command Editor The command syntax is as follows: OpenHydroBase(Parameter=Value,…) Command Parameters Parameter Description Default Database Server Used with a SQL Server HydroBase. Specify the SQL Server database machine name. A list of choices will be shown, corresponding to properties in the CDSS.cfg Required if a SQL Server database is used. 279 OpenHydroBase() Command TSTool Documentation Command Reference – OpenHydroBase() -2 configuration file. The generic value DatabaseServer=local will automatically be translated to the name of the local computer. Database Name Used with a SQL Server HydroBase. The name of the database typically follows a pattern similar to: HydroBase_CO_YYYYMMDD. A list of choices will be shown, corresponding to properties in the CDSS.cfg configuration file. HydroBase OdbcDsn The ODBC DSN to use for the connection, used only when working with a Microsoft Access database. Required if a Microsoft Access database is used. InputName The input name corresponding to the ~InputType~InputName information in time series identifiers. This is used when more than one HydroBase connection is used in the same commands file. Blank (no input name). UseStored Procedures Used with SQL Server, indicating whether stored procedures are used. Stored procedures are the default and should be used except when testing software. True (used stored procedures). RunMode Indicates when the command should be run, one of: • BatchOnly – run the command only in batch mode. • GUIOnly – run the command only in GUI mode. • GUIAndBatch – run the command in batch and GUI mode. GUIAndBatch The following example command file illustrates how to connect to a SQL Server database running on a machine named “sopris”: StartLog(LogFile="Results/Example_OpenHydroBase_DatabaseName.TSTool.log") OpenHydroBase(DatabaseServer="sopris ",DatabaseName="HydroBase_CO_20060816") ReadHydroBase(TSID="BOXHUDCO.DWR.Streamflow.Month",Alias="ts") Example_OpenHydroBase_DatabaseName The following example command file illustrates how to make two HydroBase database connections, in this case to test whether the stored procedure and SQL queries return the same results (the InputName parameter is used to tell TSTool which connection to use when reading data based on time series identifiers): OpenHydroBase(DatabaseServer="hbserver",RunMode=GUIAndBatch, UseStoredProcedures=True,InputName="SP") OpenHydroBase(Databa seServer="hbserver",RunMode=GUIAndBatch, UseStoredProcedures=False,InputName="NoSP") ReadHydroBase(TSID="BOXHUDCO.DWR.Streamflow.Month~HydroBase~SP",Alias="ts_sp") ReadHydroBase(TSID="BOXHUDCO.DWR.St reamflow.Month~HydroBase~NoSP",Alias="ts_nosp") Example_OpenHydroBase_TwoConnections.TSTool The following example commands file illustrates how to connect to a Microsoft Access database (although Microsoft Access databases are no longer supported): OpenHydroBase(RunMode=GUIAndBatch,OdbcDsn="HydroBase_DIV1_20030701") 280 Command Reference: PrintTextFile() Print a text file Version 10.00.03, 2011-07-01 The PrintTextFile() command prints a text file to a physical or virtual (e.g., PDF file) printer. This command is used in testing to verify print features but also can be used in production to automate printing. Printing is highly dependent on the features available from a printer. The command attempts to list printer options to configure command parameters. However, some options are listed based on what a printer can do, but this may require physically changing/selecting paper trays, using manual feed, etc. The command will be enhanced in the future to specify features including tray selection but currently it is intended for use with common printer settings. If advanced settings are needed beyond the properties available in the command, use ShowDialog=True (displaying the dialog will pause command execution). The following dialog is used to edit the command and illustrates the syntax for the command (in this case printing to a Microsoft XPS file). PrintTextFile PrintTextFile() Command Editor 281 Command Reference