stdpipe.subtraction module

stdpipe.subtraction.run_hotpants(image, template, mask=None, template_mask=None, err=None, template_err=None, extra=None, image_fwhm=None, template_fwhm=None, image_gain=None, template_gain=1000, rel_r=3, rel_rss=4, nx=1, ny=None, obj=None, get_convolved=False, get_scaled=False, get_noise=False, get_kernel=False, get_header=False, _tmpdir=None, _workdir=None, _exe=None, verbose=False)[source]

Wrapper for running HOTPANTS to subtract a template from science image.

To better understand the logic and available subtraction options you may check HOTPANTS documentation at https://github.com/acbecker/hotpants

The routine tries to be clever and select reasonable defaults for running HOTPANTS, but you may always directly specify any HOTPANTS option manually through extra parameter.

The noise model for both science and template images may optionally be provided as an external parameters (err and template_err). Moreover, if these parameters are set to True, the routine will try to build noise models itself. To do so, it will estimate the image background and background RMS. Then, this background RMS map is used as a primary component of the noise map. On top of that, the contribution of the sources is added by subtracting the background from original image, smoothing it a bit to mitigate pixel-level noise a bit, and then converting everything above zero to corresponding Poissonian noise contribution by dividing with gain value and taking a square root.

rel_r and rel_rss define the scaling of corresponding HOTPANTS parameters (which are the convolution kernel half width and half-width of the sub-stamps used for kernel fitting) with image FWHM.

The routine also uses “officially recommedned” logic for defining HOTPANTS ng parameter, that is to set it to [3, 6, 0.5*sigma_match, 4, 1.0*sigma_match, 2, 2.0*sigma_match] where sigma_match = np.sqrt(image_fwhm**2 - template_fwhm**2) / 2.35. This approach assumes that image_fwhm > template_fwhm, and of course needs image_fwhm and template_fwhm to be provided.

Parameters:
imagenumpy.ndarray

Input science image as a NumPy array.

templatenumpy.ndarray

Input template image, should have the same shape as the science image.

masknumpy.ndarray, optional

Science image mask as a boolean array (True values will be masked).

template_masknumpy.ndarray, optional

Template image mask as a boolean array (True values will be masked).

errnumpy.ndarray or bool, optional

Science image error map (expected RMS of every pixel). If set to True, the code will try to build the noise map directly from the image and image_gain parameter.

template_errnumpy.ndarray or bool, optional

Template image error map. If set to True, the code will try to build the noise map directly from the template and template_gain parameter.

extradict, optional

Extra parameters to be passed to HOTPANTS executable, with parameter names as keys.

image_fwhmfloat, optional

FWHM of science image in pixels.

template_fwhmfloat, optional

FWHM of template image in pixels.

image_gainfloat, optional

Gain of science image.

template_gainfloat, optional

Gain of template image.

rel_rfloat, optional

If specified, HOTPANTS r parameters will be set to image_fwhm*rel_r.

rel_rssfloat, optional

If specified, HOTPANTS rss parameters will be set to image_fwhm*rel_rss.

nxint, optional

Number of image sub-regions in x direction.

nyint, optional

Number of image sub-regions in y direction.

objastropy.table.Table, optional

List of objects detected on science image. If provided, it will be used to better place the sub-stamps used to derive the convolution kernel.

get_convolvedbool, optional

Whether to also return the convolved template image.

get_scaledbool, optional

Whether to also return noise-normalized difference image.

get_noisebool, optional

Whether to also return difference image noise model.

get_kernelbool, optional

Whether to also return convolution kernel used in the subtraction.

get_headerbool, optional

Whether to also return the FITS header from HOTPANTS output file.

_workdirstr, optional

If specified, all temporary files will be created in this directory, and will be kept intact after running HOTPANTS. May be used for debugging.

_tmpdirstr, optional

If specified, all temporary files will be created in a dedicated directory (that will be deleted after running the executable) inside this path.

_exestr, optional

Full path to HOTPANTS executable. If not provided, the code tries to locate it automatically in your PATH.

verbosebool or callable, optional

