firecrown.metadata_functions

Two-point metadata functions module.

This module contains functions used to manipulate two-point metadata, including extracting metadata from a sacc file and creating new metadata objects.

Classes

TwoPointRealIndex	Intermediate object for reading SACC real-space two-point data.
TwoPointHarmonicIndex	Intermediate object for reading SACC harmonic-space two-point data.

Functions

make_measurement(value)	Create a Measurement object from a dictionary.
make_measurements(value)	Create a Measurement object from a dictionary.
make_measurement_dict(value)	Create a dictionary from a Measurement object.
make_measurements_dict(value)	Create a dictionary from a Measurement object.
make_correlation_space(value)	Create a CorrelationSpace object from a string.
extract_all_tracers_inferred_galaxy_zdists(sacc_data)	Extracts the two-point function metadata from a Sacc object.
extract_all_measured_types(sacc_data[, allow_mixed_types])	Extract all Measurement types associated with each tracer from a SACC object.
extract_all_real_metadata_indices(sacc_data[, ...])	Extract all two-point function metadata from a sacc file.
extract_all_harmonic_metadata_indices(sacc_data[, ...])	Extracts the two-point function metadata from a sacc file.
extract_all_harmonic_metadata(sacc_data[, ...])	Extract two-point harmonic-space metadata and data from a SACC file.
extract_all_real_metadata(sacc_data[, ...])	Extract two-point real-space metadata and data from a SACC file.
extract_all_photoz_bin_combinations(sacc_data[, ...])	Extract all two-point bin pair combinations from a SACC file.
extract_window_function(sacc_data, indices[, normalize])	Extract ells and weights for a window function.
maybe_enforce_window(ells, indices, sacc_data[, normalize])	Possibly enforce a window function on the given ells.
make_binned_two_point_filtered(inferred_galaxy_zdists, ...)	Create two-point correlations filtered by a bin pair selector.
make_all_photoz_bin_combinations(inferred_galaxy_zdists)	Create all possible two-point correlation combinations for galaxy bins.
make_all_photoz_bin_combinations_with_cmb(...[, ...])	Create all galaxy-galaxy and CMB-galaxy correlation combinations.
make_cmb_galaxy_combinations_only(inferred_galaxy_zdists)	Create only CMB-galaxy cross-correlations.
filter_two_point_combinations(combinations, ...)	Filter a list of TwoPointXY combinations using a bin pair selector.
make_two_point_xy(inferred_galaxy_zdists_dict, ...)	Build a mdt.TwoPointXY object from the inferred galaxy z distributions.
measurements_from_index(index)	Return the measurements from a TwoPointXiThetaIndex object.

Package Contents

class firecrown.metadata_functions.TwoPointRealIndex

Bases: TypedDict

Intermediate object for reading SACC real-space two-point data.

Internal use only - not intended for direct user interaction.

data_type: str

tracer_names: firecrown.metadata_types.TracerNames

tracer_types: tuple[firecrown.metadata_types.Measurement, firecrown.metadata_types.Measurement]

class firecrown.metadata_functions.TwoPointHarmonicIndex

Bases: TypedDict

Intermediate object for reading SACC harmonic-space two-point data.

Internal use only - not intended for direct user interaction.

data_type: str

tracer_names: firecrown.metadata_types.TracerNames

tracer_types: tuple[firecrown.metadata_types.Measurement, firecrown.metadata_types.Measurement]

firecrown.metadata_functions.make_measurement(value)

Create a Measurement object from a dictionary.

Parameters:

value (firecrown.metadata_types.Measurement | dict[str, Any])

Return type:

firecrown.metadata_types.Measurement

firecrown.metadata_functions.make_measurements(value)

Create a Measurement object from a dictionary.

Parameters:

value (set[firecrown.metadata_types.Measurement] | list[dict[str, Any]])

Return type:

set[firecrown.metadata_types.Measurement]

firecrown.metadata_functions.make_measurement_dict(value)

Create a dictionary from a Measurement object.

Parameters:

value (firecrown.metadata_types.Measurement) – the measurement to turn into a dictionary

Return type:

dict[str, str]

firecrown.metadata_functions.make_measurements_dict(value)

Create a dictionary from a Measurement object.

Parameters:

value (set[firecrown.metadata_types.Measurement]) – the measurement to turn into a dictionary

Return type:

list[dict[str, str]]

firecrown.metadata_functions.make_correlation_space(value)

Create a CorrelationSpace object from a string.

Parameters:

value (firecrown.metadata_types.TwoPointCorrelationSpace | str)

firecrown.metadata_functions.extract_all_tracers_inferred_galaxy_zdists(sacc_data, allow_mixed_types=False)

