Three-Point Clustering Statistics (threept)#

Measure three-point clustering statistics from catalogues.

Local plane-parallel estimators#

compute_bispec(catalogue_data, catalogue_rand)

Compute bispectrum from survey-like data and random catalogues in the local plane-parallel approximation.

compute_3pcf(catalogue_data, catalogue_rand)

Compute three-point correlation function from survey-like data and random catalogues in the local plane-parallel approximation.

Global plane-parallel estimators#

compute_bispec_in_gpp_box(catalogue_data[, ...])

Compute bispectrum from a simulation-box catalogue in the global plane-parallel approximation.

compute_3pcf_in_gpp_box(catalogue_data[, ...])

Compute three-point correlation function from a simulation-box catalogue in the global plane-parallel approximation.

Window function estimator#

compute_3pcf_window(catalogue_rand[, ...])

Compute three-point correlation function window from a random catalogue.
triumvirate.threept.compute_bispec(catalogue_data, catalogue_rand, los_data=None, los_rand=None, degrees=None, binning=None, form=None, idx_bin=None, sampling_params=None, paramset=None, save=False, logger=None)[source]#

Compute bispectrum from survey-like data and random catalogues in the local plane-parallel approximation.

Parameters

  • catalogue_data (ParticleCatalogue) – Data-source catalogue.

  • catalogue_rand (ParticleCatalogue) – Random-source catalogue.

  • los_data ((N, 3) array of float, optional) – Specified lines of sight for the data-source catalogue. If None (default), this is automatically computed using compute_los().

  • los_rand ((N, 3) array of float, optional) – Specified lines of sight for the random-source catalogue. If None (default), this is automatically computed using compute_los().

  • degrees (tuple of (int, int, int) or str of length 3, optional) – Multipole degrees either as a tuple (‘ell1’, ‘ell2’, ‘ELL’) or as a string of length 3. If not None (default), this will override paramset['degrees'] entries. If a string, multipole degrees are assumed to be single-digit integers.

  • binning (Binning, optional) – Binning for the measurements. If None (default), this is constructed from paramset.

  • form ({‘diag’, ‘off-diag’, ‘row’, ‘full’}, optional) – Binning form of the measurements. If not None (default), this will override paramset['form'].

  • idx_bin (int, optional) – When binning form is ‘row’, this is the fixed bin index for the first coordinate dimension; when binning form is ‘off-diag’, this is the upper-triangular off-diagonal index; otherwise, this is ignored. If not None (default), this will override paramset['idx_bin'].

  • sampling_params (dict, optional) – Dictionary containing a subset of the following entries for sampling parameters—

    • ‘alignment’: {‘centre’, ‘pad’};

    • ‘boxsize’: sequence of [float, float, float];

    • ‘ngrid’: sequence of [int, int, int];

    • ‘assignment’: {‘ngp’, ‘cic’, ‘tsc’, ‘pcs’};

    • ‘interlace’: bool;

    and exactly one of the following only when ‘alignment’ is ‘pad’—

    • ‘boxpad’: float;

    • ‘gridpad’: float.

    If not None (default), this will override the corresponding entries in paramset.

  • paramset (ParameterSet, optional) – Full parameter set (default is None). This is used in lieu of degrees, binning, form, idx_bin or sampling_params.

  • save ({‘.txt’, ‘.npz’, False}, optional) – If not False (default), save the measurements as a ‘.txt’ file or in ‘.npz’ format. The save path is determined from paramset (if unset, a default file path in the current working directory is used).

  • logger (logging.Logger, optional) – Logger (default is None).

Returns

results – Measurement results as a dictionary with the following entries—

  • ‘k1_bin’, ‘k2_bin’: central wavenumber for each bin of the first and second wavenumbers;

  • ’k1_eff’, ‘k2_eff’: effective wavenumber for each bin of the first and second wavenumbers;

  • ’nmodes_1’, ‘nmodes_2’: number of wavevector modes in each bin of the first and second wavenumbers;

  • ’bk_raw’: bispectrum raw measurements including any specified normalisation and shot noise;

  • ’bk_shot’: bispectrum shot noise.

The effective wavenumber is here defined as the average wavenumber in each bin.

Return type

dict of {str: numpy.ndarray}

Examples

Specify multipole degrees (0, 0, 2) and bispectrum ‘row’ form with the first wavenumber fixed in the bin indexed 5. These override the corresponding parameters supplied by paramset.

