imap-processing 0.19.0__py3-none-any.whl → 0.19.3__py3-none-any.whl

imap_processing/codice/codice_l2.py

@@ -12,10 +12,12 @@ dataset = process_codice_l2(l1_filename)
 import logging
 from pathlib import Path
 
+import numpy as np
 import xarray as xr
 
 from imap_processing.cdf.imap_cdf_manager import ImapCdfAttributes
 from imap_processing.cdf.utils import load_cdf
+from imap_processing.codice.constants import HALF_SPIN_LUT
 
 logger = logging.getLogger(__name__)
 logger.setLevel(logging.INFO)
@@ -54,6 +56,14 @@ def process_codice_l2(file_path: Path) -> xr.Dataset:
     cdf_attrs = ImapCdfAttributes()
     l2_dataset = add_dataset_attributes(l2_dataset, dataset_name, cdf_attrs)
 
+    # TODO: update list of datasets that need geometric factors (if needed)
+    # Compute geometric factors needed for intensity calculations
+    if dataset_name in [
+        "imap_codice_l2_lo-sw-species",
+        "imap_codice_l2_lo-nsw-species",
+    ]:
+        geometric_factors = compute_geometric_factors(l2_dataset)
+
     if dataset_name in [
         "imap_codice_l2_hi-counters-singles",
         "imap_codice_l2_hi-counters-aggregated",
@@ -63,6 +73,7 @@ def process_codice_l2(file_path: Path) -> xr.Dataset:
         "imap_codice_l2_lo-nsw-priority",
     ]:
         # No changes needed. Just save to an L2 CDF file.
+        # TODO: May not even need L2 files for these products
         pass
 
     elif dataset_name == "imap_codice_l2_hi-direct-events":
@@ -117,6 +128,8 @@ def process_codice_l2(file_path: Path) -> xr.Dataset:
         # Calculate the pickup ion sunward solar wind intensities using equation
         # described in section 11.2.4 of algorithm document.
         # Hopefully this can also apply to lo-ialirt
+        # TODO: WIP - needs to be completed
+        l2_dataset = process_lo_sw_species(l2_dataset, geometric_factors)
         pass
 
     elif dataset_name == "imap_codice_l2_lo-nsw-species":
