tsblender 103.3.0
Drop-in replacement for TSPROC that is a utility for inverse modeling with PEST.
License: BSD-3-Clause
Requires Python: >=3.9
Keywords: baseflow, cli-app, hydrology, parameter-estimation, python, time-series, tsproc

.. image:: https://github.com/timcera/tsblender/actions/workflows/pypi-package.yml/badge.svg
    :alt: Tests
    :target: https://github.com/timcera/tsblender/actions/workflows/pypi-package.yml
    :height: 20

.. image:: https://img.shields.io/coveralls/github/timcera/tsblender
    :alt: Test Coverage
    :target: https://coveralls.io/r/timcera/tsblender?branch=master
    :height: 20

.. image:: https://img.shields.io/pypi/v/tsblender.svg
    :alt: Latest release
    :target: https://pypi.python.org/pypi/tsblender/
    :height: 20

.. image:: https://img.shields.io/pypi/l/tsblender.svg
    :alt: BSD-3 clause license
    :target: https://pypi.python.org/pypi/tsblender/
    :height: 20

.. image:: https://img.shields.io/pypi/dd/tsblender.svg
    :alt: tsblender downloads
    :target: https://pypi.python.org/pypi/tsblender/
    :height: 20

.. image:: https://img.shields.io/pypi/pyversions/tsblender
    :alt: PyPI - Python Version
    :target: https://pypi.org/project/tsblender/
    :height: 20

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         |
     +----------------------------+--------+-----------+