Documentation for hspfbintoolbox

The hspfbintoolbox is a Python script and library of functions to read Hydrological Simulation Program Fortran (HSPF) binary files and print to screen. The time series can then be redirected to file, or piped to other command line programs like tstoolbox.

Requirements

• python 3.7 or later

• tstoolbox - utilities to process time-series

Installation

pip

pip install hspfbintoolbox

conda

conda install -c conda-forge hspfbintoolbox

Usage - Command Line

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

catalog

Prints out a catalog of data sets in the binary file.

extract

Prints out data to the screen from a HSPF binary output file.

For the subcommands that output data it is printed to the screen and you can then redirect to a file.

Usage - API

You can use all of the command line subcommands as functions. The function signature is identical to the command line subcommands. The return is always a PANDAS DataFrame. Input can be a CSV or TAB separated file, or a PANDAS DataFrame and is supplied to the function via the ‘input_ts’ keyword.

Simply import hspfbintoolbox:

import hspfbintoolbox

# Then you could call the functions
ntsd = hspfbintoolbox.extract('tests/test.hbn', 'yearly', ',905,,AGWS')

# Once you have a PANDAS DataFrame you can use that as input.
ntsd = tstoolbox.aggregate(statistic='mean', agg_interval='daily', input_ts=ntsd)

Sub-command Detail

catalog

usage: hspfbintoolbox catalog [-h] [--tablefmt TABLEFMT] [--header HEADER]
  hbnfilename

The first four items of each line can be used as labels with the 'extract'
command to identify time-series in the binary file.

positional arguments:
  hbnfilename          The HSPF binary output file.  This file must have been created from
    a completed model run.


options:
  -h | --help
      show this help message and exit
  --tablefmt TABLEFMT
      [optional, default is 'csv', output format]
      The table format. Can be one of 'csv', 'tsv', 'plain', 'simple', 'grid',
      'pipe', 'orgtbl', 'rst', 'mediawiki', 'latex', 'latex_raw' and
      'latex_booktabs'.
  --header HEADER
      [optional, default is 'default', output format]
      This is if you want a different header than is the default for this output
      table. Pass a list with string column names for each column in the
      table.

extract

usage: hspfbintoolbox extract [-h] [--start_date START_DATE]
  [--end_date END_DATE] [--sort_columns] hbnfilename interval [labels ...]

Prints out data to the screen from a HSPF binary output file.

positional arguments:
  hbnfilename           The HSPF binary output file.  This file must have been created from
    a completed model run.

  interval              One of 'yearly', 'monthly', 'daily', or 'bivl'.  The 'bivl' option is
    a sub-daily interval defined in the UCI file. Typically 'bivl' is used for
    hourly output, but can be set to any value that evenly divides into a
    day.

  labels                The remaining arguments uniquely identify a time-series in the
    binary file. The format is 'OPERATIONTYPE,ID,VARIABLEGROUP,VARIABLE'.
    For example: 'PERLND,101,PWATER,UZS IMPLND,101,IWATER,RETS'
    Leaving a section without an entry will wild card that specification. To get
    all the PWATER variables for PERLND 101 the label would read:
    'PERLND,101,PWATER,'
    To get TAET for all PERLNDs:
    'PERLND,,,TAET'
    Note that there are spaces ONLY between label specifications not within the
    labels themselves.
    OPERATIONTYE can be PERLND, IMPLND, RCHRES, and BMPRAC.
    ID is the operation type identification number specified in the UCI file.
    These numbers must be in the range 1-999.
    Here, the user can specify
        • a single ID number to match
        • no entry, matching any operation ID number
        • a range, specified as any combination of simple integers and groups of
        integers marked as "start:end", with multiple allowed sub-ranges
        separated by the "+" sign.
    Examples:
      ┌───────────────────────┬───────────────────────────────┐
      │ Label ID              │ Expands to:                   │
      ╞═══════════════════════╪═══════════════════════════════╡
      │ 1:10                  │ 1,2,3,4,5,6,7,8,9,10          │
      ├───────────────────────┼───────────────────────────────┤
      │ 101:119+221:239       │ 101,102..119,221,221,...239   │
      ├───────────────────────┼───────────────────────────────┤
      │ 3:5+7                 │ 3,4,5,7                       │
      ╘═══════════════════════╧═══════════════════════════════╛

    VARIABLEGROUP depends on OPERATIONTYPE where:
    if OPERATIONTYPE is PERLND then VARIABLEGROUP can be one of
        'ATEMP', 'SNOW', 'PWATER', 'SEDMNT', 'PSTEMP', 'PWTGAS',
        'PQUAL', 'MSTLAY', 'PEST', 'NITR', 'PHOS', 'TRACER'
    
    if OPERATIONTYPE is IMPLND then VARIABLEGROUP can be one of
        'ATEMP', 'SNOW', 'IWATER', 'SOLIDS', 'IWTGAS', 'IQUAL'
    
    if OPERATIONTYPE is RCHRES then VARIABLEGROUP can be one of
        'HYDR', 'CONS', 'HTRCH', 'SEDTRN', 'GQUAL', 'OXRX', 'NUTRX',
        'PLANK', 'PHCARB', 'INFLOW', 'OFLOW', 'ROFLOW'
    
    if OPERATIONTYPE is BMPRAC then VARIABLEGROUP is not used and you
    have to leave VARIABLEGROUP as a wild card.  For example,
    'BMPRAC,875,,RMVOL'.

    The Time Series Catalog in the HSPF Manual lists all of the variables in
    each of these VARIABLEGROUPs. For BMPRAC, all of the variables in all
    Groups in the Catalog are available in the unnamed (blank) Group.


options:
  -h | --help
      show this help message and exit
  --start_date START_DATE
      [optional, defaults to first date in time-series, input filter]
      The start_date of the series in ISOdatetime format, or 'None' for
      beginning.
  --end_date END_DATE
      [optional, defaults to last date in time-series, input filter]
      The end_date of the series in ISOdatetime format, or 'None' for end.
  --sort_columns
      [optional, default is False]
      If set to False will maintain the columns order of the labels. If set to
      True will sort all columns by their columns names.