composite_stac#

geowombat.core.stac.composite_stac(stac_catalog=STACNames.ELEMENT84_V1, collection=None, bounds=None, proj_bounds=None, start_date=None, end_date=None, cloud_cover_perc=None, bands=None, chunksize=256, mask_items=None, bounds_query=None, epsg=None, resolution=None, resampling=Resampling.nearest, nodata_fill=None, frequency='MS', agg='median', max_items=100, compute=True, num_workers=4)[source]#

Creates cloud-free temporal composites from STAC data.

Wraps open_stac() to produce composites at a specified temporal frequency. Data is cloud-masked using pixel-level QA (Landsat qa_pixel), SCL (Sentinel-2), or Fmask (HLS) bands, then aggregated using the chosen method (default: median).

Parameters:

stac_catalog (str) – The STAC catalog. See open_stac() for options. Ignored when collection='hls' (uses nasa_lp_cloud).
collection (str) – The STAC collection. See open_stac() for options. Use 'hls' to query both hls_l30 and hls_s30, merge observations, then composite. Only bands common to both sensors are allowed (blue, green, red, nir, swir1, swir2, coastal, cirrus).
bounds (Union[Sequence[float], str, Path, GeoDataFrame]) – The search bounding box. See open_stac().
proj_bounds (Sequence[float]) – The projected bounds. See open_stac().
start_date (str) – The start search date (yyyy-mm-dd).
end_date (str) – The end search date (yyyy-mm-dd).
cloud_cover_perc (float | int) – Maximum cloud cover percentage for scene-level filtering.
bands (sequence) – The bands to open. Do not include qa_pixel, scl, or Fmask; these are added automatically for masking.
chunksize (int) – The dask chunk size.
mask_items (sequence) – Items to mask. See open_stac() for sensor-specific defaults.
bounds_query (str) – A query for GeoDataFrame bounds.
epsg (int) – An EPSG code to warp to.
resolution (float | int) – Cell resolution.
resampling (Optional[Resampling]) – The resampling method.
nodata_fill (float | int) – Fill value for nodata.
frequency (str) –
Pandas offset alias for temporal grouping. Default 'MS' (month start). Common values:
- 'D' — daily
- 'W' — weekly
- '2W' — biweekly (every 2 weeks)
- 'MS' — monthly (month start)
- 'QS' — quarterly (quarter start)
- 'YS' — yearly (year start)
Multiplied forms (e.g., '15D', '2MS') are supported. See pandas offset aliases.
agg (str) – Aggregation method for compositing. Default 'median'. Options: 'median', 'mean', 'min', 'max'.
max_items (int) – Maximum STAC search items.
compute (bool) – Whether to eagerly load data.
num_workers (int) – Number of threads for parallel downloads when compute=True. Default is 4.

Return type:

Optional[Tuple[DataArray, DataFrame]]

Returns:

tuple of (xarray.DataArray, pandas.DataFrame) or (None, None) if no data found.

Examples

>>> from geowombat.core.stac import composite_stac
>>>
>>> # Monthly median composite of Sentinel-2
>>> composite, df = composite_stac(
...     collection='sentinel_s2_l2a',
...     start_date='2022-01-01',
...     end_date='2022-12-31',
...     bounds='aoi.geojson',
...     bands=['blue', 'green', 'red', 'nir'],
...     cloud_cover_perc=50,
...     frequency='MS',
...     resolution=10.0,
... )
>>>
>>> # Quarterly composite of Landsat
>>> composite, df = composite_stac(
...     stac_catalog='microsoft_v1',
...     collection='landsat_c2_l2',
...     start_date='2022-01-01',
...     end_date='2022-12-31',
...     bounds='aoi.geojson',
...     bands=['red', 'green', 'blue'],
...     cloud_cover_perc=30,
...     frequency='QS',
...     resolution=30.0,
... )
>>>
>>> # Combined HLS (Landsat + Sentinel-2) composite
>>> composite, df = composite_stac(
...     collection='hls',
...     start_date='2023-06-01',
...     end_date='2023-08-31',
...     bounds=(-77.1, 38.85, -76.95, 38.95),
...     bands=['blue', 'green', 'red', 'nir'],
...     epsg=32618,
...     resolution=30.0,
...     frequency='MS',
... )

composite_stac

Contents

composite_stac#