GetUSGS Ratings Script using CDA

The code for this example can be found in the cwms-cli repo: https://github.com/HydrologicEngineeringCenter/cwms-cli. This script requires cwms-python 0.6.0 or greater, and CDA version 2025.03.05 or greater. If you need to update cwms-python on your server simply run the following to update to the latest released version.  The script also requires cwms-cli.

pip3 install -U cwms-python
pip3 install -U cwms-cli

or 

python3 -m pip install -U cwms-python
python3 -m pip install -U cwms-cli


The rating script needs both a rating spec, with the correct parameters set, as well as a USGS ID assigned to the Location in the Location group "Agency Aliases"->"USGS Station Number".  The following are the specific instruction for setting up the script. 

Rating Spec requirements for getUSGS rating script

  • For a rating to be populated by the getUSGS_rating_CDA.py script, the following parameters need to be set in the rating specification. This information can be accessed in CWMS-Vue (There is a tool to automate these changes for initial setup detailed in the next section). Select the rating spec to be edited, right click and select “Edit Rating Specification”.
    • Source Agency = USGS
    • The rating spec needs to be Active.
    • The rating spec needs to have Auto Update checked.
    • One of the following texts needs to be in the rating spec description to match the type of USGS rating that should be collected.
      • USGS-EXSA
      • USGS-CORR
      • USGS-BASE
  • The Auto Activate parameter will automatically set the new saved rating curve as Active when downloaded from the USGS.  If you want the new downloaded rating curve to be unactive, then uncheck the box in the rating spec.  By default this box will be checked.  Below is an example of an active rating curve.
  • If the Auto Migrate box is checked then any rating extensions attached to the most recent rating curve will be copied to a newly downloaded rating curve from the USGS. By default, this box is checked.  Below is an example of a rating curve extension.

Script to transition from existing updateRating script to new rating spec requirements

To make the transition to the new rating spec requirements easier, a script was created to automatically set the correct rating spec parameters for any ratings in the .ini file used in the original updateRatings.py server side script. 

  • Install cwms-cli.
  • Run the following:
cwms-cli usgs ratings-ini-file-import -f ratings.ini -a $CWBI_TEST_API_ROOT -kl $CWMS_HOME/.cwms/cwbi_test_api_key
C:\Soft\environment>cwms-cli usgs ratings-ini-file-import --help
Usage: cwms-cli usgs ratings-ini-file-import [OPTIONS]

  Store rating ini file information into database to be used with
  getusgs_ratings

Options:
  -f, --filename TEXT      filename of ratings ini file to be processed
                           [required]
  -a, --api-root TEXT      Api Root for CDA. Can be user defined or placed in
                           a env variable CDA_API_ROOT  [required]
  -k, --api-key TEXT       api key for CDA. Can be user defined or place in
                           env variable CDA_API_KEY. one of api-key or api-
                           key-loc are required
  -kl, --api-key-loc TEXT  file storing Api Key. One of api-key or api-key-loc
                           are required
  --help                   Show this message and exit.
  • An example .ini file is shown below.
  • The script will loop through each rating spec specified in the .ini file and set the following parameters.
    • Rating Spec source = USGS
    • Rating Spec Active = True
    • Rating Spec Auto Update = True
    • Rating Spec Auto Activate = True
    • Append the Rating Spec description with either USGS-EXSA, USGS-CORR, or USGS-BASE depending on the designation in the ini file of store_exsa, store_corr, store_base.

Location Group requirements for rating spec scripts

Setup and run getUSGS rating scrip on T7 server.

cwms-cli usgs ratings -d 2 -o MVP -a $CWBI_TEST_API_ROOT -kl $CWMS_HOME/.cwms/cwbi_test_api_key

                            

C:\Soft\environment>cwms-cli usgs ratings --help
Usage: cwms-cli usgs ratings [OPTIONS]

  Get USGS ratings and store into CWMS database

Options:
  -o, --office TEXT          Office to grab data for  [required]
  -d, --days-back FLOAT      Days back from current time to get data.  Can be
                             decimal and integer values
  -a, --api-root TEXT        Api Root for CDA. Can be user defined or placed
                             in a env variable CDA_API_ROOT  [required]
  -k, --api-key TEXT         api key for CDA. Can be user defined or place in
                             env variable CDA_API_KEY. one of api-key or api-
                             key-loc are required
  -kl, --api-key-loc TEXT    file storing Api Key. One of api-key or api-key-
                             loc are required
  -rs, --rating-subset TEXT  subset of rating spec ids to grab latest rating
                             for (e.g. "rating_spec_id1, rating_spec_id2").
  --help                     Show this message and exit.
    • The -d parameter designates how far back to look from the current day/time for an updated rating.  The USGS will post when specific ratings have been updated.  For example a -d 2 will only grab rating curves that have been updated in the past 2 days (48 hours) to be checked and saved.
    • If you have added a new rating spec that does not have any existing rating curves attached to it, the script will grab the most current rating curve from the USGS regardless of the -d parameter setting. 
    • The script will compare the effective dates from the USGS and the rating in the CWMS database for the most recent rating curve to see if the rating curve has already been saved.  It script will only save the rating curve if the effective dates are different.