### Create and Activate Development Environment (Shell)

Source: https://github.com/hyriver/pynldas2/blob/main/CONTRIBUTING.rst

Commands to create a new Conda environment for development, install PyNLDAS2 without dependencies, and activate the environment.

```shell
cd pynldas2/
mamba env create -f ci/requirements/environment-dev.yml
mamba activate pynldas2-dev
python -m pip install . --no-deps
```

--------------------------------

### Install PyNLDAS2 using pip

Source: https://github.com/hyriver/pynldas2/blob/main/README.rst

This command installs the PyNLDAS2 package using pip, the standard package installer for Python. Ensure you have pip installed and accessible in your environment.

```console
pip install pynldas2
```

--------------------------------

### Commit and Push Changes with Conventional Commits (Shell)

Source: https://github.com/hyriver/pynldas2/blob/main/CONTRIBUTING.rst

Example of staging all changes, committing with a conventional commit message prefix (e.g., ENH:, BUG:, DOC:), and pushing the branch to GitHub.

```shell
$ git add .
$ git commit -m "ENH: A detailed description of your changes."
$ git push origin name-of-your-branch
```

--------------------------------

### Install PyNLDAS2 using Conda

Source: https://github.com/hyriver/pynldas2/blob/main/README.rst

This command installs the PyNLDAS2 package from the conda-forge channel using Conda, a popular package and environment management system. This method is recommended for users who prefer or rely on the Conda ecosystem.

```console
conda install -c conda-forge pynldas2
```

--------------------------------

### Run All Nox Sessions (Shell)

Source: https://github.com/hyriver/pynldas2/blob/main/CONTRIBUTING.rst

If Python 3.11 is already installed, this command allows running all Nox sessions directly without creating a separate environment for linting and type-checking.

```shell
$ mamba create -n py38 python=3.8 nox tomli pre-commit codespell gdal
$ mamba activate py38
$ nox
```

--------------------------------

### Get NLDAS2 Forcing Data by Geometry using Python

Source: https://github.com/hyriver/pynldas2/blob/main/README.rst

This Python code snippet shows how to fetch NLDAS2 forcing data for a specific geographic area defined by a geometry object. It uses `pynldas2.get_bygeom` and requires `pygeohydro` for geometry definition. The function takes the geometry, start date, end date, and a CRS code as input.

```python
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)
```

--------------------------------

### Get NLDAS2 Grid Mask using Python

Source: https://github.com/hyriver/pynldas2/blob/main/README.rst

This Python code snippet demonstrates how to retrieve the NLDAS2 grid mask, which includes land, water, soil, and vegetation masks. It utilizes the `pynldas2` library and stores the result in a variable named `grid`.

```python
import pynldas2 as nldas

grid = nldas.get_grid_mask()
```

--------------------------------

### Handle NLDAS2 Data Retrieval Errors and Validation

Source: https://context7.com/hyriver/pynldas2/llms.txt

This section provides examples of how to handle common errors and validation issues when retrieving NLDAS2 data using pynldas2. It demonstrates the use of specific exception types like InputRangeError, InputTypeError, InputValueError, and NLDASServiceError to catch and manage problems related to date ranges, variable names, coordinate domains, and service issues.

```python
import pynldas2 as nldas
from pynldas2.exceptions import (
    InputRangeError,
    InputTypeError,
    InputValueError,
    NLDASServiceError
)

# Invalid date range (before 1979-01-01)
try:
    climate = nldas.get_bycoords(
        coords=(-89.5, 45.5),
        start_date="1978-01-01",
        end_date="1978-12-31"
    )
except InputRangeError as e:
    print(e)  # Valid range for start_date is 1979-01-01 to yesterday

# Invalid variable name
try:
    climate = nldas.get_bycoords(
        coords=(-89.5, 45.5),
        start_date="2010-01-01",
        end_date="2010-01-02",
        variables=["invalid_var"]
    )
except InputValueError as e:
    print(e)  # Lists all valid variable names

# Coordinates outside NLDAS2 domain
try:
    climate = nldas.get_bycoords(
        coords=(0, 0),  # Not in North America
        start_date="2010-01-01",
        end_date="2010-01-02"
    )
except InputRangeError as e:
    print(e)  # Valid range for coords is within (-125.0, 25.0, -67.0, 53.0)
```

