🔍 SkyInterpret

A Python toolkit for interpretability and explainability of Neural Network classifications of CMB maps

---

📖 Overview

SkyInterpret is a Python package for performing interpretability and explainability analyses of Neural Network model selection on CMB maps. It builds directly on the classifications produced by SkyNeuralNets, and provides tools to understand what the network has learned from CMB temperature and polarisation maps.

The core analysis relies on SHAP (SHapley Additive exPlanations) applied directly to the classified CMB images, with a key transformation step that reprojects SHAP attribution maps back onto the sphere as HEALPix maps — preserving the geometric structure of the CMB sky.

This code was developed as part of the analysis pipeline for Explaining Neural Networks on the Sky: Machine Learning Interpretability for CMB Maps.

---

✨ Features

• 🌐 SHAP-to-HEALPix reprojection — Converts Cartesian SHAP attribution maps (output of image-based explainers) back to full-sky HEALPix maps, for meaningful interpretation of feature importances on the sphere
• 🗺️ Spherical coordinate mapping — Handles the full astro-convention Cartesian projection, correctly mapping pixel coordinates of shap to spherical coordinates (θ, φ) via bilinear interpolation
• 🔎 SHAP partition explainer — Computes SHAP values using the partition algorithm with configurable maskers, number of evaluations (max_evals), and batch size
• 🎛️ Flexible SHAP-explainer interface — Supports different SHAP Explainer types, masking strategies (zero-masking, blur masking), and output labels for binary or multi-class model selection

---

📦 Installation

Requirements

• Python ≥ 3.9
• numpy, scipy, matplotlib
• healpy
• shap

All dependencies are listed in requirements.txt.

Install

git clone https://github.com/skyexplain/SkyInterpret.git
cd SkyInterpret
pip install -e .

---

🚀 Quick Start

1. Compute SHAP values

import shap

masker = shap.maskers.Image(mask_value=0, shape=X_train.shape)

explainer = shap.Explainer(
    f_logit,
    masker=masker,
    algorithm="partition",
    output_names=["feature"]
)

shap_values = explainer(X_to_explain, max_evals=30000, batch_size=32)

2. Reproject SHAP maps onto the sphere

from skyinterpret import image_to_map

# shap_imgs: shape (N, H, W, 1)
healpix_shap = image_to_map(shap_imgs, nside=256)
# Output shape: (N, Npix, 1)

See Sandbox for examples.

---

🔗 Related Packages

This repository is part of a three-package ecosystem:

Package	Description
SkySimulation	CMB map simulation (T, Q, U) with ΛCDM and oscillatory features
SkyNeuralNets	NN-based model selection on CMB maps
SkyInterpret	Interpretability analysis of the trained neural networks (this repo)

---

📄 Citation

If you use SkyInterpret in your research, please cite:

@article{ocampo2026explaining,
  author        = {Indira Ocampo and Guadalupe Cañas-Herrera},
  title         = {Explaining Neural Networks on the Sky: Machine Learning Interpretability for CMB Maps},
  year          = {2026},
  eprint        = {2604.05290},
  archivePrefix = {arXiv}
}

---

📬 Contact

For questions or issues, please open a GitHub Issue or contact indira.ocampo@csic.es.