Extracts the two-point function metadata from a Sacc object.

The Sacc object contains a set of tracers (one-dimensional bins) and data points (measurements of the correlation between two tracers).

This function extracts the two-point function metadata from the Sacc object and returns it in a list.

Parameters:

• sacc_data (sacc.Sacc)

• allow_mixed_types (bool)

Return type:

list[firecrown.metadata_types.InferredGalaxyZDist]

firecrown.metadata_functions.extract_all_measured_types(sacc_data, allow_mixed_types=False)

Extract all Measurement types associated with each tracer from a SACC object.

This function analyzes the SACC data points to determine which Measurement types are associated with each tracer (tomographic bin). Following the SACC convention, a tracer should typically be associated with only one type of measurement (e.g., galaxy shear, galaxy counts, or CMB convergence), as these represent distinct observational probes.

SACC Tracer Ordering Convention

SACC enforces a strict ordering convention for cross-correlations between different measurement types. The measurement type with the lower enum value must appear first in both:

1. The data type string (e.g., ‘galaxy_shearDensity_cl_e’)

2. The tracer pair order (e.g., (src0, lens0))

Example - How Ordering is Determined:

Consider two tracers: src0 and lens0

Step 1: Identify measurement types from auto-correlations

• src0 × src0 with ‘galaxy_shear_cl_ee’ → src0 has SHEAR_E

• lens0 × lens0 with ‘galaxy_density_cl’ → lens0 has COUNTS

Step 2: Check cross-correlation ordering

• Since SHEAR_E < COUNTS (enum ordering)

• The cross-correlation SACC string is ‘galaxy_shearDensity_cl_e’

• Correct tracer order: (src0, lens0) ✓

• Incorrect tracer order: (lens0, src0) ✗ VIOLATION

Auto-Correction (Deprecated)

If your SACC file violates this convention, this function will attempt to auto-correct it by swapping tracer labels when allow_mixed_types=False. This auto-correction is provided as a convenience for legacy SACC files but is deprecated and will be removed in a future release.

Behavior Summary

• allow_mixed_types=False (default): Raises an error if a tracer has multiple measurement types. However, if the error is due to convention violations, the function attempts auto-correction first and warns about the deprecated behavior.

• allow_mixed_types=True: Permits mixed-type measurements in the same tomographic bin without raising an error.

param sacc_data:

The SACC object containing tracers and data points.

param allow_mixed_types:

Controls handling of mixed-type measurements. If False (default), raises an error when a tracer has multiple measurement types (unless auto-corrected). If True, allows mixed-type measurements without error.

return:

Dictionary mapping tracer names to sets of Measurement types associated with that tracer.

raises ValueError:

If a tracer has multiple measurement types and allow_mixed_types=False (after attempting auto-correction).

See Also

For detailed information about the SACC convention and how to fix violations:

https://firecrown.readthedocs.io/en/latest/sacc_usage.html

Parameters:

• sacc_data (sacc.Sacc)

• allow_mixed_types (bool)

Return type:

tuple[dict[str, set[firecrown.metadata_types.Measurement]], list[str]]

firecrown.metadata_functions.extract_all_real_metadata_indices(sacc_data, allow_mixed_types=False, allowed_data_type=None)

Extract all two-point function metadata from a sacc file.

Extracts the two-point function measurement metadata for all measurements made in real space from a Sacc object.

Parameters:

• sacc_data (sacc.Sacc)

• allow_mixed_types (bool)

• allowed_data_type (None | list[str])

Return type:

list[firecrown.metadata_functions._type_defs.TwoPointRealIndex]

firecrown.metadata_functions.extract_all_harmonic_metadata_indices(sacc_data, allow_mixed_types=False, allowed_data_type=None)

Extracts the two-point function metadata from a sacc file.

Parameters:

• sacc_data (sacc.Sacc)

• allow_mixed_types (bool)

• allowed_data_type (None | list[str])

Return type:

list[firecrown.metadata_functions._type_defs.TwoPointHarmonicIndex]

firecrown.metadata_functions.extract_all_harmonic_metadata(sacc_data, allowed_data_type=None, allow_mixed_types=False, bin_pair_selector=None, normalize=True)

Extract two-point harmonic-space metadata and data from a SACC file.

Parameters:

• sacc_data (sacc.Sacc) – The SACC object containing tracers and data points.

• allowed_data_type (None | list[str]) – Optional list of SACC data type strings to include. If None, all harmonic-space data types are extracted.

• allow_mixed_types (bool) – If True, allow extraction when tracers contain mixed measurement types; otherwise require consistent tracer measurement typing.

