Skip to content

TSTool / Datastore Reference / StateCUB


Overview

The StateCUB time series input type corresponds to the file format used by the State of Colorado's StateCU consumptive use model, in particular the binary output file. These files contain important water balance information for every location in the model. The following table summarizes the contents of the binary files and corresponding text report files (all files can be large for large data sets).

Node Type Monthly Binary File Monthly Report File
CU locations *.bd1 *.dwb

The following documentation describes the format of the BD1 binary file. See the StateCU Documentation for a complete description of StateCU output files. The following is a summary to explain how TSTool handles the format.

Unlike the StateMod binary files, the StateCU BD1 file does not have a fixed length record throughout the file. Different sections of the file have fixed length segments, depending on the contents of the section. The main sections and their format are described below, using terminology consistent with StateCU.

Header Records (File Metadata)

Field Data Type Description
1 NumStr integer Number of structures (CU locations).
2 NumTS integer Number of time steps. The data period for the file is determined from first time series record plus (NumTS – 1).
3 NumStrVar integer Number of variables associated with each structure.
4 NumTSVar integer Number of time series variables (parameters) associated with each structure.
5 NumTSA integer Number of time steps in a year (1, 12, 365), although 12 (monthly data) is currently the only supported value.

Structure Header Records (Structure Metadata) - Repeat the Following for NumStrVar

Field Data                                             Type Description
1 StructureVarType char(1) The type of the structure variable: R for floating point number, I for integer, C for character string.
2 StructureVarLen integer Length of structure variable in bytes.
3 StructureVarName char(24) Structure variable name.
4 StructureVarInReport integer Whether the structure is in the DWB report file.
5 StructureVarReportHeader char(60) The report header to use for the structure variable.

Time Series Header Records (Time Series Metadata) - Repeat the Following for NumTSVar

Field Data                                       Type Description
1 TimeSeriesVarType char(1) The type of the time series variable: R for floating point number, I for integer, C for character string.
2 TimeSeriesVarLen integer Length of time series variable in bytes.
3 TimeSeriesVarName char(24) Time series variable name.
4 TimeSeriesVarInReport integer Whether the structure is in the DWB report file.
5 TimeSeriesVarUnits char(10) The units for the time series.

Structure Variable Data Records

Repeat the following for NumStr, and for each NumStrVar. The order of the variables is not fixed; however, the “Structure Index” variable contains a numeric identifier that is used to sort the structures to lookup structures when reading the time series.

Field Data                               Type Description
1 StructureVarValue As per metadata. The values of the structure variables, including “Structure Index” (1+), “Structure ID”, “Structure Name”. Additional variables may be added later. The index is used to create a sorted list of structure identifiers and names for applications like TSTool.

Time Series Data Records

Repeat the following looping on NumStr, then NumTimeSteps, and then NumTimeSeriesVar. The order of time series variables is the same for all structures and throughout the entire file (variable “X” will always be in the same position in the inner loop). The order of the structures may not agree with the order of the metadata from above. The “Structure Index” variable in the time series records is used to map the time series to the structure identified in the metadata above.

Field Data                                 Type Description
1 TimeSeriesVarValue As per metadata. The values of the time series variables, including “Structure Index” (matching “Structure Index” from the structure data), “Year” (Calendar 4-digit), “Month Index” (1-12), and variable names for values at each time step. Additional variables may be added later.

A visual representation of data is as follows (note that Structure 1 is an internal looping representation and the actual structure is identified by the “Structure Index” variable for the time series):

Structure 1
    Timestep 1
        Variable 1
        ...
        Variable NumStrVar
    Timestep 2
        Variable 1
        ...
        Variable NumStrVar
    ...
    TimeStep NumTS
Structure 2
    Timestep 1
        Variable 1
        ...
        Variable NumStrVar
    Timestep 2
        Variable 1
        ...
        Variable NumStrVar
    ...
    TimeStep NumTS
...
Structure NumStr

The order of the structures in the time series data block may not be the same as that in the header metadata due to the constraints of the StateCU model and how it writes each section during different phases of execution. Therefore, at initialization, the “Structure Index” variable value for each time series is read for the first timestep of each structure to determine the mapping of the structure in the time series data block with that in the main header.

Some time series variables are integers (e.g., the year and month) and some are characters (e.g., the month name and model flags). The integer variable “Year” has the same value for 12 monthly time steps and then increases by one. The variable “Month Index” repeats the values 1 – 12 through the period of the time series. Only floating point parameters are read by default. In the future, integer and character time series may be allowed or the character values may be translated to a lookup table of numbers.

Standard Time Series Properties

The standard time series identifier for StateCUB binary time series is of the form:

Location.StateCU.DataType.Interval~StateCUB~PathToFile

Time series properties are set using the following guidelines:

  • The location part of the time series identifier is taken from the structure identifier field in the data.
  • The data source part of the time series identifier is set to StateCU, because StateCU has created the output time series.
  • The data type is assigned as the variable (parameter) name described above – See the StateCU documentation for more information.
  • The data interval is assigned as Month.
  • The scenario is set to blank (not used).
  • The input type is set to StateCUB.
  • The input name is set to the name of the file.
  • The units are determined from the time series variable metadata.
  • The missing data value is assigned to -999.0.
  • The description is set to the structure name.
  • The period is set to the information in the first time series record incremented by the number of timesteps in the file (minus one). Current the file only contains calendar year data (January to December).

Limitations

StateCU binary files have the following limitations:

  • The file does not contain a format version; therefore, it is difficult for software to handle changes in the file format. However, the current format is designed to allow for changing structure and time series parameters without changing the file format.
  • The file does not contain header information indicating the source of the file (e.g., the creation date, user, directory, StateCU response file, command line). Therefore, it is difficult to know with certainty how a file was created.
  • Leap years are not explicitly handled with 29 days during model calculations. Therefore there may be some loss of precision as data are processed through the model. Refer to the StateCU documentation for more information on how values are calculated.