imap-processing 0.6.0__py3-none-any.whl

imap_processing/ultra/l1b/de.py

@@ -0,0 +1,59 @@
+"""Calculate Annotated Direct Events."""
+
+import numpy as np
+import xarray as xr
+
+from imap_processing.ultra.utils.ultra_l1_utils import create_dataset
+
+
+def calculate_de(de_dataset: xr.Dataset, name: str) -> xr.Dataset:
+    """
+    Create dataset with defined datatypes for Direct Event Data.
+
+    Parameters
+    ----------
+    de_dataset : xarray.Dataset
+        Dataset containing direct event data.
+    name : str
+        Name of the dataset.
+
+    Returns
+    -------
+    dataset : xarray.Dataset
+        Dataset containing the data.
+    """
+    de_dict = {}
+
+    # Placeholder for calculations
+    epoch = de_dataset.coords["epoch"].values
+
+    de_dict["epoch"] = de_dataset["epoch"]
+    de_dict["x_front"] = np.zeros(len(epoch), dtype=np.float64)
+    de_dict["y_front"] = np.zeros(len(epoch), dtype=np.float64)
+    de_dict["x_back"] = np.zeros(len(epoch), dtype=np.float64)
+    de_dict["y_back"] = np.zeros(len(epoch), dtype=np.float64)
+    de_dict["x_coin"] = np.zeros(len(epoch), dtype=np.float64)
+    de_dict["tof_start_stop"] = np.zeros(len(epoch), dtype=np.float64)
+    de_dict["tof_stop_coin"] = np.zeros(len(epoch), dtype=np.float64)
+    de_dict["tof_corrected"] = np.zeros(len(epoch), dtype=np.float64)
+    de_dict["eventtype"] = np.zeros(len(epoch), dtype=np.uint64)
+    de_dict["vx_ultra"] = np.zeros(len(epoch), dtype=np.float64)
+    de_dict["vy_ultra"] = np.zeros(len(epoch), dtype=np.float64)
+    de_dict["vz_ultra"] = np.zeros(len(epoch), dtype=np.float64)
+    de_dict["energy"] = np.zeros(len(epoch), dtype=np.float64)
+    de_dict["species"] = np.zeros(len(epoch), dtype=np.uint64)
+    de_dict["event_efficiency"] = np.zeros(len(epoch), dtype=np.float64)
+    de_dict["vx_sc"] = np.zeros(len(epoch), dtype=np.float64)
+    de_dict["vy_sc"] = np.zeros(len(epoch), dtype=np.float64)
+    de_dict["vz_sc"] = np.zeros(len(epoch), dtype=np.float64)
+    de_dict["vx_dps_sc"] = np.zeros(len(epoch), dtype=np.float64)
+    de_dict["vy_dps_sc"] = np.zeros(len(epoch), dtype=np.float64)
+    de_dict["vz_dps_sc"] = np.zeros(len(epoch), dtype=np.float64)
+    de_dict["vx_dps_helio"] = np.zeros(len(epoch), dtype=np.float64)
+    de_dict["vy_dps_helio"] = np.zeros(len(epoch), dtype=np.float64)
+    de_dict["vz_dps_helio"] = np.zeros(len(epoch), dtype=np.float64)
+    de_dict["eventtimes"] = np.zeros(len(epoch), dtype=np.float64)
+
+    dataset = create_dataset(de_dict, name, "l1b")
+
+    return dataset

imap_processing/ultra/l1b/extendedspin.py

