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

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

imap_processing/idex/idex_l2a.py

@@ -24,7 +24,7 @@ import pandas as pd
 import xarray as xr
 from numpy.typing import NDArray
 from scipy.integrate import quad
-from scipy.optimize import curve_fit
+from scipy.optimize import curve_fit, root_scalar
 from scipy.signal import butter, detrend, filtfilt, find_peaks
 from scipy.stats import exponnorm
 
@@ -52,7 +52,33 @@ class BaselineNoiseTime(IntEnum):
     STOP = -5
 
 
-def idex_l2a(l1b_dataset: xr.Dataset) -> xr.Dataset:
+def load_calibration_files(ancillary_files: dict) -> tuple[NDArray, NDArray]:
+    """
+    Load calibration files for IDEX L2A processing.
+
+    Parameters
+    ----------
+    ancillary_files : dict
+        Dictionary containing paths to calibration files.
+
+    Returns
+    -------
+    numpy.ndarray
+        Calibration parameters for the rise time function.
+    numpy.ndarray
+        Calibration parameters for the charge yield function.
+    """
+    # Load calibration coefficients from ancillary files
+    t_rise_params = pd.read_csv(
+        ancillary_files["l2a-calibration-curve-yield-params"], skiprows=1, header=None
+    ).values.flatten()[:8]
+    yield_params = pd.read_csv(
+        ancillary_files["l2a-calibration-curve-t-rise"], skiprows=1, header=None
+    ).values.flatten()[:8]
+    return t_rise_params, yield_params
+
+
+def idex_l2a(l1b_dataset: xr.Dataset, ancillary_files: dict) -> xr.Dataset:
     """
     Will process IDEX l1b data to create l2a data products.
 
@@ -68,6 +94,9 @@ def idex_l2a(l1b_dataset: xr.Dataset) -> xr.Dataset:
     ----------
     l1b_dataset : xarray.Dataset
         IDEX L1a dataset to process.
+    ancillary_files : dict
+        Ancillary files containing calibration coefficients needed to estimate
+        velocity and mass of the dust particles.
 
     Returns
     -------
@@ -79,6 +108,7 @@ def idex_l2a(l1b_dataset: xr.Dataset) -> xr.Dataset:
     logger.info(
         f"Running IDEX L2A processing on dataset: {l1b_dataset.attrs['Logical_source']}"
     )
+    t_rise_params, yield_params = load_calibration_files(ancillary_files)
 
     tof_high = l1b_dataset["TOF_High"]
     hs_time = l1b_dataset["time_high_sample_rate"]
@@ -176,11 +206,24 @@ def idex_l2a(l1b_dataset: xr.Dataset) -> xr.Dataset:
             output_dtypes=[np.float64] * 6,
             keep_attrs=True,
         )
+        # Calculate mass and velocity estimates
+        velocity_mass_results = xr.apply_ufunc(
+            calculate_velocity_and_mass,
+            fit_results[1],  # signal amplitude
+            fit_results[0].data[:, 3],  # fit params
+            output_core_dims=[[], []],
+            vectorize=True,
+            output_dtypes=[np.float64, np.float64],
+            keep_attrs=True,
+            kwargs={"t_rise_params": t_rise_params, "yield_params": yield_params},
+        )
+
         waveform_name = waveform.lower()
         output_vars = {
             f"{waveform_name}_fit_parameters": fit_results[0],
             f"{waveform_name}_impact_charge": fit_results[1],
-            f"{waveform_name}_dust_mass_estimate": fit_results[1],
+            f"{waveform_name}_velocity_estimate": velocity_mass_results[0],
+            f"{waveform_name}_dust_mass_estimate": velocity_mass_results[1],
             # Same as impact_charge for now
             f"{waveform_name}_chi_squared": fit_results[2],
             f"{waveform_name}_reduced_chi_squared": fit_results[3],
@@ -261,6 +304,89 @@ def idex_l2a(l1b_dataset: xr.Dataset) -> xr.Dataset:
     return l2a_dataset
 
 
+def calculate_velocity_and_mass(
+    sig_amp: float, t_rise: float, t_rise_params: np.ndarray, yield_params: np.ndarray
+) -> tuple[float, float]:
+    """
+    Calculate velocity and mass estimates.
+
+    The fitted target signals are used to generate IDEX’s specific charge yield as a
+    function of the impact speed. The calibration curve is fitted with a
+    segmented power law distribution. The charge yield curve enables the mass of
+    the dust particle to be estimated from the total charge it generates on the target.
+
+    Parameters
+    ----------
+    sig_amp : float
+        Signal amplitude.
+    t_rise : float
+        T_rise fit parameter from the target fit.
+    t_rise_params : np.ndarray
+        Calibration parameters for rise time.
+    yield_params : np.ndarray
+        Calibration parameters for yield.
+
+    Returns
+    -------
+    v_est : float
+        Estimated velocity.
+    mass_est : float
+        Estimated mass.
+    """
+    log_a_t: float = np.log10(t_rise_params[0])
+    try:
+        root = root_scalar(
+            lambda lv: log_smooth_powerlaw(lv, log_a_t, t_rise_params[1:])
+            - np.log10(t_rise),
+            bracket=[-1, 2],
+        )
+        v_est = 10**root.root
+    except Exception:
+        logger.error(
+            "Unable to calculate velocity and mass estimate. "
+            "The root finding failed for power law function. "
+            "Returning nans for the estimate."
+        )
+        return np.nan, np.nan
+
+    log_a_y: float = np.log10(yield_params[0])
+    yield_val = 10 ** log_smooth_powerlaw(np.log10(v_est), log_a_y, yield_params[1:])
+    mass_est = sig_amp / yield_val
+
+    return v_est, mass_est
+
+
+def log_smooth_powerlaw(log_v: float, log_a: float, params: np.ndarray) -> float:
+    """
+    Define a smoothly transitioning power law to fit the calibration curve to.
+
+    Parameters
+    ----------
+    log_v : float
+        Velocity.
+    log_a : float
+        Scale factor.
+    params : np.ndarray
+        Calibration parameters for the power law.
+
+    Returns
+    -------
+    float
+        The value of the power law at the given velocity.
+    """
+    # Unpack the rest of the calibration parameters
+    # a1, a2, and a3 are the power law exponents for the low, medium, and high-velocity
+    # segments.
+    # vb and vc are the characteristic speeds where the slope transition happens, and k
+    # setting the sharpness of the transitions.
+    a1, a2, a3, vb, vc, k, m = params
+    v = 10**log_v
+    base = log_a + a1 * log_v
+    transition1 = (1 + (v / vb) ** m) ** ((a2 - a1) / m)
+    transition2 = (1 + (v / vc) ** m) ** ((a3 - a2) / m)
+    return base + np.log10(transition1 * transition2)
+
+
 def time_to_mass(
     tof_high: np.ndarray, high_sampling_time: np.ndarray, masses: np.ndarray
 ) -> tuple[NDArray, NDArray, NDArray]:
@@ -399,7 +525,7 @@ def calculate_kappa(mass_scales: np.ndarray, peaks_2d: list) -> NDArray:
     kappas = np.asarray(
         [
             np.mean(mass_scale[peaks] - np.round(mass_scale[peaks]))
-            for mass_scale, peaks in zip(mass_scales, peaks_2d)
+            for mass_scale, peaks in zip(mass_scales, peaks_2d, strict=False)
         ]
     )
     return kappas