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

imap_processing/tests/mag/test_mag_l1b.py

@@ -5,25 +5,50 @@ import pytest
 import xarray as xr
 
 from imap_processing.cdf.utils import load_cdf, write_cdf
-from imap_processing.mag.l1b.mag_l1b import mag_l1b, mag_l1b_processing
+from imap_processing.mag.l1b.mag_l1b import (
+    calibrate_vector,
+    mag_l1b,
+    mag_l1b_processing,
+)
 
 
 @pytest.fixture(scope="module")
 def mag_l1a_dataset():
     epoch = xr.DataArray(np.arange(20), name="epoch", dims=["epoch"])
     direction = xr.DataArray(np.arange(4), name="direction", dims=["direction"])
+    compression = xr.DataArray(np.arange(2), name="compression", dims=["compression"])
+
+    direction_label = xr.DataArray(
+        direction.values.astype(str),
+        name="direction_label",
+        dims=["direction_label"],
+    )
+
+    compression_label = xr.DataArray(
+        compression.values.astype(str),
+        name="compression_label",
+        dims=["compression_label"],
+    )
+
     vectors = xr.DataArray(
         np.zeros((20, 4)),
         dims=["epoch", "direction"],
         coords={"epoch": epoch, "direction": direction},
     )
+    compression_flags = xr.DataArray(
+        np.zeros((20, 2), dtype=np.int8), dims=["epoch", "compression"]
+    )
 
     vectors[0, :] = np.array([1, 1, 1, 0])
 
     output_dataset = xr.Dataset(
-        coords={"epoch": epoch, "direction": direction},
+        coords={"epoch": epoch, "direction": direction, "compression": compression},
     )
     output_dataset["vectors"] = vectors
+    output_dataset["compression_flags"] = compression_flags
+    output_dataset["direction_label"] = direction_label
+    output_dataset["compression_label"] = compression_label
+    output_dataset.attrs["Logical_source"] = ["imap_mag_l1a_norm-mago"]
 
     return output_dataset
 
@@ -32,9 +57,8 @@ def test_mag_processing(mag_l1a_dataset):
     mag_l1a_dataset.attrs["Logical_source"] = ["imap_mag_l1a_norm-mago"]
 
     mag_l1b = mag_l1b_processing(mag_l1a_dataset)
-
     np.testing.assert_allclose(
-        mag_l1b["vectors"][0].values, [2.29819857, 2.22914442, 2.24950008, 0]
+        mag_l1b["vectors"][0].values, [2.2972, 2.2415, 2.2381, 0], atol=1e-4
     )
     np.testing.assert_allclose(mag_l1b["vectors"][1].values, [0, 0, 0, 0])
 
@@ -45,7 +69,7 @@ def test_mag_processing(mag_l1a_dataset):
     mag_l1b = mag_l1b_processing(mag_l1a_dataset)
 
     np.testing.assert_allclose(
-        mag_l1b["vectors"][0].values, [2.27615106, 2.22638234, 2.24382211, 0]
+        mag_l1b["vectors"][0].values, [2.27538, 2.23416, 2.23682, 0], atol=1e-5
     )
     np.testing.assert_allclose(mag_l1b["vectors"][1].values, [0, 0, 0, 0])
 
@@ -66,13 +90,79 @@ def test_mag_attributes(mag_l1a_dataset):
     assert output.attrs["Data_level"] == "L1B"
 
 
-@pytest.mark.skip(reason="Epoch variable data need to be monotonically increasing")
 def test_cdf_output():
     l1a_cdf = load_cdf(
-        Path(__file__).parent / "imap_mag_l1a_burst-magi_20231025_v001.cdf"
+        Path(__file__).parent / "imap_mag_l1a_norm-magi_20251017_v001.cdf"
     )
     l1b_dataset = mag_l1b(l1a_cdf, "v001")
 
     output_path = write_cdf(l1b_dataset)
 
     assert Path.exists(output_path)