--------------------------------

### Get NLDAS2 Data by Geometry (Python)

Source: https://context7.com/hyriver/pynldas2/llms.txt

Retrieves NLDAS2 hourly forcing data for a specified geographical area defined by a polygon or bounding box. Supports custom geometric coordinate reference systems and returns data as an xarray Dataset. Options include variable selection, snow data, connection timeouts, and file size validation.

```python
import pynldas2 as nldas
from shapely import Polygon

# Using a polygon geometry
geometry = Polygon([
    [-69.77, 45.07],
    [-69.31, 45.07],
    [-69.31, 45.45],
    [-69.77, 45.45],
    [-69.77, 45.07]
])

climate_grid = nldas.get_bygeom(
    geometry=geometry,
    start_date="2010-01-01",
    end_date="2010-01-31",
    geo_crs=4326,
    variables=["prcp", "temp", "humidity"],  # Or None for all
    snow=False,
    conn_timeout=1000,
    validate_filesize=True
)

# Result: xarray.Dataset with dimensions (time, y, x)
# <xarray.Dataset>
# Dimensions:   (time: 744, y: 4, x: 4)
# Coordinates:
#   * time      (time) datetime64[ns] 2010-01-01 ... 2010-01-31T23:00:00
#   * x         (x) float64 -69.75 -69.625 -69.5 -69.375
#   * y         (y) float64 45.063 45.188 45.313 45.438
# Data variables:
#     prcp      (time, y, x) float64 ...
#     temp      (time, y, x) float64 ...
#     humidity  (time, y, x) float64 ...

# Using a bounding box (minx, miny, maxx, maxy)
bbox = (-69.77, 45.07, -69.31, 45.45)
climate_bbox = nldas.get_bygeom(
    geometry=bbox,
    start_date="2000-01-01",
    end_date="2000-01-02",
    geo_crs=4326,
    variables="prcp",
    snow=False
)

# Can integrate with PyGeoHydro for watershed analysis
try:
    from pygeohydro import WBD
    huc8 = WBD("huc8")
    watershed = huc8.byids("huc8", "13060003").geometry[0]
    climate_watershed = nldas.get_bygeom(
        geometry=watershed,
        start_date="2010-01-01",
        end_date="2010-01-31",
        geo_crs=4326
    )
except ImportError:
    pass  # PyGeoHydro not installed

```

--------------------------------

### Get NLDAS2 Data by Coordinates (Python)

Source: https://context7.com/hyriver/pynldas2/llms.txt

Retrieves NLDAS2 hourly forcing data for specified point locations. Supports single or multiple coordinates, custom coordinate reference systems (CRS), and can return data as pandas DataFrames or xarray Datasets. Includes options for variable selection, snow data, connection timeouts, and file size validation.

