curryer.correction.pipeline

Main correction pipeline orchestration.

This module contains the public-facing 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.

  • _load_file() – internal helper that reads CSV/NetCDF/HDF5 files into DataFrames, replacing the old mission-specific loader callables.

  • _load_image_pair_data(), _load_calibration_data(), _geolocate_and_match() – per-iteration computation helpers.

  • 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

logger

Functions

call_error_stats_module(image_matching_results, setup)

Call the error_stats module with image matching output.

loop(setup, sweep, work_dir, tlm_sci_gcp_sets[, ...])

Correction loop for parameter sensitivity analysis.

run_correction(...)

Run the correction parameter sweep.

compute_error_stats(image_matching_results, setup)

Compute error statistics from image matching results.

run_image_matching(→ xarray.Dataset)

Run image matching against GCP reference.

Module Contents

curryer.correction.pipeline.logger
curryer.correction.pipeline.call_error_stats_module(image_matching_results, setup: curryer.correction.config.GeolocationSetup)

Call the error_stats module with image matching output.

Parameters:

  • image_matching_results – Either a single image matching result (xarray.Dataset) or a list of image matching results from multiple GCP pairs

  • setup – GeolocationSetup with variable names and thresholds (REQUIRED)

Returns:

Aggregate error statistics dataset

curryer.correction.pipeline.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.

Parameters:

  • setup (GeolocationSetup) – 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.

  • sweep (Sweep) – The parameter-variation experiment: parameters, search_strategy, n_iterations, seed, and grid settings.

  • work_dir (Path) – Working directory for temporary files.

  • tlm_sci_gcp_sets (list of (str, str, str)) – 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 resolve_path().

  • output (OutputConfig or None, optional) – Output settings (NetCDF metadata + filename). None uses defaults derived from setup.requirements.

  • resume_from_checkpoint (bool, optional) – If True, resume from an existing checkpoint.

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].

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.

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"),
]
curryer.correction.pipeline.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 loop()). Returns a structured 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 loop() are available as result.results and result.netcdf_data for advanced use.

Parameters:

  • setup (GeolocationSetup) – Durable mission setup (kernels, requirements, calibration, names).

  • sweep (Sweep) – The parameter-variation experiment to run against setup.

  • inputs (list of CorrectionInput or list of (str, str, str)) – Each element is either a 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 resolve_path().

  • work_dir (Path) – Working directory for temporary files.

  • output (OutputConfig or None, optional) – Output settings (NetCDF metadata + filename). None uses defaults derived from setup.requirements.

  • resume_from_checkpoint (bool, optional) – If True, resume from an existing checkpoint.

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).

Return type:

CorrectionResult

curryer.correction.pipeline.compute_error_stats(image_matching_results, setup: curryer.correction.config.GeolocationSetup)

Compute error statistics from image matching results.

This is the preferred name for call_error_stats_module(). See call_error_stats_module() for full documentation.

Parameters:

  • image_matching_results (xr.Dataset or list of xr.Dataset) – Output from image matching, either a single dataset or a list.

  • setup (GeolocationSetup) – Geolocation setup used to initialise the error stats processor.

Returns:

Aggregate error statistics dataset.

Return type:

xr.Dataset

curryer.correction.pipeline.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 image_matching(). See image_matching() for full documentation.

Parameters:

  • geolocated_data (xr.Dataset) – Geolocated scene data with latitude/longitude.

  • gcp_reference_file (Path) – Path to the GCP reference image (.mat file).

  • telemetry (pd.DataFrame) – Telemetry DataFrame with spacecraft state.

  • params_info (list) – Parameter information for the current iteration.

  • setup (GeolocationSetup) – Geolocation setup (calibration paths, variable names, instrument name).

  • los_vectors_cached (np.ndarray or None, optional) – Pre-loaded LOS vectors; loaded from disk if None.

  • optical_psfs_cached (list or None, optional) – Pre-loaded optical PSFs; loaded from disk if None.

Returns:

Image matching results dataset.

Return type:

xr.Dataset