imap-processing 0.17.0__py3-none-any.whl → 0.19.0__py3-none-any.whl

imap_processing/idex/idex_l2c.py

@@ -1,250 +0,0 @@
-"""
-Perform IDEX L2c Processing.
-
-Examples
---------
-.. code-block:: python
-    from imap_processing.idex.idex_l1a import PacketParser
-    from imap_processing.idex.idex_l1b import idex_l1b
-    from imap_processing.idex.idex_l2a import idex_l2a
-    from imap_processing.idex.idex_l2b import idex_l2b
-    from imap_processing.cdf.utils import write_cdf
-
-    l0_file = "imap_processing/tests/idex/imap_idex_l0_sci_20231214_v001.pkts"
-    l1a_data = PacketParser(l0_file)
-    l1b_data = idex_l1b(l1a_data)
-    l2a_data = idex_l2a(l1b_data)
-    l2b_data = idex_l2b(l2a_data)
-    write_cdf(l2b_data)
-"""
-
-import logging
-
-import astropy_healpix.healpy as hp
-import numpy as np
-import xarray as xr
-
-from imap_processing.cdf.imap_cdf_manager import ImapCdfAttributes
-from imap_processing.ena_maps.ena_maps import SkyTilingType
-from imap_processing.ena_maps.utils.coordinates import CoordNames
-from imap_processing.ena_maps.utils.spatial_utils import AzElSkyGrid
-from imap_processing.idex.idex_constants import (
-    IDEX_EVENT_REFERENCE_FRAME,
-    IDEX_HEALPIX_NESTED,
-    IDEX_HEALPIX_NSIDE,
-    IDEX_SPACING_DEG,
-)
-from imap_processing.idex.idex_utils import get_idex_attrs
-
-logger = logging.getLogger(__name__)
-
-
-def idex_l2c(l2b_dataset: xr.Dataset) -> list[xr.Dataset]:
-    """
-    Will process IDEX l2b data to create l2c data products.
-
-    Parameters
-    ----------
-    l2b_dataset : xarray.Dataset
-        IDEX L2b dataset.
-
-    Returns
-    -------
-    l2b_dataset : list[xarray.Dataset]
-        The``xarray`` dataset containing the science data and supporting metadata.
-    """
-    logger.info(
-        f"Running IDEX L2C processing on datasets: "
-        f"{l2b_dataset.attrs['Logical_source']}"
-    )
-    # create the attribute manager for this data level
-    idex_attrs = get_idex_attrs("l2c")
-    # Epoch should be the start of the collection period.
-    # TODO should epoch be start of sci acquisition?
-    epoch = xr.DataArray(
-        l2b_dataset["epoch"].data[0:1].astype(np.int64),
-        name="epoch",
-        dims=["epoch"],
-        attrs=idex_attrs.get_variable_attributes(
-            "epoch_collection_set", check_schema=False
-        ),
-    )
-    l2c_healpix_dataset = idex_healpix_map(l2b_dataset, epoch, idex_attrs)
-    l2c_rectangular_dataset = idex_rectangular_map(l2b_dataset, epoch, idex_attrs)
-
-    # TODO exposure time
-    logger.info("IDEX L2C science data processing completed.")
-    return [l2c_healpix_dataset, l2c_rectangular_dataset]
-
-
-def idex_healpix_map(
-    l1b_dataset: xr.Dataset,
-    epoch_da: xr.DataArray,
-    idex_attrs: ImapCdfAttributes,
-    nside: int = IDEX_HEALPIX_NSIDE,
-    nested: bool = IDEX_HEALPIX_NESTED,
-) -> xr.Dataset:
-    """
-    Create a healpix map out of a l1b dataset.
-
-    Parameters
-    ----------
-    l1b_dataset : xarray.Dataset
-        IDEX L2b dataset.
-    epoch_da : xarray.DataArray
-        Epoch data array of the collection. Size: (1,).
-    idex_attrs : ImapCdfAttributes
-        The attribute manager for this data level.
-    nside : int
-        Healpix nside parameter.
-    nested : bool
-        Healpix nested parameter.
-
-    Returns
-    -------
-    map : xarray.Dataset
-        Spatially binned dust counts in a healpix map format.
-    """
-    longitude = l1b_dataset["longitude"]
-    latitude = l1b_dataset["latitude"]
-
-    # Get the healpix indices
-    hpix_idx = hp.ang2pix(
-        nside, nest=nested, lonlat=True, theta=longitude, phi=latitude
-    )
-
-    n_pix = hp.nside2npix(nside)
-    healpix = xr.DataArray(
-        np.arange(n_pix),
-        name=CoordNames.HEALPIX_INDEX.value,
-        dims=CoordNames.HEALPIX_INDEX.value,
-        attrs=idex_attrs.get_variable_attributes("pixel_index", check_schema=False),
-    )
-
-    # Create a histogram of the raw dust event counts for each pixel
-    counts = np.histogram(hpix_idx, bins=n_pix, range=(0, n_pix))[0]
-    # Add epoch dimension
-    counts_da = xr.DataArray(
-        counts[np.newaxis, :].astype(np.int64),
-        name="counts",
-        dims=("epoch", CoordNames.HEALPIX_INDEX.value),
-        attrs=idex_attrs.get_variable_attributes("healpix_counts"),
-    )
-    pixel_label = xr.DataArray(
-        healpix.astype(str),
-        name="pixel_label",
-        dims="pixel_index",
-        attrs=idex_attrs.get_variable_attributes("pixel_label", check_schema=False),
-    )
-    l2c_dataset = xr.Dataset(
-        coords={CoordNames.HEALPIX_INDEX.value: healpix, "epoch": epoch_da},
-        data_vars={
-            "counts": counts_da,
-            "longitude": longitude,
-            "latitude": latitude,
-            "pixel_label": pixel_label,
-        },
-    )
-    map_attrs = {
-        "Sky_tiling_type": SkyTilingType.HEALPIX.value,
-        "HEALPix_nside": str(nside),
-        "HEALPix_nest": str(nested),
-        "Spice_reference_frame": IDEX_EVENT_REFERENCE_FRAME.name,
-        "num_points": str(n_pix),
-    } | idex_attrs.get_global_attributes("imap_idex_l2c_sci-healpix")
-    l2c_dataset.attrs.update(map_attrs)
-
-    return l2c_dataset
-
-
-def idex_rectangular_map(
-    l1b_dataset: xr.Dataset,
-    epoch_da: xr.DataArray,
-    idex_attrs: ImapCdfAttributes,
-    spacing_deg: int = IDEX_SPACING_DEG,
-) -> xr.Dataset:
-    """
-    Create a rectangular map out of a l1b dataset.
-
-    Parameters
-    ----------
-    l1b_dataset : xarray.Dataset
-        IDEX L2b dataset.
-    epoch_da : xarray.DataArray
-        Epoch data array of the collection. Size: (1,).
-    idex_attrs : ImapCdfAttributes
-        The attribute manager for this data level.
-    spacing_deg : int
-        The spacing in degrees for the rectangular grid.
-
-    Returns
-    -------
-    map : xarray.Dataset
-        Spatially binned dust counts in a rectangular map format.
-    """
-    # Get the rectangular grid with the specified spacing
-    grid = AzElSkyGrid(spacing_deg)
-    # Make sure longitude values are in the range [0, 360)
-    longitude_wrapped = np.mod(l1b_dataset["longitude"], 360)
-    latitude = l1b_dataset["latitude"]
-    # Create a 2d histogram of the raw dust event counts for each pixel using the grid
-    # bin edges
-    counts, _, _ = np.histogram2d(
-        longitude_wrapped, latitude, bins=[grid.az_bin_edges, grid.el_bin_edges]
-    )
-    counts_da = xr.DataArray(
-        counts[np.newaxis, :, :].astype(np.int64),
-        name="counts",
-        dims=("epoch", "rectangular_lon_pixel", "rectangular_lat_pixel"),
-        attrs=idex_attrs.get_variable_attributes("rectangular_counts"),
-    )
-    rec_lon_pixels = xr.DataArray(
-        name="rectangular_lon_pixel",
-        data=grid.az_bin_midpoints,
-        dims="rectangular_lon_pixel",
-        attrs=idex_attrs.get_variable_attributes(
-            "rectangular_lon_pixel", check_schema=False
-        ),
-    )
-    rec_lat_pixels = xr.DataArray(
-        name="rectangular_lat_pixel",
-        data=grid.el_bin_midpoints,
-        dims="rectangular_lat_pixel",
-        attrs=idex_attrs.get_variable_attributes(
-            "rectangular_lat_pixel", check_schema=False
-        ),
-    )
-
-    l2c_dataset = xr.Dataset(
-        coords={
-            "epoch": epoch_da,
-            "rectangular_lon_pixel": rec_lon_pixels,
-            "rectangular_lat_pixel": rec_lat_pixels,
-        },
-        data_vars={
-            "counts": counts_da,
-            "longitude": longitude_wrapped,
-            "latitude": latitude,
-            "rectangular_lon_pixel_label": rec_lon_pixels.astype(str),
-            "rectangular_lat_pixel_label": rec_lat_pixels.astype(str),
-        },
-    )
-    l2c_dataset[
-        "rectangular_lon_pixel_label"
-    ].attrs = idex_attrs.get_variable_attributes(
-        "rectangular_lon_pixel_label", check_schema=False
-    )
-    l2c_dataset[
-        "rectangular_lat_pixel_label"
-    ].attrs = idex_attrs.get_variable_attributes(
-        "rectangular_lat_pixel_label", check_schema=False
-    )
-    map_attrs = {
-        "sky_tiling_type": SkyTilingType.RECTANGULAR.value,
-        "Spacing_degrees": str(spacing_deg),
-        "Spice_reference_frame": IDEX_EVENT_REFERENCE_FRAME.name,
-        "num_points": str(counts.size),
-    } | idex_attrs.get_global_attributes("imap_idex_l2c_sci-rectangular")
-
-    l2c_dataset.attrs.update(map_attrs)
-    return l2c_dataset

