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

imap_processing/hit/l1a/hit_l1a.py

@@ -8,6 +8,7 @@ import xarray as xr
 from imap_processing.cdf.imap_cdf_manager import ImapCdfAttributes
 from imap_processing.hit.hit_utils import (
     HitAPID,
+    add_energy_variables,
     get_attribute_manager,
     get_datasets_by_apid,
     process_housekeeping_data,
@@ -66,28 +67,28 @@ def subcom_sectorates(sci_dataset: xr.Dataset) -> None:
     """
     Subcommutate sectorates data.
 
-    Sector rates data contains rates for 5 species and 10
-    energy ranges. This function subcommutates the sector
-    rates data by organizing the rates by species. Which
+    Sectored rates data contains raw counts for 5 species and 10
+    energy ranges. This function subcommutates the sectored
+    rates data by organizing the counts by species. Which
     species and energy range the data belongs to is determined
     by taking the mod 10 value of the corresponding header
     minute count value in the dataset. A mapping of mod 10
     values to species and energy ranges is provided in constants.py.
 
     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": "4He", "energy_min": 4, "energy_max": 6},
+        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},
         ...
-        9: {"species": "Fe", "energy_min": 4, "energy_max": 12}}
+        9: {"species": "fe", "energy_min": 4, "energy_max": 12}}
 
     The data is added to the dataset as new data fields named
     according to their species. They have 4 dimensions: epoch
-    energy index, declination, and azimuth. The energy index
+    energy mean, azimuth, and declination. The energy mean
     dimension is used to distinguish between the different energy
-    ranges the data belongs to. The energy min and max values for
-    each species are also added to the dataset as new data fields.
+    ranges the data belongs to. The energy deltas for each species
+    are also added to the dataset as new data fields.
 
     Parameters
     ----------
@@ -98,65 +99,55 @@ def subcom_sectorates(sci_dataset: xr.Dataset) -> None:
     hdr_min_count_mod_10 = sci_dataset.hdr_minute_cnt.values % 10
 
     # Reference mod 10 mapping to initialize data structure for species and
-    # energy ranges and add 8x15 arrays with fill values for each science frame.
+    # energy ranges and add 15x8 arrays with fill values for each science frame.
     num_frames = len(hdr_min_count_mod_10)
-    # TODO: add more specific dtype for rates (ex. int16) once this is defined by HIT
     data_by_species_and_energy_range = {
         key: {
             **value,
-            "rates": np.full((num_frames, 8, 15), fill_value=fillval, dtype=int),
+            "counts": np.full((num_frames, 15, 8), fill_value=fillval, dtype=np.int64),
         }
         for key, value in MOD_10_MAPPING.items()
     }
 
-    # Update rates for science frames where data is available
+    # Update counts for science frames where data is available
     for i, mod_10 in enumerate(hdr_min_count_mod_10):
-        data_by_species_and_energy_range[mod_10]["rates"][i] = sci_dataset[
+        data_by_species_and_energy_range[mod_10]["counts"][i] = sci_dataset[
             "sectorates"
         ].values[i]
 
     # H has 3 energy ranges, 4He, CNO, NeMgSi have 2, and Fe has 1.
-    # Aggregate sector rates and energy min/max values for each species.
+    # Aggregate sectored rates and energy min/max values for each species.
     # First, initialize dictionaries to store rates and min/max energy values by species
     data_by_species: dict = {
-        value["species"]: {"rates": [], "energy_min": [], "energy_max": []}
+        value["species"]: {"counts": [], "energy_min": [], "energy_max": []}
         for value in data_by_species_and_energy_range.values()
     }
 
     for value in data_by_species_and_energy_range.values():
         species = value["species"]
-        data_by_species[species]["rates"].append(value["rates"])
+        data_by_species[species]["counts"].append(value["counts"])
         data_by_species[species]["energy_min"].append(value["energy_min"])
         data_by_species[species]["energy_max"].append(value["energy_max"])
 
-    # Add sector rates by species to the dataset
-    for species_type, data in data_by_species.items():
-        # Rates data has shape: energy_index, epoch, declination, azimuth
+    # Add sectored rates by species to the dataset
+    for species, data in data_by_species.items():
+        # Rates data has shape: energy_mean, epoch, azimuth, declination
         # Convert rates to numpy array and transpose axes to get
-        # shape: epoch, energy_index, declination, azimuth
-        rates_data = np.transpose(np.array(data["rates"]), axes=(1, 0, 2, 3))
+        # shape: epoch, energy_mean, azimuth, declination
+        rates_data = np.transpose(np.array(data["counts"]), axes=(1, 0, 2, 3))
 
-        species = species_type.lower()
-        sci_dataset[f"{species}_counts_sectored"] = xr.DataArray(
+        sci_dataset[f"{species}_sectored_counts"] = xr.DataArray(
             data=rates_data,
-            dims=["epoch", f"{species}_energy_index", "declination", "azimuth"],
+            dims=["epoch", f"{species}_energy_mean", "azimuth", "declination"],
             name=f"{species}_counts_sectored",
         )
-        sci_dataset[f"{species}_energy_min"] = xr.DataArray(
-            data=np.array(data["energy_min"], dtype=np.int8),
-            dims=[f"{species}_energy_index"],
-            name=f"{species}_energy_min",
-        )
-        sci_dataset[f"{species}_energy_max"] = xr.DataArray(
-            data=np.array(data["energy_max"], dtype=np.int8),
-            dims=[f"{species}_energy_index"],
-            name=f"{species}_energy_max",
-        )
-        # add energy index coordinate to the dataset
-        sci_dataset.coords[f"{species}_energy_index"] = xr.DataArray(
-            np.arange(sci_dataset.sizes[f"{species}_energy_index"], dtype=np.int8),
-            dims=[f"{species}_energy_index"],
-            name=f"{species}_energy_index",
+
+        # Add energy mean and deltas for each species
+        sci_dataset = add_energy_variables(
+            sci_dataset,
+            species,
+            np.array(data["energy_min"]),
+            np.array(data["energy_max"]),
         )
 
 
@@ -202,16 +193,16 @@ def calculate_uncertainties(dataset: xr.Dataset) -> xr.Dataset:
         "hdr_code_ok",
         "hdr_minute_cnt",
         "livetime_counter",
-        "h_energy_min",
-        "h_energy_max",
-        "he4_energy_min",
-        "he4_energy_max",
-        "cno_energy_min",
-        "cno_energy_max",
-        "nemgsi_energy_min",
-        "nemgsi_energy_max",
-        "fe_energy_min",
-        "fe_energy_max",
+        "h_energy_delta_minus",
+        "h_energy_delta_plus",
+        "he4_energy_delta_minus",
+        "he4_energy_delta_plus",
+        "cno_energy_delta_minus",
+        "cno_energy_delta_plus",
+        "nemgsi_energy_delta_minus",
+        "nemgsi_energy_delta_plus",
+        "fe_energy_delta_minus",
+        "fe_energy_delta_plus",
     ]
 
     # Counts data that need uncertainties calculated
@@ -269,7 +260,7 @@ def process_science(
     # Decommutate and decompress the science data
     sci_dataset = decom_hit(dataset)
 
-    # Organize sector rates by species type
+    # Organize sectored rates by species type
     subcom_sectorates(sci_dataset)
 
     # Split the science data into count rates and event datasets
@@ -282,7 +273,7 @@ def process_science(
     count_rates_dataset = calculate_uncertainties(count_rates_dataset)
 
     # Logical sources for the two products.
-    logical_sources = ["imap_hit_l1a_count-rates", "imap_hit_l1a_pulse-height-events"]
+    logical_sources = ["imap_hit_l1a_counts", "imap_hit_l1a_direct-events"]
 
     datasets = []
     # Update attributes and dimensions

imap_processing/hit/l1b/constants.py

@@ -0,0 +1,317 @@
+"""HIT L1B constants."""
+
+# Expected number of livestim pulses per integration time.
+# This is used to calculate the fractional livetime
+livestim_pulses = 270
+
+# For the L1B summed rates product, counts are summed by particle type,
+# energy range, and detector penetration range (Range 2, Range 3, and Range 4).
+# See section 6.2 of the algorithm document for more details.
+
+# The counts to sum are in the L2FGRATES, L3FGRATES, and PENFGRATES data
+# variables in the L1A product. These variables represent different detector
+# ranges for each particle type and energy range.
+
+# Indices at each detector range are provided for each particle type
+# and energy range in the dictionary below and the counts at these indices will be
+# summed in l1B processing to produce the summed rates product.
+# R2 = Indices for Range 2 (L2FGRATES)
+# R3 = Indices for Range 3 (L3FGRATES)
+# R4 = Indices for Range 4 (PENFGRATES)
+# energy_units: MeV/n
+
+PARTICLE_ENERGY_RANGE_MAPPING = {
+    "h": [
+        {
+            "energy_min": 1.8,
+            "energy_max": 3.6,
+            "R2": [1, 2, 3, 4],
+            "R3": [0, 1],
+            "R4": [],
+        },
+        {"energy_min": 4.0, "energy_max": 6.0, "R2": [6, 7], "R3": [3, 4, 5], "R4": []},
+        {"energy_min": 6.0, "energy_max": 10.0, "R2": [], "R3": [6, 7], "R4": []},
+        {"energy_min": 10.0, "energy_max": 15.0, "R2": [], "R3": [8, 9], "R4": [1]},
+    ],
+    "he3": [
+        {
+            "energy_min": 4.0,
+            "energy_max": 6.0,
+            "R2": [14, 15, 16],
+            "R3": [12, 13, 14],
+            "R4": [],
+        },
+        {"energy_min": 6.0, "energy_max": 10.0, "R2": [], "R3": [15, 16], "R4": []},
+        {"energy_min": 10.0, "energy_max": 15.0, "R2": [], "R3": [17, 18], "R4": []},
+    ],
+    "he4": [
+        {
+            "energy_min": 1.8,
+            "energy_max": 3.6,
+            "R2": [19, 20, 21, 22],
+            "R3": [21],
+            "R4": [],
+        },
+        {
+            "energy_min": 4.0,
+            "energy_max": 6.0,
+            "R2": [24, 25],
+            "R3": [23, 24, 25],
+            "R4": [],
+        },
+        {"energy_min": 6.0, "energy_max": 10.0, "R2": [], "R3": [26, 27], "R4": []},
+        {"energy_min": 10.0, "energy_max": 15.0, "R2": [], "R3": [28, 29], "R4": [4]},
+    ],
+    "he": [
+        {
+            "energy_min": 4.0,
+            "energy_max": 6.0,
+            "R2": [14, 15, 16, 24, 25],
+            "R3": [12, 13, 14, 23, 24, 25],
+            "R4": [],
+        },
+        {
+            "energy_min": 6.0,
+            "energy_max": 10.0,
+            "R2": [],
+            "R3": [15, 16, 26, 27],
+            "R4": [],
+        },
+        {
+            "energy_min": 10.0,
+            "energy_max": 15.0,
+            "R2": [],
+            "R3": [17, 18, 28, 29],
+            "R4": [4],
+        },
+    ],
+    "c": [
+        {
+            "energy_min": 4.0,
+            "energy_max": 6.0,
+            "R2": [30, 31, 32],
+            "R3": [32, 33],
+            "R4": [],
+        },
+        {
+            "energy_min": 6.0,
+            "energy_max": 10.0,
+            "R2": [33, 34],
+            "R3": [34, 35],
+            "R4": [],
+        },
+        {"energy_min": 10.0, "energy_max": 15.0, "R2": [], "R3": [36, 37], "R4": []},
+        {"energy_min": 15.0, "energy_max": 27.0, "R2": [], "R3": [38, 39], "R4": [7]},
+    ],
+    "n": [
+        {
+            "energy_min": 4.0,
+            "energy_max": 6.0,
+            "R2": [39, 40, 41],
+            "R3": [43],
+            "R4": [],
+        },
+        {
+            "energy_min": 6.0,
+            "energy_max": 10.0,
+            "R2": [42, 43],
+            "R3": [44, 45],
+            "R4": [],
+        },
+        {"energy_min": 10.0, "energy_max": 15.0, "R2": [], "R3": [46, 47], "R4": []},
+        {"energy_min": 15.0, "energy_max": 27.0, "R2": [], "R3": [48, 49], "R4": [11]},
+    ],
+    "o": [
+        {
+            "energy_min": 4.0,
+            "energy_max": 6.0,
+            "R2": [48, 49, 50],
+            "R3": [53],
+            "R4": [],
+        },
+        {
+            "energy_min": 6.0,
+            "energy_max": 10.0,
+            "R2": [51, 52],
+            "R3": [54, 55],
+            "R4": [],
+        },
+        {"energy_min": 10.0, "energy_max": 15.0, "R2": [], "R3": [56, 57], "R4": []},
+        {"energy_min": 15.0, "energy_max": 27.0, "R2": [], "R3": [58, 59], "R4": []},
+    ],
+    "ne": [
+        {"energy_min": 4.0, "energy_max": 6.0, "R2": [57, 58, 59], "R3": [], "R4": []},
+        {
+            "energy_min": 6.0,
+            "energy_max": 10.0,
+            "R2": [60, 61],
+            "R3": [63, 64],
+            "R4": [],
+        },
+        {"energy_min": 10.0, "energy_max": 15.0, "R2": [62], "R3": [65, 66], "R4": []},
+        {"energy_min": 15.0, "energy_max": 27.0, "R2": [], "R3": [67, 68], "R4": []},
+    ],
+    "na": [
+        {"energy_min": 10.0, "energy_max": 15.0, "R2": [], "R3": [75, 76], "R4": []},
+        {"energy_min": 15.0, "energy_max": 27.0, "R2": [], "R3": [77, 78], "R4": []},
+    ],
+    "mg": [
+        {"energy_min": 4.0, "energy_max": 6.0, "R2": [67, 68, 69], "R3": [], "R4": []},
+        {
+            "energy_min": 6.0,
+            "energy_max": 10.0,
+            "R2": [70, 71],
+            "R3": [83, 84],
+            "R4": [],
+        },
+        {
+            "energy_min": 10.0,
+            "energy_max": 15.0,
+            "R2": [72, 73],
+            "R3": [85, 86],
+            "R4": [],
+        },
+        {"energy_min": 15.0, "energy_max": 27.0, "R2": [], "R3": [87, 88], "R4": []},
+    ],
+    "al": [
+        {"energy_min": 6.0, "energy_max": 10.0, "R2": [], "R3": [94, 95], "R4": []},
+        {"energy_min": 10.0, "energy_max": 15.0, "R2": [], "R3": [96, 97], "R4": []},
+        {"energy_min": 15.0, "energy_max": 27.0, "R2": [], "R3": [98, 99], "R4": []},
+    ],
+    "si": [
+        {"energy_min": 4.0, "energy_max": 6.0, "R2": [78, 79, 80], "R3": [], "R4": []},
+        {
+            "energy_min": 6.0,
+            "energy_max": 10.0,
+            "R2": [81, 82],
+            "R3": [105, 106],
+            "R4": [],
+        },
+        {
+            "energy_min": 10.0,
+            "energy_max": 15.0,
+            "R2": [83, 84],
+            "R3": [107, 108],
+            "R4": [],
+        },
+        {"energy_min": 15.0, "energy_max": 27.0, "R2": [], "R3": [109, 110], "R4": []},
+        {
+            "energy_min": 27.0,
+            "energy_max": 40.0,
+            "R2": [],
+            "R3": [111, 112],
+            "R4": [26],
+        },
+    ],
+    "s": [
+        {"energy_min": 4.0, "energy_max": 6.0, "R2": [88, 89, 90], "R3": [], "R4": []},
+        {
+            "energy_min": 6.0,
+            "energy_max": 10.0,
+            "R2": [91, 92],
+            "R3": [116, 117],
+            "R4": [],
+        },
+        {
+            "energy_min": 10.0,
+            "energy_max": 15.0,
+            "R2": [93, 94],
+            "R3": [118, 119],
+            "R4": [],
+        },
+        {"energy_min": 15.0, "energy_max": 27.0, "R2": [], "R3": [120, 121], "R4": []},
+        {"energy_min": 27.0, "energy_max": 40.0, "R2": [], "R3": [122, 123], "R4": []},
+    ],
+    "ar": [
+        {"energy_min": 4.0, "energy_max": 6.0, "R2": [98, 99, 100], "R3": [], "R4": []},
+        {
+            "energy_min": 6.0,
+            "energy_max": 10.0,
+            "R2": [101, 102],
+            "R3": [127, 128],
+            "R4": [],
+        },
+        {
+            "energy_min": 10.0,
+            "energy_max": 15.0,
+            "R2": [103, 104],
+            "R3": [129, 130],
+            "R4": [],
+        },
+        {
+            "energy_min": 15.0,
+            "energy_max": 27.0,
+            "R2": [105],
+            "R3": [131, 132],
+            "R4": [],
+        },
+        {"energy_min": 27.0, "energy_max": 40.0, "R2": [], "R3": [133, 134], "R4": []},
+    ],
+    "ca": [
+        {
+            "energy_min": 4.0,
+            "energy_max": 6.0,
+            "R2": [109, 110, 111],
+            "R3": [],
+            "R4": [],
+        },
+        {
+            "energy_min": 6.0,
+            "energy_max": 10.0,
+            "R2": [112, 113],
+            "R3": [138],
+            "R4": [],
+        },
+        {
+            "energy_min": 10.0,
+            "energy_max": 15.0,
+            "R2": [114, 115],
+            "R3": [139, 140],
+            "R4": [],
+        },
+        {
+            "energy_min": 15.0,
+            "energy_max": 27.0,
+            "R2": [116],
+            "R3": [141, 142],
+            "R4": [],
+        },
+        {"energy_min": 27.0, "energy_max": 40.0, "R2": [], "R3": [143, 144], "R4": []},
+    ],
+    "fe": [
+        {
+            "energy_min": 4.0,
+            "energy_max": 6.0,
+            "R2": [122, 123, 124],
+            "R3": [],
+            "R4": [],
+        },
+        {
+            "energy_min": 6.0,
+            "energy_max": 10.0,
+            "R2": [125, 126],
+            "R3": [148],
+            "R4": [],
+        },
+        {
+            "energy_min": 10.0,
+            "energy_max": 15.0,
+            "R2": [127, 128],
+            "R3": [149, 150],
+            "R4": [],
+        },
+        {
+            "energy_min": 15.0,
+            "energy_max": 27.0,
+            "R2": [129],
+            "R3": [151, 152],
+            "R4": [],
+        },
+        {"energy_min": 27.0, "energy_max": 40.0, "R2": [], "R3": [153, 154], "R4": []},
+    ],
+    "ni": [
+        {"energy_min": 10.0, "energy_max": 15.0, "R2": [], "R3": [159, 160], "R4": []},
+        {"energy_min": 15.0, "energy_max": 27.0, "R2": [], "R3": [161, 162], "R4": []},
+        {"energy_min": 27.0, "energy_max": 40.0, "R2": [], "R3": [163, 164], "R4": []},
+    ],
+}