imap-processing 0.12.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
@@ -213,13 +213,11 @@ energy_heliosphere:
   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:
@@ -236,20 +234,6 @@ path_length:
   LABLAXIS: path_length
   UNITS: mm / 100
 
-azimuth:
-  <<: *default_float32
-  CATDESC: Azimuth.
-  FIELDNAM: azimuth
-  LABLAXIS: azimuth
-  UNITS: radians
-
-elevation:
-  <<: *default_float32
-  CATDESC: Elevation.
-  FIELDNAM: elevation
-  LABLAXIS: elevation
-  UNITS: radians
-
 phi:
   <<: *default_float32
   CATDESC: Ultra instrument frame event phi (azimuth with range -90 -> 90).
@@ -264,6 +248,20 @@ theta:
   LABLAXIS: theta
   UNITS: degrees
 
+phi_fwhm:
+  <<: *default_float32
+  CATDESC: FWHM of the phi distribution.
+  FIELDNAM: phi_fwhm
+  LABLAXIS: phi fwhm
+  UNITS: degrees
+
+theta_fwhm:
+  <<: *default_float32
+  CATDESC: FWHM of the theta distribution.
+  FIELDNAM: phi_fwhm
+  LABLAXIS: phi fwhm
+  UNITS: degrees
+
 event_efficiency:
   <<: *default_float32
   CATDESC: Estimated event efficiency for this path through the instrument.
@@ -271,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

@@ -11,7 +11,7 @@ default_attrs: &default
 
 default_float32_attrs: &default_float32
   <<: *default
-  FILLVAL: .NAN
+  FILLVAL: -1.0e31
   FORMAT: F12.6
   VALIDMIN: -3.4028235e+38
   VALIDMAX: 3.4028235e+38
@@ -31,22 +31,6 @@ longitude:
   LABLAXIS: longitude
   UNITS: degrees
 
-spin_angle:
-  <<: *default
-  CATDESC: Angular bin defined by central location of the bin
-  FIELDNAM: spin_angle
-  LABLAXIS: spin angle
-  # TODO: come back to format
-  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
-
 species_bin:
   <<: *default
   CATDESC: Species bin defined by central location.
@@ -95,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.
@@ -127,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
@@ -61,7 +66,6 @@ def load_cdf(
 
 def write_cdf(
     dataset: xr.Dataset,
-    parent_files: Optional[list] = None,
     **extra_cdf_kwargs: dict,
 ) -> Path:
     """
@@ -71,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.
 
@@ -96,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():
@@ -128,13 +144,6 @@ 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
     if "l1" in data_level:
@@ -147,7 +156,6 @@ def write_cdf(
             extra_cdf_kwargs["istp"] = True  # type: ignore
 
     xarray_to_cdf(dataset, str(file_path), **extra_cdf_kwargs)
-
     return file_path
 
 
@@ -185,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)