Usage¶
Just run “swmmtoolbox –help” from a command line to get a list of subcommands:
swmmtoolbox --help
usage: swmmtoolbox [-h]
{about,catalog,extract,listdetail,listvariables,stdtoswmm5}
...
positional arguments:
{about,catalog,extract,listdetail,listvariables,stdtoswmm5}
about Display version number and system information.
catalog List the catalog of objects in output file.
extract Get the time series data for a particular object and
variable.
listdetail List nodes and metadata in output file.
listvariables List variables available for each type.
stdtoswmm5 Take the toolbox standard format and return SWMM5
format.
options:
-h, --help show this help message and exit
Sub-command Detail¶
extract¶
usage: swmmtoolbox extract [-h] filename [labels ...]
Get the time series data for a particular object and variable.
positional arguments:
filename Filename of SWMM output file. The SWMM model must complete
successfully for "swmmtoolbox" to correctly read it.
labels The remaining arguments uniquely identify a time-series
in the binary file. The format is:
'TYPE,NAME,VAR'
For example: 'link,41a,Flow_rate node,C63,1 ...'
The VAR part of the label can be the name of the variable or the index. The
available variables and their indices can be found using:
'swmmtoolbox listvariables filename.out'
All of the available labels can be listed with:
'swmmtoolbox catalog filename.out'
There is a wild card feature for the labels, where leaving the part out will
return all labels that match all other parts. For example,
┌─────────────────┬─────────────────────────────────────┐
│ link,b52, │ Return all variables for link "b52" │
├─────────────────┼─────────────────────────────────────┤
│ link,,Flow_rate │ Return "Flow_rate" for all links │
╘═════════════════╧═════════════════════════════════════╛
Note that all labels require two commas and no spaces.
options:
-h | --help
show this help message and exit
list¶
usage: swmmtoolbox catalog [-h] [--itemtype ITEMTYPE] [--tablefmt TABLEFMT]
[--header HEADER] filename
This catalog list is all of the labels that can be used in the extract routine.
positional arguments:
filename Filename of SWMM output file. The SWMM model must complete
successfully for "swmmtoolbox" to correctly read it.
options:
-h | --help
show this help message and exit
--itemtype ITEMTYPE
One of 'system', 'node', 'link', or 'pollutant' to identify the type of
data you want to extract.
--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.
listdetail¶
usage: swmmtoolbox listdetail [-h] [--name NAME] [--tablefmt TABLEFMT]
[--header HEADER] filename itemtype
List nodes and metadata in output file.
positional arguments:
filename Filename of SWMM output file. The SWMM model must complete
successfully for "swmmtoolbox" to correctly read it.
itemtype One of 'system', 'node', 'link', or 'pollutant' to identify the
type of data you want to extract.
options:
-h | --help
show this help message and exit
--name NAME
[optional, default is '']
Specific name to print only that entry. This can be looked up using
'listvariables'.
--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.
listvariables¶
usage: swmmtoolbox listvariables [-h] [--tablefmt TABLEFMT] [--header HEADER]
filename
The type are "subcatchment", "node", "link", "pollutant", "system".
positional arguments:
filename Filename of SWMM output file. The SWMM model must complete
successfully for "swmmtoolbox" to correctly read it.
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.
stdtoswmm5¶
usage: swmmtoolbox stdtoswmm5 [-h] [--start_date START_DATE]
[--end_date END_DATE] [--input_ts INPUT_TS]
Toolbox standard:
Datetime, Column_Name
2000-01-01 00:00:00 , 45.6
2000-01-01 01:00:00 , 45.2
...
SWMM5 format:
; comment line
01/01/2000 00:00, 45.6
01/01/2000 01:00, 45.2
...
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.
--input_ts INPUT_TS
[optional though required if using within Python, default is '-' (stdin)]
Whether from a file or standard input, data requires a single line header
of column names. The default header is the first line of the input,
but this can be changed for CSV files using the 'skiprows' option.
Most common date formats can be used, but the closer to ISO 8601 date/time
standard the better.
Comma-separated values (CSV) files or tab-separated values (TSV):
File separators will be automatically detected.
Columns can be selected by name or index, where the index for
data columns starts at 1.
Command line examples:
┌─────────────────────────────────┬───────────────────────────┐
│ Keyword Example │ Description │
╞═════════════════════════════════╪═══════════════════════════╡
│ --input_ts=fn.csv │ read all columns from │
│ │ 'fn.csv' │
├─────────────────────────────────┼───────────────────────────┤
│ --input_ts=fn.csv,2,1 │ read data columns 2 and 1 │
│ │ from 'fn.csv' │
├─────────────────────────────────┼───────────────────────────┤
│ --input_ts=fn.csv,2,skiprows=2 │ read data column 2 from │
│ │ 'fn.csv', skipping first │
│ │ 2 rows so header is read │
│ │ from third row │
├─────────────────────────────────┼───────────────────────────┤
│ --input_ts=fn.xlsx,2,Sheet21 │ read all data from 2nd │
│ │ sheet all data from │
│ │ "Sheet21" of 'fn.xlsx' │
├─────────────────────────────────┼───────────────────────────┤
│ --input_ts=fn.hdf5,Table12,T2 │ read all data from table │
│ │ "Table12" then all data │
│ │ from table "T2" of │
│ │ 'fn.hdf5' │
├─────────────────────────────────┼───────────────────────────┤
│ --input_ts=fn.wdm,210,110 │ read DSNs 210, then 110 │
│ │ from 'fn.wdm' │
├─────────────────────────────────┼───────────────────────────┤
│ --input_ts='-' │ read all columns from │
│ │ standard input (stdin) │
├─────────────────────────────────┼───────────────────────────┤
│ --input_ts='-' --columns=4,1 │ read column 4 and 1 from │
│ │ standard input (stdin) │
╘═════════════════════════════════╧═══════════════════════════╛
If working with CSV or TSV files you can use redirection rather than use
--input_ts=fname.csv. The following are identical:
From a file:
command subcmd --input_ts=fname.csv
From standard input (since '--input_ts=-' is the default:
command subcmd < fname.csv
Can also combine commands by piping:
command subcmd < filein.csv | command subcmd1 > fileout.csv
Python library examples:
You must use the `input_ts=...` option where `input_ts` can be
one of a [pandas DataFrame, pandas Series, dict, tuple, list,
StringIO, or file name].