>>> results = compute_bispec(
...     catalogue_data, catalogue_rand,
...     degrees=(0, 0, 2),
...     form='full',
...     idx_bin=5,
...     paramset=paramset
... )

See more analogous examples in compute_powspec().

triumvirate.threept.compute_3pcf(catalogue_data, catalogue_rand, los_data=None, los_rand=None, degrees=None, binning=None, form=None, idx_bin=None, sampling_params=None, paramset=None, save=False, logger=None)[source]#

Compute three-point correlation function from survey-like data and random catalogues in the local plane-parallel approximation.

Parameters

  • catalogue_data (ParticleCatalogue) – Data-source catalogue.

  • catalogue_rand (ParticleCatalogue) – Random-source catalogue.

  • los_data ((N, 3) array of float, optional) – Specified lines of sight for the data-source catalogue. If None (default), this is automatically computed using compute_los().

  • los_rand ((N, 3) array of float, optional) – Specified lines of sight for the random-source catalogue. If None (default), this is automatically computed using compute_los().

  • degrees (tuple of (int, int, int) or str of length 3, optional) – Multipole degrees either as a tuple (‘ell1’, ‘ell2’, ‘ELL’) or as a string of length 3. If not None (default), this will override paramset['degrees'] entries. If a string, multipole degrees are assumed to be single-digit integers.

  • binning (Binning, optional) – Binning for the measurements. If None (default), this is constructed from paramset.

  • form ({‘diag’, ‘off-diag’, ‘row’, ‘full’}, optional) – Binning form of the measurements. If not None (default), this will override paramset['form'].

  • idx_bin (int, optional) – When binning form is ‘row’, this is the fixed bin index for the first coordinate dimension; when binning form is ‘off-diag’, this is the upper-triangular off-diagonal index; otherwise, this is ignored. If not None (default), this will override paramset['idx_bin'].

  • sampling_params (dict, optional) – Dictionary containing a subset of the following entries for sampling parameters—

    • ‘alignment’: {‘centre’, ‘pad’};

    • ‘boxsize’: sequence of [float, float, float];

    • ‘ngrid’: sequence of [int, int, int];

    • ‘assignment’: {‘ngp’, ‘cic’, ‘tsc’, ‘pcs’};

    • ‘interlace’: bool;

    and exactly one of the following only when ‘alignment’ is ‘pad’—

    • ‘boxpad’: float;

    • ‘gridpad’: float.

    If not None (default), this will override the corresponding entries in paramset.

  • paramset (ParameterSet, optional) – Full parameter set (default is None). This is used in lieu of degrees, binning, form, idx_bin or sampling_params.

  • save ({‘.txt’, ‘.npz’, False}, optional) – If not False (default), save the measurements as a ‘.txt’ file or in ‘.npz’ format. The save path is determined from paramset (if unset, a default file path in the current working directory is used).

  • logger (logging.Logger, optional) – Logger (default is None).

Returns

results – Measurement results as a dictionary with the following entries—

  • ‘r1_bin’, ‘r2_bin’: central separation for each bin of the first and second separations;

  • ’r1_eff’, ‘r2_eff’: effective separation for each bin of the first and second separations;

  • ’npairs_1’, ‘npairs_2’: number of separation pairs in each bin of the first and second separations;

  • ’zeta_raw’: three-point correlation function raw measurements including any specified normalisation and shot noise;

  • ’zeta_shot’: three-point correlation function shot noise.

The effective separation is here defined as the average separation in each bin.

Return type

dict of {str: numpy.ndarray}

Examples

See analogous examples in compute_bispec().

triumvirate.threept.compute_bispec_in_gpp_box(catalogue_data, degrees=None, binning=None, form=None, idx_bin=None, sampling_params=None, paramset=None, save=False, logger=None)[source]#

Compute bispectrum from a simulation-box catalogue in the global plane-parallel approximation.

