pymaster.workspaces module

class pymaster.workspaces.NmtWorkspace(fl1=None, fl2=None, bins=None, is_teb=False, l_toeplitz=-1, l_exact=-1, dl_band=-1, fname=None, read_unbinned_MCM=True, normalization='MASTER')[source]

Bases: object

NmtWorkspace objects are used to compute and store the mode-coupling matrix associated with an incomplete sky coverage, and used in the MASTER algorithm. NmtWorkspace objects can be initialised from a pair of NmtField objects and an NmtBin object, containing information about the masks involved and the \(\ell\) binning scheme, or read from a file where the mode-coupling matrix was stored.

We recommend using the class methods from_fields() and from_file() to create new NmtWorkspace objects, rather than using the main constructor.

Parameters:

  • fl1 (NmtField) – First field being correlated.

  • fl2 (NmtField) – Second field being correlated.

  • bins (NmtBin) – Binning scheme.

  • is_teb (bool) – If True, all mode-coupling matrices (0-0,0-s,s-s) will be computed at the same time. In this case, fl1 must be a spin-0 field and fl2 must be spin-s.

  • l_toeplitz (int) – If a positive number, the Toeplitz approximation described in Louis et al. 2020 will be used. In that case, this quantity corresponds to \(\ell_{\rm toeplitz}\) in Fig. 3 of that paper.

  • l_exact (int) – If l_toeplitz>0, it corresponds to \(\ell_{\rm exact}\) in Fig. 3 of the paper. Ignored if l_toeplitz<=0.

  • dl_band (int) – If l_toeplitz>0, this quantity corresponds to \(\Delta \ell_{\rm band}\) in Fig. 3 of the paper. Ignored if l_toeplitz<=0.

  • fname (str) – Input file name. If not None, this workspace will be initialised from file, and the values of fl1, fl2, and bin will be ignored.

  • read_unbinned_MCM (bool) – If False, the unbinned mode-coupling matrix will not be read. This can save significant IO time.

  • normalization (str) – Normalization convention to use for the bandpower window functions. Two options supported: ‘MASTER’ (default) corresponds to the standard inversion of the binned mode-coupling matrix. ‘FKP’ simply divides by the mean of the mask product, forcing a unit response to an input white spectrum.

classmethod from_fields(fl1, fl2, bins, is_teb=False, l_toeplitz=-1, l_exact=-1, dl_band=-1, normalization='MASTER')[source]

Creates an NmtWorkspace object containing the mode-coupling matrix associated with the cross-power spectrum of two NmtField s and an NmtBin binning scheme. Note that the mode-coupling matrix will only contain \(\ell\) s up to the maximum multipole included in the bandpowers, which should match the \(\ell_{\rm max}\) of the fields as well.

Parameters:

  • fl1 (NmtField) – First field to correlate.

  • fl2 (NmtField) – Second field to correlate.

  • bins (NmtBin) – Binning scheme.

  • is_teb (bool) – If True, all mode-coupling matrices (0-0,0-s,s-s) will be computed at the same time. In this case, fl1 must be a spin-0 field and fl2 must be spin-s.

  • l_toeplitz (int) –

    If a positive number, the Toeplitz approximation described in Louis et al. 2020 will be used. In that case, this quantity corresponds to \(\ell_{\rm toeplitz}\) in Fig. 3 of that paper.

  • l_exact (int) – If l_toeplitz>0, it corresponds to \(\ell_{\rm exact}\) in Fig. 3 of the paper. Ignored if l_toeplitz<=0.

  • dl_band (int) – If l_toeplitz>0, this quantity corresponds to \(\Delta \ell_{\rm band}\) in Fig. 3 of the paper. Ignored if l_toeplitz<=0.

  • normalization (str) – Normalization convention to use for the bandpower window functions. Two options supported: ‘MASTER’ (default) corresponds to the standard inversion of the binned mode-coupling matrix. ‘FKP’ simply divides by the mean of the mask product, forcing a unit response to an input white spectrum.

classmethod from_file(fname, read_unbinned_MCM=True)[source]

Creates an NmtWorkspace object from a mode-coupling matrix stored in a FITS file. See write_to().

Parameters:

  • fname (str) – Input file name.

  • read_unbinned_MCM (bool) – If False, the unbinned mode-coupling matrix will not be read. This can save significant IO time.

check_unbinned()[source]

Raises an error if this workspace does not contain the unbinned mode-coupling matrix.

read_from(fname, read_unbinned_MCM=True)[source]