```python
import pynldas2 as nldas

# Single coordinate in EPSG:4326 (lon, lat)
coords = (-69.77, 45.07)
climate = nldas.get_bycoords(
    coords=coords,
    start_date="2010-01-01",
    end_date="2010-01-31",
    crs=4326,
    variables=["prcp", "temp", "pet"],  # Or None for all variables
    to_xarray=False,  # Returns pandas.DataFrame
    snow=False,
    conn_timeout=1000,
    validate_filesize=True
)

# Result: pandas.DataFrame with time index and variable columns
#                          prcp      temp       pet
# time
# 2010-01-01 00:00:00+00:00  0.0  268.45  0.000000
# 2010-01-01 01:00:00+00:00  0.0  268.12  0.000000
# 2010-01-01 02:00:00+00:00  0.0  267.89  0.000000

# Multiple coordinates with custom CRS (e.g., NAD83 / Massachusetts Mainland)
coords_projected = [(-1431147.7928, 318483.4618), (-1421000.0, 320000.0)]
climate_multi = nldas.get_bycoords(
    coords=coords_projected,
    start_date="2000-01-01",
    end_date="2000-01-12",
    crs=3542,  # EPSG:3542
    coords_id=["site_A", "site_B"],
    variables=["prcp", "pet"],
    to_xarray=True,  # Returns xarray.Dataset
    snow=False,
    conn_timeout=1000,
    validate_filesize=False  # Skip filesize check for faster access
)

# Result: xarray.Dataset with dimensions (id, time)
# <xarray.Dataset>
# Dimensions:  (id: 2, time: 288)
# Coordinates:
#   * id       (id) object 'site_A' 'site_B'
#   * time     (time) datetime64[ns] 2000-01-01 ... 2000-01-12T23:00:00
# Data variables:
#     prcp     (id, time) float64 ...
#     pet      (id, time) float64 ...

```

--------------------------------

### Compute Snowfall from Precipitation using Temperature

Source: https://context7.com/hyriver/pynldas2/llms.txt

This section details how to compute snowfall from total precipitation using temperature-based separation. It includes examples for automatic snow separation when fetching data by coordinates or geometry, and for manual separation on existing data. It requires the 'temp' variable to be included and allows customization of temperature thresholds for rain and snow.

```python
import pynldas2 as nldas

# Get data with automatic snow separation
coords = (-89.6, 48.3)
climate = nldas.get_bycoords(
    coords=coords,
    start_date="2000-01-01",
    end_date="2000-01-02",
    crs=4326,
    variables=["prcp", "temp"],  # Must include temp for snow calculation
    snow=True,  # Enable snow separation
    snow_params={
        "t_rain": 2.5,  # Rain threshold in °C
        "t_snow": 0.6   # Snow threshold in °C
    }
)

# Result includes additional 'snow' column
#                          prcp      temp      snow
# time
# 2000-01-01 00:00:00+00:00  0.05  272.15  0.0458
# 2000-01-01 01:00:00+00:00  0.03  271.85  0.0276

# Snow separation for gridded data
from shapely import Point
geometry = Point(-89.6, 48.3).buffer(0.05)
climate_grid = nldas.get_bygeom(
    geometry=geometry,
    start_date="2000-01-01",
    end_date="2000-01-02",
    geo_crs=4326,
    variables=["prcp", "temp"],
    snow=True,
    snow_params={"t_rain": 2.5, "t_snow": 0.6}
)

# Result: xarray.Dataset with 'snow' variable added
# Data variables:
#     prcp  (time, y, x) float64 ...
#     temp  (time, y, x) float64 ...
#     snow  (time, y, x) float64 ...

# Manual snow separation on existing data
existing_data = nldas.get_bycoords(
    coords=coords,
    start_date="2000-01-01",
    end_date="2000-01-02",
    variables=["prcp", "temp"]
)
data_with_snow = nldas.separate_snow(
    clm=existing_data,
    t_rain=2.5,  # °C
    t_snow=0.6   # °C
)
```

--------------------------------

### Clone and Set Up PyNLDAS2 Repository (Shell)

Source: https://github.com/hyriver/pynldas2/blob/main/CONTRIBUTING.rst

This snippet demonstrates how to clone your fork of the PyNLDAS2 repository and set up the original repository as an upstream remote for fetching updates.

```shell
$ git clone git@github.com:your_name_here/pynldas2.git
$ git remote add upstream git@github.com:hyriver/pynldas2.git
```

--------------------------------

### Set Up Linting and Testing Environments (Shell)

Source: https://github.com/hyriver/pynldas2/blob/main/CONTRIBUTING.rst

Commands to create and activate separate Conda environments for running linting, type-checking, and tests using Nox.

```shell
$ mamba create -n py11 python=3.11 nox tomli pre-commit codespell gdal
$ mamba activate py11
$ nox -s pre-commit
$ nox -s type-check

$ mamba create -n py38 python=3.8 nox tomli pre-commit codespell gdal
$ mamba activate py38
$ nox -s tests
```

