Window Convolution (`winconv`)#

Added in version 0.6.0.

Caution

The winconv module is currently experimental. Its behaviour has not been fully tested and may change in the future.

Perform window convolution of two- and three-point statistics.

`Multipole`(multipole)	Multipole indexing representation.
`calc_threept_winconv_coeff`(multipole, ...[, ...])	Calculate the window convolution coefficient for a specific window convolution term.
`WinConvTerm`(multipole_Q, multipole_Z, coeff)	Window convolution term as a tuple of three multiplicative factors including the coefficient, window function multipole and unwindowed correlation function (CF) multipole.
`WinConvFormulae`(formulae)	Window convolution formulae.
`ThreePointWindow`(paired_sampts, flat_multipoles)	Three-point window function in configuration space.
`calc_threept_ic`(window_sampts, ...[, ...])	Compute three-point clustering statistic integral constraint.
`WinConvBase`(formulae, window_sampts, ...[, ...])	Generic window convolution for correlation functions (CF).
`TwoPCFWinConv`(formulae, window_sampts, ...)	Window convolution of two-point correlation function (2PCF).
`PowspecWinConv`(formulae, window_sampts, ...)	Window convolution of power spectrum.
`ThreePCFWinConv`(formulae, window_sampts, ...)	Window convolution of three-point correlation function (3PCF).
`BispecWinConv`(formulae, window_sampts, ...)	Window convolution of bispectrum.

triumvirate.winconv.SPLINE = 3#: Default spline order for interpolation (see scipy.interpolate).

triumvirate.winconv.NAMED_FORMULAE = {'sugiyama+18': {'000': [('000', '000', 1), ('000', 'ic', -1), ('110', '110', Fraction(1, 3))], '110': [('000', '110', 1), ('110', '000', 1), ('110', 'ic', -1)], '112': [('000', '112', 1), ('112', '000', 1), ('112', 'ic', -1), ('022', '110', Fraction(2, 5)), ('202', '110', Fraction(2, 5)), ('110', '022', Fraction(2, 5)), ('110', '202', Fraction(2, 5))], '202': [('000', '202', 1), ('202', '000', 1), ('202', 'ic', -1), ('110', '112', Fraction(1, 3)), ('112', '110', Fraction(1, 3))]}, 'wilson+16': {0: [(0, 0, 1), (2, 2, Fraction(1, 5)), (4, 4, Fraction(1, 9))], 2: [(2, 0, 1), (0, 2, 1), (2, 2, Fraction(2, 7)), (4, 2, Fraction(2, 7)), (2, 4, Fraction(2, 7)), (4, 4, Fraction(100, 693)), (6, 4, Fraction(25, 143))], 4: [(4, 0, 1), (2, 2, Fraction(18, 35)), (4, 2, Fraction(20, 77)), (6, 2, Fraction(45, 143)), (0, 4, 1), (2, 4, Fraction(20, 77)), (4, 4, Fraction(162, 1001)), (6, 4, Fraction(20, 143)), (8, 4, Fraction(490, 2431))]}}#

Named formulae for window convolution.

This is a dict where each key corresponds to a named formula below—

'wilson+16' (for plane-parallel two-point statistics): Wilson et al., 2016. MNRAS 464(3), 3121 [arXiv:1511.07799];
'sugiyama+18' (for plane-parallel three-point statistics): Sugiyama et al., 2018. MNRAS 484(1), 364 [arXiv:1803.02132].

The value for each key is itself a dict that is used to construct an instance of WinConvFormulae.

exception triumvirate.winconv.ConvolutionRangeWarning[source]#

Bases: UserWarning

Warning issued when the convolution range is not fully covered by the sample points.

class triumvirate.winconv.Multipole(multipole)[source]#

Bases: object

Multipole indexing representation.

Parameters:

multipole (MultipoleLike) – Multipole representation.

Variables:

index (tuple of int) – Multipole index or indices (composite index).
abstr (str) – Abbreviated/undelimited string representation, e.g. ‘000’ for (0, 0, 0).

Examples

The following variables all correspond to the multipole (0, 0, 0):

>>> multipole_a = Multipole('000')
>>> multipole_b = Multipole((0, 0, 0))
>>> multipole_c = Multipole([0, 0, '0'])
>>> assert multipole_a == multipole_b == multipole_c
>>> print(multipole_a)
0,0,0
>>> print(multipole_a.abstr)
000

Caution

