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

imap_processing/cdf/config/imap_ultra_l1b_variable_attrs.yaml

@@ -58,7 +58,7 @@ default_int32_attrs: &default_int32
 
 default_float32_attrs: &default_float32
   <<: *default
-  FILLVAL: .NAN
+  FILLVAL: -1.0e31
   FORMAT: F12.6
   VALIDMIN: -3.4028235e+38
   VALIDMAX: 3.4028235e+38
@@ -101,11 +101,32 @@ x_coin:
 
 event_times:
   <<: *default_float32
-  CATDESC: time of event as calculated using aux and de l1a packets
+  CATDESC: time of event as calculated using Universal Spin Table and de l1a packets
   FIELDNAM: event_times
   LABLAXIS: event times
   UNITS: seconds
 
+spin_starts:
+  <<: *default_float32
+  CATDESC: time of spin from Universal Spin Table.
+  FIELDNAM: spin_starts
+  LABLAXIS: spin starts
+  UNITS: seconds
+
+phase_angle:
+  <<: *default_float32
+  CATDESC: Phase angle from the direct event packet in 1/2 degree increments (range is 0-719)
+  FIELDNAM: phase_angle
+  LABLAXIS: phase angle
+  UNITS: degrees
+
+spin:
+  <<: *default_uint32
+  CATDESC: Spin number.
+  FIELDNAM: spin_number
+  LABLAXIS: spin number
+  UNITS: " "
+
 tof_start_stop:
   <<: *default_float32
   CATDESC: Particle time of flight from start to stop
@@ -172,19 +193,31 @@ energy:
 
 tof_energy:
   <<: *default_float32
-  CATDESC: Energy measured using kinetic energy equation.
+  CATDESC: Energy measured using kinetic energy equation in the instrument frame.
+  FIELDNAM: energy
+  LABLAXIS: energy
+  UNITS: keV
+
+energy_spacecraft:
+  <<: *default_float32
+  CATDESC: Energy measured using kinetic energy equation in the despun spacecraft frame.
+  FIELDNAM: energy
+  LABLAXIS: energy
+  UNITS: keV
+
+energy_heliosphere:
+  <<: *default_float32
+  CATDESC: Energy measured using kinetic energy equation in the despun heliosphere frame.
   FIELDNAM: energy
   LABLAXIS: energy
   UNITS: keV
 
 species:
-  <<: *default
+  <<: *default_uint8
   DISPLAY_TYPE: no_plot
   CATDESC: Label species type.
   FIELDNAM: Label species type.
-  FILLVAL: "UNKNOWN"
-  FORMAT: A8
-  dtype: str
+  LABLAXIS: species
   UNITS: " "
 
 front_back_distance:
@@ -201,19 +234,33 @@ path_length:
   LABLAXIS: path_length
   UNITS: mm / 100
 
-azimuth:
+phi:
+  <<: *default_float32
+  CATDESC: Ultra instrument frame event phi (azimuth with range -90 -> 90).
+  FIELDNAM: phi
+  LABLAXIS: phi
+  UNITS: degrees
+
+theta:
+  <<: *default_float32
+  CATDESC: Ultra instrument frame event theta (elevation with range -90 -> 90).
+  FIELDNAM: theta
+  LABLAXIS: theta
+  UNITS: degrees
+
+phi_fwhm:
   <<: *default_float32
-  CATDESC: Azimuth.
-  FIELDNAM: azimuth
-  LABLAXIS: azimuth
-  UNITS: radians
+  CATDESC: FWHM of the phi distribution.
+  FIELDNAM: phi_fwhm
+  LABLAXIS: phi fwhm
+  UNITS: degrees
 
-elevation:
+theta_fwhm:
   <<: *default_float32
-  CATDESC: Elevation.
-  FIELDNAM: elevation
-  LABLAXIS: elevation
-  UNITS: radians
+  CATDESC: FWHM of the theta distribution.
+  FIELDNAM: phi_fwhm
+  LABLAXIS: phi fwhm
+  UNITS: degrees
 
 event_efficiency:
   <<: *default_float32
