+
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
- A Windows Powershell or Command Prompt.
- Python 3 installed and available.
- Python's Pandas library installed for Python 3.
- The DailyResults.csv file from a VELMA simulator results.
- The observed runoff .csv file provided as part of the same VELMA simulator results' input data.
- The year to generate quarterly runoff NSE values for.
Limitations
- You must specify a year, and the data for that year must be complete (all 365 or 366 days) within both the simulated (DailyResults) and observed .csv files.
- The specified year's data cannot contain NaN values, either in the simulated or observed files.
- The observed data file must be "MOEA formatted".
- Output is only to console stdio (it may be redirected to a file using the console's commands).
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:
-
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.
(TheNseQuarts.py
script is hardwired to find runoff data by a specific column name.) -
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
, andOBSERVED_VALUE
, whereYEAR
andDAY_OF_YEAR
are integer values within valid respective ranges, and theOBSERVED_VALUE
is a floating-point value representing an observed runoff amount in units of millimeters of water. -
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:
- The year the NSE values are calculated for (the
Year
column). - The range name (the
Q_name
column). - The range as its actual pair of day-of-year inclusive bounds values (the
Jday_Range
column). - 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:
- Force the output to be ASCII-encoded (so that Excel can unambiguously open our resulting file as .csv data).
- 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.