imap-processing 0.6.0__py3-none-any.whl

imap_processing/codice/utils.py

@@ -0,0 +1,95 @@
+"""
+Various classes and functions used throughout CoDICE processing.
+
+This module contains utility classes and functions that are used by various
+other CoDICE processing modules.
+"""
+
+from enum import IntEnum
+
+import space_packet_parser
+
+
+class CODICEAPID(IntEnum):
+    """Create ENUM for CoDICE APIDs."""
+
+    COD_AUT = 1120
+    COD_BOOT_HK = 1121
+    COD_BOOT_MEMDMP = 1122
+    COD_COUNTS_COMMON = 1135
+    COD_NHK = 1136
+    COD_EVTMSG = 1137
+    COD_MEMDMP = 1138
+    COD_SHK = 1139
+    COD_RTS = 1141
+    COD_DIAG_CDHFPGA = 1144
+    COD_DIAG_SNSR_HV = 1145
+    COD_DIAG_OPTC_HV = 1146
+    COD_DIAG_APDFPGA = 1147
+    COD_DIAG_SSDFPGA = 1148
+    COD_DIAG_FSW = 1149
+    COD_DIAG_SYSVARS = 1150
+    COD_LO_IAL = 1152
+    COD_LO_PHA = 1153
+    COD_LO_SW_PRIORITY_COUNTS = 1155
+    COD_LO_SW_SPECIES_COUNTS = 1156
+    COD_LO_NSW_SPECIES_COUNTS = 1157
+    COD_LO_SW_ANGULAR_COUNTS = 1158
+    COD_LO_NSW_ANGULAR_COUNTS = 1159
+    COD_LO_NSW_PRIORITY_COUNTS = 1160
+    COD_LO_INST_COUNTS_AGGREGATED = 1161
+    COD_LO_INST_COUNTS_SINGLES = 1162
+    COD_HI_IAL = 1168
+    COD_HI_PHA = 1169
+    COD_HI_INST_COUNTS_AGGREGATED = 1170
+    COD_HI_INST_COUNTS_SINGLES = 1171
+    COD_HI_OMNI_SPECIES_COUNTS = 1172
+    COD_HI_SECT_SPECIES_COUNTS = 1173
+    COD_CSTOL_CONFIG = 2457
+
+
+class CoDICECompression(IntEnum):
+    """Create ENUM for CoDICE compression algorithms."""
+
+    NO_COMPRESSION = 0
+    LOSSY_A = 1
+    LOSSY_B = 2
+    LOSSLESS = 3
+    LOSSY_A_LOSSLESS = 4
+    LOSSY_B_LOSSLESS = 5
+
+
+def add_metadata_to_array(packet: space_packet_parser, metadata_arrays: dict) -> dict:
+    """
+    Add metadata to the metadata_arrays.
+
+    Parameters
+    ----------
+    packet : space_packet_parser.parser.Packet
+        CODICE data packet.
+    metadata_arrays : dict
+        Metadata arrays.
+
+    Returns
+    -------
+    metadata_arrays : dict
+        Updated metadata arrays with values.
+    """
+    ignore_list = [
+        "SPARE_1",
+        "SPARE_2",
+        "SPARE_3",
+        "SPARE_4",
+        "SPARE_5",
+        "SPARE_6",
+        "CHECKSUM",
+    ]
+
+    for key, value in packet.header.items():
+        metadata_arrays.setdefault(key, []).append(value.raw_value)
+
+    for key, value in packet.data.items():
+        if key not in ignore_list:
+            metadata_arrays.setdefault(key, []).append(value.raw_value)
+
+    return metadata_arrays

imap_processing/decom.py

@@ -0,0 +1,40 @@
+"""
+Decommutate a packet file using a given packet definition.
+
+This module contains a common function that can be used by multiple instruments
+to decommutate CCSDS packet data using a given XTCE packet definition.
+"""
+
+from pathlib import Path
+from typing import Union
+
+from space_packet_parser import parser, xtcedef
+
+
+def decom_packets(
+    packet_file: Union[str, Path], xtce_packet_definition: Union[str, Path]
+) -> list:
+    """
+    Unpack CCSDS data packet.
+
+    In this function, we unpack and return data
+    as it is. Data modification will not be done at this step.
+
+    Parameters
+    ----------
+    packet_file : str
+        Path to data packet path with filename.
+    xtce_packet_definition : str
+        Path to XTCE file with filename.
+
+    Returns
+    -------
+    list
+        List of all the unpacked data.
+    """
+    packet_definition = xtcedef.XtcePacketDefinition(xtce_packet_definition)
+    packet_parser = parser.PacketParser(packet_definition)
+
+    with open(packet_file, "rb") as binary_data:
+        packet_generator = packet_parser.generator(binary_data)
+        return list(packet_generator)

imap_processing/glows/__init__.py

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

imap_processing/glows/ancillary/l1b_conversion_table_v001.json