--------------------------------

### Tag and Push Release Version (Shell)

Source: https://github.com/hyriver/pynldas2/blob/main/CONTRIBUTING.rst

Instructions for tagging a new release version using semantic versioning and pushing the tag to GitHub, which triggers deployment via GitHub Actions.

```shell
$ git tag -a vX.X.X -m "vX.X.X"
$ git push --follow-tags
```

--------------------------------

### Create and Push Feature Branch (Shell)

Source: https://github.com/hyriver/pynldas2/blob/main/CONTRIBUTING.rst

Instructions for creating a new Git branch for local development and pushing it to your remote repository.

```shell
$ git checkout -b bugfix-or-feature/name-of-your-bugfix-or-feature
$ git push
```

--------------------------------

### Run a Subset of Tests (Shell)

Source: https://github.com/hyriver/pynldas2/blob/main/CONTRIBUTING.rst

This command demonstrates how to execute a specific subset of tests using Nox, filtering by test names or patterns.

```shell
$ nox -s tests -- -n=1 -k "test_name1 or test_name2"
```

--------------------------------

### Fetch and Merge Upstream Changes (Shell)

Source: https://github.com/hyriver/pynldas2/blob/main/CONTRIBUTING.rst

This snippet shows how to fetch the latest changes from the upstream repository and merge them into your current branch to resolve potential conflicts.

```shell
$ git fetch upstream
$ git merge upstream/name-of-your-branch
```

--------------------------------

### BibTeX Citation for HyRiver

Source: https://github.com/hyriver/pynldas2/blob/main/README.rst

This is a BibTeX entry for citing the HyRiver software package in academic publications. It includes author information, DOI, journal, publication date, and title, which are essential for proper academic referencing.

```bibtex
@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}
}
```

--------------------------------

### Access All NLDAS2 Variables and Metadata

Source: https://context7.com/hyriver/pynldas2/llms.txt

This snippet shows how to access all available NLDAS2 forcing variables, including their units and descriptions. It demonstrates fetching all variables by default, requesting a specific subset of variables, and preserving variable metadata within the xarray.Dataset object.

```python
import pynldas2 as nldas

# All available variables
variables = [
    "prcp",      # Total precipitation (kg/m^2)
    "pet",       # Potential evaporation (kg/m^2)
    "temp",      # 2-m temperature (K)
    "humidity",  # 2-m specific humidity (kg/kg)
    "psurf",     # Surface pressure (Pa)
    "wind_u",    # U wind component at 10-m (m/s)
    "wind_v",    # V wind component at 10-m (m/s)
    "rlds",      # Downward longwave radiation (W/m^2)
    "rsds"       # Downward shortwave radiation (W/m^2)
]

# Request all variables (default behavior)
climate_all = nldas.get_bycoords(
    coords=(-89.5, 45.5),
    start_date="2010-06-01",
    end_date="2010-06-01",
    variables=None  # Returns all variables
)

# Request specific subset
climate_subset = nldas.get_bycoords(
    coords=(-89.5, 45.5),
    start_date="2010-06-01",
    end_date="2010-06-01",
    variables=["temp", "prcp", "humidity"]
)

# Variable metadata preserved in xarray
climate_xr = nldas.get_bycoords(
    coords=(-89.5, 45.5),
    start_date="2010-06-01",
    end_date="2010-06-01",
    variables=["temp"],
    to_xarray=True
)
# climate_xr.temp.attrs contains:
# {'nldas_name': 'Tair',
#  'long_name': '2-m above ground temperature',
#  'units': 'K'}
```

--------------------------------

### Configure Caching and Connection Settings in pynldas2

Source: https://context7.com/hyriver/pynldas2/llms.txt

Shows how to manage data caching and connection settings in pynldas2. This includes using the default cache location, setting a custom cache path via an environment variable, disabling file size validation, and increasing the connection timeout for large requests.

