Reach-Specific Observed Runoff Data for VelmaParallelCmdLine

Overview

As of VELMA version 2.1.0.20, VelmaParallelCmdLine supports the optional --obsRunoff=\ argument.
Use this argument to specify a table of outlet locations and associated observed runoff data files. When VelmaParallelCmdLine launches the VELMA simulator for a sub-reach, if that sub-reach's outlet in in the table, the observed runoff data file is used as the sub-reach's input_runoff, instead of the file specified (or not specfied) in the simulation configuration .xml file passed into VelmaParallelCmdLine.

Reach-Specific observed runoff data allows VelmaParallelCmdLine to compute accurate Nash-Sutcliffe Coefficients for the runoff of reach outlets other than the final reach outlet.

File Format and Requirements

If the file name specified by the --obsRunoff argument is not a fully-qualified path + name, then its location is assumed relative to the location where VelmaParallelCmdLine was invoked.

The specified file must have the following characteristics:

• NO header row.
• Exactly two columns per row, comma-separated.
• The first column must contain an integer value representing an outlet listed in the initialReachOutlets parameter of the Simulation Configuration .xml file passed to VelmaParallelCmdLine.
• The second column must contain a String value representing the name of a valid VELMA Observed Runoff data file. The specified file name will replace the input_runoff parameter when VelmaParallelCmdLine runs the reach outlet specified in the first column. The input_runoff parameter's naming rules apply:
  1. Fully-qualified path + name files are accepted as-is.
  2. Partial path or filename-only files are assumed relative to the inputDataLocationRootName/inputDataLocationDirName parameter pair from the Simulation Configuration .xml file passed to VelmaParallelCmdLine.
  3. Use the forward-slash / as a path separator.

Example

Here is an example .csv file, "CustomObsRunnoff.csv":

388,C:/Users/Meep/obsQ_1969-2008.csv
346,./m_7_Observed/ReachObs/obsRunoff_i346_TestB_perfect.csv
254,Some_Other_obsRunoff.csv
987,C:/Users/Meep/obsQ_1969-2008.csv

Suppose we invoke VelmaParallelCmdLine as follows:

C:\Users\Meep> java -Xmx1g -cp C:\Users\Meep\JVelma.jar gov.epa.velmasimulator.VelmaParallelCmdLine C:\Users\Meep\XML\OR_BR_ws10.xml --obsRunoff="D:\Data Repository\CustomObsRunnoff.csv" --maxProcesses=3

As the command line above indicates the .xml file is "OR_BR_ws10.xml".
Its initialReachOutlets parameter has this value:

388 321 346 251 254

and that the input data parameter values are:

inputDataLocationRootName = D:/My_VELMA_Data/OR_BlueRiver_ws10
inputDataLocationDirName  = DataInputs

and that the input_runoff value is unspecified (i.e. blank).

When VelmaParallelCmdLine runs, it combines the data from the .xml and .csv files above, leading to the following as each reach is run:

Reach Outlet	initial input_runoff	runtime input_runoff
388	blank	C:/Users/Meep/obsQ_1969-2008.csv
321	blank	blank
346	blank	D:/My_VELMA_Data/OR_BlueRiver_ws10/m_7_Observed/ReachObs/obsRunoff_i346_TestB_perfect.csv
251	blank	blank
254	blank	D:/My_VELMA_Data/OR_BlueRiver_ws10/Some_Other_obsRunoff.csv

Outlet 987 is not in initialReachOutlets, and will be ignored at runtime.
(That being said, it's better to exclude outlets that aren't in the initialReachOutlets list, simply to keep the contents as concise and clear as possible.)

An observed runoff data file name specified in the --obsRunoff argument that does not exist, or cannot be opened will cause that reach's simulation run to crash.
(i.e. just what happens for the same circumstances for the input_runoff value -- because it is the input_runoff value.)