@@ -222,6 +269,22 @@ event_efficiency:
   LABLAXIS: event efficiency
   UNITS: " "
 
+direct_event_unit_velocity:
+  <<: *default_float32
+  CATDESC: Unit vector of the direct event velocity in the instrument frame.
+  DEPEND_1: component
+  FIELDNAM: direct_event_unit_velocity
+  LABLAXIS: direct event unit velocity
+  UNITS: " "
+
+direct_event_unit_position:
+  <<: *default_float32
+  CATDESC: Unit vector of the direct event position in the instrument frame.
+  DEPEND_1: component
+  FIELDNAM: direct_event_unit_position
+  LABLAXIS: direct event unit position
+  UNITS: " "
+
 velocity_sc:
   <<: *default_float32
   CATDESC: x,y,z-components of the velocity vector of the ena in the spacecraft frame.

imap_processing/cdf/config/imap_ultra_l1c_variable_attrs.yaml

@@ -7,30 +7,29 @@ default_attrs: &default
   VALIDMIN: -9223372036854775808
   VALIDMAX: 9223372036854775807
   VAR_TYPE: data
+  UNITS: " "
 
-spin_angle:
+default_float32_attrs: &default_float32
   <<: *default
-  CATDESC: Angular bin defined by central location of the bin
-  FIELDNAM: spin_angle
-  LABLAXIS: spin angle
-  # TODO: come back to format
-  UNITS: degrees
+  FILLVAL: -1.0e31
+  FORMAT: F12.6
+  VALIDMIN: -3.4028235e+38
+  VALIDMAX: 3.4028235e+38
+  dtype: float32
 
-esa_step:
-  <<: *default
-  CATDESC: ESA step (0-10), nominally 9, but possibly 8 or 10, 0 is likely a background test. Energy bin.
-  FIELDNAM: esa_step
-  LABLAXIS: esa step
-  # TODO: come back to format
-  UNITS: " "
+latitude:
+  <<: *default_float32
+  CATDESC: Latitude bin center corresponding to healpix index with range [-90, 90].
+  FIELDNAM: latitude
+  LABLAXIS: latitude
+  UNITS: degrees
 
-time_bin:
-  <<: *default
-  CATDESC: Time bin defined by central location of the bin.
-  FIELDNAM: time_bin
-  LABLAXIS: time bin
-  # TODO: come back to format
-  UNITS: seconds
+longitude:
+  <<: *default_float32
+  CATDESC: Longitude bin center corresponding to healpix index with range [0, 360].
+  FIELDNAM: longitude
+  LABLAXIS: longitude
+  UNITS: degrees
 
 species_bin:
   <<: *default
@@ -40,11 +39,11 @@ species_bin:
   # TODO: come back to format
   UNITS: " "
 
-exposure_times:
-  <<: *default
-  CATDESC: Exposure time for a spin.
-  FIELDNAM: exposure_times
-  LABLAXIS: exposure times
+exposure_factor:
+  <<: *default_float32
+  CATDESC: Exposure time for a pointing.
+  FIELDNAM: exposure_factor
+  LABLAXIS: exposure factor
   # TODO: come back to format
   UNITS: seconds
 
@@ -65,7 +64,7 @@ counts:
   UNITS: counts
 
 background_rates:
-  <<: *default
+  <<: *default_float32
   CATDESC: Background rates. Background dominated by accidentals caused by a combination of UV light and misregistered low energy ENA events.
   FIELDNAM: background_rates
   LABLAXIS: background rates
@@ -80,30 +79,6 @@ sid:
   # TODO: come back to format
   UNITS: " "
 
-row:
-  <<: *default
-  CATDESC: Row number.
-  FIELDNAM: row
-  LABLAXIS: row
-  # TODO: come back to format
-  UNITS: " "
-
-column:
-  <<: *default
-  CATDESC: Column number.
-  FIELDNAM: column
-  LABLAXIS: column
-  # TODO: come back to format
-  UNITS: " "
-
-spin:
-  <<: *default
-  CATDESC: Spin number at integration start.
-  FIELDNAM: spin
-  LABLAXIS: spin
-  # TODO: come back to format
-  UNITS: " "
-
 shcoarse:
   <<: *default
   CATDESC: CCSDS packet timestamp.