When using a string to represent the multipole, it is assumed that each multipole degree is a single digit unless the string is delimited by commas. If any of the multipole degrees is more than one digit, then the undelimited string representation will not be unique.

triumvirate.winconv.DegreeType#

Degree type.

This represents a spherical degree, which can be an integer or a string.

Examples

The following variables all have this type:

>>> degree_a = 0
>>> degree_b = '0'

alias of int | str

triumvirate.winconv.MultipoleLike#

Multipole-like type.

This represents a multipole index or indices.

Examples

The following variables all have this type:

>>> multipole_a = Multipole((0,))
>>> multipole_b = (0, '0')
>>> multipole_c = '0'
>>> multipole_d = 0

alias of Multipole | tuple[int | str, …] | str | int

triumvirate.winconv.Multipole3PtLike#

Three-point multipole-like type.

This represents three-point multipole indices and is a subtype of MultipoleLike.

alias of Multipole | tuple[int | str, …] | str

triumvirate.winconv.CoeffType#

Coefficient type.

This represents a numerical coefficient (for a window convolution term).

Examples

The following variables all have this type:

>>> coeff_a = 1.
>>> coeff_b = 1
>>> coeff_c = Fraction(1, 3)
>>> coeff_d = '1/3'
>>> coeff_e = sympify('1/3')

alias of float | int | Fraction | str | Expr

triumvirate.winconv.calc_threept_winconv_coeff(multipole, multipole_Q, multipole_Z, symb=False)[source]#

Calculate the window convolution coefficient for a specific window convolution term.

Parameters:

multipole (Multipole3PtLike) – Windowed multipole indices.
multipole_Q (Multipole3PtLike) – Window function multipole indices.
multipole_Z (Multipole3PtLike) – Unwindowed correlation function multipole indices.
symb (bool, optional) – If True (default is False), return the coefficient as a symbolic expression.

Returns:

Window convolution coefficient. When multipole_Z is ‘ic’, return -1 if multipole and multipole_Q are the same, otherwise 0.

Return type:

float or sympy.core.expr.Expr

class triumvirate.winconv.WinConvTerm(multipole_Q, multipole_Z, coeff)[source]#

Bases: object

Window convolution term as a tuple of three multiplicative factors including the coefficient, window function multipole and unwindowed correlation function (CF) multipole.

Parameters:

multipole_Q (MultipoleLike) – Window function multipole index/indices.
multipole_Z (MultipoleLike) – Unwindowed-CF multipole index/indices.
coeff (CoeffType) – Numerical coefficient for the convolution term.

Variables:

coeff (CoeffType) – Numerical coefficient for the convolution term.
multipole_Q (Multipole) – Window function multipole index/indices.
multipole_Z (Multipole) – Unwindowed CF multipole index/indices.
index_Q (tuple of int) – Window function multipole index/indices as a tuple.
index_Z (tuple of int) – Unwindowed CF multipole index/indices as a tuple.

Examples

The following variables all correspond to the term \(- 1 \cdot Q_{000} \zeta_{\mathrm{ic}}\):

>>> term_a = WinConvTerm((0, 0, 0), 'ic', -1)
>>> term_b = WinConvTerm('000', 'ic', Fraction(-1))
>>> assert term_a == term_b
>>> print(term_a)
-1;0,0,0;ic

get_latex_str(symbol='\\zeta')[source]#

Get the LaTeX string representing the window convolution formula for a specific windowed CF multipole.

Parameters:: symbol (str, optional) – Symbol for the unwindowed CF (default is r"\zeta").
Returns:: LaTeX string representing the window convolution formula (without the maths-mode delimiters).
Return type:: str

triumvirate.winconv.WinConvTermLike#

Window convolution term–like type.

This represents a window convolution term.

Alias of WinConvTerm | tuple[MultipoleLike, MultipoleLike, CoeffType].

Examples

The following variables all have this type:

>>> term_a = WinConvTerm((0, 0, 0), 'ic', -1)
>>> term_b = ('000', 'ic', Fraction(-1))

alias of WinConvTerm | tuple[Multipole | tuple[int | str, …] | str | int, Multipole | tuple[int | str, …] | str | int, float | int | Fraction | str | Expr]

triumvirate.winconv.FormulaeDictType#

Formula dictionary type.

This represents a dictionary of window convolution formulae.

Alias of dict[MultipoleLike, Sequence[WinConvTermLike]].

Examples

The following variables all have this type:

>>> formulae_dict = {
...     '000': [
...         ('000', '000', 1),
...         WinConvTerm((0, 0, 0), 'ic', -1),
...     ],
... }