@@ -0,0 +1,45 @@
+"""Calculate Extended Spin."""
+
+import numpy as np
+import xarray as xr
+
+from imap_processing.ultra.utils.ultra_l1_utils import create_dataset
+
+
+def calculate_extendedspin(rates_dataset: xr.Dataset, name: str) -> xr.Dataset:
+    """
+    Create dataset with defined datatypes for Extended Spin Data.
+
+    Parameters
+    ----------
+    rates_dataset : xarray.Dataset
+        Dataset containing rates data.
+    name : str
+        Name of the dataset.
+
+    Returns
+    -------
+    extendedspin_dataset : xarray.Dataset
+        Dataset containing the data.
+    """
+    extendedspin_dict = {}
+
+    epoch = rates_dataset.coords["epoch"].values
+
+    # Placeholder for calculations
+    extendedspin_dict["epoch"] = epoch
+    extendedspin_dict["spin_number"] = np.zeros(len(epoch), dtype=np.uint64)
+    extendedspin_dict["spin_start_time"] = np.zeros(len(epoch), dtype=np.float64)
+    extendedspin_dict["avg_spin_period"] = np.zeros(len(epoch), dtype=np.float64)
+    extendedspin_dict["rate_start_pulses"] = np.zeros(len(epoch), dtype=np.float64)
+    extendedspin_dict["rate_stop_pulses"] = np.zeros(len(epoch), dtype=np.float64)
+    extendedspin_dict["rate_coin_pulses"] = np.zeros(len(epoch), dtype=np.float64)
+    extendedspin_dict["rate_processed_events"] = np.zeros(len(epoch), dtype=np.float64)
+    extendedspin_dict["rate_rejected_events"] = np.zeros(len(epoch), dtype=np.float64)
+    extendedspin_dict["quality_hk"] = np.zeros(len(epoch), dtype=np.uint16)
+    extendedspin_dict["quality_attitude"] = np.zeros(len(epoch), dtype=np.uint16)
+    extendedspin_dict["quality_instruments"] = np.zeros(len(epoch), dtype=np.uint16)
+
+    extendedspin_dataset = create_dataset(extendedspin_dict, name, "l1b")
+
+    return extendedspin_dataset

imap_processing/ultra/l1b/lookup_utils.py

