hspfbintoolbox.extract

hspfbintoolbox.extract(hbnfilename, interval, *labels, start_date=None, end_date=None, sort_columns=False)

Extracts data from a HSPF binary output file.

Parameters:

• hbnfilename (str) – The HSPF binary output file. This file must have been created from a completed model run.

• interval (Literal['yearly', 'monthly', 'daily', 'bivl']) – 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 (str) –

  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.

• start_date (str) –

  [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 (str) –

  [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 (bool) –

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