sys_mapping

sys_mapping takes a galaxy overdensity map and HEALPix maps of the observing conditions (templates), fits the multiplicative and additive contamination the templates imprint, and returns per-galaxy weights and the corrected angular correlation function. The pages below give the method and its references, the survey-design forecasts, the validation on mocks, the application to Legacy Survey DR10, and the API.

User guide

• Overview
  • Notation
  • Observed overdensity
  • Template maps
  • Contamination model
  • Likelihood
  • Posterior sampling
  • Template PCA rotation
  • Noise debiasing
  • Two-point function correction
  • Model selection
  • Calibrated detection
  • Per-galaxy weights
  • LS10 analysis script
• Installation
  • Requirements
  • From PyPI
  • From source
  • Running the tests
  • Building the documentation
• Quickstart
  • The six methods
  • Step 1: template maps
  • Step 2: galaxy field and contamination
  • Step 3: observed overdensity
  • Step 4: PCA rotation
  • Step 5: fits with the six methods
  • Step 6: point estimates and convergence
  • Step 7: a null from a matched spectrum
  • Step 8: likelihood ratio test
  • Step 9: two-point correction with cross-template terms

Methods & references

• Methods reference
  • Template pre-selection
  • Contamination model
  • Likelihood
  • Posterior sampling
  • Template PCA rotation
  • Noise debiasing
  • Two-point function correction
  • Likelihood ratio test
  • Calibrated template significance
  • Residual template correlation test
  • Null realisations
  • Resolution, footprint and template basis
  • Pseudo-\(C_\ell\) power spectrum
  • Spatial patches, bootstrap and jack-knife
  • ElasticNet regression
  • Iterative Systematics Decontamination (ISD)
  • Null tests and template ranking
  • Mock catalogues
  • HEALPix map utilities
  • Two-point function measurement
  • Implemented and missing methods
• Bibliography
  • Ross et al. 2011
  • Ho et al. 2012
  • Elsner, Leistedt & Peiris 2016
  • Leistedt & Peiris 2014
  • Elsner, Leistedt & Peiris 2017
  • Weaverdyck & Huterer 2021
  • Rezaie et al. 2020
  • Alonso et al. 2019 — NaMaster
  • Berlfein, Mandelbaum & Schafer 2024
  • Rodríguez-Monroy et al. 2025
  • Cornish et al. 2026
  • Tanidis et al. 2026
  • Weaverdyck et al. 2026
  • Hernández-Monteagudo et al. 2025
  • Kong et al. 2026
  • DeRose et al. 2026

Survey design & forecasting

• Systematic-detectability law
  • Field significance and smallest detectable amplitude
  • Scaling rules
  • LS10 worked example (log \(M_*\ge\) 10.0)
  • Reproduction
• Survey design and the detectability law
  • LS10 in the design space
  • Design rules
  • Survey dimensioning
  • Scaling exponents from GLASS mocks
  • Reproduction

Validation & tests

• Testing
  • Running the tests
  • Test modules
  • Coverage and CI
  • Docstring examples
  • JAX tests
  • Real-template integration tests
  • Adding tests
• Test and JAX coverage
  • Test coverage
  • JAX coverage
  • Reproduction
• Parameter recovery on synthetic mocks
  • Mocks and fits
  • Recovery of the parameters
  • Reproduction
• Test matrix of contamination configurations
  • Mocks
  • Methods
  • Correction quality
  • Amplitude bias
  • Compute time
  • Reproduction
• End-to-end validation under four contamination scenarios
  • Catalogues and contamination
  • Methods
  • Maps and distributions
  • Recovery
  • Amplitude recovery
  • Template ranking
  • Reproduction
• Detection under progressive template contamination
  • Mocks and detection criteria
  • Detection rates and model selection
  • Reproduction
• Recovery with real systematic templates
  • Mocks
  • Additive amplitudes
  • Multiplicative amplitudes and sampling
  • Model selection
  • Integration tests
  • Reproduction