@@ -132,14 +145,14 @@ def process_codice_l2(file_path: Path) -> xr.Dataset:
 
 
 def add_dataset_attributes(
-    l2_dataset: xr.Dataset, dataset_name: str, cdf_attrs: ImapCdfAttributes
+    dataset: xr.Dataset, dataset_name: str, cdf_attrs: ImapCdfAttributes
 ) -> xr.Dataset:
     """
     Add the global and variable attributes to the dataset.
 
     Parameters
     ----------
-    l2_dataset : xarray.Dataset
+    dataset : xarray.Dataset
         The dataset to update.
     dataset_name : str
         The name of the dataset.
@@ -155,12 +168,12 @@ def add_dataset_attributes(
     cdf_attrs.add_instrument_variable_attrs("codice", "l2")
 
     # Update the global attributes
-    l2_dataset.attrs = cdf_attrs.get_global_attributes(dataset_name)
+    dataset.attrs = cdf_attrs.get_global_attributes(dataset_name)
 
     # Set the variable attributes
-    for variable_name in l2_dataset.data_vars.keys():
+    for variable_name in dataset.data_vars.keys():
         try:
-            l2_dataset[variable_name].attrs = cdf_attrs.get_variable_attributes(
+            dataset[variable_name].attrs = cdf_attrs.get_variable_attributes(
                 variable_name, check_schema=False
             )
         except KeyError:
@@ -169,7 +182,7 @@ def add_dataset_attributes(
             descriptor = dataset_name.split("imap_codice_l2_")[-1]
             cdf_attrs_key = f"{descriptor}-{variable_name}"
             try:
-                l2_dataset[variable_name].attrs = cdf_attrs.get_variable_attributes(
+                dataset[variable_name].attrs = cdf_attrs.get_variable_attributes(
                     f"{cdf_attrs_key}", check_schema=False
                 )
             except KeyError:
@@ -177,4 +190,89 @@ def add_dataset_attributes(
                     f"Field '{variable_name}' and '{cdf_attrs_key}' not found in "
                     f"attribute manager."
                 )
-    return l2_dataset
+    return dataset
+
+
+def compute_geometric_factors(dataset: xr.Dataset) -> np.ndarray:
+    """
+    Calculate geometric factors needed for intensity calculations.
+
+    Geometric factors are determined by comparing the half-spin values per
+    esa_step in the HALF_SPIN_LUT to the rgfo_half_spin values in the provided
+    L2 dataset.
+
+    If the half-spin value is less than the corresponding rgfo_half_spin value,
+    the geometric factor is set to 0.75 (full mode); otherwise, it is set to 0.5
+    (reduced mode).
+
+    NOTE: Half spin values are associated with ESA steps which corresponds to the
+    index of the energy_per_charge dimension that is between 0 and 127.
+
+    Parameters
+    ----------
+    dataset : xarray.Dataset
+        The L2 dataset containing rgfo_half_spin data variable.
+
+    Returns
+    -------
+    geometric_factors : np.ndarray
+        A 2D array of geometric factors with shape (epoch, esa_steps).
+    """
+    # Convert the HALF_SPIN_LUT to a reverse mapping of esa_step to half_spin
+    esa_step_to_half_spin_map = {
+        val: key for key, vals in HALF_SPIN_LUT.items() for val in vals
+    }
+
+    # Create a list of half_spin values corresponding to ESA steps (0 to 127)
+    half_spin_values = np.array(
+        [esa_step_to_half_spin_map[step] for step in range(128)]
+    )
+
+    # Expand dimensions to compare each rgfo_half_spin value against
+    # all half_spin_values
+    rgfo_half_spin = dataset.rgfo_half_spin.data[:, np.newaxis]  # Shape: (epoch, 1)
+
+    # Perform the comparison and calculate geometric factors
+    geometric_factors = np.where(half_spin_values < rgfo_half_spin, 0.75, 0.5)
+
+    return geometric_factors
+
+
+def process_lo_sw_species(
+    dataset: xr.Dataset, geometric_factors: np.ndarray
+) -> xr.Dataset:
+    """
+    Process the lo-sw-species L2 dataset to calculate species intensities.
+
+    Parameters
+    ----------
+    dataset : xarray.Dataset
+        The L2 dataset to process.
+    geometric_factors : np.ndarray
+        The geometric factors array with shape (epoch, esa_steps).
+
+    Returns
+    -------
+    xarray.Dataset
+        The updated L2 dataset with species intensities calculated.
+    """
+    # TODO: WIP - implement intensity calculations
+    # valid_solar_wind_vars = [
+    #     "hplus",
+    #     "heplusplus",
+    #     "cplus4",
+    #     "cplus5",
+    #     "cplus6",
+    #     "oplus5",
+    #     "oplus6",
+    #     "oplus7",
+    #     "oplus8",
+    #     "ne",
+    #     "mg",
+    #     "si",
+    #     "fe_loq",
+    #     "fe_hiq",
+    # ]
+    # valid_pick_up_ion_vars = ["heplus", "cnoplus"]
+
+    return dataset

imap_processing/codice/constants.py

@@ -60,6 +60,7 @@ CODICEAPID_MAPPING = {
 # Numerical constants
 SPIN_PERIOD_CONVERSION = 0.00032
 K_FACTOR = 5.76  # This is used to convert voltages to energies in L2
+HI_ACQUISITION_TIME = 0.59916
 
 # CDF variable names used for lo data products
 LO_COUNTERS_SINGLES_VARIABLE_NAMES = ["apd_singles"]
@@ -172,8 +173,6 @@ CODICE_HI_IAL_DATA_FIELDS = ["h"]
 
 # lo- and hi-counters-aggregated data product variables are dynamically
 # determined based on the number of active counters
-# TODO: Try to convince Joey to move to lower case variable names with
-#       underscores?
 LO_COUNTERS_AGGREGATED_ACTIVE_VARIABLES = {
     "tcr": True,
     "dcr": True,
@@ -438,7 +437,7 @@ DATA_PRODUCT_CONFIGURATIONS: dict[CODICEAPID | int, dict] = {
         "instrument": "hi",
         "num_counters": len(
             HI_COUNTERS_AGGREGATED_VARIABLE_NAMES
-        ),  # The number of counters depends on the number of active counters
+        ),  # The number of counters depends on the number of *active* counters
         "support_variables": ["data_quality", "spin_period"],
         "variable_names": HI_COUNTERS_AGGREGATED_VARIABLE_NAMES,
     },
@@ -527,7 +526,7 @@ DATA_PRODUCT_CONFIGURATIONS: dict[CODICEAPID | int, dict] = {
         "instrument": "lo",
         "num_counters": len(
             LO_COUNTERS_AGGREGATED_VARIABLE_NAMES
-        ),  # The number of counters depends on the number of active counters
+        ),  # The number of counters depends on the number of *active* counters
         "support_variables": [
             "energy_table",
             "acquisition_time_per_step",
@@ -689,9 +688,9 @@ L1B_DATA_PRODUCT_CONFIGURATIONS: dict[str, dict] = {
         "num_spin_sectors": 24,
         "num_spins": 4,
     },
-    "hi-priority": {  # TODO: Ask Joey to define these
-        "num_spin_sectors": 1,
-        "num_spins": 1,
+    "hi-priority": {
+        "num_spin_sectors": 24,
+        "num_spins": 16,
     },
     "hi-sectored": {
         "num_spin_sectors": 2,
@@ -849,7 +848,7 @@ DE_DATA_PRODUCT_CONFIGURATIONS: dict[Any, dict[str, Any]] = {
 }
 
 # Define the packet fields needed to be stored in segmented data and their
-# corresponding bit lengths for direct event data products
+# corresponding bit lengths for I-ALiRT data products
 IAL_BIT_STRUCTURE = {
     "SHCOARSE": 32,
     "PACKET_VERSION": 16,
@@ -1657,6 +1656,8 @@ PIXEL_ORIENTATIONS = {
 # processing. These are taken from the "Acq Time" column in the "Lo Stepping"
 # tab of the "*-SCI-LUT-*.xml" spreadsheet that largely defines CoDICE
 # processing.
+# TODO: Do away with this lookup table and instead calculate the acquisition
+#       times. See GitHub issue #1945.
 ACQUISITION_TIMES = {
     0: [
         578.70833333,
@@ -2179,3 +2180,44 @@ ACQUISITION_TIMES = {
         96.45138889,
     ],
 }
+
+# TODO: Update EFFICIENCY value when better information is available.
+# Constant for CoDICE Intensity calculations.
+EFFICIENCY = 1
+
+# Lookup table for mapping half-spin (keys) to esa steps (values)
+# This is used to determine geometry factors L2
+HALF_SPIN_LUT = {
+    0: [0],
+    1: [1],
+    2: [2],
+    3: [3],
+    4: [4, 5],
+    5: [6, 7],
+    6: [8, 9],
+    7: [10, 11],
+    8: [12, 13, 14],
+    9: [15, 16, 17],
+    10: [18, 19, 20],
+    11: [21, 22, 23],
+    12: [24, 25, 26, 27],
+    13: [28, 29, 30, 31],
+    14: [32, 33, 34, 35],
+    15: [36, 37, 38, 39],
+    16: [40, 41, 42, 43, 44],
+    17: [45, 46, 47, 48, 49],
+    18: [50, 51, 52, 53, 54],
+    19: [55, 56, 57, 58, 59],
+    20: [60, 61, 62, 63, 64],
+    21: [65, 66, 67, 68, 69],
+    22: [70, 71, 72, 73, 74],
+    23: [75, 76, 77, 78, 79],
+    24: [80, 81, 82, 83, 84, 85],
+    25: [86, 87, 88, 89, 90, 91],
+    26: [92, 93, 94, 95, 96, 97],
+    27: [98, 99, 100, 101, 102, 103],
+    28: [104, 105, 106, 107, 108, 109],
+    29: [110, 111, 112, 113, 114, 115],
+    30: [116, 117, 118, 119, 120, 121],
+    31: [122, 123, 124, 125, 126, 127],
+}

imap_processing/codice/data/lo_stepping_values.csv

@@ -1,4 +1,4 @@
-table_num,row_num,num_reps,store_data,e1,e2,e3,e4,e5,e6,e7,e8,acq_time
+table_num,half_spin_num,num_reps,store_data,e1,e2,e3,e4,e5,e6,e7,e8,acq_time
 0,0,1,12,0,-,-,-,-,-,-,-,578.708333
 0,1,1,12,1,-,-,-,-,-,-,-,578.708333
 0,2,1,12,2,-,-,-,-,-,-,-,578.708333

imap_processing/ena_maps/ena_maps.py

@@ -768,6 +768,7 @@ class AbstractSkyMap(ABC):
         pointing_set: PointingSet,
         value_keys: list[str] | None = None,
         index_match_method: IndexMatchMethod = IndexMatchMethod.PUSH,
+        pset_valid_mask: NDArray | None = None,
     ) -> None:
         """
         Project a pointing set's values to the map grid.
