GetUSGS Ratings Script using CDA

GetUSGS_rating_CDA script is located in github here  https://github.com/HydrologicEngineeringCenter/CWMS-data-acquisition-python/tree/main/src/get_USGS_rating

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.

pip3 install -U cwms-python


The getUSGS_rating_CDA.py 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 hit “Edit Rating Specification”
      • source agency = USGS
      • The rating spec needs to be Active
      • The rating specs 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 setup 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. 
    • Download the script rating_ini_file_import.py from the github repo. 
    • Place the script on your server in the same folder with the .ini rating file.
    • Run the following:


python3 rating_ini_file_import.py -f ratings.ini -a $CWBI_TEST_API_ROOT -kl $CWMS_HOME/.cwms/cwbi_test_api_key

  

                         

    • 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.



  • Setup and run getUSGS rating scrip on T7 server.
    • Once the Rating Specification parameters and Location Group setups are complete the getUSGS_rating_CDA.py script can be run from the server. 
    • Download the getUSGS_rating_CDA.py script from the github repo and place it in a folder on your server. 
    • Make sure that CDA, cwms-python, and an API key are properly setup.
    •  This script requires cwms-python 0.6.0, and CDA version 2025.03.05.  For setting up CDA and cwms-python including a updating to a new version please see the instructions. https://www.hec.usace.army.mil/confluence/spaces/CCM/pages/192381637/Setting+up+CDA+writes+and+cwms-python+on+T7s
    • To run the script run the following


python3 getUSGS_ratings_CDA.py -d 2 -o MVP -a $CWBI_TEST_API_ROOT -kl $CWMS_HOME/.cwms/cwbi_test_api_key

                           

                           

    • The -d parameter designates how far back to look from the USGS 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 effective date for the most recent rating curve in the CWMS database to see if the rating curve has already been saved.  It will only save the rating curve if the effective dates are different.