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

imap_processing/ultra/l0/ultra_utils.py

@@ -1,6 +1,6 @@
 """Contains data classes to support Ultra L0 processing."""
 
-from typing import NamedTuple, Union
+from typing import NamedTuple
 
 
 class PacketProperties(NamedTuple):
@@ -9,23 +9,21 @@ class PacketProperties(NamedTuple):
     apid: list  # List of APIDs
     logical_source: list  # List of logical sources
     addition_to_logical_desc: str  # Description of the logical source
-    width: Union[int, None]  # Width of binary data (could be None).
+    width: int | None  # Width of binary data (could be None).
     # Block, image_planes, pixel_window_rows, and pixel_window_columns are important for
     # decompressing the images and a description is available on page 171 of IMAP-Ultra
     # Flight Software Specification document (7523-9009_Rev_-.pdf).
-    block: Union[int, None]  # Number of values in each block (could be None).
-    len_array: Union[
-        int, None
-    ]  # Length of the array to be decompressed (could be None).
-    mantissa_bit_length: Union[int, None]  # used to determine the level of
+    block: int | None  # Number of values in each block (could be None).
+    len_array: int | None  # Length of the array to be decompressed (could be None).
+    mantissa_bit_length: int | None  # used to determine the level of
     # precision that can be recovered from compressed data (could be None).
-    image_planes: Union[int, None] = None
+    image_planes: int | None = None
     # number of images. See table 11 in the FSSD.
-    pixel_window_rows: Union[int, None] = None
+    pixel_window_rows: int | None = None
     # number of rows in each image. See table 49 in the FSSD.
-    pixel_window_columns: Union[int, None] = None
+    pixel_window_columns: int | None = None
     # number of columns in each image. See table 49 in the FSSD.
-    image_planes_per_packet: Union[int, None] = None
+    image_planes_per_packet: int | None = None
     # number of image planes in each packet. See table 52 in the FSSD.
 
 

imap_processing/ultra/l1a/ultra_l1a.py

@@ -1,7 +1,6 @@
 """Generate ULTRA L1a CDFs."""
 
 import logging
-from typing import Optional
 
 import xarray as xr
 
