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

imap_processing/ialirt/l0/process_swapi.py

@@ -2,7 +2,6 @@
 
 import logging
 from decimal import Decimal
-from typing import Optional
 
 import numpy as np
 import pandas as pd
@@ -10,13 +9,12 @@ import xarray as xr
 from scipy.optimize import curve_fit
 from scipy.special import erf
 
-from imap_processing import imap_module_directory
 from imap_processing.ialirt.constants import IalirtSwapiConstants as Consts
 from imap_processing.ialirt.utils.grouping import find_groups
 from imap_processing.ialirt.utils.time import calculate_time
 from imap_processing.spice.time import met_to_ttj2000ns, met_to_utc
 from imap_processing.swapi.l1.swapi_l1 import process_sweep_data
-from imap_processing.swapi.l2.swapi_l2 import TIME_PER_BIN
+from imap_processing.swapi.l2.swapi_l2 import SWAPI_LIVETIME
 
 logger = logging.getLogger(__name__)
 
@@ -70,7 +68,7 @@ def count_rate(
 def optimize_pseudo_parameters(
     count_rates: np.ndarray,
     count_rate_error: np.ndarray,
-    energy_passbands: Optional[np.ndarray] = None,
+    energy_passbands: np.ndarray,
 ) -> (dict)[str, list[float]]:
     """
     Find the pseudo speed (u), density (n) and temperature (T) of solar wind particles.
@@ -84,7 +82,7 @@ def optimize_pseudo_parameters(
     count_rate_error : np.ndarray
         Standard deviation of the coincidence count rates parameter.
     energy_passbands : np.ndarray, default None
-        Energy passbands, passed in only for testing purposes.
+        Energy values, taken from the SWAPI lookup table.
 
     Returns
     -------
@@ -92,21 +90,6 @@ def optimize_pseudo_parameters(
         Dictionary containing the optimized speed, density, and temperature values for
         each sweep included in the input count_rates array.
     """
-    if not energy_passbands:
-        # Read in energy passbands
-        energy_data = pd.read_csv(
-            f"{imap_module_directory}/tests/swapi/lut/imap_swapi_esa-unit"
-            f"-conversion_20250211_v000.csv"
-        )
-        energy_passbands = (
-            energy_data["Energy"][0:63]
-            .replace(",", "", regex=True)
-            .to_numpy()
-            .astype(float)
-        )
-
-    # Initial guess pulled from page 52 of the IMAP SWAPI Instrument Algorithms Document
-    initial_param_guess = np.array([550, 5.27, 1e5])
     solution_dict = {  # type: ignore
         "pseudo_speed": [],
         "pseudo_density": [],
@@ -116,8 +99,16 @@ def optimize_pseudo_parameters(
     for sweep in np.arange(count_rates.shape[0]):
         current_sweep_count_rates = count_rates[sweep, :]
         current_sweep_count_rate_errors = count_rate_error[sweep, :]
-        # Find the max count rate, and use the 6 points surrounding it (inclusive)
+        # Find the max count rate, and use the 5 points surrounding it
         max_index = np.argmax(current_sweep_count_rates)
+        initial_speed_guess = np.sqrt(energy_passbands[max_index]) * Consts.speed_coeff
+        initial_param_guess = np.array(
+            [
+                initial_speed_guess,
+                5 * (400 / initial_speed_guess) ** 2,
+                60000 * (initial_speed_guess / 400) ** 2,
+            ]
+        )
         sol = curve_fit(
             f=count_rate,
             xdata=energy_passbands.take(
@@ -138,7 +129,9 @@ def optimize_pseudo_parameters(
     return solution_dict
 
 
-def process_swapi_ialirt(unpacked_data: xr.Dataset) -> list[dict]:
+def process_swapi_ialirt(
+    unpacked_data: xr.Dataset, calibration_lut_table: pd.DataFrame
+) -> list[dict]:
     """
     Extract I-ALiRT variables and calculate coincidence count rate.
 
@@ -146,6 +139,8 @@ def process_swapi_ialirt(unpacked_data: xr.Dataset) -> list[dict]:
     ----------
     unpacked_data : xr.Dataset
         SWAPI I-ALiRT data that has been parsed from the spacecraft packet.
+    calibration_lut_table : pd.DataFrame
+        DataFrame containing the contents of the SWAPI esa-unit-conversion lookup table.
 
     Returns
     -------
@@ -191,10 +186,31 @@ def process_swapi_ialirt(unpacked_data: xr.Dataset) -> list[dict]:
             continue
 
     raw_coin_count = process_sweep_data(grouped_dataset, "swapi_coin_cnt")
-    raw_coin_rate = raw_coin_count / TIME_PER_BIN
-    count_rate_error = np.sqrt(raw_coin_count) / TIME_PER_BIN
+    raw_coin_rate = raw_coin_count / SWAPI_LIVETIME
+    count_rate_error = np.sqrt(raw_coin_count) / SWAPI_LIVETIME
 
-    solution = optimize_pseudo_parameters(raw_coin_rate, count_rate_error)
+    # Extract energy values from the calibration lookup table file
+    calibration_lut_table["timestamp"] = pd.to_datetime(
+        calibration_lut_table["timestamp"], format="%m/%d/%Y %H:%M"
+    )
+    calibration_lut_table["timestamp"] = calibration_lut_table["timestamp"].to_numpy(
+        dtype="datetime64[ns]"
+    )
+
+    # Find the sweep's energy data for the latest time, where sweep_id == 2
+    subset = calibration_lut_table[
+        (calibration_lut_table["timestamp"] == calibration_lut_table["timestamp"].max())
+        & (calibration_lut_table["Sweep #"] == 2)
+    ]
+    if subset.empty:
+        energy_passbands = np.full(63, np.nan, dtype=np.float64)
+    else:
+        subset = subset.sort_values(["timestamp", "ESA Step #"])
+        energy_passbands = subset["Energy"][0:63].to_numpy().astype(float)
+
+    solution = optimize_pseudo_parameters(
+        raw_coin_rate, count_rate_error, energy_passbands
+    )
 
     swapi_data = []
 

imap_processing/ialirt/l0/process_swe.py

@@ -542,16 +542,32 @@ def process_swe(accumulated_data: xr.Dataset, in_flight_cal_files: list) -> list
         summed_first = normalized_first_half.sum(axis=(1, 2))
         summed_second = normalized_second_half.sum(axis=(1, 2))
 
+        met_first_half = int(
+            grouped["met"].where(grouped["swe_seq"] == 0, drop=True).values[0]
+        )
+        met_second_half = int(
+            grouped["met"].where(grouped["swe_seq"] == 30, drop=True).values[0]
+        )
+
+        swe_data.append(
+            {
+                "apid": 478,
+                "met": met_first_half,
+                "met_in_utc": met_to_utc(met_first_half).split(".")[0],
+                "ttj2000ns": int(met_to_ttj2000ns(met_first_half)),
+                "swe_normalized_counts": [int(val) for val in summed_first],
+                "swe_counterstreaming_electrons": bde_first_half,
+            },
+        )
         swe_data.append(
             {
                 "apid": 478,
-                "met": int(grouped["met"].min()),
-                "met_in_utc": met_to_utc(grouped["met"].min()).split(".")[0],
-                "ttj2000ns": int(met_to_ttj2000ns(grouped["met"].min())),
-                "swe_normalized_counts_half_1_esa": [int(val) for val in summed_first],
-                "swe_normalized_counts_half_2_esa": [int(val) for val in summed_second],
-                "swe_counterstreaming_electrons": max(bde_first_half, bde_second_half),
-            }
+                "met": met_second_half,
+                "met_in_utc": met_to_utc(met_second_half).split(".")[0],
+                "ttj2000ns": int(met_to_ttj2000ns(met_second_half)),
+                "swe_normalized_counts": [int(val) for val in summed_second],
+                "swe_counterstreaming_electrons": bde_second_half,
+            },
         )
 
     return swe_data

imap_processing/ialirt/process_ephemeris.py

@@ -8,22 +8,20 @@ Reference: https://spiceypy.readthedocs.io/en/main/documentation.html.
 
 import logging
 import typing
-from typing import Union
+from datetime import datetime, timedelta
 
 import numpy as np
 import spiceypy
 from numpy import ndarray
 
+from imap_processing.ialirt.constants import STATIONS
 from imap_processing.spice.geometry import SpiceBody, SpiceFrame, imap_state
-from imap_processing.spice.kernels import ensure_spice
 from imap_processing.spice.time import et_to_utc, str_to_et
 
 # Logger setup
 logger = logging.getLogger(__name__)
 
 
-@typing.no_type_check
-@ensure_spice
 def latitude_longitude_to_ecef(
     longitude: float, latitude: float, altitude: float
 ) -> ndarray:
@@ -68,12 +66,11 @@ def latitude_longitude_to_ecef(
 
 
 @typing.no_type_check
-@ensure_spice
 def calculate_azimuth_and_elevation(
     longitude: float,
     latitude: float,
     altitude: float,
-    observation_time: Union[float, np.ndarray],
+    observation_time: float | np.ndarray,
     target: str = SpiceBody.IMAP.name,
 ) -> tuple:
     """
@@ -137,8 +134,8 @@ def calculate_doppler(
     longitude: float,
     latitude: float,
     altitude: float,
-    observation_time: Union[float, np.ndarray],
-) -> Union[float, ndarray[float]]:
+    observation_time: float | np.ndarray,
+) -> float | ndarray[float]:
     """
     Calculate the doppler velocity.
 
@@ -194,7 +191,7 @@ def build_output(
     latitude: float,
     altitude: float,
     time_endpoints: tuple[str, str],
-    time_step: float,
+    time_step: float = 60,
 ) -> dict[str, np.ndarray]:
     """
     Build the output dictionary containing time, azimuth, elevation, and doppler.
@@ -210,7 +207,7 @@ def build_output(
     time_endpoints : tuple[str, str]
         Start and stop times in UTC.
     time_step : float
-        Seconds between data points.
+        Seconds between data points. Default is 60.
 
     Returns
     -------
@@ -230,10 +227,10 @@ def build_output(
     )
 
     output_dict["time"] = et_to_utc(time_range, format_str="ISOC")
-    output_dict["azimuth"] = azimuth
-    output_dict["elevation"] = elevation
-    output_dict["doppler"] = calculate_doppler(
-        longitude, latitude, altitude, time_range
+    output_dict["azimuth"] = np.round(azimuth, 6)
+    output_dict["elevation"] = np.round(elevation, 6)
+    output_dict["doppler"] = np.round(
+        calculate_doppler(longitude, latitude, altitude, time_range), 6
     )
 
     logger.info(
@@ -242,3 +239,62 @@ def build_output(
     )
 
     return output_dict
+
+
+def generate_text_files(station: str, day: str) -> list[str]:
+    """
+    Generate a pointing schedule text file and return it as a list of strings.
+
+    Parameters
+    ----------
+    station : str
+        Station name.
+    day : str
+        The day for which to generate a pointing schedule, in ISO format.
+        Ex: "2025-08-11".
+
+    Returns
+    -------
+    lines : list[str]
+        A list of strings that makeup the lines of a pointing schedule file.
+    """
+    station_properties = STATIONS[station]
+
+    day_as_datetime = datetime.fromisoformat(day)
+    time_endpoints = (
+        datetime.strftime(day_as_datetime, "%Y-%m-%d %H:%M:%S"),
+        datetime.strftime(day_as_datetime + timedelta(days=1), "%Y-%m-%d %H:%M:%S"),
+    )
+    output_dict = build_output(
+        station_properties[0],
+        station_properties[1],
+        station_properties[2],
+        time_endpoints,
+    )
+
+    lines = [
+        f"Station: {station}\n",
+        "Target: IMAP\n",
+        f"Creation date (UTC): {datetime.utcnow()}\n",
+        f"Start time: {time_endpoints[0]}\n",
+        f"End time: {time_endpoints[1]}\n",
+        "Cadence (sec): 60\n\n",
+        "Date/Time"
+        + "Azimuth".rjust(29)
+        + "Elevation".rjust(17)
+        + "Doppler".rjust(15)
+        + "\n",
+        "(UTC)" + "(deg.)".rjust(33) + "(deg.)".rjust(16) + "(km/s)".rjust(16) + "\n",
+    ]
+
+    length = len(output_dict["time"])
+    for i in range(length):
+        lines.append(
+            f"{output_dict['time'][i]}"
+            + f"{output_dict['azimuth'][i]}".rjust(16)
+            + f"{output_dict['elevation'][i]}".rjust(16)
+            + f"{output_dict['doppler'][i]}".rjust(15)
+            + "\n"
+        )
+
+    return lines

imap_processing/ialirt/utils/constants.py

@@ -2,19 +2,19 @@
 
 IALIRT_KEYS = [
     # H intensities in 15 energy ranges and binned into 4 azimuths and 4 spin angle bins
-    "codicehi_h",
+    "codice_hi_h",
     # C/O abundance ratio
-    "codicelo_c_over_o_abundance",
+    "codice_lo_c_over_o_abundance",
     # Mg/O abundance ratio
-    "codicelo_mg_over_o_abundance",
+    "codice_lo_mg_over_o_abundance",
     # Fe/O abundance ratio
-    "codicelo_fe_over_o_abundance",
+    "codice_lo_fe_over_o_abundance",
     # C+6/C+5 charge state ratio
-    "codicelo_c_plus_6_over_c_plus_5_ratio",
+    "codice_lo_c_plus_6_over_c_plus_5_ratio",
     # O+7/O+6 charge state ratio
-    "codicelo_o_plus_7_over_o_plus_6_ratio",
+    "codice_lo_o_plus_7_over_o_plus_6_ratio",
     # Fe low/Fe high charge state ratio
-    "codicelo_fe_low_over_fe_high_ratio",
+    "codice_lo_fe_low_over_fe_high_ratio",
     # Low energy (~300 keV) electrons (A-side)
     "hit_e_a_side_low_en",
     # Medium energy (~3 MeV) electrons (A-side)
@@ -37,26 +37,32 @@ IALIRT_KEYS = [
     "hit_he_omni_low_en",
     # High energy (15 to 70 MeV/nuc) He (Omnidirectional)
     "hit_he_omni_high_en",
+    # MAG instrument epoch
+    "mag_epoch",
     # Magnetic field vector in GSE coordinates
-    "mag_4s_b_gse",
+    "mag_B_GSE",
     # Magnetic field vector in GSM coordinates
-    "mag_4s_b_gsm",
+    "mag_B_GSM",
     # Magnetic field vector in RTN coordinates
-    "mag_4s_b_rtn",
+    "mag_B_RTN",
+    # Magnitude of the magnetic field vector
+    "mag_B_magnitude",
     # Azimuth angle (φ) of the magnetic field in GSM coordinates
-    "mag_phi_4s_b_gsm",
+    "mag_phi_B_GSM",
     # Elevation angle (θ) of the magnetic field in GSM coordinates
-    "mag_theta_4s_b_gsm",
+    "mag_theta_B_GSM",
+    # Azimuth angle (φ) of the magnetic field in GSE coordinates
+    "mag_phi_B_GSE",
+    # Elevation angle (θ) of the magnetic field in GSE coordinates
+    "mag_theta_B_GSE",
     # Pseudo density of solar wind protons
     "swapi_pseudo_proton_density",
     # Pseudo speed of solar wind protons in solar inertial frame
     "swapi_pseudo_proton_speed",
     # Pseudo temperature of solar wind protons in plasma frame
     "swapi_pseudo_proton_temperature",
-    # SWE Normalized Counts - Half Cycle 1
-    "swe_normalized_counts_half_1",
-    # SWE Normalized Counts - Half Cycle 2
-    "swe_normalized_counts_half_2",
+    # SWE Normalized Counts
+    "swe_normalized_counts",
     # SWE Counterstreaming flag
     "swe_counterstreaming_electrons",
 ]

imap_processing/ialirt/utils/create_xarray.py

@@ -48,6 +48,13 @@ def create_xarray_from_records(records: list[dict]) -> xr.Dataset:  # noqa: PLR0
         attrs=cdf_manager.get_variable_attributes("component", check_schema=False),
     )
 
+    rtn_component = xr.DataArray(
+        ["radial", "tangential", "normal"],
+        name="RTN_component",
+        dims=["RTN_component"],
+        attrs=cdf_manager.get_variable_attributes("RTN_componentt", check_schema=False),
+    )
+
     esa_step = xr.DataArray(
         data=np.arange(8, dtype=np.uint8),
         name="esa_step",
@@ -57,32 +64,39 @@ def create_xarray_from_records(records: list[dict]) -> xr.Dataset:  # noqa: PLR0
 
     energy_ranges = xr.DataArray(
         data=np.arange(15, dtype=np.uint8),
-        name="energy_ranges",
-        dims=["energy_ranges"],
-        attrs=cdf_manager.get_variable_attributes("energy_ranges", check_schema=False),
+        name="codice_hi_h_energy_ranges",
+        dims=["codice_hi_h_energy_ranges"],
+        attrs=cdf_manager.get_variable_attributes(
+            "codice_hi_h_energy_ranges", check_schema=False
+        ),
     )
 
-    azimuth = xr.DataArray(
+    elevation = xr.DataArray(
         data=np.arange(4, dtype=np.uint8),
-        name="azimuth",
-        dims=["azimuth"],
-        attrs=cdf_manager.get_variable_attributes("azimuth", check_schema=False),
+        name="codice_hi_h_elevation",
+        dims=["codice_hi_h_elevation"],
+        attrs=cdf_manager.get_variable_attributes(
+            "codice_hi_h_elevation", check_schema=False
+        ),
     )
 
-    spin_angle_bin = xr.DataArray(
+    spin_angle = xr.DataArray(
         data=np.arange(4, dtype=np.uint8),
-        name="spin_angle_bin",
-        dims=["spin_angle_bin"],
-        attrs=cdf_manager.get_variable_attributes("spin_angle_bin", check_schema=False),
+        name="codice_hi_h_spin_angle",
+        dims=["codice_hi_h_spin_angle"],
+        attrs=cdf_manager.get_variable_attributes(
+            "codice_hi_h_spin_anglen", check_schema=False
+        ),
     )
 
     coords = {
         "epoch": epoch,
         "component": component,
+        "RTN_component": rtn_component,
         "esa_step": esa_step,
-        "energy_ranges": energy_ranges,
-        "azimuth": azimuth,
-        "spin_angle_bin": spin_angle_bin,
+        "codice_hi_h_energy_ranges": energy_ranges,
+        "codice_hi_h_elevation": elevation,
+        "codice_hi_h_spin_angle": spin_angle,
     }
     dataset = xr.Dataset(
         coords=coords,
@@ -93,13 +107,22 @@ def create_xarray_from_records(records: list[dict]) -> xr.Dataset:  # noqa: PLR0
     for key in instrument_keys:
         attrs = cdf_manager.get_variable_attributes(key, check_schema=False)
         fillval = attrs.get("FILLVAL")
-        if key.startswith("mag"):
+        if key in ["mag_B_GSE", "mag_B_GSM"]:
             data = np.full((n, 3), fillval, dtype=np.float32)
             dims = ["epoch", "component"]
             dataset[key] = xr.DataArray(data, dims=dims, attrs=attrs)
-        elif key.startswith("codicehi"):
+        elif key == "mag_B_RTN":
+            data = np.full((n, 3), fillval, dtype=np.float32)
+            dims = ["epoch", "RTN_component"]
+            dataset[key] = xr.DataArray(data, dims=dims, attrs=attrs)
+        elif key.startswith("codice_hi"):
             data = np.full((n, 15, 4, 4), fillval, dtype=np.float32)
-            dims = ["epoch", "energy", "azimuth", "spin_angle_bin"]
+            dims = [
+                "epoch",
+                "codice_hi_h_energy_ranges",
+                "codice_hi_h_elevation",
+                "codice_hi_h_spin_angle",
+            ]
             dataset[key] = xr.DataArray(data, dims=dims, attrs=attrs)
         elif key == "swe_counterstreaming_electrons":
             data = np.full(n, fillval, dtype=np.uint8)
@@ -123,11 +146,11 @@ def create_xarray_from_records(records: list[dict]) -> xr.Dataset:  # noqa: PLR0
         for key, val in record.items():
             if key in ["apid", "met", "met_in_utc", "ttj2000ns"]:
                 continue
-            elif key.startswith("mag"):
+            elif key in ["mag_B_GSE", "mag_B_GSM", "mag_B_RTN"]:
                 dataset[key].data[i, :] = val
             elif key.startswith("swe_normalized_counts"):
                 dataset[key].data[i, :] = val
-            elif key.startswith("codicehi"):
+            elif key.startswith("codice_hi"):
                 dataset[key].data[i, :, :, :] = val
             else:
                 dataset[key].data[i] = val

imap_processing/idex/idex_constants.py

@@ -82,13 +82,9 @@ SPICE_ARRAYS = [
     "spin_phase",
 ]
 
-# Default IDEX Healpix parameters
-# Used in IDEX l2c processing
-IDEX_HEALPIX_NSIDE = 8
-IDEX_HEALPIX_NESTED = False
 # Default IDEX Rectangular parameters
 # Used in IDEX l2c processing
-IDEX_SPACING_DEG = 4  # TODO
+IDEX_SPACING_DEG = 6
 
 # Define the pointing reference frame for IDEX
 IDEX_EVENT_REFERENCE_FRAME = SpiceFrame.ECLIPJ2000

imap_processing/idex/idex_l0.py

@@ -2,7 +2,7 @@
 
 import logging
 from pathlib import Path
-from typing import Any, Union
+from typing import Any
 
 from xarray import Dataset
 
@@ -13,7 +13,7 @@ logger = logging.getLogger(__name__)
 
 
 def decom_packets(
-    packet_file: Union[str, Path],
+    packet_file: str | Path,
 ) -> tuple[list[Any], dict[int, Dataset], dict[int, Dataset]]:
     """
     Decom IDEX data packets using IDEX packet definition.

imap_processing/idex/idex_l1a.py

@@ -17,7 +17,6 @@ Examples
 import logging
 from enum import IntEnum
 from pathlib import Path
-from typing import Union
 
 import numpy as np
 import numpy.typing as npt
@@ -61,7 +60,7 @@ class PacketParser:
         The path and filename to the L0 file to read.
     """
 
-    def __init__(self, packet_file: Union[str, Path]) -> None:
+    def __init__(self, packet_file: str | Path) -> None:
         """
         Read a L0 pkts file and perform all of the decom work.
 
@@ -250,7 +249,7 @@ def _read_waveform_bits(waveform_raw: str, high_sample: bool = True) -> list[int
 
 
 def calculate_idex_epoch_time(
-    shcoarse_time: Union[float, np.ndarray], shfine_time: Union[float, np.ndarray]
+    shcoarse_time: float | np.ndarray, shfine_time: float | np.ndarray
 ) -> npt.NDArray[np.int64]:
     """
     Calculate the epoch time from the FPGA header time variables.

imap_processing/idex/idex_l1b.py

@@ -16,7 +16,6 @@ Examples
 
 import logging
 from enum import Enum
-from typing import Union
 
 import pandas as pd
 import xarray as xr
@@ -226,7 +225,7 @@ def convert_waveforms(
 
 def get_trigger_mode_and_level(
     l1a_dataset: xr.Dataset,
-) -> Union[dict[str, xr.DataArray], dict]:
+) -> dict[str, xr.DataArray] | dict:
     """
     Determine the trigger mode and threshold level for each event.
 
@@ -249,7 +248,7 @@ def get_trigger_mode_and_level(
 
     def compute_trigger_values(
         trigger_mode: int, trigger_controls: int, gain_channel: str
-    ) -> Union[tuple[str, Union[int, float]], tuple[None, None]]:
+    ) -> tuple[str, int | float] | tuple[None, None]:
         """
         Compute the trigger mode label and threshold level.