+
+
+def test_mag_compression_scale(mag_l1a_dataset):
+    test_calibration = np.array(
+        [
+            [2.2972202, 0.0, 0.0],
+            [0.00348625, 2.23802879, 0.0],
+            [-0.00250788, -0.00888437, 2.24950008],
+        ]
+    )
+    mag_l1a_dataset["vectors"][0, :] = np.array([1, 1, 1, 0])
+    mag_l1a_dataset["vectors"][1, :] = np.array([1, 1, 1, 0])
+    mag_l1a_dataset["vectors"][2, :] = np.array([1, 1, 1, 0])
+    mag_l1a_dataset["vectors"][3, :] = np.array([1, 1, 1, 0])
+
+    mag_l1a_dataset["compression_flags"][0, :] = np.array([1, 16], dtype=np.int8)
+    mag_l1a_dataset["compression_flags"][1, :] = np.array([0, 0], dtype=np.int8)
+    mag_l1a_dataset["compression_flags"][2, :] = np.array([1, 18], dtype=np.int8)
+    mag_l1a_dataset["compression_flags"][3, :] = np.array([1, 14], dtype=np.int8)
+
+    mag_l1a_dataset.attrs["Logical_source"] = ["imap_mag_l1a_norm-mago"]
+    output = mag_l1b(mag_l1a_dataset, "v001")
+
+    calibrated_vectors = np.matmul(test_calibration, np.array([1, 1, 1]))
+    # 16 bit width is the standard
+    assert np.allclose(output["vectors"].data[0][:3], calibrated_vectors)
+    # uncompressed data is uncorrected
+    assert np.allclose(output["vectors"].data[1][:3], calibrated_vectors)
+
+    # width of 18 should be multiplied by 1/4
+    scaled_vectors = calibrated_vectors * 1 / 4
+    # should be corrected
+    assert np.allclose(output["vectors"].data[2][:3], scaled_vectors)
+
+    # width of 14 should be multiplied by 4
+    scaled_vectors = calibrated_vectors * 4
+    assert np.allclose(output["vectors"].data[3][:3], scaled_vectors)
+
+
+def test_calibrate_vector():
+    # from MFOTOURFO
+    cal_array = np.array(
+        [
+            [
+                [2.29722020e00, 7.38200160e-02, 1.88479865e-02, 4.59777333e-03],
+                [0.00000000e00, 0.00000000e00, 0.00000000e00, 0.00000000e00],
+                [0.00000000e00, 0.00000000e00, 0.00000000e00, 0.00000000e00],
+            ],
+            [
+                [3.48624576e-03, 1.09224000e-04, 3.26118600e-05, 5.02830000e-06],
+                [2.23802879e00, 7.23781440e-02, 1.84842873e-02, 4.50744060e-03],
+                [0.00000000e00, 0.00000000e00, 0.00000000e00, 0.00000000e00],
+            ],
+            [
+                [-2.50787532e-03, -8.33760000e-05, -2.71240200e-05, 2.50509000e-06],
+                [-8.88437262e-03, -2.84256000e-04, -7.41600000e-05, -2.29399200e-05],
+                [2.24950008e00, 7.23836160e-02, 1.84847323e-02, 4.50945192e-03],
+            ],
+        ]
+    )
+
+    calibration_matrix = xr.DataArray(cal_array)
+
+    cal_vector = calibrate_vector(np.array([1.0, 1.0, 1.0, 0]), calibration_matrix)
+    expected_vector = np.array([2.2972, 2.2415, 2.2381, 0])
+
+    assert np.allclose(cal_vector, expected_vector, atol=1e-4)

imap_processing/tests/spice/test_data/imap_ena_sim_metakernel.template

@@ -3,4 +3,6 @@
 {SPICE_TEST_DATA_PATH}/imap_spk_demo.bsp
 {SPICE_TEST_DATA_PATH}/sim_1yr_imap_attitude.bc
 {SPICE_TEST_DATA_PATH}/imap_wkcp.tf
-{SPICE_TEST_DATA_PATH}/de440s.bsp
+{SPICE_TEST_DATA_PATH}/de440s.bsp
+{SPICE_TEST_DATA_PATH}/imap_science_0001.tf
+{SPICE_TEST_DATA_PATH}/sim_1yr_imap_pointing_frame.bc

imap_processing/tests/spice/test_geometry.py

