libera_utils.footprint_matching.product.assemble_fmatch_dataset#

libera_utils.footprint_matching.product.assemble_fmatch_dataset(mode: OperationalMode, inputs: Sequence[PseudoFootprint] | dict[str, np.ndarray], *, definition: LiberaDataProductDefinition | None = None, algorithm_version: str | None = None, input_files: str | None = None, cloud_fraction_camera: np.ndarray | None = None, source_file_paths: dict[str, Sequence[Path]] | None = None, sources: dict[str, AncillaryReader] | None = None, weigher: PixelWeigher | None = None, allow_placeholders: bool = False) → Dataset#

Assemble a conformant FMATCH xarray.Dataset for an operational mode.

Combines the per-footprint geolocation inputs, the derived viewing geometry from compute_derived_viewing_geometry(), and the aggregated external variables from aggregate_external_variables() into the variable dict expected by the mode’s product definition (from load_fmatch_definition()), then builds the Dataset once via LiberaDataProductDefinition.create_product_dataset, with algorithm_version and InputGranules as its dynamic attributes, and brings it into conformance with enforce_dataset_conformance.

Dispatch is by timescale, because that determines what the mode is built from:

  • Camera-timescale (CAM_CAMTIME, IMAGER_CAMTIME) - assembled from the camera pseudo-footprints segmented by the Camera Cloud Fraction algorithm and read from its CF-CAM-CAMTIME product. inputs is that sequence of PseudoFootprint objects. See _assemble_camtime_dataset.

  • Radiometer-timescale (CAM, IMAGER) - assembled from the L1B pass-through arrays the FMATCH runner reads from L1B Daily. inputs is that dict. See _assemble_radiometer_dataset.

In both cases the derived viewing geometry (Sunglint_Angle) is always computed from the real geolocation angles. The external aggregated variables and the coverage/QA columns are computed from the ancillary inputs (sources or source_file_paths, forwarded to aggregate_external_variables()). A declared variable no input produced raises, unless allow_placeholders=True asks for it to be written as a conformant placeholder. Columns are named as the product definition declares them.

Parameters:

  • mode (OperationalMode) – The FMATCH operational mode being assembled.

  • inputs (Sequence[PseudoFootprint] or dict[str, np.ndarray]) – Camera pseudo-footprints for the camera-timescale modes, or the L1B dict (keyed by L1B names) for the radiometer-timescale modes.

  • definition (LiberaDataProductDefinition, optional) – The product definition. Loaded via load_fmatch_definition() when omitted.

  • algorithm_version (str, optional) – Value for the dynamic algorithm_version global attribute. Writing the product requires it; assembly alone does not.

  • input_files (str, optional) – Provenance string for the dynamic InputGranules global attribute. Writing the product requires it; assembly alone does not.

  • cloud_fraction_camera (np.ndarray, optional) – Per-footprint cloud fraction from the Camera Cloud Fraction (CF-CAM) algorithm (Libera WFOV camera), in percent [0, 100] with NaN for a missing value, as a 1-D array indexed by footprint in the same order as the time coordinate. This is an internal algorithm output - it does not come from a reader and is already aggregated to one value per footprint - so it is merged directly into the Cloud_Fraction_Camera variable rather than going through aggregate_external_variables(). Only the CAM modes (CAM, CAM_CAMTIME) declare this variable: it is required for them unless allow_placeholders is True, and must be None for the IMAGER modes.

  • source_file_paths (dict[str, Sequence[Path]], optional) – Reader-key -> staged ancillary granule(s) map the sources are built from. Pass this or sources, not both.

  • sources (dict[str, AncillaryReader], optional) – Pre-built readers to aggregate from, keyed by reader registry key: exactly the readers active in mode. Pass this or source_file_paths, not both.

  • weigher (PixelWeigher, optional) – PSF weigher for the aggregation. Defaults to AngularPSFWeigher (see aggregate_external_variables()).

  • allow_placeholders (bool, optional) – When True, a declared variable no input produced is written as fill instead of raising: the external, PSF_Coverage_Fraction and Quality_Flag columns when neither sources nor source_file_paths is given, a reader’s columns when its source is missing, and Cloud_Fraction_Camera when cloud_fraction_camera is omitted for a CAM mode. Defaults to False.

Returns:

A dataset brought into conformance with the mode’s product definition.

Return type:

xarray.Dataset

Raises:

  • ValueError – If inputs is empty; if the radiometer-timescale inputs dict is missing a required L1B key or its arrays have inconsistent lengths; if neither sources nor source_file_paths is given and allow_placeholders is False, or both are given; if cloud_fraction_camera is omitted for a CAM mode without allow_placeholders, given for an IMAGER mode, not one value per footprint, or has a finite value outside [0, 100]; if any other declared variable no input produced is left without allow_placeholders; if a footprint has no finite viewing zenith angle, or no usable cone-angle rate under the default weigher; if a camera-timescale mode is aggregated, since camera pseudo-footprints carry no L1B ephemeris; if a footprint’s time is NaT and a source selects by time; or if assembly produces a column the definition does not declare.

  • KeyError – If the keys of sources or source_file_paths are not exactly the readers active in mode.

  • MissingGeolocationError – If a radiometer record’s ephemeris is unusable or its footprint is not visible from the satellite (see build_radiometer_footprints()).