pydaymet.pydaymet

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

Module Contents

pydaymet.pydaymet.get_bycoords(coords, dates, coords_id=None, crs=4326, variables=None, region='na', time_scale='daily', pet=None, pet_params=None, snow=False, snow_params=None, to_xarray=False, conn_timeout=1000, validate_filesize=True)

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

This function uses THREDDS data service to get the coordinates and supports getting monthly and annual summaries of the climate data directly from the server.

Parameters:

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

• dates (tuple or list) – 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: tmin, tmax, prcp, srad, vp, swe, dayl Descriptions can be found here.

• region (str, optional) – Target region in the US, defaults to na. Acceptable values are:

  • na: Continental North America

  • hi: Hawaii

  • pr: Puerto Rico

• time_scale (str, optional) – Data time scale which can be daily, monthly (monthly summaries), or annual (annual summaries). Defaults to daily.

• pet (str, optional) – Method for computing PET. Supported methods are penman_monteith, priestley_taylor, hargreaves_samani, and None (don’t compute PET). The penman_monteith method is based on Allen et al.[1] assuming that soil heat flux density is zero. The priestley_taylor method is based on Priestley and TAYLOR[2] assuming that soil heat flux density is zero. The hargreaves_samani method is based on Hargreaves and Samani[3]. Defaults to None.

• pet_params (dict, optional) – Model-specific parameters as a dictionary, defaults to None. An important parameter for priestley_taylor and penman_monteith methods is arid_correction which is used to correct the actual vapor pressure for arid regions. Since relative humidity is not provided by Daymet, the actual vapor pressure is computed assuming that the dewpoint temperature is equal to the minimum temperature. However, for arid regions, FAO 56 suggests subtracting the minimum temperature by 2-3 °C to account for aridity, since in arid regions, the air might not be saturated when its temperature is at its minimum. For such areas, you can pass {"arid_correction": True, ...} to subtract 2 °C from the minimum temperature before computing the actual vapor pressure.

• 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 pydaymet as daymet
>>> coords = (-1431147.7928, 318483.4618)
>>> dates = ("2000-01-01", "2000-12-31")
>>> clm = daymet.get_bycoords(
...     coords,
...     dates,
...     crs=3542,
...     pet="hargreaves_samani",
... )
>>> clm["pet (mm/day)"].mean()
3.713

References

[1] (1,2,3)

Richard G Allen, Luis S Pereira, Dirk Raes, Martin Smith, and others. Crop evapotranspiration-guidelines for computing crop water requirements-fao irrigation and drainage paper 56. Fao, Rome, 300(9):D05109, 1998.

[2] (1,2,3)

Charles Henry Brian Priestley and Robert Joseph TAYLOR. On the assessment of surface heat flux and evaporation using large-scale parameters. Monthly weather review, 100(2):81–92, 1972.

[3] (1,2,3)

George H. Hargreaves and Zohrab A. Samani. Estimating potential evapotranspiration. Journal of the Irrigation and Drainage Division, 108(3):225–230, sep 1982. URL: https://doi.org/10.1061%2Fjrcea4.0001390, doi:10.1061/jrcea4.0001390.

pydaymet.pydaymet.get_bygeom(geometry, dates, crs=4326, variables=None, region='na', time_scale='daily', pet=None, pet_params=None, snow=False, snow_params=None, conn_timeout=1000, validate_filesize=True)

Get gridded data from the Daymet 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) – 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: tmin, tmax, prcp, srad, vp, swe, dayl Descriptions can be found here.

• region (str, optional) – Region in the US, defaults to na. Acceptable values are:

  • na: Continental North America

  • hi: Hawaii

  • pr: Puerto Rico

• time_scale (str, optional) – Data time scale which can be daily, monthly (monthly average), or annual (annual average). Defaults to daily.

• pet (str, optional) – Method for computing PET. Supported methods are penman_monteith, priestley_taylor, hargreaves_samani, and None (don’t compute PET). The penman_monteith method is based on Allen et al.[1] assuming that soil heat flux density is zero. The priestley_taylor method is based on Priestley and TAYLOR[2] assuming that soil heat flux density is zero. The hargreaves_samani method is based on Hargreaves and Samani[3]. Defaults to None.

