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

imap_processing/ena_maps/ena_maps.py

@@ -2,10 +2,12 @@
 
 from __future__ import annotations
 
+import json
 import logging
-import pathlib
 from abc import ABC, abstractmethod
 from enum import Enum
+from pathlib import Path
+from typing import TypeVar
 
 import astropy_healpix.healpy as hp
 import numpy as np
@@ -23,6 +25,9 @@ from imap_processing.spice.time import ttj2000ns_to_et
 
 logger = logging.getLogger(__name__)
 
+# Set the maximum recursion depth for the conversion from Healpix to rectangular SkyMap.
+MAX_SUBDIV_RECURSION_DEPTH = 8
+
 
 class SkyTilingType(Enum):
     """Enumeration of the types of tiling used in the ENA maps."""
@@ -133,9 +138,9 @@ def match_coords_to_indices(
     # which must be converted to ephemeris time (ET) for SPICE.
     if event_et is None:
         if isinstance(input_object, PointingSet):
-            event_et = ttj2000ns_to_et(input_object.data["epoch"].values)
+            event_et = ttj2000ns_to_et(input_object.epoch)
         elif isinstance(output_object, PointingSet):
-            event_et = ttj2000ns_to_et(output_object.data["epoch"].values)
+            event_et = ttj2000ns_to_et(output_object.epoch)
         else:
             raise ValueError(
                 "Event time must be specified if both objects are SkyMaps."
@@ -199,6 +204,11 @@ def match_coords_to_indices(
     return flat_indices_input_grid_output_frame
 
 
+# Define a TypeVar type to dynamically hint the return type of the base PointingSet
+# class classmethod
+T = TypeVar("T", bound="PointingSet")
+
+
 # Define the pointing set classes
 class PointingSet(ABC):
     """
@@ -209,20 +219,69 @@ class PointingSet(ABC):
 
     Parameters
     ----------
-    dataset : xr.Dataset
-        Dataset containing the pointing set data.
+    dataset : xr.Dataset | str | Path
+        Dataset or path to CDF file containing the pointing set data.
     spice_reference_frame : geometry.SpiceFrame
         The reference Spice frame of the pointing set.
     """
 
+    # The minimum set of class attributes for any PointingSet to function with
+    # a SkyMap using only the PUSH method of projecting are defined here.
+
+    # ======== Attributes that are set in the ABC __init__ method ========
+    # The xarray.Dataset containing the data from the PSET CDF
+    data: xr.Dataset
+    # The spice frame that the az_el_points are expressed in
+    spice_reference_frame: geometry.SpiceFrame
+
+    # ======== Attributes required to be set in a subclass ========
+    # Azimuth and elevation coordinates of each spatial pixel. The ndarray should
+    # have the shape (n, 2) where n is the number of spatial pixels
+    az_el_points: np.ndarray
+    # Tuple containing the names of each spatial coordinate of the xarray.Dataset
+    # stored in the data attribute
+    spatial_coords: tuple[str, ...]
+
     @abstractmethod
-    def __init__(self, dataset: xr.Dataset, spice_reference_frame: geometry.SpiceFrame):
+    def __init__(
+        self,
+        dataset: xr.Dataset | str | Path,
+        spice_reference_frame: geometry.SpiceFrame = geometry.SpiceFrame.IMAP_DPS,
+    ):
         """Abstract method to initialize the pointing set object."""
         self.spice_reference_frame = spice_reference_frame
-        self.num_points = 0
-        self.az_el_points = np.zeros((self.num_points, 2))
-        self.data = xr.Dataset()
-        self.spatial_coords: tuple[str, ...] = ()
+
+        if isinstance(dataset, (str, Path)):
+            dataset = load_cdf(dataset)
+        self.data = dataset
+
+        # A PSET must have a single epoch
+        if len(np.unique(self.data["epoch"].values)) > 1:
+            raise ValueError("Multiple epochs found in the dataset.")
+
+    @property
+    def num_points(self) -> int:
+        """
+        The number of spatial pixels in the pointing set.
+
+        Returns
+        -------
+        num_points: int
+            The number of spatial pixels in the pointing set.
+        """
+        return self.az_el_points.shape[0]
+
+    @property
+    def epoch(self) -> int:
+        """
+        The singular epoch value from the xarray.Dataset.
+
+        Returns
+        -------
+        epoch: int
+            The epoch value [J2000 TT ns] of the pointing set.
+        """
+        return self.data["epoch"].values[0]
 
     @property
     def unwrapped_dims_dict(self) -> dict[str, tuple[str, ...]]:
@@ -234,7 +293,7 @@ class PointingSet(ABC):
         unwrapped_dims_dict : dict[str, tuple[str, ...]]
             Dictionary of variable names and their dimensions, with only 1 spatial dim.
             The generic pixel dimension is always included.
-            E.g.: {"counts": ("epoch", "energy_bin_center", "pixel")} .
+            E.g.: {"counts": ("epoch", "energy", "pixel")} .
         """
         variable_dims = {}
         for var_name in self.data.data_vars:
@@ -287,8 +346,8 @@ class RectangularPointingSet(PointingSet):
 
     Parameters
     ----------
-    l1c_dataset : xr.Dataset | pathlib.Path | str
-        L1c xarray dataset containing the pointing set data or the path to the dataset.
+    dataset : xr.Dataset | str | Path
+        Dataset or path to CDF file containing the pointing set data.
         Currently, the dataset is expected to be tiled in a rectangular grid,
         with data_vars indexed along the coordinates:
             - 'epoch' : time value (1 value per PSET)
@@ -306,26 +365,19 @@ class RectangularPointingSet(PointingSet):
         If multiple epochs are found in the dataset.
     """
 
+    # In addition to the required attributes defined in the base PointingSet
+    # class, the following attributes are required for a RectangularPointingSet
+    # to be projected using the PULL method.
+    tiling_type: SkyTilingType = SkyTilingType.RECTANGULAR
+    sky_grid: spatial_utils.AzElSkyGrid
+
     def __init__(
         self,
-        l1c_dataset: xr.Dataset | pathlib.Path | str,
+        dataset: xr.Dataset | str | Path,
         spice_reference_frame: geometry.SpiceFrame = geometry.SpiceFrame.IMAP_DPS,
     ):
-        # Store the reference frame of the pointing set
-        self.spice_reference_frame = spice_reference_frame
-
-        # Read in the data and store the xarray dataset as data attr
-        if isinstance(l1c_dataset, (str, pathlib.Path)):
-            self.data = load_cdf(pathlib.Path(l1c_dataset))
-        elif isinstance(l1c_dataset, xr.Dataset):
-            self.data = l1c_dataset
-
-        # A PSET must have a single epoch
-        self.epoch = self.data["epoch"].values
-        if len(np.unique(self.epoch)) > 1:
-            raise ValueError("Multiple epochs found in the dataset.")
+        super().__init__(dataset, spice_reference_frame)
 
-        self.tiling_type = SkyTilingType.RECTANGULAR
         self.spatial_coords = (
             CoordNames.AZIMUTH_L1C.value,
             CoordNames.ELEVATION_L1C.value,
@@ -344,12 +396,12 @@ class RectangularPointingSet(PointingSet):
                 "Azimuth and elevation bin spacing do not match: "
                 f"az {az_bin_delta[0]} != el {el_bin_delta[0]}."
             )
-        self.spacing_deg = az_bin_delta[0]
+        spacing_deg = az_bin_delta[0]
 
         # Build the az/azimuth and el/elevation grids with an AzElSkyGrid object
         # and check that the 1D axes match the dataset's az and el.
         self.sky_grid = spatial_utils.AzElSkyGrid(
-            spacing_deg=self.spacing_deg,
+            spacing_deg=spacing_deg,
         )
 
         for dim, constructed_bins in zip(
@@ -378,23 +430,47 @@ class RectangularPointingSet(PointingSet):
                 self.sky_grid.el_grid.ravel(),
             )
         )
-        self.num_points = self.az_el_points.shape[0]
 
-        # Also store the bin edges for the pointing set to allow for "pull" method
-        # of index matching (not yet implemented).
-        # These are 1D arrays of different lengths and cannot be stacked.
-        self.az_bin_edges = self.sky_grid.az_bin_edges
-        self.el_bin_edges = self.sky_grid.el_bin_edges
 
+class HealpixPointingSet(PointingSet, ABC):
+    """
+    Abstract base class for Healpix pointing sets.
+
+    Defines additional properties and absract properties that are required
+    for a PointingSet instance to be used with the match_coords_to_indices
+    function.
+    """
+
+    tiling_type: SkyTilingType = SkyTilingType.HEALPIX
+
+    @property
+    def nside(self) -> int:
+        """
+        Number of pixels on the side of one of the 12 top-level healpix tiles.
+
+        Returns
+        -------
+        npix: int
+            The number of pixels on the side of one of the 12 ‘top-level’ healpix
+            tiles.
+        """
+        return hp.npix_to_nside(self.num_points)
 
-class UltraPointingSet(PointingSet):
+    @property
+    @abstractmethod
+    def nested(self) -> bool:
+        """Abstract property for getting nested boolean."""
+        raise NotImplementedError
+
+
+class UltraPointingSet(HealpixPointingSet):
     """
     Pointing set object specifically for Healpix-tiled ULTRA data, nominally at Level1C.
 
     Parameters
     ----------
-    l1c_dataset : xr.Dataset | pathlib.Path | str
-        L1c xarray dataset containing the pointing set data or the path to the dataset.
+    dataset : xr.Dataset | str | Path
+        Dataset or path to CDF file containing the pointing set data.
         Currently, the dataset is expected to be tiled in a HEALPix tessellation,
         with data_vars indexed along the coordinates:
             - 'epoch' : time value (1 value per PSET, from the mean of the PSET)
@@ -415,36 +491,19 @@ class UltraPointingSet(PointingSet):
 
     def __init__(
         self,
-        l1c_dataset: xr.Dataset | pathlib.Path | str,
+        dataset: xr.Dataset | str | Path,
         spice_reference_frame: geometry.SpiceFrame = geometry.SpiceFrame.IMAP_DPS,
     ):
-        # Store the reference frame of the pointing set
-        self.spice_reference_frame = spice_reference_frame
-
-        # Read in the data and store the xarray dataset as data attr
-        if isinstance(l1c_dataset, (str, pathlib.Path)):
-            self.data = load_cdf(pathlib.Path(l1c_dataset))
-        elif isinstance(l1c_dataset, xr.Dataset):
-            self.data = l1c_dataset
+        super().__init__(dataset, spice_reference_frame)
 
-        # A PSET must have a single epoch
-        self.epoch = self.data["epoch"].values
-        if len(np.unique(self.epoch)) > 1:
-            raise ValueError("Multiple epochs found in the dataset.")
-
-        # Set the tiling type and number of points
-        self.tiling_type = SkyTilingType.HEALPIX
+        # Set the spatial coordinates and number of points
         self.spatial_coords = (CoordNames.HEALPIX_INDEX.value,)
-        self.num_points = self.data[CoordNames.HEALPIX_INDEX.value].size
-        self.nside = hp.npix_to_nside(self.num_points)
 
-        # Determine if the HEALPix tessellation is nested, default is False
-        self.nested = bool(
-            self.data[CoordNames.HEALPIX_INDEX.value].attrs.get("nested", False)
-        )
+        # Tracks Per-Pixel Solid Angle in steradians.
+        self.solid_angle = hp.nside2pixarea(self.nside, degrees=False)
 
         # Get the azimuth and elevation coordinates of the healpix pixel centers (deg)
-        self.azimuth_pixel_center, self.elevation_pixel_center = hp.pix2ang(
+        azimuth_pixel_center, elevation_pixel_center = hp.pix2ang(
             nside=self.nside,
             ipix=np.arange(self.num_points),
             nest=self.nested,
@@ -457,7 +516,7 @@ class UltraPointingSet(PointingSet):
         # (e.g. "longitude"/"latitude" vs "azimuth"/"elevation").
         for dim, constructed_bins in zip(
             [CoordNames.AZIMUTH_L1C.value, CoordNames.ELEVATION_L1C.value],
-            [self.azimuth_pixel_center, self.elevation_pixel_center],
+            [azimuth_pixel_center, elevation_pixel_center],
         ):
             if not np.allclose(
                 self.data[dim],
@@ -475,7 +534,33 @@ class UltraPointingSet(PointingSet):
         # of shape (num_points, 2) where column 0 is the lon/az
         # and column 1 is the lat/el.
         self.az_el_points = np.column_stack(
-            (self.azimuth_pixel_center, self.elevation_pixel_center)
+            (azimuth_pixel_center, elevation_pixel_center)
+        )
+
+    @property
+    def num_points(self) -> int:
+        """
+        Override the base class property to get the number from the dataset.
+
+        Returns
+        -------
+        num_points: int
+            The number of healpix pixels in the pointing set.
+        """
+        return self.data[CoordNames.HEALPIX_INDEX.value].size
+
+    @property
+    def nested(self) -> bool:
+        """
+        Whether the healpix tessellation is nested.
+
+        Returns
+        -------
+        nested: bool
+            Whether the healpix tessellation is nested.
+        """
+        return bool(
+            self.data[CoordNames.HEALPIX_INDEX.value].attrs.get("nested", False)
         )
 
     def __repr__(self) -> str:
@@ -494,6 +579,27 @@ class UltraPointingSet(PointingSet):
         )
 
 
+class HiPointingSet(PointingSet):
+    """
+    PointingSet object specific to Hi L1C PSet data.
+
+    Parameters
+    ----------
+    dataset : xarray.Dataset
+        Hi L1C pointing set data loaded in an xarray.DataArray.
+    """
+
+    def __init__(self, dataset: xr.Dataset):
+        super().__init__(dataset, spice_reference_frame=geometry.SpiceFrame.ECLIPJ2000)
+        self.az_el_points = np.column_stack(
+            (
+                np.squeeze(self.data["hae_longitude"]),
+                np.squeeze(self.data["hae_latitude"]),
+            )
+        )
+        self.spatial_coords = ("spin_angle_bin",)
+
+
 # Define the Map classes
 class AbstractSkyMap(ABC):
     """
@@ -519,6 +625,10 @@ class AbstractSkyMap(ABC):
         self.binning_grid_shape: tuple[int, ...]
         self.data_1d: xr.Dataset
 
+        # Initialize values to be used by the instrument code to push/pull
+        self.values_to_push_project: list[str] = []
+        self.values_to_pull_project: list[str] = []
+
     def to_dataset(self) -> xr.Dataset:
         """
         Get the SkyMap data as a formatted xarray Dataset.
@@ -685,8 +795,164 @@ class AbstractSkyMap(ABC):
                     "Only PUSH and PULL index matching methods are supported."
                 )
 
+            # TODO: we may need to allow for unweighted/weighted means here by
+            # dividing pointing_projected_values by some binned weights.
+            # For unweighted means, we could use the number of pointing set pixels
+            # that correspond to each map pixel as the weights.
             self.data_1d[value_key] += pointing_projected_values
 
+    @classmethod
+    def from_json(cls, json_path: str | Path) -> RectangularSkyMap | HealpixSkyMap:
+        """
+        Create a SkyMap object from a JSON configuration file.
+
+        Parameters
+        ----------
+        json_path : str | Path
+            Path to the JSON configuration file.
+
+        Returns
+        -------
+        RectangularSkyMap | HealpixSkyMap
+            An instance of a SkyMap object with the specified properties.
+        """
+        with open(json_path) as f:
+            properties = json.load(f)
+        return cls.from_dict(properties)
+
+    @classmethod
+    def from_dict(cls, properties: dict) -> RectangularSkyMap | HealpixSkyMap:
+        """
+        Create a SkyMap object from a dictionary of properties.
+
+        Parameters
+        ----------
+        properties : dict
+            Dictionary containing the map properties. The required keys are:
+            - "spice_reference_frame" : str
+                The reference Spice frame of the map as a string. The available
+                options are defined in the spice geometry module:
+                `imap_processing.geometry.spice.SpiceFrame`. Example: "ECLIPJ2000".
+            - "sky_tiling_type" : str
+                The type of sky tiling, either "HEALPIX" or "RECTANGULAR".
+            - if "HEALPIX":
+                - "nside" : int
+                    The nside parameter for the Healpix tessellation.
+                - "nested" : bool
+                    Whether the Healpix tessellation is nested or not.
+            - if "RECTANGULAR":
+                - "spacing_deg" : float
+                    The spacing of the rectangular grid in degrees.
+            - "values_to_push_project" : list[str], optional
+                The names of the variables to project to the map with the PUSH method.
+                NOTE: The projection is done by the instrument code, so this value can
+                only be used to inform that code. No values are projected automatically.
+            - "values_to_pull_project" : list[str], optional
+                The names of the variables to project to the map with the PULL method.
+                See the above note for more details.
+
+            See example dictionary in notes section.
+
+        Returns
+        -------
+        RectangularSkyMap | HealpixSkyMap
+            An instance of a SkyMap object with the specified properties.
+
+        Raises
+        ------
+        ValueError
+            If the sky tiling type is not recognized.
+
+        Notes
+        -----
+        Example dictionary:
+
+        ```python
+        properties = {
+            "spice_reference_frame": "ECLIPJ2000",
+            "sky_tiling_type": "HEALPIX",
+            "nside": 32,
+            "nested": False,
+            "values_to_push_project": ['counts', 'flux'],
+            "values_to_pull_project": []
+        }
+        ```
+        """
+        sky_tiling_type = SkyTilingType[properties["sky_tiling_type"].upper()]
+        spice_reference_frame = geometry.SpiceFrame[properties["spice_reference_frame"]]
+
+        skymap: RectangularSkyMap | HealpixSkyMap  # Mypy gets confused by if/elif types
+        if sky_tiling_type is SkyTilingType.HEALPIX:
+            skymap = HealpixSkyMap(
+                nside=properties["nside"],
+                nested=properties["nested"],
+                spice_frame=spice_reference_frame,
+            )
+        elif sky_tiling_type is SkyTilingType.RECTANGULAR:
+            skymap = RectangularSkyMap(
+                spacing_deg=properties["spacing_deg"],
+                spice_frame=spice_reference_frame,
+            )
+        else:
+            raise ValueError(
+                f"Unknown sky tiling type: {sky_tiling_type}. "
+                f"Must be one of: {SkyTilingType.__members__.keys()}"
+            )
+
+        # Store requested variables to push/pull, which will be done by the instrument
+        # code which creates and uses the SkyMap object.
+        skymap.values_to_push_project = properties.get("values_to_push_project", [])
+        skymap.values_to_pull_project = properties.get("values_to_pull_project", [])
+        return skymap
+
+    def to_dict(self) -> dict:
+        """
+        Convert the SkyMap object to a dictionary of properties.
+
+        Returns
+        -------
+        dict
+            Dictionary containing the map properties.
+        """
+        if isinstance(self, HealpixSkyMap):
+            map_properties_dict = {
+                "sky_tiling_type": "HEALPIX",
+                "spice_reference_frame": self.spice_reference_frame.name,
+                "nside": self.nside,
+                "nested": self.nested,
+            }
+        elif isinstance(self, RectangularSkyMap):
+            map_properties_dict = {
+                "sky_tiling_type": "RECTANGULAR",
+                "spice_reference_frame": self.spice_reference_frame.name,
+                "spacing_deg": self.spacing_deg,
+            }
+        else:
+            raise ValueError(
+                f"Unknown SkyMap type: {self.__class__.__name__}. "
+                f"Must be one of: {AbstractSkyMap.__subclasses__()}"
+            )
+
+        map_properties_dict["values_to_push_project"] = (
+            self.values_to_push_project if self.values_to_push_project else []
+        )
+        map_properties_dict["values_to_pull_project"] = (
+            self.values_to_pull_project if self.values_to_pull_project else []
+        )
+        return map_properties_dict
+
+    def to_json(self, json_path: str | Path) -> None:
+        """
+        Save the SkyMap object to a JSON configuration file.
+
+        Parameters
+        ----------
+        json_path : str | Path
+            Path to the JSON file where the properties will be saved.
+        """
+        with open(json_path, "w") as f:
+            json.dump(self.to_dict(), f, indent=4)
+
 
 class RectangularSkyMap(AbstractSkyMap):
     """
@@ -720,7 +986,7 @@ class RectangularSkyMap(AbstractSkyMap):
     in degrees, with a spacing of 30 degrees. There will be 12 azimuth bins and 6
     elevation bins in this example, resulting in 72 pixels in the map.
 
-    A multidimentional value (e.g. counts, with energy levels at each pixel)
+    A multidimensional value (e.g. counts, with energy levels at each pixel)
     will be stored as a 2D array with the first axis as the energy dimension and the
     second axis as the pixel index.
 
@@ -749,6 +1015,10 @@ class RectangularSkyMap(AbstractSkyMap):
         # The reference Spice frame of the map, in which angles are defined
         self.spice_reference_frame = spice_frame
 
+        # Initialize values to be used by the instrument code to push/pull
+        self.values_to_push_project: list[str] = []
+        self.values_to_pull_project: list[str] = []
+
         # Angular spacing of the map grid (degrees) defines the number, size of pixels.
         self.spacing_deg = spacing_deg
         self.sky_grid = spatial_utils.AzElSkyGrid(
@@ -829,6 +1099,10 @@ class HealpixSkyMap(AbstractSkyMap):
         self.tiling_type = SkyTilingType.HEALPIX
         self.spice_reference_frame = spice_frame
 
+        # Initialize values to be used by the instrument code to push/pull
+        self.values_to_push_project: list[str] = []
+        self.values_to_pull_project: list[str] = []
+
         # Tile the sky with a Healpix tessellation. Defined by nside, nested parameters.
         self.nside = nside
         self.nested = nested
@@ -867,6 +1141,325 @@ class HealpixSkyMap(AbstractSkyMap):
             }
         )
 
+    # Define several methods for converting a Healpix map to a Rectangular map:
+    def calculate_rect_pixel_value_from_healpix_map_n_subdivisions(
+        self,
+        rect_pix_center_lon_lat: np.typing.NDArray | tuple[float, float],
+        rect_pix_spacing_deg: float,
+        value_array: xr.DataArray,
+        num_subdivisions: int,
+    ) -> np.typing.NDArray:
+        """
+        Interpolate the value of a rectangular pixel from a healpix map w/ subdivisions.
+
+        This function splits a single rectangular pixel into smaller subpixels
+        and calculates the solid angle weighted mean value of
+        the healpix map at all of the subpixel centers.
+
+        Parameters
+        ----------
+        rect_pix_center_lon_lat : np.typing.NDArray | tuple[float, float]
+            The center longitude and latitude of the rectangular pixel.
+        rect_pix_spacing_deg : float
+            The spacing of the rectangular pixel in degrees.
+        value_array : xr.DataArray
+            The data array containing the healpix map values.
+        num_subdivisions : int
+            The number of subdivisions to create for the rectangular pixel.
+            The more subdivisions, the more accurate the interpolation, but also
+            the more computationally expensive it is.
+
+        Returns
+        -------
+        np.typing.NDArray
+            The mean value of the healpix map at the subpixel centers.
+
+            If value_array has a single value at each pixel, the output
+            will be a single value, but if there are other dimensions,
+            (e.g., if self.data_1d['flux'].sizes =
+            {"epoch": 1, "energy": 24, "pixel": 16200}),
+            the output will be an array with the same dims except the pixel dimension
+            (e.g., (1, 24)).
+        """
+        # Assumes that you already checked the pixel doesn't fall entirely in an HP pix
+        # TODO: Ask Nick if we need to add this here to mimic his code.
+        # It shouldn't really be necessary, as the next function
+        # get_pixel_value_recursive_subdivs will finish at 1 subdivision
+
+        # Ensure input contains lon in the first column and lat in the second column
+        rect_pix_center_lon_lat = np.array(rect_pix_center_lon_lat).reshape(-1, 2)
+
+        # Calculate the number of subdivisions and the spacing of the subpixels
+        # Then calculate the subpixel centers
+        n_subpix_side = 2**num_subdivisions
+        subpix_spacing = rect_pix_spacing_deg / n_subpix_side
+        left_edge_lon = rect_pix_center_lon_lat[:, 0] - rect_pix_spacing_deg / 2
+        bottom_edge_lat = rect_pix_center_lon_lat[:, 1] - rect_pix_spacing_deg / 2
+
+        rect_subpix_lon_ctrs = (
+            left_edge_lon
+            + subpix_spacing * np.arange(n_subpix_side)
+            + subpix_spacing / 2
+        )
+        rect_subpix_lat_ctrs = (
+            bottom_edge_lat
+            + subpix_spacing * np.arange(n_subpix_side)
+            + subpix_spacing / 2
+        )
+
+        # We must weight by solid angle, which is not exactly equal for all subpixels
+        # Calculate the solid angle of the full rectangular pixel (sterad)
+        full_rect_pixel_solid_angle = np.deg2rad(rect_pix_spacing_deg) * (
+            np.sin(np.deg2rad(bottom_edge_lat + rect_pix_spacing_deg))
+            - np.sin(np.deg2rad(bottom_edge_lat))
+        )
+
+        # Calculate solid angle of each subpix from the rect_subpix_lat_ctrs (sterad)
+        all_edges_lat = bottom_edge_lat + np.arange(n_subpix_side + 1) * subpix_spacing
+        sine_all_edges_lat = np.sin(np.deg2rad(all_edges_lat))
+        rect_subpix_solid_angle_by_lat = np.diff(sine_all_edges_lat) * np.deg2rad(
+            subpix_spacing
+        )
+        rect_subpix_solid_angle_by_lat = np.repeat(
+            rect_subpix_solid_angle_by_lat[np.newaxis, :], n_subpix_side, axis=0
+        ).reshape(-1)
+
+        rect_subpix_ctrs = (
+            np.array(
+                np.meshgrid(rect_subpix_lon_ctrs, rect_subpix_lat_ctrs, indexing="ij")
+            )
+            .reshape(2, -1)
+            .T
+        )
+
+        # Get the healpix pixel indices at the rectangular subpixel centers
+        hp_pix_at_rect_subpix_ctrs = hp.ang2pix(
+            nside=self.nside,
+            nest=self.nested,
+            theta=rect_subpix_ctrs[:, 0],
+            phi=rect_subpix_ctrs[:, 1],
+            lonlat=True,
+        )
+        # Get the healpix values at the rectangular subpixel centers
+        hp_vals_at_rect_pix_ctrs = value_array.values[..., hp_pix_at_rect_subpix_ctrs]
+
+        # Weighted mean (weighted by solid angle) of these values over the pixel axis,
+        # which is the last axis of this array
+        weighted_hp_vals_at_rect_pix_ctrs = (
+            hp_vals_at_rect_pix_ctrs * rect_subpix_solid_angle_by_lat
+        )
+        mean_pixel_value = (
+            weighted_hp_vals_at_rect_pix_ctrs.sum(axis=-1) / full_rect_pixel_solid_angle
+        )
+        # Log the mean pixel value and the number of subdivisions for debugging
+        logger.debug(
+            f"    Mean pixel value at Number of subdivisions: {num_subdivisions}: "
+            f"array of shape {mean_pixel_value.shape}: {mean_pixel_value}"
+        )
+        return mean_pixel_value
+
+    def get_rect_pixel_value_recursive_subdivs(
+        self,
+        rect_pix_center_lon_lat: np.typing.NDArray | tuple[float, float],
+        rect_pix_spacing_deg: float,
+        value_array: xr.DataArray,
+        *,
+        rtol: float = 1e-3,
+        atol: float = 1e-12,
+        max_subdivision_depth: int = MAX_SUBDIV_RECURSION_DEPTH,
+    ) -> tuple[np.typing.NDArray, int]:
+        """
+        Recursively subdivide a rectangular pixel to get a mean value within tolerances.
+
+        Takes a rectangular pixel, and recursively breaks it up into
+        smaller and smaller subpixels, then calculates the solid-angle weighted mean
+        of the healpix map's value at this pixel, until the difference
+        between the mean values of two consecutive subdivisions is within the
+        specified tolerances. The function returns the mean value at the final level
+        of subdivision and the depth of recursion.
+
+        Parameters
+        ----------
+        rect_pix_center_lon_lat : np.typing.NDArray | tuple[float, float]
+            The center longitude and latitude of the rectangular pixel.
+        rect_pix_spacing_deg : float
+            The spacing of the rectangular pixel in degrees.
+        value_array : xr.DataArray
+            The data array containing the healpix map values to interpolate from.
+        rtol : float, optional
+            The relative tolerance for convergence, by default 1e-3.
+        atol : float, optional
+            The absolute tolerance for convergence, by default 1e-12.
+        max_subdivision_depth : int, optional
+            The maximum depth of recursion for subdivision,
+            by default MAX_SUBDIV_RECURSION_DEPTH.
+            Computation grows exponentially with depth, but only where the value
+            has a significant gradient between adjacent healpix pixels.
+            If the value is smooth, the recursion depth will be low.
+
+        Returns
+        -------
+        tuple[list[float], int]
+            The mean value at the final level of subdivision and the depth of recursion.
+        """
+        # Recursively subdivide a pixel and calculate its mean value until either the
+        # difference between consecutive levels is within the specified tolerances
+        # or the maximum recursion depth is reached
+        depth = 0
+        previous_mean_pixel_value: NDArray = np.full((1,), np.nan)
+        while depth < max_subdivision_depth:
+            mean_pixel_value = (
+                self.calculate_rect_pixel_value_from_healpix_map_n_subdivisions(
+                    rect_pix_center_lon_lat=rect_pix_center_lon_lat,
+                    rect_pix_spacing_deg=rect_pix_spacing_deg,
+                    value_array=value_array,
+                    num_subdivisions=depth,
+                )
+            )
+
+            # Determine if tolerance is met
+            # (skip on the 0th iteration, as there's no delta)
+            if depth > 0:
+                # TODO: Ask Nick/Ultra Instrument team if we need to compare each value
+                # in the pixel's array, or just the mean value.
+                if np.isclose(
+                    mean_pixel_value.mean(),
+                    previous_mean_pixel_value.mean(),
+                    rtol=rtol,
+                    atol=atol,
+                ):
+                    break
+            depth += 1
+            previous_mean_pixel_value = mean_pixel_value
+
+        logger.debug(
+            f"Pixel at ({rect_pix_center_lon_lat} deg size={rect_pix_spacing_deg} deg,)"
+            f" converged to {mean_pixel_value.mean()} in {depth} subdivisions."
+            f" Previous mean was {previous_mean_pixel_value.mean()}."
+        )
+        # Only keep the last (best) mean pixel value
+        return mean_pixel_value, depth
+
+    def to_rectangular_skymap(
+        self,
+        rect_spacing_deg: float,
+        value_keys: list[str],
+        max_subdivision_depth: int = MAX_SUBDIV_RECURSION_DEPTH,
+    ) -> tuple[RectangularSkyMap, dict[str, np.typing.NDArray]]:
+        """
+        Interpolate a healpix map to a rectangular map using recursive subdivision.
+
+        Parameters
+        ----------
+        rect_spacing_deg : float
+            The spacing of the rectangular map in degrees.
+        value_keys : list[str]
+            The names of the values to interpolate from the healpix map.
+            Each must be independently interpolated because the subdivision depth
+            depends on the gradient of the value between adjacent healpix pixels.
+        max_subdivision_depth : int, optional
+            The maximum depth of recursion for subdivision,
+            by default MAX_SUBDIV_RECURSION_DEPTH.
+
+        Returns
+        -------
+        tuple[RectangularSkyMap, dict[str, np.typing.NDArray]]
+            A RectangularSkyMap containing the interpolated values, and a dictionary of
+            each value and its corresponding subdivision depth by pixel.
+        """
+        # Begin by defining the rectangular map we want to create, which must be
+        # in the same spice reference frame as the healpix map
+        rect_map = RectangularSkyMap(
+            spacing_deg=rect_spacing_deg,
+            spice_frame=self.spice_reference_frame,
+        )
+
+        # Depending on the maximum recursion depth, the number of pixels in the
+        # RectangularSkyMap, and the number of value keys, and especially on the
+        # gradients of the values, the number of operations can be very large, so
+        # log key information about the expected number of operations.
+        approx_max_operations = (
+            (4**max_subdivision_depth) * self.num_points * len(value_keys)
+        )
+        logger.info(
+            f"Converting from a HealpixSkyMap(nside={self.nside}) to a "
+            f"RectangularSkyMap(spacing_deg={rect_spacing_deg}) with recursive "
+            "subdivision.\n The maximum recursion depth is "
+            f"{max_subdivision_depth}, yielding a maximum number of healpix calls"
+            f" of {approx_max_operations:.3e}."
+        )
+
+        # Dict to hold the subdivision depth by pixel for each value key
+        subdiv_depth_dict = {}
+        for value_key in value_keys:
+            # For each of the values, calculate each pixel's value with
+            # recursive subdivision. Unfortunately, this must be done independently
+            # for each value key.
+
+            # Yields a list of tuple (mean_value, depth) for each pixel in the map
+            healpix_values_array = self.data_1d[value_key]
+            best_value_and_recursion_depth_by_pixel = [
+                self.get_rect_pixel_value_recursive_subdivs(
+                    rect_pix_center_lon_lat=lon_lat,
+                    rect_pix_spacing_deg=rect_map.spacing_deg,
+                    value_array=healpix_values_array,
+                    max_subdivision_depth=max_subdivision_depth,
+                )
+                for lon_lat in rect_map.az_el_points
+            ]
+
+            # Separate the best value and the recursion depth for each pixel
+            # into two lists, then convert both to numpy arrays
+            # and move the pixel dim to the last dim of values
+            interpolated_data_by_rect_pixel, subdiv_depth_of_value_by_pixel = zip(
+                *best_value_and_recursion_depth_by_pixel
+            )
+            interpolated_data_by_rect_pixel = np.moveaxis(
+                np.array(interpolated_data_by_rect_pixel), 0, -1
+            )
+            subdiv_depth_of_value_by_pixel = np.array(subdiv_depth_of_value_by_pixel)
+
+            # This can introduce an extra dim as the last dim of the array
+            # to values with only one dimension
+            if len(healpix_values_array.dims) == 1:
+                interpolated_data_by_rect_pixel = np.squeeze(
+                    interpolated_data_by_rect_pixel,
+                )
+
+            # Store the best value(s) of each pixel in the rectangular map with the
+            # leading coordinates of the healpix map, and the pixel coordinate last
+            rect_map.data_1d[value_key] = xr.DataArray(
+                data=interpolated_data_by_rect_pixel,
+                dims=(*healpix_values_array.dims[:-1], CoordNames.GENERIC_PIXEL.value),
+            )
+
+            # Update the coordinates of the rectangular map with any new coordinates
+            # from the healpix map except the pixel coord,
+            # which will be different in the rectangular map.
+            for coord in healpix_values_array.coords:
+                if coord not in (
+                    CoordNames.GENERIC_PIXEL.value,
+                    CoordNames.HEALPIX_INDEX.value,
+                ):
+                    rect_map.data_1d.coords[coord] = healpix_values_array.coords[coord]
+
+            # Add the subdivision depth by pixel of this value_key to the dictionary
+            # This may be necessary for uncertainty estimation
+            subdiv_depth_dict[value_key] = subdiv_depth_of_value_by_pixel
+            logger.info(
+                f"Summary of subdivision depth for {value_key}:\n"
+                "Mean +/- std number of subdivisions for the "
+                f"{rect_map.num_points} pixels of {value_key} is:\n"
+                f"    {np.mean(subdiv_depth_of_value_by_pixel):.6f}."
+                f" +/- {np.std(subdiv_depth_of_value_by_pixel):.6f}.\n"
+                "Min / Max number of subdivisions: \n"
+                f"    {np.min(subdiv_depth_of_value_by_pixel):.6f} / "
+                f"{np.max(subdiv_depth_of_value_by_pixel):.6f}.\n"
+                f"The maximum allowed depth is {max_subdivision_depth}."
+            )
+
+        return rect_map, subdiv_depth_dict
+
     def __repr__(self) -> str:
         """
         Return a string representation of the HealpixSkyMap.