libera_utils.footprint_matching.product.write_fmatch_product#

libera_utils.footprint_matching.product.write_fmatch_product(mode: OperationalMode, inputs: Sequence[PseudoFootprint] | dict[str, np.ndarray], output_path: str | Path, *, algorithm_version: str, input_files: str, 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) → LiberaDataProductFilename#

Assemble and write one FMATCH NetCDF product for an operational mode.

Loads the product definition once (so assembly and writing cannot disagree about it), assembles the product’s arrays as assemble_fmatch_dataset() does, and hands them, with algorithm_version and InputGranules as dynamic attributes, to libera_utils.io.netcdf.write_libera_data_product, which builds the Dataset, enforces and checks its conformance once, and writes it using time_variable=fmatch_time_variable(mode) (RADIOMETER_TIME or CAMERA_TIME), so the standardized Libera filename encodes the footprint time span.

Parameters:

  • mode (OperationalMode) – The FMATCH operational mode to write.

  • inputs (Sequence[PseudoFootprint] or dict[str, np.ndarray]) – The mode’s assembly inputs: camera pseudo-footprints for the camera-timescale modes, or the L1B dict for the radiometer-timescale modes.

  • output_path (str or pathlib.Path) – Directory (or S3 prefix) to write the product file into.

  • algorithm_version (str) – Value for the algorithm_version global attribute.

  • input_files (str) – Provenance string for the InputGranules global attribute.

  • cloud_fraction_camera (np.ndarray, optional) – Per-footprint Camera Cloud Fraction values (Libera WFOV), as in assemble_fmatch_dataset(): required for the CAM modes unless allow_placeholders is True, and 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 used by the aggregation path. 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:

The written product filename object.

Return type:

LiberaDataProductFilename

Raises:

  • ValueError – As assemble_fmatch_dataset() raises (empty or inconsistent inputs, no ancillary inputs without allow_placeholders or both kinds given, a missing, unexpected, wrong-length or out-of-range cloud_fraction_camera, any other declared variable no input produced without allow_placeholders, a footprint with no viewing zenith angle or no usable cone-angle rate under the default weigher, camera pseudo-footprints aggregated without ephemeris, a footprint whose time is NaT when a source selects by time, an assembled column the definition does not declare), or if the assembled Dataset does not conform to the product definition.

  • 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 (see build_radiometer_footprints()).