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

imap_processing/spacecraft/quaternions.py

@@ -0,0 +1,123 @@
+"""Spacecraft quaternion processing."""
+
+from pathlib import Path
+
+import numpy as np
+import xarray as xr
+
+from imap_processing.cdf.imap_cdf_manager import ImapCdfAttributes
+from imap_processing.spice.time import met_to_ttj2000ns
+from imap_processing.utils import packet_file_to_datasets
+
+
+def load_quaternion_packets(packet_file: Path | str) -> xr.Dataset:
+    """
+    Load the raw quaternion packets from the packet file.
+
+    Parameters
+    ----------
+    packet_file : Path
+        Path to the packet file containing the quaternions in apid 594.
+
+    Returns
+    -------
+    xarray.Dataset
+        Dataset containing the raw quaternion packets.
+    """
+    xtce_packet_definition = Path(__file__).parent / "packet_definitions/scid_x252.xml"
+    datasets_by_apid = packet_file_to_datasets(
+        packet_file=packet_file, xtce_packet_definition=xtce_packet_definition
+    )
+    return datasets_by_apid[0x252]
+
+
+def assemble_quaternions(ds: xr.Dataset) -> xr.Dataset:
+    """
+    Assemble quaternions from the l1a dataset.
+
+    The quaternions are stored in separate variables for each component (x, y, z, s)
+    and for each 10 Hz sample of the 1s packet. i.e. there are 4 * 10 = 40 variables
+    in the initial dataset that we want to turn into 4 variables with a continuous
+    10 Hz sampling period.
+
+    The output dataset will have a single dimension "epoch" that will be the time
+    associated with each of the 10 Hz samples. There are 4 data variables: "quat_x",
+    "quat_y", "quat_z", "quat_s".
+
+    Parameters
+    ----------
+    ds : xarray.Dataset
+        Input dataset containing the 10Hz quaternions from packet 0x252 (APID 594).
+
+    Returns
+    -------
+    xarray.Dataset
+        Output dataset with the quaternions assembled into 4 variables with a
+        continuous 10 Hz sampling period.
+    """
+    # Our time is only given for the first timestamp
+    # We then add to it 0.1 increments and ravel the array to associate a specific time
+    # with each of the 10 samples
+    time = (
+        ds["SCIENCEDATA1HZ_QUAT_10_HZ_TIME".lower()].values[:, np.newaxis]
+        + np.arange(0, 1, 0.1)
+    ).ravel()
+    output_ds = xr.Dataset(coords={"epoch": time})
+    base_name = "FSW_ACS_QUAT_10_HZ_BUFFERED".lower()
+    for quat_i, label in enumerate(["x", "y", "z", "s"]):
+        # 0, 1, 2, .. 9 // 10, 11, 12, .. 19 // 20, 21, 22, .. 29 // 30, 31, 32, .. 39
+        names = [f"{base_name}_{i + quat_i*10}" for i in range(10)]
+        quat = np.stack([ds[name] for name in names], axis=1).ravel()
+        output_ds[f"quat_{label}"] = ("epoch", quat)
+    return output_ds
+
+
+def process_quaternions(packet_file: Path | str) -> tuple[xr.Dataset, xr.Dataset]:
+    """
+    Generate l1a and l1b datasets from a packet file containing the raw quaternions.
+
+    This produces two CDF files: one for the l1a quaternions and one for the l1b
+    quaternions. The l1b quaternions are assembled into 4 variables: "quat_x",
+    "quat_y", "quat_z", "quat_s".
+
+    Parameters
+    ----------
+    packet_file : Path
+        Path to the packet file containing the quaternions in apid 594.
+
+    Returns
+    -------
+    xarray.Dataset
+        Dataset containing the l1a quaternions.
+    xarray.Dataset
+        Dataset containing the l1b quaternions.
+    """
+    l1a_ds = load_quaternion_packets(packet_file)
+
+    # Assemble the quaternions into the correct components
+    l1b_ds = assemble_quaternions(l1a_ds)
+
+    # Update dataset global attributes
+    attr_mgr = ImapCdfAttributes()
+    attr_mgr.add_instrument_global_attrs("spacecraft")
+    # TODO: Allow version to be passed in
+    attr_mgr.add_global_attribute("Data_version", 1)
+    attr_mgr.add_instrument_variable_attrs(instrument="spacecraft", level=None)
+
+    l1a_ds.attrs.update(
+        attr_mgr.get_global_attributes("imap_spacecraft_l1a_quaternions")
+    )
+    l1b_ds.attrs.update(
+        attr_mgr.get_global_attributes("imap_spacecraft_l1b_quaternions")
+    )
+
+    # Update the epoch attribute
+    l1b_ds["epoch"] = met_to_ttj2000ns(l1b_ds["epoch"])
+    # check_schema=False keeps DEPEND_0 = '' from being auto added
+    epoch_attrs = attr_mgr.get_variable_attributes("epoch", check_schema=False)
+    l1b_ds["epoch"].attrs.update(epoch_attrs)
+
+    for var in ["quat_x", "quat_y", "quat_z", "quat_s"]:
+        l1b_ds[var].attrs.update(attr_mgr.get_variable_attributes(var))
+
+    return l1a_ds, l1b_ds

