tsblender - Quick Guide

The tsblender is a pure python re-write of the Time Series PROCessor (TSPROC). When finished it will be a superset of TSPROC functionality and a more robust and flexible tool for time series analysis.

The tsblender is almost a drop-in replacement for TSPROC. It is currently a super-set of TSPROC functionality, while missing only the DIGITAL_FILTER and MOVING_MINIMUM processing blocks. Existing TSPROC control and input files can be used without modification except as noted previously.

The documentation for TSPROC can be used to understand tsblender and build the control and input files. The TSPROC documentation is available at: https://pubs.usgs.gov/tm/tm7c7/

The tsblender works with PEST, PEST++, and PEST-HP suites of programs. These are used to optimize model parameters and to perform uncertainty analysis on model predictions. Information on PEST and related programs can be found at: http://www.pesthomepage.org/ and https://github.com/usgs/pestpp.

USGS TSPROC

The USGS TSPROC is a Time Series PROCessor that uses a configuration file to describe the tasks the data scientist or modeler wants to accomplish.

The USGS TSPROC is based upon part of the Surface Water Utilities Package developed by John Doherty, Watermark Numerical Computing. The Surface Water Utilities package was created to support optimization of model parameters using the Parameter ESTimation (PEST) suite of programs. PEST was also developed by John Doherty.

USGS TSPROC was rewritten in a project led by Steve Westenbroek, of the Wisconsin USGS. It is written in Fortran 90 and “C” and is available from the USGS at:

TSPROC Main site:

https://wi.water.usgs.gov/models/tsproc/

TSPROC Documentation:

https://pubs.usgs.gov/tm/tm7c7/

TSPROC Development:

https://github.com/smwesten-usgs/tsproc

Requirements

• python 3.8 or higher

Installation

Should be as easy as running pip install tsblender or conda install -c conda-forge -c timcera tsblender at any command line.

Usage - Command Line

Just run ‘tsblender –help’ to get a list of subcommands:

usage: tsblender [-h]
                 {run, about) ...

positional arguments:
  {run, about}

about
    Display version number and system information.
run
    Run a tsblender script file.

optional arguments:
    -h, --help            show this help message and exit

Progress

ONLY in tsblender

tsblender Block Name
GET_SERIES_GSFLOW_GAGE
GET_SERIES_CSV
GET_SERIES_HSPFBIN
GET_SERIES_XLSX
COPY
MOVE
PLOT

There is a new feature in tsblender to “roll up” multiple blocks into a single block. This is done to simplify the control file, to reduce mistakes that can come from repetition, and to make the control file easier to read and understand. Not all blocks can be rolled up depending on how they are configured. The blocks that can’t be rolled up are: EXCEEDENCE_TIME, FLOW_DURATION, GET_MUL_*, HYDROLOGIC_INDICES, LIST_OUTPUT, PLOT, SETTINGS, and WRITE_PEST_FILES.

Rolled up example of GET_SERIES_WDM:

START GET_SERIES_WDM
  CONTEXT input
  NEW_SERIES_NAME obs01   sim01
  FILE            obs.wdm sim.wdm
  DSN             1001
  DATE_1          2000-01-01
  DATE_2          2000-12-31
END GET_SERIES_WDM

Would un-roll within tsblender to the following:

START GET_SERIES_WDM
  CONTEXT input
  NEW_SERIES_NAME obs01
  FILE            obs.wdm
  DSN             1001
  DATE_1          2000-01-01
  DATE_2          2000-12-31
END GET_SERIES_WDM

START GET_SERIES_WDM
  CONTEXT input
  NEW_SERIES_NAME sim01
  FILE            sim.wdm
  DSN             1001
  DATE_1          2000-01-01
  DATE_2          2000-12-31
END GET_SERIES_WDM

In Progress

The following table shows the progress of the implementation of the TSPROC blocks in ‘tsblender’.

TSPROC Block Name	tsproc	tsblender
DIGITAL_FILTER	X
ERASE_ENTITY	X	X
EXCEEDENCE_TIME	X	X
FLOW_DURATION	X	X
GET_SERIES_SSF	X	X
GET_SERIES_STATVAR	X	X
GET_SERIES_PLOTGEN	X	X
GET_SERIES_TETRAD	X
GET_SERIES_UFORE_HYDRO	X	X
GET_SERIES_WDM	X	X
HYDRO_EVENTS	X	X
HYDRO_PEAKS	X
HYDROLOGIC_INDICES	X	X
LIST_OUTPUT	X	X
MOVING_MINIMUM	X
NEW_SERIES_UNIFORM	X	X
NEW_TIME_BASE	X	X
PERIOD_STATISTICS	X	X
REDUCE_TIME_SPAN	X	X
SERIES_BASE_LEVEL	X	X
SERIES_CLEAN	X	X
SERIES_COMPARE	X	X
SERIES_DIFFERENCE	X	X
SERIES_DISPLACE	X	X
SERIES_EQUATION	X	X
SERIES_STATISTICS	X	X
SETTINGS	X	X
USGS_HYSEP	X	X
V_TABLE_TO_SERIES	X	X
VOLUME_CALCULATION	X	X
WRITE_PEST_FILES	X	X

Deprecated in tsblender

The GET_MUL_SERIES_* blocks are redundant in ‘tsblender’ and can be replaced by rolled up versions of the GET_SERIES_* blocks. They are implemented full in tsblender, but discouraged for use in new scripts.

TSPROC Block Name	tsproc	tsblender
GET_MUL_SERIES_GSFLOW_GAGE	X	X
GET_MUL_SERIES_PLOTGEN	X	X
GET_MUL_SERIES_SSF	X	X
GET_MUL_SERIES_STATVAR	X	X