nikamap.ContMap¶

class nikamap.ContMap(data, *args, **kwargs)[source]¶

A ContMap object represent a continuum map with additionnal capabilities.

It contains the metadata, wcs, and all attribute (data/stddev/time/unit/mask) as well as potential source list detected in these maps.

Parameters:

data (ndarray or astropy.nddata.NDData) – The actual data contained in this NDData object. Not that this will always be copies by reference , so you should make copy the data before passing it in if that’s the desired behavior.
uncertainty (astropy.nddata.NDUncertainty, optional) – Uncertainties on the data.
mask (ndarray-like, optional) – Mask for the data, given as a boolean Numpy array or any object that can be converted to a boolean Numpy array with a shape matching that of the data. The values must be False where the data is valid and True when it is not (like Numpy masked arrays). If data is a numpy masked array, providing mask here will causes the mask from the masked array to be ignored.
hits (ndarray-like, optional) – The hit per pixel on the map
sampling_freq (float or Quantity) – the sampling frequency of the experiment, default 1 Hz
wcs (undefined, optional) – WCS-object containing the world coordinate system for the data.
meta (dict-like object, optional) – Metadata for this object. “Metadata” here means all information that is included with this object but not part of any other attribute of this particular object. e.g., creation date, unique identifier, simulation parameters, exposure time, telescope name, etc.
unit (astropy.units.UnitBase instance or str, optional) – The units of the data.
beam (ContBeam) – The beam corresponding to the data, by default a gaussian constructed from the header ‘BMAJ’ ‘BMIN’, ‘PA’ keyword.
fake_source (astropy.table.Table, optional) –
The table of potential fake sources included in the data

Note

The table must contain at least 3 columns: [‘ID’, ‘ra’, ‘dec’]
sources (:class`astropy.table.Table`, optional) – The table of detected sources in the data.

surface(box_size=None)[source]¶

Retrieve surface covered by unmasked pixels.

Parameters:: box_size (scalar or tuple, optional) – The edge of the map is cropped by the box_size if not None. Default is None.
Returns:: Surface covered by unmasked pixels
Return type:: astropy.units.Quantity

Notes

Default value for box_size in detect_sources is 5

property uncertainty¶

Uncertainty in the dataset, if any.

Should have an attribute uncertainty_type that defines what kind of uncertainty is stored, such as 'std' for standard deviation or 'var' for variance. A metaclass defining such an interface is NDUncertainty but isn’t mandatory.

Type:: any type

property weights¶: Return the weights as inverse variance regardless of the uncertainty type

trim()[source]¶

Remove masked region on the edges

Returns:: return a trimmed ContMap object
Return type:: ContMap

add_gaussian_sources(within=(0, 1), peak_flux=<Quantity 1. mJy>, cat_gen=<function pos_uniform>, **kwargs)[source]¶

Add gaussian sources into the map.

Parameters:

within (tuple of 2 int) – force the sources within this relative range in the map
cat_gen (callable (pos_uniform | pos_gridded | pos_list | …)) – the function used to generate the pixel positions and flux of the sources (see Notes below)
**kwargs – any keyword arguments to be passed to the cat_gen function

Notes

the cat_gen function is used to generate the list of x, y pixel positions and fluxes and must at least support the shape=None, within=(0, 1), mask=None arguments.

detect_sources(threshold=3, box_size=5, detect_on='snr')[source]¶

Detect sources with find local peaks above a specified threshold value.

The detection is made on the SNR map, and return an :class`astropy.table.Table` with columns ID, ra, dec, SNR. If fake sources are present, a match is made with a distance threshold of beam_fwhm / 3

Parameters:

threshold (float) – The data value or pixel-wise data values to be used for the detection threshold.
box_size (scalar or tuple, optional) – The size of the local region to search for peaks at every point in data. If box_size is a scalar, then the region shape will be (box_size, box_size).
detect_on (str (None|signal|uncertainty|snr|residual)) – do the detection on given array, default ‘snr’

Notes

The edge of the map is cropped by the box_size in order to insure proper subpixel fitting.

phot_sources(sources=None, peak=True, psf=True, fixed_positions=True, fixed_sigma=True, background=True, local_background=False, background_clipping=3, grouping_threshold=3, fit_shape=11)[source]¶

_summary_

Parameters:

