Evaluation Declaration Example 5

# NOTE: Execution of this evaluation requires access to NWC-hosted WRDS services. You
# will not be able to execute this evaluation, as is, unless you are on a machine that
# can access those services. To execute, be sure to replace "[WRDS]" with the correct
# WRDS services URL. If you are not sure of that URL, contact the WRES team.

# This example illustrates how to incorporate data from the sources USGS NWIS, and NWM
# and AHPS forecasts served through WRDS services hosted at the NWC. Each source has 
# its own unique requirements for use, as described below. In this case, the NWM 
# medium-range channel routing forecasts are being evaluated against USGS observations
# and compared to AHPS forecasts for the same locations. To determine features, the 
# user is defining one feature explicitly, while using WRDS location services to 
# identify other features.
label: Example 5

# The WRES knows how to connect to the USGS NWIS IV service, allowing for the 
# acquisition of instantaneous values; at present, that is the only USGS service
# to which it can connect. In this case, instantaneous streamflow values are obtained 
# by specifying the USGS variable code 00060. The features for which data is acquired
# is specified by the "features" tag below.  The dates for which data is acquired 
# are specified by the "valid_dates".
observed:
  label: USGS NWIS Observed Flows
  sources:
    uri: https://nwis.waterservices.usgs.gov/nwis/iv
    interface: usgs nwis
  variable: "00060" 
  feature_authority: usgs site code
  type: observations

# The forecasts being evaluated are NWM medium-range forecasts provided via WRDS
# services. Note that the interface is "wrds nwm" and the variable "streamflow" 
# (for channel routing data). Though the "feature authority" is included, it is 
# unnecessary since the "wrds nwm" interface is specified so that the authority is
# already known.
predicted:
  label: WRDS NWM MRF Single Valued Streamflow Forecasts
  sources:
    uri: https://[WRDS]/api/nwm3.0/v3.0/ops/medium_range
    interface: wrds nwm
  variable: streamflow
  feature_authority: nwm feature id
  type: single valued forecasts

# The NWM forecasts are compared against AHPS forecasts. The interface is 
# specified as "wrds ahps", and the "uri" contain the service address for the
# WRDS AHPS data service. The variable is specified as a SHEF code physical
# element (i.e., the PE in SHEF PEDTSEP), and must match that of the desired
# data. The attribute "seperate_metrics" is included to ensure that the 
# metrics are computed separately for the baseline dataset, as well as the 
# predicted dataset (and the skill score).
baseline:
  label: AHPS Single Valued Flow Forecasts
  sources:
    uri: http://[WRDS]/api/rfc_forecast/v2.0/forecast/streamflow
    interface: wrds ahps
  variable: QR
  feature_authority: nws lid
  type: single valued forecasts
  separate_metrics: true

# NOTE: Feature declaration examples are provided below for individual features
# and features obtained from a feature service. It is highly recommended you only 
# run this evaluation for either the individual feature or one of the two groups
# to keep the evaluation small. Comment out the features you do not want to use.

# The features to evaluate with each name originating from the feature authority 
# of the corresponding dataset orientation. See NOTE, above.
features:
  - {observed: "01631000", predicted: "5907079", baseline: FROV2}

# A feature service can be defined to declare groups of features to include
# in an evaluation, or to "crosswalk" identifiers with known but different 
# "feature authority". See NOTE, above.
feature_service:
  uri: https://[WRDS]/api/location/v3.0/metadata
  groups:
    # Employs a tag provided by WRDS location services to identify all known USGS
    # Gages-II reference gauges that are headwater locations.
    - group: tag
      value: usgs_gages_ii_ref_headwater
    # Includes all features that the featureService knows about that are in the
    # state of Alabama.
    - group: state
      value: AL

# The measurement unit.
unit: CFS

# NOTE: The WRDS NWM forecast service only serves recent NWM forecast data. Adjust
# the dates below to be for a week within the past month to ensure that data is 
# available. 

# The reference dates restrict forecasts included in evaluation to those with 
# issued date/times within the specified range. This is required for ingesting
# data from the WRDS AHPS and NWM forecast services and dictates the range of those
# forecasts acquired. See NOTE, above.
reference_dates:
  minimum: 2020-03-19T00:00:00Z
  maximum: 2020-03-26T00:00:00Z

# The dates restricts the data evaluated (i.e., the pairs constructed) to that 
# with valid times within the specified range. This is required for ingesting data
# from USGS NWIS and dictates the range of that data acquired. See NOTE, above.
valid_dates:
  minimum: 2020-03-19T00:00:00Z
  maximum: 2020-03-29T00:00:00Z

# The evaluation is restricted to 72-hours, because the AHPS forecasts are only
# available for about 3 days, in most cases.
lead_times:
  minimum: 0
  maximum: 72
  unit: hours

# Due to the inconsistent nature of the AHPS issued dates, which do not line up 
# with forecast synoptic times, ingesting AHPS data also requires that lead time
# pooling windows be included in order to group pairs by lead times. The 
# configuration below defines 4 x 6-hour pooling windows within the overall 24-hour 
# leadHours period defined above. By default, those windows are adjacent; i.e. 
# non-overlapping.
lead_time_pools:
  period: 6
  frequency: 6
  unit: hours

# Indicate that AHPS and NWM MRF forecasts are to be cross-paired, so only
# pairs that line up by valid time and corresponding forecast reference time 
# are included. In this case, the forecast reference times do not require an
# exact match ("fuzzy"), as the AHPS forecasts are not issued at synoptic times.
cross_pair: fuzzy

# The metrics.
metrics:
  - sample size
  - mean square error skill score

# The format to use when writing durations to numeric outputs.
duration_format: hours

# The output formats to write.
output_formats:
  - csv
  - png