Reads the contents of an NmtWorkspace object from a FITS file.

Parameters:

  • fname (str) – Input file name.

  • read_unbinned_MCM (bool) – If False, the unbinned mode-coupling matrix will not be read. This can save significant IO time.

update_beams(beam1, beam2)[source]

Update beams associated with this mode-coupling matrix. This is significantly faster than recomputing the matrix from scratch.

Parameters:

  • beam1 (array) – First beam, in the form of a 1D array with the beam sampled at all integer multipoles up to the maximum \(\ell\) with which this workspace was initialised.

  • beam2 (array) – Second beam.

update_bins(bins)[source]

Update binning associated with this mode-coupling matrix. This is significantly faster than recomputing the matrix from scratch.

Parameters:

bins (NmtBin) – New binning scheme.

compute_coupling_matrix(fl1, fl2, bins, is_teb=False, l_toeplitz=-1, l_exact=-1, dl_band=-1, normalization='MASTER')[source]

Computes the mode-coupling matrix associated with the cross-power spectrum of two NmtField s and an NmtBin binning scheme. Note that the mode-coupling matrix will only contain \(\ell\) s up to the maximum multipole included in the bandpowers, which should match the \(\ell_{\rm max}\) of the fields as well.

Parameters:

  • fl1 (NmtField) – First field to correlate.

  • fl2 (NmtField) – Second field to correlate.

  • bins (NmtBin) – Binning scheme.

  • is_teb (bool) – If True, all mode-coupling matrices (0-0,0-s,s-s) will be computed at the same time. In this case, fl1 must be a spin-0 field and fl2 must be spin-s.

  • l_toeplitz (int) –

    If a positive number, the Toeplitz approximation described in Louis et al. 2020 will be used. In that case, this quantity corresponds to \(\ell_{\rm toeplitz}\) in Fig. 3 of that paper.

  • l_exact (int) – If l_toeplitz>0, it corresponds to \(\ell_{\rm exact}\) in Fig. 3 of the paper. Ignored if l_toeplitz<=0.

  • dl_band (int) – If l_toeplitz>0, this quantity corresponds to \(\Delta \ell_{\rm band}\) in Fig. 3 of the paper. Ignored if l_toeplitz<=0.

  • normalization (str) – Normalization convention to use for the bandpower window functions. Two options supported: ‘MASTER’ (default) corresponds to the standard inversion of the binned mode-coupling matrix. ‘FKP’ simply divides by the mean of the mask product, forcing a unit response to an input white spectrum.

write_to(fname)[source]

Writes the contents of an NmtWorkspace object to a FITS file.

Parameters:

fname (str) – Output file name

get_coupling_matrix()[source]

Returns the currently stored mode-coupling matrix.

Returns:

Mode-coupling matrix. The matrix will have shape (nrows,nrows), with nrows = n_cls * n_ells, where n_cls is the number of power spectra (1, 2 or 4 for spin 0-0, spin 0-2 and spin 2-2 correlations), and n_ells = lmax + 1, and lmax is the maximum multipole associated with this workspace. The assumed ordering of power spectra is such that the L-th element of the i-th power spectrum be stored with index L * n_cls + i.

Return type:

(array)

update_coupling_matrix(new_matrix)[source]

Updates the stored mode-coupling matrix. The new matrix (new_matrix) must have shape (nrows,nrows). See docstring of get_coupling_matrix() for an explanation of the size and ordering of this matrix.

Parameters:

new_matrix (array) – Matrix that will replace the mode-coupling matrix.

couple_cell(cl_in)[source]

Convolves a set of input power spectra with a coupling matrix (see Eq. 9 of the NaMaster paper).

Parameters:

cl_in (array) – Set of input power spectra. The number of power spectra must correspond to the spins of the two fields that this NmtWorkspace object was initialized with (i.e. 1 for two spin-0 fields, 2 for one spin-0 field and one spin-s field, and 4 for two spin-s fields).

Returns:

Mode-coupled power spectra.

Return type:

(array)

decouple_cell(cl_in, cl_bias=None, cl_noise=None)[source]

Decouples a set of pseudo-\(C_\ell\) power spectra into a set of bandpowers by inverting the binned coupling matrix (se Eq. 16 of the NaMaster paper).

