imap-processing 0.6.0__py3-none-any.whl

imap_processing/glows/utils/constants.py

@@ -0,0 +1,105 @@
+"""Module for constants and useful shared classes used in GLOWS."""
+
+from dataclasses import dataclass
+
+import numpy as np
+
+
+@dataclass(frozen=True)
+class TimeTuple:
+    """
+    Spacecraft clock time, a float divided into seconds and subseconds.
+
+    Attributes
+    ----------
+    seconds: int
+        Seconds of clock, integer
+    subseconds: int
+        Subseconds of clock, defined as 1/SUB_SECOND_LIMIT th of a second. Will
+        always be less than SUB_SECOND_LIMIT. If the class is initialized with a
+        subsecond value above SUB_SECOND_LIMIT, the subseconds above the limit will be
+        converted to seconds.
+    """
+
+    seconds: int
+    subseconds: int
+
+    def __post_init__(self) -> None:
+        """Add any subseconds over the limit into the seconds field."""
+        final_seconds = self.seconds
+        final_subseconds = self.subseconds
+        if final_subseconds >= GlowsConstants.SUBSECOND_LIMIT:
+            final_seconds += self.subseconds // GlowsConstants.SUBSECOND_LIMIT
+            final_subseconds = self.subseconds % GlowsConstants.SUBSECOND_LIMIT
+
+        object.__setattr__(self, "seconds", final_seconds)
+        object.__setattr__(self, "subseconds", final_subseconds)
+
+    def to_seconds(self) -> np.single:
+        """
+        Convert the TimeTuple to seconds.
+
+        Returns
+        -------
+        np.single
+            TimeTuple in seconds.
+        """
+        return np.single(
+            self.seconds + self.subseconds / GlowsConstants.SUBSECOND_LIMIT
+        )
+
+
+@dataclass(frozen=True)
+class GlowsConstants:
+    """
+    Constants for GLOWS which can be used across different levels or classes.
+
+    Attributes
+    ----------
+    SUBSECOND_LIMIT: int
+        subsecond limit for GLOWS clock (and consequently also onboard-interpolated
+        IMAP clock)
+    SCAN_CIRCLE_ANGULAR_RADIUS: float
+        angular radius of IMAP/GLOWS scanning circle [deg]
+    """
+
+    SUBSECOND_LIMIT: int = 2_000_000
+    SCAN_CIRCLE_ANGULAR_RADIUS: float = 75.0
+
+
+@dataclass
+class DirectEvent:
+    """
+    DirectEvent() class for IMAP/GLOWS.
+
+    Authors: Marek Strumik, maro@cbk.waw.pl, Maxine Hartnett
+
+    Attributes
+    ----------
+    timestamp: TimeTuple
+        Timestamp for the direct event
+    impulse_length: int
+        Direct event data
+    multi_event: bool
+        If the event was a multi event. Defaults to False.
+    """
+
+    timestamp: TimeTuple
+    impulse_length: int
+    multi_event: bool = False
+
+    def to_list(self) -> list:
+        """
+        Convert object to list [seconds, subseconds, impulse length, multievent].
+
+        Returns
+        -------
+        list
+            Converted object to list.
+        """
+        return [
+            self.timestamp.seconds,
+            self.timestamp.subseconds,
+            self.impulse_length,
+            self.multi_event,
+        ]

imap_processing/hi/__init__.py

@@ -0,0 +1 @@
+__version__ = "001"

imap_processing/hi/l0/decom_hi.py

@@ -0,0 +1,24 @@
+"""Decom IMAP-Hi data."""
+
+from imap_processing import decom, imap_module_directory
+
+
+def decom_packets(packet_file_path: str) -> list:
+    """
+    Decom IMAP-Hi data using its packet definition.
+
+    Parameters
+    ----------
+    packet_file_path : str
+        File path to the packet.
+
+    Returns
+    -------
+    list
+        Decompressed file packets.
+    """
+    packet_def_file = (
+        imap_module_directory / "hi/packet_definitions/hi_packet_definition.xml"
+    )
+    decom_file_packets: list = decom.decom_packets(packet_file_path, packet_def_file)
+    return decom_file_packets

imap_processing/hi/l1a/hi_l1a.py