Whether to show verbose messages during the run of the function or not.

Returns:
numpy.ndarray or list

The difference image and, optionally, other kinds of images as requested by the get_* options above.

stdpipe.subtraction.run_zogy(image, template, mask=None, template_mask=None, err=None, template_err=None, image_psf=None, template_psf=None, image_gain=None, template_gain=None, image_fwhm=None, template_fwhm=None, scale=None, psf_clean=0, dx=0.25, dy=0.25, nx=1, ny=None, overlap=50, fit_scale=True, fit_shift=True, good_regions=None, image_obj=None, template_obj=None, get_psf=False, get_Fpsf=False, nthreads=0, verbose=False, **kwargs)[source]

Image subtraction using Zackay–Ofek–Gal-Yam (ZOGY) algorithm, as described in http://dx.doi.org/10.3847/0004-637X/830/1/27

The science and template images should be already aligned astrometrically, and roughly matched photometrically, i.e. have similar flux scale. There is an option to fit for the small difference in flux scales (fit_scale), which is enabled by default. Also, optionally (if fit_shift is set) it may fit for a small systematic positional error (sub-pixel shift) of the template.

Required inputs are science and template images (plus optionally their masks), their noise maps and PSFs, as well as their relative flux scale. If noise maps are not provided, they will be constructed from the input images using estimated background noise and gain values for source contributions. If PSFs are not specified, they will be also estimated from the images using stdpipe.psf.run_psfex(). Flux normalization for PSF estimation also requires FWHMs of the images, which may either be specified directly, or estimated from the images too.

Relative template image flux scaling may either be provided as scale argument, or it may be estimated from the lists of objects detected in both images. These may either be provided directly (image_obj and template_obj), or derived during PSF estimation. These objects will also be used for restricting the scale/shift fitting to their vicinities only. Alternatively, the map of good regions may be directly provided as good_regions argument.

The image will be optionally split into given number (nx`x`ny) of sub-images, subtracted independently, and then the results will be stitched back. Sub-images will overlap by overlap pixels.

Parameters:
imagenumpy.ndarray

Input science image as a NumPy array.

templatenumpy.ndarray

Input template image, should have the same shape as the science image.

masknumpy.ndarray, optional

Science image mask as a boolean array (True values will be masked).

template_masknumpy.ndarray, optional

Template image mask as a boolean array (True values will be masked).

errnumpy.ndarray, optional

Science image noise map (expected RMS of every pixel). If not set, the code will try to build the noise map directly from the image and image_gain parameter.

template_errnumpy.ndarray, optional

Template image noise map. If not set, the code will try to build the noise map directly from the template and template_gain parameter.

image_gainfloat, optional

Gain of science image, to be used for construction of the noise map.

template_gainfloat, optional

Gain of template image, to be used for construction of the noise map.

image_psfdict, optional

PSF for science image. If not provided, will be estimated by stdpipe.psf.run_psfex().

template_psfdict, optional

PSF for template image. If not provided, will be estimated by stdpipe.psf.run_psfex().

image_fwhmfloat, optional

FWHM of science image, to be used for estimated PSF normalization.

template_fwhmfloat, optional

FWHM of template image, to be used for estimated PSF normalization.

scalefloat, optional

Template image flux scale relative to science image.

psf_cleanfloat, optional

If non-zero, will clean the PSF regions with relative values less than this factor.

dxfloat, optional

Astrometric uncertainty (sigma) in x coordinate.

dyfloat, optional

Astrometric uncertainty (sigma) in y coordinate.

nxint, optional

Number of sub-images in x direction.

nyint, optional

Number of sub-images in y direction.

overlapint, optional

If set, defines how much sub-images will overlap, in pixels.

fit_scalebool, optional

If set, will fit for the difference in flux scales between template and science images.

fit_shiftbool, optional

If set, will also fit for the sub-pixel shift between template and science images.

good_regionsnumpy.ndarray, optional

If set, this boolean map will be used to restrict scale/shift fitting to only these regions.

image_objastropy.table.Table, optional

List of objects detected in science image. If provided, they will be used for placing good regions.