sources (astropy.table.Table, optional) – Catalog on which to do the photometry, by default None
peak (bool, optional) – Do peak photometry, by default True
psf (bool, optional) – Do psf photometry, by default True
fixed_positions (bool, optional,) – Fix sources positions in the fit, default True
fixed_sigma (bool, optional) – Fix the sigma of the psf in the fit, default True
background (bool, optional) – Estimate and remove a global median background, by default True
local_background (bool, optional) – Estimate and remove a local background, by default True
background_clipping (int, optional) – Sigma clipping used for the background, by default 3
grouping_threshold (int, optional) – Grouping distance for psf photometry in unit of psf fwhm, by default 3
fit_shape (int, optional) – The size of the box used for the fit in unit of pixel, by default 11

match_filter(kernel)[source]¶

Return a matched filtered version of the map.

Parameters:: kernel (nikamap.contmap.ContBeam or any astropy.convolution.kernel2D) – the kernel used for filtering
Returns:: the resulting match filtered ContMap object
Return type:: nikamap.ContMap

Notes

This compute the match filtered \(MF\) map as :

\[MF = \frac{B * (W M)}{B^2 * W}\]

with \(B\) the beam, \(W\) the weights (inverse variance) and \(M\) the signal map

Peak photometry is conserved for data and e_data

Resultings maps have a different mask

