gedih3.egi.dataframe#

EGI (EASE Grid Index) DataFrame Module

This module provides operations for integrating EGI spatial indexing with pandas and GeoPandas DataFrames: - Adding EGI indices to DataFrames based on coordinates - Converting between resolution levels (to_parent) - Aggregation functions with spatial grouping - Conversion to/from GeoDataFrames

Functions#

`egi_dataframe`(→ geopandas.GeoDataFrame)	Add EGI spatial index to a DataFrame based on coordinate columns.
`egi_dataframe_vectorized`(→ geopandas.GeoDataFrame)	Add EGI spatial index using vectorized operations (faster for large datasets).
`egi_to_parent`(→ Union[pandas.DataFrame, ...)	Convert EGI-indexed DataFrame to a coarser resolution level.
`egi_to_parent_vectorized`(→ Union[pandas.DataFrame, ...)	Convert EGI-indexed DataFrame to coarser resolution (vectorized version).
`egi_to_geo`(→ geopandas.GeoDataFrame)	Add geometry to an EGI-indexed DataFrame.
`egi_aggregate`(→ Union[pandas.DataFrame, ...)	Aggregate EGI-indexed DataFrame by spatial index.
`egi_col_from_df`(→ Optional[str])	Find the EGI column in a DataFrame.
`egi_get_level_from_df`(→ Optional[int])	Get the EGI resolution level from a DataFrame's index.

Module Contents#

gedih3.egi.dataframe.egi_dataframe(df: pandas.DataFrame | geopandas.GeoDataFrame, x_col: str = 'lon_lowestmode', y_col: str = 'lat_lowestmode', level: int = 1, in_epsg: int = 4326, set_index: bool = True) → geopandas.GeoDataFrame[source]#

Add EGI spatial index to a DataFrame based on coordinate columns.

This is the primary function for converting GEDI shot data to EGI-indexed format. It reprojects coordinates to EPSG:6933 and computes EGI hashes at the specified resolution level.

Parameters:

dfDataFrame or GeoDataFrame: Input data with coordinate columns or Point geometries
x_colstr: Name of longitude/X column (default: ‘lon_lowestmode’)
y_colstr: Name of latitude/Y column (default: ‘lat_lowestmode’)
levelint: EGI resolution level (1-12), default=1 (finest)
in_epsgint: EPSG code of input coordinates (default: 4326 for WGS84)
set_indexbool: If True, set the EGI column as the DataFrame index

Returns:

GeoDataFrame: GeoDataFrame with EGI column added and optionally set as index

Examples

>>> # Add EGI index to GEDI shots
>>> gedi_df = pd.read_parquet("gedi_shots.parquet")
>>> egi_df = egi_dataframe(gedi_df, level=6)  # ~1km resolution
>>>
>>> # Using existing GeoDataFrame
>>> gdf = gpd.read_file("points.gpkg")
>>> egi_gdf = egi_dataframe(gdf, level=6)

gedih3.egi.dataframe.egi_dataframe_vectorized(df: pandas.DataFrame | geopandas.GeoDataFrame, x_col: str = 'lon_lowestmode', y_col: str = 'lat_lowestmode', level: int = 1, in_epsg: int = 4326, set_index: bool = True) → geopandas.GeoDataFrame[source]#

Add EGI spatial index using vectorized operations (faster for large datasets).

This is an optimized version of egi_dataframe() that uses numpy vectorization for better performance on large datasets.

Parameters:

dfDataFrame or GeoDataFrame: Input data with coordinate columns
x_colstr: Name of longitude/X column
y_colstr: Name of latitude/Y column
levelint: EGI resolution level (1-12)
in_epsgint: EPSG code of input coordinates
set_indexbool: If True, set the EGI column as index

Returns:

GeoDataFrame: GeoDataFrame with EGI column added

gedih3.egi.dataframe.egi_to_parent(gdf: pandas.DataFrame | geopandas.GeoDataFrame, parent_level: int = OUTER_LEVEL, set_index: bool = True) → pandas.DataFrame | geopandas.GeoDataFrame[source]#

Convert EGI-indexed DataFrame to a coarser resolution level.

Parameters:

gdfDataFrame or GeoDataFrame: EGI-indexed DataFrame (index must be EGI hash)
parent_levelint: Target coarser resolution level
set_indexbool: If True, replace the index with the parent level

Returns:

DataFrame or GeoDataFrame: DataFrame with parent-level EGI column/index

Examples

>>> # Aggregate from level 1 to level 6
>>> parent_df = egi_to_parent(fine_df, parent_level=6)

gedih3.egi.dataframe.egi_to_parent_vectorized(gdf: pandas.DataFrame | geopandas.GeoDataFrame, parent_level: int = OUTER_LEVEL, set_index: bool = True) → pandas.DataFrame | geopandas.GeoDataFrame[source]#

Convert EGI-indexed DataFrame to coarser resolution (vectorized version).

This is an optimized version using numpy vectorization.

Parameters:

gdfDataFrame or GeoDataFrame: EGI-indexed DataFrame
parent_levelint: Target coarser resolution level
set_indexbool: If True, replace the index with parent level

Returns:

DataFrame or GeoDataFrame: DataFrame with parent-level EGI column/index

gedih3.egi.dataframe.egi_to_geo(df: pandas.DataFrame | geopandas.GeoDataFrame, polygons: bool = True) → geopandas.GeoDataFrame[source]#

Add geometry to an EGI-indexed DataFrame.

Parameters:

dfDataFrame or GeoDataFrame: EGI-indexed DataFrame
polygonsbool: If True, use polygon geometries; if False, use point centroids

Returns:

GeoDataFrame: GeoDataFrame with geometry column added

Examples

>>> # Add polygon geometries for visualization
>>> gdf = egi_to_geo(aggregated_df, polygons=True)

Aggregate EGI-indexed DataFrame by spatial index.

Parameters:

gdfDataFrame or GeoDataFrame: EGI-indexed DataFrame
mapperstr, list, dict, or callable: Aggregation specification: - str: Single aggregation function (e.g., ‘mean’, ‘sum’, ‘count’) - list: Multiple functions [‘mean’, ‘std’, ‘count’] - dict: Per-column specification {‘col1’: ‘mean’, ‘col2’: [‘min’, ‘max’]} - callable: Custom aggregation function
return_geometrybool: If True, return GeoDataFrame with geometry
geom_pointsbool: If True and return_geometry, use point centroids instead of polygons

Returns:

DataFrame or GeoDataFrame: Aggregated data, optionally with geometry

Examples

>>> # Simple mean aggregation
>>> agg_df = egi_aggregate(shots_df, mapper='mean')
>>>
>>> # Multiple aggregations
>>> agg_df = egi_aggregate(shots_df, mapper=['mean', 'std', 'count'])
>>>
>>> # Per-column specification
>>> agg_df = egi_aggregate(shots_df, mapper={'agbd': 'mean', 'rh_098': ['mean', 'std']})

gedih3.egi.dataframe.egi_col_from_df(df: pandas.DataFrame | geopandas.GeoDataFrame) → str | None[source]#

Find the EGI column in a DataFrame.

Parameters:

dfDataFrame or GeoDataFrame: DataFrame to search

Returns:

str or None: Name of the EGI column, or None if not found

gedih3.egi.dataframe.egi_get_level_from_df(df: pandas.DataFrame | geopandas.GeoDataFrame) → int | None[source]#

Get the EGI resolution level from a DataFrame’s index.

Parameters:

dfDataFrame or GeoDataFrame: EGI-indexed DataFrame

Returns:

int or None: Resolution level, or None if not EGI-indexed