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

imap_processing/hi/utils.py

@@ -174,7 +174,7 @@ def create_dataset_variables(
     """
     attr_mgr = ImapCdfAttributes()
     attr_mgr.add_instrument_global_attrs("hi")
-    attr_mgr.load_variable_attributes("imap_hi_variable_attrs.yaml")
+    attr_mgr.add_instrument_variable_attrs(instrument="hi", level=None)
 
     new_variables = dict()
     for var in variable_names:

imap_processing/hit/hit_utils.py

@@ -0,0 +1,221 @@
+"""
+Classes and functions used in HIT processing.
+
+This module contains utility classes and functions that are used by
+HIT processing modules.
+"""
+
+from enum import IntEnum
+
+import numpy as np
+import xarray as xr
+
+from imap_processing import imap_module_directory
+from imap_processing.cdf.imap_cdf_manager import ImapCdfAttributes
+from imap_processing.utils import packet_file_to_datasets
+
+
+class HitAPID(IntEnum):
+    """
+    HIT APID Mappings.
+
+    Attributes
+    ----------
+    HIT_HSKP: int
+        Housekeeping
+    HIT_SCIENCE : int
+        Science
+    HIT_IALRT : int
+        I-ALiRT
+    """
+
+    HIT_HSKP = 1251
+    HIT_SCIENCE = 1252
+    HIT_IALRT = 1253
+
+
+def get_datasets_by_apid(
+    packet_file: str, derived: bool = False
+) -> dict[int, xr.Dataset]:
+    """
+    Get datasets by APID from a CCSDS packet file.
+
+    Parameters
+    ----------
+    packet_file : str
+        Path to the CCSDS data packet file.
+    derived : bool, optional
+        Flag to use derived values, by default False.
+        Only set to True to get engineering units for L1B
+        housekeeping data product.
+
+    Returns
+    -------
+    datasets_by_apid : dict[int, xr.Dataset]
+        Dictionary of xarray datasets by APID.
+    """
+    # Unpack ccsds file
+    packet_definition = (
+        imap_module_directory / "hit/packet_definitions/hit_packet_definitions.xml"
+    )
+    datasets_by_apid: dict[int, xr.Dataset] = packet_file_to_datasets(
+        packet_file=packet_file,
+        xtce_packet_definition=packet_definition,
+        use_derived_value=derived,
+    )
+    return datasets_by_apid
+
+
+def get_attribute_manager(data_version: str, level: str) -> ImapCdfAttributes:
+    """
+    Create an attribute manager for the HIT data products.
+
+    Parameters
+    ----------
+    data_version : str
+        Version of the data product being created.
+    level : str
+        Data level of the product being created.
+
+    Returns
+    -------
+    attr_mgr : ImapCdfAttributes
+        Attribute manager to set CDF attributes.
+    """
+    # Create the attribute manager for this data level
+    attr_mgr = ImapCdfAttributes()
+    attr_mgr.add_instrument_global_attrs(instrument="hit")
+    attr_mgr.add_instrument_variable_attrs(instrument="hit", level=level)
+    attr_mgr.add_global_attribute("Data_version", data_version)
+    return attr_mgr
+
+
+def concatenate_leak_variables(
+    dataset: xr.Dataset, adc_channels: xr.DataArray
+) -> xr.Dataset:
+    """
+    Concatenate leak variables in the dataset.
+
+    Updates the housekeeping dataset to replace the individual
+    leak_i_00, leak_i_01, ..., leak_i_63 variables with a single
+    leak_i variable as a 2D array. "i" here represents current
+    in the leakage current [Voltage] data.
+
+    Parameters
+    ----------
+    dataset : xarray.Dataset
+        Dataset containing 64 leak variables.
+    adc_channels : xarray.DataArray
+        DataArray to be used as a dimension for the concatenated leak variables.
+
+    Returns
+    -------
+    dataset : xarray.Dataset
+        Updated dataset with concatenated leak variables.
+    """
+    # Stack 64 leak variables (leak_00, leak_01, ..., leak_63)
+    leak_vars = [dataset[f"leak_i_{i:02d}"] for i in range(64)]
+
+    # Concatenate along 'adc_channels' and reorder dimensions
+    stacked_leaks = xr.concat(leak_vars, dim=adc_channels).transpose(
+        "epoch", "adc_channels"
+    )
+    dataset["leak_i"] = stacked_leaks
+
+    # Drop the individual leak variables
+    updated_dataset = dataset.drop_vars([f"leak_i_{i:02d}" for i in range(64)])
+
+    return updated_dataset
+
+
+def process_housekeeping_data(
+    dataset: xr.Dataset, attr_mgr: ImapCdfAttributes, logical_source: str
+) -> xr.Dataset:
+    """
+    Will process housekeeping dataset for CDF product.
+
+    Updates the housekeeping dataset with a single 2D leak_i
+    variable. Also updates the dataset attributes, coordinates
+    and data variable dimensions according to specifications in
+    a cdf yaml file. This function is used for both L1A and L1B
+    housekeeping data products.
+
+    Parameters
+    ----------
+    dataset : xarray.Dataset
+        Dataset containing HIT housekeeping data.
+
+    attr_mgr : ImapCdfAttributes
+        Attribute manager used to get the data product field's attributes.
+
+    logical_source : str
+        Logical source of the data -> imap_hit_l1a_hk or imap_hit_l1b_hk.
+
+    Returns
+    -------
+    dataset : xarray.Dataset
+        An updated dataset ready for CDF conversion.
+    """
+    # Drop keys that are not CDF data variables
+    drop_keys = [
+        "pkt_apid",
+        "sc_tick",
+        "version",
+        "type",
+        "sec_hdr_flg",
+        "seq_flgs",
+        "src_seq_ctr",
+        "pkt_len",
+        "hskp_spare1",
+        "hskp_spare2",
+        "hskp_spare3",
+        "hskp_spare4",
+        "hskp_spare5",
+    ]
+
+    # Drop variables not needed for CDF
+    dataset = dataset.drop_vars(drop_keys)
+
+    # Create data arrays for dependencies
+    adc_channels = xr.DataArray(
+        np.arange(64, dtype=np.uint8),
+        name="adc_channels",
+        dims=["adc_channels"],
+        attrs=attr_mgr.get_variable_attributes("adc_channels"),
+    )
+
+    # NOTE: LABL_PTR_1 should be CDF_CHAR.
+    adc_channels_label = xr.DataArray(
+        adc_channels.values.astype(str),
+        name="adc_channels_label",
+        dims=["adc_channels_label"],
+        attrs=attr_mgr.get_variable_attributes("adc_channels_label"),
+    )
+
+    # Update dataset coordinates and attributes
+    dataset = dataset.assign_coords(
+        {
+            "adc_channels": adc_channels,
+            "adc_channels_label": adc_channels_label,
+        }
+    )
+    dataset.attrs = attr_mgr.get_global_attributes(logical_source)
+
+    # Stack 64 leak variables (leak_00, leak_01, ..., leak_63)
+    dataset = concatenate_leak_variables(dataset, adc_channels)
+
+    # Assign attributes and dimensions to each data array in the Dataset
+    for field in dataset.data_vars.keys():
+        # Create a dict of dimensions using the DEPEND_I keys in the
+        # attributes
+        dims = {
+            key: value
+            for key, value in attr_mgr.get_variable_attributes(field).items()
+            if "DEPEND" in key
+        }
+        dataset[field].attrs = attr_mgr.get_variable_attributes(field)
+        dataset[field].assign_coords(dims)
+
+    dataset.epoch.attrs = attr_mgr.get_variable_attributes("epoch")
+
+    return dataset

imap_processing/hit/l0/constants.py

@@ -0,0 +1,118 @@
+"""HIT L0 constants for data decommutation."""
+
+from collections import namedtuple
+
+import numpy as np
+
+# energy_units: MeV/n
+MOD_10_MAPPING = {
+    0: {"species": "H", "energy_min": 1.8, "energy_max": 3.6},
+    1: {"species": "H", "energy_min": 4, "energy_max": 6},
+    2: {"species": "H", "energy_min": 6, "energy_max": 10},
+    3: {"species": "He4", "energy_min": 4, "energy_max": 6},
+    4: {"species": "He4", "energy_min": 6, "energy_max": 12},
+    5: {"species": "CNO", "energy_min": 4, "energy_max": 6},
+    6: {"species": "CNO", "energy_min": 6, "energy_max": 12},
+    7: {"species": "NeMgSi", "energy_min": 4, "energy_max": 6},
+    8: {"species": "NeMgSi", "energy_min": 6, "energy_max": 12},
+    9: {"species": "Fe", "energy_min": 4, "energy_max": 12},
+}
+
+# Structure to hold binary details for a
+# section of science data. Used to unpack
+# binary data.
+HITPacking = namedtuple(
+    "HITPacking",
+    [
+        "bit_length",
+        "section_length",
+        "shape",
+    ],
+)
+
+# Define data structure for counts rates data
+COUNTS_DATA_STRUCTURE = {
+    # field: bit_length, section_length, shape
+    # ------------------------------------------
+    # science frame header
+    "hdr_unit_num": HITPacking(2, 2, (1,)),
+    "hdr_frame_version": HITPacking(6, 6, (1,)),
+    "hdr_dynamic_threshold_state": HITPacking(2, 2, (1,)),
+    "hdr_leak_conv": HITPacking(1, 1, (1,)),
+    "hdr_heater_duty_cycle": HITPacking(4, 4, (1,)),
+    "hdr_code_ok": HITPacking(1, 1, (1,)),
+    "hdr_minute_cnt": HITPacking(8, 8, (1,)),
+    # ------------------------------------------
+    # spare bits. Contains no data
+    "spare": HITPacking(24, 24, (1,)),
+    # ------------------------------------------
+    # erates - contains livetime counters
+    "livetime": HITPacking(16, 16, (1,)),  # livetime counter
+    "num_trig": HITPacking(16, 16, (1,)),  # number of triggers
+    "num_reject": HITPacking(16, 16, (1,)),  # number of rejected events
+    "num_acc_w_pha": HITPacking(
+        16, 16, (1,)
+    ),  # number of accepted events with PHA data
+    "num_acc_no_pha": HITPacking(16, 16, (1,)),  # number of events without PHA data
+    "num_haz_trig": HITPacking(16, 16, (1,)),  # number of triggers with hazard flag
+    "num_haz_reject": HITPacking(
+        16, 16, (1,)
+    ),  # number of rejected events with hazard flag
+    "num_haz_acc_w_pha": HITPacking(
+        16, 16, (1,)
+    ),  # number of accepted hazard events with PHA data
+    "num_haz_acc_no_pha": HITPacking(
+        16, 16, (1,)
+    ),  # number of hazard events without PHA data
+    # -------------------------------------------
+    "sngrates": HITPacking(16, 1856, (2, 58)),  # single rates
+    # -------------------------------------------
+    # evprates - contains event processing rates
+    "nread": HITPacking(16, 16, (1,)),  # events read from event fifo
+    "nhazard": HITPacking(16, 16, (1,)),  # events tagged with hazard flag
+    "nadcstim": HITPacking(16, 16, (1,)),  # adc-stim events
+    "nodd": HITPacking(16, 16, (1,)),  # odd events
+    "noddfix": HITPacking(16, 16, (1,)),  # odd events that were fixed in sw
+    "nmulti": HITPacking(
+        16, 16, (1,)
+    ),  # events with multiple hits in a single detector
+    "nmultifix": HITPacking(16, 16, (1,)),  # multi events that were fixed in sw
+    "nbadtraj": HITPacking(16, 16, (1,)),  # bad trajectory
+    "nl2": HITPacking(16, 16, (1,)),  # events sorted into L12 event category
+    "nl3": HITPacking(16, 16, (1,)),  # events sorted into L123 event category
+    "nl4": HITPacking(16, 16, (1,)),  # events sorted into L1423 event category
+    "npen": HITPacking(16, 16, (1,)),  # events sorted into penetrating event category
+    "nformat": HITPacking(16, 16, (1,)),  # nothing currently goes in this slot
+    "naside": HITPacking(16, 16, (1,)),  # A-side events
+    "nbside": HITPacking(16, 16, (1,)),  # B-side events
+    "nerror": HITPacking(16, 16, (1,)),  # events that caused a processing error
+    "nbadtags": HITPacking(
+        16, 16, (1,)
+    ),  # events with inconsistent tags vs pulse heights
+    # -------------------------------------------
+    # other count rates
+    "coinrates": HITPacking(16, 416, (26,)),  # coincidence rates
+    "bufrates": HITPacking(16, 512, (32,)),  # priority buffer rates
+    "l2fgrates": HITPacking(16, 2112, (132,)),  # range 2 foreground rates
+    "l2bgrates": HITPacking(16, 192, (12,)),  # range 2 background rates
+    "l3fgrates": HITPacking(16, 2672, (167,)),  # range 3 foreground rates
+    "l3bgrates": HITPacking(16, 192, (12,)),  # range 3 background rates
+    "penfgrates": HITPacking(16, 528, (33,)),  # range 4 foreground rates
+    "penbgrates": HITPacking(16, 240, (15,)),  # range 4 background rates
+    "ialirtrates": HITPacking(16, 320, (20,)),  # ialirt rates
+    "sectorates": HITPacking(16, 1920, (8, 15)),  # sectored rates
+    "l4fgrates": HITPacking(16, 768, (48,)),  # all range foreground rates
+    "l4bgrates": HITPacking(16, 384, (24,)),  # all range foreground rates
+}
+
+
+# Define the pattern of grouping flags in a complete science frame.
+FLAG_PATTERN = np.array([1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 2])
+
+# Define size of science frame (num of packets)
+FRAME_SIZE = len(FLAG_PATTERN)
+
+# Define the number of bits in the mantissa and exponent for
+# decompressing data
+MANTISSA_BITS = 12
+EXPONENT_BITS = 4