pynldas2 0.17.1

Description:

pynldas2 0.17.1

Package
Description
Status



PyNHD
Navigate and subset NHDPlus (MR and HR) using web services


Py3DEP
Access topographic data through National Map’s 3DEP web service


PyGeoHydro
Access NWIS, NID, WQP, eHydro, NLCD, CAMELS, and SSEBop databases


PyDaymet
Access daily, monthly, and annual climate data via Daymet


PyGridMET
Access daily climate data via GridMET


PyNLDAS2
Access hourly NLDAS-2 data via web services


HydroSignatures
A collection of tools for computing hydrological signatures


AsyncRetriever
High-level API for asynchronous requests with persistent caching


PyGeoOGC
Send queries to any ArcGIS RESTful-, WMS-, and WFS-based services


PyGeoUtils
Utilities for manipulating geospatial, (Geo)JSON, and (Geo)TIFF data





PyNLDAS2: Hourly NLDAS-2 Forcing Data



































Features
PyNLDAS2 is a part of HyRiver software stack that
is designed to aid in hydroclimate analysis through web services. This package
provides access NLDAS-2 Forcing dataset
via Hydrology Data Rods.
Currently, only hourly data is supported. There are three main functions:

get_bycoords: Forcing data for a list of coordinates as a pandas.DataFrame or
xarray.Dataset,
get_bygeom: Forcing data within a geometry as a xarray.Dataset,
get_grid_mask: NLDAS2
land/water grid mask
as a xarray.Dataset.

PyNLDAS2 only provides access to the hourly NLDAS2 dataset, so if you need to access
other NASA climate datasets you can check out
tsgettoolbox developed by
Tim Cera.
Moreover, under the hood, PyNLDAS2 uses
PyGeoOGC and
AsyncRetriever packages
for making requests in parallel and storing responses in chunks. This improves the
reliability and speed of data retrieval significantly.
You can control the request/response caching behavior and verbosity of the package
by setting the following environment variables:

HYRIVER_CACHE_NAME: Path to the caching SQLite database for asynchronous HTTP
requests. It defaults to ./cache/aiohttp_cache.sqlite
HYRIVER_CACHE_NAME_HTTP: Path to the caching SQLite database for HTTP requests.
It defaults to ./cache/http_cache.sqlite
HYRIVER_CACHE_EXPIRE: Expiration time for cached requests in seconds. It defaults to
one week.
HYRIVER_CACHE_DISABLE: Disable reading/writing from/to the cache. The default is false.
HYRIVER_SSL_CERT: Path to a SSL certificate file.

For example, in your code before making any requests you can do:
import os

os.environ["HYRIVER_CACHE_NAME"] = "path/to/aiohttp_cache.sqlite"
os.environ["HYRIVER_CACHE_NAME_HTTP"] = "path/to/http_cache.sqlite"
os.environ["HYRIVER_CACHE_EXPIRE"] = "3600"
os.environ["HYRIVER_CACHE_DISABLE"] = "true"
os.environ["HYRIVER_SSL_CERT"] = "path/to/cert.pem"
You can find some example notebooks here.
You can also try using PyNLDAS2 without installing
it on your system by clicking on the binder badge. A Jupyter Lab
instance with the HyRiver stack pre-installed will be launched in your web browser, and you
can start coding!
Moreover, requests for additional functionalities can be submitted via
issue tracker.


Citation
If you use any of HyRiver packages in your research, we appreciate citations:
@article{Chegini_2021,
author = {Chegini, Taher and Li, Hong-Yi and Leung, L. Ruby},
doi = {10.21105/joss.03175},
journal = {Journal of Open Source Software},
month = {10},
number = {66},
pages = {1--3},
title = {{HyRiver: Hydroclimate Data Retriever}},
volume = {6},
year = {2021}
}


Installation
You can install pynldas2 using pip:
$ pip install pynldas2
Alternatively, pynldas2 can be installed from the conda-forge repository
using Conda:
$ conda install -c conda-forge pynldas2


Quick start
The NLDAS2 database provides forcing data at 1/8th-degree grid spacing and range
from 01 Jan 1979 to present. Let’s take a look at NLDAS2 grid mask that includes
land, water, soil, and vegetation masks:
import pynldas2 as nldas

grid = nldas.get_grid_mask()



Next, we use PyGeoHydro to get the
geometry of a HUC8 with ID of 1306003, then we get the forcing data within the
obtained geometry.
from pygeohydro import WBD

huc8 = WBD("huc8")
geometry = huc8.byids("huc8", "13060003").geometry[0]
clm = nldas.get_bygeom(geometry, "2010-01-01", "2010-01-31", 4326)





Road Map

[ ] Add PET calculation functions similar to
PyDaymet but at hourly timescale.
[ ] Add a command line interfaces.



Contributing
Contributions are appreciated and very welcomed. Please read
CONTRIBUTING.rst
for instructions.