cmbstack 0.0.1__py3-none-any.whl

cmbstack/__init__.py

@@ -0,0 +1 @@
+

cmbstack/main.py

@@ -0,0 +1,103 @@
+"""High-level stacking pipeline for HEALPix CMB maps.
+
+:class:`StackingPipeline` runs the full analysis in one place:
+simulate (or load) a map, detect peaks, extract gnomonic patches, stack them,
+and compute a radial profile. The pipeline stores every intermediate product
+as an attribute so individual steps can be inspected after the run.
+
+Typical use
+-----------
+>>> pipeline = StackingPipeline.from_cl("path/to/cl.txt", nside=1024, seed=42)
+>>> pipeline.run()
+>>> plt.imshow(pipeline.stacked)
+"""
+
+from . import maps, stacking
+import numpy as np
+import healpy as hp
+
+
+class StackingPipeline:
+    """End-to-end stacking pipeline.
+
+    Construct from a power spectrum (:meth:`from_cl`) or from an existing map
+    (:meth:`from_map`), then call :meth:`run`.
+
+    Parameters
+    ----------
+    sky_map : numpy.ndarray
+        The HEALPix map to stack on.
+    nside : int
+        Resolution parameter of the map.
+
+    Attributes
+    ----------
+    normalized : numpy.ndarray or None
+        Set after run(); the normalized map.
+    """
+
+    def __init__(self, sky_map, nside):
+        self.map = sky_map
+        self.nside = nside
+        self.normalized = None
+        self.positions = None
+        self.patches = None
+        self.stacked = None
+        self.radius = None
+        self.profile = None
+
+
+    @classmethod
+    def from_cl(cls, cl_path, nside=128, seed=None):
+        """Build a pipeline by simulating a map from a power-spectrum file."""
+        cl = maps.load_cl(cl_path)
+
+        sky_map = maps.simulate_map(cl, nside, seed)
+        return cls(sky_map, nside)
+    
+    @classmethod
+    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)
+        nside = hp.npix2nside(sky_map.size)
+        return cls(sky_map, nside)
+ 
+    @classmethod
+    def from_fits(cls, path, field=0):
+        """Build a pipeline from any HEALPix FITS file on disk."""
+        sky_map = maps.load_map(path, field=field)
+        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):
+        """Run the full stacking loop.
+
+        Parameters
+        ----------
+        size_deg, reso_arcmin : float
+            Patch geometry.
+        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.
+
+        Returns
+        -------
+        result : cmbstack.stack.StackResult
+        """
+
+        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 profile:
+            self.radius, self.profile = stacking.radial_profile(self.stacked,reso_arcmin=reso_arcmin)
+
+        return self

cmbstack/maps.py

