pymaster.field module

class pymaster.field.NmtField(mask, maps, *, spin=None, templates=None, beam=None, purify_e=False, purify_b=False, n_iter=None, n_iter_mask=None, tol_pinv=None, wcs=None, lmax=None, lmax_mask=None, masked_on_input=False, lite=False, mask_22=None, mask_12=None)[source]

Bases: object

An NmtField object contains all the information describing the fields to correlate, including their observed maps, masks and contaminant templates.

Parameters:

  • mask (array) – Array containing a map corresponding to the field’s mask. Should be 1-dimensional for a HEALPix map or 2-dimensional for a map with rectangular (CAR) pixelization.

  • maps (array) – Array containing the observed maps for this field. Should be at least 2-dimensional. The first dimension corresponds to the number of maps, which should be 1 for a spin-0 field and 2 otherwise. The other dimensions should be either [npix] for HEALPix maps or [ny,nx] for maps with rectangular pixels (with the y and x dimensions corresponding to latitude and longitude respectively). For a spin>0 field, the two maps passed should be the usual Q/U Stokes parameters for polarization, or \(e_1\)/\(e_2\) (\(\gamma_1\)/\(\gamma_2\) etc.) in the case of cosmic shear. It is important to note that NaMaster uses the same polarization convention as HEALPix (i.e. with the growing colatitude \(\theta\)). It is however more common for galaxy ellipticities to be provided using the IAU convention (e.g. growing declination). In this case, the sign of the \(e_2\)/\(\gamma_2\) map should be swapped before using it to create an NmtField. See more here. If None, this field will only contain a mask but no maps. The field can then be used to compute a mode-coupling matrix, for instance, but not actual power spectra.

  • spin (int) – Spin of this field. If None it will default to 0 or 2 if maps contains 1 or 2 maps, respectively.

  • templates (array) – Array containing a set of contaminant templates for this field. This array should have shape [ntemp,nmap,...], where ntemp is the number of templates, nmap should be 1 for spin-0 fields and 2 otherwise. The other dimensions should be [npix] for HEALPix maps or [ny,nx] for maps with rectangular pixels. The best-fit contribution from each contaminant is automatically removed from the maps unless templates=None.

  • beam (array) – Spherical harmonic transform of the instrumental beam (assumed to be rotationally symmetric - i.e. no \(m\) dependence). If None, no beam will be corrected for. Otherwise, this array should have at least as many elements as the maximum multipole sampled by the maps + 1 (see lmax). Note that NaMaster does not automatically correct for pixel window function effects, as this is not always appropriate. If you want to correct for these effects, you should include them pixel window function in the beam or account for it when interpreting the measured power spectrum.

  • purify_e (bool) – Purify E-modes?

  • purify_b (bool) – Purify B-modes?

  • n_iter (int) – Number of iterations when computing the \(a_{\ell m}\) s of the input maps. See the documentation of map2alm(). If None, it will default to the internal value (see documentation of NmtParams), which can be accessed via get_default_params(), and modified via set_n_iter_default().

  • n_iter_mask (int) – Number of iterations when computing the spherical harmonic transform of the mask. If None, it will default to the internal value (see documentation of NmtParams), which can be accessed via get_default_params(), and modified via set_n_iter_default().

  • lmax (int) – Maximum multipole up to which map power spectra will be computed. If None, the maximum multipole given the map resolution will be used (e.g. \(3N_{\rm side}-1\) for HEALPix maps).

  • lmax_mask (int) – Maximum multipole up to which the power spectrum of the mask will be computed. If None, the maximum multipole given the map resolution will be used (e.g. \(3N_{\rm side}-1\) for HEALPix maps).

  • tol_pinv (float) – When computing the pseudo-inverse of the contaminant covariance matrix. See documentation of moore_penrose_pinvh(). Only relevant if passing contaminant templates that are likely to be highly correlated. If None, it will default to the internal value, which can be accessed via get_default_params(), and modified via set_tol_pinv_default().

  • wcs (WCS) – A WCS object if using rectangular (CAR) pixels (see the astropy documentation).

  • masked_on_input (bool) – Set to True if the input maps and templates are already multiplied by the mask. Note that this is not advisable if you’re using purification, as correcting for this usually incurs inaccuracies around the mask edges that may lead to significantly biased power spectra.

  • lite (bool) – Set to True if you want to only store the bare minimum necessary to run a standard pseudo-\(C_\ell\) with deprojection and purification, but you don’t care about deprojection bias. This will significantly reduce the memory taken up by the resulting object.

  • mask_22 (array) – Array containing the mask corresponding to the 22 component of an anisotropic weight matrix. If not None the mask argument will be interpreted as the 11 component of the same matrix. The off-diagonal component of the weight matrix must then be passed as mask_12 (below). If mask_22 and mask_12 are None, isotropic weighting is assumed, described by mask.

  • mask_12 (array) – Array containing the off-diagonal component of the anisotropic weight matrix. See mask_22 above.