@@ -8,6 +8,8 @@ import spiceypy as spice
 from imap_processing.spice.geometry import (
     SpiceBody,
     SpiceFrame,
+    basis_vectors,
+    cartesian_to_spherical,
     frame_transform,
     get_instrument_spin_phase,
     get_rotation_matrix,
@@ -16,7 +18,9 @@ from imap_processing.spice.geometry import (
     get_spin_data,
     imap_state,
     instrument_pointing,
+    spherical_to_cartesian,
 )
+from imap_processing.spice.kernels import ensure_spice
 
 
 @pytest.mark.parametrize(
@@ -99,10 +103,10 @@ def test_get_spacecraft_spin_phase_value_error(query_met_times, fake_spin_data):
         _ = get_spacecraft_spin_phase(query_met_times)
 
 
-@pytest.mark.usefixtures("_set_spin_data_filepath")
-def test_get_spin_data():
+@pytest.mark.usefixtures("use_fake_spin_data_for_time")
+def test_get_spin_data(use_fake_spin_data_for_time):
     """Test get_spin_data() with generated spin data."""
-
+    use_fake_spin_data_for_time(453051323.0 - 56120)
     spin_data = get_spin_data()
 
     (
@@ -200,6 +204,19 @@ def test_get_spacecraft_to_instrument_spin_phase_offset(instrument, expected_off
             SpiceFrame.IMAP_SPACECRAFT,
             SpiceFrame.IMAP_DPS,
         ),
+        # single et, multiple position vectors
+        (
+            ["2025-04-30T12:00:00.000"],
+            np.array(
+                [
+                    [1, 0, 0],
+                    [0, 1, 0],
+                    [0, 0, 1],
+                ]
+            ),
+            SpiceFrame.IMAP_SPACECRAFT,
+            SpiceFrame.IMAP_DPS,
+        ),
     ],
 )
 def test_frame_transform(et_strings, position, from_frame, to_frame, furnish_kernels):
@@ -219,11 +236,24 @@ def test_frame_transform(et_strings, position, from_frame, to_frame, furnish_ker
         et = np.array([spice.utc2et(et_str) for et_str in et_strings])
         et_arg = et[0] if len(et) == 1 else et
         result = frame_transform(et_arg, position, from_frame, to_frame)
-        # check the result shape before modifying for value checking
-        assert result.shape == (3,) if len(et) == 1 else (len(et), 3)
-        # compare against pure SPICE calculation
-        position = np.broadcast_to(position, (len(et), 3))
-        result = np.broadcast_to(result, (len(et), 3))
+        # check the result shape before modifying for value checking.
+        # There are 3 cases to consider:
+
+        # 1 event time, multiple position vectors:
+        if len(et) == 1 and position.ndim > 1:
+            assert result.shape == position.shape
+        # multiple event times, single position vector:
+        elif len(et) > 1 and position.ndim == 1:
+            assert result.shape == (len(et), 3)
+        # multiple event times, multiple position vectors (same number of each)
+        elif len(et) > 1 and position.ndim > 1:
+            assert result.shape == (len(et), 3)
+
+        # compare against pure SPICE calculation.
+        # If the result is a single position vector, broadcast it to first.
+        if position.ndim == 1:
+            position = np.broadcast_to(position, (len(et), 3))
+            result = np.broadcast_to(result, (len(et), 3))
         for spice_et, spice_position, test_result in zip(et, position, result):
             rotation_matrix = spice.pxform(from_frame.name, to_frame.name, spice_et)
             spice_result = spice.mxv(rotation_matrix, spice_position)
@@ -250,7 +280,7 @@ def test_frame_transform_exceptions():
         match="Mismatch in number of position vectors and Ephemeris times provided.",
     ):
         frame_transform(
-            np.arange(2),
+            [1, 2],
             np.arange(9).reshape((3, 3)),
             SpiceFrame.ECLIPJ2000,
             SpiceFrame.IMAP_HIT,
@@ -306,3 +336,79 @@ def test_instrument_pointing(furnish_kernels):
             et, SpiceFrame.IMAP_HI_90, SpiceFrame.ECLIPJ2000, cartesian=True
         )
         assert ins_pointing.shape == (3, 3)
+
+
+@pytest.mark.external_kernel()
+@pytest.mark.use_test_metakernel("imap_ena_sim_metakernel.template")
+def test_basis_vectors():
+    """Test coverage for basis_vectors()."""
+    # This call to SPICE needs to be wrapped with `ensure_spice` so that kernels
+    # get furnished automatically
+    et = ensure_spice(spice.utc2et)("2025-09-30T12:00:00.000")
+    # test input of float
+    sc_axes = basis_vectors(et, SpiceFrame.IMAP_SPACECRAFT, SpiceFrame.IMAP_SPACECRAFT)
+    np.testing.assert_array_equal(sc_axes, np.eye(3))
+    # test array of et input
+    et_array = np.arange(10) + et
+    sc_axes = basis_vectors(et_array, SpiceFrame.IMAP_SPACECRAFT, SpiceFrame.ECLIPJ2000)
+    assert sc_axes.shape == (10, 3, 3)
+    # Verify that for each time, the basis vectors are correct
+    for et, basis_matrix in zip(et_array, sc_axes):
+        np.testing.assert_array_equal(
+            basis_matrix,
+            frame_transform(
+                et * np.ones(3),
+                np.eye(3),
+                SpiceFrame.IMAP_SPACECRAFT,
+                SpiceFrame.ECLIPJ2000,
+            ),
+        )
+
+
+def test_cartesian_to_spherical():
+    """Tests cartesian_to_spherical function."""
+
+    step = 0.05
+    x = np.arange(-1, 1 + step, step)
+    y = np.arange(-1, 1 + step, step)
+    z = np.arange(-1, 1 + step, step)
+    x, y, z = np.meshgrid(x, y, z)
+
+    cartesian_points = np.stack((x.ravel(), y.ravel(), z.ravel()), axis=-1)
+
+    for point in cartesian_points:
+        r, az, el = cartesian_to_spherical(point)
+        r_spice, colat_spice, slong_spice = spice.recsph(point)
+
+        # Convert SPICE co-latitude to elevation
+        el_spice = 90 - np.degrees(colat_spice)
+        az_spice = np.degrees(slong_spice)
+
+        # Normalize azimuth to [0, 360]
+        az_spice = az_spice % 360
+
+        np.testing.assert_allclose(r, r_spice, atol=1e-5)
+        np.testing.assert_allclose(az, az_spice, atol=1e-5)
+        np.testing.assert_allclose(el, el_spice, atol=1e-5)
+
+
+def test_spherical_to_cartesian():
+    """Tests spherical_to_cartesian function."""
+
+    azimuth = np.linspace(0, 2 * np.pi, 50)
+    elevation = np.linspace(-np.pi / 2, np.pi / 2, 50)
+    theta, elev = np.meshgrid(azimuth, elevation)
+    r = 1.0
+
+    spherical_points = np.stack(
+        (r * np.ones_like(theta).ravel(), theta.ravel(), elev.ravel()), axis=-1
+    )
+
+    # Convert elevation to colatitude for SPICE
+    colat = np.pi / 2 - spherical_points[:, 2]
+
+    for i in range(len(colat)):
+        cartesian_coords = spherical_to_cartesian(np.array([spherical_points[i]]))
+        spice_coords = spice.sphrec(r, colat[i], spherical_points[i, 1])
+
+        np.testing.assert_allclose(cartesian_coords[0], spice_coords, atol=1e-5)

imap_processing/tests/spice/test_time.py

@@ -2,22 +2,41 @@
 
 import numpy as np
 import pytest
-import spiceypy as spice
+import spiceypy
 
 from imap_processing.spice import IMAP_SC_ID
-from imap_processing.spice.time import _sct2e_wrapper, j2000ns_to_j2000s, met_to_j2000ns
+from imap_processing.spice.time import (
+    TICK_DURATION,
+    _sct2e_wrapper,
+    et_to_utc,
+    j2000ns_to_j2000s,
+    met_to_datetime64,
+    met_to_j2000ns,
+    met_to_sclkticks,
+    met_to_utc,
+    str_to_et,
+)
+
+
+@pytest.mark.parametrize("met", [1, np.arange(10)])
+def test_met_to_sclkticks(met):
+    """Test coverage for met_to_sclkticks."""
+    # Tick duration is 20us as specified in imap_sclk_0000.tsc
+    expected = met * 1 / 20e-6
+    ticks = met_to_sclkticks(met)
+    np.testing.assert_array_equal(ticks, expected)
 
 
 def test_met_to_j2000ns(furnish_time_kernels):
     """Test coverage for met_to_j2000ns function."""
     utc = "2026-01-01T00:00:00.125"
-    et = spice.str2et(utc)
-    sclk_str = spice.sce2s(IMAP_SC_ID, et)
+    et = spiceypy.str2et(utc)
+    sclk_str = spiceypy.sce2s(IMAP_SC_ID, et)
     seconds, ticks = sclk_str.split("/")[1].split(":")
     # There is some floating point error calculating tick duration from 1 clock
     # tick so average over many clock ticks for better accuracy
     spice_tick_duration = (
-        spice.sct2e(IMAP_SC_ID, 1e12) - spice.sct2e(IMAP_SC_ID, 0)
+        spiceypy.sct2e(IMAP_SC_ID, 1e12) - spiceypy.sct2e(IMAP_SC_ID, 0)
     ) / 1e12
     met = float(seconds) + float(ticks) * spice_tick_duration
     j2000ns = met_to_j2000ns(met)
@@ -30,7 +49,7 @@ def test_j2000ns_to_j2000s(furnish_time_kernels):
     # Use spice to come up with reasonable J2000 values
     utc = "2025-09-23T00:00:00.000"
     # Test single value input
-    et = spice.str2et(utc)
+    et = spiceypy.str2et(utc)
     epoch = int(et * 1e9)
     j2000s = j2000ns_to_j2000s(epoch)
     assert j2000s == et
@@ -42,6 +61,61 @@ def test_j2000ns_to_j2000s(furnish_time_kernels):
     )
 
 