@@ -0,0 +1,165 @@
+"""Contains tools for lookup tables for l1b."""
+
+import numpy as np
+import numpy.typing as npt
+import pandas as pd
+import xarray as xr
+
+from imap_processing import imap_module_directory
+
+BASE_PATH = imap_module_directory / "ultra" / "lookup_tables"
+
+_YADJUST_DF = pd.read_csv(BASE_PATH / "yadjust.csv").set_index("dYLUT")
+_TDC_NORM_DF_ULTRA45 = pd.read_csv(
+    BASE_PATH / "ultra45_tdc_norm.csv", header=1, index_col="Index"
+)
+_TDC_NORM_DF_ULTRA90 = pd.read_csv(
+    BASE_PATH / "ultra90_tdc_norm.csv", header=1, index_col="Index"
+)
+_BACK_POS_DF_ULTRA45 = pd.read_csv(
+    BASE_PATH / "ultra45_back-pos-luts.csv", index_col="Index_offset"
+)
+_BACK_POS_DF_ULTRA90 = pd.read_csv(
+    BASE_PATH / "ultra90_back-pos-luts.csv", index_col="Index_offset"
+)
+_ENERGY_NORM_DF = pd.read_csv(BASE_PATH / "EgyNorm.mem.csv")
+_IMAGE_PARAMS_DF = pd.read_csv(BASE_PATH / "FM45_Startup1_ULTRA_IMGPARAMS_20240719.csv")
+
+
+def get_y_adjust(dy_lut: np.ndarray) -> npt.NDArray:
+    """
+    Adjust the front yf position based on the particle's trajectory.
+
+    Instead of using trigonometry, this function utilizes a 256-element lookup table
+    to find the Y adjustment. For more details, refer to pages 37-38 of the
+    IMAP-Ultra Flight Software Specification document (7523-9009_Rev_-.pdf).
+
+    Parameters
+    ----------
+    dy_lut : np.ndarray
+        Change in y direction used for the lookup table (mm).
+
+    Returns
+    -------
+    yadj : np.ndarray
+        Y adjustment (mm).
+    """
+    return _YADJUST_DF["dYAdj"].iloc[dy_lut].values
+
+
+def get_norm(dn: xr.DataArray, key: str, file_label: str) -> npt.NDArray:
+    """
+    Correct mismatches between the stop Time to Digital Converters (TDCs).
+
+    There are mismatches between the stop TDCs, i.e., SpN, SpS, SpE, and SpW.
+    Before these can be used, they must be corrected, or normalized,
+    using lookup tables.
+
+    Further description is available on pages 31-32 of the IMAP-Ultra Flight Software
+    Specification document (7523-9009_Rev_-.pdf). This will work for both Tp{key}Norm,
+    Bt{key}Norm. This is for getStopNorm and getCoinNorm.
+
+    Parameters
+    ----------
+    dn : np.ndarray
+        DN of the TDC.
+    key : str
+        TpSpNNorm, TpSpSNorm, TpSpENorm, or TpSpWNorm.
+        BtSpNNorm, BtSpSNorm, BtSpENorm, or BtSpWNorm.
+    file_label : str
+        Instrument (ultra45 or ultra90).
+
+    Returns
+    -------
+    dn_norm : np.ndarray
+        Normalized DNs.
+    """
+    if file_label == "ultra45":
+        tdc_norm_df = _TDC_NORM_DF_ULTRA45
+    else:
+        tdc_norm_df = _TDC_NORM_DF_ULTRA90
+
+    dn_norm = tdc_norm_df[key].iloc[dn].values
+
+    return dn_norm
+
+
+def get_back_position(back_index: np.ndarray, key: str, file_label: str) -> npt.NDArray:
+    """
+    Convert normalized TDC values using lookup tables.
+
+    The anodes behave non-linearly near their edges; thus, the use of lookup tables
+    instead of linear equations is necessary. The computation will use different
+    tables to accommodate variations between the top and bottom anodes.
+    Further description is available on page 32 of the
+    IMAP-Ultra Flight Software Specification document (7523-9009_Rev_-.pdf).
+
+    Parameters
+    ----------
+    back_index : np.ndarray
+        Options include SpSNorm - SpNNorm + 2047, SpENorm - SpWNorm + 2047,
+        SpSNorm - SpNNorm + 2047, or SpENorm - SpWNorm + 2047.
+    key : str
+        XBkTp, YBkTp, XBkBt, or YBkBt.
+    file_label : str
+        Instrument (ultra45 or ultra90).
+
+    Returns
+    -------
+    dn_converted : np.ndarray
+        Converted DNs to Units of hundredths of a millimeter.
+    """
+    if file_label == "ultra45":
+        back_pos_df = _BACK_POS_DF_ULTRA45
+    else:
+        back_pos_df = _BACK_POS_DF_ULTRA90
+
+    return back_pos_df[key].values[back_index]
+
+
+def get_energy_norm(ssd: np.ndarray, composite_energy: np.ndarray) -> npt.NDArray:
+    """
+    Normalize composite energy per SSD using a lookup table.
+
+    Further description is available on page 41 of the
+    IMAP-Ultra Flight Software Specification document
+    (7523-9009_Rev_-.pdf). Note : There are 8 SSDs containing
+    4096 composite energies each.
+
+    Parameters
+    ----------
+    ssd : np.ndarray
+        Acts as index 1.
+    composite_energy : np.ndarray
+        Acts as index 2.
+
+    Returns
+    -------
+    norm_composite_energy : np.ndarray
+        Normalized composite energy.
+    """
+    row_number = ssd * 4096 + composite_energy
+
+    return _ENERGY_NORM_DF["NormEnergy"].iloc[row_number]
+
+
+def get_image_params(image: str) -> np.float64:
+    """
+    Lookup table for image parameters.
+
+    Further description is available starting on
+    page 30 of the IMAP-Ultra Flight Software
+    Specification document (7523-9009_Rev_-.pdf).
+
+    Parameters
+    ----------
+    image : str
+        The column name to lookup in the CSV file, e.g., 'XFTLTOFF' or 'XFTRTOFF'.
+
+    Returns
+    -------
+    value : np.float64
+        Image parameter value from the CSV file.
+    """
+    value: np.float64 = _IMAGE_PARAMS_DF[image].values[0]
+    return value

imap_processing/ultra/l1b/ultra_l1b.py