is_compatible(other, strict=True)[source]

Returns True if the this NmtField is compatible with that of another one (other).

Parameters:

  • other – field to compare with

  • strict – if True, the fields are compared at the pixel- and harmonic-space levels. Otherwise, only the harmonic-space resolution is compared. This is relevant if only power spectra between fields are necessary, but no pixel-level operations (e.g. map multiplications).

get_mask()[source]

Get this field’s mask.

Returns:

1D array containing the field’s mask.

Return type:

(array)

get_anisotropic_mask()[source]

Get this field’s anisotropic mask components.

Returns:

2D array containing the field’s anisotropic mask.

Return type:

(array)

get_mask_alms()[source]

Get the \(a_{\ell m}\) coefficients of this field’s mask. Note that, in most cases, the mask \(a_{\ell n}\) s are not computed when generating the field. When calling this function for the first time, if they have not been calculated, they will be (which may be a slow operation), and stored internally for any future calls.

Returns:

1D array containing the mask \(a_{\ell m}\) s.

Return type:

(array)

get_anisotropic_mask_alms()[source]

Get the \(a_{\ell m}\) coefficients of this field’s anisotropic mask components.

Returns:

2D array containing the mask \(a_{\ell m}\) s.

Return type:

(array)

get_maps()[source]

Get this field’s set of maps. The returned maps will be masked, contaminant-deprojected, and purified (if so required when generating this NmtField).

Returns:

2D array containing the field’s maps.

Return type:

(array)

get_alms()[source]

Get the \(a_{\ell m}\) coefficients of this field. They include the effects of masking, as well as contaminant deprojection and purification (if required when generating this NmtField).

Returns:

2D array containing the field’s \(a_{\ell m}\) s.

Return type:

(array)

get_templates()[source]

Get this field’s set of contaminant templates maps. The returned maps will have the mask applied to them.

Returns:

3D array containing the field’s contaminant maps.

Return type:

(array)

property Nw

Shot noise contribution associated with the mask for catalog-based fields (0 for standard fields).

property Nf

Shot noise contribution to the weighted field power spectrum for catalog-based fields (0 for standard fields).

property alpha

Ratio of random to data catalog sources (None for standard fields or catalog-based fields without randoms).

class pymaster.field.NmtFieldFlat(lx, ly, mask, maps, spin=None, templates=None, beam=None, purify_e=False, purify_b=False, tol_pinv=None, masked_on_input=False, lite=False)[source]

Bases: object

An NmtFieldFlat object contains all the information describing the flat-sky fields to correlate, including their observed maps, masks and contaminant templates.