Parameters

  • catalogue_data (ParticleCatalogue) – Data-source catalogue.

  • degrees (tuple of (int, int, int) or str of length 3, optional) – Multipole degrees either as a tuple (‘ell1’, ‘ell2’, ‘ELL’) or as a string of length 3. If not None (default), this will override paramset['degrees'] entries. If a string, multipole degrees are assumed to be single-digit integers.

  • binning (Binning, optional) – Binning for the measurements. If None (default), this is constructed from paramset.

  • form ({‘diag’, ‘off-diag’, ‘row’, ‘full’}, optional) – Binning form of the measurements. If not None (default), this will override paramset['form'].

  • idx_bin (int, optional) – When binning form is ‘row’, this is the fixed bin index for the first coordinate dimension; when binning form is ‘off-diag’, this is the upper-triangular off-diagonal index; otherwise, this is ignored. If not None (default), this will override paramset['idx_bin'].

  • sampling_params (dict, optional) – Dictionary containing a subset of the following entries for sampling parameters—

    • ‘alignment’: {‘centre’, ‘pad’};

    • ‘boxsize’: sequence of [float, float, float];

    • ‘ngrid’: sequence of [int, int, int];

    • ‘assignment’: {‘ngp’, ‘cic’, ‘tsc’, ‘pcs’};

    • ‘interlace’: bool;

    and exactly one of the following only when ‘alignment’ is ‘pad’—

    • ‘boxpad’: float;

    • ‘gridpad’: float.

    If not None (default), this will override the corresponding entries in paramset.

  • paramset (ParameterSet, optional) – Full parameter set (default is None). This is used in lieu of degrees, binning, form, idx_bin or sampling_params.

  • save ({‘.txt’, ‘.npz’, False}, optional) – If not False (default), save the measurements as a ‘.txt’ file or in ‘.npz’ format. The save path is determined from paramset (if unset, a default file path in the current working directory is used).

  • logger (logging.Logger, optional) – Logger (default is None).

Returns

results – Measurement results as a dictionary with the following entries—

  • ‘k1_bin’, ‘k2_bin’: central wavenumber for each bin of the first and second wavenumbers;

  • ’k1_eff’, ‘k2_eff’: effective wavenumber for each bin of the first and second wavenumbers;

  • ’nmodes_1’, ‘nmodes_2’: number of wavevector modes in each bin of the first and second wavenumbers;

  • ’bk_raw’: bispectrum raw measurements including any specified normalisation and shot noise;

  • ’bk_shot’: bispectrum shot noise.

The effective wavenumber is here defined as the average wavenumber in each bin.

Return type

dict of {str: numpy.ndarray}

Examples

See analogous examples in compute_bispec() (though without the line-of-sight arguments).

triumvirate.threept.compute_3pcf_in_gpp_box(catalogue_data, degrees=None, binning=None, form=None, idx_bin=None, sampling_params=None, paramset=None, save=False, logger=None)[source]#

Compute three-point correlation function from a simulation-box catalogue in the global plane-parallel approximation.

Parameters

  • catalogue_data (ParticleCatalogue) – Data-source catalogue.

  • degrees (tuple of (int, int, int) or str of length 3, optional) – Multipole degrees either as a tuple (‘ell1’, ‘ell2’, ‘ELL’) or as a string of length 3. If not None (default), this will override paramset['degrees'] entries. If a string, multipole degrees are assumed to be single-digit integers.

  • binning (Binning, optional) – Binning for the measurements. If None (default), this is constructed from paramset.

  • form ({‘diag’, ‘off-diag’, ‘row’, ‘full’}, optional) – Binning form of the measurements. If not None (default), this will override paramset['form'].

  • idx_bin (int, optional) – When binning form is ‘row’, this is the fixed bin index for the first coordinate dimension; when binning form is ‘off-diag’, this is the upper-triangular off-diagonal index; otherwise, this is ignored. If not None (default), this will override paramset['idx_bin'].

  • sampling_params (dict, optional) – Dictionary containing a subset of the following entries for sampling parameters—

    • ‘alignment’: {‘centre’, ‘pad’};

    • ‘boxsize’: sequence of [float, float, float];

    • ‘ngrid’: sequence of [int, int, int];

    • ‘assignment’: {‘ngp’, ‘cic’, ‘tsc’, ‘pcs’};

    • ‘interlace’: bool;

    and exactly one of the following only when ‘alignment’ is ‘pad’—

    • ‘boxpad’: float;

    • ‘gridpad’: float.

    If not None (default), this will override the corresponding entries in paramset.

  • paramset (ParameterSet, optional) – Full parameter set (default is None). This is used in lieu of degree, binning, form, idx_bin or sampling_params.

  • save ({‘.txt’, ‘.npz’, False}, optional) – If not False (default), save the measurements as a ‘.txt’ file or in ‘.npz’ format. The save path is determined from paramset (if unset, a default file path in the current working directory is used).

  • logger (logging.Logger, optional) – Logger (default is None).

