curryer.correction.pipeline =========================== .. py:module:: curryer.correction.pipeline .. autoapi-nested-parse:: Main correction pipeline orchestration. This module contains the public-facing :func:`loop` function that drives the Monte Carlo parameter sensitivity analysis, plus all of the helper functions it calls: - Adapter functions that bridge between the geolocation/image-matching sub-modules and the correction loop. - :func:`_load_file` -- internal helper that reads CSV/NetCDF/HDF5 files into DataFrames, replacing the old mission-specific loader callables. - :func:`_load_image_pair_data`, :func:`_load_calibration_data`, :func:`_geolocate_and_match` -- per-iteration computation helpers. - :func:`loop` -- outer GCP-pair loop, inner parameter-set loop. Architecture note ----------------- The correction pipeline follows the **pipeline → verification** dependency direction. The core image-matching and aggregation logic lives in ``verification.py``; ``pipeline.py`` imports it from there. This means *verification* is a standalone module (GCP pairing + image matching + error stats) that the correction loop reuses for its own last three steps. Attributes ---------- .. autoapisummary:: curryer.correction.pipeline.logger Functions --------- .. autoapisummary:: curryer.correction.pipeline.call_error_stats_module curryer.correction.pipeline.loop curryer.correction.pipeline.run_correction curryer.correction.pipeline.compute_error_stats curryer.correction.pipeline.run_image_matching Module Contents --------------- .. py:data:: logger .. py:function:: call_error_stats_module(image_matching_results, setup: curryer.correction.config.GeolocationSetup) Call the error_stats module with image matching output. :param image_matching_results: Either a single image matching result (xarray.Dataset) or a list of image matching results from multiple GCP pairs :param setup: GeolocationSetup with variable names and thresholds (REQUIRED) :returns: Aggregate error statistics dataset .. py:function:: loop(setup: curryer.correction.config.GeolocationSetup, sweep: curryer.correction.config.Sweep, work_dir: pathlib.Path, tlm_sci_gcp_sets: list[tuple[str, str, str]], output: curryer.correction.config.OutputConfig | None = None, resume_from_checkpoint: bool = False) Correction loop for parameter sensitivity analysis. :param setup: Durable mission setup: SPICE kernels/instrument (``geo``), pass/fail ``requirements``, ``data_config`` (file format + time scaling), optional ``calibration`` files, mission variable names, and an optional ``image_matching_func`` override. :type setup: GeolocationSetup :param sweep: The parameter-variation experiment: ``parameters``, ``search_strategy``, ``n_iterations``, ``seed``, and grid settings. :type sweep: Sweep :param work_dir: Working directory for temporary files. :type work_dir: Path :param tlm_sci_gcp_sets: List of (`telemetry_key`, `science_key`, `gcp_key`) tuples. File paths are expected to be local. S3 URIs (``s3://…``) are also accepted as a convenience when ``boto3`` is installed; see :func:`~curryer.correction.io.resolve_path`. :type tlm_sci_gcp_sets: list of (str, str, str) :param output: Output settings (NetCDF metadata + filename). ``None`` uses defaults derived from ``setup.requirements``. :type output: OutputConfig or None, optional :param resume_from_checkpoint: If True, resume from an existing checkpoint. :type resume_from_checkpoint: bool, optional :returns: * **results** (*list*) -- List of iteration results (order: `pair_idx * N + param_idx`). * **netcdf_data** (*dict*) -- Dictionary of NetCDF variables indexed as `[param_idx, pair_idx]`. .. rubric:: Notes This implementation uses a pair-outer, parameter-inner loop order: - Outer loop: GCP pairs (load data once per image) - Inner loop: Parameter sets (reuse loaded data) This reduces file I/O and centralizes mission-specific behavior through the ``setup`` object. .. rubric:: Examples Correction mode (parameter optimization):: from curryer.correction.config import DataConfig results, netcdf_data = loop(setup, sweep, work_dir, tlm_sci_gcp_sets) Where each element of ``tlm_sci_gcp_sets`` is a tuple of file paths:: tlm_sci_gcp_sets = [ ("telemetry.csv", "science.csv", "landsat_chip_001.mat"), ] .. py:function:: run_correction(setup: curryer.correction.config.GeolocationSetup, sweep: curryer.correction.config.Sweep, inputs: collections.abc.Sequence[curryer.correction.config.CorrectionInput | tuple[str, str, str]], work_dir: pathlib.Path, output: curryer.correction.config.OutputConfig | None = None, resume_from_checkpoint: bool = False) -> curryer.correction.results.CorrectionResult Run the correction parameter sweep. This is the preferred user-facing entry point (compared to :func:`loop`). Returns a structured :class:`~curryer.correction.results.CorrectionResult` with the best parameter set, pass/fail verdict, recommendation, and a human-readable summary table. The raw ``results`` list and ``netcdf_data`` dict from :func:`loop` are available as ``result.results`` and ``result.netcdf_data`` for advanced use. :param setup: Durable mission setup (kernels, requirements, calibration, names). :type setup: GeolocationSetup :param sweep: The parameter-variation experiment to run against *setup*. :type sweep: Sweep :param inputs: Each element is either a :class:`~curryer.correction.config.CorrectionInput` (named fields) or a legacy ``(telemetry_key, science_key, gcp_key)`` tuple. Both forms may be mixed in the same list. File paths are expected to be local. S3 URIs (``s3://…``) are also accepted as a convenience when ``boto3`` is installed; see :func:`~curryer.correction.io.resolve_path`. :type inputs: list of CorrectionInput or list of (str, str, str) :param work_dir: Working directory for temporary files. :type work_dir: Path :param output: Output settings (NetCDF metadata + filename). ``None`` uses defaults derived from ``setup.requirements``. :type output: OutputConfig or None, optional :param resume_from_checkpoint: If True, resume from an existing checkpoint. :type resume_from_checkpoint: bool, optional :returns: Structured result with best parameters, pass/fail verdict, recommendation, summary table, and raw NetCDF/intermediate data available on the returned object (for example, ``result.netcdf_data``). :rtype: CorrectionResult .. py:function:: compute_error_stats(image_matching_results, setup: curryer.correction.config.GeolocationSetup) Compute error statistics from image matching results. This is the preferred name for :func:`call_error_stats_module`. See :func:`call_error_stats_module` for full documentation. :param image_matching_results: Output from image matching, either a single dataset or a list. :type image_matching_results: xr.Dataset or list of xr.Dataset :param setup: Geolocation setup used to initialise the error stats processor. :type setup: GeolocationSetup :returns: Aggregate error statistics dataset. :rtype: xr.Dataset .. py:function:: run_image_matching(geolocated_data: xarray.Dataset, gcp_reference_file: pathlib.Path, telemetry: pandas.DataFrame, params_info: list, setup: curryer.correction.config.GeolocationSetup, los_vectors_cached: numpy.ndarray | None = None, optical_psfs_cached: list | None = None) -> xarray.Dataset Run image matching against GCP reference. This is the preferred name for :func:`image_matching`. See :func:`image_matching` for full documentation. :param geolocated_data: Geolocated scene data with latitude/longitude. :type geolocated_data: xr.Dataset :param gcp_reference_file: Path to the GCP reference image (.mat file). :type gcp_reference_file: Path :param telemetry: Telemetry DataFrame with spacecraft state. :type telemetry: pd.DataFrame :param params_info: Parameter information for the current iteration. :type params_info: list :param setup: Geolocation setup (calibration paths, variable names, instrument name). :type setup: GeolocationSetup :param los_vectors_cached: Pre-loaded LOS vectors; loaded from disk if None. :type los_vectors_cached: np.ndarray or None, optional :param optical_psfs_cached: Pre-loaded optical PSFs; loaded from disk if None. :type optical_psfs_cached: list or None, optional :returns: Image matching results dataset. :rtype: xr.Dataset