@@ -789,6 +790,10 @@ class AbstractSkyMap(ABC):
         index_match_method : IndexMatchMethod, optional
             The method of index matching to use for all values.
             Default is IndexMatchMethod.PUSH.
+        pset_valid_mask : NDArray, optional
+            A boolean mask of shape (number of pointing set pixels,) indicating
+            which pixels in the pointing set should be considered valid for projection.
+            If None, all pixels are considered valid. Default is None.
 
         Raises
         ------
@@ -801,6 +806,9 @@ class AbstractSkyMap(ABC):
             if value_key not in pointing_set.data.data_vars:
                 raise ValueError(f"Value key {value_key} not found in pointing set.")
 
+        if pset_valid_mask is None:
+            pset_valid_mask = np.ones(pointing_set.num_points, dtype=bool)
+
         if index_match_method is IndexMatchMethod.PUSH:
             # Determine the indices of the sky map grid that correspond to
             # each pixel in the pointing set.
@@ -860,22 +868,32 @@ class AbstractSkyMap(ABC):
                     value_array=raveled_pset_data,
                     projection_grid_shape=self.binning_grid_shape,
                     projection_indices=matched_indices_push,
+                    input_valid_mask=pset_valid_mask,
                 )
+                # TODO: we may need to allow for unweighted/weighted means here by
+                # dividing pointing_projected_values by some binned weights.
+                # For unweighted means, we could use the number of pointing set pixels
+                # that correspond to each map pixel as the weights.
+                self.data_1d[value_key] += pointing_projected_values
             elif index_match_method is IndexMatchMethod.PULL:
