{"id":31531509,"url":"https://github.com/hyriver/pygridmet","last_synced_at":"2025-10-04T02:13:00.089Z","repository":{"id":209229207,"uuid":"722777113","full_name":"hyriver/pygridmet","owner":"hyriver","description":"Access daily climate data from GridMet over CONUS","archived":false,"fork":false,"pushed_at":"2025-06-25T20:11:20.000Z","size":212,"stargazers_count":6,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-05T00:41:34.711Z","etag":null,"topics":["climate","conus","data","gridmet","hydrology","python","webservice"],"latest_commit_sha":null,"homepage":"https://docs.hyriver.io","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hyriver.png","metadata":{"files":{"readme":"README.rst","changelog":"HISTORY.rst","contributing":"CONTRIBUTING.rst","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.rst","threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS.rst","dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["cheginit"]}},"created_at":"2023-11-23T23:37:53.000Z","updated_at":"2025-08-15T21:04:07.000Z","dependencies_parsed_at":"2023-11-26T01:25:24.083Z","dependency_job_id":"3ea90a5b-89b4-44c6-91cc-03be0ff9c47d","html_url":"https://github.com/hyriver/pygridmet","commit_stats":{"total_commits":31,"total_committers":3,"mean_commits":"10.333333333333334","dds":0.09677419354838712,"last_synced_commit":"67aa471fc0378ca5d263ac58cefcedb8c2b4c9fc"},"previous_names":["hyriver/pygridmet"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/hyriver/pygridmet","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyriver%2Fpygridmet","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyriver%2Fpygridmet/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyriver%2Fpygridmet/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyriver%2Fpygridmet/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hyriver","download_url":"https://codeload.github.com/hyriver/pygridmet/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyriver%2Fpygridmet/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278254466,"owners_count":25956604,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-04T02:00:05.491Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["climate","conus","data","gridmet","hydrology","python","webservice"],"created_at":"2025-10-04T02:12:59.188Z","updated_at":"2025-10-04T02:13:00.077Z","avatar_url":"https://github.com/hyriver.png","language":"Python","funding_links":["https://github.com/sponsors/cheginit"],"categories":[],"sub_categories":[],"readme":".. image:: https://raw.githubusercontent.com/hyriver/HyRiver-examples/main/notebooks/_static/pygridmet_logo.png\n    :target: https://github.com/hyriver/HyRiver\n\n|\n\n.. image:: https://joss.theoj.org/papers/b0df2f6192f0a18b9e622a3edff52e77/status.svg\n    :target: https://joss.theoj.org/papers/b0df2f6192f0a18b9e622a3edff52e77\n    :alt: JOSS\n\n|\n\n.. |pygeohydro| image:: https://github.com/hyriver/pygeohydro/actions/workflows/test.yml/badge.svg\n    :target: https://github.com/hyriver/pygeohydro/actions/workflows/test.yml\n    :alt: Github Actions\n\n.. |pygeoogc| image:: https://github.com/hyriver/pygeoogc/actions/workflows/test.yml/badge.svg\n    :target: https://github.com/hyriver/pygeoogc/actions/workflows/test.yml\n    :alt: Github Actions\n\n.. |pygeoutils| image:: https://github.com/hyriver/pygeoutils/actions/workflows/test.yml/badge.svg\n    :target: https://github.com/hyriver/pygeoutils/actions/workflows/test.yml\n    :alt: Github Actions\n\n.. |pynhd| image:: https://github.com/hyriver/pynhd/actions/workflows/test.yml/badge.svg\n    :target: https://github.com/hyriver/pynhd/actions/workflows/test.yml\n    :alt: Github Actions\n\n.. |py3dep| image:: https://github.com/hyriver/py3dep/actions/workflows/test.yml/badge.svg\n    :target: https://github.com/hyriver/py3dep/actions/workflows/test.yml\n    :alt: Github Actions\n\n.. |pydaymet| image:: https://github.com/hyriver/pydaymet/actions/workflows/test.yml/badge.svg\n    :target: https://github.com/hyriver/pydaymet/actions/workflows/test.yml\n    :alt: Github Actions\n\n.. |pygridmet| image:: https://github.com/hyriver/pygridmet/actions/workflows/test.yml/badge.svg\n    :target: https://github.com/hyriver/pygridmet/actions/workflows/test.yml\n    :alt: Github Actions\n\n.. |pynldas2| image:: https://github.com/hyriver/pynldas2/actions/workflows/test.yml/badge.svg\n    :target: https://github.com/hyriver/pynldas2/actions/workflows/test.yml\n    :alt: Github Actions\n\n.. |async| image:: https://github.com/hyriver/async-retriever/actions/workflows/test.yml/badge.svg\n    :target: https://github.com/hyriver/async-retriever/actions/workflows/test.yml\n    :alt: Github Actions\n\n.. |signatures| image:: https://github.com/hyriver/hydrosignatures/actions/workflows/test.yml/badge.svg\n    :target: https://github.com/hyriver/hydrosignatures/actions/workflows/test.yml\n    :alt: Github Actions\n\n================ ====================================================================\nPackage          Description\n================ ====================================================================\nPyNHD_           Navigate and subset NHDPlus (MR and HR) using web services\nPy3DEP_          Access topographic data through National Map's 3DEP web service\nPyGeoHydro_      Access NWIS, NID, WQP, eHydro, NLCD, CAMELS, and SSEBop databases\nPyDaymet_        Access daily, monthly, and annual climate data via Daymet\nPyGridMET_       Access daily climate data via GridMET\nPyNLDAS2_        Access hourly NLDAS-2 data via web services\nHydroSignatures_ A collection of tools for computing hydrological signatures\nAsyncRetriever_  High-level API for asynchronous requests with persistent caching\nPyGeoOGC_        Send queries to any ArcGIS RESTful-, WMS-, and WFS-based services\nPyGeoUtils_      Utilities for manipulating geospatial, (Geo)JSON, and (Geo)TIFF data\n================ ====================================================================\n\n.. _PyGeoHydro: https://github.com/hyriver/pygeohydro\n.. _AsyncRetriever: https://github.com/hyriver/async-retriever\n.. _PyGeoOGC: https://github.com/hyriver/pygeoogc\n.. _PyGeoUtils: https://github.com/hyriver/pygeoutils\n.. _PyNHD: https://github.com/hyriver/pynhd\n.. _Py3DEP: https://github.com/hyriver/py3dep\n.. _PyDaymet: https://github.com/hyriver/pydaymet\n.. _PyGridMET: https://github.com/hyriver/pygridmet\n.. _PyNLDAS2: https://github.com/hyriver/pynldas2\n.. _HydroSignatures: https://github.com/hyriver/hydrosignatures\n\nPyGridMET: Daily climate data through GridMET\n---------------------------------------------\n\n.. image:: https://img.shields.io/pypi/v/pygridmet.svg\n    :target: https://pypi.python.org/pypi/pygridmet\n    :alt: PyPi\n\n.. image:: https://img.shields.io/conda/vn/conda-forge/pygridmet.svg\n    :target: https://anaconda.org/conda-forge/pygridmet\n    :alt: Conda Version\n\n.. image:: https://codecov.io/gh/hyriver/pygridmet/branch/main/graph/badge.svg\n    :target: https://codecov.io/gh/hyriver/pygridmet\n    :alt: CodeCov\n\n.. image:: https://img.shields.io/pypi/pyversions/pygridmet.svg\n    :target: https://pypi.python.org/pypi/pygridmet\n    :alt: Python Versions\n\n.. image:: https://static.pepy.tech/badge/pygridmet\n    :target: https://pepy.tech/project/pygridmet\n    :alt: Downloads\n\n|\n\n.. image:: https://www.codefactor.io/repository/github/hyriver/pygridmet/badge\n   :target: https://www.codefactor.io/repository/github/hyriver/pygridmet\n   :alt: CodeFactor\n\n.. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json\n    :target: https://github.com/astral-sh/ruff\n    :alt: Ruff\n\n.. image:: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit\u0026logoColor=white\n    :target: https://github.com/pre-commit/pre-commit\n    :alt: pre-commit\n\n.. image:: https://mybinder.org/badge_logo.svg\n    :target: https://mybinder.org/v2/gh/hyriver/HyRiver-examples/main?urlpath=lab/tree/notebooks\n    :alt: Binder\n\n|\n\nFeatures\n--------\n\nPyGridMET is a part of `HyRiver \u003chttps://github.com/hyriver/HyRiver\u003e`__ software stack that\nis designed to aid in hydroclimate analysis through web services. This package provides\naccess to daily climate data over contermonious US (CONUS) from\n`GridMET \u003chttps://www.climatologylab.org/gridmet.html\u003e`__ database using NetCDF\nSubset Service (NCSS). Both single pixel (using ``get_bycoords`` function) and gridded data (using\n``get_bygeom``) are supported which are returned as\n``pandas.DataFrame`` and ``xarray.Dataset``, respectively.\n\nBoth ``get_bygeom`` and ``get_bycoords`` functions save the intermediate files\nreturned by the web service in a local cache folder (``./cache`` in the current\ndirectory). The cache folder is created automatically when the functions are\ncalled for the first time. The cache folder is used to store the intermediate\nfiles to avoid re-downloading them. These two functions allow modifying the\nweb service calls via two options:\n\n- ``conn_timeout``: Sets the connection timeout in seconds. The default value\n  is 5 minutes. This can be increaseed for larger requests. If running these\n  functions fails with a connection timeout error, try increasing this value.\n- ``validate_filesize``: If ``True``, the functions compares the file size\n  of the previously cached files in the ``./cache`` folder, if they exist, with\n  their size on the remote server. If the sizes do not match, the cached files are\n  removed and they will be re-download. By default this is set to ``False`` since\n  the files on the server rarely change. So, if a request has already been cached\n  there shouldn't be a need for re-donwloading them from scratch. However, if you\n  suspect that the files on the server have changed or the functions fails to process\n  the cached files, you can set this to ``True`` or manually delete the cached\n  files in the ``./cache`` folder.\n\nYou can find some example notebooks\n`here \u003chttps://github.com/hyriver/HyRiver-examples\u003e`__.\nYou can also try using PyGridMET without installing\nit on your system by clicking on the binder badge. A Jupyter Lab\ninstance with the HyRiver stack pre-installed will be launched in your web browser, and you\ncan start coding!\n\nMoreover, requests for additional functionalities can be submitted via\n`issue tracker \u003chttps://github.com/hyriver/pygridmet/issues\u003e`__.\n\nCitation\n--------\nIf you use any of HyRiver packages in your research, we appreciate citations:\n\n.. code-block:: bibtex\n\n    @article{Chegini_2021,\n        author = {Chegini, Taher and Li, Hong-Yi and Leung, L. Ruby},\n        doi = {10.21105/joss.03175},\n        journal = {Journal of Open Source Software},\n        month = {10},\n        number = {66},\n        pages = {1--3},\n        title = {{HyRiver: Hydroclimate Data Retriever}},\n        volume = {6},\n        year = {2021}\n    }\n\nInstallation\n------------\n\nYou can install PyGridMET using ``pip`` as follows:\n\n.. code-block:: console\n\n    $ pip install pygridmet\n\nAlternatively, PyGridMET can be installed from the ``conda-forge`` repository\nusing `Conda \u003chttps://docs.conda.io/en/latest/\u003e`__:\n\n.. code-block:: console\n\n    $ conda install -c conda-forge pygridmet\n\nQuick start\n-----------\n\nYou can use PyGridMET using command-line or as a Python library. The commanda-line\nprovides access to two functionality:\n\n- Getting gridded climate data: You must create a ``geopandas.GeoDataFrame`` that contains\n  the geometries of the target locations. This dataframe must have four columns:\n  ``id``, ``start``, ``end``, ``geometry``. The ``id`` column is used as\n  filenames for saving the obtained climate data to a NetCDF (``.nc``) file. The ``start``\n  and ``end`` columns are starting and ending dates of the target period. Then,\n  you must save the dataframe as a shapefile (``.shp``) or geopackage (``.gpkg``) with\n  CRS attribute.\n- Getting single pixel climate data: You must create a CSV file that\n  contains coordinates of the target locations. This file must have at four columns:\n  ``id``, ``start``, ``end``, ``lon``, and ``lat``. The ``id`` column is used as filenames\n  for saving the obtained climate data to a CSV (``.csv``) file. The ``start`` and ``end``\n  columns are the same as the ``geometry`` command. The ``lon`` and ``lat`` columns are\n  the longitude and latitude coordinates of the target locations.\n\n.. code-block:: console\n\n    $ pygridmet -h\n    Usage: pygridmet [OPTIONS] COMMAND [ARGS]...\n\n    Command-line interface for PyGridMET.\n\n    Options:\n    -h, --help  Show this message and exit.\n\n    Commands:\n    coords    Retrieve climate data for a list of coordinates.\n    geometry  Retrieve climate data for a dataframe of geometries.\n\nThe ``coords`` sub-command is as follows:\n\n.. code-block:: console\n\n    $ pygridmet coords -h\n    Usage: pygridmet coords [OPTIONS] FPATH\n\n    Retrieve climate data for a list of coordinates.\n\n    FPATH: Path to a csv file with four columns:\n        - ``id``: Feature identifiers that gridmet uses as the output netcdf filenames.\n        - ``start``: Start time.\n        - ``end``: End time.\n        - ``lon``: Longitude of the points of interest.\n        - ``lat``: Latitude of the points of interest.\n        - ``snow``: (optional) Separate snowfall from precipitation, default is ``False``.\n\n    Examples:\n        $ cat coords.csv\n        id,lon,lat,start,end\n        california,-122.2493328,37.8122894,2012-01-01,2014-12-31\n        $ pygridmet coords coords.csv -v pr -v tmmn\n\n    Options:\n    -v, --variables TEXT  Target variables. You can pass this flag multiple\n                            times for multiple variables.\n    -s, --save_dir PATH   Path to a directory to save the requested files.\n                            Extension for the outputs is .nc for geometry and .csv\n                            for coords.\n    --disable_ssl         Pass to disable SSL certification verification.\n    -h, --help            Show this message and exit.\n\nAnd, the ``geometry`` sub-command is as follows:\n\n.. code-block:: console\n\n    $ pygridmet geometry -h\n    Usage: pygridmet geometry [OPTIONS] FPATH\n\n    Retrieve climate data for a dataframe of geometries.\n\n    FPATH: Path to a shapefile (.shp) or geopackage (.gpkg) file.\n    This file must have four columns and contain a ``crs`` attribute:\n        - ``id``: Feature identifiers that gridmet uses as the output netcdf filenames.\n        - ``start``: Start time.\n        - ``end``: End time.\n        - ``geometry``: Target geometries.\n        - ``snow``: (optional) Separate snowfall from precipitation, default is ``False``.\n\n    Examples:\n        $ pygridmet geometry geo.gpkg -v pr -v tmmn\n\n    Options:\n    -v, --variables TEXT  Target variables. You can pass this flag multiple\n                            times for multiple variables.\n    -s, --save_dir PATH   Path to a directory to save the requested files.\n                            Extension for the outputs is .nc for geometry and .csv\n                            for coords.\n    --disable_ssl         Pass to disable SSL certification verification.\n    -h, --help            Show this message and exit.\n\nNow, let's see how we can use PyGridMET as a library.\n\nPyGridMET offers two functions for getting climate data; ``get_bycoords`` and ``get_bygeom``.\nThe arguments of these functions are identical except the first argument where the latter\nshould be polygon and the former should be a coordinate (a tuple of length two as in (x, y)).\nThe input geometry or coordinate can be in any valid CRS (defaults to ``EPSG:4326``). The\n``dates`` argument can be either a tuple of length two like ``(start_str, end_str)`` or a list of\nyears like ``[2000, 2005]``. It is noted that both functions have a ``snow`` flag for separating\nsnow from precipitation using\n`Martinez and Gupta (2010) \u003chttps://doi.org/10.1029/2009WR008294\u003e`__ method.\n\nWe can get a dataframe of available variables and their info by calling\n``GridMET().gridmet_table``:\n\n+----------------------------------------+------------+------------------------------+\n| Variable                               | Abbr       | Unit                         |\n+========================================+============+==============================+\n| Precipitation                          | ``pr``     | mm                           |\n+----------------------------------------+------------+------------------------------+\n| Maximum Relative Humidity              | ``rmax``   | %                            |\n+----------------------------------------+------------+------------------------------+\n| Minimum Relative Humidity              | ``rmin``   | %                            |\n+----------------------------------------+------------+------------------------------+\n| Specific Humidity                      | ``sph``    | kg/kg                        |\n+----------------------------------------+------------+------------------------------+\n| Surface Radiation                      | ``srad``   | W/m2                         |\n+----------------------------------------+------------+------------------------------+\n| Wind Direction                         | ``th``     | Degrees Clockwise from north |\n+----------------------------------------+------------+------------------------------+\n| Minimum Air Temperature                | ``tmmn``   | K                            |\n+----------------------------------------+------------+------------------------------+\n| Maximum Air Temperature                | ``tmmx``   | K                            |\n+----------------------------------------+------------+------------------------------+\n| Wind Speed                             | ``vs``     | m/s                          |\n+----------------------------------------+------------+------------------------------+\n| Burning Index                          | ``bi``     | Dimensionless                |\n+----------------------------------------+------------+------------------------------+\n| Fuel Moisture (100-hr)                 | ``fm100``  | %                            |\n+----------------------------------------+------------+------------------------------+\n| Fuel Moisture (1000-hr)                | ``fm1000`` | %                            |\n+----------------------------------------+------------+------------------------------+\n| Energy Release Component               | ``erc``    | Dimensionless                |\n+----------------------------------------+------------+------------------------------+\n| Reference Evapotranspiration (Alfalfa) | ``etr``    | mm                           |\n+----------------------------------------+------------+------------------------------+\n| Reference Evapotranspiration (Grass)   | ``pet``    | mm                           |\n+----------------------------------------+------------+------------------------------+\n| Vapor Pressure Deficit                 | ``vpd``    | kPa                          |\n+----------------------------------------+------------+------------------------------+\n\n.. code-block:: python\n\n    from pynhd import NLDI\n    import pygridmet as gridmet\n\n    geometry = NLDI().get_basins(\"01031500\").geometry[0]\n\n    var = [\"pr\", \"tmmn\"]\n    dates = (\"2000-01-01\", \"2000-06-30\")\n\n    daily = gridmet.get_bygeom(geometry, dates, variables=var, snow=True)\n\n.. image:: https://raw.githubusercontent.com/hyriver/HyRiver-examples/main/notebooks/_static/gridmet_grid.png\n    :target: https://github.com/hyriver/HyRiver-examples/blob/main/notebooks/gridmet.ipynb\n\nIf the input geometry (or coordinate) is in a CRS other than ``EPSG:4326``, we should pass\nit to the functions.\n\n.. code-block:: python\n\n    coords = (-1431147.7928, 318483.4618)\n    crs = 3542\n    dates = (\"2000-01-01\", \"2006-12-31\")\n    data = gridmet.get_bycoords(coords, dates, variables=var, loc_crs=crs)\n\n.. image:: https://raw.githubusercontent.com/hyriver/HyRiver-examples/main/notebooks/_static/gridmet_loc.png\n    :target: https://github.com/hyriver/HyRiver-examples/blob/main/notebooks/gridmet.ipynb\n\nAdditionally, the ``get_bycoords`` function accepts a list of coordinates and by setting the\n``to_xarray`` flag to ``True`` it can return the results as a ``xarray.Dataset`` instead of\na ``pandas.DataFrame``:\n\n.. code-block:: python\n\n    coords = [(-94.986, 29.973), (-95.478, 30.134)]\n    idx = [\"P1\", \"P2\"]\n    clm_ds = gridmet.get_bycoords(coords, range(2000, 2021), coords_id=idx, to_xarray=True)\n\nContributing\n------------\n\nContributions are very welcomed. Please read\n`CONTRIBUTING.rst \u003chttps://github.com/hyriver/pygridmet/blob/main/CONTRIBUTING.rst\u003e`__\nfile for instructions.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyriver%2Fpygridmet","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhyriver%2Fpygridmet","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyriver%2Fpygridmet/lists"}