@@ -0,0 +1,42 @@
+{
+    "description": "Table for conversion/decoding ancillary parameters collected onboard by IMAP/GLOWS",
+    "version": "v001",
+    "date_of_creation_yyyymmdd": "20230527",
+    "filter_temperature": {
+        "min": -30.0,
+        "max": 80.0,
+        "n_bits": 8,
+        "p01": 0.0,
+        "p02": 0.0,
+        "p03": 0.0,
+        "p04": 0.0
+    },
+    "hv_voltage": {
+        "min": 0.0,
+        "max": 3500.0,
+        "n_bits": 12,
+        "p01": 0.0,
+        "p02": 0.0,
+        "p03": 0.0,
+        "p04": 0.0
+    },
+    "spin_period": {
+        "min": 0.0,
+        "max": 20.9712,
+        "n_bits": 16
+    },
+    "spin_phase": {
+        "min": 0.0,
+        "max": 360.0,
+        "n_bits": 16
+    },
+    "pulse_length": {
+        "min": 0.0,
+        "max": 255.0,
+        "n_bits": 8,
+        "p01": 0.0,
+        "p02": 0.0,
+        "p03": 0.0,
+        "p04": 0.0
+    }
+}

imap_processing/glows/l0/decom_glows.py

@@ -0,0 +1,91 @@
+"""Decommutate GLOWS CCSDS packets using GLOWS packet definitions."""
+
+from enum import Enum
+from pathlib import Path
+
+from space_packet_parser import parser, xtcedef
+
+from imap_processing import imap_module_directory
+from imap_processing.ccsds.ccsds_data import CcsdsData
+from imap_processing.glows import __version__
+from imap_processing.glows.l0.glows_l0_data import DirectEventL0, HistogramL0
+
+
+class GlowsParams(Enum):
+    """
+    Enum class for Glows packet data.
+
+    Attributes
+    ----------
+    HIST_APID : int
+        Histogram packet APID
+    DE_APID : int
+        Direct event APID
+    """
+
+    HIST_APID = 1480
+    DE_APID = 1481
+
+
+def decom_packets(
+    packet_file_path: Path,
+) -> tuple[list[HistogramL0], list[DirectEventL0]]:
+    """
+    Decom GLOWS data packets using GLOWS packet definition.
+
+    Parameters
+    ----------
+    packet_file_path : str
+        Path to data packet path with filename.
+
+    Returns
+    -------
+    data : tuple[list[HistogramL0], list[DirectEventL0]]
+        A tuple with two pieces: one list of the GLOWS histogram data, in GlowsHistL0
+        instances, and one list of the GLOWS direct event data, in GlowsDeL0 instance.
+    """
+    # Define paths
+    xtce_document = Path(
+        f"{imap_module_directory}/glows/packet_definitions/GLX_COMBINED.xml"
+    )
+
+    packet_definition = xtcedef.XtcePacketDefinition(xtce_document)
+    glows_parser = parser.PacketParser(packet_definition)
+
+    histdata = []
+    dedata = []
+
+    filename = packet_file_path.name
+
+    with open(packet_file_path, "rb") as binary_data:
+        glows_packets = glows_parser.generator(binary_data)
+
+        for packet in glows_packets:
+            apid = packet.header["PKT_APID"].derived_value
+            # Do something with the packet data
+            if apid == GlowsParams.HIST_APID.value:
+                values = [
+                    item.derived_value
+                    if item.derived_value is not None
+                    else item.raw_value
+                    for item in packet.data.values()
+                ]
+                hist_l0 = HistogramL0(
+                    __version__, filename, CcsdsData(packet.header), *values
+                )
+                histdata.append(hist_l0)
+
+            if apid == GlowsParams.DE_APID.value:
+                values = [
+                    item.derived_value
+                    if item.derived_value is not None
+                    else item.raw_value
+                    for item in packet.data.values()
+                ]
+
+                de_l0 = DirectEventL0(
+                    __version__, filename, CcsdsData(packet.header), *values
+                )
+                dedata.append(de_l0)
+
+        return histdata, dedata

imap_processing/glows/l0/glows_l0_data.py