@@ -0,0 +1,136 @@
+"""Map simulation and preprocessing utilities for HEALPix CMB maps.
+
+Provides the building blocks for turning a raw power spectrum into a
+normalised HEALPix map ready for stacking:
+
+  1. :func:`load_cl`      — read a D_ell spectrum file and convert to C_ell
+  2. :func:`simulate_map` — draw a Gaussian random realisation with ``healpy.synfast``
+  3. :func:`normalize_map`— subtract the monopole and divide by the std
+
+These functions are intentionally field-agnostic: they work on any scalar
+power spectrum (temperature TT, lensing convergence, y-map, ...).
+"""
+
+import numpy as np
+import healpy as hp
+
+
+def dl_to_cl(ell, dl,lmax):
+    """Convert D_ell = ell(ell+1) C_ell / (2 pi) to C_ell.
+
+    Parameters
+    ----------
+    ell : array_like
+        Multipole values. May start at 0; the ell=0 and ell=1 entries are set
+        to zero in the output to avoid division by zero (they carry no usable
+        power for this purpose).
+    dl : array_like
+        D_ell values in the same units you want C_ell returned in (e.g. uK^2).
+
+    Returns
+    -------
+    cl : numpy.ndarray
+        The angular power spectrum C_ell, same shape as ``dl``.
+
+    Notes
+    -----
+    The inverse normalization is ``C_ell = D_ell * 2*pi / (ell*(ell+1))``.
+    """
+    # Convert D_ell -> C_ell
+    cl_vals = 2.0 * np.pi * dl / (ell * (ell + 1.0))
+
+    # Build a full array indexed from ell=0, with 0,1 set to zero
+    lmax = np.max(ell)
+    cl = np.zeros(lmax + 1)
+    cl[ell] = cl_vals
+
+    return cl
+
+# Function 1
+def load_cl(path):
+    """Load a power-spectrum file and return C_ell for the requested spectrum.
+
+    The expected file columns are ell, Dl_TT, Dl_TE, Dl_EE, Dl_BB, Dl_dd, with
+    D_ell in uK^2. The chosen column is converted from D_ell to C_ell via
+    :func:`dl_to_cl` before being returned.
+
+    Parameters
+    ----------
+    path : str
+        Path to the whitespace-delimited spectrum file.
+    column : str, optional
+        Which spectrum to return: one of "TT", "TE", "EE", "BB", "dd".
+        Default "TT".
+
+    Returns
+    -------
+    cl : numpy.ndarray
+        C_ell array indexed from ell=0, suitable for passing to
+        :func:`simulate_map`.
+    """
+    ell, dl = np.loadtxt(path,usecols=(0,1),unpack=True)
+    ell = ell.astype(int)
+    lmax = ell.max()  
+    cl = dl_to_cl(ell,dl,lmax)
+
+    return cl
+
+# Function 2
+def simulate_map(cl, nside=128, seed=None):
+    """Simulate a Gaussian random HEALPix map from a power spectrum.
+
+    Thin wrapper over ``healpy.synfast`` with an optional seed so results are
+    reproducible in tests.
+
+    Parameters
+    ----------
+    cl : array_like
+        Angular power spectrum C_ell (not D_ell).
+    nside : int, optional
+        HEALPix resolution parameter. Default 128.
+    seed : int or None, optional
+        Seed for the random number generator. If None, the draw is random.
+
+    Returns
+    -------
+    m : numpy.ndarray
+        A HEALPix map (RING ordering) of length ``12 * nside**2``.
+    """
+    if seed:
+        np.random.seed(seed)
+
+    map = hp.synfast(cl, nside=nside) 
+
+    return map
+
+
+def normalize_map(m):
+    """Subtract the monopole and divide by the standard deviation.
+
+    After this, peak thresholds can be expressed in units of sigma, which is the
+    natural convention for peak statistics.
+
+    Parameters
+    ----------
+    m : array_like
+        Input HEALPix map. May contain UNSEEN/NaN pixels, which are ignored in
+        the mean and standard deviation.
+
+    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()
+    return m_norm
+
+
+def load_map(path, field=0):
+    """Wraps ``hp.read_map``"""
+    return hp.read_map(path, field=field)
+ 
+ 
+def save_map(path, sky_map, overwrite=True):
+    """Wraps ``hp.write_map``"""
+    hp.write_map(path, sky_map, overwrite=overwrite)

cmbstack/stacking.py

@@ -0,0 +1,198 @@
+"""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.0.1.dist-info/METADATA

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: cmbstack
+Version: 0.0.1
+Summary: Stack patches of the CMB temperature sky around local maxima
+Author-email: Isaac Alexis López Paredes <first@example.com>, Anushka Sanjay Tilekar <anushka.tilekar.23@alumni.ucl.ac.uk>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/IsaacLP/cmbstack
+Project-URL: Repository, https://github.com/IsaacLP/cmbstack.git
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: numpy
+Requires-Dist: healpy
+Requires-Dist: matplotlib
+
+[![A rectangular badge, half black half purple containing the text made at Code Astro](https://img.shields.io/badge/Made%20at-Code/Astro-blueviolet.svg)](https://semaphorep.github.io/codeastro/)
+
+# CMB Peak Stacking Pipeline
+
+## Overview
+
+`cmbstack` is a Python package for stacking patches of the Cosmic Microwave Background (CMB) temperature sky. It accepts input as a theoretical power spectrum, a [HEALPix](https://healpy.readthedocs.io/en/latest/index.html) FITS file, or a map array already in memory. From there it detects local maxima, extracts gnomonic (flat-sky) patches around each peak, and averages them. This stacking procedure enhances the coherent peak profile while suppressing uncorrelated noise.
+
+## Installation
+
+```bash
+pip install cmbstack
+```
+
+## Quick Start
+
+**From a power spectrum file:**
+```python
+from cmbstack.main import StackingPipeline
+
+pipeline = StackingPipeline.from_cl("path/to/spectrum.dat", nside=1024, seed=42)
+pipeline.run()
+```
+
+**From an existing FITS map:**
+```python
+pipeline = StackingPipeline.from_fits("path/to/map.fits", field=0)
+pipeline.run()
+```
+
+**From a map array already in memory:**
+```python
+pipeline = StackingPipeline.from_map(sky_map)
+pipeline.run()
+```
+
+See `examples/from_theoretical_cl.ipynb` for a full worked example.
+
+## Package Structure
+
+```
+cmbstack/
+├── maps.py      — power-spectrum loading, map simulation, normalisation
+├── stacking.py  — peak finding, patch extraction, stacking, radial profile
+└── main.py      — StackingPipeline high-level class
+```
+
+## Workflow
+
+> **Note:** Steps 1–2 apply when starting from a power spectrum. Use `StackingPipeline.from_fits` or `from_map` to skip them when working with a real or pre-simulated map.
+
+### 1. Load the Power Spectrum — `maps.load_cl`
+
+The input file contains the power spectrum as $D_\ell^{TT}$:
+
+$$D_\ell \equiv \frac{\ell(\ell+1)}{2\pi} C_\ell$$
+
+`load_cl` reads columns $(\ell, D_\ell)$ and converts to $C_\ell$:
+
+$$C_\ell = \frac{2\pi}{\ell(\ell+1)} D_\ell, \qquad C_0 = C_1 = 0$$
+
+---
+
+### 2. Simulate a Sky Map — `maps.simulate_map`
+
+A Gaussian random realization is drawn by sampling spherical harmonic coefficients $a_{\ell m}$ with variance $C_\ell$:
+
+$$T(\hat{n}) = \sum_{\ell,m} a_{\ell m} \, Y_{\ell m}(\hat{n}), \qquad \langle |a_{\ell m}|^2 \rangle = C_\ell$$
+
+This calls `healpy.synfast` internally. An optional `seed` makes runs reproducible.
+
+---
+
+### 3. Normalise the Map — `maps.normalize_map`
+
+Before peak detection, the map is standardised so that thresholds have a clear statistical meaning:
+
+$$T_{\text{norm}}(\hat{n}) = \frac{T(\hat{n}) - \langle T \rangle}{\sigma}$$
+
+After this step the map has mean $\approx 0$ and standard deviation $= 1$, so peaks are measured in units of $\sigma$.
+
+---
+
+### 4. Detect Peaks — `stacking.find_peaks`
+
+Local maxima are identified with `healpy.hotspots`: a pixel is a maximum if its value exceeds every immediate HEALPix neighbour. Peaks are filtered by a significance threshold $\nu$ (default $\nu = 3\sigma$) and optionally capped at the $N$ highest:
+
+$$\text{Peaks} = \{\hat{n}_p \in \text{Maxima} \mid T_{\text{norm}}(\hat{n}_p) > \nu\}$$
+
+Returns sky positions as $(θ, φ)$ pairs in radians.
+
+---
+
+### 5. Extract Patches — `stacking.extract_patches`
+
+For each peak a square patch is cut using a gnomonic (tangent-plane) projection centred on $\hat{n}_p$. Every patch shares the same fixed pixel grid (side length `size_deg`, pixel scale `reso_arcmin`), so the centre pixel always corresponds to the peak itself and patches can be co-added directly.
+
+---
+
+### 6. Stack — `stacking.stack_patches`
+
+Patches are averaged pixel-by-pixel:
+
+$$S = \frac{1}{N} \sum_{i=1}^{N} P_i$$
+
+Incoherent noise averages towards zero; the coherent central profile survives.
+
+---
+
+### 7. Radial Profile — `stacking.radial_profile`
+
+The 2D stacked image is collapsed to a 1D profile by azimuthal averaging in concentric annuli about the centre. Returns bin-centre radii in arcminutes and the mean temperature in each annulus.
+
+---
+
+## Pipeline Constructors
+
+`StackingPipeline` provides three entry points depending on where your data comes from:
+
+| Constructor | Input | Notes |
+|---|---|---|
+| `from_cl(path, nside, seed)` | Power-spectrum file | Simulates a Gaussian random map via `healpy.synfast` |
+| `from_fits(path, field=0)` | HEALPix FITS file | Loads the map with `maps.load_map`; `nside` is inferred automatically |
+| `from_map(sky_map)` | NumPy array | Accepts any in-memory HEALPix map; `nside` is inferred automatically |
+
+All three store the map in `pipeline.map` and share the same `run()` interface.
+
+---
+
+## Map I/O Utilities
+
+`maps.load_map` and `maps.save_map` wrap the healpy FITS readers for convenience:
+
+```python
+from cmbstack import maps
+
+m = maps.load_map("map.fits", field=0)   # wraps hp.read_map
+maps.save_map("out.fits", m)             # wraps hp.write_map (overwrite=True by default)
+```
+
+---
+
+## Pipeline Object
+
+`StackingPipeline` stores every intermediate product as an attribute:
+
+| Attribute | Content |
+|---|---|
+| `pipeline.map` | Raw simulated map |
+| `pipeline.normalized` | Normalised map (units of $\sigma$) |
+| `pipeline.positions` | Peak positions $(θ, φ)$ in radians |
+| `pipeline.patches` | List of 2D gnomonic patches |
+| `pipeline.stacked` | Mean stacked 2D image |
+| `pipeline.radius` | Radial bin centres (arcmin) |
+| `pipeline.profile` | Mean temperature per radial bin |

cmbstack-0.0.1.dist-info/RECORD

@@ -0,0 +1,8 @@
+cmbstack/__init__.py,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+cmbstack/main.py,sha256=MsEC7R4N14LM6YqsHssYCCL8L27G43eSTteSSTuX29M,3213
+cmbstack/maps.py,sha256=ri6jBpWe0SRZZsFg-FQ-_y_sqZA6fLiaIZk_mX4VYr0,3893
+cmbstack/stacking.py,sha256=P6aXH9xiYWVSj7xD7Zlwg3FQZ0MObKJNj9Hw1dG4NO4,7366
+cmbstack-0.0.1.dist-info/METADATA,sha256=1vSxDLa-V1CIfhLXk6LWqMnBSOGEg-BiaW-lmydcYpY,6056
+cmbstack-0.0.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+cmbstack-0.0.1.dist-info/top_level.txt,sha256=QFyCKT2_L8ZxFKUUzMWPSV1hORigTGvvQCvzshyGJvw,9
+cmbstack-0.0.1.dist-info/RECORD,,

cmbstack-0.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

cmbstack-0.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+cmbstack