pygridmet.pygridmet#

Access the GridMET database for both single single pixel and gridded queries.

Module Contents#

pygridmet.pygridmet.get_bycoords(coords, dates, coords_id=None, crs=4326, variables=None, snow=False, snow_params=None, to_xarray=False, conn_timeout=1000, validate_filesize=True)#

Get point-data from the GridMET database at 1-km resolution.

Parameters:

  • coords (tuple or list of tuples) – Coordinates of the location(s) of interest as a tuple (x, y)

  • dates (tuple or list, optional) – Start and end dates as a tuple (start, end) or a list of years [2001, 2010, ...].

  • coords_id (list of int or str, optional) – A list of identifiers for the coordinates. This option only applies when to_xarray is set to True. If not provided, the coordinates will be enumerated.

  • crs (str, int, or pyproj.CRS, optional) – The CRS of the input coordinates, defaults to EPSG:4326.

  • variables (str or list) – List of variables to be downloaded. The acceptable variables are: pr, rmax, rmin, sph, srad, th, tmmn, tmmx, vs, bi, fm100, fm1000, erc, etr, pet, and vpd. Descriptions can be found here. Defaults to None, i.e., all the variables are downloaded.

  • snow (bool, optional) – Compute snowfall from precipitation and minimum temperature. Defaults to False.

  • snow_params (dict, optional) – Model-specific parameters as a dictionary that is passed to the snowfall function. These parameters are only used if snow is True. Two parameters are required: t_rain (deg C) which is the threshold for temperature for considering rain and t_snow (deg C) which is the threshold for temperature for considering snow. The default values are {'t_rain': 2.5, 't_snow': 0.6} that are adopted from https://doi.org/10.5194/gmd-11-1077-2018.

  • to_xarray (bool, optional) – Return the data as an xarray.Dataset. Defaults to False.

  • conn_timeout (int, optional) – Connection timeout in seconds, defaults to 1000.

  • validate_filesize (bool, optional) – When set to True, the function checks the file size of the previously cached files and will re-download if the local filesize does not match that of the remote. Defaults to True. Setting this to False can be useful when you are sure that the cached files are not corrupted and just want to get the combined dataset more quickly. This is faster because it avoids web requests that are necessary for getting the file sizes.

Returns:

pandas.DataFrame or xarray.Dataset – Daily climate data for a single or list of locations.

Return type:

pandas.DataFrame | xarray.Dataset

Examples

>>> import pygridmet as gridmet
>>> coords = (-1431147.7928, 318483.4618)
>>> dates = ("2000-01-01", "2000-01-31")
>>> clm = gridmet.get_bycoords(
...     coords,
...     dates,
...     crs=3542,
... )
>>> clm["pr (mm)"].mean()
9.677
pygridmet.pygridmet.get_bygeom(geometry, dates, crs=4326, variables=None, snow=False, snow_params=None, conn_timeout=1000, validate_filesize=True)#

Get gridded data from the GridMET database at 1-km resolution.

Parameters:

  • geometry (Polygon or tuple) – The geometry of the region of interest. It can be a shapely Polygon or a tuple of length 4 representing the bounding box (minx, miny, maxx, maxy).

  • dates (tuple or list, optional) – Start and end dates as a tuple (start, end) or a list of years [2001, 2010, …].

  • crs (str, int, or pyproj.CRS, optional) – The CRS of the input geometry, defaults to epsg:4326.

  • variables (str or list) – List of variables to be downloaded. The acceptable variables are: pr, rmax, rmin, sph, srad, th, tmmn, tmmx, vs, bi, fm100, fm1000, erc, etr, pet, and vpd. Descriptions can be found here. Defaults to None, i.e., all the variables are downloaded.

  • snow (bool, optional) – Compute snowfall from precipitation and minimum temperature. Defaults to False.

  • snow_params (dict, optional) – Model-specific parameters as a dictionary that is passed to the snowfall function. These parameters are only used if snow is True. Two parameters are required: t_rain (deg C) which is the threshold for temperature for considering rain and t_snow (deg C) which is the threshold for temperature for considering snow. The default values are {'t_rain': 2.5, 't_snow': 0.6} that are adopted from https://doi.org/10.5194/gmd-11-1077-2018.

  • conn_timeout (int, optional) – Connection timeout in seconds, defaults to 1000.

  • validate_filesize (bool, optional) – When set to True, the function checks the file size of the previously cached files and will re-download if the local filesize does not match that of the remote. Defaults to True. Setting this to False can be useful when you are sure that the cached files are not corrupted and just want to get the combined dataset more quickly. This is faster because it avoids web requests that are necessary for getting the file sizes.

Returns:

xarray.Dataset – Daily climate data within the target geometry.

Return type:

xarray.Dataset

Examples

>>> from shapely import Polygon
>>> import pygridmet as gridmet
>>> geometry = Polygon(
...     [[-69.77, 45.07], [-69.31, 45.07], [-69.31, 45.45], [-69.77, 45.45], [-69.77, 45.07]]
... )
>>> clm = gridmet.get_bygeom(geometry, 2010, variables="tmmn")
>>> clm["tmmn"].mean().item()
274.167
pygridmet.pygridmet.get_conus(years, variables=None, save_dir='clm_gridmet', conn_timeout=1000, validate_filesize=True)#

Get the entire CONUS data for the specified years and variables.

Parameters:

  • years (int or list) – The year(s) of interest.

  • variables (str or list, optional) – The variable(s) of interest, defaults to None which downloads all the variables.

  • save_dir (str or Path, optional) – The directory to store the downloaded data, defaults to ./clm_gridmet. The files are stored in the NetCDF format and the file names are based on the variable names and the years, e.g., tmmn_2010.nc.

  • conn_timeout (int, optional) – Connection timeout in seconds, defaults to 1000.

  • validate_filesize (bool, optional) – When set to True, the function checks the file size of the previously cached files and will re-download if the local filesize does not match that of the remote. Defaults to True. Setting this to False can be useful when you are sure that the cached files are not corrupted and just want to get the combined dataset more quickly. This is faster because it avoids web requests that are necessary for getting the file sizes.

Returns:

list – A list of the downloaded files.

Return type:

list[pathlib.Path | None]

Examples

>>> import pygridmet as gridmet
>>> filenames = gridmet.get_conus(2010, "tmmn")