>>> npix, std = 501, 4
>>> kernel = ContBeam(std, pixscale=1*u.deg)
>>> mask = np.zeros((npix,npix))
>>> data = np.random.normal(0, 1, size=mask.shape)
>>> data[(npix-std*7-1)//2:(npix+std*7-1)//2+1,(npix-std*7-1)//2:(npix+std*7-1)//2+1] += kernel.array/kernel.array.max()
>>> data = ContMap(data, uncertainty=np.ones_like(data), hits=np.ones_like(data)*u.s, mask=mask)
>>> mf_data = data.match_filter(kernel)
>>> import matplotlib.pyplot as plt
>>> fig, axes = plt.subplots(ncols=2)
>>> _ = axes[0].imshow(data) ; _ = axes[1].imshow(mf_data)

plot(to_plot=None, ax=None, cbar=False, cat=None, levels=None, beam=False, **kwargs)[source]¶

Convenience routine to plot the dataset.

Parameters:

to_plot (str, optionnal (None|signal|uncertainty|snr|residual)) – Choose which quantity to plot, by default None (signal)
ax (matplotlib.axes.Axes, optional) – Axe to plot the power spectrum
cbar (boolean) – Draw a colorbar (ax must be None), default=False
cat (boolean of list of tuple [(cat, kwargs)], optionnal) – If True, overplot the current self.source catalog with ‘^’ as marker. Otherwise overplot the given catalogs on the map, with kwargs.
levels (array_like, optionnal) – Overplot levels contours, add negative contours as dashed line
beam (boolean) – Draw a beam in the lower left corner, default False
**kwargs – Arbitrary keyword arguments for matplotlib.pyplot.imshow()

Returns:

image

Return type:

AxesImage

Notes

if a fake_sources property is present, it will be overplotted with ‘o’ as marker
each catalog must have ‘_ra’ & ‘_dec’ column

plot_SNR(vmin=-3, vmax=5, **kwargs)[source]¶

Convenience method to plot the signal to noise map.

Notes

See nikamap.ContMap.plot() for additional keywords

check_SNR_pdf(ax=None, range=(-6, 3), return_mean=False)[source]¶

Perform normality test on SNR map.

This perform a normal distribution fit on snr pixels clipped between -6 and 3

Parameters:

ax (Axes, optional) – axe to plot the histogram and fits
range (tuple of 2 floats) – perform the fit on the histogram between range[0] and range[1], default (-6, 3)
return_mean (bool) – if True, return the mean of the histogram, default False

Returns:

std – return the robust standard deviation of the SNR

Return type:

float[robust]

Notes

To recover the normality you must multiply the uncertainty array by the returned stddev value, if uncertainty is StdDevUncertainty.

>>> data = ContMap(np.random.normal(0, 1, size=(100, 100)), uncertainty=np.ones((100, 100)), mask=None)
>>> std = data.check_SNR_pdf()
>>> data.uncertainty.array *= std

check_SNR(ax=None, bins='auto', range=(-6, 3), return_mean=False, **kwargs)[source]¶

Perform normality test on SNR map.

This perform a gaussian fit on snr pixels histogram clipped between -6 and 3

Parameters:

ax (Axes, optional) – axe to plot the histogram and fits
bins (int or 'auto') – number of bins for the histogram. Default ‘auto’.
range (tuple of 2 floats) – perform the fit on the histogram between range[0] and range[1], default (-6, 3)
return_mean (bool) – if True, return the mean of the histogram, default False

Returns:

std – return the robust standard deviation of the SNR

Return type:

float[robust]

Notes

To recover the normality you must multiply the uncertainty array by the returned stddev value, if uncertainty is StdDevUncertainty.

>>> data = ContMap(np.random.normal(0, 1, size=(100, 100)), uncertainty=np.ones((100, 100)), mask=None)
>>> std = data.check_SNR()
>>> data.uncertainty.array *= std

check_SNR_simple(**kwargs)[source]¶

Perform normality test on SNR maps

This perform a simple mad absolute deviation on snr pixels

normalize_uncertainty(factor=None, method='check_SNR', **kwargs)[source]¶

Normalize the uncertainty

Parameters:

factor (float, optionnal) – the factor which normalize the snr distribution
method (str, (check_SNR_simple|check_SNR|check_SNR_pdf),) – the method to compute this factor if not provided, by default check_SNR

plot_PSD(to_plot=None, ax=None, bins=100, range=None, apod_size=None, **kwargs)[source]¶

Plot the power spectrum of the map.

Parameters:

to_plot (str, optionnal (None|signal|uncertainty|snr|residual)) – Choose which quantity to plot, by default None (signal)
ax (matplotlib.axes.Axes, optional) – Axe to plot the power spectrum
bins (int) – Number of bins for the histogram. Default 100.
range ((float, float), optional) – The lower and upper range of the bins. (see histogram)

Returns:

powspec_k (astropy.units.quantity.Quantity) – The value of the power spectrum
bin_edges (astropy.units.quantity.Quantity) – Return the bin edges (length(hist)+1).

get_square_slice(start=None)[source]¶

Retrieve the slice to get the maximum unmasked square.

Parameters:: start ((int, int)) – define the center (y, x) of the starting point (default: center of the image)
Returns:: islice – to be applied on the object itself on both dimension data[islice, islice]
Return type:: slice

Notes

Simply growth a square symetrically from the starting point

to_hdus(hdu_data='DATA', hdu_mask='MASK', hdu_uncertainty='UNCERT', hdu_hits='HITS', wcs_relax=True, key_uncertainty_type='UTYPE', fits_header_comment=None)[source]¶

Creates an HDUList object from a ContMap object.

Parameters:

hdu_data (str or None, optional) – If it is a string append this attribute to the HDUList as ImageHDU with the string as extension name. Default is 'DATA' for data, 'MASK' for mask, 'UNCERT' for uncertainty and HITS for hits.
hdu_mask (str or None, optional) – If it is a string append this attribute to the HDUList as ImageHDU with the string as extension name. Default is 'DATA' for data, 'MASK' for mask, 'UNCERT' for uncertainty and HITS for hits.
hdu_uncertainty (str or None, optional) – If it is a string append this attribute to the HDUList as ImageHDU with the string as extension name. Default is 'DATA' for data, 'MASK' for mask, 'UNCERT' for uncertainty and HITS for hits.
hdu_hits (str or None, optional) – If it is a string append this attribute to the HDUList as ImageHDU with the string as extension name. Default is 'DATA' for data, 'MASK' for mask, 'UNCERT' for uncertainty and HITS for hits.
wcs_relax (bool) – Value of the relax parameter to use in converting the WCS to a FITS header using to_header. The common CTYPE RA---TAN-SIP and DEC--TAN-SIP requires relax=True for the -SIP part of the CTYPE to be preserved.
key_uncertainty_type (str, optional) – The header key name for the class name of the uncertainty (if any) that is used to store the uncertainty type in the uncertainty hdu. Default is UTYPE.
fits_header_comment (dict, optional) – A dictionnary (key, comment) to update the fits header comments.

Raises:

ValueError –

If self.mask is set but not a numpy.ndarray. - If self.uncertainty is set but not a astropy uncertainty type. - If self.uncertainty is set but has another unit then self.data.

Returns:

hdulist

Return type:

HDUList