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.10 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] [--header HEADER] [--tablefmt TABLEFMT]
[--float_format FLOAT_FORMAT]
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
--header HEADER [optional, default is "default"]
The header for the print out version of the catalog.
The "default" header is: ["LUE", "LC", "GROUP", "VAR", "TC", "START", "END",
"TC"]
--tablefmt TABLEFMT [optional, default is 'cvs_nos']
The table format. Can be one of 'csv', 'tsv', 'csv_nos', 'tsv_nos',
'plain', 'simple', 'github', 'grid', 'fancy_grid', 'pipe', 'orgtbl',
'jira', 'presto', 'psql', 'rst', 'mediawiki', 'moinmoin', 'youtrack',
'html', 'latex', 'latex_raw', 'latex_booktabs' and 'textile'.
--float_format FLOAT_FORMAT
[optional, default is 'g']
The format for floating point numbers in the output table.
extract¶
usage: hspfbintoolbox extract [-h] [--start_date START_DATE]
[--end_date END_DATE] [--sort_columns]
[--tablefmt TABLEFMT]
[--float_format FLOAT_FORMAT]
hbnfilename interval [labels ...]
Extracts 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.
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.
--tablefmt TABLEFMT [optional, default is 'cvs_nos']
The table format. Can be one of 'csv', 'tsv', 'csv_nos', 'tsv_nos',
'plain', 'simple', 'github', 'grid', 'fancy_grid', 'pipe', 'orgtbl',
'jira', 'presto', 'psql', 'rst', 'mediawiki', 'moinmoin', 'youtrack',
'html', 'latex', 'latex_raw', 'latex_booktabs' and 'textile'.
--float_format FLOAT_FORMAT
[optional, default is 'g']
The format for floating point numbers in the output table.
