Advanced functions

This list is not complete, but aims to provide references for the more used/useful extended features.

Covariance comparison functions

Compact measures for covariance matrix comparison introduced in Section 3.1 of Rashkovetskyi et al 2023 and briefly explained again in Section 2.2 of Rashkovetskyi et al 2025.

RascalC.cov_comparison.rms_eig_inv_test_covs(C1: ndarray[float], C2: ndarray[float]) → float

Compute the R_inv comparison measure (see Equation 3.4 of Rashkovetskyi et al 2023 or Equation 2.17 of Rashkovetskyi et al 2025) between two covariance matrices; the first is inverted.

RascalC.cov_comparison.KL_div_covs(C1: ndarray[float], C2: ndarray[float]) → float

Compute the Kullback-Leibler divergence between two covariance matrices; the first is inverted.

RascalC.cov_comparison.chi2_red_covs(C1: ndarray[float], C2: ndarray[float]) → float

Compute the reduced chi-squared comparison measure (see Equation 3.4 of Rashkovetskyi et al 2023 or Equation 2.18 of Rashkovetskyi et al 2025) between two covariance matrices; the first is inverted.

Extra convergence check functions

Extra convergence check is performed in the main wrapper function (RascalC.run_cov) and also performed by default in the automatic post-processing function (RascalC.post_process_auto), but the following functions may be useful to run additionally.

Functions to perform extra convergence check on full (and jackknife) RascalC integrals. More specifically, divide integral subsamples into halves and check similarity of their average results. These methods work in any mode — e.g. jackknife, Legendre, multi-tracer — as it utilizes universal data from RascalC file

RascalC.convergence_check_extra.cmp_cov(cov_first: ~numpy.ndarray[float], cov_second: ~numpy.ndarray[float], print_function: ~typing.Callable[[str], None] = <function blank_function>) → dict[str, float]

Compute the selected comparison measures between two covariance matrices and return as a dictionary. This method is decribed in Section 3.2 of Rashkovetskyi et al 2023. Optionally, use print_function to report the results.

RascalC.convergence_check_extra.convergence_check_extra_splittings(c_samples: ~numpy.ndarray[float], n_samples: int | None = None, print_function: ~typing.Callable[[str], None] = <function blank_function>) → dict[str, dict[str, float]]

Perform two different splittings in halves using the covariance matrix samples c_samples, compute the comparison measures between the two average covariance matrices and return as a dictionary. This method is decribed in Section 3.2 of Rashkovetskyi et al 2023. Optionally, use only n_samples first samples. Further optionally, use print_function to report the results.

RascalC.convergence_check_extra.convergence_check_extra(rascalc_results: dict[str], n_samples: int | None = None, print_function: ~typing.Callable[[str], None] = <function blank_function>) → dict[str, dict[str, dict[str, float]]]

Perform two different splittings in halves using the RascalC results file/dictionary, compute the comparison measures between the two average covariance matrices and return as a dictionary. Do this for full and jackknife covariance matrices (if the latter are present). This method is decribed in Section 3.2 of Rashkovetskyi et al 2023. Optionally, use only n_samples first samples. Further optionally, use print_function to report the results.

RascalC.convergence_check_extra.convergence_check_extra_file(rascalc_results_filename: str, n_samples: int | None = None, print_function: ~typing.Callable[[str], None] = <function blank_function>) → dict[str, dict[str, dict[str, float]]]

Perform two different splittings in halves using the RascalC results filename, compute the comparison measures between the two average covariance matrices and return as a dictionary. Do this for full and jackknife covariance matrices (if the latter are present). This method is decribed in Section 3.2 of Rashkovetskyi et al 2023. Optionally, use only n_samples first samples. Further optionally, use print_function to report the results.

Sample catenation function

RascalC.cat_raw_covariance_matrices(n: int, mstr: str, input_roots: list[str], ns_samples: list[None | int | ~typing.Iterable[int] | ~typing.Iterable[bool]], output_root: str, collapse_factor: int = 1, print_function: ~typing.Callable[[str], None] = <built-in function print>) → dict[str]

Catenate the raw covariance matrices from one or more input directories, assuming they are from similar runs: the same number of input random points, N2, N3, N4 and loops_per_sample.

Parameters

ninteger

The number of radial bins.

