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

imap_processing/mag/l1a/mag_l1a.py

@@ -8,7 +8,6 @@ import numpy as np
 import xarray as xr
 
 from imap_processing.cdf.imap_cdf_manager import ImapCdfAttributes
-from imap_processing.cdf.utils import J2000_EPOCH
 from imap_processing.mag.constants import DataMode, PrimarySensor
 from imap_processing.mag.l0 import decom_mag
 from imap_processing.mag.l0.mag_l0_data import MagL0
@@ -17,7 +16,7 @@ from imap_processing.mag.l1a.mag_l1a_data import (
     MagL1aPacketProperties,
     TimeTuple,
 )
-from imap_processing.spice.time import met_to_j2000ns
+from imap_processing.spice.time import J2000_EPOCH, met_to_j2000ns
 
 logger = logging.getLogger(__name__)
 

imap_processing/mag/l1a/mag_l1a_data.py

@@ -9,7 +9,6 @@ from math import floor
 import numpy as np
 import numpy.typing as npt
 
-from imap_processing.cdf.utils import J2000_EPOCH
 from imap_processing.mag.constants import (
     AXIS_COUNT,
     FIBONACCI_SEQUENCE,
@@ -17,7 +16,7 @@ from imap_processing.mag.constants import (
     MAX_FINE_TIME,
     RANGE_BIT_WIDTH,
 )
-from imap_processing.spice.time import met_to_j2000ns
+from imap_processing.spice.time import J2000_EPOCH, met_to_j2000ns
 
 
 @dataclass

imap_processing/mag/l1b/mag_l1b.py

@@ -202,6 +202,7 @@ def calibrate_vector(
     updated_vector = input_vector.copy()
 
     updated_vector[:3] = np.matmul(
-        input_vector[:3], calibration_matrix.values[:, :, int(input_vector[3])]
+        calibration_matrix.values[:, :, int(input_vector[3])], input_vector[:3]
     )
+
     return updated_vector

imap_processing/spice/geometry.py

@@ -64,8 +64,6 @@ class SpiceFrame(IntEnum):
     IMAP_GLOWS = -43750
 
 
-# TODO: Update boresight for in-situ instruments
-# TODO: Confirm ENA boresight vectors
 BORESIGHT_LOOKUP = {
     SpiceFrame.IMAP_LO: np.array([0, -1, 0]),
     SpiceFrame.IMAP_HI_45: np.array([0, 1, 0]),
@@ -73,12 +71,12 @@ BORESIGHT_LOOKUP = {
     SpiceFrame.IMAP_ULTRA_45: np.array([0, 0, 1]),
     SpiceFrame.IMAP_ULTRA_90: np.array([0, 0, 1]),
     SpiceFrame.IMAP_MAG: np.array([0, 0, 1]),
-    SpiceFrame.IMAP_SWE: np.array([0, 0, 1]),
-    SpiceFrame.IMAP_SWAPI: np.array([0, 0, 1]),
+    SpiceFrame.IMAP_SWE: np.array([-1, 0, 0]),
+    SpiceFrame.IMAP_SWAPI: np.array([0, 1, 0]),
     SpiceFrame.IMAP_CODICE: np.array([0, 0, 1]),
-    SpiceFrame.IMAP_HIT: np.array([0, 0, 1]),
-    SpiceFrame.IMAP_IDEX: np.array([0, 0, 1]),
-    SpiceFrame.IMAP_GLOWS: np.array([0, 0, 1]),
+    SpiceFrame.IMAP_HIT: np.array([0, 1, 0]),
+    SpiceFrame.IMAP_IDEX: np.array([0, 1, 0]),
+    SpiceFrame.IMAP_GLOWS: np.array([0, 0, -1]),
 }
 
 
@@ -326,8 +324,11 @@ def frame_transform(
         Ephemeris time(s) corresponding to position(s).
     position : np.ndarray
         <x, y, z> vector or array of vectors in reference frame `from_frame`.
-        A single position vector may be provided for multiple `et` query times
-        but only a single position vector can be provided for a single `et`.
+        There are several possible shapes for the input position and et:
+        1. A single position vector may be provided for multiple `et` query times
+        2. A single `et` may be provided for multiple position vectors,
+        3. The same number of `et` and position vectors may be provided.
+        But it is not allowed to have n position vectors and m `et`, where n != m.
     from_frame : SpiceFrame
         Reference frame of input vector(s).
     to_frame : SpiceFrame
@@ -350,11 +351,13 @@ def frame_transform(
                 f"Each input position vector must have 3 elements."
             )
         if not len(position) == np.asarray(et).size:
-            raise ValueError(
-                "Mismatch in number of position vectors and Ephemeris times provided."
-                f"Position has {len(position)} elements and et has "
-                f"{np.asarray(et).size} elements."
-            )
+            if np.asarray(et).size != 1:
+                raise ValueError(
+                    "Mismatch in number of position vectors and "
+                    "Ephemeris times provided."
+                    f"Position has {len(position)} elements and et has "
+                    f"{np.asarray(et).size} elements."
+                )
 
     # rotate will have shape = (3, 3) or (n, 3, 3)
     # position will have shape = (3,) or (n, 3)
@@ -494,6 +497,7 @@ def basis_vectors(
 
 def cartesian_to_spherical(
     v: NDArray,
+    degrees: bool = True,
 ) -> NDArray:
     """
     Convert cartesian coordinates to spherical coordinates.
@@ -504,6 +508,9 @@ def cartesian_to_spherical(
         A NumPy array with shape (n, 3) where each
         row represents a vector
         with x, y, z-components.
+    degrees : bool
+        If True, the azimuth and elevation angles are returned in degrees.
+        Defaults to True.
 
     Returns
     -------
@@ -512,8 +519,16 @@ def cartesian_to_spherical(
         the spherical coordinates (r, azimuth, elevation):
 
         - r : Distance of the point from the origin.
-        - azimuth : angle in the xy-plane in radians [0, 2*pi].
-        - elevation : angle from the z-axis in radians [-pi/2, pi/2].
+        - azimuth : angle in the xy-plane
+          In degrees if degrees parameter is True (by default):
+          output range=[0, 360],
+          otherwise in radians if degrees parameter is False:
+          output range=[0, 2*pi].
+        - elevation : angle from the z-axis
+          In degrees if degrees parameter is True (by default):
+          output range=[0, 180],
+          otherwise in radians if degrees parameter is False:
+          output range=[-pi/2, pi/2].
     """
     # Magnitude of the velocity vector
     magnitude_v = np.linalg.norm(v, axis=-1, keepdims=True)
@@ -528,9 +543,12 @@ def cartesian_to_spherical(
 
     # Ensure azimuth is from 0 to 2PI
     az = az % (2 * np.pi)
-    spherical_coords = np.stack(
-        (np.squeeze(magnitude_v), np.degrees(az), np.degrees(el)), axis=-1
-    )
+
+    if degrees:
+        az = np.degrees(az)
+        el = np.degrees(el)
+
+    spherical_coords = np.stack((np.squeeze(magnitude_v), az, el), axis=-1)
 
     return spherical_coords
 

imap_processing/spice/time.py

@@ -1,7 +1,7 @@
 """Time conversion functions that rely on SPICE."""
 
 import typing
-from collections.abc import Collection
+from collections.abc import Collection, Iterable
 from typing import Union
 
 import numpy as np
@@ -13,6 +13,32 @@ from imap_processing.spice.kernels import ensure_spice
 
 TICK_DURATION = 2e-5  # 20 microseconds as defined in imap_sclk_0000.tsc
 
+# Hard code the J2000 epoch. This allows for CDF epoch to be converted without
+# use of SPICE though it should be noted that this results in a 5-second error
+# due to the occurrence of 5 leap-seconds since the J2000 epoch.
+# TODO: Implement a function for converting CDF epoch to UTC correctly.
+#     see github ticket #1208
+# The UTC string was generated by:
+# >>> spiceypy.et2utc(0, "ISOC", 9)
+J2000_EPOCH = np.datetime64("2000-01-01T11:58:55.816072737", "ns")
+
+
+def met_to_sclkticks(met: npt.ArrayLike) -> npt.NDArray[float]:
+    """
+    Convert Mission Elapsed Time (MET) to floating point spacecraft clock ticks.
+
+    Parameters
+    ----------
+    met : float, numpy.ndarray
+        Number of seconds since epoch according to the spacecraft clock.
+
+    Returns
+    -------
+    numpy.ndarray[float]
+        The mission elapsed time converted to nanoseconds since the J2000 epoch.
+    """
+    return np.asarray(met, dtype=float) / TICK_DURATION
+
 
 def met_to_j2000ns(
     met: npt.ArrayLike,
@@ -40,7 +66,7 @@ def met_to_j2000ns(
     "tick" which is defined to be 20 microseconds, according to the sclk kernel,
     it is preferable to use the higher accuracy method.
     """
-    sclk_ticks = np.asarray(met, dtype=float) / TICK_DURATION
+    sclk_ticks = met_to_sclkticks(met)
     return np.asarray(_sct2e_wrapper(sclk_ticks) * 1e9, dtype=np.int64)
 
 
@@ -64,6 +90,53 @@ def j2000ns_to_j2000s(j2000ns: npt.ArrayLike) -> npt.NDArray[float]:
     return np.asarray(j2000ns, dtype=np.float64) / 1e9
 
 
+@typing.no_type_check
+@ensure_spice(time_kernels_only=True)
+def met_to_utc(met: npt.ArrayLike, precision: int = 9) -> npt.NDArray[str]:
+    """
+    Convert mission elapsed time (MET) to UTC.
+
+    Parameters
+    ----------
+    met : float, numpy.ndarray
+        Number of seconds since epoch according to the spacecraft clock.
+    precision : int
+        The number of digits of precision to which fractional seconds
+        are to be computed.
+
+    Returns
+    -------
+    numpy.ndarray[str]
+        The mission elapsed time converted to UTC string. The UTC string(s)
+        returned will be of the form '1987-04-12T16:31:12.814' with the
+        fractional seconds precision as specified by the precision keyword.
+    """
+    sclk_ticks = met_to_sclkticks(met)
+    et = _sct2e_wrapper(sclk_ticks)
+    return spice.et2utc(et, "ISOC", prec=precision)
+
+
+def met_to_datetime64(
+    met: npt.ArrayLike,
+) -> Union[np.datetime64, npt.NDArray[np.datetime64]]:
+    """
+    Convert mission elapsed time (MET) to datetime.datetime.
+
+    Parameters
+    ----------
+    met : float, numpy.ndarray
+        Number of seconds since epoch according to the spacecraft clock.
+
+    Returns
+    -------
+    numpy.ndarray[str]
+        The mission elapsed time converted to UTC string.
+    """
+    if isinstance(met, typing.Iterable):
+        return np.asarray([np.datetime64(utc) for utc in met_to_utc(met)])
+    return np.datetime64(met_to_utc(met))
+
+
 @typing.no_type_check
 @ensure_spice
 def _sct2e_wrapper(
@@ -90,3 +163,72 @@ def _sct2e_wrapper(
         return np.array([spice.sct2e(IMAP_SC_ID, s) for s in sclk_ticks])
     else:
         return spice.sct2e(IMAP_SC_ID, sclk_ticks)
+
+
+@typing.no_type_check
+@ensure_spice
+def str_to_et(
+    time_str: Union[str, Iterable[str]],
+) -> Union[float, np.ndarray]:
+    """
+    Convert string to ephemeris time.
+
+    Decorated wrapper for spiceypy.str2et that vectorizes the function in addition
+    to wrapping with the @ensure_spice automatic kernel furnishing functionality.
+    https://spiceypy.readthedocs.io/en/main/documentation.html#spiceypy.spiceypy.str2et
+
+    Parameters
+    ----------
+    time_str : str or Iterable[str]
+        Input string(s) to be converted to ephemeris time.
+
+    Returns
+    -------
+    ephemeris_time: np.ndarray
+        Ephemeris time, seconds past J2000.
+    """
+    if isinstance(time_str, str):
+        return spice.str2et(time_str)
+    else:
+        return np.array([spice.str2et(t) for t in time_str])
+
+
+@typing.no_type_check
+@ensure_spice
+def et_to_utc(
+    et: Union[float, Iterable[float]],
+    format_str: str = "ISOC",
+    precision: int = 3,
+    utclen: int = 24,
+) -> Union[str, np.ndarray]:
+    """
+    Convert ephemeris time to UTC.
+
+    Decorated wrapper for spiceypy.et2utc that vectorizes the function in addition
+    to wrapping with the @ensure_spice automatic kernel furnishing functionality.
+    https://spiceypy.readthedocs.io/en/main/documentation.html#spiceypy.spiceypy.et2utc
+
+    Parameters
+    ----------
+    et : float or Iterable[float]
+        Input ephemeris time(s) to be converted to UTC.
+    format_str : str
+        Format of the output time string. Default is "ISOC". All options:
+        "C" Calendar format, UTC.
+        "D" Day-of-Year format, UTC.
+        "J" Julian Date format, UTC.
+        "ISOC" ISO Calendar format, UTC.
+        "ISOD" ISO Day-of-Year format, UTC.
+    precision : int
+        Digits of precision in fractional seconds or days. Default is 3.
+    utclen : int
+        The length of the output string. Default is 24 (to accommodate the
+        "YYYY-MM-DDT00:00:00.000" format + 1). From the NAIF docs: if the output string
+        is expected to have `x` characters, utclen` must be x + 1.
+
+    Returns
+    -------
+    utc_time : str or np.ndarray
+        UTC time(s).
+    """
+    return spice.et2utc(et, format_str, precision, utclen)

imap_processing/swapi/l1/swapi_l1.py

@@ -39,7 +39,7 @@ def filter_good_data(full_sweep_sci: xr.Dataset) -> npt.NDArray:
     """
     # PLAN_ID for current sweep should all be one value and
     # SWEEP_TABLE should all be one value.
-    plan_id = full_sweep_sci["plan_id_science"].data.reshape(-1, 12)
+    plan_id = full_sweep_sci["plan_id"].data.reshape(-1, 12)
     sweep_table = full_sweep_sci["sweep_table"].data.reshape(-1, 12)
 
     mode = full_sweep_sci["mode"].data.reshape(-1, 12)
@@ -72,7 +72,7 @@ def filter_good_data(full_sweep_sci: xr.Dataset) -> npt.NDArray:
     )
     logger.debug(
         "Plan ID should be same: "
-        f"{full_sweep_sci['plan_id_science'].data[bad_cycle_indices]}"
+        f"{full_sweep_sci['plan_id'].data[bad_cycle_indices]}"
     )
     logger.debug(
         f"Mode Id should be 3(HVSCI): {full_sweep_sci['mode'].data[bad_cycle_indices]}"
@@ -615,7 +615,7 @@ def process_swapi_science(
         attrs=cdf_manager.get_variable_attributes("sweep_table"),
     )
     dataset["plan_id"] = xr.DataArray(
-        good_sweep_sci["plan_id_science"].data.reshape(total_full_sweeps, 12)[:, 0],
+        good_sweep_sci["plan_id"].data.reshape(total_full_sweeps, 12)[:, 0],
         name="plan_id",
         dims=["epoch"],
         attrs=cdf_manager.get_variable_attributes("plan_id"),