+                valid_map_mask = pset_valid_mask[matched_indices_pull]
                 # We know that there will only be one value per sky map pixel,
                 # so we can use the matched indices directly
-                pointing_projected_values = raveled_pset_data[..., matched_indices_pull]
+                pointing_projected_values = raveled_pset_data[
+                    ..., matched_indices_pull[valid_map_mask]
+                ]
+                # TODO: we may need to allow for unweighted/weighted means here by
+                # dividing pointing_projected_values by some binned weights.
+                # For unweighted means, we could use the number of pointing set pixels
+                # that correspond to each map pixel as the weights.
+                self.data_1d[value_key].values[..., valid_map_mask] += (
+                    pointing_projected_values
+                )
             else:
                 raise NotImplementedError(
                     "Only PUSH and PULL index matching methods are supported."
                 )
 
-            # TODO: we may need to allow for unweighted/weighted means here by
-            # dividing pointing_projected_values by some binned weights.
-            # For unweighted means, we could use the number of pointing set pixels
-            # that correspond to each map pixel as the weights.
-            self.data_1d[value_key] += pointing_projected_values
-
         # TODO: The max epoch needs to include the pset duration. Right now it
         #     is just capturing the start epoch. See issue #1747
         self.min_epoch = min(self.min_epoch, pointing_set.epoch)
@@ -1169,6 +1187,10 @@ class RectangularSkyMap(AbstractSkyMap):
         # Rewrap each data array in the data_1d to the original 2D grid shape
         rewrapped_data = {}
         for key in self.data_1d.data_vars:
+            # Don't rewrap non-spatial variables
+            if CoordNames.GENERIC_PIXEL.value not in self.data_1d[key].coords:
+                rewrapped_data[key] = self.data_1d[key]
+                continue
             # drop pixel dim from the end, and add the spatial coords as dims
             rewrapped_dims = [
                 dim
@@ -1274,18 +1296,17 @@ class RectangularSkyMap(AbstractSkyMap):
                     name=f"{coord_name}_delta",
                     dims=[coord_name],
                 )
-            # Add energy delta_minus and delta_plus variables
             elif coord_name == CoordNames.ENERGY_L2.value:
-                cdf_ds[f"{coord_name}_delta_minus"] = xr.DataArray(
-                    xr.full_like(cdf_ds[coord_name], np.nan),
-                    name=f"{coord_name}_delta",
-                    dims=[coord_name],
-                )
-                cdf_ds[f"{coord_name}_delta_plus"] = xr.DataArray(
-                    xr.full_like(cdf_ds[coord_name], np.nan),
-                    name=f"{coord_name}_delta",
-                    dims=[coord_name],
-                )
+                if f"{coord_name}_delta_minus" not in cdf_ds:
+                    raise KeyError(
+                        f"Required variable '{coord_name}_delta_minus' "
+                        f"not found in cdf Dataset."
+                    )
+                if f"{coord_name}_delta_plus" not in cdf_ds:
+                    raise KeyError(
+                        f"Required variable '{coord_name}_delta_plus' "
+                        f"not found in cdf Dataset."
+                    )
 
         # Object which holds CDF attributes for the map
         cdf_attrs = ImapCdfAttributes()

imap_processing/ena_maps/utils/corrections.py

@@ -0,0 +1,291 @@
+"""L2 corrections common to multiple IMAP ENA instruments."""
+
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+from numpy.polynomial import Polynomial
+
+
+class PowerLawFluxCorrector:
+    """
+    IMAP-Lo flux correction algorithm implementation.
+
+    Based on Section 5 of the Mapping Algorithm Document. Applies corrections for
+    ESA transmission integration over energy bandpass using iterative
+    predictor-corrector scheme to estimate source fluxes from observed fluxes.
+
+    Parameters
+    ----------
+    coeffs_file : str or Path
+        Location of CSV file containing ESA transmission coefficients.
+    """
+
+    def __init__(self, coeffs_file: str | Path):
+        """Initialize PowerLawFluxCorrector."""
+        # Load the csv file
+        eta_coeffs_df = pd.read_csv(coeffs_file, index_col="esa_step")
+        # Create a lookup dictionary to get the correct np.polynomial.Polynomial
+        # for a given esa_step
+        coeff_columns = ["M0", "M1", "M2", "M3", "M4", "M5"]
+        self.polynomial_lookup = {
+            row.name: Polynomial(row[coeff_columns].values)
+            for _, row in eta_coeffs_df.iterrows()
+        }
+
+    def eta_esa(self, k: np.ndarray, gamma: np.ndarray) -> np.ndarray:
+        """
+        Calculate ESA transmission scale factor η_esa,k(γ) for each energy level.
+
+        Parameters
+        ----------
+        k : np.ndarray
+            Energy levels.
+        gamma : np.ndarray
+            Power-law slopes.
+
+        Returns
+        -------
+        np.ndarray
+            ESA transmission scale factors.
+        """
+        k = np.atleast_1d(k)
+        gamma = np.atleast_1d(gamma)
+        eta = np.empty_like(gamma)
+        for i, esa_step in enumerate(k):
+            eta[i] = self.polynomial_lookup[esa_step](gamma[i])
+            # Negative transmissions get set to 1
+            if eta[i] < 0:
+                eta[i] = 1
+
+        return eta
+
+    @staticmethod
+    def estimate_power_law_slope(
+        fluxes: np.ndarray,
+        energies: np.ndarray,
+        uncertainties: np.ndarray | None = None,
+    ) -> tuple[np.ndarray, np.ndarray | None]:
+        """
+        Estimate power-law slopes γ_k for each energy level using vectorized operations.
+
+        Implements equations (36)-(41) from the Mapping Algorithm Document v7
+        with proper boundary handling. Uses extended arrays with repeated
+        endpoints for unified calculation, and handles zero fluxes by falling
+        back to linear differencing or returning NaN where both central and
+        linear differencing fail.
+
+        Parameters
+        ----------
+        fluxes : np.ndarray
+            Array of differential fluxes [J_1, J_2, ..., J_7].
+        energies : np.ndarray
+            Array of energy levels [E_1, E_2, ..., E_7].
+        uncertainties : np.ndarray, optional
+            Array of flux uncertainties [δJ_1, δJ_2, ..., δJ_7].
+
+        Returns
+        -------
+        gamma : np.ndarray
+            Array of power-law slopes.
+        delta_gamma : np.ndarray or None
+            Array of uncertainty slopes (if uncertainties provided).
+        """
+        n_levels = len(fluxes)
+        gamma = np.full(n_levels, 0, dtype=float)
+        delta_gamma = (
+            np.full(n_levels, 0, dtype=float) if uncertainties is not None else None
+        )
+
+        # Create an array of indices that can be used to create a padded array where
+        # the padding duplicates the first element on the front and the last element
+        # on the end of the array
+        extended_inds = np.pad(np.arange(n_levels), 1, mode="edge")
+
+        # Compute logs, setting non-positive fluxes to NaN
+        log_fluxes = np.log(np.where(fluxes > 0, fluxes, np.nan))
+        log_energies = np.log(energies)
+        # Create extended arrays by repeating first and last values. This allows
+        # for linear differencing to be used on the ends and central differencing
+        # to be used on the interior of the array with a single vectorized equation.
+        # Interior points use central differencing equation:
+        #     gamma_k = ln(J_{k+1}/J_{k-1}) / ln(E_{k+1}/E_{k-1})
+        # Left boundary uses linear forward differencing:
+        #     gamma_k = ln(J_{k+1}/J_{k}) / ln(E_{k+1}/E_{k})
+        # Right boundary uses linear backward differencing:
+        #     gamma_k = ln(J_{k}/J_{k-1}) / ln(E_{k}/E_{k-1})
+        log_extended_fluxes = log_fluxes[extended_inds]
+        log_extended_energies = log_energies[extended_inds]
+
+        # Extract the left and right log values to use in slope calculation
+        left_log_fluxes = log_extended_fluxes[:-2]  # indices 0 to n_levels-1
+        right_log_fluxes = log_extended_fluxes[2:]  # indices 2 to n_levels+1
+        left_log_energies = log_extended_energies[:-2]
+        right_log_energies = log_extended_energies[2:]
+
+        # Compute power-law slopes for valid indices
+        central_valid = np.isfinite(left_log_fluxes) & np.isfinite(right_log_fluxes)
+        gamma[central_valid] = (
+            (right_log_fluxes - left_log_fluxes)
+            / (right_log_energies - left_log_energies)
+        )[central_valid]
+
+        # Compute uncertainty slopes
+        if uncertainties is not None:
+            with np.errstate(divide="ignore"):
+                rel_unc_sq = (uncertainties / fluxes) ** 2
+            extended_rel_unc_sq = rel_unc_sq[extended_inds]
+            delta_gamma = np.sqrt(
+                extended_rel_unc_sq[:-2] + extended_rel_unc_sq[2:]
+            ) / (log_extended_energies[2:] - log_extended_energies[:-2])
+            delta_gamma[~central_valid] = 0
+
+        # Handle one-sided differencing for points where central differencing failed
+        need_fallback = ~central_valid & np.isfinite(log_fluxes)
+        # Exclude first and last points since they already use the correct
+        # one-sided differencing
+        interior_fallback = np.zeros_like(need_fallback, dtype=bool)
+        interior_fallback[1:-1] = need_fallback[1:-1]
+
+        if np.any(interior_fallback):
+            indices = np.where(interior_fallback)[0]
+
+            for k in indices:
+                # For interior points: try forward first, then backward
+                if k < n_levels - 1 and np.isfinite(log_fluxes[k + 1]):
+                    gamma[k] = (log_fluxes[k + 1] - log_fluxes[k]) / (
+                        log_energies[k + 1] - log_energies[k]
+                    )
+
+                    # Compute uncertainty slope using same differencing
+                    if isinstance(delta_gamma, np.ndarray):
+                        delta_gamma[k] = np.sqrt(rel_unc_sq[k + 1] + rel_unc_sq[k]) / (
+                            log_energies[k + 1] - log_energies[k]
+                        )
+
+                elif k > 0 and np.isfinite(log_fluxes[k - 1]):
+                    gamma[k] = (log_fluxes[k] - log_fluxes[k - 1]) / (
+                        log_energies[k] - log_energies[k - 1]
+                    )
+
+                    # Compute uncertainty slope using same differencing
+                    if isinstance(delta_gamma, np.ndarray):
+                        delta_gamma[k] = np.sqrt(rel_unc_sq[k] + rel_unc_sq[k - 1]) / (
+                            log_energies[k] - log_energies[k - 1]
+                        )
+
+        return gamma, delta_gamma
+
+    def predictor_corrector_iteration(
+        self,
+        observed_fluxes: np.ndarray,
+        observed_uncertainties: np.ndarray,
+        energies: np.ndarray,
+        max_iterations: int = 20,
+        convergence_threshold: float = 0.005,
+    ) -> tuple[np.ndarray, np.ndarray, int]:
+        """
+        Estimate source fluxes using iterative predictor-corrector scheme.
+
+        Implements the algorithm from Appendix A of the Mapping Algorithm Document.
+
+        Parameters
+        ----------
+        observed_fluxes : np.ndarray
+            Array of observed fluxes.
+        observed_uncertainties : numpy.ndarray
+            Array of observed uncertainties.
+        energies : np.ndarray
+            Array of energy levels.
+        max_iterations : int, optional
+            Maximum number of iterations, by default 20.
+        convergence_threshold : float, optional
+            RMS convergence criterion, by default 0.005 (0.5%).
+
+        Returns
+        -------
+        source_fluxes : np.ndarray
+            Final estimate of source fluxes.
+        source_uncertainties : np.ndarray
+            Final estimate of source uncertainties.
+        n_iterations : int
+            Number of iterations run.
+        """
+        n_levels = len(observed_fluxes)
+        energy_levels = np.arange(n_levels) + 1
+
+        # Initial power-law estimate from observed fluxes
+        gamma_initial, _ = self.estimate_power_law_slope(observed_fluxes, energies)
+
+        # Initial source flux estimate
+        eta_initial = self.eta_esa(energy_levels, gamma_initial)
+        source_fluxes_n = observed_fluxes / eta_initial
+
+        for _iteration in range(max_iterations):
+            # Store previous iteration
+            source_fluxes_prev = source_fluxes_n.copy()
+
+            # Predictor step
+            gamma_pred, _ = self.estimate_power_law_slope(source_fluxes_n, energies)
+            gamma_half = 0.5 * (gamma_initial + gamma_pred)
+
+            # Predictor source flux estimate
+            eta_half = self.eta_esa(energy_levels, gamma_half)
+            source_fluxes_half = observed_fluxes / eta_half
+
+            # Corrector step
+            gamma_corr, _ = self.estimate_power_law_slope(source_fluxes_half, energies)
+            gamma_n = 0.5 * (gamma_pred + gamma_corr)
+
+            # Final source flux estimate for this iteration
+            eta_final = self.eta_esa(energy_levels, gamma_n)
+            source_fluxes_n = observed_fluxes / eta_final
+            source_uncertainties = observed_uncertainties / eta_final
+
+            # Check convergence
+            ratios_sq = (source_fluxes_n / source_fluxes_prev) ** 2
+            chi_n = np.sqrt(np.mean(ratios_sq)) - 1
+
+            if chi_n < convergence_threshold:
+                break
+
+        return source_fluxes_n, source_uncertainties, _iteration + 1
+
+    def apply_flux_correction(
+        self, flux: np.ndarray, flux_stat_unc: np.ndarray, energies: np.ndarray
+    ) -> tuple[np.ndarray, np.ndarray]:
+        """
+        Apply flux correction to observed fluxes.
+
+        Iterative predictor-corrector scheme is run on each spatial pixel
+        individually to correct fluxes and statistical uncertainties. This method
+        is intended to be used with the unwrapped data in the ena_maps.AbstractSkyMap
+        class or child classes.
+
+        Parameters
+        ----------
+        flux : numpy.ndarray
+            Input flux with shape (n_energy, n_spatial_pixels).
+        flux_stat_unc : np.ndarray
+            Statistical uncertainty for input fluxes. Shape must match the shape
+            of flux.
+        energies : numpy.ndarray
+            Array of energy levels in units of eV or keV.
+
+        Returns
+        -------
+        tuple[numpy.ndarray, numpy.ndarray]
+            Corrected fluxes and flux uncertainties.
+        """
+        corrected_flux = np.empty_like(flux)
+        corrected_flux_stat_unc = np.empty_like(flux_stat_unc)
+
+        # loop over spatial pixels (last dimension)
+        for i_pixel in range(flux.shape[-1]):
+            corrected_flux[:, i_pixel], corrected_flux_stat_unc[:, i_pixel], _ = (
+                self.predictor_corrector_iteration(
+                    flux[:, i_pixel], flux_stat_unc[:, i_pixel], energies
+                )
+            )
+
+        return corrected_flux, corrected_flux_stat_unc