• bin_pair_selector (None | firecrown.metadata_types.BinPairSelector) – Optional selector to filter which bin pairs to include. If None, all valid bin pairs are returned.

• normalize (bool) – If True, normalize the window function weights to sum to 1.

Returns:

List of TwoPointHarmonic objects with metadata and ell values.

Return type:

list[firecrown.metadata_types.TwoPointHarmonic]

firecrown.metadata_functions.extract_all_real_metadata(sacc_data, allowed_data_type=None, allow_mixed_types=False, bin_pair_selector=None)

Extract two-point real-space metadata and data from a SACC file.

Parameters:

• sacc_data (sacc.Sacc) – The SACC object containing tracers and data points.

• allowed_data_type (None | list[str]) – Optional list of SACC data type strings to include. If None, all real-space data types are extracted.

• bin_pair_selector (None | firecrown.metadata_types.BinPairSelector) – Optional selector to filter which bin pairs to include. If None, all valid bin pairs are returned.

• allow_mixed_types (bool)

Returns:

List of TwoPointReal objects with metadata and theta values.

Return type:

list[firecrown.metadata_types.TwoPointReal]

firecrown.metadata_functions.extract_all_photoz_bin_combinations(sacc_data, allow_mixed_types=False, bin_pair_selector=None)

Extract all two-point bin pair combinations from a SACC file.

Parameters:

• sacc_data (sacc.Sacc) – The SACC object containing tracers and data points.

• bin_pair_selector (None | firecrown.metadata_types.BinPairSelector) – Optional selector to filter which bin pairs to include. If None, all valid bin pairs are returned.

• allow_mixed_types (bool)

Returns:

List of TwoPointXY objects representing valid bin pair combinations.

Return type:

list[firecrown.metadata_types.TwoPointXY]

firecrown.metadata_functions.extract_window_function(sacc_data, indices, normalize=True)

Extract ells and weights for a window function.

Parameters:

• sacc_data (sacc.Sacc) – the Sacc object from which we read.

• indices (numpy.typing.NDArray[numpy.int64]) – the indices of the data points in the Sacc object which are computed by the window function.

• normalize (bool) – if True, normalize the window function weights to sum to 1.

Returns:

the ells and weights of the window function that match the given indices from a sacc object, or a tuple of (None, None) if the indices represent the measured Cells directly.

Raises:

ValueError – if any window function column has zero total weight.

Return type:

tuple[None | numpy.typing.NDArray[numpy.int64], None | numpy.typing.NDArray[numpy.float64]]

firecrown.metadata_functions.maybe_enforce_window(ells, indices, sacc_data, normalize=True)

Possibly enforce a window function on the given ells.

Parameters:

• ells (numpy.typing.NDArray) – The original ell values.

• indices (numpy.typing.NDArray[numpy.int64]) – The indices of the data points in the SACC object.

• sacc_data (sacc.Sacc) – The SACC object containing the data.

• normalize (bool) – if True, normalize the window function weights to sum to 1.

Returns:

A tuple containing the possibly replaced ells, the window weights, and window_ells, the original ell grid used by the window (or None if no window function is applied).

Return type:

tuple[numpy.typing.NDArray[numpy.int64], None | numpy.typing.NDArray[numpy.float64], None | numpy.typing.NDArray]

firecrown.metadata_functions.make_binned_two_point_filtered(inferred_galaxy_zdists, bin_pair_selector)

Create two-point correlations filtered by a bin pair selector.

This function generates all possible bin combinations and then filters them using the provided selector, keeping only pairs that satisfy the selection criteria (e.g., auto-correlations only, specific measurements, neighboring bins).

Parameters:

• inferred_galaxy_zdists (list[firecrown.metadata_types.InferredGalaxyZDist]) – List of tomographic redshift bins with their associated measurement types.

• bin_pair_selector (firecrown.metadata_types.BinPairSelector) – Selector defining which bin pairs to include.

Returns:

List of TwoPointXY combinations that pass the selector’s criteria.

Raises:

ValueError – If duplicate bin names are found in inferred_galaxy_zdists.

Return type:

list[firecrown.metadata_types.TwoPointXY]

Example:

# Get only auto-correlations of source measurements selector = AutoNameBinPairSelector() & SourceBinPairSelector() combinations = make_binned_two_point_filtered(bins, selector)

firecrown.metadata_functions.make_all_photoz_bin_combinations(inferred_galaxy_zdists)

Create all possible two-point correlation combinations for galaxy bins.

This function generates all possible pairs of (bin, measurement) combinations, keeping only those where the measurements are compatible. For auto-correlations (same measurement type), only unique pairs are kept to avoid duplicates (e.g., only bin0-bin1, not both bin0-bin1 and bin1-bin0).