@@ -112,10 +87,10 @@ shcoarse:
   # TODO: come back to format
   UNITS: seconds
 
-packetdata:
-  <<: *default
-  CATDESC: A 2D numpy array representing pixel values. Each pixel is stored as an unsigned 16-bit integer.
-  FIELDNAM: packetdata
-  LABLAXIS: packet data
-  # TODO: come back to format
-  UNITS: " "
+energy_bin_delta:
+  <<: *default_float32
+  CATDESC: Difference between the energy bin edges.
+  DEPEND_0: energy_bin_geometric_mean
+  FIELDNAM: energy_bin_delta
+  LABLAXIS: energy bin delta
+  UNITS: keV

imap_processing/cdf/utils.py

@@ -1,9 +1,11 @@
 """Various utility functions to support creation of CDF files."""
 
+from __future__ import annotations
+
 import logging
 import re
+import warnings
 from pathlib import Path
-from typing import Optional
 
 import imap_data_access
 import numpy as np
@@ -19,15 +21,15 @@ logger = logging.getLogger(__name__)
 
 
 def load_cdf(
-    file_path: Path, remove_xarray_attrs: bool = True, **kwargs: dict
+    file_path: Path | str, remove_xarray_attrs: bool = True, **kwargs: dict
 ) -> xr.Dataset:
     """
     Load the contents of a CDF file into an ``xarray`` dataset.
 
     Parameters
     ----------
-    file_path : Path
-        The path to the CDF file.
+    file_path : Path or ImapFilePath or str
+        The path to the CDF file or ImapFilePath object.
     remove_xarray_attrs : bool
         Whether to remove the xarray attributes that get injected by the
         cdf_to_xarray function from the output xarray.Dataset. Default is True.
@@ -39,6 +41,9 @@ def load_cdf(
     dataset : xarray.Dataset
         The ``xarray`` dataset for the CDF file.
     """
+    if isinstance(file_path, imap_data_access.ImapFilePath):
+        file_path = file_path.construct_path()
+
     dataset = cdf_to_xarray(file_path, kwargs)
 
     # cdf_to_xarray converts single-value attributes to lists