mstrstring

The next part of the output configuration label: m{number of angular bins} in s_mu mode and l{max_multipole} in Legendre modes.

input_rootslist of strings

Input directories to catenate from.

ns_sampleslist of the same length as input_roots

Each element allows to select subsamples flexibly from the corresponding input directory:

• if None, returns all samples;

• if a positive integer, returns as many samples from the beginning;

• if a sequence of integers, returns subsamples with indices from this sequence;

• sequence of boolean values is interpreted as a boolean mask for subsamples.

output_rootstring

The output directory, in which the NumPy file with the resulting raw covariance matrix arrays is created.

collapse_factorpositive integer

(Optional) allows to reduce the number of subsamples by averaging over a given number of adjacent subsamples. Default value is 1, meaning no reduction.

print_functionCallable

(Optional) custom function to use for printing. Default is print.

Returns

catenation_resultsdict[str, np.ndarray[float]]

Catenated raw covariance matrices as a dictionary with string keys and Numpy array values. All this information is also saved in a Raw_Covariance_Matrices*.npz file in the output_root.

Covariance combination functions for two independent regions

These functions follow the particular procedure for combination of DESI NGC and SGC 2-point correlation function measurements into GCcomb (previously N and S into NS). For more information, see Appendix B of Rashkovetskyi et al 2025.

RascalC.combine_regions.combine_covs(rascalc_results1: str, rascalc_results2: str, pycorr_file1: str, pycorr_file2: str, output_cov_file: str, n_mu_bins: int | None = None, r_step: float = 1, skip_r_bins: int | tuple[int, int] = 0, output_cov_file1: str | None = None, output_cov_file2: str | None = None, print_function: ~typing.Callable[[str], None] = <built-in function print>) → ndarray[float]

Produce s,mu mode single-tracer covariance matrix for the region/footprint that is a combination of two regions/footprints neglecting the correlations between the clustering statistics in the different regions. For additional details, see Appendix B.1 of Rashkovetskyi et al 2025.

Parameters

rascalc_results1, rascalc_results2string

Filenames for the RascalC (post-processing) results for the two regions in NumPy format.

pycorr_file1, pycorr_file2string