• Simulation tests on GLASS and Uchuu mocks with LSDR10 systematics
  • Mock catalogues
  • Systematic templates
  • Contamination
  • Correction methods
  • Mean fractional bias
  • Residuals of w(θ)
  • Bias by configuration
  • Amplitude recovery
  • Run time
  • Reproduction
  • References
• SNR-based template pre-selection
  • Simulated sky and injected contamination
  • Template ranking
  • Mock-based ISD p-values
  • Run time
  • Number of realisations
  • Reproduction
  • API reference
• Algorithm characterisation
  • 1. Break-even condition
  • 2. Inflation of the independent-pixel error
  • 3. Clustering of the calibration nulls
  • 4. Cross-template terms of the two-point correction
• Pipeline timings
  • Per-function costs
  • HEALPix map utilities
  • Stage-1 pre-selection
  • Stage-2 decontamination
  • Range of the run times

Application to real data: Legacy Survey DR10

• Real-data pipeline for Legacy Survey DR10
  • Input data
  • Command and options
  • Output files
• Systematic weights of the LS10 samples
  • Issued products
  • Detection of systematics
  • Likelihood ratio between the additive and combined models
  • Corrected angular correlation function
  • Residual scatter at three resolutions
  • Per-sample pages
• LS10 systematic-correction recommendations
• BGS VLIM log M* ≥ 9.0, z < 0.08
  • Template significance
  • Fitted amplitudes (NSIDE 32)
  • Weights
  • Angular correlation function
  • Likelihood ratio between the additive and combined models
  • Residual scatter at three resolutions
• BGS VLIM log M* ≥ 9.5, z < 0.12
  • Template significance
  • Fitted amplitudes (NSIDE 64)
  • Weights
  • Angular correlation function
  • Likelihood ratio between the additive and combined models
  • Residual scatter at three resolutions
• BGS VLIM log M* ≥ 10.0, z < 0.18
  • Template significance
  • Fitted amplitudes (NSIDE 128)
  • Weights
  • Angular correlation function
  • Likelihood ratio between the additive and combined models
  • Residual scatter at three resolutions
• BGS VLIM log M* ≥ 10.25, z < 0.22
  • Template significance
  • Fitted amplitudes (NSIDE 128)
  • Weights
  • Angular correlation function
  • Likelihood ratio between the additive and combined models
  • Residual scatter at three resolutions
• BGS VLIM log M* ≥ 10.5, z < 0.26
  • Template significance
  • Fitted amplitudes (NSIDE 128)
  • Weights
  • Angular correlation function
  • Likelihood ratio between the additive and combined models
  • Residual scatter at three resolutions
• BGS VLIM log M* ≥ 10.75, z < 0.31
  • Template significance
  • Fitted amplitudes (NSIDE 128)
  • Weights
  • Angular correlation function
  • Likelihood ratio between the additive and combined models
  • Residual scatter at three resolutions
• BGS VLIM log M* ≥ 11.0, z < 0.35
  • Template significance
  • Fitted amplitudes (NSIDE 64)
  • Weights
  • Angular correlation function
  • Likelihood ratio between the additive and combined models
  • Residual scatter at three resolutions
• BGS VLIM log M* ≥ 11.25, z < 0.35
  • Template significance
  • Fitted amplitudes (NSIDE 64)
  • Weights
  • Angular correlation function
  • Likelihood ratio between the additive and combined models
  • Residual scatter at three resolutions
• BGS VLIM log M* ≥ 11.5, z < 0.35
  • Template significance
  • Fitted amplitudes (NSIDE 16)
  • Weights
  • Angular correlation function
  • Likelihood ratio between the additive and combined models
  • Residual scatter at three resolutions

API reference

• sys_mapping.contamination
  • n_free_params()
  • pack_params()
  • unpack_params()
  • apply_contamination()
  • invert_contamination()
  • compute_two_point_correction()
  • RESPONSE_KINDS
  • TemplateResponse
  • evaluate_response()
  • apply_nonlinear_contamination()