@@ -60,7 +65,8 @@ def load_cdf(
 
 
 def write_cdf(
-    dataset: xr.Dataset, parent_files: Optional[list] = None, **extra_cdf_kwargs: dict
+    dataset: xr.Dataset,
+    **extra_cdf_kwargs: dict,
 ) -> Path:
     """
     Write the contents of "data" to a CDF file using cdflib.xarray_to_cdf.
@@ -69,17 +75,19 @@ def write_cdf(
     fills in the final attributes, and converts the whole dataset to a CDF.
     The date in the file name is determined by the time of the first epoch in the
     xarray Dataset.  The first 3 file name fields (mission, instrument, level) are
-    determined by the "Logical_source" attribute.  The version is determiend from
+    determined by the "Logical_source" attribute.  The version is determined from
     "Data_version".
 
+    The start_date and repointing attributes in the dataset are used to override the
+    computed values.
+
+    If these are not included, start_date is generated from the first epoch in the
+    dataset and repointing is not included if the attribute is not present or None.
+
     Parameters
     ----------
     dataset : xarray.Dataset
         The dataset object to convert to a CDF.
-    parent_files : list of Path, optional
-        List of parent files that were used to make this file. These get added to
-        the ``Parents`` global attribute:
-        https://spdf.gsfc.nasa.gov/istp_guide/gattributes.html.
     **extra_cdf_kwargs : dict
         Additional keyword arguments to pass to the ``xarray_to_cdf`` function.
 
@@ -94,26 +102,36 @@ def write_cdf(
     # Convert J2000 epoch referenced data to datetime64
     # TODO: This implementation of epoch to time string results in an error of
     #       5 seconds due to 5 leap-second occurrences since the J2000 epoch.
-    dt64 = TTJ2000_EPOCH + dataset["epoch"].values[0].astype("timedelta64[ns]")
-    start_time = np.datetime_as_string(dt64, unit="D").replace("-", "")
-
-    # Will now accept vXXX or XXX formats, as batch starter sends versions as vXXX.
-    r = re.compile(r"v\d{3}")
-    if (
-        not isinstance(dataset.attrs["Data_version"], str)
-        or r.match(dataset.attrs["Data_version"]) is None
-    ):
-        version = f"v{int(dataset.attrs['Data_version']):03d}"  # vXXX
-    else:
-        version = dataset.attrs["Data_version"]
+    # TODO: Create a ttj2000_to_datetime function to handle this conversion
+    start_date = dataset.attrs.get("Start_date", None)
+
+    if start_date is None:
+        # If no start time is included, then use the first epoch in the dataset
+        dt64 = TTJ2000_EPOCH + dataset["epoch"].values[0].astype("timedelta64[ns]")
+        start_date = np.datetime_as_string(dt64, unit="D").replace("-", "")
+
+    version = dataset.attrs.get("Data_version", None)
+    if version is None:
+        warnings.warn(
+            "No Data_version attribute found in dataset. Using default v999.",
+            stacklevel=2,
+        )
+        version = "v999"
+    elif not re.match(r"v\d{3}", version):
+        raise ValueError(
+            f"The Data_version attribute {version} does not match expected format vXXX."
+        )
+
     repointing = dataset.attrs.get("Repointing", None)
+
+    repointing_int = int(repointing[-5:]) if repointing else None
     science_file = imap_data_access.ScienceFilePath.generate_from_inputs(
         instrument=instrument,
         data_level=data_level,
         descriptor=descriptor,
-        start_time=start_time,
+        start_time=start_date,
         version=version,
-        repointing=repointing,
+        repointing=repointing_int,
     )
     file_path = Path(science_file.construct_path())
     if not file_path.parent.exists():
@@ -126,22 +144,18 @@ def write_cdf(
     dataset.attrs["Logical_file_id"] = file_path.stem
     # Add the processing version to the dataset attributes
     dataset.attrs["ground_software_version"] = imap_processing._version.__version__
-    # Add any parent files to the dataset attributes
-    if parent_files:
-        # Include the current files if there are any and include just the filename
-        # [file1.txt, file2.cdf, ...]
-        dataset.attrs["Parents"] = dataset.attrs.get("Parents", []) + [
-            parent_file.name for parent_file in parent_files
-        ]
 
     # Convert the xarray object to a CDF
-    xarray_to_cdf(
-        dataset,
-        str(file_path),
-        terminate_on_warning=True,
-        **extra_cdf_kwargs,
-    )  # Terminate if not ISTP compliant
+    if "l1" in data_level:
+        if "terminate_on_warning" not in extra_cdf_kwargs:
+            extra_cdf_kwargs["terminate_on_warning"] = False  # type: ignore
+    else:
+        if "terminate_on_warning" not in extra_cdf_kwargs:
+            extra_cdf_kwargs["terminate_on_warning"] = True  # type: ignore
+        if "istp" not in extra_cdf_kwargs:
+            extra_cdf_kwargs["istp"] = True  # type: ignore
 
+    xarray_to_cdf(dataset, str(file_path), **extra_cdf_kwargs)
     return file_path
 
 
@@ -179,7 +193,7 @@ def parse_filename_like(filename_like: str) -> re.Match:
         r"(?P<descriptor>[^_]+)"  # Required descriptor
         r"(_(?P<start_date>\d{8}))?"  # Optional start date
         r"(-repoint(?P<repointing>\d{5}))?"  # Optional repointing field
-        r"(?:_v(?P<version>\d{3}))?"  # Optional version
+        r"(?:_(?P<version>v\d{3}))?"  # Optional version
         r"(?:\.(?P<extension>cdf|pkts))?$"  # Optional extension
     )
     match = re.match(regex_str, filename_like)