sys_mapping.mocks

Synthetic galaxy catalog generation for package validation.

Generates physically motivated mock catalogs with controlled contamination:

Lognormal galaxy field (Coles & Jones 1991): overdensity \(\delta_g = \exp(G - \sigma^2/2) - 1\) from a Gaussian random field with \(C_\ell \propto (\ell+1)^{-2}\).
Galactic mask at configurable latitude cut.
Contamination injection with chosen scenario (additive / multiplicative / combined / none) and known amplitudes \(a_i^{\rm true}\), \(b_i^{\rm true}\).
Poisson sampling of galaxy and random catalogs.

The MockCatalog dataclass stores all inputs and outputs for convenient downstream use.

Inputs: NSIDE, number of templates, true amplitudes (optional), scenario, mean galaxy density, seed.

Outputs: MockCatalog with RA/Dec arrays, template maps, true and observed overdensity fields, galactic mask, and the true contamination parameters.

Mock galaxy density field generation for validation and testing.

Provides physically-motivated synthetic galaxy catalogs with controlled systematic contamination. All scenarios produce a known ground-truth density field so that parameter recovery and decontamination quality can be measured exactly.

Contamination scenarios

"none": Pure lognormal galaxy field, no systematics.
"additive": \(\hat\delta_g = \delta_g + \sum_i a_i t_i\).
"multiplicative": \(\hat\delta_g = \delta_g (1 + \sum_i b_i t_i)\).
"combined": \(\hat\delta_g = \delta_g (1 + \sum_i b_i t_i) + \sum_i a_i t_i\).

Galaxy field model

The true overdensity is a lognormal random field,

\[\delta_g^{\rm true}(p) = e^{G(p) - \sigma^2/2} - 1\]

where \(G\) is a zero-mean Gaussian random field with power spectrum \(C_\ell \propto (\ell+1)^{-2}\) normalised so that \(\langle G^2 \rangle = \sigma^2\). Galaxy counts are Poisson-sampled:

\[n_g(p) \sim \mathrm{Poisson}\!\left[\bar n\,(1 + \hat\delta_g(p))\right]\]

References

Berlfein et al. 2024, MNRAS 531, 4954. Weaverdyck & Huterer 2021, MNRAS 503, 5061.

class sys_mapping.mocks.MockCatalog(scenario, nside, ra_gal, dec_gal, ra_rand, dec_rand, templates, delta_true, delta_obs, mask, a_true, b_true, n_mean, sigma, seed)[source]

Bases: object

Container for one synthetic galaxy catalog with known contamination.

Parameters:

scenario (str)
nside (int)
ra_gal (ndarray)
dec_gal (ndarray)
ra_rand (ndarray)
dec_rand (ndarray)
templates (ndarray)
delta_true (ndarray)
delta_obs (ndarray)
mask (ndarray)
a_true (ndarray)
b_true (ndarray)
n_mean (float)
sigma (float)
seed (int)

scenario

Contamination scenario label.

Type:: str

nside

HEALPix NSIDE used to generate the catalog.

Type:: int

ra_gal, dec_gal: Galaxy positions (degrees).

ra_rand, dec_rand: Random catalog positions (degrees).

templates

Template maps used (shape (n_sys, n_pix)).

Type:: numpy.ndarray

delta_true

True lognormal overdensity at every pixel (shape (n_pix,)).

Type:: numpy.ndarray

delta_obs

Observed (contaminated) overdensity at every pixel (shape (n_pix,)).

Type:: numpy.ndarray

mask

Boolean survey mask (True = included; shape (n_pix,)).

Type:: numpy.ndarray

a_true

Injected additive amplitudes (shape (n_sys,)).

Type:: numpy.ndarray

b_true

Injected multiplicative amplitudes (shape (n_sys,)).

Type:: numpy.ndarray

n_mean

Mean galaxies per pixel used for Poisson sampling.

Type:: float

sigma

Log-normal width \(\sigma\) of the underlying Gaussian field.

Type:: float

seed

Random seed used for reproducibility.

Type:: int

property n_sys: int

property n_gal: int

property n_rand: int

property n_pix: int

property n_good_pix: int

sys_mapping.mocks.generate_lognormal_field(nside, sigma=0.5, *, seed=None)[source]

Generate a lognormal galaxy overdensity field.

Draws a Gaussian random field \(G\) with power spectrum \(C_\ell \propto (\ell+1)^{-2}\) (normalised to variance \(\sigma^2\)), then computes the lognormal transform:

\[\delta_g(p) = e^{G(p) - \sigma^2/2} - 1\]

This ensures \(\langle\delta_g\rangle = 0\) exactly and produces a positively skewed overdensity distribution consistent with realistic galaxy number counts.

Parameters:

nside (int) – HEALPix NSIDE (typical choices: 16, 32, 64, 128).
sigma (float) – Log-normal width. sigma=0.5 gives mild clustering; sigma=1.0 gives strongly non-Gaussian fluctuations.
seed (int | None) – Random seed for reproducibility.