Returns

results – Measurement results as a dictionary with the following entries—

  • ‘r1_bin’, ‘r2_bin’: central separation for each bin of the first and second separations;

  • ’r1_eff’, ‘r2_eff’: effective separation for each bin of the first and second separations;

  • ’npairs_1’, ‘npairs_2’: number of separation pairs in each bin of the first and second separations;

  • ’zeta_raw’: three-point correlation function raw measurements including any specified normalisation and shot noise;

  • ’zeta_shot’: three-point correlation function shot noise.

The effective separation is here defined as the average separation in each bin.

Return type

dict of {str: numpy.ndarray}

Examples

See analogous examples in compute_bispec() (though without the line-of-sight arguments).

triumvirate.threept.compute_3pcf_window(catalogue_rand, los_rand=None, degrees=None, wa_orders=None, binning=None, form=None, idx_bin=None, sampling_params=None, paramset=None, save=False, logger=None)[source]#

Compute three-point correlation function window from a random catalogue.

Parameters

  • catalogue_rand (ParticleCatalogue) – Random-source catalogue.

  • los_rand ((N, 3) array of float, optional) – Specified lines of sight for the random-source catalogue. If None (default), this is automatically computed using compute_los().

  • degrees (tuple of (int, int, int) or str of length 3, optional) – Multipole degrees either as a tuple (‘ell1’, ‘ell2’, ‘ELL’) or as a string of length 3. If not None (default), this will override paramset['degrees'] entries. If a string, multipole degrees are assumed to be single-digit integers.

  • wa_orders (tuple of (int, int) or str of length 2, optional) – Wide-angle correction orders either as a tuple (‘i_wa’, ‘j_wa’) or as a string of length 2. If not None (default), this will override paramset['wa_orders'] entries. If a string, multipole degrees are assumed to be single-digit integers.

  • binning (Binning, optional) – Binning for the measurements. If None (default), this is constructed from paramset.

  • form ({‘diag’, ‘off-diag’, ‘row’, ‘full’}, optional) – Binning form of the measurements. If not None (default), this will override paramset['form'].

  • idx_bin (int, optional) – When binning form is ‘row’, this is the fixed bin index for the first coordinate dimension; when binning form is ‘off-diag’, this is the upper-triangular off-diagonal index; otherwise, this is ignored. If not None (default), this will override paramset['idx_bin'].

  • sampling_params (dict, optional) – Dictionary containing a subset of the following entries for sampling parameters—

    • ‘alignment’: {‘centre’, ‘pad’};

    • ‘boxsize’: sequence of [float, float, float];

    • ‘ngrid’: sequence of [int, int, int];

    • ‘assignment’: {‘ngp’, ‘cic’, ‘tsc’, ‘pcs’};

    • ‘interlace’: bool;

    and exactly one of the following only when ‘alignment’ is ‘pad’—

    • ‘boxpad’: float;

    • ‘gridpad’: float.

    If not None (default), this will override the corresponding entries in paramset.

  • paramset (ParameterSet, optional) – Full parameter set (default is None). This is used in lieu of degrees, binning, form, idx_bin or sampling_params.

  • save ({‘.txt’, ‘.npz’, False}, optional) – If not False (default), save the measurements as a ‘.txt’ file or in ‘.npz’ format. The save path is determined from paramset (if unset, a default file path in the current working directory is used).

  • logger (logging.Logger, optional) – Logger (default is None).

Returns

results – Measurement results as a dictionary with the following entries—

  • ‘r1_bin’, ‘r2_bin’: central separation for each bin of the first and second separations;

  • ’r1_eff’, ‘r2_eff’: effective separation for each bin of the first and second separations;

  • ’npairs_1’, ‘npairs_2’: number of separation pairs in each bin of the first and second separations;

  • ’zeta_raw’: three-point correlation function raw measurements including any specified normalisation and shot noise;

  • ’zeta_shot’: three-point correlation function shot noise.

The effective separation is here defined as the average separation in each bin.

Return type

dict of {str: numpy.ndarray}

Examples

See analogous examples in compute_bispec().