Filenames for the pycorr (https://github.com/cosmodesi/pycorr) .npy files with the correlation functions and pair counts for the two regions. The order of regions must be the same as in RascalC results.

output_cov_filestring

Filename for the output text file, in which the covariance matrix will be saved.

n_mu_binsinteger

The number of angular (mu) bins, must match the RascalC results.

r_stepfloat

The width of the radial (separation) bins, must match the RascalC results.

skip_r_binsinteger or tuple of two integers

(Optional) removal of some radial bins from the loaded pycorr counts before adjusting the radial (separation) bin width to match the covariance settings. First (or the only) number sets the number of radial/separation bins to skip from the beginning. Second number (if provided) sets the number of radial/separation bins to skip from the end. By default, no bins are skipped. E.g. if the pycorr counts are in 1 Mpc/h bins from 0 to 200 Mpc/h and the RascalC covariances are computed only between 20 and 200 Mpc/h, skip_r_bins should be 20.

output_cov_file1, output_cov_file2string or None

(Optional) if provided, the text covariance matrices for the corresponding region will be saved in this file.

print_functionCallable[[str], None]

(Optional) custom function to use for printing. Needs to take string arguments and not return anything. Default is print.

Returns

combined_covnp.ndarray[float]

The resulting covariance matrix for the combined region.

RascalC.combine_regions.combine_covs_legendre(rascalc_results1: str, rascalc_results2: str, pycorr_file1: str, pycorr_file2: str, output_cov_file: str, max_l: int, r_step: float = 1, skip_r_bins: int | tuple[int, int] = 0, output_cov_file1: str | None = None, output_cov_file2: str | None = None, print_function: ~typing.Callable[[str], None] = <built-in function print>) → ndarray[float]

Produce Legendre mode single-tracer covariance matrix for the region/footprint that is a combination of two regions/footprints neglecting the correlations between the clustering statistics in the different regions. For additional details, see Appendix B.2 of Rashkovetskyi et al 2025.

Parameters

rascalc_results1, rascalc_results2string

Filenames for the RascalC (post-processing) results for the two regions in NumPy format.

pycorr_file1, pycorr_file2string

Filenames for the pycorr (https://github.com/cosmodesi/pycorr) .npy files with the correlation functions and pair counts for the two regions. The order of regions must be the same as in RascalC results.

output_cov_filestring

Filename for the output text file, in which the covariance matrix will be saved.

max_linteger

The highest (even) multipole index, must match the RascalC results.

r_stepfloat

The width of the radial (separation) bins, must match the RascalC results.

skip_r_binsinteger or tuple of two integers

(Optional) removal of some radial bins from the loaded pycorr counts before adjusting the radial (separation) bin width to match the covariance settings. First (or the only) number sets the number of radial/separation bins to skip from the beginning. Second number (if provided) sets the number of radial/separation bins to skip from the end. By default, no bins are skipped. E.g. if the pycorr counts are in 1 Mpc/h bins from 0 to 200 Mpc/h and the RascalC covariances are computed only between 20 and 200 Mpc/h, skip_r_bins should be 20.

output_cov_file1, output_cov_file2string or None

(Optional) if provided, the text covariance matrices for the corresponding region will be saved in this file.

print_functionCallable[[str], None]

(Optional) custom function to use for printing. Needs to take string arguments and not return anything. Default is print.

Returns

combined_covnp.ndarray[float]

The resulting covariance matrix for the combined region.

RascalC.combine_regions.combine_covs_multi(rascalc_results1: str, rascalc_results2: str, pycorr_files1: list[str], pycorr_files2: list[str], output_cov_file: str, n_mu_bins: int | None = None, r_step: float = 1, skip_r_bins: int | tuple[int, int] = 0, output_cov_file1: str | None = None, output_cov_file2: str | None = None, print_function: ~typing.Callable[[str], None] = <built-in function print>) → ndarray[float]

Produce s,mu mode two-tracer covariance matrix for the region/footprint that is a combination of two regions/footprints neglecting the correlations between the clustering statistics in the different regions. For additional details, see Appendix B.1 of Rashkovetskyi et al 2025.

Parameters

rascalc_results1, rascalc_results2string

Filenames for the RascalC (post-processing) results for the two regions in NumPy format.

pycorr_file1, pycorr_file2list of strings

Filenames for the pycorr (https://github.com/cosmodesi/pycorr) .npy files with the correlation functions and pair counts for the two regions. Each list must contain three filenames: first for the auto-correlation of the first tracer, second for the cross-correlation of the two tracers, and the third for the auto-correlation of the second tracer. The order of regions must be the same as in RascalC results.

output_cov_filestring

Filename for the output text file, in which the covariance matrix will be saved.

n_mu_binsinteger

The number of angular (mu) bins, must match the RascalC results.

r_stepfloat

The width of the radial (separation) bins, must match the RascalC results.

skip_r_binsinteger or tuple of two integers

(Optional) removal of some radial bins from the loaded pycorr counts before adjusting the radial (separation) bin width to match the covariance settings. First (or the only) number sets the number of radial/separation bins to skip from the beginning. Second number (if provided) sets the number of radial/separation bins to skip from the end. By default, no bins are skipped. E.g. if the pycorr counts are in 1 Mpc/h bins from 0 to 200 Mpc/h and the RascalC covariances are computed only between 20 and 200 Mpc/h, skip_r_bins should be 20.

output_cov_file1, output_cov_file2string or None

(Optional) if provided, the text covariance matrices for the corresponding region will be saved in this file.

print_functionCallable[[str], None]

(Optional) custom function to use for printing. Needs to take string arguments and not return anything. Default is print.

Returns

combined_covnp.ndarray[float]

The resulting covariance matrix for the combined region.

RascalC.combine_regions.combine_covs_legendre_multi(rascalc_results1: str, rascalc_results2: str, pycorr_files1: list[str], pycorr_files2: list[str], output_cov_file: str, max_l: int, r_step: float = 1, skip_r_bins: int | tuple[int, int] = 0, output_cov_file1: str | None = None, output_cov_file2: str | None = None, print_function: ~typing.Callable[[str], None] = <built-in function print>) → ndarray[float]

Produce Legendre mode two-tracer covariance matrix for the region/footprint that is a combination of two regions/footprints neglecting the correlations between the clustering statistics in the different regions. For additional details, see Appendix B.2 of Rashkovetskyi et al 2025.

Parameters

rascalc_results1, rascalc_results2string

Filenames for the RascalC (post-processing) results for the two regions in NumPy format.

pycorr_file1, pycorr_file2string

Filenames for the pycorr (https://github.com/cosmodesi/pycorr) .npy files with the correlation functions and pair counts for the two regions. Each list must contain three filenames: first for the auto-correlation of the first tracer, second for the cross-correlation of the two tracers, and the third for the auto-correlation of the second tracer. The order of regions must be the same as in RascalC results.

output_cov_filestring

Filename for the output text file, in which the covariance matrix will be saved.

max_linteger

The highest (even) multipole index, must match the RascalC results.

r_stepfloat

The width of the radial (separation) bins, must match the RascalC results.

skip_r_binsinteger or tuple of two integers

(Optional) removal of some radial bins from the loaded pycorr counts before adjusting the radial (separation) bin width to match the covariance settings. First (or the only) number sets the number of radial/separation bins to skip from the beginning. Second number (if provided) sets the number of radial/separation bins to skip from the end. By default, no bins are skipped. E.g. if the pycorr counts are in 1 Mpc/h bins from 0 to 200 Mpc/h and the RascalC covariances are computed only between 20 and 200 Mpc/h, skip_r_bins should be 20.

output_cov_file1, output_cov_file2string or None

(Optional) if provided, the text covariance matrices for the corresponding region will be saved in this file.

print_functionCallable[[str], None]

(Optional) custom function to use for printing. Needs to take string arguments and not return anything. Default is print.

Returns

combined_covnp.ndarray[float]

The resulting covariance matrix for the combined region.

Sample covariance utility functions

Radial and angular bins (s_mu binning mode)

These functions generate sample covariances of binned \(\xi(s,\mu)\) from cosmodesi/pycorr s_mu 2PCF estimators

RascalC.pycorr_utils.sample_cov.sample_cov_from_pycorr(xi_estimators: list[list[BaseTwoPointEstimator]], n_mu: int | None = None, r_step: float | None = None, r_max: float = inf) → ndarray[float]

Produce a sample covariance of binned \(\xi(s,\mu)\) from cosmodesi/pycorr s_mu 2PCF estimators. Multiple tracers are supported.

Parameters

xi_estimatorslist of lists of pycorr.twopoint_estimator.BaseTwoPointEstimators

The first element must be the list of first tracer auto-correlation function estimators. The (optional) second element should be the list of cross-correlation function estimators between the 1st and the 2nd tracer. (Ordering of mock realizations must be the same, or the cross-covariance blocks will be wrong.) The (optional) third element should be the list of second tracer auto-correlation function estimators. This ordering can be extended (or altered) but it must be consistent.

n_muinteger or None

(Optional) If integer, number of angular (\(\mu\)) bins to rebin to (after wrapping). If None (default), the angular bins are unchanged aside from wrapping of \(-1 \le \mu < 0\) bins into \(0 \le \mu \le 1\).

r_step: float or None

(Optional) If float, sets the uniform spacing of radial/separation bins. If None (default), the radial/separation binning is not changed.

r_max: float

(Optional) Sets the maximum radius/separation, any bins beyond that value are discarded. By default, the value is infinity, so no bins are discarded.

RascalC.pycorr_utils.sample_cov.sample_cov_from_pycorr_to_file(xi_estimators: list[list[BaseTwoPointEstimator]], outfile_name: str, n_mu: int | None = None, r_step: float | None = None, r_max: float = inf) → None

Produce a sample covariance of binned \(\xi(s,\mu)\) from cosmodesi/pycorr s_mu 2PCF estimators and write the matrix to a text file. Multiple tracers are supported.

Parameters are analogous to sample_cov_from_pycorr() except

outfile_namestring (filename)

The name for the output text file.

RascalC.pycorr_utils.sample_cov.sample_cov_from_pycorr_files(infile_names: list[list[str]], outfile_name: str, n_mu: int | None = None, r_step: float | None = None, r_max: float = inf)

Produce a sample covariance of binned \(\xi(s,\mu)\) from cosmodesi/pycorr s_mu .npy files and write the matrix to a text file. Multiple tracers are supported.

Parameters

infile_nameslist of lists of strings (filenames)

The first element must be the list of first tracer auto-correlation function estimator filenames. The (optional) second element should be the list of cross-correlation function estimator filenames between the 1st and the 2nd tracer. (Ordering of mock realizations must be the same, or the cross-covariance blocks will be wrong.) The (optional) third element should be the list of second tracer auto-correlation function estimator filenames. This ordering can be extended (or altered) but it must be consistent.

outfile_namestring

The name for the output text file.

n_muinteger or None

(Optional) If integer, number of angular (\(\mu\)) bins to rebin to (after wrapping). If None (default), the angular bins are unchanged aside from wrapping of \(-1 \le \mu < 0\) bins into \(0 \le \mu \le 1\).

r_step: float or None

(Optional) If float, sets the uniform spacing of radial/separation bins. If None (default), the radial/separation binning is not changed.

r_max: float

(Optional) Sets the maximum radius/separation, any bins beyond that value are discarded. By default, the value is infinity, so no bins are discarded.

Legendre multipoles (legendre binning modes)

These functions generate sample covariances of binned \(\xi_\ell(s)\) from cosmodesi/pycorr s_mu 2PCF estimators

RascalC.pycorr_utils.sample_cov_multipoles.sample_cov_multipoles_from_pycorr(xi_estimators: list[list[BaseTwoPointEstimator]], max_l: int, r_step: float | None = None, r_max: float = inf)

Produce a sample covariance of binned \(\xi_\ell(s)\) from cosmodesi/pycorr s_mu 2PCF estimators. Considers only even multipoles. Multiple tracers are supported.

Parameters

xi_estimatorslist of lists of pycorr.twopoint_estimator.BaseTwoPointEstimators

The first element must be the list of first tracer auto-correlation function estimators. The (optional) second element should be the list of cross-correlation function estimators between the 1st and the 2nd tracer. (Ordering of mock realizations must be the same, or the cross-covariance blocks will be wrong.) The (optional) third element should be the list of second tracer auto-correlation function estimators. This ordering can be extended (or altered) but it must be consistent.

max_linteger

Max (even) Legendre multipole index.

r_step: float or None

(Optional) If float, sets the uniform spacing of radial/separation bins. If None (default), the radial/separation binning is not changed.

r_max: float

(Optional) Sets the maximum radius/separation, any bins beyond that value are discarded. By default, the value is infinity, so no bins are discarded.

RascalC.pycorr_utils.sample_cov_multipoles.sample_cov_multipoles_from_pycorr_to_file(xi_estimators: list[list[BaseTwoPointEstimator]], outfile_name: str, max_l: int, r_step: float | None = None, r_max: float = inf)

Produce a sample covariance of binned \(\xi_\ell(s)\) from cosmodesi/pycorr s_mu 2PCF estimators and write the matrix to a text file. Considers only even multipoles. Multiple tracers are supported.

Parameters are analogous to sample_cov_multipoles_from_pycorr() except

outfile_namestring (filename)

The name for the output text file.

RascalC.pycorr_utils.sample_cov_multipoles.sample_cov_multipoles_from_pycorr_files(infile_names: list[list[str]], outfile_name: str, max_l: int, r_step: float | None = None, r_max: float = inf)

Produce a sample covariance of binned \(\xi_\ell(s)\) from cosmodesi/pycorr s_mu .npy files and write the matrix to a text file. Considers only even multipoles. Multiple tracers are supported.

Parameters

infile_nameslist of lists of strings (filenames)

The first element must be the list of first tracer auto-correlation function estimator filenames. The (optional) second element should be the list of cross-correlation function estimator filenames between the 1st and the 2nd tracer. (Ordering of mock realizations must be the same, or the cross-covariance blocks will be wrong.) The (optional) third element should be the list of second tracer auto-correlation function estimator filenames. This ordering can be extended (or altered) but it must be consistent.

outfile_namestring

The name for the output text file.

max_linteger

Max (even) Legendre multipole index.

r_step: float or None

(Optional) If float, sets the uniform spacing of radial/separation bins. If None (default), the radial/separation binning is not changed.

r_max: float

(Optional) Sets the maximum radius/separation, any bins beyond that value are discarded. By default, the value is infinity, so no bins are discarded.