Parameters:

  • cl_in (array) – Set of input power spectra. The number of power spectra must correspond to the spins of the two fields that this NmtWorkspace object was initialized with (i.e. 1 for two spin-0 fields, 2 for one spin-0 field and one spin-s field, 4 for two spin-s fields, and 7 if this NmtWorkspace was created using is_teb=True).

  • cl_bias (array) – Bias to the power spectrum associated with contaminant residuals (optional). This can be computed through deprojection_bias().

  • cl_noise (array) – Noise bias (i.e. angular pseudo-\(C_\ell\) of masked noise realizations).

Returns:

Set of decoupled bandpowers.

Return type:

(array)

get_bandpower_windows()[source]

Get bandpower window functions. Convolve the theory power spectra with these as an alternative to the combination of function calls w.decouple_cell(w.couple_cell(cls_theory)). See Eqs. 18 and 19 of the NaMaster paper.

As an example consider the power spectrum of two spin-2 fields. In this case, the estimated bandpowers would have shape [4, n_bpw], where n_bpw is the number of bandpowers. The unbinned power spectra would have shape [4, lmax+1], where lmax is the maximum multipole under study. The bandpower window functions would then have shape [4, n_bpw, 4, lmax+1] and, for example, the window function at indices [0, b1, 3, ell2] quantifies the amount of \(BB\) power at \(\ell=\) ell2 that is leaked into the b1-th \(EE\) bandpower.

Returns:

Bandpower windows with shape (n_cls, n_bpws, n_cls, lmax+1).

Return type:

(array)

class pymaster.workspaces.NmtWorkspaceFlat[source]

Bases: object

NmtWorkspaceFlat objects are used to compute and store the mode-coupling matrix associated with an incomplete sky coverage, and used in the flat-sky version of the MASTER algorithm. When initialized, this object is practically empty. The information describing the coupling matrix must be computed or read from a file afterwards.

read_from(fname)[source]

Reads the contents of an NmtWorkspaceFlat object from a FITS file.

Parameters:

fname (str) – Input file name.

compute_coupling_matrix(fl1, fl2, bins, ell_cut_x=[1.0, -1.0], ell_cut_y=[1.0, -1.0], is_teb=False)[source]

Computes mode-coupling matrix associated with the cross-power spectrum of two NmtFieldFlat s and an NmtBinFlat binning scheme.

Parameters:

  • fl1 (NmtFieldFlat) – First field to correlate.

  • fl2 (NmtFieldFlat) – Second field to correlate.

  • bin (NmtBinFlat) – Binning scheme.

  • ell_cut_x (array) – Sequence of two elements determining the range of \(l_x\) to remove from the calculation. No Fourier modes removed by default.

  • ell_cut_y (array) – Sequence of two elements determining the range of \(l_y\) to remove from the calculation. No Fourier modes removed by default.

  • is_teb (bool) – If True, all mode-coupling matrices (0-0,0-s,s-s) will be computed at the same time. In this case, fl1 must be a spin-0 field and fl2 must be spin-s.

write_to(fname)[source]

Writes the contents of an NmtWorkspaceFlat object to a FITS file.

Parameters:

fname (str) – Output file name.

couple_cell(ells, cl_in)[source]

Convolves a set of input power spectra with a coupling matrix (see Eq. 42 of the NaMaster paper).

Parameters:

  • ells (array) – List of multipoles on which the input power spectra are defined.

  • cl_in (array) – Set of input power spectra. The number of power spectra must correspond to the spins of the two fields that this NmtWorkspace object was initialized with (i.e. 1 for two spin-0 fields, 2 for one spin-0 field and one spin-s field, and 4 for two spin-s fields).

Returns:

Mode-coupled power spectra. The coupled power spectra are returned at the multipoles returned by calling get_ell_sampling() for any of the fields that were used to generate the workspace.

Return type:

(array)

decouple_cell(cl_in, cl_bias=None, cl_noise=None)[source]

Decouples a set of pseudo-\(C_\ell\) power spectra into a set of bandpowers by inverting the binned coupling matrix (see Eq. 47 of the NaMaster paper).

Parameters:

  • cl_in (array) – Set of input power spectra. The number of power spectra must correspond to the spins of the two fields that this NmtWorkspace object was initialized with (i.e. 1 for two spin-0 fields, 2 for one spin-0 field and one spin-s field, 4 for two spin-s fields, and 7 if this NmtWorkspace was created using is_teb=True). These power spectra must be defined at the multipoles returned by get_ell_sampling() for any of the fields used to create the workspace.

  • cl_bias (array) – Bias to the power spectrum associated with contaminant residuals (optional). This can be computed through deprojection_bias_flat().

  • cl_noise (array) – Noise bias (i.e. angular pseudo-\(C_\ell\) of masked noise realisations).