Parameters:

  • lx (float) – Size of the patch in the x direction (in radians).

  • ly (float) – Size of the patch in the y direction (in radians).

  • mask (array) – 2D array of shape (ny, nx) containing the field’s mask.

  • maps (array) – Array containing the observed maps for this field. Should be at 3-dimensional. The first dimension corresponds to the number of maps, which should be 1 for a spin-0 field and 2 otherwise. The other dimensions should be (ny, nx). If None, this field will only contain a mask but no maps. The field can then be used to compute a mode-coupling matrix, for instance, but not actual power spectra.

  • spin (int) – Spin of this field. If None it will default to 0 or 2 if maps contains 1 or 2 maps, respectively.

  • templates (array) – Array containing a set of contaminant templates for this field. This array should have shape [ntemp,nmap,ny,nx], where ntemp is the number of templates, and nmap should be 1 for spin-0 fields and, 2 otherwise. The best-fit contribution from each contaminant is automatically removed from the maps unless templates=None.

  • beam (array) – Spherical harmonic transform of the instrumental beam (assumed to be rotationally symmetric). Should be 2D, with shape (2,nl). beam[0] contains the values of \(\ell\) for which de beam is defined, with beam[1] containing the corresponding beam values. If None, no beam will be corrected for. Note that NaMaster does not automatically correct for pixel window function effects, as this is not always appropriate. If you want to correct for these effects, you should include them pixel window function in the beam or account for it when interpreting the measured power spectrum.

  • purify_e (bool) – Purify E-modes?

  • purify_b (bool) – Purify B-modes?

  • tol_pinv (float) – When computing the pseudo-inverse of the contaminant covariance matrix. See documentation of moore_penrose_pinvh(). Only relevant if passing contaminant templates that are likely to be highly correlated. If None, it will default to the internal value, which can be accessed via get_default_params(), and modified via set_tol_pinv_default().

  • masked_on_input (bool) – Set to True if the input maps and templates are already multiplied by the mask. Note that this is not advisable if you’re using purification, as correcting for this usually incurs inaccuracies around the mask edges that may lead to significantly biased power spectra.

  • lite (bool) – Set to True if you want to only store the bare minimum necessary to run a standard pseudo-\(C_\ell\) with deprojection and purification, but you don’t care about deprojection bias. This will significantly reduce the memory taken up by the resulting object.

get_mask()[source]

Returns this field’s mask as a 2D array with shape (ny, nx).

Returns:

Mask.

Return type:

(array)

get_maps()[source]

Returns a 3D array with shape (nmap, ny, nx) corresponding to the observed maps for this field. If the field was initialized with contaminant templates, the maps returned by this function have their best-fit contribution from these contaminants removed.

Returns:

Maps.

Return type:

(array)

get_templates()[source]

Returns a 4D array with shape (ntemp, nmap, ny, nx), corresponding to the contaminant templates passed when initializing this field.

Returns:

Contaminant maps.

Return type:

(array)

get_ell_sampling()[source]

Returns the finest \(\ell\) sampling at which intermediate power spectra calculated involving this field are evaluated.

Returns:

Array of \(\ell\) values.

Return type:

(array)

class pymaster.field.NmtFieldCatalog(positions, weights, field, lmax, lmax_mask=None, spin=None, beam=None, field_is_weighted=False, lonlat=False, templates=None, tol_pinv=None, noise_variance=None)[source]

Bases: NmtField

An NmtFieldCatalog object contains all the information describing a field sampled at the discrete positions of a given catalog of sources. If you want to estimate clustering power spectra directly from catalogs, use NmtFieldCatalogClustering instead. The mathematical background for these fields was laid out in Baleato & White 2024 , and expanded in Wolz et al. 2024.

Parameters:

  • positions (array) – Source positions, provided as a list or array of 2 arrays. If lonlat is True, the arrays should contain the longitude and latitude of the sources, in this order, and in degrees (e.g. R.A. and Dec. if using Equatorial coordinates). Otherwise, the arrays should contain the colatitude and longitude of each source in radians (i.e. the spherical coordinates \((\theta,\phi)\)).

  • weights (array) – An array containing the weight assigned to each source.

  • field (array) – A list of 1 or 2 arrays (for spin-0 and spin-s fields, respectively), containing the value of the field whose power spectra we aim to calculate at the positions of each source.

  • lmax (int) – Maximum multipole up to which the spherical harmonics of this field will be computed.

  • lmax_mask (int) – Maximum multipole up to which the spherical harmonics of this field’s mask will be computed. If None, it will default to lmax. Note that you should explore the sensitivity of the recovered \(C_\ell\) to the choice of lmax_mask, and enlarge it if necessary.

  • spin (int) – Spin of this field. If None it will default to 0 or 2 if field contains 1 or 2 arrays, respectively.

  • beam (array) – Spherical harmonic transform of the instrumental beam (assumed to be rotationally symmetric - i.e. no \(m\) dependence) associated with any smoothing that the field that was sampled on these catalog sources may have undergone. If None, no beam will be corrected for. Otherwise, this array should have at least of size lmax+1.

  • field_is_weighted (bool) – Set to True if the input field has already been multiplied by the source weights. The same will also be assumed of the contaminant templates (see templates).

  • lonlat (bool) – If True, longitude and latitude in degrees are provided as input. If False, colatitude and longitude in radians are provided instead.

  • templates (array) – Array containing the values of a set of contaminant templates for this field sampled at the source positions. This array should have a shape [ntemp, nmap, nsrc], where ntemp is the number of templates, nmap is 1 for spin-0 fields and 2 otherwise, and nsrc is the number of sources in the catalogue (i.e. the length of weights). The best-fit contribution from all contaminants is automatically subtracted (i.e. deprojected) from the field values for each source. If None, no deprojection is carried out.

  • tol_pinv (float) – When computing the pseudo-inverse of the contaminant covariance matrix. See documentation of moore_penrose_pinvh(). Only relevant if passing contaminant templates that are likely to be highly correlated. If None, it will default to the internal value, which can be accessed via get_default_params(), and modified via set_tol_pinv_default().

  • noise_variance (array) – estimate of the noise variance per source. Needed to correct for additional uncorrelated noise bias due to deprojection. If None, no additional correction is computed.