+@pytest.mark.parametrize(
+    "expected_utc, precision",
+    [
+        ("2024-01-01T00:00:00.000", 3),
+        (
+            [
+                "2024-01-01T00:00:00.000555",
+                "2025-09-23T00:00:00.000111",
+                "2040-11-14T10:23:48.156980",
+            ],
+            6,
+        ),
+    ],
+)
+def test_met_to_utc(furnish_time_kernels, expected_utc, precision):
+    """Test coverage for met_to_utc function."""
+    if isinstance(expected_utc, list):
+        et_arr = spiceypy.str2et(expected_utc)
+        sclk_ticks = np.array([spiceypy.sce2c(IMAP_SC_ID, et) for et in et_arr])
+    else:
+        et = spiceypy.str2et(expected_utc)
+        sclk_ticks = spiceypy.sce2c(IMAP_SC_ID, et)
+    met = sclk_ticks * TICK_DURATION
+    utc = met_to_utc(met, precision=precision)
+    np.testing.assert_array_equal(utc, expected_utc)
+
+
+@pytest.mark.parametrize(
+    "utc",
+    [
+        "2024-01-01T00:00:00.000",
+        [
+            "2024-01-01T00:00:00.000",
+            "2025-09-23T00:00:00.000",
+            "2040-11-14T10:23:48.15698",
+        ],
+    ],
+)
+def test_met_to_datetime64(furnish_time_kernels, utc):
+    """Test coverage for met_to_datetime64 function."""
+    if isinstance(utc, list):
+        expected_dt64 = np.array([np.datetime64(utc_str) for utc_str in utc])
+        et_arr = spiceypy.str2et(utc)
+        sclk_ticks = np.array([spiceypy.sce2c(IMAP_SC_ID, et) for et in et_arr])
+    else:
+        expected_dt64 = np.asarray(np.datetime64(utc))
+        et = spiceypy.str2et(utc)
+        sclk_ticks = spiceypy.sce2c(IMAP_SC_ID, et)
+    met = sclk_ticks * TICK_DURATION
+    dt64 = met_to_datetime64(met)
+    np.testing.assert_array_equal(
+        dt64.astype("datetime64[us]"), expected_dt64.astype("datetime64[us]")
+    )
+
+
 @pytest.mark.parametrize("sclk_ticks", [0.0, np.arange(10)])
 def test_sct2e_wrapper(sclk_ticks):
     """Test for `_sct2e_wrapper` function."""