template_objastropy.table.Table, optional

List of objects detected in template image. If provided, they will be used for deriving template flux scale.

get_psfbool, optional

If set, will also return the PSF of the difference image.

get_Fpsfbool, optional

If set, will also return the optimal PSF photometry image and its error.

nthreadsint, optional

Set the number of threads to use for FFTW routines (0 for auto).

verbosebool or callable, optional

Whether to show verbose messages during the run of the function or not.

**kwargs

Extra parameters to be passed to stdpipe.psf.run_psfex() for PSF estimation.

Returns:
list

The list of the difference image and other subtraction results:

  • D: Subtracted image

  • S_corr: Corrected subtracted image

  • P_D: PSF of subtracted image, if get_psf=True

  • Fpsf: optimal PSF photometry image, if get_Fpsf=True

  • Fpsf_err: optimal PSF photometry error image, if get_Fpsf=True

stdpipe.subtraction.run_sfft(image, template, mask=None, template_mask=None, err=None, template_err=None, image_gain=None, template_gain=None, kernel_shape=(7, 7), kernel_poly_order=2, bg_poly_order=2, flux_poly_order=1, flux_penalty=1000.0, ridge=1e-06, sigma_clip=3.0, max_iter=5, obj=None, obj_size=None, get_convolved=False, get_scaled=False, get_noise=False, get_kernel=False, verbose=False)[source]

Image subtraction using SFFT with spatially varying kernel.

Wrapper around stdpipe.sfft.solve() that handles noise model construction, difference image noise propagation, and follows the same interface conventions as run_hotpants() and run_zogy().

The noise model for both science and template images may be provided directly (as arrays), or built automatically from the images using background estimation and gain values (same approach as HOTPANTS). If err or template_err is set to True, the routine builds a noise map from the image using SEP background estimation and the corresponding gain parameter.

Parameters:
imagenumpy.ndarray

Input science image as a NumPy array.

templatenumpy.ndarray

Input template image, same shape as science image.

masknumpy.ndarray, optional

Science image mask (True = bad).

template_masknumpy.ndarray, optional

Template image mask (True = bad).

errnumpy.ndarray or bool, optional

Science image noise map (per-pixel RMS). If True, built from the image and image_gain.

template_errnumpy.ndarray or bool, optional

Template image noise map. If True, built from the template and template_gain.

image_gainfloat, optional

Gain of science image in e-/ADU.

template_gainfloat, optional

Gain of template image in e-/ADU.

kernel_shapetuple of int, optional

(ky, kx) kernel size, must be odd. Default (7, 7).

kernel_poly_orderint, optional

Polynomial order for kernel spatial variation. Default 2.

bg_poly_orderint, optional

Polynomial order for differential background. Default 2.

flux_poly_orderint, optional

Polynomial order for kernel-sum (flux scale) constraint. Default 1.

flux_penaltyfloat, optional

Penalty weight for kernel-sum constraint. Default 1e3.

ridgefloat, optional

Tikhonov regularization. Default 1e-6.

sigma_clipfloat, optional

Sigma threshold for outlier rejection. Default 3.0.

max_iterint, optional

Maximum sigma-clipping iterations. Default 5.

objastropy.table.Table, optional

List of detected objects with x, y columns. If provided, kernel fitting is restricted to rectangular regions around these objects, analogous to HOTPANTS stamp placement. This concentrates the fit on high-S/N regions and can improve kernel quality.

obj_sizeint, optional

Half-size in pixels of the fitting region around each object. If None (default), derived from the median fwhm column of obj (3 × median(fwhm)), or 15 pixels if fwhm is not available.

get_convolvedbool, optional

Whether to also return the convolved template.

get_scaledbool, optional

Whether to also return noise-normalized difference.

get_noisebool, optional

Whether to also return the difference image noise map.

get_kernelbool, optional

Whether to also return the SFFTResult object containing kernel coefficients and fit metadata.

verbosebool or callable, optional

Whether to show verbose messages.

Returns:
numpy.ndarray or list

The difference image, or a list [diff, ...] if any get_* option is set.