imap_processing/spice/geometry.py

@@ -268,7 +268,7 @@ def frame_transform_az_el(
     spherical_coords_in = np.array(
         [np.ones_like(az_el[..., 0]), az_el[..., 0], az_el[..., 1]]
     ).T
-    from_frame_cartesian = spherical_to_cartesian(spherical_coords_in, degrees=degrees)
+    from_frame_cartesian = spherical_to_cartesian(spherical_coords_in)
     # Transform to to_frame
     to_frame_cartesian = frame_transform(et, from_frame_cartesian, from_frame, to_frame)
     # Convert to spherical and extract azimuth/elevation
@@ -425,14 +425,14 @@ def cartesian_to_spherical(
         - r : Distance of the point from the origin.
         - azimuth : angle in the xy-plane
           In degrees if degrees parameter is True (by default):
-          output range=[0, 360],
+          output range=[0, 360) degrees,
           otherwise in radians if degrees parameter is False:
-          output range=[0, 2*pi].
+          output range=[0, 2*pi) radians.
         - elevation : angle from the xy-plane
           In degrees if degrees parameter is True (by default):
-          output range=[0, 180],
+          output range=[-90, 90) degrees,
           otherwise in radians if degrees parameter is False:
-          output range=[-pi/2, pi/2].
+          output range=[-pi/2, pi/2) radians.
     """
     # Magnitude of the velocity vector
     magnitude_v = np.linalg.norm(v, axis=-1, keepdims=True)
@@ -457,9 +457,9 @@ def cartesian_to_spherical(
     return spherical_coords
 
 
-def spherical_to_cartesian(spherical_coords: NDArray, degrees: bool = False) -> NDArray:
+def spherical_to_cartesian(spherical_coords: NDArray) -> NDArray:
     """
-    Convert spherical coordinates to Cartesian coordinates.
+    Convert spherical coordinates (angles in degrees) to Cartesian coordinates.
 
     Parameters
     ----------
@@ -468,11 +468,8 @@ def spherical_to_cartesian(spherical_coords: NDArray, degrees: bool = False) ->
         the spherical coordinates (r, azimuth, elevation):
 
         - r : Distance of the point from the origin.
-        - azimuth : angle in the xy-plane in radians [0, 2*pi].
-        - elevation : angle from the xy-plane in radians [-pi/2, pi/2].
-    degrees : bool
-        Set to True if input azimuth and elevation angles are in degrees.
-        Defaults to False.
+        - azimuth : angle in the xy-plane in degrees. Range is [0, 360) degrees.
+        - elevation : angle from the xy-plane in degrees. Range is [-90, 90) degrees.
 
     Returns
     -------
@@ -483,9 +480,9 @@ def spherical_to_cartesian(spherical_coords: NDArray, degrees: bool = False) ->
     azimuth = spherical_coords[..., 1]
     elevation = spherical_coords[..., 2]
 
-    if degrees:
-        azimuth = np.radians(azimuth)
-        elevation = np.radians(elevation)
+    # Convert to radians for numpy trigonometric operations
+    azimuth = np.deg2rad(azimuth)
+    elevation = np.deg2rad(elevation)
 
     x = r * np.cos(elevation) * np.cos(azimuth)
     y = r * np.cos(elevation) * np.sin(azimuth)
@@ -496,7 +493,7 @@ def spherical_to_cartesian(spherical_coords: NDArray, degrees: bool = False) ->
     return cartesian_coords
 
 
-def cartesian_to_latitudinal(coords: NDArray, degrees: bool = False) -> NDArray:
+def cartesian_to_latitudinal(coords: NDArray, degrees: bool = True) -> NDArray:
     """
     Convert cartesian coordinates to latitudinal coordinates in radians.
 
@@ -511,7 +508,7 @@ def cartesian_to_latitudinal(coords: NDArray, degrees: bool = False) -> NDArray:
         with x, y, z-components.
     degrees : bool
         If True, the longitude and latitude coords are returned in degrees.
-        Defaults to False.
+        Defaults to True.
 
     Returns
     -------
@@ -532,7 +529,7 @@ def cartesian_to_latitudinal(coords: NDArray, degrees: bool = False) -> NDArray:
 
 def solar_longitude(
     et: Union[np.ndarray, float],
-    degrees: bool = False,
+    degrees: bool = True,
 ) -> Union[float, npt.NDArray]:
     """
     Compute the solar longitude of the Imap Spacecraft.
@@ -543,7 +540,7 @@ def solar_longitude(
         Ephemeris time(s) to at which to compute solar longitude.
     degrees : bool
         If True, the longitude is returned in degrees.
-        Defaults to False.
+        Defaults to True.
 
     Returns
     -------

imap_processing/spice/repoint.py

@@ -0,0 +1,120 @@
+"""Functions for retrieving repointing table data."""
+
+import logging
+import os
+from pathlib import Path
+from typing import Union
+
+import numpy as np
+import pandas as pd
+from numpy import typing as npt
+
+logger = logging.getLogger(__name__)
+
+
+def get_repoint_data() -> pd.DataFrame:
+    """
+    Read repointing file using environment variable and return as dataframe.
+
+    REPOINT_DATA_FILEPATH environment variable should point to a local
+    file where the repointing csv file is located.
+
+    Returns
+    -------
+    repoint_df : pd.DataFrame
+        The repointing csv loaded into a pandas dataframe. The dataframe will
+        contain the following columns:
+            - `repoint_start_time`: Starting MET time of each repoint maneuver.
+            - `repoint_end_time`: Ending MET time of each repoint maneuver.
+            - `repoint_id`: Unique ID number of each repoint maneuver.
+    """
+    repoint_data_filepath = os.getenv("REPOINT_DATA_FILEPATH")
+    if repoint_data_filepath is not None:
+        path_to_spin_file = Path(repoint_data_filepath)
+    else:
+        # Handle the case where the environment variable is not set
+        raise ValueError("REPOINT_DATA_FILEPATH environment variable is not set.")
+
+    logger.info(f"Reading repointing data from {path_to_spin_file}")
+    repoint_df = pd.read_csv(path_to_spin_file, comment="#")
+
+    return repoint_df
+
+
+def interpolate_repoint_data(
+    query_met_times: Union[float, npt.NDArray],
+) -> pd.DataFrame:
+    """
+    Interpolate repointing data to the queried MET times.
+
+    In addition to the repoint start, end, and id values that come directly from
+    the universal repointing table, a column is added to the output dataframe
+    which indicates whether each query met time occurs during a repoint maneuver
+    i.e. between the repoint start and end times of a row in the repointing
+    table.
+
+    Query times that are more than 24-hours after that last repoint start time
+    in the repoint table will cause an error to be raised. The assumption here
+    is that we shouldn't be processing data that occurs that close to the next
+    expected repoint start time before getting an updated repoint table.
+
+    Parameters
+    ----------
+    query_met_times : float or np.ndarray
+        Query times in Mission Elapsed Time (MET).
+
+    Returns
+    -------
+    repoint_df : pandas.DataFrame
+        Repoint table data interpolated such that there is one row
+        for each of the queried MET times. Output columns are:
+            - `repoint_start_time`
+            - `repoint_end_time`
+            - `repoint_id`
+            - `repoint_in_progress`
+
+    Raises
+    ------
+    ValueError : If any of the query_met_times are before the first repoint
+    start time or after the last repoint start time plus 24-hours.
+    """
+    repoint_df = get_repoint_data()
+
+    # Ensure query_met_times is an array
+    query_met_times = np.atleast_1d(query_met_times)
+
+    # Make sure no query times are before the first repoint in the dataframe.
+    repoint_df_start_time = repoint_df["repoint_start_time"].values[0]
+    if np.any(query_met_times < repoint_df_start_time):
+        bad_times = query_met_times[query_met_times < repoint_df_start_time]
+        raise ValueError(
+            f"{bad_times.size} query times are before the first repoint start "
+            f" time in the repoint table. {bad_times=}, {repoint_df_start_time=}"
+        )
+    # Make sure that no query times are after the valid range of the dataframe.
+    # We approximate the end time of the table by adding 24 hours to the last
+    # known repoint start time.
+    repoint_df_end_time = repoint_df["repoint_start_time"].values[-1] + 24 * 60 * 60
+    if np.any(query_met_times >= repoint_df_end_time):
+        bad_times = query_met_times[query_met_times >= repoint_df_end_time]
+        raise ValueError(
+            f"{bad_times.size} query times are after the valid time of the "
+            f"pointing table. The valid end time is 24-hours after the last "
+            f"repoint_start_time. {bad_times=}, {repoint_df_end_time=}"
+        )
+
+    # Find the row index for each queried MET time such that:
+    # repoint_start_time[i] <= MET < repoint_start_time[i+1]
+    row_indices = (
+        np.searchsorted(repoint_df["repoint_start_time"], query_met_times, side="right")
+        - 1
+    )
+    out_df = repoint_df.iloc[row_indices]
+
+    # Add a column indicating if the query time is during a repoint or not.
+    # The table already has the correct row for each query time, so we
+    # only need to check if the query time is less than the repoint end time to
+    # get the same result as `repoint_start_time <= query_met_times < repoint_end_time`.
+    out_df["repoint_in_progress"] = query_met_times < out_df["repoint_end_time"].values
+
+    return out_df

imap_processing/swapi/l1/swapi_l1.py

@@ -509,6 +509,10 @@ def process_swapi_science(
     # since we are not processing in real-time, the ground processing
     # algorithm should use the closest timestamp HK packet to fill in
     # the data quality for the SCI data per SWAPI team.
+
+    # Drop duplicate epoch values in HK data. Otherwise, the nearest
+    # method will not work as expected because .sel requires unique values.
+    hk_dataset = hk_dataset.drop_duplicates("epoch")
     good_sweep_times = good_sweep_sci["epoch"].data
     good_sweep_hk_data = hk_dataset.sel({"epoch": good_sweep_times}, method="nearest")
 

imap_processing/swapi/l2/swapi_l2.py

@@ -62,7 +62,6 @@ def swapi_l2(l1_dataset: xr.Dataset, data_version: str) -> xr.Dataset:
     # Update L2 specific attributes
     l2_dataset.attrs["Data_version"] = data_version
     l2_global_attrs = cdf_manager.get_global_attributes("imap_swapi_l2_sci")
-    l2_dataset.attrs["Data_level"] = l2_global_attrs["Data_level"]
     l2_dataset.attrs["Data_type"] = l2_global_attrs["Data_type"]
     l2_dataset.attrs["Logical_source"] = l2_global_attrs["Logical_source"]
     l2_dataset.attrs["Logical_source_description"] = l2_global_attrs[

imap_processing/swe/l1a/swe_l1a.py

@@ -5,6 +5,7 @@ import logging
 import xarray as xr
 
 from imap_processing import imap_module_directory
+from imap_processing.cdf.imap_cdf_manager import ImapCdfAttributes
 from imap_processing.swe.l1a.swe_science import swe_science
 from imap_processing.swe.utils.swe_utils import (
     SWEAPID,
@@ -42,12 +43,50 @@ def swe_l1a(packet_file: str, data_version: str) -> xr.Dataset:
         packet_file, xtce_document, use_derived_value=False
     )
 
-    if SWEAPID.SWE_SCIENCE not in datasets_by_apid:
-        logger.info("No science data found in packet file.")
-        return []
-    # TODO: figure out how to handle non-science data
-    return [
-        swe_science(
-            l0_dataset=datasets_by_apid[SWEAPID.SWE_SCIENCE], data_version=data_version
+    processed_data = []
+
+    if SWEAPID.SWE_SCIENCE in datasets_by_apid:
+        logger.info("Processing SWE science data.")
+        processed_data.append(
+            swe_science(
+                l0_dataset=datasets_by_apid[SWEAPID.SWE_SCIENCE],
+                data_version=data_version,
+            )
+        )
+
+    # Process non-science data
+    # Define minimal CDF attrs for the non science dataset
+    imap_attrs = ImapCdfAttributes()
+    imap_attrs.add_instrument_global_attrs("swe")
+    imap_attrs.add_global_attribute("Data_version", data_version)
+    imap_attrs.add_instrument_variable_attrs("swe", "l1a")
+    non_science_attrs = imap_attrs.get_variable_attributes("non_science_attrs")
+    epoch_attrs = imap_attrs.get_variable_attributes("epoch", check_schema=False)
+
+    if SWEAPID.SWE_APP_HK in datasets_by_apid:
+        logger.info("Processing SWE housekeeping data.")
+        hk_ds = datasets_by_apid[SWEAPID.SWE_APP_HK]
+        hk_ds.attrs.update(imap_attrs.get_global_attributes("imap_swe_l1a_hk"))
+        hk_ds["epoch"].attrs.update(epoch_attrs)
+        # Add attrs to HK data variables
+        for var_name in hk_ds.data_vars:
+            hk_ds[var_name].attrs.update(non_science_attrs)
+        processed_data.append(hk_ds)
+
+    if SWEAPID.SWE_CEM_RAW in datasets_by_apid:
+        logger.info("Processing SWE CEM raw data.")
+        cem_raw_ds = datasets_by_apid[SWEAPID.SWE_CEM_RAW]
+        cem_raw_ds.attrs.update(
+            imap_attrs.get_global_attributes("imap_swe_l1a_cem-raw")
         )
-    ]
+        cem_raw_ds["epoch"].attrs.update(epoch_attrs)
+
+        # Add attrs to CEM raw data variables
+        for var_name in cem_raw_ds.data_vars:
+            cem_raw_ds[var_name].attrs.update(non_science_attrs)
+        processed_data.append(cem_raw_ds)
+
+    if len(processed_data) == 0:
+        logger.info("Data contains unknown APID.")
+
+    return processed_data

imap_processing/swe/l1a/swe_science.py

@@ -6,6 +6,7 @@ import numpy as np
 import xarray as xr
 
 from imap_processing.cdf.imap_cdf_manager import ImapCdfAttributes
+from imap_processing.swe.utils import swe_constants
 from imap_processing.swe.utils.swe_utils import SWEAPID
 
 logger = logging.getLogger(__name__)
@@ -119,7 +120,9 @@ def swe_science(l0_dataset: xr.Dataset, data_version: str) -> xr.Dataset:
     # 4. Reshape the data to 180 x 7
     raw_science_array = np.array(
         [
-            np.frombuffer(binary_string, dtype=np.uint8).reshape(180, 7)
+            np.frombuffer(binary_string, dtype=np.uint8).reshape(
+                180, swe_constants.N_CEMS
+            )
             for binary_string in l0_dataset["science_data"].values
         ]
     )
@@ -157,7 +160,7 @@ def swe_science(l0_dataset: xr.Dataset, data_version: str) -> xr.Dataset:
     )
 
     cem_id = xr.DataArray(
-        np.arange(7),
+        np.arange(swe_constants.N_CEMS),
         name="cem_id",
         dims=["cem_id"],
         attrs=cdf_attrs.get_variable_attributes("cem_id"),