Returns:

Set of decoupled bandpowers.

Return type:

(array)

pymaster.workspaces.deprojection_bias(f1, f2, cl_guess, n_iter=None)[source]

Computes the bias associated to contaminant removal to the cross-pseudo-\(C_\ell\) of two fields. See Eq. 26 in the NaMaster paper.

Parameters:

  • f1 (NmtField) – First field to correlate.

  • f2 (NmtField) – Second field to correlate.

  • cl_guess (array) – Array of power spectra corresponding to a best-guess of the true power spectra of f1 and f2.

  • n_iter (int) – Number of iterations when computing \(a_{\ell m}\) s. See docstring of NmtField.

Returns:

Deprojection bias pseudo-\(C_\ell\).

Return type:

(array)

pymaster.workspaces.uncorr_noise_deprojection_bias(f1, map_var, n_iter=None)[source]

Computes the bias associated to contaminant removal in the presence of uncorrelated inhomogeneous noise to the auto-pseudo-\(C_\ell\) of a given field.

Parameters:

  • f1 (NmtField) – Field being correlated.

  • map_var (array) – Single map containing the local noise variance in one steradian. The map should have the same pixelization used by f1.

  • n_iter (int) – Number of iterations when computing \(a_{\ell m}\) s. See docstring of NmtField.

Returns:

Deprojection bias pseudo-\(C_\ell\).

Return type:

(array)

pymaster.workspaces.deprojection_bias_flat(f1, f2, b, ells, cl_guess, ell_cut_x=[1.0, -1.0], ell_cut_y=[1.0, -1.0])[source]

Computes the bias associated to contaminant removal to the cross-pseudo-\(C_\ell\) of two flat-sky fields. See Eq. 50 in the NaMaster paper.

Parameters:

  • f1 (NmtFieldFlat) – First field to correlate.

  • f2 (NmtFieldFlat) – Second field to correlate.

  • b (NmtBinFlat) – Binning scheme defining the output bandpowers.

  • ells (array) – List of multipoles on which the guess power spectra are defined.

  • cl_guess (array) – Array of power spectra corresponding to a best-guess of the true power spectra of f1 and f2.

  • ell_cut_x (array) – Sequence of two elements determining the range of \(l_x\) to remove from the calculation. No Fourier modes removed by default.

  • ell_cut_y (array) – Sequence of two elements determining the range of \(l_y\) to remove from the calculation. No Fourier modes removed by default.

Returns:

Deprojection bias pseudo-\(C_\ell\).

Return type:

(array)

pymaster.workspaces.compute_coupled_cell(f1, f2)[source]

Computes the full-sky pseudo-\(C_\ell\) of two masked fields (f1 and f2) without aiming to deconvolve the mode-coupling matrix (Eq. 7 of the NaMaster paper). Effectively, this is equivalent to calling the usual HEALPix anafast routine on the masked and contaminant-cleaned maps.

Parameters:

  • f1 (NmtField) – First field to correlate.

  • f2 (NmtField) – Second field to correlate.

Returns:

Array of coupled pseudo-\(C_\ell\) s.

Return type:

(array)

pymaster.workspaces.compute_coupled_cell_flat(f1, f2, b, ell_cut_x=[1.0, -1.0], ell_cut_y=[1.0, -1.0])[source]

Computes the flat-sky pseudo-\(C_\ell\) of two masked fields (f1 and f2) without aiming to deconvolve the mode-coupling matrix (Eq. 42 of the NaMaster paper). Effectively, this is equivalent to computing the map FFTs and averaging over rings of wavenumber. The returned power spectrum is defined at the multipoles returned by the method get_ell_sampling() of either f1 or f2.

Parameters:

  • f1 (NmtFieldFlat) – First field to correlate.

  • f2 (NmtFieldFlat) – Second field to correlate.

  • b (NmtBinFlat) – Binning scheme defining the output bandpowers.

  • ell_cut_x (array) – Sequence of two elements determining the range of \(l_x\) to remove from the calculation. No Fourier modes removed by default.

  • ell_cut_y (array) – Sequence of two elements determining the range of \(l_y\) to remove from the calculation. No Fourier modes removed by default.

Returns:

Array of coupled pseudo-\(C_\ell\) s.

Return type:

(array)

