Skip to main content

ECOSTRESS Collection 3 CMR Tools

ECOv003-CMR searches NASA's Common Metadata Repository (CMR) for ECOSTRESS Collection 3 granules, downloads granules, and samples raster values at geographic points.

CI

Requirements and installation

Python 3.11 or later is required. Install the package from PyPI:

python -m pip install ECOv003-CMR

NASA Earthdata authentication

CMR search is public. Downloading and reading ECOSTRESS data requires a NASA Earthdata account and credentials. Configure either ~/.netrc:

machine urs.earthdata.nasa.gov
    login YOUR_USERNAME
    password YOUR_PASSWORD

or the EARTHDATA_USERNAME and EARTHDATA_PASSWORD environment variables. Protect the .netrc file so that only your account can read it:

chmod 600 ~/.netrc

Create an account at urs.earthdata.nasa.gov and authorize the relevant LP DAAC applications if prompted.

Supported products

The package supports these Collection 3 CMR product codes:

Product Description Example variables
L1CT_RAD Calibrated at-sensor radiance radiance_1
L2T_LSTE Land surface temperature and emissivity LST, LST_err, QC, EmisWB
L2T_STARS Surface reflectance and vegetation/albedo layers NDVI, albedo
L3T_ETAUX Tiled evapotranspiration auxiliary data Ta, RH, SM, Rg, Rn, cloud, water
L3T_JET Jet Propulsion Laboratory evapotranspiration product PTJPLSMinst
L4T_ESI Evaporative Stress Index ESI
L4T_WUE Water Use Efficiency WUE

Collection 3 replaces the separate Collection 2 L3T_MET, L3T_SM, and L3T_SEB products with L3T_ETAUX. Do not use the discontinued product names for Collection 3 searches.

Search CMR

Use ECOSTRESS_CMR_search() to find files for a product, Sentinel-2 tile, and date range:

from datetime import date
from ECOv003_CMR import ECOSTRESS_CMR_search

results = ECOSTRESS_CMR_search(
    product="L2T_LSTE",
    tile="52NHN",
    start_date=date(2026, 6, 1),
    end_date=date(2026, 6, 7),
)

geotiffs = results[results["type"] == "GeoTIFF Data"]
print(geotiffs[["product", "variable", "granule", "URL"]].head())

The result is a pandas DataFrame with parsed granule and file metadata. Search accepts a product or list of products and a tile or list of tiles. Use CONCEPT_IDS for the supported product-to-CMR collection map.

The command-line search accepts the same products:

ECOv003-search \
  --product L2T_LSTE L2T_STARS \
  --tile 52NHN \
  --start-date 2026-06-01 \
  --end-date 2026-06-07 \
  --output ecostress-files.csv

Run ECOv003-search --help for all options.

Download granules

Download and open granules from Python with download_ECOSTRESS_granule():

from datetime import date
from ECOv003_CMR import download_ECOSTRESS_granule

granule = download_ECOSTRESS_granule(
    product="L2T_LSTE",
    tile="52NHN",
    aquisition_date=date(2026, 6, 1),
    parent_directory="./data",
)
print(granule)

The default parent directory is ~/data/ECOSTRESS_v003. The equivalent CLI command is:

ECOv003-download \
  --product L2T_LSTE \
  --tile 52NHN \
  --start-date 2026-06-01 \
  --parent-directory ./data

Downloading requires Earthdata authentication. The CLI accepts multiple products and tiles, date ranges, and optional orbit/scene filters; see ECOv003-download --help.

Point sampling

Point-sampling functions are exported by ECOv003_CMR. Coordinates are interpreted as EPSG:4326; GeoDataFrames must declare a CRS and are reprojected to WGS84 when needed. ST_C is returned in Celsius, while LST remains in Kelvin.

Search a date range

Use sample_points_over_date_range() when you do not know the acquisition times. It searches CMR for acquisitions over the requested period:

from datetime import date
import geopandas as gpd
from shapely.geometry import Point
from ECOv003_CMR import sample_points_over_date_range

sites = gpd.GeoDataFrame(
    {
        "site_id": ["downtown", "airport"],
        "geometry": [Point(-118.2437, 34.0522), Point(-118.4085, 33.9416)],
    },
    crs="EPSG:4326",
)