alias of dict[Multipole | tuple[int | str, …] | str | int, Sequence[WinConvTerm | tuple[Multipole | tuple[int | str, …] | str | int, Multipole | tuple[int | str, …] | str | int, float | int | Fraction | str | Expr]]]

class triumvirate.winconv.WinConvFormulae(formulae)[source]#

Bases: object

Window convolution formulae.

The full set of formulae are encoded as a dictionary, where each key corresponds to a windowed correlation function (CF) multipole, and each value is a sequence of tuples each corresponding to a window convolution term.

Parameters:

formulae (FormulaeDictType) – Window convolution formulae.

Variables:

formulae (dict of {Multipole: list of WinConvTerm}) – Window convolution formulae.
multipoles (list of Multipole) – Windowed CF multipole index/indices.
multipoles_Q (list of Multipole) – Required window function multipole index/indices.
multipoles_Z (list of Multipole or str) – Required unwindowed CF multipole index/indices including pseudo-index such as ‘ic’ for the integral constraint.

Examples

The following formulae corresponds to a single formula for the three-point CF monopole (0, 0, 0) consisting of three terms, namely \(Q_{000} \zeta_{000} - Q_{000} \zeta_{\mathrm{ic}} + \frac{1}{3} Q_{110} \zeta_{110}\):

>>> formulae_dict = {
...     '000': [
...         ('000', '000', 1),
...         ('000', 'ic', -1),
...         ('110', '110', '1/3'),
...     ],
... }
>>> formulae = WinConvFormulae(formulae_dict)

It encodes the formula for the windowed (0, 0, 0) monopole only:

>>> print(formulae.multipoles)
[Multipole((0, 0, 0))]

The window function multipoles required are:

>>> print(formulae.multipoles_Q)
[Multipole((0, 0, 0)), Multipole((1, 1, 0))]

The unwindowed three-point CF multipoles required are:

>>> print(formulae.multipoles_Z)
[Multipole((0, 0, 0)), Multipole((1, 1, 0)), 'ic']

The formular can be printed as a LaTeX string (without the maths-mode delimiters):

>>> print(formulae.get_latex_expr('000'))
Q_\mathrm{000} \zeta_\mathrm{000} - Q_\mathrm{000} \zeta_\mathrm{ic} + \frac{1}{3} Q_\mathrm{110} \zeta_\mathrm{110}

__getitem__(multipole)[source]#

Get the formula for a specific windowed CF multipole.

Parameters:: multipole (MultipoleLike) – Windowed CF multipole.
Returns:: List of window convolution terms for multipole.
Return type:: list of WinConvTerm

get_latex_expr(multipole, symbol='\\zeta')[source]#

Get the LaTeX string representing the window convolution formula for a specific windowed CF multipole.

Parameters:

multipole (str or int or tuple or Multipole) – Windowed CF multipole.
symbol (str, optional) – Symbol for the unwindowed CF (default is r"\zeta").

Returns:

LaTeX string representing the window convolution formula (without the maths-mode delimiters).

Return type:

str

class triumvirate.winconv.ThreePointWindow(paired_sampts, flat_multipoles, alpha_contrast=1.0, make_loglin=True)[source]#

Bases: object

Three-point window function in configuration space.

By construction, the window function is discretely sampled as a symmetric matrix where the upper triangular part is stored as a flattened array in row-major order, and each matrix element corresponds to a pair of separation sample points.

Parameters:

paired_sampts (2-d array of float or dict of {Multipole3PtLike: 2-d array of float}) – Paired separation window function sample points, i.e. each row is \((r_1, r_2)\) where \(r_1\) and \(r_2\) are the separation sample points for the first and second dimensions.
flat_multipoles (dict of {Multipole3PtLike: 1-d array of float}) – Flattened window function multipole samples (each key is a multipole) evaluated at paired_sampts.
alpha_contrast (float, optional) – Alpha contrast factor (default is 1.) for normalising the higher number density of the random catalogue, e.g. 0.1 for a random catalogue with 10 times the number density of the data catalogue. The square of this factor is applied to the amplitude of the window function.
make_loglin (bool or int, optional) – Whether to resample the window function multipole samples logarithmically if they are not already (default is True). If an integer, it is the number of points to resample to.

Variables:

multipoles (list of Multipole) – Window function multipoles.
r (dict of {Multipole: 1-d array of float}) – Window function separation sample points.
Q (dict of {Multipole: 2-d array of float}) – Window function multipole samples (each key is a multipole).
Q_diag (dict of {Multipole: 1-d array of float}) – Diagonal of the window function multipole samples (each key is a multipole).
sources (list of str) – Sources of the window function multipole samples as either ‘array’ or the file path.

Raises:

ValueError – If paired_sampts is not a 2-d array.
ValueError – If paired_sampts and flat_multipoles have different lengths.
ValueError – If paired_sampts and flat_multipoles do not correspond to an upper triangular or square matrix.

Attention

All window function multipole samples are assumed to be evaluated at the same separation sample points.

classmethod load_from_textfiles(filepaths, subtract_shotnoise=True, usecols=(1, 4, 6, 8), alpha_contrast=1.0, make_loglin=True)[source]#

Load window function from plain-text files as saved by compute_3pcf_window() with form='full'.

Parameters:

filepaths (dict of {Multipole3PtLike: str}) – Window function file paths (values) for each multipole (key).
subtract_shotnoise (bool, optional) – Whether to subtract the shot-noise contribution from the window function (default is True).
usecols (sequence of int, optional) – Zero-indexed columns to read from the file (default is (1, 4, 6, 8)). If subtract_shotnoise is True, must be of length 4 and correspond to the effective separation sample points (two columns), and the raw window function and shot-noise (two columns); otherwise, must be of length 3 and correspond to the effective separation sample points (two columns) and the raw window function (one column).
alpha_contrast (float, optional) – Alpha contrast factor (default is 1.) for normalising the higher number density of the random catalogue, e.g. 0.1 for a random catalogue with 10 times the number density of the data catalogue.
make_loglin (bool, optional) – Whether to resample the window function multipole samples logarithmically if they are not already (default is True).

Returns:

Three-point window function.

Return type:

ThreePointWindow

Attention

The effective separation sample points are assumed to be the same for all window function files.

classmethod load_from_dict(dict_obj)[source]#

Load window function from a dictionary.

Parameters:: dict_obj (dict of {str: dict or 1-d array of float}) – Dictionary of 2-d window function multipoles (key ‘Q’) and sample points (key ‘r’), where the multipoles are themselves a single dictionary with each key corresponding to a multipole.
Returns:: Three-point window function.
Return type:: ThreePointWindow

classmethod load_from_file(filepath)[source]#

Load window function multipoles from a compressed NumPy file as saved by save_to_file().

Parameters:: filepath (str) – File path to load the window function multipoles.
Returns:: Three-point window function.
Return type:: ThreePointWindow

save_to_file(filepath)[source]#

Save window function to a compressed NumPy file.

Parameters:: filepath (str) – File path to save the window function multipoles.

subselect(rrange=None, idxrange=None, inplace=False)[source]#

Subselect samples based on a range of separation sample points.

Parameters:

rrange (tuple of float or dict of {Multipole3PtLike: tuple of float}, optional) – Range of separation sample points (default is None), e.g. (None, 300.).
idxrange (tuple of int or None, optional) – Range of separation sample point indices (default is None), e.g. (None, -1), equivalent to slice(None, -1).
inplace (bool, optional) – If False (default), return a new window function object; otherwise, modify the window function in place.

Returns:

If returned (default is None), three-point window function for the subselected range of separation sample points.

Return type:

ThreePointWindow or None

resample(spacing='lglin', size=None, spline=3)[source]#

Resample window function multipole samples.

Parameters:

spacing ({‘lglin’, ‘lin’}, optional) – Spacing type for the resampled separation sample points either ‘lglin’ (default) (logarithmic-linear) or ‘lin’ (linear).
size ((tuple of) int, optional) – Number(s) of points to resample to (default is None).
spline (int, optional) – Spline order for interpolation (default is SPLINE). See scipy.interpolate for more details.

triumvirate.winconv.calc_threept_ic(window_sampts, window_multipoles, r, zeta, r_common=None, approx=False, spline=3)[source]#

Compute three-point clustering statistic integral constraint.

Parameters:

window_sampts (1-d array of float or dict of {Multipole3PtLike: 1-d array of float}) – Window function multipole separation sample points, either the same for all multipoles or a dictionary of sample points (value) for each multipole (key).
window_multipoles (dict of {Multipole3PtLike: 2-d array of float}) – Window function multipole samples (each key is a multipole). Must contain the (0, 0, 0) monopole.
r (1-d array of float or dict of {Multipole3PtLike: 1-d array of float}) – Separation sample points for the input 3PCF multipoles, either the same for all multipoles or a dictionary of sample points (value) for each multipole (key).
zeta (dict of {Multipole3PtLike: 2-d array of float}) – Input 3PCF multipole samples (each key is a multipole) at sample points r_in.
r_common (1-d array of float, optional) – Common separation sample points. If None (default), it is the same as r_in.
approx (bool, optional) – If True (default is False), include only the leading-order term with the (0, 0, 0) multipole as an approximation.
spline (int, optional) – Spline order for interpolation (default is SPLINE). See scipy.interpolate for more details.

Returns:

Integral constraint.

Return type:

float

class triumvirate.winconv.WinConvBase(formulae, window_sampts, window_multipoles, comm=None, comm_root=0)[source]#

Bases: object

Generic window convolution for correlation functions (CF).

Parameters:

formulae (str, FormulaeDictType or dict of {Multipole: list of WinConvTerm}) – Window convolution formulae (see WinConvFormulae). If a string, it is assumed to be a named formula (see NAMED_FORMULAE).
window_sampts (1-d array of float or dict of {MultipoleLike: 1-d array of float}) – Window function multipole separation sample points, either the same for all multipoles or a dictionary of sample points (value) for each multipole (key).
window_multipoles (dict of {MultipoleLike: array of float}) – Window function multipole samples (each key is a multipole).
comm (mpi4py.MPI.Comm, optional) – MPI communicator (default is None).
comm_root (int, optional) – Root process rank of the MPI communicator (default is 0). Ignored if comm is None.

Variables:

r_in (dict of {Multipole: 1-d array of float} or None) – Separation sample points for the input CF multipoles.
r_out (dict of {Multipole: 1-d array of float} or None) – Separation sample points for the output CF multipoles.
comm (mpi4py.MPI.Comm or None) – MPI communicator.
comm_root (int or None) – Root process rank of any MPI communicator.

initialise_sampts(r_in, r_out=None, enforce_coverage=False)[source]#

Initialise sample points r_in and r_out for the input and output CF multipoles.

Parameters:

r_in (1-d array of float or dict of {MultipoleLike: 1-d array of float} or 2-d array of float or dict of {MultipoleLike: 2-d array of float}) – Separation sample points for the input CF multipoles, either the same for all multipoles or a dictionary of sample points (value) for each multipole (key).
r_out (1-d array of float or dict of {MultipoleLike: 1-d array of float} or 2-d array of float or dict of {MultipoleLike: 2-d array of float}) – Separation sample points for the output CF multipoles, either the same for all multipoles or a dictionary of sample points (value) for each multipole (key). If None (default), it is set to r_in.
enforce_coverage (bool, optional) – If True (default is False) and r_out is not provided, enforce that the output CF separation sample points are fully covered by the separation sample points of the window function and input CF multipoles, and that they are logarithmically spaced.

class triumvirate.winconv.TwoPCFWinConv(formulae, window_sampts, window_multipoles, r_in, r_out=None, spline=3)[source]#

Bases: WinConvBase

Window convolution of two-point correlation function (2PCF).

Parameters:

formulae (str, FormulaeDictType or dict of {Multipole: list of WinConvTerm}) – Window convolution formulae (see WinConvFormulae). If a string, it is assumed to be a named formula (see NAMED_FORMULAE).
window_sampts (1-d array of float or dict of {MultipoleLike: 1-d array of float}) – Window function multipole separation sample points, either the same for all multipoles or a dictionary of sample points (value) for each multipole (key).
window_multipoles (dict of {MultipoleLike: 1-d array of float}) – Window function multipole samples (each key is a multipole).
r_in (1-d array of float or dict of {MultipoleLike: 1-d array of float}) – Separation sample points for the input 2PCF multipoles, either the same for all multipoles or a dictionary of sample points (value) for each multipole (key).
r_out (1-d array of float, optional) – Separation sample points for the output 2PCF multipoles. If None (default), it is set to r_in.
spline (int, optional) – Spline order for interpolation (default is SPLINE). See scipy.interpolate for more details.

Variables:

r_in (dict of {Multipole: 1-d array of float}) – Separation sample points for the input 2PCF multipoles.
r_out (dict of {Multipole: 1-d array of float}) – Separation sample points for the output 2PCF multipoles.
spline (int) – Spline order for interpolation (default is SPLINE).

Attention

Integral constraint is ignored.

Window Convolution (winconv)#

Window Convolution (`winconv`)#