@@ -44,7 +43,7 @@ logger = logging.getLogger(__name__)
 
 
 def ultra_l1a(  # noqa: PLR0912
-    packet_file: str, apid_input: Optional[int] = None
+    packet_file: str, apid_input: int | None = None
 ) -> list[xr.Dataset]:
     """
     Will process ULTRA L0 data into L1A CDF files at output_filepath.

imap_processing/ultra/l1b/cullingmask.py

@@ -3,7 +3,7 @@
 import numpy as np
 import xarray as xr
 
-from imap_processing.ultra.l1b.quality_flag_filters import QUALITY_FLAG_FILTERS
+from imap_processing.ultra.l1b.quality_flag_filters import SPIN_QUALITY_FLAG_FILTERS
 from imap_processing.ultra.utils.ultra_l1_utils import create_dataset, extract_data_dict
 
 FILLVAL_UINT16 = 65535
@@ -32,14 +32,17 @@ def calculate_cullingmask(extendedspin_dataset: xr.Dataset, name: str) -> xr.Dat
     good_mask = (
         (
             extendedspin_dataset["quality_attitude"]
-            & sum(flag.value for flag in QUALITY_FLAG_FILTERS["quality_attitude"])
+            & sum(flag.value for flag in SPIN_QUALITY_FLAG_FILTERS["quality_attitude"])
         )
         == 0
     ) & (
         (
             (
                 extendedspin_dataset["quality_ena_rates"]
-                & sum(flag.value for flag in QUALITY_FLAG_FILTERS["quality_ena_rates"])
+                & sum(
+                    flag.value
+                    for flag in SPIN_QUALITY_FLAG_FILTERS["quality_ena_rates"]
+                )
             )
             == 0
         ).all(dim="energy_bin_geometric_mean")

imap_processing/ultra/l1b/de.py

@@ -4,12 +4,16 @@ import numpy as np
 import xarray as xr
 
 from imap_processing.cdf.utils import parse_filename_like
-from imap_processing.quality_flags import ImapDEUltraFlags
+from imap_processing.quality_flags import (
+    ImapDEOutliersUltraFlags,
+    ImapDEScatteringUltraFlags,
+)
 from imap_processing.spice.geometry import SpiceFrame
 from imap_processing.ultra.l1b.lookup_utils import get_geometric_factor
 from imap_processing.ultra.l1b.ultra_l1b_annotated import (
     get_annotated_particle_velocity,
 )
+from imap_processing.ultra.l1b.ultra_l1b_culling import flag_scattering
 from imap_processing.ultra.l1b.ultra_l1b_extended import (
     StopType,
     determine_ebin_pulse_height,
@@ -32,6 +36,8 @@ from imap_processing.ultra.l1b.ultra_l1b_extended import (
     get_spin_number,
     get_ssd_back_position_and_tof_offset,
     get_ssd_tof,
+    is_back_tof_valid,
+    is_coin_ph_valid,
 )
 from imap_processing.ultra.utils.ultra_l1_utils import create_dataset
 
@@ -88,7 +94,10 @@ def calculate_de(
     ]
 
     de_dict.update(
-        {key: de_dataset[dataset_key] for key, dataset_key in zip(keys, dataset_keys)}
+        {
+            key: de_dataset[dataset_key]
+            for key, dataset_key in zip(keys, dataset_keys, strict=False)
+        }
     )
 
     valid_mask = de_dataset["start_type"].data != FILLVAL_UINT8
@@ -114,6 +123,7 @@ def calculate_de(
     tof = np.full(len(de_dataset["epoch"]), FILLVAL_FLOAT32, dtype=np.float32)
     etof = np.full(len(de_dataset["epoch"]), FILLVAL_FLOAT32, dtype=np.float32)
     ctof = np.full(len(de_dataset["epoch"]), FILLVAL_FLOAT32, dtype=np.float32)
+    tof_energy = np.full(len(de_dataset["epoch"]), FILLVAL_FLOAT32, dtype=np.float32)
     magnitude_v = np.full(len(de_dataset["epoch"]), FILLVAL_FLOAT32, dtype=np.float32)
     energy = np.full(len(de_dataset["epoch"]), FILLVAL_FLOAT32, dtype=np.float32)
     e_bin = np.full(len(de_dataset["epoch"]), FILLVAL_UINT8, dtype=np.uint8)
@@ -125,10 +135,18 @@ def calculate_de(
     sc_dps_velocity = np.full(shape, FILLVAL_FLOAT32, dtype=np.float32)
     helio_velocity = np.full(shape, FILLVAL_FLOAT32, dtype=np.float32)
     spin_starts = np.full(len(de_dataset["epoch"]), FILLVAL_FLOAT32, dtype=np.float64)
+    velocities = np.full(shape, FILLVAL_FLOAT32, dtype=np.float32)
+    v_hat = np.full(shape, FILLVAL_FLOAT32, dtype=np.float32)
+    r_hat = np.full(shape, FILLVAL_FLOAT32, dtype=np.float32)
 
     start_type = np.full(len(de_dataset["epoch"]), FILLVAL_UINT8, dtype=np.uint8)
     quality_flags = np.full(
-        de_dataset["epoch"].shape, ImapDEUltraFlags.NONE.value, dtype=np.uint16
+        de_dataset["epoch"].shape, ImapDEOutliersUltraFlags.NONE.value, dtype=np.uint16
+    )
+    scattering_quality_flags = np.full(
+        de_dataset["epoch"].shape,
+        ImapDEScatteringUltraFlags.NONE.value,
+        dtype=np.uint16,
     )
 
     xf[valid_indices] = get_front_x_position(
@@ -149,9 +167,13 @@ def calculate_de(
     )
 
     # Pulse height
-    tof[ph_indices], t2[ph_indices], xb[ph_indices], yb[ph_indices] = (
-        get_ph_tof_and_back_positions(de_dataset, xf, f"ultra{sensor}", ancillary_files)
+    ph_result = get_ph_tof_and_back_positions(
+        de_dataset, xf, f"ultra{sensor}", ancillary_files
     )
+    tof[ph_indices] = ph_result.tof
+    t2[ph_indices] = ph_result.t2
+    xb[ph_indices] = ph_result.xb
+    yb[ph_indices] = ph_result.yb
     d[ph_indices], yf[ph_indices] = get_front_y_position(
         de_dataset["start_type"].data[ph_indices], yb[ph_indices], ancillary_files
     )
@@ -174,9 +196,6 @@ def calculate_de(
         (xb[ph_indices], yb[ph_indices]),
         d[ph_indices],
     )
-    e_bin[ph_indices] = determine_ebin_pulse_height(
-        energy[ph_indices], tof[ph_indices], r[ph_indices]
-    )
     species_bin[ph_indices] = determine_species(tof[ph_indices], r[ph_indices], "PH")
     etof[ph_indices], xc[ph_indices] = get_coincidence_positions(
         de_dataset.isel(epoch=ph_indices),
@@ -184,6 +203,27 @@ def calculate_de(
         f"ultra{sensor}",
         ancillary_files,
     )
+    backtofvalid = is_back_tof_valid(
+        de_dataset,
+        xf,
+        f"ultra{sensor}",
+        ancillary_files,
+    )
+    coinphvalid = is_coin_ph_valid(
+        etof[ph_indices],
+        xc[ph_indices],
+        xb[ph_indices],
+        f"ultra{sensor}",
+        ancillary_files,
+    )
+    e_bin[ph_indices] = determine_ebin_pulse_height(
+        energy[ph_indices],
+        tof[ph_indices],
+        r[ph_indices],
+        backtofvalid,
+        coinphvalid,
+        ancillary_files,
+    )
     ctof[ph_indices], magnitude_v[ph_indices] = get_ctof(
         tof[ph_indices], r[ph_indices], "PH"
     )
@@ -211,7 +251,11 @@ def calculate_de(
         d[ssd_indices],
     )
     e_bin[ssd_indices] = determine_ebin_ssd(
-        energy[ssd_indices], tof[ssd_indices], r[ssd_indices]
+        energy[ssd_indices],
+        tof[ssd_indices],
+        r[ssd_indices],
+        f"ultra{sensor}",
+        ancillary_files,
     )
     species_bin[ssd_indices] = determine_species(
         tof[ssd_indices], r[ssd_indices], "SSD"
@@ -237,17 +281,22 @@ def calculate_de(
     de_dict["phi"] = phi
     de_dict["theta"] = theta
 
-    v, vhat, r = get_de_velocity(
-        (de_dict["x_front"], de_dict["y_front"]),
-        (de_dict["x_back"], de_dict["y_back"]),
-        de_dict["front_back_distance"],
-        de_dict["tof_start_stop"],
+    velocities[valid_indices], v_hat[valid_indices], r_hat[valid_indices] = (
+        get_de_velocity(
+            (de_dict["x_front"][valid_indices], de_dict["y_front"][valid_indices]),
+            (de_dict["x_back"][valid_indices], de_dict["y_back"][valid_indices]),
+            de_dict["front_back_distance"][valid_indices],
+            de_dict["tof_start_stop"][valid_indices],
+        )
     )
-    de_dict["direct_event_velocity"] = v.astype(np.float32)
-    de_dict["direct_event_unit_velocity"] = vhat.astype(np.float32)
-    de_dict["direct_event_unit_position"] = r.astype(np.float32)
+    de_dict["direct_event_velocity"] = velocities.astype(np.float32)
+    de_dict["direct_event_unit_velocity"] = v_hat.astype(np.float32)
+    de_dict["direct_event_unit_position"] = r_hat.astype(np.float32)
 
-    de_dict["tof_energy"] = get_de_energy_kev(v, species_bin)
+    tof_energy[valid_indices] = get_de_energy_kev(
+        velocities[valid_indices], species_bin[valid_indices]
+    )
+    de_dict["tof_energy"] = tof_energy
     de_dict["energy"] = energy
     de_dict["ebin"] = e_bin
     de_dict["species"] = species_bin
@@ -289,20 +338,29 @@ def calculate_de(
         de_dict["tof_energy"], de_dict["phi"], de_dict["theta"], ancillary_files
     )
     de_dict["geometric_factor_blades"] = get_geometric_factor(
-        ancillary_files,
-        "l1b-sensor-gf-blades",
         de_dict["phi"],
         de_dict["theta"],
         quality_flags,
+        ancillary_files,
+        "l1b-sensor-gf-blades",
     )
     de_dict["geometric_factor_noblades"] = get_geometric_factor(
-        ancillary_files,
-        "l1b-sensor-gf-noblades",
         de_dict["phi"],
         de_dict["theta"],
         quality_flags,
+        ancillary_files,
+        "l1b-sensor-gf-noblades",
+    )
+    de_dict["quality_outliers"] = quality_flags
+    flag_scattering(
+        de_dict["tof_energy"],
+        de_dict["theta"],
+        de_dict["phi"],
+        ancillary_files,
+        sensor,
+        scattering_quality_flags,
     )
-    de_dict["quality_fov"] = quality_flags
+    de_dict["quality_scattering"] = scattering_quality_flags
 
     dataset = create_dataset(de_dict, name, "l1b")
 

imap_processing/ultra/l1b/extendedspin.py

@@ -4,6 +4,7 @@ import numpy as np
 import xarray as xr
 
 from imap_processing.ultra.l1b.ultra_l1b_culling import (
+    count_rejected_events_per_spin,
     flag_attitude,
     flag_hk,
     flag_imap_instruments,
@@ -64,8 +65,15 @@ def calculate_extendedspin(
     first_epochs = filtered_dataset["epoch"].values[first_indices]
 
     # Get the number of pulses per spin.
-    start_per_spin, stop_per_spin, coin_per_spin = get_pulses_per_spin(rates_dataset)
+    pulses = get_pulses_per_spin(rates_dataset)
 
+    # Track rejected events in each spin based on
+    # quality flags in de l1b data.
+    rejected_counts = count_rejected_events_per_spin(
+        de_dataset["spin"].values,
+        de_dataset["quality_scattering"].values,
+        de_dataset["quality_outliers"].values,
+    )
     # These will be the coordinates.
     extendedspin_dict["epoch"] = first_epochs
     extendedspin_dict["spin_number"] = spin
@@ -76,15 +84,10 @@ def calculate_extendedspin(
     extendedspin_dict["spin_start_time"] = spin_starttime
     extendedspin_dict["spin_period"] = spin_period
     extendedspin_dict["spin_rate"] = spin_rates
-    extendedspin_dict["start_pulses_per_spin"] = start_per_spin
-    extendedspin_dict["stop_pulses_per_spin"] = stop_per_spin
-    extendedspin_dict["coin_pulses_per_spin"] = coin_per_spin
-    # TODO: this will be used to track rejected events in each
-    #  spin based on quality flags in de l1b data.
-    extendedspin_dict["rejected_events_per_spin"] = np.full_like(
-        spin, FILLVAL_UINT16, dtype=np.uint16
-    )
-
+    extendedspin_dict["start_pulses_per_spin"] = pulses.start_per_spin
+    extendedspin_dict["stop_pulses_per_spin"] = pulses.stop_per_spin
+    extendedspin_dict["coin_pulses_per_spin"] = pulses.coin_per_spin
+    extendedspin_dict["rejected_events_per_spin"] = rejected_counts
     extendedspin_dict["quality_attitude"] = attitude_qf
     extendedspin_dict["quality_ena_rates"] = rates_qf
     extendedspin_dict["quality_hk"] = hk_qf

imap_processing/ultra/l1b/lookup_utils.py

@@ -6,7 +6,7 @@ import pandas as pd
 import xarray as xr
 from numpy.typing import NDArray
 
-from imap_processing.quality_flags import ImapDEUltraFlags
+from imap_processing.quality_flags import ImapDEOutliersUltraFlags
 
 
 def get_y_adjust(dy_lut: np.ndarray, ancillary_files: dict) -> npt.NDArray:
@@ -232,15 +232,12 @@ def get_energy_efficiencies(ancillary_files: dict) -> pd.DataFrame:
     return lookup_table
 
 
-def get_geometric_factor(
+def load_geometric_factor_tables(
     ancillary_files: dict,
     filename: str,
-    phi: NDArray,
-    theta: NDArray,
-    quality_flag: NDArray,
-) -> tuple[NDArray, NDArray]:
+) -> dict:
     """
