+

NseQuarts Guide

Overview

As part of its results, the VELMA simulator generates a "final" Nash-Sutcliffe Efficiency value for runoff, as well as annual values. However, quarterly runoff NSE values have also proven useful in analyzing simulator runoff behavior during calibration efforts.

The VELMA simulator does not provide automatic generation of quarterly runoff NSE values, but the NseQuarts Python utility script can generate them from post-simulation results combined with the observed runoff used as part of the input data.

Requirements

Limitations

Usage

Open a Windows Powershell or Command Prompt and type the following command:

py -3 NseQuarts.py --help

Depending upon where the NseQuarts.py script is located, you may need to include full or partial path info as part of its name.
The command above assumes it is being run in the directory where NseQuarts.py is located.
Running the command above echoes NseQuarts.py's help message to your console:

usage: NseQuarts.py [-h] simRunoffFilename obsRunoffFilename year
 
Computes annual and quarterly runoff NSE values for specified VELMA data.
 
positional arguments:
  simRunoffFilename  The DailyResults.csv file from a VELMA simulator results folder (provides the simulated runoff
                    values).
  obsRunoffFilename  The MOEA-formatted .csv file containing the observed runoff values for same VELMA simulation run
                    as simRunoffFilename.
  year               The year within the VELMA simulator run's range to generate quarterly NSE values for.
 
optional arguments:
  -h, --help         show this help message and exit

Per the help message above:

  1. You must specify the DailyResults.csv file from a VELMA simulator results folder as the source of your simulator runoff value.
    The DailyResults.csv file must appear as the first argument of the command line.
    You must include whatever path information is necessary to find the file.
    The file must be a DailyResults.csv file -- no other .csv file or format is allowed.
    (The NseQuarts.py script is hardwired to find runoff data by a specific column name.)

  2. You must specify a file containing observed runoff data as the second argument of the command line.
    The observed runoff file must be "MOEA formatted": i.e. a .csv file with 3 values per row.
    The values in order are: YEAR, DAY_OF_YEAR, and OBSERVED_VALUE, where YEAR and DAY_OF_YEAR are integer values within valid respective ranges, and the OBSERVED_VALUE is a floating-point value representing an observed runoff amount in units of millimeters of water.

  3. You must specify the simulation year you wish to generate quarterly NSE values for as the third argument of the command line.
    The year must be an integer value, and the data for that year must exist and be complete (all 365 or 366 days) within both the simulated (DailyResults) and observed .csv files.

Example Usage

Remember: you will typically need to include paths in the file names. Paths have been omitted in this example to keep the command line compact.

PS C:\Users\Me\Velma\My_Results> py -3 NseQuarts.py DailyResults.csv My_Obs_Runoff.csv 2020
Year,Q_Name,Jday_Range,NSE_Value
2020,All,[1-366],0.7845631459960574
2020,Q1,[1-92],0.7381363311608637
2020,Q2,[93-183],0.7932735462074367
2020,Q3,[184-274],0.5355080821221985
2020,Q4,[275-366],0.8337491857897329

As the example above shows, output is to the console (stdout) and is comma-separated (for easy copy-paste into a spreadhseet or .csv file).
After a header row, each row of output contains, in order:

  1. The year the NSE values are calculated for (the Year column).
  2. The range name (the Q_name column).
  3. The range as its actual pair of day-of-year inclusive bounds values (the Jday_Range column).
  4. The actual NSE for that range (the NSE_Value column).

Output to Files

The NseQuarts.py script outputs its results directly to your console. There is no option for saving the results directly to a file, however you can capture the output into a file using various console options.

For Windows PowerShell, we recommend capturing the output via a pipeline combined with the PowerShell Out-File cmdlet.
Here is the previous Usage example, plus the additional command line syntax to capture the output to a file named "my2020_quarts.csv" instead of to the console itself:

PS C:\Users\Me\Velma\My_Results> py -3 NseQuarts.py DailyResults.csv My_Obs_Runoff.csv 2020 | Out-File -Encoding ASCII -FilePath my2020_quarts.csv

The pipe ("|") symbol tells PowerShell to take the output of command on its left (the NseQuarts.py command) and pass it to the command its right (the Write-Output cmdlet).

The Out-File cmdlet can be used in various ways and for various situations, but what we want it to do here is:

  1. Force the output to be ASCII-encoded (so that Excel can unambiguously open our resulting file as .csv data).
  2. Save the output to the file "my2020_quarts.csv" specified by the -FilePath argument.

We force the output to be ASCII because PowerShell's default encoding is Unicode. If you omit the -Encoding ASCII argument, the output is written to the file as Unicode characters. If you then open the file in Excel, you may find Excel has interpreted the contents as 6 rows of 1 column each, instead of 6 rows of 4 columns each, because Excel did not auto-detect the comma (",") character. Whether this actually happens depends on how your Excel and Windows enviroments are configured. If you find you don't need the -Encoding ASCII option, feel free to omit it.