BasinComps

DESCRIPTION

This utility is used to write time series hyetograph data to DSS &/or output
equivalent reports to a text file. When written to DSS the results are written
as a regular time series record, one record per polygon/subbasin, and the TIN
timespan determines the time series timespan.

This entry point can process multiple shape files specified on the command
line (-basinFile option) or in a control file (-basinFileList option) or a
combination of both.

It can compute the basin averages for those files using multiple TINs specified
on the command line (-tinFile and -tinPath options) or in a control file (-tinFileList option)
The specification of the TIN filenames &/or pathnames can be optionally masked
using the standard '*' and '?' characters or it can use date masking along
with the applicable -sTime, -eTime, and -dTime command line options. Optional
arguments are also available to move the input TIN prior to performing any computations.

USAGE

BasinComps ( -tinFileList file | (-tinFilefileSpec...) (-tinPath pathSpec...) )
( -basinFileList file | (-basinFile fileSpec...) )
[-sTime time] [-dTime timespan] [-eTime time]
[-tinInputInterval timeInterval] [-instantaneousInput]
[-readTimeZone timeZone] [-bPartColumn columnName] [-polyline]
[-center centerpoint] [-move moveArg]
[-gridCell | -TINSurface]
[-shiftInTime timespan]
[-zone] [-SI | -EN] [-outputUnits units] [-writeTimeZone timeZone]
[-cPart cPathPart] [-timeSeriesOutputInterval timeInterval]
[-instantaneousOutput] [-saveType saveType] [-outputFormat format]
[-textOutFile file] [-dssOutFile file] [-test] [-verbose]

OPTIONS

-tinFileList file

Specifies the input file that holds a list of the input file and path specifications.
This option is always processed first. Other command line options may override
contents of this control file.

Use 'tinFile:' and 'tinPath:' in file to denote files and DSS
paths/pathmasks repsectively.

Note that file masking is not supported for DSS files.
Use an * in column 1 for comments. Blank lines are ignored.

-tinFile filespec

Multiple filespecs can be used. The filespec can be a simple filename or can
contain masks.

-tinPath pathSpec

The DSS path or mask to use. Multiple paths can be specified. If this is
specified, then all filesspecs that end in '.dss' are considered to be
DSS files. Any pathSpecs can use masks.

-basinFileList file

Specifies the input file that holds a list of the basin shape files.
Use 'shapefile:' to denote files/filemasks. Currently all basins/polygons
must be contained in shapefiles.
Use an * in column 1 for comments. Blank lines are ignored.

-basinFile fileSpec

Multiple fileSpecs can be used. The filespec can be a simple filename or
can contain the standard filemasks '?' and '*'. as well. Any fileSpecs containing
the characters * or ? should be in quotes to keep the operating system
shell from expanding them. If date masks are used the timespan must be specified.

Sample filespecs:
C:/shapefiles/MyProject.shp - Use the specified shapefile.
"C:/shapefiles/*.shp" - Use all shapefiles in the specified directory.

-tinInputInterval timeInterval

Used to constrain the TINs to the specified time interval. This option is only needed
when using file/path masks.

Refer to -dTime option for applicable formats. Use this option to ensure that the program
uses only TINs with a specific time interval for computations.

For example use '-tinInputInterval 1Hour' to ensure that files or paths which
match the given file/path masks are also 1 hour time interval.

-instantaneousInput

Identifies that the input data is instantaneous. If this flag is not used,
the duration of each image is assumed to be equal to the interval. This
is only necessary when using path masking with dates. Once the files are
read, the metadata is parsed to determine if the data is instantaneous.

-readTimeZone timeZone

Override of the read time zone. If specified, the time zone specified
in the input file's metadata will be ignored, and replaced with the
time zone specified at the command line.

A listing of the available time zones can be found at
https://en.wikipedia.org/wiki/List_of_tz_database_time_zones. The TZ
database name should be passed in as the argument. It's preferred to use
time zone specifications with the Canonical status if possible.

-bPartColumn columnName

Specifies the column name from the shape file DBF file that holds the
DSS B pathname part. If not specified, the program will use the following
column names in the order in an attempt to find a valid B part:
NAME, LOCATION, ID, DSSB, and STATION.

If none of these are available, the program will generate a B part to use.
Note that every polygon in the shape file should have a unique B path part.

If multiple shape files are specified that contain the same B path parts,
the column names DSSA and DSSF can be used to help create unique pathnames.
The text output will also use this column name.

-polyline

Used to include polyline data, and use it as basin polygons. The
default is to exclude shape files which contain non-polygon data.

-center lon:lat

Used to specify the centerpoint in decimal degrees to perform any
storm rotations. e.g. '-center -95.9264:36.0426'.

-move (lon:lat:rot | x:y:rot:units)

Specifies how to move the TIN prior to performing computations. Leaving
a value blank will set it to zero.

e.g. -move ::30 will rotate the TIN 30 degrees CCW. -move 2:1:0 will
move the TIN 2 degrees east and 1 degree north.

e.g. -move -22:-18:30:miles will rotate the TIN 30 degrees CCW and then
translate the TIN 22 miles west and 18 miles south.

If both a translation and rotation is specified, the rotation will occur
prior to the translation. If a non-zero translation is specified, the
-center argument must be used to specify the rotation centerpoint.

-gridCell

If specified and processing gridded datasets, the grid cell values are
considered to be spatial average values. Without this option, the center
of each grid cell is treated as a point value.
If processing non-gridded data, this option will be ignored although a
warning may be issued.

