https://travis-ci.org/timcera/hspfbintoolbox.svg?branch=master https://coveralls.io/repos/timcera/hspfbintoolbox/badge.png?branch=master Latest release hspfbintoolbox license

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

  • pandas - on Windows this is part of the Python(x,y), Enthought, or Anaconda distributions

  • mando - command line parser

  • tstoolbox - utilities to process time-series

Installation

Should be as easy as running pip install hspfbintoolbox or easy_install hspfbintoolbox at any command line. Not sure on Windows whether this will bring in pandas but as mentioned above, if you start with Python(x,y) then you won’t have a problem.

Usage - Command Line

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

catalog

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

dump

Prints out ALL data from a HSPF binary output file.

extract

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

time_series

DEPRECATED: Use ‘extract’ instead.

The default for all of the subcommands is to accept data from stdin (typically a pipe). If a subcommand accepts an input file for an argument, you can use “–infile=filename”, or to explicitly specify from stdin use “–infile=’-‘” .

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.dump('tests/test.hbn')

# 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.


optional arguments:
  -h | --help
      show this help message and exit
  --tablefmt TABLEFMT
      [optional, default is 'simple']
      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']
      This is if you want a different header than is the default for this output
      table. Pass a list of strings for each column in the table.

dump

usage: hspfbintoolbox dump [-h] [--time_stamp TIME_STAMP] hbnfilename

Prints out ALL data 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.


optional arguments:
  -h | --help
      show this help message and exit
  --time_stamp TIME_STAMP
      [optional, default is 'begin']
      For the interval defines the location of the time stamp. If set to
      'begin', the time stamp is at the begining of the interval. If set
      to any other string, the reported time stamp will represent the end
      of the interval. Default is 'begin'.Z

extract

usage: hspfbintoolbox extract [-h] hbnfilename interval [labels [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,VARIABLE_GROUP,VARIABLE'.
    For example: 'PERLND,101,PWATER,UZS IMPLND,101,IWATER,RETS'
    Leaving a section without an entry will wildcard 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.
    OPERATIONTYE can be PERLND, IMPLND, RCHRES, and BMPRAC.
    ID is specified in the UCI file.
    VARIABLE_GROUP 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 there is no VARIABLEGROUP and you
    have to leave VARIABLEGROUP as a wild card.  For example,
    'BMPRAC,875,,RMVOL'.



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

time_series

usage: hspfbintoolbox time_series [-h]
                                  hbnfilename interval [labels [labels ...]]

DEPRECATED: Use 'extract' instead.

positional arguments:
  hbnfilename
  interval
  labels

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