pymaster.covariance module

class pymaster.covariance.NmtCovarianceWorkspace(fla1, fla2, flb1=None, flb2=None, all_spins=False, l_toeplitz=-1, l_exact=-1, dl_band=-1, fname=None)[source]

Bases: object

NmtCovarianceWorkspace objects are used to compute and store the coupling coefficients needed to calculate the Gaussian covariance matrix of angular power spectra under the approximations described in in Garcia-Garcia et al. 2019 (see also Efstathiou et al. 2003, and Couchot et al. 2016).

NmtCovarianceWorkspace objects may be constructed from a set of NmtField objects, describing the masks of the fields being correlated, or may be read from a file. We recommend using the class methods from_fields() and from_file() to create new NmtCovarianceWorkspace objects, rather than using the main constructor.

Parameters:

  • fla1 (NmtField) – First field contributing to the first power spectrum whose covariance you want to compute.

  • fla2 (NmtField) – Second field contributing to the first power spectrum whose covariance you want to compute.

  • flb1 (NmtField) – As fla1 for the second power spectrum. If None, it will be set to fla1.

  • flb2 (NmtField) – As fla2 for the second power spectrum. If None, it will be set to fla2.

  • all_spins (bool) – If True, coupling coefficients for all spin combinations will be calculated. Otherwise, only the spin combination determined by the input fields will be considered. The default value is True, but setting it to False will generally lead to faster results and better memory usage (at the expense of some flexibility).

  • 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, the values of all input fields will be ignored, and all mode-coupling coefficients will be read from file.

classmethod from_fields(fla1, fla2, flb1=None, flb2=None, *, all_spins=False, l_toeplitz=-1, l_exact=-1, dl_band=-1)[source]

Creates an NmtCovarianceWorkspace object containing the mode-coupling coefficients of the Gaussian covariance between the power spectra of two pairs of NmtField objects (fla1, fla2, flb1, and flb2). Note that you can reuse this workspace for the covariance of power spectra between any pairs of fields as long as the fields have the same masks as those passed to this function, and as long as the binning schemes used are also the same.

Parameters:

  • fla1 (NmtField) – First field contributing to the first power spectrum whose covariance you want to compute.

  • fla2 (NmtField) – Second field contributing to the first power spectrum whose covariance you want to compute.

  • flb1 (NmtField) – As fla1 for the second power spectrum. If None, it will be set to fla1.

  • flb2 (NmtField) – As fla2 for the second power spectrum. If None, it will be set to fla2.

  • all_spins (bool) – If True, coupling coefficients for all spin combinations will be calculated. Otherwise, only the spin combination determined by the input fields will be considered.

  • 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.

classmethod from_file(fname, fname_SN=None, fname_NS=None, fname_NN=None)[source]

Creates an NmtCovarianceWorkspace object from the mode-coupling coefficients stored in a FITS file. See write_to().

Parameters:

fname (str) – Input file name.

write_to(fname)[source]

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

Parameters:

fname (str) – Output file name.

gaussian_covariance(cla1b1, cla1b2, cla2b1, cla2b2, wa, wb=None, coupled=False, spins=None)[source]

Computes the Gaussian covariance matrix for power spectra using the information precomputed in this NmtCovarianceWorkspace object). Let us call the four fields used to initialise this workspace a1, a2, b1, and b2, corresponding to the two pairs of fields whose power spectra we want the covariance of. These power spectra should have been computed using two NmtWorkspace objects, wa and wb, which must be passed as arguments of this method (the power spectrum for fields a1 and a2 was computed with wa, and that of b1 and b2 with wb). Using the same notation, clXnYm should be a prediction for the power spectrum between fields Xn and Ym. These predicted input power spectra should be defined for all multipoles \(\ell\) up to the \(\ell_{\rm max}\) with which all fields were constructed.

Note

Note that, as suggested in Nicola et al. 2020 (the so-called “improved narrow-kernel approximation” - iNKA), an optimal choice for the input power spectra would be the mode-coupled version of the true power spectra of the corresponding fields divided by the average of the product of the associated masks across the sky (Eq. 2.36 in the paper). Often, a good substitute for this can be obtained as the pseudo-\(C_\ell\) of the associated maps (e.g. computed via compute_coupled_cell()), divided by the same mean mask product. The convenience function get_iNKA_cell() may be used to calculate this spectrum under the iNKA.

Parameters:

  • cla1b1 (array) – Prediction for the cross-power spectrum between fields a1 and b1.

  • cla1b2 (array) – As cla1b1 for fields a1 and b2.

  • cla2b1 (array) – As cla1b1 for fields a2 and b1.

  • cla2b2 (array) – As cla1b1 for fields a2 and b2.

  • wa (NmtWorkspace) – Workspace containing the mode-coupling matrix for the first power spectrum (that of fields a1 and a2).

  • wb (NmtWorkspace) – As wa for the second power spectrum (that of fields b1 and b2). If None, wa will be used instead.

  • coupled (bool) – If True, the covariance matrix of the mode-coupled pseudo-\(C_\ell\) s will be computed. Otherwise it’ll be the covariance of mode-decoupled bandpowers.

  • spins (array) – A list of 4 integers containing the spins of the fields whose power spectrum covariance one wishes to calculate. Note that you can only select arbitrary spin combinations if you created this object using all_spins=True. If None, the spin combination is determined by the fields used to create this object.

class pymaster.covariance.NmtCovarianceWorkspaceFlat[source]

Bases: object

NmtCovarianceWorkspaceFlat objects are used to compute and store the coupling coefficients needed to calculate the Gaussian covariance matrix of angular power spectra using a flat-sky version of the approximations described in Garcia-Garcia et al. 2019. When initialized, this object is practically empty. The information describing the coupling coefficients must be computed or read from a file afterwards.