Returns:

True galaxy overdensity (shape (n_pix,)). Mean ≈ 0; standard deviation ≈ \(e^{\sigma^2} - 1\).

Return type:

delta_true

Examples

>>> from sys_mapping.mocks import generate_lognormal_field
>>> delta = generate_lognormal_field(nside=32, sigma=0.5, seed=0)
>>> delta.shape
(12288,)
>>> abs(float(delta.mean())) < 0.01
True
>>> float(delta.min()) > -1   # physically valid: n_g > 0
True

sys_mapping.mocks.make_galactic_mask(nside, lat_cut_deg=20.0)[source]

Boolean survey mask: exclude pixels within Galactic latitude b_gal < lat_cut_deg.

Parameters:

nside (int) – HEALPix NSIDE.
lat_cut_deg (float) – Galactic latitude cut in degrees.

Returns:

Boolean array (shape (n_pix,)); True = included.

Return type:

mask

Examples

>>> from sys_mapping.mocks import make_galactic_mask
>>> mask = make_galactic_mask(nside=32, lat_cut_deg=20.0)
>>> mask.dtype
dtype('bool')
>>> mask.mean() > 0.5   # more than half the sky survives
True

sys_mapping.mocks.make_mock_catalog(nside, n_sys, a_true=None, b_true=None, *, scenario='combined', template_families=None, n_mean=30.0, sigma=0.5, lat_cut_deg=20.0, rand_factor=8, seed=0)[source]

Generate a single mock galaxy catalog with controlled contamination.

Parameters:

nside (int) – HEALPix NSIDE (16 for unit tests, 32–64 for science validation).
n_sys (int) – Number of systematic templates.
a_true (ndarray | None) – Additive amplitudes (shape (n_sys,)). If None and scenario requires additive contamination, drawn from \(\mathcal{N}(0, 0.10)\).
b_true (ndarray | None) – Multiplicative amplitudes (shape (n_sys,)). Same default rule.
scenario (Literal['none', 'additive', 'multiplicative', 'combined']) – Which contamination model to apply. One of "none", "additive", "multiplicative", "combined".
template_families (list[int] | None) – HEALPix power-spectrum family indices (0–4) for template generation. Defaults to the first n_sys families.
n_mean (float) – Mean galaxies per pixel (controls Poisson noise level).
sigma (float) – Log-normal width of the true density field.
lat_cut_deg (float) – Galactic latitude cut in degrees.
rand_factor (int) – Random-to-data catalog size ratio.
seed (int) – Master random seed.

Returns:

Fully populated container with positions, templates, truth vectors, and the pixel-level density fields before and after contamination.

Return type:

MockCatalog

Examples

>>> from sys_mapping.mocks import make_mock_catalog
>>> mock = make_mock_catalog(nside=16, n_sys=2, scenario="additive", seed=0)
>>> mock.n_sys
2
>>> mock.n_gal > 0
True
>>> import numpy as np
>>> np.all(mock.a_true != 0) or mock.scenario == "none"
True

References

Berlfein et al. 2024, MNRAS 531, 4954.

sys_mapping.mocks.make_mock_suite(nside, n_sys, *, scenarios=None, a_amplitudes=None, b_amplitudes=None, n_mean=30.0, sigma=0.5, lat_cut_deg=20.0, rand_factor=8, seed=0)[source]

Generate a matched suite of mock catalogs across contamination scenarios.

All four scenarios share the same true density field and templates (only the contamination amplitudes differ), enabling direct comparison of how each decontamination method performs on identical underlying data.

Parameters:

nside (int) – HEALPix NSIDE.
n_sys (int) – Number of systematic templates.
scenarios (list[Literal['none', 'additive', 'multiplicative', 'combined']] | None) – List of scenario labels to generate. Defaults to all four: ["none", "additive", "multiplicative", "combined"].
a_amplitudes (ndarray | None) – Fixed additive amplitudes (shape (n_sys,)). If None, drawn from \(\mathcal{N}(0, 0.10)\).
b_amplitudes (ndarray | None) – Fixed multiplicative amplitudes (shape (n_sys,)).
n_mean (float) – Passed to make_mock_catalog().
sigma (float) – Passed to make_mock_catalog().
lat_cut_deg (float) – Passed to make_mock_catalog().
rand_factor (int) – Passed to make_mock_catalog().
seed (int) – Master seed; each scenario gets a deterministic child seed.

Returns:

Dict mapping scenario name → MockCatalog.

Return type:

suite

Examples

>>> from sys_mapping.mocks import make_mock_suite
>>> suite = make_mock_suite(nside=16, n_sys=2, seed=0)
>>> set(suite.keys()) == {"none", "additive", "multiplicative", "combined"}
True
>>> suite["additive"].n_sys
2