imap_processing/spice/kernels.py

@@ -1,187 +0,0 @@
-"""Functions that generate, furnish, and retrieve metadata from SPICE kernels."""
-
-import functools
-import logging
-import os
-from typing import Any, Callable, Optional, Union, overload
-
-import spiceypy
-from spiceypy.utils.exceptions import SpiceyError
-
-from imap_processing import imap_module_directory
-
-logger = logging.getLogger(__name__)
-
-
-# Declarations to help with typing. Taken from mypy documentation on
-# decorator-factories:
-# https://mypy.readthedocs.io/en/stable/generics.html#decorator-factories
-# Bare decorator usage
-@overload
-def ensure_spice(
-    __func: Callable[..., Any],
-) -> Callable[..., Any]: ...  # numpydoc ignore=GL08
-# Decorator with arguments
-@overload
-def ensure_spice(
-    *, time_kernels_only: bool = False
-) -> Callable[[Callable[..., Any]], Callable[..., Any]]: ...  # numpydoc ignore=GL08
-# Implementation
-def ensure_spice(
-    __func: Optional[Callable[..., Any]] = None, *, time_kernels_only: bool = False
-) -> Union[Callable[..., Any], Callable[[Callable[..., Any]], Callable[..., Any]]]:
-    """
-    Decorator/wrapper that automatically furnishes SPICE kernels.
-
-    Parameters
-    ----------
-    __func : Callable
-        The function requiring SPICE that we are going to wrap if being used
-        explicitly, otherwise None, in which case ensure_spice is being used,
-        not as a function wrapper (see l2a_processing.py) but as a true
-        decorator without an explicit function argument.
-    time_kernels_only : bool
-        Specify that we only need to furnish time kernels (if SPICE_METAKERNEL
-        is set, we still just furnish that metakernel and assume the time
-        kernels are included.
-
-    Returns
-    -------
-    Callable
-        Decorated function, with spice error handling.
-
-    Notes
-    -----
-    Before trying to understand this piece of code, read this:
-    https://stackoverflow.com/questions/5929107/decorators-with-parameters/60832711#60832711
-
-    **Control flow overview:**
-
-    1. Try simply calling the wrapped function naively.
-        * SUCCESS? Great! We're done.
-        * SpiceyError? Go to step 2.
-
-    2. Furnish metakernel at SPICE_METAKERNEL
-        * SUCCESS? Great, return the original function again (so it can be
-          re-run).
-        * KeyError? Seems like SPICE_METAKERNEL isn't set, no problem. Go to
-          step 3.
-
-    3. Did we get the parameter time_kernels_only=True?
-        * YES? We only need LSK and SCLK kernels to run this function. Go fetch
-          those and furnish and return the original function (so it can be re-run).
-        * NO? Dang. This is sort of the end of the line. Re-raise the error
-          generated from the failed spiceypy function call but add a better
-          message to it.
-
-    Examples
-    --------
-    There are three ways to use this object
-
-    1. A decorator with no arguments
-
-        >>> @ensure_spice
-        ... def my_spicey_func(a, b):
-        ...     pass
-
-    2. A decorator with parameters. This is useful
-       if we only need the latest SCLK and LSK kernels for the function involved.
-
-        >>> @ensure_spice(time_kernels_only=True)
-        ... def my_spicey_time_func(a, b):
-        ...     pass
-
-    3. An explicit wrapper function, providing a dynamically set value for
-       parameters, e.g. time_kernels_only
-
-        >>> wrapped = ensure_spice(spicey_func, time_kernels_only=True)
-        ... result = wrapped(args, kwargs)
-    """
-
-    def _decorator(func: Callable[..., Callable]) -> Callable:
-        """
-        Decorate or wrap input function depending on how ensure_spice is used.
-
-        Parameters
-        ----------
-        func : Callable
-            The function to be decorated/wrapped.
-
-        Returns
-        -------
-        Callable
-            If used as a function wrapper, the decorated function is returned.
-        """
-
-        @functools.wraps(func)
-        def wrapper_ensure_spice(*args: Any, **kwargs: Any) -> Any:
-            """
-            Wrap the function that ensure_spice is used on.
-
-            Parameters
-            ----------
-            *args : list
-                The positional arguments passed to the decorated function.
-            **kwargs
-                The keyword arguments passed to the decorated function.
-
-            Returns
-            -------
-            Object
-                Output from wrapped function.
-            """
-            try:
-                # Step 1.
-                return func(
-                    *args, **kwargs
-                )  # Naive first try. Maybe SPICE is already furnished.
-            except SpiceyError as spicey_err:
-                try:
-                    # Step 2.
-                    if os.getenv("SPICE_METAKERNEL"):
-                        metakernel_path = os.getenv("SPICE_METAKERNEL")
-                        spiceypy.furnsh(metakernel_path)
-                    else:
-                        furnish_time_kernel()
-                except KeyError:
-                    # TODO: An additional step that was used on EMUS was to get
-                    #  a custom metakernel from the SDC API based on an input
-                    #  time range.
-                    if time_kernels_only:
-                        # Step 3.
-                        # TODO: Decide if this is useful for IMAP. Possible
-                        #  implementation could include downloading
-                        #  the most recent leapsecond kernel from NAIF (see:
-                        #  https://lasp.colorado.edu/nucleus/projects/LIBSDC/repos/libera_utils/browse/libera_utils/spice_utils.py
-                        #  for LIBERA implementation of downloading and caching
-                        #  kernels) and finding the most recent IMAP clock
-                        #  kernel in EFS.
-                        raise NotImplementedError from spicey_err
-                    else:
-                        raise SpiceyError(
-                            "When calling a function requiring SPICE, we failed "
-                            "to load a metakernel. SPICE_METAKERNEL is not set,"
-                            "and time_kernels_only is not set to True"
-                        ) from spicey_err
-                return func(*args, **kwargs)
-
-        return wrapper_ensure_spice
-
-    # Note: This return was originally implemented as a ternary operator, but
-    # this caused mypy to fail due to this bug:
-    # https://github.com/python/mypy/issues/4134
-    if callable(__func):
-        return _decorator(__func)
-    else:
-        return _decorator
-
-
-def furnish_time_kernel() -> None:
-    """Furnish the time kernels."""
-    spice_test_data_path = imap_module_directory / "tests/spice/test_data"
-
-    # TODO: we need to load these kernels from EFS volumen that is
-    # mounted to batch volume and extend this to generate metakernell
-    # which is TBD.
-    spiceypy.furnsh(str(spice_test_data_path / "imap_sclk_0000.tsc"))
-    spiceypy.furnsh(str(spice_test_data_path / "naif0012.tls"))