NashSutcliffeCalculator : A Tool for Computing Nash-Sutcliffe Coefficients

This guide explains how to use the NashSutcliffeCalculator utility.

Background

The VelmaSimulator engine automatically calculates a Nash-Sutcliffe coefficient for simulated-vs-observed watershed runoff values, but only if the following conditions are met:

1. Observed runoff values are available for every day of driver data specified for the simulation run.
2. Those observed runoff values are available in a properly-formatted .csv file, and that file is specified in the VELMA Simulation Configuration .xml file for the simulation run.

Often, only partial or sparse observed runoff data is available for a given simulation site, or full runoff data only becomes available at some point after simulation runs have been completed.
In these cases, the NashSutcliffeCalculator utility can be used to compute a Nash-Sutcliffe value after the simulation run is completed, and can utilize partial or sparse observed data if that is all that is available.

When NashSutcliffeCalculator is run from a command-line with the names of observed and simulation data files, it finds and pairs all the corresponding obs, sim data values, then computes the Nash-Sutcliffe coefficient for those data pairs.

Platform Requirements and Runtime Notes

Running NashSutcliffeCalculator as a command-line utility requires the following:

• Java 1.8 JRE (new versions should also work, but older versions -- e.g. 1.7 -- will not).
• Windows 10 (although the tool is not Windows-specific, Windows it the only platform it has been tested on).
• Windows Powershell (other shells should work, but PowerShell is the command shell it has been tested on).
• Access to either a JVelma .jar file (the NashSutcliffeCalculator is included in it)
  or
  Access to the VELMA source code and a way to generate the .class files for at least the VelmaUtils/bin directory tree. (This is usually done by cloning a local copy of the VELMA project into an Eclipse workspace.)

Step-by-Step Instructions

1. Determine Observed and Simulation Data File Sources

You must provide Nash-Sutcliffe with two comma-separated value (.csv) files:

An Observed Data File

• Must contain 3 values per row, in this order: YEAR, JDAY, VALUE
  1. YEAR must be a YYYY integer value.
  2. JDAY must be a JJJ (range [1, 366]) Julian day value.
  3. VALUE must be a floating-point data value.
• Must NOT contain a header row.

A Simulation Data File

• Must contain the following data, in the following (zero-based) column positions:
  1. LOOP (an integer value) in column 0.
  2. YEAR (a YYYY integer value) in column 2.
  3. JDAY (a JJJ range [1, 366] value) in column 3.
  4. VALUE must be a floating-point data value in column 9.

The DailyResults.csv file generated as part of the standard results of a VELMA simulation run exactly meets the Simulation Data File requirements.

2. Run NashSutcliffeCalculator from a PowerShell Window

Running from a .jar file

The command must include the location of the JVelma.jar file.
(The NashSutcliffeCalculator engine and main() method are included in JVelma.jar.)
A template for the command is:

java -cp C:\path\to\JVelma.jar gov.epa.velmautils.NashSutcliffeCalculator --obsFile=C:\full\path\to\obs.csv --simFile=C:\full\path\to\sim.csv

Running from a VELMA Eclipse Workspace

The command must include the location of VelmaUtils\bin within the Eclipes VELMA workspace.
A template for the command is:

java -cp C:\path\to\Velma\VelmaUtils\bin gov.epa.velmautils.NashSutcliffeCalculator --obsFile=C:\full\path\to\obs.csv --simFile=C:\full\path\to\sim.csv

Using NashSutcliffeCalculator within Java code

1. Create Java File objects for the observed and simulation data files.
   (Also: perform any file-validation and "bad file" handling deemed necessary by your code.)

File obsFile = new File("C:/full/path/to/obs.csv");
File simFile = new File("C:/full/path/to/sim.csv");

1. Create a NashSutcliffeCalulator object, and pass the the obs and sim File objects to its constructor.

NashSutcliffeCalculator nsCalc = new NashSutcliffeCalculator(obsFile, simFile);

1. Set desired options by calling appropriate set..() methods on the NashSutcliffeCalculator object.
   Options available when calling NashSutcliffeCalculator via a command line are also available via setter methods.
   Important: Set options before calling generateCoefficient()!
   For example:

nsCalc.setSimMinYear(2010)

is the source code equivalent to specifying

--setSimMinYear=2010 

on the command line. 4. Call the generateCoefficient() method to compute the coefficient value for the specified obs and sim data files, taking into account any