Parameters:

inferred_galaxy_zdists (list[firecrown.metadata_types.InferredGalaxyZDist]) – List of tomographic redshift bins with their associated measurement types.

Returns:

List of all valid TwoPointXY combinations.

Raises:

ValueError – If duplicate bin names are found in inferred_galaxy_zdists.

Return type:

list[firecrown.metadata_types.TwoPointXY]

firecrown.metadata_functions.make_all_photoz_bin_combinations_with_cmb(inferred_galaxy_zdists, cmb_tracer_name='cmb_convergence', include_cmb_auto=False)

Create all galaxy-galaxy and CMB-galaxy correlation combinations.

This function generates all possible two-point correlations including both galaxy-galaxy auto/cross-correlations and CMB-galaxy cross-correlations.

Parameters:

• inferred_galaxy_zdists (list[firecrown.metadata_types.InferredGalaxyZDist]) – List of galaxy redshift bins with their associated measurement types.

• cmb_tracer_name (str) – Name to assign to the CMB tracer (default: “cmb_convergence”).

• include_cmb_auto (bool) – Whether to include CMB auto-correlation (default: False).

Returns:

Combined list of galaxy-galaxy and CMB-galaxy correlation combinations.

Raises:

ValueError – If duplicate bin names are found in inferred_galaxy_zdists.

Return type:

list[firecrown.metadata_types.TwoPointXY]

firecrown.metadata_functions.make_cmb_galaxy_combinations_only(inferred_galaxy_zdists, cmb_tracer_name='cmb_convergence', include_cmb_auto=False)

Create only CMB-galaxy cross-correlations.

This function generates cross-correlations between CMB convergence and galaxy measurements, optionally including the CMB auto-correlation. It does NOT include any galaxy-galaxy correlations.

Parameters:

• inferred_galaxy_zdists (list[firecrown.metadata_types.InferredGalaxyZDist]) – List of galaxy redshift bins with their associated measurement types.

• cmb_tracer_name (str) – Name to assign to the CMB tracer (default: “cmb_convergence”).

• include_cmb_auto (bool) – Whether to include CMB auto-correlation (default: False).

Returns:

List of CMB-galaxy cross-correlation combinations (and optionally CMB auto).

Raises:

ValueError – If duplicate bin names are found in inferred_galaxy_zdists.

Return type:

list[firecrown.metadata_types.TwoPointXY]

firecrown.metadata_functions.filter_two_point_combinations(combinations, bin_pair_selector)

Filter a list of TwoPointXY combinations using a bin pair selector.

This function takes an existing list of TwoPointXY combinations and applies the provided selector to filter out pairs that do not meet the selection criteria. This function preserves the order of the input combinations while applying the filter.

Parameters:

• combinations (list[firecrown.metadata_types.TwoPointXY]) – List of TwoPointXY combinations to filter.

• bin_pair_selector (firecrown.metadata_types.BinPairSelector) – Selector defining which bin pairs to include.

Returns:

List of TwoPointXY combinations that pass the selector’s criteria.

Return type:

list[firecrown.metadata_types.TwoPointXY]

Example:

# Filter existing combinations to get only auto-correlations of source # measurements selector = AutoNameBinPairSelector() & SourceBinPairSelector() filtered_combinations = filter_two_point_combinations(combinations, selector)

firecrown.metadata_functions.make_two_point_xy(inferred_galaxy_zdists_dict, tracer_names, data_type)

Build a mdt.TwoPointXY object from the inferred galaxy z distributions.

The mdt.TwoPointXY object is built from the inferred galaxy z distributions, the data type, and the tracer names.

Parameters:

• inferred_galaxy_zdists_dict (dict[str, firecrown.metadata_types.InferredGalaxyZDist]) – a dictionary of inferred galaxy z distributions.

• tracer_names (firecrown.metadata_types.TracerNames) – a tuple of tracer names.

• data_type (str) – the data type.

Returns:

a mdt.TwoPointXY object.

Raises:

ValueError – If the tracer measurements do not match the data type specification according to the SACC naming convention.

Return type:

firecrown.metadata_types.TwoPointXY

firecrown.metadata_functions.measurements_from_index(index)

Return the measurements from a TwoPointXiThetaIndex object.

Parameters:

index (firecrown.metadata_functions._type_defs.TwoPointRealIndex | firecrown.metadata_functions._type_defs.TwoPointHarmonicIndex)

Return type:

tuple[str, firecrown.metadata_types.Measurement, str, firecrown.metadata_types.Measurement]