pymaster.workspaces.compute_full_master(f1, f2, b=None, cl_noise=None, cl_guess=None, workspace=None, l_toeplitz=-1, l_exact=-1, dl_band=-1, normalization='MASTER')[source]

Computes the full MASTER estimate of the power spectrum of two fields (f1 and f2). This is equivalent to sequentially calling:

Parameters:

  • fl1 (NmtField) – First field to correlate.

  • fl2 (NmtField) – Second field to correlate.

  • b (NmtBin) – Binning scheme.

  • cl_noise (array) – Noise bias (i.e. angular pseudo-\(C_\ell\) of masked noise realizations).

  • cl_guess (array) – Array of power spectra corresponding to a best-guess of the true power spectra of f1 and f2.

  • workspace (NmtWorkspace) – Object containing the mode-coupling matrix associated with an incomplete sky coverage. If provided, the function will skip the computation of the mode-coupling matrix and use the information encoded in this object.

  • l_toeplitz (int) –

    If a positive number, the Toeplitz approximation described in Louis et al. 2020 will be used. In that case, this quantity corresponds to \(\ell_{\rm toeplitz}\) in Fig. 3 of that paper.

  • l_exact (int) – If l_toeplitz>0, it corresponds to \(\ell_{\rm exact}\) in Fig. 3 of the paper. Ignored if l_toeplitz<=0.

  • dl_band (int) – If l_toeplitz>0, this quantity corresponds to \(\Delta \ell_{\rm band}\) in Fig. 3 of the paper. Ignored if l_toeplitz<=0.

  • normalization (str) – Normalization convention to use for the bandpower window functions. Two options supported: ‘MASTER’ (default) corresponds to the standard inversion of the binned mode-coupling matrix. ‘FKP’ simply divides by the mean of the mask product, forcing a unit response to an input white spectrum.

Returns:

Set of decoupled bandpowers.

Return type:

(array)

pymaster.workspaces.compute_full_master_flat(f1, f2, b, cl_noise=None, cl_guess=None, ells_guess=None, workspace=None, ell_cut_x=[1.0, -1.0], ell_cut_y=[1.0, -1.0])[source]

Computes the full MASTER estimate of the power spectrum of two flat-sky fields (f1 and f2). This is equivalent to sequentially calling:

Parameters:

  • f1 (NmtFieldFlat) – First field to correlate.

  • f2 (NmtFieldFlat) – Second field to correlate.

  • b (NmtBinFlat) – Binning scheme defining the output bandpowers.

  • cl_noise (array) – Noise bias (i.e. angular pseudo-\(C_\ell\) of masked noise realisations).

  • cl_guess (array) – Array of power spectra corresponding to a best-guess of the true power spectra of f1 and f2.

  • ells_guess (array) – List of multipoles on which the guess power spectra are defined.

  • workspace (NmtWorkspaceFlat) – Object containing the mode-coupling matrix associated with an incomplete sky coverage. If provided, the function will skip the computation of the mode-coupling matrix and use the information encoded in this object.

  • ell_cut_x (array) – Sequence of two elements determining the range of \(l_x\) to remove from the calculation. No Fourier modes removed by default.

  • ell_cut_y (array) – Sequence of two elements determining the range of \(l_y\) to remove from the calculation. No Fourier modes removed by default.

Returns:

Set of decoupled bandpowers.

Return type:

(array)

pymaster.workspaces.get_general_coupling_matrix(pcl_mask, s1, s2, n1, n2)[source]

Returns a general mode-coupling matrix of the form

\[\begin{split}M_{\ell \ell'}=\sum_{\ell''} \frac{(2\ell'+1)(2\ell''+1)}{4\pi} \tilde{C}^{uv}_\ell \left(\begin{array}{ccc} \ell & \ell' & \ell'' \\ n_1 & -s_1 & s_1-n_1 \end{array}\right) \left(\begin{array}{ccc} \ell & \ell' & \ell'' \\ n_2 & -s_2 & s_2-n_2 \end{array}\right)\end{split}\]
Parameters:

  • pcl_mask (array) – 1D array containing the power spectrum of the masks \(\tilde{C}_\ell^{uw}\).

  • s1 (int) – spin index \(s_1\) above.

  • s2 (int) – spin index \(s_2\) above.

  • n1 (int) – spin index \(n_1\) above.

  • n2 (int) – spin index \(n_2\) above.

Returns:

2D array of shape [nl, nl], where nl is the size of pcl_mask, containing the mode-coupling matrix for multipoles from 0 to nl-1.

Return type:

(array)