Climate

AnnAGNPS requires daily climate data as representing the main watershed loads. As well as watershed scale rainfall and erosivity parameters

Variables

The parameters that the software accepts are:

Parameter	Unit	Description	Required?
Month	1-12 number		✅
Day	1-31 number		✅
Year	number		✅
Max_Air_Temperature	°C	Daily Maximum Temperature	✅
Min_Air_Temperature	°C	Daily Minimum Temperature	✅
Precip	mm	Precipitation	✅
Dew_Point	°C	Dew Point	✅
Sky_Cover	%	Percentage of sky that is masked by clouds	🟠 Not required if Solar_Radiation is provided
Solar_Radiation	W/m²	Shortwave sun radiation incoming	🟠 Not required if Sky_Cover is provided
Storm_Type_ID		Storm type see AnnAGNPS documentation and USDA publication TR-55	✖️
Potential_ET	mm	Potential Evapotranspiration for the day	✖️
Actual_ET	mm	Actual Evapotranspiration for the day	✖️
Actual_EI	MJ-mm/(ha.hr)	Actual EI value (storm intensity) for the day	✖️
Input_Units_Code	1 (SI) / 0 (Weird US Customary units)	Software flag to specify units, SI is preferred therefore use value 1	✅

Watershed scale erosivity and rainfall parameters

Additional parameters need to be provided for the entire watershed: The Erosivity Rain Factor R_factor, the 10_year_EI number, and the dominant EI zone EI_Zone. These parameters come from the RUSLE2 database and the TR-55 technical document. GIS layers have been put together to produce them and more details and GIS layers are provided in the following repo:

NRCS / RUSLE2 Climate Shapefile / SCS Storm Types

Climate Data sources

• NLDAS-2
• CMIP5, CMIP6 climate models

Climate data files generation

The pyagnps.climate.ClimateAnnAGNPSCoords Python class is used to handle the generation of AnnAGNPS climate files from various sources. The class is initialized with geographic coordinates of the desired climate station, the desired beginning and end dates, as well as an optional date mode to :

x, y = -76.8227548, 39.5317701
clm = pyagnps.climate.ClimateAnnAGNPSCoords(coords=(x,y), 
                                            start='2023-10-01', 
                                            end='2023-12-04', 
                                            date_mode='local')

The data is then read from static files on disk or queried using the NLDAS-2 API.

Querying NLDAS-2 Hydrology Data Rods (Easiest)

df = clm.query_nldas2_generate_annagnps_climate_daily()

This method directly queries the NASA GES-DISC API and is fairly fast and efficient. Ideal for smaller watersheds.

It is built upon the excellent pynldas2 library.

CMIP data:

Please refer to the relevant Dataset page above to learn about how to obtain the files that were used in this project.

from pathlib import Path
cmip_files = Path("Path/to/CMIP/Data/for/example/CMIP5/MACAv2METDATA/CNRM-CM5/r1i1p1/") 
# Under this specific climate realization can be two subdirectories: 1. "historical" and 2. the specific climate scenario e.g. "rcp45"
cmip_files = cmip_files.glob("**/*.nc")

df = clm.read_cmip5_maca_generate_annagnps_climate_daily(cmip5_files)

From a custom PostgreSQL/PostGIS database (you probably don't want to do this unless you want to create your own decision support system)

pyagnps also offers tools to download, preprocess, and populate climate data to a custom PostgreSQL with the TimescaleDB postgis extension. This steps assumes that you have a configured database as detailed in the relevant section of the NLDAS-2 page.

from sqlalchemy import URL, create_engine

db_url = URL.create(
                    "postgresql",
                    username="postgres",
                    password="dbpassword",
                    host="addressofthedatabase.xyz",
                    port=5432,
                    database="name_of_the_db"
                    )

engine = create_engine(db_url)

df = clm.generate_annagnps_daily_climate_data_from_db(engine='climate_nldas2')

Writing climate time series to disk

• AnnAGNPS requires at least one climate_daily.csv file and can easily be generated from the DataFrame:

df.to_csv('climate_daily.csv', float_format='%.2f')

• A climate_station.csv is also required and can be built with a dictionary:

from pathlib import Path

climate_station = { # Climate station metadata
     'output_filepath': Path('path/to/climate_station.csv'),
     'climate_station_name': 'NLDAS-2 climate station',
     'beginning_climate_date': clm.start.strftime("%m/%d/%Y"),
     'ending_climate_date': clm.end.strftime("%m/%d/%Y"),
     'latitude': y,
     'longitude': x,
     'elevation': 10.0 # Meters, or whatever local elevation you want to set for those specific coordinates
}

pyagnps.climate.generate_climate_station_file(**climate_station)