• pet_params (dict, optional) – Model-specific parameters as a dictionary, defaults to None. Valid parameters are:

  • penman_monteith: soil_heat_flux, albedo, alpha, and arid_correction.

  • priestley_taylor: soil_heat_flux, albedo, and arid_correction.

  • hargreaves_samani: None.

  Default values for the parameters are: soil_heat_flux = 0, albedo = 0.23, alpha = 1.26, and arid_correction = False. An important parameter for priestley_taylor and penman_monteith methods is arid_correction which is used to correct the actual vapor pressure for arid regions. Since relative humidity is not provided by Daymet, the actual vapor pressure is computed assuming that the dewpoint temperature is equal to the minimum temperature. However, for arid regions, FAO 56 suggests subtracting the minimum temperature by 2-3 °C to account for aridity, since in arid regions, the air might not be saturated when its temperature is at its minimum. For such areas, you can pass {"arid_correction": True, ...} to subtract 2 °C from the minimum temperature before computing the actual vapor pressure.

• 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 pydaymet as daymet
>>> geometry = Polygon(
...     [[-69.77, 45.07], [-69.31, 45.07], [-69.31, 45.45], [-69.77, 45.45], [-69.77, 45.07]]
... )
>>> clm = daymet.get_bygeom(geometry, 2010, variables="tmin", time_scale="annual")
>>> clm["tmin"].mean().item()
1.361

References

pydaymet.pydaymet.get_bystac(geometry, dates, crs=4326, variables=None, region='na', time_scale='daily', res_km=1, pet=None, pet_params=None, snow=False, snow_params=None)

Get gridded Daymet from STAC.

Added in version 0.16.1.

Note

This function provides access to the Daymet data from Microsoft’s the Planetary Computer: https://planetarycomputer.microsoft.com/dataset/group/daymet. Although this function can be much faster than get_bygeom(), currently, it gives access to Daymet v4.2 from 1980 to 2020. For accessing the latest version of Daymet (v4.5) you need to use get_bygeom().

Also, this function requires fsspec, dask, zarr, and pystac-client packages. They can be installed using pip install fsspec dask zarr pystac-client or conda install fsspec dask-core zarr pystac-client.

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) – 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: tmin, tmax, prcp, srad, vp, swe, dayl Descriptions can be found here.

• region (str, optional) – Region in the US, defaults to na. Acceptable values are:

  • na: Continental North America

  • hi: Hawaii

  • pr: Puerto Rico

• time_scale (str, optional) – Data time scale which can be daily, monthly (monthly average), or annual (annual average). Defaults to daily.

• res_km (int, optional) – Spatial resolution in kilometers, defaults to 1. For values greater than 1, the data will be aggregated (coarsend) using mean.

• pet (str, optional) – Method for computing PET. Supported methods are penman_monteith, priestley_taylor, hargreaves_samani, and None (don’t compute PET). The penman_monteith method is based on Allen et al.[1] assuming that soil heat flux density is zero. The priestley_taylor method is based on Priestley and TAYLOR[2] assuming that soil heat flux density is zero. The hargreaves_samani method is based on Hargreaves and Samani[3]. Defaults to None.

• pet_params (dict, optional) – Model-specific parameters as a dictionary, defaults to None. Valid parameters are:

  • penman_monteith: soil_heat_flux, albedo, alpha, and arid_correction.

  • priestley_taylor: soil_heat_flux, albedo, and arid_correction.

  • hargreaves_samani: None.

  Default values for the parameters are: soil_heat_flux = 0, albedo = 0.23, alpha = 1.26, and arid_correction = False. An important parameter for priestley_taylor and penman_monteith methods is arid_correction which is used to correct the actual vapor pressure for arid regions. Since relative humidity is not provided by Daymet, the actual vapor pressure is computed assuming that the dewpoint temperature is equal to the minimum temperature. However, for arid regions, FAO 56 suggests subtracting the minimum temperature by 2-3 °C to account for aridity, since in arid regions, the air might not be saturated when its temperature is at its minimum. For such areas, you can pass {"arid_correction": True, ...} to subtract 2 °C from the minimum temperature before computing the actual vapor pressure.

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

Returns:

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

Return type:

xarray.Dataset

Examples

>>> from shapely import Polygon
>>> geometry = Polygon(
...     [[-69.77, 45.07], [-69.70, 45.07], [-69.70, 45.15], [-69.77, 45.15], [-69.77, 45.07]]
... )
>>> clm = daymet.get_bystac(
...     geometry,
...     ("2010-01-01", "2010-01-02"),
...     variables="prcp",
...     res_km=4,
...     snow=True,
...     pet="hargreaves_samani",
... )
>>> clm["pet"].mean().item()
0.3

References