alsdb.processing.gap.compute_gap_fraction#

alsdb.processing.gap.compute_gap_fraction(provider: TileDBProvider, store: ALSZarrStore, resolution: float = 10.0, bbox: tuple[float, float, float, float] | None = None, year: int | None = None, *, lai: bool = False, k: float = 0.5, clumping_index: float = 1.0, baba_radius: float = 0.0, min_density: float = 0.0, overwrite: bool = False, tile_size: float = 500.0, tile_buffer: float = 50.0, n_workers: int = 1) → None[source]#

Compute gap fraction (and optionally effective LAI) and write into store.

Gap fraction is the MacArthur-Wilson estimator:

P_gap = N_gnd_first / (N_gnd_first + N_veg_first)

When lai=True, effective LAI is derived via the Beer-Lambert law with an optional clumping correction (Jonckheere et al. 2004):

L_true = -ln(P_gap) / (k × Ω)

where k is the extinction coefficient and Ω is the element clumping index. For biome-appropriate k values see LAI_K_PRESETS.

Parameters:

  • provider – TileDB provider instance.

  • store – ALSZarrStore target. Must have "gap" (and "lai" if lai=True) pre-allocated at resolution.

  • resolution – Cell size in metres (default 10 m).

  • bbox – Optional spatial filter (min_x, min_y, max_x, max_y).

  • year – Survey year filter. Written as a time slice in the store.

  • lai – If True, also compute effective LAI via Beer-Lambert.

  • k – Extinction coefficient (default 0.5, spherical leaf angle distribution). See LAI_K_PRESETS for biome presets. Only used when lai=True.

  • clumping_index – Element clumping index Ω ∈ (0, 1] (default 1.0 = no correction). Values < 1 correct for foliage clumping — typical ranges: 0.5–0.7 for conifers, 0.7–0.9 for broadleaf forests. Only used when lai=True.

  • min_density – Minimum first-return density (returns m⁻²) for a cell to receive a gap fraction estimate. Cells below this threshold are set to np.nan. Default 0.0 disables the guard.

  • overwrite – If False (default) and gap (and LAI if requested) already exist for year in the store, the computation is skipped.

  • tile_size – Sub-tile width and height in metres (default 500 m).

  • tile_buffer – Overlap buffer for filters.hag_delaunay accuracy (default 50 m).

  • n_workers – Parallel workers (default 1 = sequential).

On this page