gedih3.daac#

Attributes#

`logger`
`DOWNLOAD_CONNECT_TIMEOUT_DEFAULT`
`DOWNLOAD_READ_TIMEOUT_DEFAULT`

Classes#

GEDIAccessor

NASA Earthdata accessor for searching and downloading GEDI granules.

Functions#

`gedi_list_versions`(→ List[dict])	Query NASA CMR for all available versions of a GEDI product.
`gedi_latest_version`(→ str)	Return the latest available version string for a GEDI product.
`download_custom_granule`(→ Optional[str])	Download a custom (non-GEDI) granule with retry logic.
`download_granule`(→ Optional[str])	Download a GEDI granule with retry logic and optional variable subsetting.
`gedi_download`(→ Union[Dict[str, List[str]], List[str]])	Download GEDI granules for specified products and variables.

Module Contents#

gedih3.daac.logger#

gedih3.daac.DOWNLOAD_CONNECT_TIMEOUT_DEFAULT = 60.0#

gedih3.daac.DOWNLOAD_READ_TIMEOUT_DEFAULT = 300.0#

gedih3.daac.gedi_list_versions(product: str) → List[dict][source]#

Query NASA CMR for all available versions of a GEDI product.

Parameters:

productstr: Product code (e.g., ‘L2A’, ‘L4A’)

Returns:

list of dict: Available versions with metadata, sorted by version string.

gedih3.daac.gedi_latest_version(product: str) → str[source]#

Return the latest available version string for a GEDI product.

Parameters:

productstr: Product code (e.g., ‘L2A’, ‘L4A’)

Returns:

str: Latest version string (e.g., ‘002’)

Raises:

GediProductError: If no versions are found

class gedih3.daac.GEDIAccessor(authenticate: bool = True, spatial: List[float] | shapely.geometry.Polygon | str | geopandas.GeoDataFrame = None, temporal: Tuple[str, str] | List[str] = None)[source]#

NASA Earthdata accessor for searching and downloading GEDI granules.

Provides authentication, spatial/temporal filtering, granule search, and batch download functionality using the earthaccess library.

Parameters:

authenticatebool: If True (default), automatically call login() on initialization.
spatiallist, Polygon, str, or GeoDataFrame, optional: Spatial filter: bounding box [W, S, E, N], Shapely geometry, vector file path, or GeoDataFrame.
temporaltuple or list of str, optional: Temporal filter as (start_date, end_date), e.g. ('2020-01-01', '2021-01-01').

Raises:

GediAuthenticationError: If authentication fails on initialization (when authenticate=True).

Examples

>>> accessor = GEDIAccessor(
...     spatial=[-51, 0, -50, 1],
...     temporal=('2020-01-01', '2021-01-01')
... )
>>> granules = accessor.search_data('L4A')
>>> paths = accessor.download_all('/path/to/output', product='L4A')

product_files#

authenticated = False#

login(strategy: str = 'netrc', persist: bool = True, max_attempts: int = 3)[source]#

Authenticate with NASA Earthdata Login.

Parameters:

strategystr: Authentication strategy (‘netrc’, ‘environment’, ‘interactive’). Default is ‘netrc’ which reads credentials from ~/.netrc file. Use ‘environment’ for EDL_USERNAME/EDL_PASSWORD env vars. Use ‘interactive’ only in interactive terminals (may crash VSCode).
persistbool: Whether to persist credentials
max_attemptsint: Maximum authentication attempts

Raises:

GediAuthenticationError: If authentication fails after all attempts

Notes

For CLI usage, credentials should be stored in ~/.netrc file:

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

Create an account at https://urs.earthdata.nasa.gov/ if needed.

Token-based authentication is also supported by setting the EARTHDATA_TOKEN environment variable. When set, earthaccess uses the token directly regardless of the strategy parameter. This is the recommended approach for HPC environments.

search_data(product: str = None, version: str = None, **kwargs) → List[Any][source]#

Search for GEDI granules with spatial and temporal filtering.

Uses short_name + version for GEDI product searches (preferred over DOI). Falls back to DOI if short_name is not available.

Parameters:

productstr, optional: GEDI product level (‘L1B’, ‘L2A’, ‘L2B’, ‘L4A’, ‘L4C’). If None, uses kwargs directly for custom dataset searches.
versionstr or int, optional: GEDI data version (e.g., ‘002’ or 2). If None, earthaccess returns the latest version by default.
**kwargsdict: Additional search parameters passed to earthaccess.search_data().

Returns:

list: List of granule objects

Examples

>>> accessor.search_data('L4A')
>>> accessor.search_data('L4A', version=2)
>>> accessor.search_data(short_name='MY_PRIVATE_DATASET', version='001')

download_all(download_dir: str = None, product: str = None, **kwargs)[source]#

Download all searched granules.

Parameters:

download_dirstr, optional: Output directory. Defaults to GH3_DEFAULT_DOWNLOAD_DIR.
productstr, optional: Product key to download. If None, downloads all granules.
show_progressbool, optional: Whether to display download progress bar. Passed through to earthaccess.download() via **kwargs.
**kwargs: Additional arguments passed to earthaccess.download().

link_s3(product: str = None)[source]#

merge_paths(open_s3: bool = False)[source]#

gedih3.daac.download_custom_granule(granule, odir: str, resume: bool = False, max_attempts: int = RETRY_DEFAULTS['max_attempts']) → str | None[source]#

Download a custom (non-GEDI) granule with retry logic.

This function handles granules from any NASA dataset without requiring GEDI-specific filename parsing. Files are downloaded directly to the output directory without year/doy subdirectory structure.

Parameters:

granuleearthaccess.Granule: Granule object to download
odirstr: Output directory for downloaded files
resumebool: If True, skip already-downloaded files
max_attemptsint: Maximum download attempts on failure

Returns:

str or None: Path to downloaded file, or None on failure

gedih3.daac.download_granule(granule, odir: str = None, subset_vars: List[str] = None, resume: bool = False, max_attempts: int = RETRY_DEFAULTS['max_attempts']) → str | None[source]#

Download a GEDI granule with retry logic and optional variable subsetting.

Parameters:

granuleearthaccess.Granule: Granule object to download
odirstr: Base output directory
subset_varslist of str, optional: Variables to extract (subset HDF5 after download)
resumebool: If True, skip already-downloaded files
max_attemptsint: Maximum download attempts on failure

Returns:

str or None: Path to downloaded/existing file, or None on failure

gedih3.daac.gedi_download(product_vars: Dict = None, odir: str = None, spatial=None, temporal=None, version=None, n_jobs: int = 5, to_list: bool = False, resume: bool = False, max_attempts: int = RETRY_DEFAULTS['max_attempts'], search_kwargs: Dict = None, granule_names: Iterable[str] | None = None, on_granule_complete: Callable | None = None) → Dict[str, List[str]] | List[str][source]#

Download GEDI granules for specified products and variables.

Parameters:

product_varsdict, optional: Dictionary mapping product codes to variable specifications. If None and search_kwargs is provided, downloads a custom dataset.
odirstr, optional: Output directory. If None, returns S3 links instead of downloading.
spatialvarious, optional: Spatial filter (bbox, file path, or GeoDataFrame)
temporaltuple, optional: Temporal filter as (start_date, end_date)
versionint or str, optional: GEDI data version (e.g., 2 or ‘002’). If None, uses latest available.
n_jobsint: Number of parallel download jobs (when not using Dask)
to_listbool: If True, return flat list instead of dict
resumebool: If True, skip already-downloaded files
max_attemptsint: Maximum download attempts per granule
search_kwargsdict, optional: Custom search parameters for non-GEDI datasets.
granule_namesiterable of str, optional: Restrict the CMR search to these specific GEDI granule filenames. Trailing .h5 is stripped before forwarding to CMR because readable_granule_name matches the filename stem, not the full filename. Ignored for CUSTOM datasets (use search_kwargs with granule_name=... instead).
on_granule_completecallable, optional: Callback (granule_info_dict, status_str) -> None called after each granule completes. granule_info_dict has orbit, granule, track, and path keys. path is the target SOC path on 'PENDING', the actual downloaded file path on 'DOWNLOADED', and None on 'FAILED'. status_str is one of 'PENDING', 'DOWNLOADED', or 'FAILED'.

Returns:

dict or list: Downloaded file paths, organized by product or as flat list.

Raises:

GediAuthenticationError: If NASA Earthdata authentication fails.
GediValidationError: If neither product_vars nor search_kwargs is provided.
GediDownloadError: If downloads fail after all retry attempts.

Examples

>>> from gedih3.daac import gedi_download
>>> paths = gedi_download(
...     product_vars={'L2A': ['default'], 'L4A': ['agbd']},
...     odir='/path/to/output',
...     spatial=[-51, 0, -50, 1],
...     temporal=('2020-01-01', '2021-01-01'),
...     resume=True,
... )