imap-processing 0.9.0__py3-none-any.whl → 0.11.0__py3-none-any.whl

imap_processing/ultra/l1b/de.py

@@ -13,6 +13,9 @@ from imap_processing.ultra.l1b.ultra_l1b_extended import (
     determine_species,
     get_coincidence_positions,
     get_ctof,
+    get_de_az_el,
+    get_de_energy_kev,
+    get_de_velocity,
     get_energy_pulse_height,
     get_energy_ssd,
     get_front_x_position,
@@ -21,12 +24,11 @@ from imap_processing.ultra.l1b.ultra_l1b_extended import (
     get_ph_tof_and_back_positions,
     get_ssd_back_position_and_tof_offset,
     get_ssd_tof,
-    get_unit_vector,
 )
 from imap_processing.ultra.utils.ultra_l1_utils import create_dataset
 
 
-def calculate_de(de_dataset: xr.Dataset, name: str) -> xr.Dataset:
+def calculate_de(de_dataset: xr.Dataset, name: str, data_version: str) -> xr.Dataset:
     """
     Create dataset with defined datatypes for Direct Event Data.
 
@@ -36,6 +38,8 @@ def calculate_de(de_dataset: xr.Dataset, name: str) -> xr.Dataset:
         L1a dataset containing direct event data.
     name : str
         Name of the l1a dataset.
+    data_version : str
+        Version of the data.
 
     Returns
     -------
@@ -45,6 +49,11 @@ def calculate_de(de_dataset: xr.Dataset, name: str) -> xr.Dataset:
     de_dict = {}
     sensor = parse_filename_like(name)["sensor"][0:2]
 
+    # Drop events with invalid start type.
+    de_dataset = de_dataset.where(
+        de_dataset["START_TYPE"] != np.iinfo(np.int64).min, drop=True
+    )
+
     # Instantiate arrays
     yf = np.full(len(de_dataset["epoch"]), np.nan, dtype=np.float32)
     xb = np.full(len(de_dataset["epoch"]), np.nan, dtype=np.float32)
@@ -55,17 +64,13 @@ def calculate_de(de_dataset: xr.Dataset, name: str) -> xr.Dataset:
     tof = np.full(len(de_dataset["epoch"]), np.nan, dtype=np.float32)
     etof = np.full(len(de_dataset["epoch"]), np.nan, dtype=np.float32)
     ctof = np.full(len(de_dataset["epoch"]), np.nan, dtype=np.float32)
+    magnitude_v = np.full(len(de_dataset["epoch"]), np.nan, dtype=np.float32)
     energy = np.full(len(de_dataset["epoch"]), np.nan, dtype=np.float32)
-    #  TODO: Confirm with Ultra team what fill values and dtype we want.
     species_bin = np.full(len(de_dataset["epoch"]), "UNKNOWN", dtype="U10")
     t2 = np.full(len(de_dataset["epoch"]), np.nan, dtype=np.float32)
 
-    # Drop events with invalid start type.
-    de_dataset = de_dataset.where(
-        de_dataset["START_TYPE"] != np.iinfo(np.int64).min, drop=True
-    )
     # Define epoch.
-    de_dict["epoch"] = de_dataset["epoch"]
+    de_dict["epoch"] = de_dataset["epoch"].data
 
     xf = get_front_x_position(
         de_dataset["START_TYPE"].data,
@@ -97,7 +102,9 @@ def calculate_de(de_dataset: xr.Dataset, name: str) -> xr.Dataset:
     etof[ph_indices], xc[ph_indices] = get_coincidence_positions(
         de_dataset.isel(epoch=ph_indices), t2[ph_indices], f"ultra{sensor}"
     )
-    ctof[ph_indices], _ = get_ctof(tof[ph_indices], r[ph_indices], "PH")
+    ctof[ph_indices], magnitude_v[ph_indices] = get_ctof(
+        tof[ph_indices], r[ph_indices], "PH"
+    )
 
     # SSD
     ssd_indices = np.nonzero(np.isin(de_dataset["STOP_TYPE"], StopType.SSD.value))[0]
@@ -118,7 +125,9 @@ def calculate_de(de_dataset: xr.Dataset, name: str) -> xr.Dataset:
     species_bin[ssd_indices] = determine_species(
         tof[ssd_indices], r[ssd_indices], "SSD"
     )
-    ctof[ssd_indices], _ = get_ctof(tof[ssd_indices], r[ssd_indices], "SSD")
+    ctof[ssd_indices], magnitude_v[ssd_indices] = get_ctof(
+        tof[ssd_indices], r[ssd_indices], "SSD"
+    )
 
     # Combine ph_yb and ssd_yb along with their indices
     de_dict["x_front"] = xf.astype(np.float32)
@@ -129,6 +138,7 @@ def calculate_de(de_dataset: xr.Dataset, name: str) -> xr.Dataset:
     de_dict["tof_start_stop"] = tof
     de_dict["tof_stop_coin"] = etof
     de_dict["tof_corrected"] = ctof
+    de_dict["velocity_magnitude"] = magnitude_v
     de_dict["front_back_distance"] = d
     de_dict["path_length"] = r
 
@@ -137,61 +147,46 @@ def calculate_de(de_dataset: xr.Dataset, name: str) -> xr.Dataset:
         "start_type",
         "event_type",
         "de_event_met",
+        "event_times",
     ]
-    dataset_keys = ["COIN_TYPE", "START_TYPE", "STOP_TYPE", "SHCOARSE"]
+    dataset_keys = ["COIN_TYPE", "START_TYPE", "STOP_TYPE", "SHCOARSE", "EVENTTIMES"]
 
     de_dict.update(
         {key: de_dataset[dataset_key] for key, dataset_key in zip(keys, dataset_keys)}
     )
 
-    vx_ultra, vy_ultra, vz_ultra = get_unit_vector(
+    v = 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"],
     )
+    de_dict["direct_event_velocity"] = v.astype(np.float32)
 
-    de_dict["vx_ultra"] = vx_ultra.astype(np.float32)
-    de_dict["vy_ultra"] = vy_ultra.astype(np.float32)
-    de_dict["vz_ultra"] = vz_ultra.astype(np.float32)
+    de_dict["tof_energy"] = get_de_energy_kev(v, species_bin)
+    de_dict["azimuth"], de_dict["elevation"] = get_de_az_el(v)
     de_dict["energy"] = energy
     de_dict["species"] = species_bin
 
     # Annotated Events.
-    position = np.stack(
-        (de_dict["vx_ultra"], de_dict["vy_ultra"], de_dict["vz_ultra"]), axis=-1
-    )
-
     ultra_frame = getattr(SpiceFrame, f"IMAP_ULTRA_{sensor}")
     sc_velocity, sc_dps_velocity, helio_velocity = get_annotated_particle_velocity(
-        de_dataset.data_vars["EVENTTIMES"],
-        position,
+        de_dataset.data_vars["EVENTTIMES"].values,
+        de_dict["direct_event_velocity"],
         ultra_frame,
         SpiceFrame.IMAP_DPS,
         SpiceFrame.IMAP_SPACECRAFT,
     )
 
-    de_dict["vx_sc"], de_dict["vy_sc"], de_dict["vz_sc"] = (
-        sc_velocity[:, 0],
-        sc_velocity[:, 1],
-        sc_velocity[:, 2],
-    )
-    de_dict["vx_dps_sc"], de_dict["vy_dps_sc"], de_dict["vz_dps_sc"] = (
-        sc_dps_velocity[:, 0],
-        sc_dps_velocity[:, 1],
-        sc_dps_velocity[:, 2],
-    )
-    de_dict["vx_dps_helio"], de_dict["vy_dps_helio"], de_dict["vz_dps_helio"] = (
-        helio_velocity[:, 0],
-        helio_velocity[:, 1],
-        helio_velocity[:, 2],
-    )
+    de_dict["velocity_sc"] = sc_velocity
+    de_dict["velocity_dps_sc"] = sc_dps_velocity
+    de_dict["velocity_dps_helio"] = helio_velocity
 
     # TODO: TBD.
     de_dict["event_efficiency"] = np.full(
         len(de_dataset["epoch"]), np.nan, dtype=np.float32
     )
 
-    dataset = create_dataset(de_dict, name, "l1b")
+    dataset = create_dataset(de_dict, name, "l1b", data_version)
 
     return dataset

imap_processing/ultra/l1b/extendedspin.py

@@ -1,21 +1,38 @@
 """Calculate Extended Spin."""
 
-import numpy as np
 import xarray as xr
 
+from imap_processing.ultra.l1b.ultra_l1b_culling import (
+    flag_attitude,
+    flag_spin,
+    get_energy_histogram,
+    get_spin,
+)
 from imap_processing.ultra.utils.ultra_l1_utils import create_dataset
 
 
-def calculate_extendedspin(rates_dataset: xr.Dataset, name: str) -> xr.Dataset:
+def calculate_extendedspin(
+    hk_dataset: xr.Dataset,
+    rates_dataset: xr.Dataset,
+    de_dataset: xr.Dataset,
+    name: str,
+    data_version: str,
+) -> xr.Dataset:
     """
     Create dataset with defined datatypes for Extended Spin Data.
 
     Parameters
     ----------
+    hk_dataset : xarray.Dataset
+        Dataset containing l1a hk data.
     rates_dataset : xarray.Dataset
-        Dataset containing rates data.
+        Dataset containing l1a rates data.
+    de_dataset : xarray.Dataset
+        Dataset containing l1b de data.
     name : str
         Name of the dataset.
+    data_version : str
+        Version of the data.
 
     Returns
     -------
@@ -23,23 +40,30 @@ def calculate_extendedspin(rates_dataset: xr.Dataset, name: str) -> xr.Dataset:
         Dataset containing the data.
     """
     extendedspin_dict = {}
+    rates_qf, spin, energy_midpoints, n_sigma_per_energy = flag_spin(
+        de_dataset["event_times"].values,
+        de_dataset["energy"].values,
+    )
+    spin_number = get_spin(de_dataset["event_times"].values)
+    count_rates, _, counts, _ = get_energy_histogram(
+        spin_number, de_dataset["energy"].values
+    )
+    attitude_qf, spin_rates, spin_period, spin_starttime = flag_attitude(
+        de_dataset["event_times"].values
+    )
 
-    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")
+    # These will be the coordinates.
+    extendedspin_dict["spin_number"] = spin
+    extendedspin_dict["energy_bin_geometric_mean"] = energy_midpoints
+
+    extendedspin_dict["ena_rates"] = count_rates
+    extendedspin_dict["ena_rates_threshold"] = n_sigma_per_energy
+    extendedspin_dict["spin_start_time"] = spin_starttime
+    extendedspin_dict["spin_period"] = spin_period
+    extendedspin_dict["spin_rate"] = spin_rates
+    extendedspin_dict["quality_attitude"] = attitude_qf
+    extendedspin_dict["quality_ena_rates"] = rates_qf
+
+    extendedspin_dataset = create_dataset(extendedspin_dict, name, "l1b", data_version)
 
     return extendedspin_dataset

imap_processing/ultra/l1b/ultra_l1b.py

@@ -27,38 +27,37 @@ def ultra_l1b(data_dict: dict, data_version: str) -> list[xr.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:
+    if (
+        f"imap_ultra_l1a_{instrument_id}sensor-hk" in data_dict
+        and f"imap_ultra_l1a_{instrument_id}sensor-de" in data_dict
+        and f"imap_ultra_l1a_{instrument_id}sensor-rates" 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",
+            data_version,
+        )
         extendedspin_dataset = calculate_extendedspin(
+            data_dict[f"imap_ultra_l1a_{instrument_id}sensor-hk"],
             data_dict[f"imap_ultra_l1a_{instrument_id}sensor-rates"],
+            de_dataset,
             f"imap_ultra_l1b_{instrument_id}sensor-extendedspin",
+            data_version,
         )
-        # 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"
+            extendedspin_dataset,
+            f"imap_ultra_l1b_{instrument_id}sensor-cullingmask",
+            data_version,
         )
-        cullingmask_dataset.attrs["Data_version"] = data_version
-
         badtimes_dataset = calculate_badtimes(
-            extendedspin_dataset, f"imap_ultra_l1b_{instrument_id}sensor-badtimes"
+            extendedspin_dataset,
+            cullingmask_dataset["spin_number"].values,
+            f"imap_ultra_l1b_{instrument_id}sensor-badtimes",
+            data_version,
         )
-        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, extendedspin_dataset, cullingmask_dataset, badtimes_dataset]
         )
-        de_dataset.attrs["Data_version"] = data_version
-
-        output_datasets.append(de_dataset)
     else:
         raise ValueError("Data dictionary does not contain the expected keys.")
 

imap_processing/ultra/l1b/ultra_l1b_culling.py

@@ -0,0 +1,190 @@
+"""Culls Events for ULTRA L1b."""
+
+import numpy as np
+from numpy.typing import NDArray
+
+from imap_processing.quality_flags import ImapAttitudeUltraFlags, ImapRatesUltraFlags
+from imap_processing.spice.spin import get_spin_data, interpolate_spin_data
+from imap_processing.ultra.constants import UltraConstants
+
+
+def get_spin(eventtimes_met: NDArray) -> NDArray:
+    """
+    Get spin number for each event.
+
+    Parameters
+    ----------
+    eventtimes_met : NDArray
+        Event Times in Mission Elapsed Time.
+
+    Returns
+    -------
+    spin_number : NDArray
+        Spin number at each event derived the from Universal Spin Table.
+    """
+    spin_df = interpolate_spin_data(eventtimes_met)
+    return spin_df["spin_number"].values
+
+
+def get_energy_histogram(
+    spin_number: NDArray, energy: NDArray
+) -> tuple[NDArray, NDArray, NDArray, float]:
+    """
+    Compute a 2D histogram of the counts binned by energy and spin number.
+
+    Parameters
+    ----------
+    spin_number : NDArray
+        Spin number.
+    energy : NDArray
+        The particle energy.
+
+    Returns
+    -------
+    hist : NDArray
+        A 2D histogram array containing the
+        count rate per spin at each energy bin.
+    spin_edges : NDArray
+        Edges of the spin number bins.
+    counts : NDArray
+        A 2D histogram array containing the
+        counts per spin at each energy bin.
+    mean_duration : float
+        Mean duration of the spin.
+    """
+    spin_df = get_spin_data()
+
+    spin_edges = np.unique(spin_number)
+    spin_edges = np.append(spin_edges, spin_edges.max() + 1)
+
+    # Counts per spin at each energy bin.
+    hist, _ = np.histogramdd(
+        sample=(energy, spin_number),
+        bins=[UltraConstants.CULLING_ENERGY_BIN_EDGES, spin_edges],
+    )
+
+    counts = hist.copy()
+    total_spin_duration = 0
+
+    # Count rate per spin at each energy bin.
+    for i in range(hist.shape[1]):
+        spin_duration = spin_df.spin_period_sec[spin_df.spin_number == i]
+        hist[:, i] /= spin_duration.values[0]
+        total_spin_duration += spin_duration.sum()
+
+    mean_duration = total_spin_duration / hist.shape[1]
+
+    return hist, spin_edges, counts, mean_duration
+
+
+def flag_attitude(eventtimes_met: NDArray) -> tuple[NDArray, NDArray, NDArray, NDArray]:
+    """
+    Flag data based on attitude.
+
+    Parameters
+    ----------
+    eventtimes_met : NDArray
+        Event Times in Mission Elapsed Time.
+
+    Returns
+    -------
+    quality_flags : NDArray
+        Quality flags.
+    spin_rates : NDArray
+        Spin rates.
+    spin_period : NDArray
+        Spin period.
+    spin_starttime : NDArray
+        Spin start time.
+    """
+    spins = np.unique(get_spin(eventtimes_met))  # Get unique spins
+    spin_df = get_spin_data()  # Load spin data
+
+    spin_period = spin_df.loc[spin_df.spin_number.isin(spins), "spin_period_sec"]
+    spin_starttime = spin_df.loc[spin_df.spin_number.isin(spins), "spin_start_time"]
+    spin_rates = 60 / spin_period  # 60 seconds in a minute
+    bad_spin_rate_indices = (spin_rates < UltraConstants.CULLING_RPM_MIN) | (
+        spin_rates > UltraConstants.CULLING_RPM_MAX
+    )
+
+    quality_flags = np.full(
+        spin_rates.shape, ImapAttitudeUltraFlags.NONE.value, dtype=np.uint16
+    )
+    quality_flags[bad_spin_rate_indices] |= ImapAttitudeUltraFlags.SPINRATE.value
+
+    return quality_flags, spin_rates, spin_period, spin_starttime
+
+
+def get_n_sigma(count_rates: NDArray, mean_duration: float, sigma: int = 6) -> NDArray:
+    """
+    Calculate the threshold for the HIGHRATES flag.
+
+    Parameters
+    ----------
+    count_rates : NDArray
+        A 2D histogram array containing the
+        count rates per spin at each energy bin.
+    mean_duration : float
+        Mean duration of the spins.
+    sigma : int (default=6)
+        The number of sigma.
+
+    Returns
+    -------
+    threshold : NDArray
+        Threshold for applying HIGHRATES flag.
+    """
+    sigma_per_energy = np.std(count_rates, axis=1)
+    n_sigma_per_energy = sigma * sigma_per_energy
+    mean_per_energy = np.mean(count_rates, axis=1)
+    # Must have a HIGHRATES threshold of at least 3 counts per spin.
+    threshold = np.maximum(mean_per_energy + n_sigma_per_energy, 3 / mean_duration)
+
+    return threshold
+
+
+def flag_spin(
+    eventtimes_met: NDArray, energy: NDArray, sigma: int = 6
+) -> tuple[NDArray, NDArray, NDArray, NDArray]:
+    """
+    Flag data based on counts and negative energies.
+
+    Parameters
+    ----------
+    eventtimes_met : NDArray
+        Event Times in Mission Elapsed Time.
+    energy : NDArray
+        Energy data.
+    sigma : int (default=6)
+        The number of sigma.
+
+    Returns
+    -------
+    quality_flags : NDArray
+        Quality flags.
+    spin : NDArray
+        Spin data.
+    energy_midpoints : NDArray
+        Energy midpoint data.
+    n_sigma_per_energy_reshape : NDArray
+        N sigma per energy.
+    """
+    spin = get_spin(eventtimes_met)
+    count_rates, spin_edges, counts, duration = get_energy_histogram(spin, energy)
+    quality_flags = np.full(
+        count_rates.shape, ImapRatesUltraFlags.NONE.value, dtype=np.uint16
+    )
+
+    # Zero counts/spin/energy level
+    quality_flags[counts == 0] |= ImapRatesUltraFlags.ZEROCOUNTS.value
+    threshold = get_n_sigma(count_rates, duration, sigma=sigma)
+
+    bin_edges = np.array(UltraConstants.CULLING_ENERGY_BIN_EDGES)
+    energy_midpoints = np.sqrt(bin_edges[:-1] * bin_edges[1:])
+    spin = np.unique(spin)
+
+    # Indices where the counts exceed the threshold
+    indices_n_sigma = count_rates > threshold[:, np.newaxis]
+    quality_flags[indices_n_sigma] |= ImapRatesUltraFlags.HIGHRATES.value
+
+    return quality_flags, spin, energy_midpoints, threshold

imap_processing/ultra/l1b/ultra_l1b_extended.py

@@ -10,6 +10,7 @@ import xarray
 from numpy import ndarray
 from numpy.typing import NDArray
 
+from imap_processing.spice.geometry import cartesian_to_spherical
 from imap_processing.ultra.constants import UltraConstants
 from imap_processing.ultra.l1b.lookup_utils import (
     get_back_position,
@@ -437,20 +438,14 @@ def get_coincidence_positions(
     return etof, xc_array * 100
 
 
-def get_unit_vector(
+def get_de_velocity(
     front_position: tuple[NDArray, NDArray],
     back_position: tuple[NDArray, NDArray],
     d: np.ndarray,
     tof: np.ndarray,
-) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+) -> NDArray:
     """
-    Determine the particle velocity.
-
-    The equation is: velocity = ((xf - xb), (yf - yb), d).
-
-    Further description is available on pages 39 of
-    IMAP-Ultra Flight Software Specification document
-    (7523-9009_Rev_-.pdf).
+    Determine the direct event velocity.
 
     Parameters
     ----------
@@ -465,35 +460,30 @@ def get_unit_vector(
 
     Returns
     -------
-    vhat_x : np.array
-        Normalized component of the velocity vector in x direction.
-    vhat_y : np.array
-        Normalized component of the velocity vector in y direction.
-    vhat_z : np.array
-        Normalized component of the velocity vector in z direction.
+    velocities : np.ndarray
+        N x 3 array of velocity components (vx, vy, vz) in km/s.
     """
     if tof[tof < 0].any():
         logger.info("Negative tof values found.")
 
-    delta_x = front_position[0] - back_position[0]
-    delta_y = front_position[1] - back_position[1]
-
-    v_x = delta_x / tof
-    v_y = delta_y / tof
-    v_z = d / tof
+    # distances in .1 mm
+    delta_v = np.empty((len(d), 3), dtype=np.float32)
+    delta_v[:, 0] = (front_position[0] - back_position[0]) * 0.1
+    delta_v[:, 1] = (front_position[1] - back_position[1]) * 0.1
+    delta_v[:, 2] = d * 0.1
 
-    # Magnitude of the velocity vector
-    magnitude_v = np.sqrt(v_x**2 + v_y**2 + v_z**2)
+    # Convert from 0.1mm/0.1ns to km/s.
+    v_x = delta_v[:, 0] / tof * 1e3
+    v_y = delta_v[:, 1] / tof * 1e3
+    v_z = delta_v[:, 2] / tof * 1e3
 
-    vhat_x = -v_x / magnitude_v
-    vhat_y = -v_y / magnitude_v
-    vhat_z = -v_z / magnitude_v
+    v_x[tof < 0] = np.nan  # used as fillvals
+    v_y[tof < 0] = np.nan
+    v_z[tof < 0] = np.nan
 
-    vhat_x[tof < 0] = np.nan  # used as fillvals
-    vhat_y[tof < 0] = np.nan
-    vhat_z[tof < 0] = np.nan
+    velocities = np.vstack((v_x, v_y, v_z)).T
 
-    return vhat_x, vhat_y, vhat_z
+    return velocities
 
 
 def get_ssd_tof(de_dataset: xarray.Dataset, xf: np.ndarray) -> NDArray[np.float64]:
@@ -545,6 +535,37 @@ def get_ssd_tof(de_dataset: xarray.Dataset, xf: np.ndarray) -> NDArray[np.float6
     return np.asarray(tof, dtype=np.float64)
 
 
+def get_de_energy_kev(v: np.ndarray, species: np.ndarray) -> NDArray:
+    """
+    Calculate the direct event energy.
+
+    Parameters
+    ----------
+    v : np.ndarray
+        N x 3 array of velocity components (vx, vy, vz) in km/s.
+    species : np.ndarray
+        Species of the particle.
+
+    Returns
+    -------
+    energy : np.ndarray
+        Energy of the direct event in keV.
+    """
+    vv = v * 1e3  # convert km/s to m/s
+    # Compute the sum of squares.
+    v2 = np.sum(vv**2, axis=1)
+
+    index_hydrogen = np.where(species == "H")
+    energy = np.full_like(v2, np.nan)
+
+    # 1/2 mv^2 in Joules, convert to keV
+    energy[index_hydrogen] = (
+        0.5 * UltraConstants.MASS_H * v2[index_hydrogen] * UltraConstants.J_KEV
+    )
+
+    return energy
+
+
 def get_energy_pulse_height(
     stop_type: np.ndarray, energy: np.ndarray, xb: np.ndarray, yb: np.ndarray
 ) -> NDArray[np.float64]:
@@ -728,3 +749,33 @@ def determine_species(tof: np.ndarray, path_length: np.ndarray, type: str) -> ND
     ] = "H"
 
     return species_bin
+
+
+def get_de_az_el(v: NDArray) -> tuple[NDArray, NDArray]:
+    """
+    Compute azimuth (phi) angles and elevation (theta).
+
+    Parameters
+    ----------
+    v : np.ndarray
+        A NumPy array with shape (n, 3) where each
+        row represents a vector
+        with x, y, z-components.
+
+    Returns
+    -------
+    spherical_coords : np.ndarray
+        A NumPy array with shape (n, 3), where each row contains
+        the spherical coordinates (r, azimuth, elevation):
+
+        - azimuth : angle in the xy-plane
+          In radians:
+          output range=[0, 2*pi].
+        - elevation : angle from the xy-plane
+          In radians:
+          output range=[-pi/2, pi/2].
+    """
+    # Compute azimuth (phi) angles and elevation (theta)
+    spherical_coords = cartesian_to_spherical(v, degrees=False)
+
+    return spherical_coords[:, 1], spherical_coords[:, 2]

imap_processing/ultra/l1c/histogram.py

@@ -6,7 +6,9 @@ import xarray as xr
 from imap_processing.ultra.utils.ultra_l1_utils import create_dataset
 
 
-def calculate_histogram(histogram_dataset: xr.Dataset, name: str) -> xr.Dataset:
+def calculate_histogram(
+    histogram_dataset: xr.Dataset, name: str, data_version: str
+) -> xr.Dataset:
     """
     Create dictionary with defined datatype for Histogram Data.
 
@@ -16,6 +18,8 @@ def calculate_histogram(histogram_dataset: xr.Dataset, name: str) -> xr.Dataset:
         Dataset containing histogram data.
     name : str
         Name of dataset.
+    data_version : str
+        Version of the data.
 
     Returns
     -------
@@ -31,6 +35,6 @@ def calculate_histogram(histogram_dataset: xr.Dataset, name: str) -> xr.Dataset:
     histogram_dict["epoch"] = epoch
     histogram_dict["sid"] = np.zeros(len(epoch), dtype=np.uint8)
 
-    dataset = create_dataset(histogram_dict, name, "l1c")
+    dataset = create_dataset(histogram_dict, name, "l1c", data_version)
 
     return dataset