samples = sample_points_over_date_range(
    geometry=sites,
    start_date=date(2026, 6, 1),
    end_date=date(2026, 6, 7),
    layers=["ST_C", "NDVI", "albedo", "Ta_C"],
)
print(samples[["site_id", "timestamp", "ST_C", "NDVI", "albedo", "Ta_C"]])

The default layers are ST_C, NDVI, and albedo. This function can also accept a single Shapely Point, a list of points, or a GeoSeries. It uses max_workers to control parallel sampling.

Sample near known datetimes

Use sample_points_from_geodataframe() when your GeoDataFrame has a datetime column for each point. It searches within date_buffer_days of each datetime:

from datetime import datetime
import geopandas as gpd
from shapely.geometry import Point
from ECOv003_CMR import sample_points_from_geodataframe

sites = gpd.GeoDataFrame(
    {
        "site_id": ["downtown"],
        "datetime": [datetime(2026, 6, 1, 12)],
        "geometry": [Point(-118.2437, 34.0522)],
    },
    crs="EPSG:4326",
)

samples = sample_points_from_geodataframe(
    geometry=sites,
    layers=["ST_C", "NDVI", "albedo"],
    datetime_col="datetime",
    date_buffer_days=1,
)
print(samples[["site_id", "timestamp", "ST_C", "NDVI", "albedo"]])

Available sampling layers

Layer Product variable Units or meaning
ST_C L2T_LSTE / LST Land surface temperature, Celsius (converted from Kelvin)
LST L2T_LSTE / LST Land surface temperature, Kelvin
LST_err, QC, EmisWB / emissivity L2T_LSTE Uncertainty, quality, and wideband emissivity
NDVI, albedo L2T_STARS Vegetation index and albedo
Ta_C / Ta L3T_ETAUX / Ta Near-surface air temperature, Celsius
RH, SM L3T_ETAUX Relative humidity and soil moisture ratios
Rg, Rn L3T_ETAUX Global and net radiation, W/m²
cloud, water L3T_ETAUX Cloud and water masks

The former EVI and SAVI layers are not included in the supported Collection 3 sampling mappings. Unsupported layers raise ValueError.

Sample one raster URL

sample_point_from_url() samples one pixel from a raster URL and returns (value, metadata). If the point is outside the raster or has nodata, the value is None and the second result describes the reason.

from ECOv003_CMR import setup_earthdata_session, sample_point_from_url

session = setup_earthdata_session()
value, metadata = sample_point_from_url(
    session=session,
    url="URL_FROM_A_CMR_SEARCH_RESULT",
    lon=-118.2437,
    lat=34.0522,
)

See the scripts in examples/ for runnable workflows, including CSV input and multi-site sampling.

Development and tests

The test suite uses mocked CMR responses and in-memory raster fixtures; it does not require authenticated downloads:

pytest -q

Live authenticated download/open and point-sampling checks are recommended before a release.

Metadata

Release files for ECOv003-CMR 1.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ECOv003-CMR 1.0.0
File Size Uploaded Provenance Actions
ecov003_cmr-1.0.0.tar.gz 2.6 MB Without provenance Details for ecov003_cmr-1.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ECOv003-CMR 1.0.0
File Interpreter ABI Platform Actions
ecov003_cmr-1.0.0-py3-none-any.whl Python 3 none any Details for ecov003_cmr-1.0.0-py3-none-any.whl

Total release size: 2.6 MB

Release files / ecov003_cmr-1.0.0.tar.gz

Download URL ecov003_cmr-1.0.0.tar.gz
Size 2.6 MB
Tags Source
SHA-256 checksum
How to use checksums
32c2a423189cb90c18747b653f18219a113dd3ce5a4ccadfab9c6e7e0cdad3c1
BLAKE2b-256 checksum
How to use checksums
5d339d2a7c4ddd1493cb1b96ed81c6d0a1be194d4c356bdc9abcb95bf1a30cb9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.18

Release files / ecov003_cmr-1.0.0-py3-none-any.whl

Download URL ecov003_cmr-1.0.0-py3-none-any.whl
Size 39.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
04502013a6d072684a67cb4d4fbe597533a380599b7d67ddd328ec5dc2fe681a
BLAKE2b-256 checksum
How to use checksums
7fbf8cefaffc8dfe0b0d2ca753f571339b2026bf98755256307cdc71ab8d7c3c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.18

Security for ECOv003-CMR 1.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.0.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page