@@ -0,0 +1,73 @@
+"""IMAP-HI L1A processing module."""
+
+import logging
+from pathlib import Path
+from typing import Union
+
+import xarray as xr
+
+from imap_processing import imap_module_directory
+from imap_processing.hi.l1a.histogram import create_dataset as hist_create_dataset
+from imap_processing.hi.l1a.housekeeping import process_housekeeping
+from imap_processing.hi.l1a.science_direct_event import science_direct_event
+from imap_processing.hi.utils import HIAPID
+from imap_processing.utils import packet_file_to_datasets
+
+logger = logging.getLogger(__name__)
+
+
+def hi_l1a(packet_file_path: Union[str, Path], data_version: str) -> list[xr.Dataset]:
+    """
+    Will process IMAP raw data to l1a.
+
+    Parameters
+    ----------
+    packet_file_path : str
+        Data packet file path.
+    data_version : str
+        Version of the data product being created.
+
+    Returns
+    -------
+    processed_data : list[xarray.Dataset]
+        List of processed xarray dataset.
+    """
+    packet_def_file = (
+        imap_module_directory / "hi/packet_definitions/hi_packet_definition.xml"
+    )
+    datasets_by_apid = packet_file_to_datasets(
+        packet_file=packet_file_path, xtce_packet_definition=packet_def_file
+    )
+
+    # Process science to l1a.
+    processed_data = []
+    for apid in datasets_by_apid:
+        if apid == HIAPID.H45_SCI_CNT:
+            logger.info(
+                "Processing histogram data for [%s] packets", HIAPID.H45_SCI_CNT.name
+            )
+            data = hist_create_dataset(datasets_by_apid[apid])
+        elif apid == HIAPID.H45_SCI_DE:
+            logger.info(
+                "Processing direct event data for [%s] packets", HIAPID.H45_SCI_DE.name
+            )
+
+            data = science_direct_event(datasets_by_apid[apid])
+        elif apid == HIAPID.H45_APP_NHK:
+            logger.info(
+                "Processing housekeeping data for [%s] packets", HIAPID.H45_APP_NHK.name
+            )
+            data = process_housekeeping(datasets_by_apid[apid])
+        else:
+            raise RuntimeError(f"Encountered unexpected APID [{apid}]")
+
+        # TODO: revisit this
+        data.attrs["Data_version"] = data_version
+
+        # set the sensor string in Logical_source
+        sensor_str = HIAPID(apid).sensor
+        data.attrs["Logical_source"] = data.attrs["Logical_source"].format(
+            sensor=sensor_str
+        )
+        processed_data.append(data)
+    return processed_data

imap_processing/hi/l1a/histogram.py

