gedih3.raster.timeseries#

Time-Series Raster Generation Module

This module provides functions for generating time-series raster products from GEDI data. It supports: - Temporal filtering by date range - Time-windowed aggregation (years, months, weeks, days) - Batch raster generation for time intervals

Attributes#

GEDI_START_DATE

Classes#

TimeSeriesRasterizer

Class for generating time-series raster products.

Functions#

`parse_datetime_column`(→ Optional[str])	Find and identify the datetime column in a DataFrame.
`convert_delta_time_to_datetime`(...)	Convert GEDI delta_time (seconds since epoch) to datetime.
`generate_time_windows`(...)	Generate time windows for temporal aggregation.
`filter_by_time_range`(→ Union[pandas.DataFrame, ...)	Filter DataFrame by time range.
`build_temporal_query`(→ Optional[str])	Build a pandas query string for temporal filtering.

Module Contents#

gedih3.raster.timeseries.GEDI_START_DATE#

gedih3.raster.timeseries.parse_datetime_column(df: pandas.DataFrame | geopandas.GeoDataFrame, time_col: str | None = None) → str | None[source]#

Find and identify the datetime column in a DataFrame.

Parameters:

dfDataFrame or GeoDataFrame: Input data
time_colstr, optional: Explicit column name to use

Returns:

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

gedih3.raster.timeseries.convert_delta_time_to_datetime(df: pandas.DataFrame | geopandas.GeoDataFrame, delta_time_col: str = 'delta_time', output_col: str = 'datetime') → pandas.DataFrame | geopandas.GeoDataFrame[source]#

Convert GEDI delta_time (seconds since epoch) to datetime.

GEDI delta_time is seconds since 2018-01-01 00:00:00 UTC.

Parameters:

dfDataFrame or GeoDataFrame: Input data with delta_time column
delta_time_colstr: Name of the delta_time column
output_colstr: Name for the output datetime column

Returns:

DataFrame or GeoDataFrame: Data with new datetime column added

gedih3.raster.timeseries.generate_time_windows(start_date: str | datetime.datetime, end_date: str | datetime.datetime, interval: int, units: str = 'years') → Generator[Tuple[datetime.datetime, datetime.datetime, str], None, None][source]#

Generate time windows for temporal aggregation.

Parameters:

start_datestr or datetime: Start date (YYYY-MM-DD format if string)
end_datestr or datetime: End date (YYYY-MM-DD format if string)
intervalint: Number of time units per window
unitsstr: Time unit: ‘years’, ‘months’, ‘weeks’, ‘days’

Yields:

tuple: (window_start, window_end, suffix_string)

Examples

>>> # Generate yearly windows
>>> for t0, t1, suffix in generate_time_windows('2020-01-01', '2023-01-01', 1, 'years'):
...     print(f"{suffix}: {t0} to {t1}")
2020-01-01-to-2021-01-01: 2020-01-01 00:00:00 to 2021-01-01 00:00:00
2021-01-01-to-2022-01-01: 2021-01-01 00:00:00 to 2022-01-01 00:00:00
2022-01-01-to-2023-01-01: 2022-01-01 00:00:00 to 2023-01-01 00:00:00

Filter DataFrame by time range.

Parameters:

dfDataFrame or GeoDataFrame: Input data with datetime column
start_datestr or datetime, optional: Start date for filtering (inclusive)
end_datestr or datetime, optional: End date for filtering (exclusive)
time_colstr: Name of the datetime column

Returns:

DataFrame or GeoDataFrame: Filtered data

gedih3.raster.timeseries.build_temporal_query(start_date: str | None = None, end_date: str | None = None, time_col: str = 'datetime') → str | None[source]#

Build a pandas query string for temporal filtering.

Parameters:

start_datestr, optional: Start date (YYYY-MM-DD)
end_datestr, optional: End date (YYYY-MM-DD)
time_colstr: Name of the datetime column

Returns:

str or None: Query string for pandas.query(), or None if no filters

class gedih3.raster.timeseries.TimeSeriesRasterizer(gdf: pandas.DataFrame | geopandas.GeoDataFrame, time_col: str = 'datetime', aggregation: str | List | dict | Callable = 'mean', target_level: int = 6, use_egi: bool = False, columns: List[str] | None = None)[source]#

Class for generating time-series raster products.

This class provides a convenient interface for generating multiple raster outputs for different time windows from a single dataset.

Parameters:

gdfGeoDataFrame or dask GeoDataFrame: Input H3 or EGI-indexed data
time_colstr: Name of the datetime column
aggregationstr, list, dict, or callable: Aggregation specification for spatial aggregation
target_levelint: Target spatial resolution level (H3 or EGI)
use_egibool: If True, use EGI; if False, use H3
columnslist, optional: Columns to include in output

Examples

>>> rasterizer = TimeSeriesRasterizer(
...     gdf=data,
...     time_col='datetime',
...     aggregation='mean',
...     target_level=6,
...     use_egi=True
... )
>>>
>>> # Generate yearly rasters
>>> for raster, suffix in rasterizer.generate(
...     start_date='2020-01-01',
...     end_date='2023-01-01',
...     interval=1,
...     units='years'
... ):
...     raster.rio.to_raster(f"output_{suffix}.tif")

gdf#

time_col = 'datetime'#

aggregation = 'mean'#

target_level = 6#

use_egi = False#

columns = None#

generate(start_date: str, end_date: str, interval: int, units: str = 'years', to_raster: bool = True) → Generator[Tuple[geopandas.GeoDataFrame | xarray.Dataset, str], None, None][source]#

Generate time-series outputs.

Parameters:

start_datestr: Start date (YYYY-MM-DD)
end_datestr: End date (YYYY-MM-DD)
intervalint: Number of time units per window
unitsstr: Time unit: ‘years’, ‘months’, ‘weeks’, ‘days’
to_rasterbool: If True, convert to raster; if False, return GeoDataFrame

Yields:

tuple: (output_data, time_suffix)