firecrown.metadata_functions ============================ .. py:module:: firecrown.metadata_functions .. autoapi-nested-parse:: 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 ------- .. autoapisummary:: firecrown.metadata_functions.TwoPointRealIndex firecrown.metadata_functions.TwoPointHarmonicIndex Functions --------- .. autoapisummary:: firecrown.metadata_functions.make_measurement firecrown.metadata_functions.make_measurements firecrown.metadata_functions.make_measurement_dict firecrown.metadata_functions.make_measurements_dict firecrown.metadata_functions.make_correlation_space firecrown.metadata_functions.extract_all_tracers_inferred_galaxy_zdists firecrown.metadata_functions.extract_all_measured_types firecrown.metadata_functions.extract_all_real_metadata_indices firecrown.metadata_functions.extract_all_harmonic_metadata_indices firecrown.metadata_functions.extract_all_harmonic_metadata firecrown.metadata_functions.extract_all_real_metadata firecrown.metadata_functions.extract_all_photoz_bin_combinations firecrown.metadata_functions.extract_window_function firecrown.metadata_functions.maybe_enforce_window firecrown.metadata_functions.make_binned_two_point_filtered firecrown.metadata_functions.make_all_photoz_bin_combinations firecrown.metadata_functions.make_all_photoz_bin_combinations_with_cmb firecrown.metadata_functions.make_cmb_galaxy_combinations_only firecrown.metadata_functions.filter_two_point_combinations firecrown.metadata_functions.make_two_point_xy firecrown.metadata_functions.measurements_from_index Package Contents ---------------- .. py:class:: TwoPointRealIndex Bases: :py:obj:`TypedDict` .. autoapi-inheritance-diagram:: firecrown.metadata_functions.TwoPointRealIndex :parts: 1 Intermediate object for reading SACC real-space two-point data. Internal use only - not intended for direct user interaction. .. py:attribute:: data_type :type: str .. py:attribute:: tracer_names :type: firecrown.metadata_types.TracerNames .. py:attribute:: tracer_types :type: tuple[firecrown.metadata_types.Measurement, firecrown.metadata_types.Measurement] .. py:class:: TwoPointHarmonicIndex Bases: :py:obj:`TypedDict` .. autoapi-inheritance-diagram:: firecrown.metadata_functions.TwoPointHarmonicIndex :parts: 1 Intermediate object for reading SACC harmonic-space two-point data. Internal use only - not intended for direct user interaction. .. py:attribute:: data_type :type: str .. py:attribute:: tracer_names :type: firecrown.metadata_types.TracerNames .. py:attribute:: tracer_types :type: tuple[firecrown.metadata_types.Measurement, firecrown.metadata_types.Measurement] .. py:function:: make_measurement(value) Create a Measurement object from a dictionary. .. py:function:: make_measurements(value) Create a Measurement object from a dictionary. .. py:function:: make_measurement_dict(value) Create a dictionary from a Measurement object. :param value: the measurement to turn into a dictionary .. py:function:: make_measurements_dict(value) Create a dictionary from a Measurement object. :param value: the measurement to turn into a dictionary .. py:function:: make_correlation_space(value) Create a CorrelationSpace object from a string. .. py:function:: 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. .. py:function:: 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 .. py:function:: 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. .. py:function:: 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. .. py:function:: 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. :param sacc_data: The SACC object containing tracers and data points. :param allowed_data_type: Optional list of SACC data type strings to include. If None, all harmonic-space data types are extracted. :param allow_mixed_types: If True, allow extraction when tracers contain mixed measurement types; otherwise require consistent tracer measurement typing. :param bin_pair_selector: Optional selector to filter which bin pairs to include. If None, all valid bin pairs are returned. :param normalize: If True, normalize the window function weights to sum to 1. :return: List of TwoPointHarmonic objects with metadata and ell values. .. py:function:: 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. :param sacc_data: The SACC object containing tracers and data points. :param allowed_data_type: Optional list of SACC data type strings to include. If None, all real-space data types are extracted. :param bin_pair_selector: Optional selector to filter which bin pairs to include. If None, all valid bin pairs are returned. :return: List of TwoPointReal objects with metadata and theta values. .. py:function:: 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. :param sacc_data: The SACC object containing tracers and data points. :param bin_pair_selector: Optional selector to filter which bin pairs to include. If None, all valid bin pairs are returned. :return: List of TwoPointXY objects representing valid bin pair combinations. .. py:function:: extract_window_function(sacc_data, indices, normalize = True) Extract ells and weights for a window function. :param sacc_data: the Sacc object from which we read. :param indices: the indices of the data points in the Sacc object which are computed by the window function. :param normalize: if True, normalize the window function weights to sum to 1. :return: 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. .. py:function:: maybe_enforce_window(ells, indices, sacc_data, normalize = True) Possibly enforce a window function on the given ells. :param ells: The original ell values. :param indices: The indices of the data points in the SACC object. :param sacc_data: The SACC object containing the data. :param normalize: if True, normalize the window function weights to sum to 1. :return: 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). .. py:function:: 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). :param inferred_galaxy_zdists: List of tomographic redshift bins with their associated measurement types. :param bin_pair_selector: Selector defining which bin pairs to include. :return: List of TwoPointXY combinations that pass the selector's criteria. :raises ValueError: If duplicate bin names are found in inferred_galaxy_zdists. Example: # Get only auto-correlations of source measurements selector = AutoNameBinPairSelector() & SourceBinPairSelector() combinations = make_binned_two_point_filtered(bins, selector) .. py:function:: 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). :param inferred_galaxy_zdists: List of tomographic redshift bins with their associated measurement types. :return: List of all valid TwoPointXY combinations. :raises ValueError: If duplicate bin names are found in inferred_galaxy_zdists. .. py:function:: 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. :param inferred_galaxy_zdists: List of galaxy redshift bins with their associated measurement types. :param cmb_tracer_name: Name to assign to the CMB tracer (default: "cmb_convergence"). :param include_cmb_auto: Whether to include CMB auto-correlation (default: False). :return: Combined list of galaxy-galaxy and CMB-galaxy correlation combinations. :raises ValueError: If duplicate bin names are found in inferred_galaxy_zdists. .. py:function:: 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. :param inferred_galaxy_zdists: List of galaxy redshift bins with their associated measurement types. :param cmb_tracer_name: Name to assign to the CMB tracer (default: "cmb_convergence"). :param include_cmb_auto: Whether to include CMB auto-correlation (default: False). :return: List of CMB-galaxy cross-correlation combinations (and optionally CMB auto). :raises ValueError: If duplicate bin names are found in inferred_galaxy_zdists. .. py:function:: 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. :param combinations: List of TwoPointXY combinations to filter. :param bin_pair_selector: Selector defining which bin pairs to include. :return: List of TwoPointXY combinations that pass the selector's criteria. Example: # Filter existing combinations to get only auto-correlations of source # measurements selector = AutoNameBinPairSelector() & SourceBinPairSelector() filtered_combinations = filter_two_point_combinations(combinations, selector) .. py:function:: 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. :param inferred_galaxy_zdists_dict: a dictionary of inferred galaxy z distributions. :param tracer_names: a tuple of tracer names. :param data_type: the data type. :return: a mdt.TwoPointXY object. :raises ValueError: If the tracer measurements do not match the data type specification according to the SACC naming convention. .. py:function:: measurements_from_index(index) Return the measurements from a TwoPointXiThetaIndex object.