• sys_mapping.likelihood
  • MIN_EFFICIENCY
  • make_log_likelihood()
• sys_mapping.covariance
  • LowRankPrecision
  • build_lowrank_precision()
  • mock_sandwich_covariance()
  • method_marginalised_covariance()
  • sample_covariance()
  • hartlap_factor()
  • build_harmonic_precision()
• sys_mapping.maps
  • Synthetic template families
  • Real observational templates
• sys_mapping.inference
  • GPU / vectorised mode
  • make_log_prob()
  • run_mcmc()
  • run_additive_analytic()
  • posterior_median_params()
  • refine_to_mle()
  • get_param_variance_from_chain()
  • get_param_covariance_from_chain()
• sys_mapping.nuts
  • Reparameterization
  • Device portability
  • default_n_chains()
  • build_logdensity()
  • run_nuts()
• sys_mapping.correction
  • debias_params()
  • debias_params_matrix()
  • rotate_templates()
  • transform_params_from_rotated()
  • correct_two_point_function()
  • estimate_overcorrection_bias()
  • debias_two_point_function()
  • correct_power_spectrum_harmonic()
• sys_mapping.model_selection
  • LikelihoodRatioResult
  • likelihood_ratio_test()
  • lrt_from_maxima()
  • lrt_null_distribution()
  • ForwardSelectionRound
  • GreedyForwardSelectionResult
  • greedy_forward_select()
  • SnrPreselectionResult
  • snr_preselect()
• sys_mapping.bootstrap
  • assign_spatial_patches()
  • block_bootstrap_variance()
  • jackknife_covariance()
• sys_mapping.utils
  • compute_covariance_matrix()
  • compute_amplitude_bias()
  • measure_two_point_function()
  • measure_cross_two_point_function()
  • measure_two_point_function_corrfunc()
  • measure_kk_correlation_treecorr()
  • template_correlation_matrix()
  • measure_kk_covariance_treecorr()
  • measure_kk_correlation_corrfunc()
• sys_mapping.power_spectrum
  • measure_pseudo_cl()
  • subtract_template_cl()
  • harmonic_bias()
  • mode_projection_bias()
• sys_mapping.regression
  • elasticnet_contamination_fit()
  • polynomial_ols_decontamination()
  • ISDStep
  • ISDResult
  • iterative_systematics_decontamination()
  • method_comparison()
  • run_decontamination()
• sys_mapping.diagnostics
  • null_test_cross_correlations()
  • calibrated_template_significance()
  • residual_template_correlation_test()
  • snr_template_ranking()
  • vet_templates_against_tracer()
  • isd_marginal_fit()
  • footprint_mask_diagnostics()
  • isd_template_significance()
• sys_mapping.mocks
  • Contamination scenarios
  • Galaxy field model
  • MockCatalog
  • generate_lognormal_field()
  • make_galactic_mask()
  • make_mock_catalog()
  • make_mock_suite()
• sys_mapping.glass_mocks
  • Workflow
  • MockCatalogDict
  • measure_nz()
  • sanitise_cl()
  • load_matched_cl()
  • generate_glass_fullsky_mock()
  • generate_glass_delta_map()
  • draw_null_overdensity()
  • generate_glass_null_overdensity()
  • sample_positions_from_delta()
• sys_mapping.simulation
  • Contamination injection strategy
  • ContaminationConfig
  • make_contamination_grid()
  • RESPONSE_SHAPES
  • make_response_grid()
  • load_uchuu_mock()
  • load_systematic_maps()
  • apply_footprint_mask()
  • inject_systematics()
  • save_simulation_catalog()
  • load_simulation_catalog()
  • run_wtheta_recovery()
• sys_mapping.plotting
  • Usage
  • Color palette

Development

• Roadmap
• Changelog