get_noise_deprojection_bias()[source]

Returns the deprojection bias due to uncorrelated noise for this field. You may only use this function if you provided a noise_variance when creating this field.

Returns:

noise deprojection bias to the power spectrum.

Return type:

(array)

class pymaster.field.NmtFieldCatalogClustering(positions, weights, positions_rand, weights_rand, lmax, lonlat=False, mask=None, lmax_mask=None, n_iter_mask=None, wcs=None, templates=None, lmax_deproj=None, n_iter_temp=None, tol_pinv=None, masked_on_input=False, calculate_noise_dp_bias=False)[source]

Bases: NmtField

An NmtFieldCatalogClustering object contains all the information describing a field represented by the position and density of discrete sources, with a survey footprint characterised by a set of random points or through a standard mask.

Note

The ordering of arguments for this class will change in the next major version of NaMaster.

Parameters:

  • positions (array) – Source positions, provided as a list or array of 2 arrays. If lonlat is True, the arrays should contain the longitude and latitude of the sources, in this order, and in degrees (e.g. R.A. and Dec. if using Equatorial coordinates). Otherwise, the arrays should contain the colatitude and longitude of each source in radians (i.e. the spherical coordinates \((\theta,\phi)\)).

  • weights (array) – An array containing the weight assigned to each source.

  • positions_rand (array) – As positions for the random catalog.

  • weights_rand (array) – As weights for the random catalog.

  • lmax (int) – Maximum multipole up to which the spherical harmonics of this field will be computed.

  • mask (array) – Array containing a map corresponding to the field’s mask. Should be 1-dimensional for a HEALPix map or 2-dimensional for a map with rectangular (CAR) pixelization. If not None, the random catalogue (positions_rand and weights_rand) will be ignored.

  • lmax_mask (int) – Maximum multipole up to which the power spectrum of the mask will be computed. If None, lmax will be used if mask is None. If a mask is provided as a map, the maximum multipole given the map resolution will be used (e.g. \(3N_{\rm side}-1\) for HEALPix maps).

  • lonlat (bool) – If True, longitude and latitude in degrees are provided as input. If False, colatitude and longitude in radians are provided instead.

  • n_iter_mask (int) – Number of iterations when computing the spherical harmonic transform of the mask. If None, it will default to the internal value (see documentation of NmtParams), which can be accessed via get_default_params(), and modified via set_n_iter_default().

  • wcs (WCS) –

    A WCS object if using rectangular (CAR) pixels (see the astropy documentation).

  • templates (array) – An array containing either the values of a set of contaminant templates for this field sampled at the positions of the randoms, or the templates themselves. The choice depends on whether the survey footprint is being characterised using a set of randoms, or with a standard mask. If the former, this array should have a shape [ntemp, 1, nran] where ntemp is the number of templates, and nran is the number of randoms (i.e. the length of weights_rand). If the latter, it should have shape [ntemp, 1, npix], where npix is the number of pixels in each template (all templates must have the same resolution). The best-fit contribution from all contaminants is automatically subtracted (i.e. deprojected) from the density field values for each source. If None, no deprojection is carried out.

  • lmax_deproj (int) – maximum multipole used for contaminant deprojection. If None, lmax will be used.

  • n_iter_temp (int) – Number of iterations when computing the spherical harmonic transform of the templates. Note that this is only relevant if a mask is provided. If None, it will default to the internal value (see documentation of NmtParams), which can be accessed via get_default_params(), and modified via set_n_iter_default().

  • tol_pinv (float) – When computing the pseudo-inverse of the contaminant covariance matrix. See documentation of moore_penrose_pinvh(). Only relevant if passing contaminant templates that are likely to be highly correlated. If None, it will default to the internal value, which can be accessed via get_default_params(), and modified via set_tol_pinv_default().

  • masked_on_input (bool) – Set to True if the input templates have already been masked. If templates is provided as an array of templates sampled at the positions of the randoms, then the templates are considered masked if the sampled values have been multiplied by the weights of the corresponding randoms. If templates is instead an array containing the templates themselves, then this masking consitutes a pixel-wise multiplication of each template with the mask.

  • calculate_noise_dp_bias (bool) – If set to True, will compute and store the bias induced in the shot noise component of the pseudo-\(C_\ell\) by template deprojection. This can be retrieved through get_noise_deprojection_bias().