-TINSurface

If specified, the TIN dataset is processed as a TIN surface,
regardless of whether it is gridded or not.
This is the default if neither -gridCell or -TINSurface is specified.

-shiftInTime timespan

The amount of time to shift the image from its encoded time.
The formats are the same as for the -dTime option with the additional
specification that the timespan can be negative. e.g. -06:00:00

-zone

Specifies to compute and output any defined zonal data. All zone
hyetographs will be written with a DSS A path part of ZONE.
Zones are defined using the shapefile DBF files. Refer to the MetVue user
manual for instructions on defining zones.

-SI

Specifies depth, area and volume units as "mm", "sq km" and "m^3", respectively
for text output reports.

-EN

The default unit system if neither -SI or -EN specified.
Specifies depth, area and volume units as "in", "sq mi" and "ac-ft", respectively
for text output reports.

-outputUnits units

Units of the output data. Refer to supported Unit Aliases for the allowed units specifications.

Default is the units of the input data.

If the outputUnits are not set, and the input units are a depth
(i.e. ft, meters), then output units will default to "in" or "mm" depending on
which unit system argument (-EN or -SI) is used.

-writeTimeZone timeZone

Specifies the time zone for which the output data will be written. If
not specified, the output will be written in the time zone of the input data.

A listing of the available time zones can be found at
https://en.wikipedia.org/wiki/List_of_tz_database_time_zones. The TZ
database name should be passed in as the argument. It's preferred to use
time zone specifications with the Canonical status if possible.

-cPart cpart

Used to define the DSS C path part. The default is PRECIP-INC if nothing
is specified.

-timeSeriesOutputInterval timeInterval

Output interval for the time series e.g. '3Hours'. Default is equal to
the input interval.

-instantaneousOutput

Using this flag will write instantaneous output. If not used, then the
output time series will have a duration equal to the interval.

-saveType saveType

saveType can be either 'intersection' or 'total'. The default is 'total' if not defined.
If set to 'intersection', then only the polygon areas that are covered by a defined TIN are used.
If set to 'total', then the entire polygon area will be used for average computation regardless of TIN coverage.

-outputFormat fmt

Specifies the output the format. Options are:
tabular - This is the default if not specified. It is columnar output that is easy to read.
legacy_forecast - This is used for backwards compatibility with some legacy software.
csv - Uses a DSSVue formatter to write the data to a text file.
csv_alt1 - A format designed to make loading the data into a spreadsheet or database straightforward.
Each row contains a polygon average for a single time interval.

-textOutFile file

Specifies a text output filename. This is optional, and output will go to
stdout if not specified.

-dssOutFile file

Specifies the DSS filename for the output time series. If not specified,
no time series data will be written to DSS.

-test

Reports information on filenames and paths to be read, but do not process data.

-verbose

Give detailed output of files and paths etc.

SAMPLE COMMAND LINE ARGUMENTS

For all TIN files matching the given file mask compute the basin average and
write it to the given DSS and text files. Use the column name 'SNAME' from
the DBF file for the B path part. Compute and write zonal values also.
-tinfile "C:\rainfiles\??may2017.rf" -basinfile "C:\shapefiles\coun.polygon.shp"
-zone -bpartcolumn SNAME
-dssoutfile "C:\daily\basinAvg.dss" -textoutfile "C:\daily\outfile.txt"

Read matching paths from a DSS file that matches the given path masks
from 10 days ago to the current time. Print detailed information on the process
to the console.
-tinFile "C:\radar\data.dss" -tinPath "\HRAP\LMRFC\PRECIP-INC\\\\"
-sTime T -eTime "T-10D"-dssoutFile "C:\obs\radar.dss" -verbose

Read matching paths from a DSS file that matches the given path masks
from 10 days ago to the current time. Specify the center of the storm, rotate
the TIN 30 degrees CCW and then translate the TIN 22 miles west and 18 miles south
-tinFile "C:\radar\data.dss" -tinPath "\HRAP\LMRFC\PRECIP-INC\\\\"
-center -95.9264:36.0426 -move -22:-18:30:miles
-dssoutFile "C:\obs\radar.dss" -sTime T -eTime "T-10D"

Arguments shown in brackets are optional.

Use double quotes for options that have spaces or special characters.

NOTE FOR WINDOWS USERS

Any command line arguments containing a % sign needs to be escaped in order
to work.

For example The command:

-tinFile "C:\radar\%s:ddMMMyy%.dss" -tinPath "\HRAP\LMRFC\PRECIP-INC\\\\"
-dssoutFile "C:\obs\radar.dss" -sTime T -eTime "T-10D" -verbose

becomes:

-tinFile "C:\radar\%%s:ddMMMyy%%.dss" -tinPath "\HRAP\LMRFC\PRECIP-INC\\\\"
-dssoutFile "C:\obs\radar.dss" -sTime T -eTime "T-10D" -verbose

Additionally, if the units of % are required for the -outputUnits argument, the units should
be specified as %% (or use the string "Percent" or "PERCENT") to work properly.

NOTE ON PERFORMANCE

This program may utilize a significant amount of memory depending on datasets specified.
   For extra intensive data operations, it may be necessary to increase the memory allocated
   to the jvm. This can be performed by setting the -Xmx argument, which can be altered
   easily in the "memory_setting" variable in the BasinComps.cmd example file provided.