read_from(fname)[source]

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

Parameters:

fname (str) – Input file name.

compute_coupling_coefficients(fla1, fla2, bin_a, flb1=None, flb2=None, bin_b=None)[source]

Computes coupling coefficients of the Gaussian covariance between the power spectra of two pairs of NmtFieldFlat objects (fla1, fla2, flb1, and flb2). Note that you can reuse this workspace for the covariance of power spectra between any pairs of fields as long as the fields have the same masks as those passed to this function, and as long as the binning schemes used are also the same.

Parameters:

  • fla1 (NmtFieldFlat) – First field contributing to the first power spectrum whose covariance you want to compute.

  • fla2 (NmtFieldFlat) – Second field contributing to the first power spectrum whose covariance you want to compute.

  • bin_a (NmtBinFlat) – Binning scheme for the first power spectrum.

  • flb1 (NmtFieldFlat) – As fla1 for the second power spectrum. If None, it will be set to fla1.

  • flb2 (NmtFieldFlat) – As fla2 for the second power spectrum. If None, it will be set to fla2.

  • bin_b (NmtBinFlat) – Binning scheme for the second power spectrum. If None, bin_a will be used.

write_to(fname)[source]

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

Parameters:

fname (str) – Output file name.

gaussian_covariance(spin_a1, spin_a2, spin_b1, spin_b2, larr, cla1b1, cla1b2, cla2b1, cla2b2, wa, wb=None)[source]

As NmtCovarianceWorkspace.gaussian_covariance() but for the flat-sky versions of all quantities involved. The only difference with is that all power spectra must have been sampled at the input multipoles larr, and the spins of all fields must be specified.

pymaster.covariance.gaussian_covariance(cw, spin_a1, spin_a2, spin_b1, spin_b2, cla1b1, cla1b2, cla2b1, cla2b2, wa, wb=None, coupled=False)[source]

Computes the Gaussian covariance matrix for power spectra using the information precomputed in cw (a NmtCovarianceWorkspace object). cw should have been initialized using four NmtField objects (let’s call them a1, a2, b1, and b2), corresponding to the two pairs of fields whose power spectra we want the covariance of. These power spectra should have been computed using two NmtWorkspace objects, wa and wb, which must be passed as arguments of this function (the power spectrum for fields a1 and a2 was computed with wa, and that of b1 and b2 with wb). Using the same notation, clXnYm should be a prediction for the power spectrum between fields Xn and Ym. These predicted input power spectra should be defined for all multipoles \(\ell\) up to the \(\ell_{\rm max}\) with which all fields were constructed.

Warning

This function is deprecated and will be removed in a future version of NaMaster. Use the NmtCovarianceWorkspace.gaussian_covariance() method instead.

Parameters:

  • cw (NmtCovarianceWorkspace) – Workspace containing the precomputed coupling coefficients.

  • spin_a1 (int) – Spin of field a1.

  • spin_a2 (int) – Spin of field a2.

  • spin_b1 (int) – Spin of field b1.

  • spin_b2 (int) – Spin of field b2.

  • cla1b1 (array) – Prediction for the cross-power spectrum between fields a1 and b1.

  • cla1b2 (array) – As cla1b1 for fields a1 and b2.

  • cla2b1 (array) – As cla1b1 for fields a2 and b1.

  • cla2b2 (array) – As cla1b1 for fields a2 and b2.

  • wa (NmtWorkspace) – Workspace containing the mode-coupling matrix for the first power spectrum (that of fields a1 and a2).

  • wb (NmtWorkspace) – As wa for the second power spectrum (that of fields b1 and b2). If None, wa will be used instead.

  • coupled (bool) – If True, the covariance matrix of the mode-coupled pseudo-\(C_\ell\) s will be computed. Otherwise it’ll be the covariance of mode-decoupled bandpowers.

pymaster.covariance.gaussian_covariance_flat(cw, spin_a1, spin_a2, spin_b1, spin_b2, larr, cla1b1, cla1b2, cla2b1, cla2b2, wa, wb=None)[source]

As gaussian_covariance() but for the flat-sky versions of all quantities involved. The only difference with gaussian_covariance() is that all power spectra must have been sampled at the input multipoles larr.

Warning

This function is deprecated and will be removed in a future version of NaMaster. Use the NmtCovarianceWorkspaceFlat.gaussian_covariance() method instead.

pymaster.covariance.get_iNKA_cell(fla, flb, cl_guess=None, w=None)[source]

Returns the power spectrum that should be used in the calculation of the Gaussian covariance matrix according to the improved Narrow-Kernel Approximation (iNKA) of Nicola et al. 2020. This can then be used, for instance, as input for NmtCovarianceWorkspace.gaussian_covariance().

The two fields whose power spectra we need must be compatible. This means that, at least, they must be represented in harmonic space up to the same maximum multipole. If they are also compatible at the map level, the effective sky fraction used in the iNKA will be calculated from the product of their masks. Otherwise, their harmonic-space spectrum will be used.

Parameters:

  • fla (NmtField) – First field whose power spectrum we want to calculate.

  • flb (NmtField) – Second field whose power spectrum we want to calculate.

  • cl_guess (array) – A guess for the true power spectra between fla and flb. The number of power spectra must correspond to the spins of the two fields in question. If None, the pseudo-\(C_\ell\) between the two fields will be used instead.

  • w (NmtWorkspace) – Workspace containing the mode-coupling matrix for these two fields. This is only required if cl_guess is not None. If needed but None, the mode-coupling matrix will be calculated on the fly.

Returns:

power spectrum to be used in covariance calculations.

Return type:

(array)