```python
import pynldas2 as nldas
import os
from pathlib import Path

# Default cache location: ./cache directory
climate = nldas.get_bycoords(
    coords=(-89.5, 45.5),
    start_date="2010-01-01",
    end_date="2010-01-02"
)
# Creates: ./cache/[coordinate]_[variable]_[hash].txt

# Custom cache via environment variable
os.environ["HYRIVER_CACHE_NAME"] = "/custom/path/cache.db"
climate = nldas.get_bycoords(
    coords=(-89.5, 45.5),
    start_date="2010-01-01",
    end_date="2010-01-02"
)
# Caches to: /custom/path/[coordinate]_[variable]_[hash].txt

# Disable filesize validation for faster repeated access
climate = nldas.get_bycoords(
    coords=(-89.5, 45.5),
    start_date="2010-01-01",
    end_date="2010-12-31",
    validate_filesize=False  # Skip remote size check
)

# Increase timeout for large requests
climate_large = nldas.get_bygeom(
    geometry=(-100, 35, -90, 45),  # Large region
    start_date="2010-01-01",
    end_date="2010-12-31",
    conn_timeout=5000  # 5000 seconds
)

# Manual cache cleanup
cache_dir = Path("./cache")
if cache_dir.exists():
    # Remove all cached files for a fresh download
    for cache_file in cache_dir.glob("*.txt"):
        cache_file.unlink()

# Check package versions for debugging
nldas.show_versions()
# Prints system info and dependency versions
```

--------------------------------

### Access NLDAS2 Grid Masks with Custom Cache

Source: https://context7.com/hyriver/pynldas2/llms.txt

This snippet demonstrates how to retrieve grid mask information from NLDAS2 data using a custom cache directory. It shows how to specify the save directory for caching and how to access specific mask variables like CONUS_mask, LANDMASK, SOIL, and VEG.

```python
import pynldas2 as nldas

# Specify custom cache directory
grid_mask_custom = nldas.get_grid_mask(save_dir="./my_cache")

# Access specific mask variables
conus_mask = grid_mask.CONUS_mask  # Continental US boundary
land_mask = grid_mask.LANDMASK    # Land/water classification
soil_type = grid_mask.SOIL        # Soil texture classification
vegetation = grid_mask.VEG        # Vegetation type classification
```

--------------------------------

### Handle Web Service Errors with pynldas2

Source: https://context7.com/hyriver/pynldas2/llms.txt

Illustrates how to catch and handle NLDASServiceError exceptions that occur due to web service issues. This is useful for debugging connection problems or service unavailability.

```python
try:
    climate = nldas.get_bycoords(
        coords=(-89.5, 45.5),
        start_date="2010-01-01",
        end_date="2010-01-02",
        conn_timeout=1  # Very short timeout
    )
except NLDASServiceError as e:
    print(e)  # NLDAS2 web service returned error details
```

--------------------------------

### Download NLDAS2 Grid Mask (Python)

Source: https://context7.com/hyriver/pynldas2/llms.txt

Downloads and caches the NLDAS2 grid mask, which contains land, water, soil, and vegetation classifications. The function returns the grid mask as an xarray Dataset, providing spatial information for the NLDAS-2 grid.

```python
import pynldas2 as nldas

# Download and cache grid mask
grid_mask = nldas.get_grid_mask()

# Result: xarray.Dataset with grid properties
# <xarray.Dataset>
# Dimensions:      (lat: 224, lon: 464)
# Coordinates:

```

--------------------------------

### Handle Invalid CRS with pynldas2

Source: https://context7.com/hyriver/pynldas2/llms.txt

Demonstrates how to catch and handle Invalid CRS errors when using the get_bycoords function. It shows the expected exception type and how to print the error message.

```python
try:
    climate = nldas.get_bycoords(
        coords=(-89.5, 45.5),
        start_date="2010-01-01",
        end_date="2010-01-02",
        crs="invalid_crs"
    )
except InputTypeError as e:
    print(e)  # The crs argument should be of type a valid CRS
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.