get_noise_deprojection_bias()[source]

Returns the deprojection bias due to uncorrelated shot noise for this field. You may only use this function if you used calculate_noise_dp_bias=True when creating this field.

Returns:

noise deprojection bias to the power spectrum.

Return type:

(array)

class pymaster.field.NmtFieldCatalogMomentum(positions, weights, field, positions_rand, weights_rand, lmax, lonlat=False, mask=None, lmax_mask=None, n_iter_mask=None, wcs=None, tol_pinv=None)[source]

Bases: NmtField

An NmtFieldCatalogMomentum object contains all the information describing a field weighted by the local density of sources. A typical application of such a field is in the analysis of kSZ-galaxy correlations, where one must construct the radial galaxy momentum field (see Harscouet et al. 2025 for details). The mean density of sources in the sample is characterised by a set of random points or through a standard mask.

Note

The ordering of arguments for this class will change in the next major version of NaMaster.

Parameters:

  • positions (array) – Source positions, provided as a list or array of 2 arrays. If lonlat is True, the arrays should contain the longitude and latitude of the sources, in this order, and in degrees (e.g. R.A. and Dec. if using Equatorial coordinates). Otherwise, the arrays should contain the colatitude and longitude of each source in radians (i.e. the spherical coordinates \((\theta,\phi)\)).

  • weights (array) – An array containing the weight assigned to each source.

  • field (array) – An array containing the field values (e.g. the reconstructed galaxy velocities, in the case of a galaxy momentum field) at the source positions.

  • positions_rand (array) – As positions for the random catalog.

  • weights_rand (array) – As weights for the random catalog.

  • lmax (int) – Maximum multipole up to which the spherical harmonics of this field will be computed.

  • mask (array) – Array containing a map corresponding to the field’s mask. Should be 1-dimensional for a HEALPix map or 2-dimensional for a map with rectangular (CAR) pixelization. If not None, the random catalogue (positions_rand and weights_rand) will be ignored.

  • lmax_mask (int) – Maximum multipole up to which the power spectrum of the mask will be computed. If None, lmax will be used if mask is None. If a mask is provided as a map, the maximum multipole given the map resolution will be used (e.g. \(3N_{\rm side}-1\) for HEALPix maps).

  • lonlat (bool) – If True, longitude and latitude in degrees are provided as input. If False, colatitude and longitude in radians are provided instead.

  • n_iter_mask (int) – Number of iterations when computing the \(a_{\ell m}\) s of the input mask. See the documentation of map2alm(). If None, it will default to the internal value (see documentation of NmtParams), which can be accessed via get_default_params(), and modified via set_n_iter_default(). Only needed if mask is not None.

  • wcs (WCS) –

    A WCS object if using rectangular (CAR) pixels (see the astropy documentation).