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.