eomatch.enrich.roi_valid_fraction.roi_valid_fraction

eomatch.enrich.roi_valid_fraction.roi_valid_fraction(matchup, min_collocation_area_km2: float | None = None, gate: Dict[str, Dict[str, Any]] | None = None) → Dict[str, Any]

Return the fraction of this matchup’s collocation region with valid satellite data.

For a matchup with more than one satellite product (a sat2sat case), the minimum across products is used – a mostly-valid product masking one that’s entirely empty would hide exactly the case this enricher exists to catch (the same reasoning as eomatch.enrich.roi_cloud_cover.roi_cloud_cover() taking the maximum across products, just inverted since here a higher value is the good outcome).

Parameters:

• matchup – Matchup to enrich.

• min_collocation_area_km2 – if given, a matchup whose collocation_region area (computed directly from geometry via eomatch.utils.geometry.collocation_area_km2() – independent of whether eomatch.enrich.geometric.geometric() has already run) is below this returns {} immediately, before resolving or downloading any product. None (the default) applies no gate, preserving existing behaviour. A generalisation of one specific case of gate below; kept as its own parameter for backwards compatibility.

• gate – generic version of the same idea – see eomatch.enrich._gate.passes_gate() for exactly which properties can be checked and how a not-yet-known one is handled. Checked in addition to, not instead of, min_collocation_area_km2.

Returns:

{"roi_valid_fraction": float} in [0, 1], or {} if the matchup is below min_collocation_area_km2, fails gate, has no satellite product, or no product yields any floating-point measurement data inside the collocation region.