@@ -0,0 +1,142 @@
+"""Unpack IMAP-Hi histogram data."""
+
+import numpy as np
+import xarray as xr
+
+from imap_processing.cdf.imap_cdf_manager import ImapCdfAttributes
+
+# define the names of the 24 counter arrays
+# contained in the histogram packet
+QUALIFIED_COUNTERS = (
+    "qual_ab",
+    "qual_c1c2",
+    "qual_ac1",
+    "qual_bc1",
+    "qual_abc1",
+    "qual_ac1c2",
+    "qual_bc1c2",
+    "qual_abc1c2",
+)
+LONG_COUNTERS = (
+    "long_a",
+    "long_b",
+    "long_c",
+    "long_ab",
+    "long_c1c2",
+    "long_ac1",
+    "long_bc1",
+    "long_abc1",
+    "long_ac1c2",
+    "long_bc1c2",
+    "long_abc1c2",
+)
+TOTAL_COUNTERS = ("total_a", "total_b", "total_c", "fee_de_sent", "fee_de_recd")
+
+
+def create_dataset(input_ds: xr.Dataset) -> xr.Dataset:
+    """
+    Create dataset for a number of Hi Histogram packets.
+
+    Parameters
+    ----------
+    input_ds : xarray.Dataset
+        Dataset of packets.
+
+    Returns
+    -------
+    dataset : xarray.Dataset
+        Dataset with all metadata field data in xr.DataArray.
+    """
+    dataset = allocate_histogram_dataset(len(input_ds.epoch))
+
+    # TODO: Move into the allocate dataset function?
+    dataset["epoch"].data[:] = input_ds["epoch"].data
+    dataset["ccsds_met"].data = input_ds["ccsds_met"].data
+    dataset["esa_stepping_num"].data = input_ds["esa_step"].data
+
+    # unpack the packets data into the Dataset
+    # (npackets, 24 * 90 * 12)
+    # TODO: Look into avoiding the for-loops below
+    #       It seems like we could try to reshape the arrays and do some numpy
+    #       broadcasting rather than for-loops directly here
+    for i_epoch, counters_binary_data in enumerate(input_ds["counters"].data):
+        # unpack 24 arrays of 90 12-bit unsigned integers
+        counter_ints = [
+            int(counters_binary_data[i * 12 : (i + 1) * 12], 2) for i in range(90 * 24)
+        ]
+        # populate the dataset with the unpacked integers
+        for i_counter, counter in enumerate(
+            (*QUALIFIED_COUNTERS, *LONG_COUNTERS, *TOTAL_COUNTERS)
+        ):
+            dataset[counter][i_epoch] = counter_ints[
+                i_counter * 90 : (i_counter + 1) * 90
+            ]
+
+    return dataset
+
+
+def allocate_histogram_dataset(num_packets: int) -> xr.Dataset:
+    """
+    Allocate empty xarray.Dataset for specified number of Hi Histogram packets.
+
+    Parameters
+    ----------
+    num_packets : int
+        The number of Hi Histogram packets to allocate space for
+        in the xarray.Dataset.
+
+    Returns
+    -------
+    dataset : xarray.Dataset
+        Empty xarray.Dataset ready to be filled with packet data.
+    """
+    attr_mgr = ImapCdfAttributes()
+    attr_mgr.add_instrument_global_attrs(instrument="hi")
+    attr_mgr.load_variable_attributes("imap_hi_variable_attrs.yaml")
+    # preallocate the xr.DataArrays for all CDF attributes based on number of packets
+    coords = dict()
+    coords["epoch"] = xr.DataArray(
+        np.empty(num_packets, dtype="datetime64[ns]"),
+        name="epoch",
+        dims=["epoch"],
+        attrs=attr_mgr.get_variable_attributes("epoch"),
+    )
+    # Histogram data is binned in 90, 4-degree bins
+    coords["angle"] = xr.DataArray(
+        np.arange(2, 360, 4),
+        name="angle",
+        dims=["angle"],
+        attrs=attr_mgr.get_variable_attributes("hi_hist_angle"),
+    )
+    data_vars = dict()
+    data_vars["ccsds_met"] = xr.DataArray(
+        np.empty(num_packets, dtype=np.uint32),
+        dims=["epoch"],
+        attrs=attr_mgr.get_variable_attributes("hi_hist_ccsds_met"),
+    )
+    data_vars["esa_stepping_num"] = xr.DataArray(
+        np.empty(num_packets, dtype=np.uint8),
+        dims=["epoch"],
+        attrs=attr_mgr.get_variable_attributes("hi_hist_esa_stepping_num"),
+    )
+
+    # Allocate xarray.DataArray objects for the 24 90-element histogram counters
+    default_counter_attrs = attr_mgr.get_variable_attributes("hi_hist_counters")
+    for counter_name in (*QUALIFIED_COUNTERS, *LONG_COUNTERS, *TOTAL_COUNTERS):
+        # Inject counter name into generic counter attributes
+        counter_attrs = default_counter_attrs.copy()
+        for key, val in counter_attrs.items():
+            if isinstance(val, str) and "{counter_name}" in val:
+                counter_attrs[key] = val.format(counter_name=counter_name)
+        data_vars[counter_name] = xr.DataArray(
+            data=np.empty((num_packets, len(coords["angle"])), np.uint16),
+            dims=["epoch", "angle"],
+            attrs=counter_attrs,
+        )
+
+    dataset = xr.Dataset(
+        data_vars=data_vars,
+        coords=coords,
+        attrs=attr_mgr.get_global_attributes("imap_hi_l1a_hist_attrs"),
+    )
+    return dataset

imap_processing/hi/l1a/housekeeping.py

@@ -0,0 +1,27 @@
+"""Unpack IMAP-Hi housekeeping data."""
+
+import xarray as xr
+
+from imap_processing.cdf.imap_cdf_manager import ImapCdfAttributes
+
+
+def process_housekeeping(dataset: xr.Dataset) -> xr.Dataset:
+    """
+    Create dataset for each metadata field.
+
+    Parameters
+    ----------
+    dataset : xarray.Dataset
+        Packet input dataset.
+
+    Returns
+    -------
+    dataset : xarray.Dataset
+        Dataset with all metadata field data in xr.DataArray.
+    """
+    # Load the CDF attributes
+    attr_mgr = ImapCdfAttributes()
+    attr_mgr.add_instrument_global_attrs("hi")
+    # Add datalevel attrs
+    dataset.attrs.update(attr_mgr.get_global_attributes("imap_hi_l1a_hk_attrs"))
+    return dataset