@@ -0,0 +1,194 @@
+"""Contains data classes to support GLOWS L0 processing."""
+
+from dataclasses import dataclass, field
+
+from imap_processing.ccsds.ccsds_data import CcsdsData
+
+
+@dataclass
+class GlowsL0:
+    """
+    Data structure for common values across histogram and direct events data.
+
+    Attributes
+    ----------
+    ground_sw_version : str
+        Ground software version
+    packet_file_name : str
+        File name of the source packet
+    ccsds_header : CcsdsData
+        CCSDS header data
+    """
+
+    ground_sw_version: str
+    packet_file_name: str
+    ccsds_header: CcsdsData
+
+
+@dataclass
+class HistogramL0(GlowsL0):
+    """
+    Data structure for storing GLOWS histogram packet data.
+
+    Attributes
+    ----------
+    MET : int
+        CCSDS Packet Time Stamp (coarse time)
+    STARTID : int
+        Histogram Start ID
+    ENDID : int
+        Histogram End ID
+    FLAGS : int
+        Histogram flags
+    SWVER : int
+        Version of SW used for generation
+    SEC : int
+        Block start time (IMAP), seconds
+    SUBSEC : int
+        Block start time (IMAP), subseconds
+    OFFSETSEC : int
+        Block end time (IMAP), seconds
+    OFFSETSUBSEC : int
+        Block end time (IMAP), subseconds
+    GLXSEC : int
+        Block start time (GLOWS), seconds
+    GLXSUBSEC : int
+        Block start time (GLOWS), Subseconds
+    GLXOFFSEC : int
+        Block end time (GLOWS), seconds
+    GLXOFFSUBSEC : int
+        Block end time (GLOWS), subseconds
+    SPINS : int
+        Number of spins
+    NBINS : int
+        Number of bins
+    TEMPAVG : int
+        Mean filter temperature
+    TEMPVAR : int
+        Variance of filter temperature
+    HVAVG : int
+        Mean CEM voltage
+    HVVAR : int
+        Variance of CEM voltage
+    SPAVG : int
+        Mean spin period
+    SPVAR : int
+        Variance of spin period
+    ELAVG : int
+        Mean length of event impulse
+    ELVAR : int
+        Variance of event-impulse length
+    EVENTS : int
+        Number of events
+    HISTOGRAM_DATA : bytes
+        Raw binary format histogram data
+    ground_sw_version : str
+        Ground software version
+    packet_file_name : str
+        File name of the source packet
+    ccsds_header : CcsdsData
+        CCSDS header data
+    """
+
+    MET: int
+    STARTID: int
+    ENDID: int
+    FLAGS: int
+    SWVER: int
+    SEC: int
+    SUBSEC: int
+    OFFSETSEC: int
+    OFFSETSUBSEC: int
+    GLXSEC: int
+    GLXSUBSEC: int
+    GLXOFFSEC: int
+    GLXOFFSUBSEC: int
+    SPINS: int
+    NBINS: int
+    TEMPAVG: int
+    TEMPVAR: int
+    HVAVG: int
+    HVVAR: int
+    SPAVG: int
+    SPVAR: int
+    ELAVG: int
+    ELVAR: int
+    EVENTS: int
+    HISTOGRAM_DATA: bytearray
+
+    def __post_init__(self) -> None:
+        """Convert HISTOGRAM_DATA attribute from string to bytearray if needed."""
+        if isinstance(self.HISTOGRAM_DATA, str):
+            # Convert string output from space_packet_parser to bytearray
+            self.HISTOGRAM_DATA = bytearray(
+                int(self.HISTOGRAM_DATA, 2).to_bytes(
+                    len(self.HISTOGRAM_DATA) // 8, "big"
+                )
+            )
+
+
+@dataclass
+class DirectEventL0(GlowsL0):
+    """
+    Data structure for storing GLOWS direct event packet data.
+
+    Attributes
+    ----------
+    MET : int
+        CCSDS Packet Time Stamp (coarse time)
+    SEC : int
+        Data IMAP timestamp, seconds counter.
+    LEN : int
+        Number of packets in data set.
+    SEQ : int
+        Packet sequence in data set.
+    DE_DATA : bytearray
+        Raw direct event data (compressed)
+    ground_sw_version : str
+        Ground software version
+    packet_file_name : str
+        File name of the source packet
+    ccsds_header : CcsdsData
+        CCSDS header data
+
+    Methods
+    -------
+    within_same_sequence(other)
+    """
+
+    MET: int
+    SEC: int
+    LEN: int
+    SEQ: int
+    DE_DATA: bytearray = field(repr=False)  # Do not include in print
+
+    def __post_init__(self) -> None:
+        """Convert from string to bytearray if DE_DATA is a string of ones and zeros."""
+        if isinstance(self.DE_DATA, str):
+            # Convert string output from space_packet_parser to bytearray
+            self.DE_DATA = bytearray(
+                int(self.DE_DATA, 2).to_bytes(len(self.DE_DATA) // 8, "big")
+            )
+
+    def within_same_sequence(self, other: "DirectEventL0") -> bool:
+        """
+        Compare fields for L0 which should be the same for packets within one sequence.
+
+        This method compares the IMAP time (SEC) and packet length (LEN) fields.
+
+        Parameters
+        ----------
+        other : DirectEventL0
+            Another instance of DirectEventL0 to compare to.
+
+        Returns
+        -------
+        bool
+            True if the SEC and LEN fields match, False otherwise.
+        """
+        if not isinstance(other, DirectEventL0):
+            return False
+
+        # Time and overall packet length should match
+        # TODO: What other fields need to match?
+        return self.SEC == other.SEC and self.LEN == other.LEN