@@ -50,3 +124,58 @@ def test_sct2e_wrapper(sclk_ticks):
         assert isinstance(et, float)
     else:
         assert len(et) == len(sclk_ticks)
+
+
+def test_str_to_et(furnish_time_kernels):
+    """Test coverage for string to et conversion function."""
+    utc = "2017-07-14T19:46:00"
+    # Test single value input
+    expected_et = 553333629.1837274
+    actual_et = str_to_et(utc)
+    assert expected_et == actual_et
+
+    # Test list input
+    list_of_utc = [
+        "2017-08-14T19:46:00.000",
+        "2017-09-14T19:46:00.000",
+        "2017-10-14T19:46:00.000",
+    ]
+
+    expected_et_array = np.array(
+        (556012029.1829445, 558690429.1824446, 561282429.1823651)
+    )
+    actual_et_array = str_to_et(list_of_utc)
+    assert np.array_equal(expected_et_array, actual_et_array)
+
+    # Test array input
+    array_of_utc = np.array(
+        [
+            "2017-08-14T19:46:00.000",
+            "2017-09-14T19:46:00.000",
+            "2017-10-14T19:46:00.000",
+        ]
+    )
+
+    actual_et_array = str_to_et(array_of_utc)
+    assert np.array_equal(expected_et_array, actual_et_array)
+
+
+def test_et_to_utc(furnish_time_kernels):
+    """Test coverage for et to utc conversion function."""
+    et = 553333629.1837274
+    # Test single value input
+    expected_utc = "2017-07-14T19:46:00.000"
+    actual_utc = et_to_utc(et)
+    assert expected_utc == actual_utc
+
+    # Test array input
+    array_of_et = np.array((556012029.1829445, 558690429.1824446, 561282429.1823651))
+    expected_utc_array = np.array(
+        (
+            "2017-08-14T19:46:00.000",
+            "2017-09-14T19:46:00.000",
+            "2017-10-14T19:46:00.000",
+        )
+    )
+    actual_utc_array = et_to_utc(array_of_et)
+    assert np.array_equal(expected_utc_array, actual_utc_array)