-    Lookup table for geometric factor using nearest neighbor.
+    Lookup tables for geometric factor.
 
     Parameters
     ----------
@@ -248,17 +245,11 @@ def get_geometric_factor(
         Ancillary files.
     filename : str
         Name of the file in ancillary_files to use.
-    phi : NDArray
-        Azimuth angles in degrees.
-    theta : NDArray
-        Elevation angles in degrees.
-    quality_flag : NDArray
-        Quality flag to set when geometric factor is zero.
 
     Returns
     -------
-    geometric_factor : NDArray
-        Geometric factor.
+    geometric_factor_tables : dict
+        Geometric factor lookup tables.
     """
     gf_table = pd.read_csv(
         ancillary_files[filename], header=None, skiprows=6, nrows=301
@@ -270,30 +261,207 @@ def get_geometric_factor(
         ancillary_files[filename], header=None, skiprows=610, nrows=301
     ).to_numpy(dtype=float)
 
+    return {
+        "gf_table": gf_table,
+        "theta_table": theta_table,
+        "phi_table": phi_table,
+    }
+
+
+def get_geometric_factor(
+    phi: NDArray,
+    theta: NDArray,
+    quality_flag: NDArray,
+    ancillary_files: dict | None = None,
+    filename: str | None = None,
+    geometric_factor_tables: dict | None = None,
+) -> tuple[NDArray, NDArray]:
+    """
+    Lookup table for geometric factor using nearest neighbor.
+
+    Parameters
+    ----------
+    phi : NDArray
+        Azimuth angles in degrees.
+    theta : NDArray
+        Elevation angles in degrees.
+    quality_flag : NDArray
+        Quality flag to set when geometric factor is zero.
+    ancillary_files : dict[Path], optional
+        Ancillary files.
+    filename : str, optional
+        Name of the file in ancillary_files to use.
+    geometric_factor_tables : dict, optional
+        Preloaded geometric factor lookup tables. If not provided, will load.
+
+    Returns
+    -------
+    geometric_factor : NDArray
+        Geometric factor.
+    """
+    if geometric_factor_tables is None:
+        if ancillary_files is None or filename is None:
+            raise ValueError(
+                "ancillary_files and filename must be provided if "
+                "geometric_factor_tables is not supplied."
+            )
+        geometric_factor_tables = load_geometric_factor_tables(
+            ancillary_files, filename
+        )
     # Assume uniform grids: extract 1D arrays from first row/col
-    theta_vals = theta_table[0, :]  # columns represent theta
-    phi_vals = phi_table[:, 0]  # rows represent phi
+    theta_vals = geometric_factor_tables["theta_table"][0, :]  # columns represent theta
+    phi_vals = geometric_factor_tables["phi_table"][:, 0]  # rows represent phi
 
     # Find nearest index in table for each input value
     phi_idx = np.abs(phi_vals[:, None] - phi).argmin(axis=0)
     theta_idx = np.abs(theta_vals[:, None] - theta).argmin(axis=0)
 
     # Fetch geometric factor values at nearest (phi, theta) pairs
-    geometric_factor = gf_table[phi_idx, theta_idx]
-
-    phi_rad = np.deg2rad(phi)
-    numerator = 5.0 * np.cos(phi_rad)
-    denominator = 1 + 2.80 * np.cos(phi_rad)
-    # Equation 19 in the Ultra Algorithm Document.
-    theta_nom = np.arctan(numerator / denominator)
-    theta_nom = np.rad2deg(theta_nom)
+    geometric_factor = geometric_factor_tables["gf_table"][phi_idx, theta_idx]
 
-    outside_fov = np.abs(theta) > theta_nom
-    quality_flag[outside_fov] |= ImapDEUltraFlags.FOV.value
+    outside_fov = ~is_inside_fov(np.deg2rad(phi), np.deg2rad(theta))
+    quality_flag[outside_fov] |= ImapDEOutliersUltraFlags.FOV.value
 
     return geometric_factor
 
 
+def load_scattering_lookup_tables(ancillary_files: dict, instrument_id: int) -> dict:
+    """
+    Load scattering coefficient lookup tables for the specified instrument.
+
+    Parameters
+    ----------
+    ancillary_files : dict
+        Ancillary files.
+    instrument_id : int
+        Instrument ID, either 45 or 90.
+
+    Returns
+    -------
+    dict
+        Dictionary containing arrays for theta_grid, phi_grid, a_theta, g_theta,
+         a_phi, g_phi.
+    """
+    # TODO remove the line below when the 45 sensor scattering coefficients are
+    #  delivered.
+    instrument_id = 90
+    descriptor = f"l1b-{instrument_id}sensor-scattering-calibration"
+    theta_grid = pd.read_csv(
+        ancillary_files[descriptor], header=None, skiprows=7, nrows=241
+    ).to_numpy(dtype=float)
+    phi_grid = pd.read_csv(
+        ancillary_files[descriptor], header=None, skiprows=249, nrows=241
+    ).to_numpy(dtype=float)
+    a_theta = pd.read_csv(
+        ancillary_files[descriptor], header=None, skiprows=491, nrows=241
+    ).to_numpy(dtype=float)
+    g_theta = pd.read_csv(
+        ancillary_files[descriptor], header=None, skiprows=733, nrows=241
+    ).to_numpy(dtype=float)
+    a_phi = pd.read_csv(
+        ancillary_files[descriptor], header=None, skiprows=975, nrows=241
+    ).to_numpy(dtype=float)
+    g_phi = pd.read_csv(
+        ancillary_files[descriptor], header=None, skiprows=1217, nrows=241
+    ).to_numpy(dtype=float)
+    return {
+        "theta_grid": theta_grid,
+        "phi_grid": phi_grid,
+        "a_theta": a_theta,
+        "g_theta": g_theta,
+        "a_phi": a_phi,
+        "g_phi": g_phi,
+    }
+
+
+def get_scattering_coefficients(
+    theta: NDArray,
+    phi: NDArray,
+    lookup_tables: dict | None = None,
+    ancillary_files: dict | None = None,
+    instrument_id: int | None = None,
+) -> tuple[NDArray, NDArray]:
+    """
+    Get a and g coefficients for theta and phi to compute scattering FWHM.
+
+    Parameters
+    ----------
+    theta : NDArray
+        Elevation angles in degrees.
+    phi : NDArray
+        Azimuth angles in degrees.
+    lookup_tables : dict, optional
+        Preloaded lookup tables. If not provided, will load using ancillary_files and
+         instrument_id.
+    ancillary_files : dict, optional
+        Ancillary files, required if lookup_tables is not provided.
+    instrument_id : int, optional
+        Instrument ID, required if lookup_tables is not provided.
+
+    Returns
+    -------
+    tuple
+        Scattering a and g values corresponding to the given theta and phi values.
+    """
+    if lookup_tables is None:
+        if ancillary_files is None or instrument_id is None:
+            raise ValueError(
+                "ancillary_files and instrument_id must be provided if lookup_tables "
+                "is not supplied."
+            )
+        lookup_tables = load_scattering_lookup_tables(ancillary_files, instrument_id)
+
+    theta_grid = lookup_tables["theta_grid"]
+    phi_grid = lookup_tables["phi_grid"]
+    a_theta = lookup_tables["a_theta"]
+    g_theta = lookup_tables["g_theta"]
+    a_phi = lookup_tables["a_phi"]
+    g_phi = lookup_tables["g_phi"]
+
+    theta_vals = theta_grid[0, :]  # columns represent theta
+    phi_vals = phi_grid[:, 0]  # rows represent phi
+
+    phi_idx = np.abs(phi_vals[:, None] - phi).argmin(axis=0)
+    theta_idx = np.abs(theta_vals[:, None] - theta).argmin(axis=0)
+
+    a_theta_val = a_theta[phi_idx, theta_idx]
+    g_theta_val = g_theta[phi_idx, theta_idx]
+    a_phi_val = a_phi[phi_idx, theta_idx]
+    g_phi_val = g_phi[phi_idx, theta_idx]
+
+    return np.column_stack([a_theta_val, g_theta_val]), np.column_stack(
+        [a_phi_val, g_phi_val]
+    )
+
+
+def is_inside_fov(phi: np.ndarray, theta: np.ndarray) -> np.ndarray:
+    """
+    Determine angles in the field of view (FOV).
+
+    This function is used in the deadtime correction to determine whether a given
+    (theta, phi) angle is within the instrument's Field of View (FOV).
+    Only pixels inside the FOV are considered for time accumulation. The FOV boundary
+    is defined by equation 19 in the Ultra Algorithm Document.
+
+    Parameters
+    ----------
+    phi : np.ndarray
+        Azimuth angles in radians.
+    theta : np.ndarray
+        Elevation angles in radians.
+
+    Returns
+    -------
+    numpy.ndarray
+        Boolean array indicating if the angle is in the FOV, False otherwise.
+    """
+    numerator = 5.0 * np.cos(phi)
+    denominator = 1 + 2.80 * np.cos(phi)
+    # Equation 19 in the Ultra Algorithm Document.
+    theta_nom = np.arctan(numerator / denominator)
+    return np.abs(theta) <= theta_nom
+
+
 def get_ph_corrected(
     sensor: str,
     location: str,
@@ -343,8 +511,93 @@ def get_ph_corrected(
 
     # Flag where clamping occurred
     flagged_mask = (xlut != xlut_clamped) | (ylut != ylut_clamped)
-    quality_flag[flagged_mask] |= ImapDEUltraFlags.PHCORR.value
+    quality_flag[flagged_mask] |= ImapDEOutliersUltraFlags.PHCORR.value
 
     ph_correction = ph_correct_array[xlut_clamped, ylut_clamped]
 
     return ph_correction, quality_flag
+
+
+def get_ebins(
+    lut: str,
+    energy: NDArray,
+    ctof: NDArray,
+    ebins: NDArray,
+    ancillary_files: dict,
+) -> NDArray:
+    """
+    Get energy bins from the lookup table.
+
+    Parameters
+    ----------
+    lut : str
+        Lookup table name, e.g., "l1b-tofxpht".
+    energy : NDArray
+        Energy from the event (keV).
+    ctof : NDArray
+        Corrected TOF (tenths of a ns).
+    ebins : NDArray
+        Energy bins to fill with values.
+    ancillary_files : dict[Path]
+        Ancillary files.
+
+    Returns
+    -------
+    ebins : NDArray
+        Energy bins from the lookup table.
+    """
+    with open(ancillary_files[lut]) as f:
+        all_lines = f.readlines()
+        pixel_text = "".join(all_lines[4:])
+
+    lut_array = np.fromstring(pixel_text, sep=" ", dtype=int).reshape((2048, 4096))
+    # Note that the LUT is indexed [energy, ctof] for l1b-tofxph
+    # and [ctof, energy] for everything else.
+    if lut == "l1b-tofxph":
+        energy_lookup = (2048 - np.floor(energy)).astype(int)
+        ctof_lookup = np.floor(ctof).astype(int)
+        valid = (
+            (energy_lookup >= 0)
+            & (energy_lookup < 2048)
+            & (ctof_lookup >= 0)
+            & (ctof_lookup < 4096)
+        )
+        ebins[valid] = lut_array[energy_lookup[valid], ctof_lookup[valid]]
+    else:
+        energy_lookup = np.floor(energy).astype(int)
+        ctof_lookup = (2048 - np.floor(ctof)).astype(int)
+        valid = (
+            (energy_lookup >= 0)
+            & (energy_lookup < 4096)
+            & (ctof_lookup >= 0)
+            & (ctof_lookup < 2048)
+        )
+        ebins[valid] = lut_array[ctof_lookup[valid], energy_lookup[valid]]
+
+    return ebins
+
+
+def get_scattering_thresholds(ancillary_files: dict) -> dict:
+    """
+    Load scattering culling thresholds as a function of energy from a lookup table.
+
+    Parameters
+    ----------
+    ancillary_files : dict[Path]
+        Ancillary files.
+
+    Returns
+    -------
+    threshold_dict
+         Dictionary containing energy ranges and the corresponding scattering culling
+          threshold.
+    """
+    # Culling FWHM Scattering values as a function of energy.
+    thresholds = pd.read_csv(
+        ancillary_files["l1b-scattering-thresholds-per-energy"], header=None, skiprows=1
+    ).to_numpy(dtype=np.float64)
+    # The first two columns represent the energy range (min, max) in keV, and the
+    # value is the FWHM scattering threshold in degrees
+    threshold_dict = {(row[0], row[1]): row[2] for row in thresholds}
+
+    return threshold_dict