cmbstack 0.1.1__tar.gz → 0.2.0__tar.gz

{cmbstack-0.1.1 → cmbstack-0.2.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: cmbstack
-Version: 0.1.1
-Summary: Stack patches of the CMB temperature sky around local maxima
+Version: 0.2.0
+Summary: Stack patches of HEALPix maps around peaks or catalogue positions
 Author-email: Isaac Alexis López Paredes <isaacalexis.lopezparedes@students.uniroma2.eu>, Anushka Sanjay Tilekar <anushka.tilekar.23@alumni.ucl.ac.uk>
 License-Expression: MIT
 Project-URL: Homepage, https://cmbstack-docs.readthedocs.io/en/latest/index.html
@@ -23,7 +23,7 @@ Requires-Dist: matplotlib
 
 # cmbstack
 
-Stack patches of the Cosmic Microwave Background (CMB) temperature sky. Go [here](https://cmbstack-docs.readthedocs.io/en/latest/index.html) to see the full documentation and a worked example.
+Stack patches of HEALPix maps, such as the CMB temperature, CMB lensing or galaxy density, around their peaks or around the positions of a catalogue. Go [here](https://cmbstack-docs.readthedocs.io/en/latest/index.html) to see the full documentation, and [here](https://github.com/IsaacLP/cmbstack/tree/main/docs/tutorials) for worked examples.
 
 ## Installation
 
@@ -62,3 +62,15 @@ stacked_result = pipeline.run()
 pipeline = StackingPipeline.from_map(sky_map)
 stacked_result = pipeline.run()
 ```
+
+A masked map (`healpy.ma`) keeps its mask: masked pixels are ignored, and `pipeline.counts` gives the number of patches contributing to each pixel.
+
+**On the positions of a catalogue, with a rotation for each patch:**
+```python
+# positions: (N, 2) array of (lon, lat) in degrees; angles: (N,) rotations in degrees
+pipeline = StackingPipeline.from_map(sky_map)
+stacked_result = pipeline.run(positions=positions, psi=angles, size_deg=2.4, size_deg_y=12.0,
+                              profile=False, keep_patches=False)
+```
+
+`keep_patches=False` stacks the patches one at a time instead of keeping them all in memory, which is needed for large catalogues.

{cmbstack-0.1.1 → cmbstack-0.2.0}/README.md

@@ -6,7 +6,7 @@
 
 # cmbstack
 
-Stack patches of the Cosmic Microwave Background (CMB) temperature sky. Go [here](https://cmbstack-docs.readthedocs.io/en/latest/index.html) to see the full documentation and a worked example.
+Stack patches of HEALPix maps, such as the CMB temperature, CMB lensing or galaxy density, around their peaks or around the positions of a catalogue. Go [here](https://cmbstack-docs.readthedocs.io/en/latest/index.html) to see the full documentation, and [here](https://github.com/IsaacLP/cmbstack/tree/main/docs/tutorials) for worked examples.
 
 ## Installation
 
@@ -44,4 +44,16 @@ stacked_result = pipeline.run()
 ```python
 pipeline = StackingPipeline.from_map(sky_map)
 stacked_result = pipeline.run()
-```
+```
+
+A masked map (`healpy.ma`) keeps its mask: masked pixels are ignored, and `pipeline.counts` gives the number of patches contributing to each pixel.
+
+**On the positions of a catalogue, with a rotation for each patch:**
+```python
+# positions: (N, 2) array of (lon, lat) in degrees; angles: (N,) rotations in degrees
+pipeline = StackingPipeline.from_map(sky_map)
+stacked_result = pipeline.run(positions=positions, psi=angles, size_deg=2.4, size_deg_y=12.0,
+                              profile=False, keep_patches=False)
+```
+
+`keep_patches=False` stacks the patches one at a time instead of keeping them all in memory, which is needed for large catalogues.

cmbstack-0.2.0/cmbstack/__init__.py

@@ -0,0 +1,5 @@
+__version__ = "0.2.0"
+
+from cmbstack.pipeline import StackingPipeline
+
+__all__ = ["StackingPipeline", "maps", "stacking"]

{cmbstack-0.1.1 → cmbstack-0.2.0}/cmbstack/maps.py

@@ -123,16 +123,22 @@ def normalize_map(m):
     Parameters
     ----------
     m : array_like
-        Input HEALPix map. May contain UNSEEN/NaN pixels, which are ignored in
-        the mean and standard deviation.
+        Input HEALPix map. May contain UNSEEN/NaN pixels or be a masked array
+        (e.g. from ``hp.ma``); these pixels are ignored in the mean and
+        standard deviation and set to UNSEEN in the output.
 
     Returns
     -------
     m_norm : numpy.ndarray
         The normalized map, with mean ~0 and std ~1.
     """
-    m_clean = hp.remove_monopole(m)
-    m_norm = m_clean / m_clean.std()
+    m = np.ma.filled(np.ma.asarray(m, dtype=float), hp.UNSEEN)
+    # mask_bad compares to UNSEEN with a tolerance, so UNSEEN stored as float32
+    # (e.g. Planck maps from hp.read_map) is still recognised; it also flags NaN/inf.
+    good = ~hp.mask_bad(m)
+    m_norm = np.full_like(m, hp.UNSEEN)
+    m_good = m[good] - m[good].mean()
+    m_norm[good] = m_good / m_good.std()
     return m_norm
 
 

{cmbstack-0.1.1 → cmbstack-0.2.0}/cmbstack/pipeline.py

@@ -35,7 +35,9 @@ class StackingPipeline:
     normalized : numpy.ndarray or None
         Set after run(); the normalized map.
     positions : numpy.ndarray or None
-        Set after run(); the peak positions in (theta, phi) radians.
+        Set after run(); the peak or catalogue positions in (lon, lat) degrees.
+    psi : numpy.ndarray or None
+        Set after run(); the per-patch rotation angles in degrees, if any.
     patches : numpy.ndarray or None
         Set after run(); the extracted patches.
     stacked : numpy.ndarray or None
@@ -51,6 +53,7 @@ class StackingPipeline:
         self.nside = nside
         self.normalized = None
         self.positions = None
+        self.psi = None
         self.patches = None
         self.stacked = None
         self.radius = None
@@ -69,7 +72,8 @@ class StackingPipeline:
     def from_map(cls, sky_map):
         """Build a pipeline from a HEALPix map array already in memory. nside is inferred from the map length, so the caller doesn't have to supply it.
         """
-        sky_map = np.asarray(sky_map)
+        # Masked pixels become UNSEEN; np.asarray alone would drop the mask.
+        sky_map = np.ma.filled(sky_map, hp.UNSEEN)
         nside = hp.npix2nside(sky_map.size)
         return cls(sky_map, nside)
  
@@ -80,19 +84,46 @@ class StackingPipeline:
         return cls.from_map(sky_map)
     
 
-    def run(self, size_deg=10.0, reso_arcmin=3.0, profile=True, threshold=3.0, n_peaks=None):
+    def run(self, size_deg=10.0, reso_arcmin=3.0, profile=True, threshold=3.0, n_peaks=None,
+            positions=None, psi=None, min_count=1, mask_distance_deg=None, verbose=False,
+            size_deg_y=None, keep_patches=True):
         """Run the full stacking loop.
 
         Parameters
         ----------
         size_deg, reso_arcmin : float
-            Patch geometry.
+            Patch geometry: side length in x (degrees) and pixel size (arcmin).
+        size_deg_y : float or None
+            Patch side length in y in degrees. None (default) gives a square
+            patch of side ``size_deg``.
         profile : bool
             Whether to also compute the radial profile.
         threshold : float
             Peak-finding threshold in units of the map std.
         n_peaks : int or None
             Maximum number of peaks to use; None means use all.
+        positions : array_like, shape (N, 2), optional
+            External catalogue positions as ``(lon, lat)`` in degrees. 
+            If given, peak finding is skipped and ``threshold``/``n_peaks`` 
+            are ignored.
+        psi : array_like, shape (N,), optional
+            Per-patch rotation in degrees for oriented stacking.
+        min_count : int or float
+            Minimum number of contributing patches for a stacked pixel to be
+            kept (see :func:`stacking.stack_patches`). The per-pixel counts
+            are stored in ``self.counts``.
+        mask_distance_deg : float or None
+            Discard detected peaks with a masked pixel within this distance in
+            degrees (see :func:`stacking.find_peaks`). Peaks touching the mask
+            are always discarded. Ignored when ``positions`` is given. The
+            number of discarded peaks is stored in ``self.n_rejected``.
+        verbose : bool
+            If True, print how many peaks were kept and rejected by the mask cut.
+        keep_patches : bool
+            If True (default), keep every patch in ``self.patches``. If False,
+            stream the patches straight into the stack and set ``self.patches``
+            to None: memory then stays at about one patch whatever the number
+            of positions, which is needed for large catalogues.
 
         Returns
         -------
@@ -103,11 +134,27 @@ class StackingPipeline:
 
         self.normalized = maps.normalize_map(self.map)
 
-        self.positions = stacking.find_peaks(self.normalized, self.nside, threshold=threshold, n_peaks=n_peaks)
-
-        self.patches = stacking.extract_patches(self.normalized,self.positions,size_deg=size_deg,reso_arcmin=reso_arcmin)
-
-        self.stacked = stacking.stack_patches(self.patches)
+        if positions is None:
+            self.positions, self.n_rejected = stacking.find_peaks(
+                self.normalized, self.nside, threshold=threshold, n_peaks=n_peaks,
+                mask_distance_deg=mask_distance_deg, return_n_rejected=True)
+            if verbose:
+                print(f"find_peaks: kept {len(self.positions)} peaks, "
+                      f"rejected {self.n_rejected} near the mask")
+        else:
+            self.positions = np.atleast_2d(positions)
+            self.n_rejected = 0
+        if len(self.positions) == 0:
+            raise ValueError("No positions to stack on: no peaks found above the threshold.")
+        self.psi = psi
+
+        patches = stacking.iter_patches(self.normalized,self.positions,psi=self.psi,size_deg=size_deg,
+                                        size_deg_y=size_deg_y,reso_arcmin=reso_arcmin)
+        if keep_patches:
+            patches = list(patches)
+        self.patches = patches if keep_patches else None
+
+        self.stacked, self.counts = stacking.stack_patches(patches, min_count=min_count, return_counts=True)
 
         if profile:
             self.radius, self.profile = stacking.radial_profile(self.stacked,reso_arcmin=reso_arcmin)

cmbstack-0.2.0/cmbstack/stacking.py

@@ -0,0 +1,340 @@
+"""Stacking of patches around positions on a HEALPix map.
+
+The pipeline is field-agnostic: it operates on any scalar HEALPix map (CMB
+temperature, lensing convergence, a y-map, galaxy density, ...). Positions to
+stack on can either be auto-detected peaks (local maxima) or supplied as an
+external catalogue, so the same code serves peak stacking and
+stacking-on-catalogue (clusters, voids, filaments, ...).
+
+Typical use
+-----------
+>>> peaks = find_peaks(m, nside, threshold=3.0)      # positions in (lon, lat), degrees
+>>> patches = extract_patches(m, peaks)              # fixed-grid 2D cutouts
+>>> stacked = stack_patches(patches)                 # mean 2D image
+>>> r, profile = radial_profile(stacked, reso_arcmin=3.0)
+
+Oriented stacking on a catalogue, streaming the patches so that only one is in
+memory at a time:
+
+>>> patches = iter_patches(m, positions, psi=angles, size_deg=2.4, size_deg_y=12.0)
+>>> stacked, counts = stack_patches(patches, return_counts=True)
+"""
+
+import numpy as np
+import healpy as hp
+
+
+# ---------------------------------------------------------------------------
+# Position finding
+# ---------------------------------------------------------------------------
+def find_peaks(sky_map, nside, threshold=None, n_peaks=None, mask_distance_deg=None,
+               return_n_rejected=False):
+    """Find local maxima of a HEALPix map and return their sky positions.
+
+    A pixel is a local maximum if its value is strictly greater than all of its
+    immediate HEALPix neighbours. Peaks can be filtered by a significance
+    threshold and/or capped at the ``n_peaks`` highest.
+
+    Peaks next to masked (UNSEEN) pixels are discarded: there a pixel only has
+    to beat its unmasked neighbours, so the true maximum may lie under the mask.
+
+    Parameters
+    ----------
+    sky_map : numpy.ndarray
+        Input HEALPix map (RING ordering). For a normalised map, values are in
+        units of sigma, so ``threshold`` is a significance nu.
+    nside : int
+        HEALPix resolution parameter of ``sky_map``.
+    threshold : float, optional
+        If given, keep only peaks with value greater than this (e.g. 3.0 for
+        3-sigma peaks on a normalised map). Default None (no threshold).
+    n_peaks : int, optional
+        If given, keep only the ``n_peaks`` highest peaks (applied after the
+        threshold and the mask cut). Default None (keep all).
+    mask_distance_deg : float, optional
+        If given, also discard peaks with any masked pixel within this angular
+        distance in degrees. Default None (only the immediate neighbours are
+        checked).
+    return_n_rejected : bool, optional
+        If True, also return the number of peaks discarded for being next to
+        (or within ``mask_distance_deg`` of) the mask. Default False.
+
+    Returns
+    -------
+    positions : numpy.ndarray, shape (N, 2)
+        Sky positions of the selected peaks as ``(lon, lat)`` in degrees, the
+        same format accepted by :func:`extract_patches`.
+    n_rejected : int
+        Number of peaks discarded by the mask cut (before ``threshold`` and
+        ``n_peaks``). Only returned if ``return_n_rejected`` is True.
+    """
+    # hp.hotspots returns (max_map, minima_pix, maxima_pix); we want the maxima.
+    _, _, maxima_pix = hp.hotspots(sky_map)
+    maxima_pix = np.asarray(maxima_pix)
+
+    # Drop peaks touching the mask (or within mask_distance_deg of it).
+    bad = hp.mask_bad(sky_map)
+    n_rejected = 0
+    if bad.any() and maxima_pix.size:
+        neighbours = hp.get_all_neighbours(nside, maxima_pix)
+        near_mask = np.any((neighbours >= 0) & bad[neighbours], axis=0)
+        if mask_distance_deg is not None:
+            radius = np.radians(mask_distance_deg)
+            vecs = hp.pix2vec(nside, maxima_pix)
+            near_mask |= [
+                bad[hp.query_disc(nside, v, radius, inclusive=True)].any()
+                for v in np.transpose(vecs)
+            ]
+        n_rejected = int(np.count_nonzero(near_mask))
+        maxima_pix = maxima_pix[~near_mask]
+
+    values = sky_map[maxima_pix]
+
+    if threshold is not None: # Add check for minimmun threshold/n_peaks and ratio between threshold and n_peaks
+        keep = values > threshold
+        maxima_pix = maxima_pix[keep]
+        values = values[keep]
+
+    # Sort highest-first so n_peaks keeps the most significant.
+    order = np.argsort(values)[::-1]
+    maxima_pix = maxima_pix[order]
+
+    if n_peaks is not None:
+        maxima_pix = maxima_pix[:n_peaks]
+
+    lon, lat = hp.pix2ang(nside, maxima_pix,lonlat=True)
+    positions = np.column_stack([lon, lat])
+    if return_n_rejected:
+        return positions, n_rejected
+    return positions
+
+
+# ---------------------------------------------------------------------------
+# Patch extraction
+# ---------------------------------------------------------------------------
+def size_mpc_to_deg(size_mpc, z, cosmo):
+    """Convert a physical size in Mpc to an angular size in degrees.
+
+    Uses the angular diameter distance at redshift ``z`` from the given
+    cosmology.
+
+    Parameters
+    ----------
+    size_mpc : float
+        Physical size in Mpc.
+    z : float
+        Redshift.
+    cosmo : astropy.cosmology.Cosmology
+        Cosmology object to compute the angular diameter distance.
+
+    Returns
+    -------
+    size_deg : float
+        Angular size in degrees.
+    """
+    d_a = cosmo.angular_diameter_distance(z).value  # Mpc
+    size_rad = size_mpc / d_a  # radians
+    size_deg = np.degrees(size_rad)
+    return size_deg
+
+
+def extract_patches(sky_map, positions, psi=None, size_deg=10.0, size_deg_y=None, reso_arcmin=3.0):
+    """Extract fixed-grid gnomonic patches centred on each position.
+
+    Each patch is a square or a rectangular 2D array produced by a gnomonic (tangent-plane)
+    projection centred on the position, so every patch shares the same grid and
+    the centre pixel always corresponds to the position itself. 
+
+    Parameters
+    ----------
+    sky_map : numpy.ndarray
+        Input HEALPix map (RING ordering). Any scalar field.
+    positions : array_like, shape (N, 2)
+        Sky positions as ``(lon, lat)`` in degrees (e.g. the output of
+        :func:`find_peaks`, or an external catalogue converted to this format).
+    psi : array_like, shape (N,), optional
+        Rotation angle in degrees for each patch, passed to the gnomonic projector's
+        ``rot``. If None, defaults to 0.0.
+    size_deg : float, optional
+        Full side length of the patch along x in degrees (along the direction
+        given by ``psi`` for a rotated patch). Default 10.0.
+    size_deg_y : float, optional
+        Full side length of the patch along y in degrees. If None, defaults
+        to ``size_deg`` (square patch). Default None.
+    reso_arcmin : float, optional
+        Pixel size of the projected patch in arcminutes. Default 3.0.
+
+    Returns
+    -------
+    patches : list of numpy.ndarray
+        One 2D array per position, all of shape ``(ysize, xsize)`` with
+        ``xsize = size_deg * 60 / reso_arcmin`` and
+        ``ysize = size_deg_y * 60 / reso_arcmin``. Masked pixels are NaN.
+
+    See Also
+    --------
+    iter_patches : The same patches one at a time, without keeping them all in
+        memory.
+    """
+    return list(iter_patches(sky_map, positions, psi=psi, size_deg=size_deg,
+                             size_deg_y=size_deg_y, reso_arcmin=reso_arcmin))
+
+
+def iter_patches(sky_map, positions, psi=None, size_deg=10.0, size_deg_y=None, reso_arcmin=3.0):
+    """Yield the patches of :func:`extract_patches` one at a time.
+
+    Takes the same arguments as :func:`extract_patches`. Only one patch is in
+    memory at a time, so passing this generator to :func:`stack_patches` stacks
+    any number of positions in constant memory.
+
+    Yields
+    ------
+    patch : numpy.ndarray
+        2D array of shape ``(ysize, xsize)`` for the next position, with masked
+        pixels set to NaN.
+    """
+    positions = np.atleast_2d(positions)
+    if size_deg_y is None:
+        size_deg_y = size_deg
+    xsize = int(round(size_deg * 60.0 / reso_arcmin))
+    ysize = int(round(size_deg_y * 60.0 / reso_arcmin))
+
+    # Masked arrays become plain arrays with UNSEEN at the masked pixels.
+    sky_map = hp.pixelfunc.ma_to_array(sky_map)
+    nside = hp.get_nside(sky_map)
+
+    def vec2pix(x, y, z):
+        return hp.vec2pix(nside, x, y, z)
+
+    if psi is None:
+        psi = np.zeros(len(positions))
+    for lon, lat, angle in zip(positions[:, 0], positions[:, 1], psi):
+        # Use the projector directly: same result as gnomview, but without
+        # building a matplotlib figure per patch. rot expects (lon, lat) in degrees.
+        proj = hp.projector.GnomonicProj(
+            rot=(lon, lat, angle), xsize=xsize, ysize=ysize, reso=reso_arcmin
+        )
+        patch = proj.projmap(sky_map, vec2pix).astype(float)
+        # Masked (UNSEEN) pixels become NaN so stack_patches ignores them.
+        patch[hp.mask_bad(patch)] = np.nan
+        yield patch
+
+
+# ---------------------------------------------------------------------------
+# Stacking
+# ---------------------------------------------------------------------------
+def stack_patches(patches, min_count=1, return_counts=False):
+    """Average patches pixel-by-pixel into a single stacked image.
+
+    Because every patch shares the same fixed grid (see :func:`extract_patches`),
+    the mean is a genuine stacked image: incoherent noise averages towards zero
+    while the coherent central profile survives. NaN pixels (masked or UNSEEN
+    regions of the map) are ignored.
+
+    The function counts the number of times each pixel contributes (its number
+    of valid, finite values across patches) and divides the sum by that count,
+    rather than by the total number of patches. Pixels with fewer than
+    ``min_count`` contributions are set to NaN.
+
+    Parameters
+    ----------
+    patches : iterable of numpy.ndarray
+        Patches of identical shape: a list such as the output of
+        :func:`extract_patches`, or a generator such as :func:`iter_patches`.
+        The patches are accumulated one at a time, so a generator never needs
+        all of them in memory.
+    min_count : int or float, optional
+        Minimum number of contributions for a pixel to be kept. A float in
+        (0, 1) is a fraction of the number of patches. Default 1 (keep every
+        pixel with at least one contribution).
+    return_counts : bool, optional
+        If True, also return the per-pixel count map. Default False.
+
+    Returns
+    -------
+    stacked : numpy.ndarray
+        The mean 2D patch. Display with ``plt.imshow(stacked)``.
+    counts : numpy.ndarray of int
+        Number of patches contributing to each pixel. Only returned if
+        ``return_counts`` is True.
+    """
+    # Running sum and per-pixel count, so only one patch is needed at a time.
+    total = counts = None
+    n_patches = 0
+    for patch in patches:
+        patch = np.asarray(patch, dtype=float)
+        if total is None:
+            total = np.zeros(patch.shape)
+            counts = np.zeros(patch.shape, dtype=int)
+        elif patch.shape != total.shape:
+            raise ValueError(f"Patch {n_patches} has shape {patch.shape}, expected {total.shape}.")
+        valid = np.isfinite(patch)
+        total += np.where(valid, patch, 0.0)
+        counts += valid
+        n_patches += 1
+    if n_patches == 0:
+        raise ValueError("No patches to stack.")
+
+    if isinstance(min_count, float) and 0.0 < min_count < 1.0:
+        min_count = int(np.ceil(min_count * n_patches))
+    min_count = max(int(min_count), 1)
+
+    mean_stacked = np.full(counts.shape, np.nan)
+    np.divide(total, counts, out=mean_stacked, where=counts >= min_count)
+
+    if return_counts:
+        return mean_stacked, counts
+    return mean_stacked
+
+
+# ---------------------------------------------------------------------------
+# Profile characterisation
+# ---------------------------------------------------------------------------
+def radial_profile(stacked, reso_arcmin=3.0, n_bins=None):
+    """Azimuthally average a stacked patch into a 1D radial profile.
+
+    Collapses the 2D stacked image to value-versus-radius by averaging in
+    concentric annuli about the centre. This 1D profile is the characterisation
+    of the mean peak: a central maximum, and (for CMB temperature) a faint
+    acoustic ring further out.
+
+    Parameters
+    ----------
+    stacked : numpy.ndarray
+        Square 2D stacked patch from :func:`stack_patches`.
+    reso_arcmin : float, optional
+        Pixel size in arcminutes, so the returned radius is in physical angular
+        units. Default 3.0.
+    n_bins : int, optional
+        Number of radial bins. Default is half the patch side length.
+
+    Returns
+    -------
+    radius_arcmin : numpy.ndarray
+        Bin-centre radii in arcminutes.
+    profile : numpy.ndarray
+        Mean value in each annulus.
+    """
+    ny, nx = stacked.shape
+    cy, cx = (ny - 1) / 2.0, (nx - 1) / 2.0
+
+    y, x = np.indices(stacked.shape)
+    r_pix = np.sqrt((x - cx) ** 2 + (y - cy) ** 2)
+
+    if n_bins is None:
+        n_bins = nx // 2
+
+    r_max = nx // 2
+    bin_edges = np.linspace(0, r_max, n_bins + 1)
+    bin_centres = 0.5 * (bin_edges[:-1] + bin_edges[1:])
+
+    profile = np.full(n_bins, np.nan)
+    flat_r = r_pix.ravel()
+    flat_v = stacked.ravel()
+    for i in range(n_bins):
+        in_bin = (flat_r >= bin_edges[i]) & (flat_r < bin_edges[i + 1])
+        if np.any(in_bin):
+            profile[i] = np.nanmean(flat_v[in_bin])
+
+    radius_arcmin = bin_centres * reso_arcmin
+    return radius_arcmin, profile

{cmbstack-0.1.1 → cmbstack-0.2.0}/cmbstack.egg-info/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: cmbstack
-Version: 0.1.1
-Summary: Stack patches of the CMB temperature sky around local maxima
+Version: 0.2.0
+Summary: Stack patches of HEALPix maps around peaks or catalogue positions
 Author-email: Isaac Alexis López Paredes <isaacalexis.lopezparedes@students.uniroma2.eu>, Anushka Sanjay Tilekar <anushka.tilekar.23@alumni.ucl.ac.uk>
 License-Expression: MIT
 Project-URL: Homepage, https://cmbstack-docs.readthedocs.io/en/latest/index.html
@@ -23,7 +23,7 @@ Requires-Dist: matplotlib
 
 # cmbstack
 
-Stack patches of the Cosmic Microwave Background (CMB) temperature sky. Go [here](https://cmbstack-docs.readthedocs.io/en/latest/index.html) to see the full documentation and a worked example.
+Stack patches of HEALPix maps, such as the CMB temperature, CMB lensing or galaxy density, around their peaks or around the positions of a catalogue. Go [here](https://cmbstack-docs.readthedocs.io/en/latest/index.html) to see the full documentation, and [here](https://github.com/IsaacLP/cmbstack/tree/main/docs/tutorials) for worked examples.
 
 ## Installation
 
@@ -62,3 +62,15 @@ stacked_result = pipeline.run()
 pipeline = StackingPipeline.from_map(sky_map)
 stacked_result = pipeline.run()
 ```
+
+A masked map (`healpy.ma`) keeps its mask: masked pixels are ignored, and `pipeline.counts` gives the number of patches contributing to each pixel.
+
+**On the positions of a catalogue, with a rotation for each patch:**
+```python
+# positions: (N, 2) array of (lon, lat) in degrees; angles: (N,) rotations in degrees
+pipeline = StackingPipeline.from_map(sky_map)
+stacked_result = pipeline.run(positions=positions, psi=angles, size_deg=2.4, size_deg_y=12.0,
+                              profile=False, keep_patches=False)
+```
+
+`keep_patches=False` stacks the patches one at a time instead of keeping them all in memory, which is needed for large catalogues.

{cmbstack-0.1.1 → cmbstack-0.2.0}/cmbstack.egg-info/SOURCES.txt

@@ -10,5 +10,6 @@ cmbstack.egg-info/dependency_links.txt
 cmbstack.egg-info/requires.txt
 cmbstack.egg-info/top_level.txt
 tests/test_find_peaks.py
+tests/test_mask.py
 tests/test_round.py
 tests/test_runtime.py

{cmbstack-0.1.1 → cmbstack-0.2.0}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta"
 [project]
 name = "cmbstack"
 dynamic = ["version"]
-description = "Stack patches of the CMB temperature sky around local maxima"
+description = "Stack patches of HEALPix maps around peaks or catalogue positions"
 readme = "README.md"
 authors = [
     {name = "Isaac Alexis López Paredes", email = "isaacalexis.lopezparedes@students.uniroma2.eu"},

cmbstack-0.2.0/tests/test_find_peaks.py

@@ -0,0 +1,92 @@
+import numpy as np
+import healpy as hp
+
+from cmbstack.stacking import find_peaks
+from cmbstack.maps import normalize_map
+
+
+def test_single_peak():
+    '''Test if find_peaks returns the corrected coordinates for a known peak'''
+    nside = 64
+    n_pix = hp.nside2npix(nside)
+    m = np.zeros(n_pix)
+
+    spike_pix = n_pix // 2
+    m[spike_pix] = 10.0
+
+    positions = find_peaks(m, nside=nside, threshold=5.0)
+
+    assert len(positions) == 1
+
+    lon_expected, lat_expected = hp.pix2ang(nside, spike_pix, lonlat=True)
+    lon_found, lat_found = positions[0]
+
+    assert np.isclose(lon_found, lon_expected)
+    assert np.isclose(lat_found, lat_expected)
+
+
+def test_high_threshold():
+    '''Test if find_peaks returns empty array for very high threshold'''
+    cl = np.zeros(384)
+    cl[2:] = 1.0/np.arange(2,384)**2
+    np.random.seed(0)
+    m = hp.synfast(cl, nside=128)
+    m_norm = normalize_map(m)
+    threshold = 1e3
+
+    positions = find_peaks(m_norm,nside=128,threshold=threshold)
+
+    assert positions.size == 0
+
+
+def test_high_n_peaks():
+    '''Test if find_peaks returns all the peaks when n_peaks is greater than the total number of found peaks'''
+    cl = np.zeros(384)
+    cl[2:] = 1.0/np.arange(2,384)**2
+    np.random.seed(0)
+    m = hp.synfast(cl, nside=128)
+
+    positions = find_peaks(m,nside=128)
+
+    n_peaks = len(positions)
+
+    test_n_peaks = n_peaks + 1
+
+    new_positions = find_peaks(m,nside=128,n_peaks=test_n_peaks)
+
+    assert len(new_positions) == len(positions)
+
+
+def test_peaks_near_mask_dropped():
+    '''Test if find_peaks discards peaks touching the mask, or within mask_distance_deg of it'''
+    nside = 64
+    m = np.zeros(hp.nside2npix(nside))
+
+    edge_pix = hp.ang2pix(nside, 0.0, 0.0, lonlat=True)
+    far_pix = hp.ang2pix(nside, 180.0, 0.0, lonlat=True)
+    mid_pix = hp.ang2pix(nside, 0.0, 10.0, lonlat=True)
+    m[[edge_pix, far_pix, mid_pix]] = 10.0
+
+    # Mask a neighbour of edge_pix, plus a pixel 5 deg away from mid_pix.
+    m[hp.get_all_neighbours(nside, edge_pix)[0]] = hp.UNSEEN
+    m[hp.ang2pix(nside, 0.0, 15.0, lonlat=True)] = hp.UNSEEN
+
+    positions, n_rejected = find_peaks(m, nside=nside, threshold=5.0, return_n_rejected=True)
+    found = hp.ang2pix(nside, positions[:, 0], positions[:, 1], lonlat=True)
+    assert set(found) == {far_pix, mid_pix}
+    assert n_rejected == 1
+
+    positions, n_rejected = find_peaks(m, nside=nside, threshold=5.0, mask_distance_deg=6.0,
+                                       return_n_rejected=True)
+    found = hp.ang2pix(nside, positions[:, 0], positions[:, 1], lonlat=True)
+    assert set(found) == {far_pix}
+    assert n_rejected == 2
+
+
+if __name__ == '__main__':
+
+    test_high_threshold()
+
+    test_high_n_peaks()
+
+    test_single_peak()

cmbstack-0.2.0/tests/test_mask.py

@@ -0,0 +1,145 @@
+import warnings
+
+import numpy as np
+import healpy as hp
+import pytest
+
+from cmbstack import StackingPipeline
+from cmbstack.maps import normalize_map
+from cmbstack.stacking import stack_patches, extract_patches, iter_patches
+
+
+def _masked_map(nside=32, dtype=np.float64):
+    np.random.seed(0)
+    m = np.random.normal(5.0, 2.0, hp.nside2npix(nside)).astype(dtype)
+    m_masked = hp.ma(m)
+    m_masked.mask = np.zeros(m.size, dtype=bool)
+    m_masked.mask[: m.size // 4] = True
+    return m, m_masked
+
+
+@pytest.mark.parametrize("dtype", [np.float64, np.float32])
+def test_normalize_map_keeps_mask(dtype):
+    '''Test if normalize_map sets masked pixels to UNSEEN and ignores them in the statistics'''
+    _, m_masked = _masked_map(dtype=dtype)
+    mask = m_masked.mask
+
+    m_norm = normalize_map(m_masked)
+
+    assert np.all(m_norm[mask] == hp.UNSEEN)
+    assert np.isclose(m_norm[~mask].mean(), 0.0, atol=1e-6)
+    assert np.isclose(m_norm[~mask].std(), 1.0)
+
+
+@pytest.mark.parametrize("dtype", [np.float64, np.float32])
+def test_from_map_keeps_mask(dtype):
+    '''Test if StackingPipeline.from_map preserves the mask of a masked array through run()'''
+    _, m_masked = _masked_map(dtype=dtype)
+    mask = m_masked.mask
+
+    pipeline = StackingPipeline.from_map(m_masked)
+    assert np.all(hp.mask_bad(pipeline.map) == mask)
+
+    pipeline.run(threshold=2.0, profile=False)
+    assert np.all(pipeline.normalized[mask] == hp.UNSEEN)
+
+    # Peaks are found, and none of them inside the masked region.
+    assert len(pipeline.positions) > 0
+    pix = hp.ang2pix(pipeline.nside, pipeline.positions[:, 0], pipeline.positions[:, 1], lonlat=True)
+    assert not np.any(mask[pix])
+
+
+def test_run_rectangular_patches():
+    '''Test if run() passes size_deg_y through to the patches and the stack'''
+    _, m_masked = _masked_map()
+    pipeline = StackingPipeline.from_map(m_masked).run(size_deg=10.0, size_deg_y=6.0,
+                                                       reso_arcmin=30.0, threshold=2.0,
+                                                       profile=False)
+
+    # extract_patches returns (ysize, xsize) arrays.
+    assert pipeline.patches[0].shape == (12, 20)
+    assert pipeline.stacked.shape == (12, 20)
+
+
+def test_stack_patches_counts():
+    '''Test if stack_patches divides by the per-pixel count and applies min_count'''
+    nan = np.nan
+    patches = [
+        np.array([[1.0, 2.0], [nan, nan]]),
+        np.array([[3.0, nan], [5.0, nan]]),
+        np.array([[5.0, 4.0], [nan, nan]]),
+    ]
+
+    with warnings.catch_warnings():
+        warnings.simplefilter("error")  # no "Mean of empty slice" for the all-NaN pixel
+        stacked, counts = stack_patches(patches, return_counts=True)
+
+    assert np.array_equal(counts, [[3, 2], [1, 0]])
+    assert np.allclose(stacked, [[3.0, 3.0], [5.0, nan]], equal_nan=True)
+
+    # Pixels seen by fewer than 2 patches are dropped, also as a fraction.
+    expected = [[3.0, 3.0], [nan, nan]]
+    assert np.allclose(stack_patches(patches, min_count=2), expected, equal_nan=True)
+    assert np.allclose(stack_patches(patches, min_count=0.5), expected, equal_nan=True)
+
+
+def _masked_patch_args():
+    '''Masked map, random positions and angles for the streaming tests'''
+    _, m_masked = _masked_map()
+    rng = np.random.default_rng(1)
+    positions = np.column_stack([rng.uniform(0, 360, 50), rng.uniform(-60, 60, 50)])
+    psi = rng.uniform(0, 180, 50)
+    return m_masked, positions, dict(psi=psi, size_deg=10.0, size_deg_y=6.0, reso_arcmin=30.0)
+
+
+def test_iter_patches_matches_extract_patches():
+    '''Test if iter_patches yields the same patches as extract_patches, in the same order'''
+    m_masked, positions, kwargs = _masked_patch_args()
+
+    listed = extract_patches(m_masked, positions, **kwargs)
+    streamed = list(iter_patches(m_masked, positions, **kwargs))
+
+    assert len(streamed) == len(listed) == len(positions)
+    for a, b in zip(listed, streamed):
+        assert np.array_equal(a, b, equal_nan=True)
+
+
+def test_stack_patches_generator_matches_list():
+    '''Test if stacking a generator gives the same stack and counts as stacking a list'''
+    m_masked, positions, kwargs = _masked_patch_args()
+    patches = extract_patches(m_masked, positions, **kwargs)
+    assert any(np.isnan(p).any() for p in patches)  # the mask reaches some patches
+
+    for min_count in [1, 0.9]:
+        s_list, c_list = stack_patches(patches, min_count=min_count, return_counts=True)
+        s_gen, c_gen = stack_patches(iter_patches(m_masked, positions, **kwargs),
+                                     min_count=min_count, return_counts=True)
+        assert np.array_equal(c_list, c_gen)
+        assert np.allclose(s_list, s_gen, equal_nan=True)
+
+
+def test_stack_patches_errors():
+    '''Test if stack_patches rejects an empty input and patches of different shapes'''
+    with pytest.raises(ValueError):
+        stack_patches(iter([]))
+    with pytest.raises(ValueError):
+        stack_patches([np.zeros((2, 2)), np.zeros((2, 3))])
+
+
+def test_run_keep_patches_false():
+    '''Test if run(keep_patches=False) gives the same stack and counts without storing the patches'''
+    _, m_masked = _masked_map()
+    kwargs = dict(size_deg=10.0, reso_arcmin=30.0, threshold=2.0)
+
+    kept = StackingPipeline.from_map(m_masked).run(**kwargs)
+    streamed = StackingPipeline.from_map(m_masked).run(keep_patches=False, **kwargs)
+
+    assert streamed.patches is None
+    assert len(kept.patches) == len(streamed.positions)
+    assert np.array_equal(kept.counts, streamed.counts)
+    assert np.allclose(kept.stacked, streamed.stacked, equal_nan=True)
+    assert np.allclose(kept.profile, streamed.profile, equal_nan=True)
+
+
+if __name__ == "__main__":
+    pytest.main([__file__])

cmbstack-0.1.1/cmbstack/__init__.py

@@ -1,5 +0,0 @@
-__version__ = "0.1.1"
-
-from cmbstack.pipeline import StackingPipeline
-
-__all__ = ["StackingPipeline", "maps", "stacking"]

cmbstack-0.1.1/cmbstack/stacking.py

@@ -1,198 +0,0 @@
-"""Stacking of patches around positions on a HEALPix map.
-
-The pipeline is field-agnostic: it operates on any scalar HEALPix map (CMB
-temperature, lensing convergence, a y-map, galaxy density, ...). Positions to
-stack on can either be auto-detected peaks (local maxima) or supplied as an
-external catalogue, so the same code serves peak stacking and
-stacking-on-catalogue (clusters, voids, filaments, ...).
-
-Typical use
------------
->>> peaks = find_peaks(m, nside, threshold=3.0)      # positions in (theta, phi)
->>> patches = extract_patches(m, peaks)              # fixed-grid 2D cutouts
->>> stacked = stack_patches(patches)                 # mean 2D image
->>> r, profile = radial_profile(stacked, reso_arcmin=3.0)
-"""
-
-import numpy as np
-import healpy as hp
-
-
-# ---------------------------------------------------------------------------
-# Position finding
-# ---------------------------------------------------------------------------
-def find_peaks(sky_map, nside, threshold=None, n_peaks=None):
-    """Find local maxima of a HEALPix map and return their sky positions.
-
-    A pixel is a local maximum if its value is strictly greater than all of its
-    immediate HEALPix neighbours. Peaks can be filtered by a significance
-    threshold and/or capped at the ``n_peaks`` highest.
-
-    Parameters
-    ----------
-    sky_map : numpy.ndarray
-        Input HEALPix map (RING ordering). For a normalised map, values are in
-        units of sigma, so ``threshold`` is a significance nu.
-    nside : int
-        HEALPix resolution parameter of ``sky_map``.
-    threshold : float, optional
-        If given, keep only peaks with value greater than this (e.g. 3.0 for
-        3-sigma peaks on a normalised map). Default None (no threshold).
-    n_peaks : int, optional
-        If given, keep only the ``n_peaks`` highest peaks (applied after the
-        threshold). Default None (keep all).
-
-    Returns
-    -------
-    positions : numpy.ndarray, shape (N, 2)
-        Sky positions of the selected peaks as ``(theta, phi)`` in radians, the
-        same format accepted by :func:`extract_patches`.
-    """
-    # hp.hotspots returns (max_map, minima_pix, maxima_pix); we want the maxima.
-    _, _, maxima_pix = hp.hotspots(sky_map)
-    maxima_pix = np.asarray(maxima_pix)
-
-    values = sky_map[maxima_pix]
-
-    if threshold is not None: # Add check for minimmun threshold/n_peaks and ratio between threshold and n_peaks
-        keep = values > threshold
-        maxima_pix = maxima_pix[keep]
-        values = values[keep]
-
-    # Sort highest-first so n_peaks keeps the most significant.
-    order = np.argsort(values)[::-1]
-    maxima_pix = maxima_pix[order]
-
-    if n_peaks is not None:
-        maxima_pix = maxima_pix[:n_peaks]
-
-    theta, phi = hp.pix2ang(nside, maxima_pix)
-    return np.column_stack([theta, phi])
-
-
-# ---------------------------------------------------------------------------
-# Patch extraction
-# ---------------------------------------------------------------------------
-def extract_patches(sky_map, positions, size_deg=10.0, reso_arcmin=3.0):
-    """Extract fixed-grid gnomonic patches centred on each position.
-
-    Each patch is a square 2D array produced by a gnomonic (tangent-plane)
-    projection centred on the position, so every patch shares the same grid and
-    the centre pixel always corresponds to the position itself. 
-
-    Parameters
-    ----------
-    sky_map : numpy.ndarray
-        Input HEALPix map (RING ordering). Any scalar field.
-    positions : array_like, shape (N, 2)
-        Sky positions as ``(theta, phi)`` in radians (e.g. the output of
-        :func:`find_peaks`, or an external catalogue converted to this format).
-    size_deg : float, optional
-        Full side length of the square patch in degrees. Default 10.0.
-    reso_arcmin : float, optional
-        Pixel size of the projected patch in arcminutes. Default 3.0.
-
-    Returns
-    -------
-    patches : list of numpy.ndarray
-        One square 2D array per position, all of identical shape
-        ``(xsize, xsize)`` with ``xsize = size_deg * 60 / reso_arcmin``.
-    """
-    positions = np.atleast_2d(positions)
-    xsize = int(round(size_deg * 60.0 / reso_arcmin))
-
-    patches = []
-    for theta, phi in positions:
-        # gnomview's rot expects (lon, lat) in degrees.
-        lon = np.degrees(phi)
-        lat = 90.0 - np.degrees(theta)
-        patch = hp.gnomview(
-            sky_map,
-            rot=(lon, lat),
-            xsize=xsize,
-            reso=reso_arcmin,
-            return_projected_map=True,
-            no_plot=True,
-        )
-        patches.append(np.asarray(patch))
-
-    return patches
-
-
-# ---------------------------------------------------------------------------
-# Stacking
-# ---------------------------------------------------------------------------
-def stack_patches(patches):
-    """Average patches pixel-by-pixel into a single stacked image.
-
-    Because every patch shares the same fixed grid (see :func:`extract_patches`),
-    the mean is a genuine stacked image: incoherent noise averages towards zero
-    while the coherent central profile survives. NaN/UNSEEN pixels (patch edges
-    that fall off the map near the poles) are ignored.
-
-    Parameters
-    ----------
-    patches : sequence of numpy.ndarray
-        Patches of identical shape, e.g. the output of :func:`extract_patches`.
-
-    Returns
-    -------
-    stacked : numpy.ndarray
-        The mean 2D patch. Display with ``plt.imshow(stacked)``.
-    """
-    stack = np.array(patches, dtype=float)
-    mean_stacked = np.nanmean(stack, axis=0)
-    return mean_stacked
-
-
-# ---------------------------------------------------------------------------
-# Profile characterisation
-# ---------------------------------------------------------------------------
-def radial_profile(stacked, reso_arcmin=3.0, n_bins=None):
-    """Azimuthally average a stacked patch into a 1D radial profile.
-
-    Collapses the 2D stacked image to value-versus-radius by averaging in
-    concentric annuli about the centre. This 1D profile is the characterisation
-    of the mean peak: a central maximum, and (for CMB temperature) a faint
-    acoustic ring further out.
-
-    Parameters
-    ----------
-    stacked : numpy.ndarray
-        Square 2D stacked patch from :func:`stack_patches`.
-    reso_arcmin : float, optional
-        Pixel size in arcminutes, so the returned radius is in physical angular
-        units. Default 3.0.
-    n_bins : int, optional
-        Number of radial bins. Default is half the patch side length.
-
-    Returns
-    -------
-    radius_arcmin : numpy.ndarray
-        Bin-centre radii in arcminutes.
-    profile : numpy.ndarray
-        Mean value in each annulus.
-    """
-    ny, nx = stacked.shape
-    cy, cx = (ny - 1) / 2.0, (nx - 1) / 2.0
-
-    y, x = np.indices(stacked.shape)
-    r_pix = np.sqrt((x - cx) ** 2 + (y - cy) ** 2)
-
-    if n_bins is None:
-        n_bins = nx // 2
-
-    r_max = nx // 2
-    bin_edges = np.linspace(0, r_max, n_bins + 1)
-    bin_centres = 0.5 * (bin_edges[:-1] + bin_edges[1:])
-
-    profile = np.full(n_bins, np.nan)
-    flat_r = r_pix.ravel()
-    flat_v = stacked.ravel()
-    for i in range(n_bins):
-        in_bin = (flat_r >= bin_edges[i]) & (flat_r < bin_edges[i + 1])
-        if np.any(in_bin):
-            profile[i] = np.nanmean(flat_v[in_bin])
-
-    radius_arcmin = bin_centres * reso_arcmin
-    return radius_arcmin, profile

cmbstack-0.1.1/tests/test_find_peaks.py

@@ -1,66 +0,0 @@
-import numpy as np
-import healpy as hp
-
-from cmbstack.stacking import find_peaks
-from cmbstack.maps import normalize_map
-
-
-def test_single_peak():
-    '''Test if find_peaks returns the corrected coordinates for a known peak'''
-    nside = 64
-    n_pix = hp.nside2npix(nside)
-    m = np.zeros(n_pix)
-
-    spike_pix = n_pix // 2
-    m[spike_pix] = 10.0
-
-    positions = find_peaks(m, nside=nside, threshold=5.0)
-
-    assert len(positions) == 1
-
-    theta_expected, phi_expected = hp.pix2ang(nside, spike_pix)
-    theta_found, phi_found = positions[0]
-
-    assert np.isclose(theta_found, theta_expected)
-    assert np.isclose(phi_found, phi_expected)
-
-
-def test_high_threshold():
-    '''Test if find_peaks returns empty array for very high threshold'''
-    cl = np.zeros(384)
-    cl[2:] = 1.0/np.arange(2,384)**2
-    np.random.seed(0)
-    m = hp.synfast(cl, nside=128)
-    m_norm = normalize_map(m)
-    threshold = 1e3
-
-    positions = find_peaks(m_norm,nside=128,threshold=threshold)
-
-    assert positions.size == 0
-
-
-def test_high_n_peaks():
-    '''Test if find_peaks returns all the peaks when n_peaks is greater than the total number of found peaks'''
-    cl = np.zeros(384)
-    cl[2:] = 1.0/np.arange(2,384)**2
-    np.random.seed(0)
-    m = hp.synfast(cl, nside=128)
-
-    positions = find_peaks(m,nside=128)
-
-    n_peaks = len(positions)
-
-    test_n_peaks = n_peaks + 1
-
-    new_positions = find_peaks(m,nside=128,n_peaks=test_n_peaks)
-
-    assert len(new_positions) == len(positions)
-
-
-if __name__ == '__main__':
-
-    test_high_threshold()
-
-    test_high_n_peaks()
-
-    test_single_peak()