@@ -0,0 +1,65 @@
+"""Calculate ULTRA L1b."""
+
+import xarray as xr
+
+from imap_processing.ultra.l1b.badtimes import calculate_badtimes
+from imap_processing.ultra.l1b.cullingmask import calculate_cullingmask
+from imap_processing.ultra.l1b.de import calculate_de
+from imap_processing.ultra.l1b.extendedspin import calculate_extendedspin
+
+
+def ultra_l1b(data_dict: dict, data_version: str) -> list[xr.Dataset]:
+    """
+    Will process ULTRA L1A data into L1B CDF files at output_filepath.
+
+    Parameters
+    ----------
+    data_dict : dict
+        The data itself and its dependent data.
+    data_version : str
+        Version of the data product being created.
+
+    Returns
+    -------
+    output_datasets : list[xarray.Dataset]
+        List of xarray.Dataset.
+    """
+    output_datasets = []
+    instrument_id = 45 if any("45" in key for key in data_dict.keys()) else 90
+
+    if f"imap_ultra_l1a_{instrument_id}sensor-rates" in data_dict:
+        extendedspin_dataset = calculate_extendedspin(
+            data_dict[f"imap_ultra_l1a_{instrument_id}sensor-rates"],
+            f"imap_ultra_l1b_{instrument_id}sensor-extendedspin",
+        )
+        # TODO: move these to use ImapCdfAttributes().add_global_attribute()
+        extendedspin_dataset.attrs["Data_version"] = data_version
+
+        cullingmask_dataset = calculate_cullingmask(
+            extendedspin_dataset, f"imap_ultra_l1b_{instrument_id}sensor-cullingmask"
+        )
+        cullingmask_dataset.attrs["Data_version"] = data_version
+
+        badtimes_dataset = calculate_badtimes(
+            extendedspin_dataset, f"imap_ultra_l1b_{instrument_id}sensor-badtimes"
+        )
+        badtimes_dataset.attrs["Data_version"] = data_version
+
+        output_datasets.extend(
+            [extendedspin_dataset, cullingmask_dataset, badtimes_dataset]
+        )
+    elif (
+        f"imap_ultra_l1a_{instrument_id}sensor-aux" in data_dict
+        and f"imap_ultra_l1a_{instrument_id}sensor-de" in data_dict
+    ):
+        de_dataset = calculate_de(
+            data_dict[f"imap_ultra_l1a_{instrument_id}sensor-de"],
+            f"imap_ultra_l1b_{instrument_id}sensor-de",
+        )
+        de_dataset.attrs["Data_version"] = data_version
+
+        output_datasets.append(de_dataset)
+    else:
+        raise ValueError("Data dictionary does not contain the expected keys.")
+
+    return output_datasets

imap_processing/ultra/l1b/ultra_l1b_annotated.py

@@ -0,0 +1,54 @@
+"""Calculates Annotated Events for ULTRA L1b."""
+
+import typing
+
+import numpy as np
+import spiceypy as spice
+from numpy.typing import NDArray
+
+from imap_processing.spice.geometry import SpiceFrame
+from imap_processing.spice.kernels import ensure_spice
+
+
+@ensure_spice
+@typing.no_type_check
+def get_particle_velocity(
+    time: np.ndarray,
+    instrument_velocity: np.ndarray,
+    instrument_frame: SpiceFrame,
+    pointing_frame: SpiceFrame,
+) -> NDArray[np.float64]:
+    """
+    Get the particle velocity in the pointing (DPS) frame wrt the spacecraft.
+
+    Parameters
+    ----------
+    time : np.ndarray
+        Ephemeris time.
+    instrument_velocity : np.ndarray
+        Particle velocity in the instrument frame.
+    instrument_frame : SpiceFrame
+        Instrument frame.
+    pointing_frame : SpiceFrame
+        Pointing frame.
+
+    Returns
+    -------
+    spacecraft_velocity : np.ndarray
+        Particle velocity in the spacecraft frame.
+
+    References
+    ----------
+    https://spiceypy.readthedocs.io/en/main/documentation.html#spiceypy.spiceypy
+    """
+    # Particle velocity in the pointing (DPS) frame wrt spacecraft.
+    spacecraft_velocity = np.zeros((len(time), 3), dtype=np.float64)
+
+    for index in range(len(time)):
+        # Get and apply the rotation matrix to the particle velocity.
+        spacecraft_velocity[index] = spice.mxv(
+            spice.pxform(instrument_frame.name, pointing_frame.name, time[index]),
+            instrument_velocity[index],
+        )
+
+    return spacecraft_velocity