Image cutouts, or *postage stamps*, are useful for quick visual characterization of the detected transients or artefacts. We have a set of functions inside :mod:`stdpipe.cutouts` sub-module that ease these tasks.
They all work with the cutout structure returned by :func:`stdpipe.cutouts.get_cutout` that contains the stamps of requested size around the object from various image planes (science image, template, background map, mask, footprint map, ...), as well as some meta-information.
.. code-block:: python
# Create and display the cutouts from an image and its mask
for i,cand in enumerate(candidates):
# Create the cutout from image based on the candidate
Cutouts may be easily written to multi-extension FITS images, and restored from them later using the following functions:
.. autofunction:: stdpipe.cutouts.write_cutout
:noindex:
.. autofunction:: stdpipe.cutouts.load_cutout
:noindex:
Plotting the cutouts
--------------------
There is a dedicated plotting routine that helps quickly visualize the information contained in it, including its different image planes - :func:`stdpipe.plots.plot_cutout`
.. autofunction:: stdpipe.plots.plot_cutout
:noindex:
Cutout-level rejection of subtraction artefacts
-----------------------------------------------
The difference image often contains the characteristic artefacts ("dipoles") due to slight sub-pixel displacement of the object between the science image and the template (e.g. due to imperfect astrometric alignment, or due to large proper motion for the templates acquired long ago). Also, the intensity of the object may also be slightly different on the science image - e.g. due to slightly different photometric band - that leads to unshifted positive or negative differences. In principle, such cases may be automatically detected and - if appropriate - rejected by a simple adjustment procedure based solely on the information we already have inside typical cutout. The adjustment here means optimizing slight (sub-pixel) shifts between the image and (convolved) template, as well as slight scaling of the template, in order to minimize the residuals. We have a dedicated routine, :func:`stdpipe.cutouts.adjust_cutout`, that tries to perform such optimization, and may be used inside the pipelines like in the following example:
.. code-block:: python
for i,cand in enumerate(candidates):
print('Candidate %d with mag = %.2f +/- %.2f at x/y = %.1f %.1d and RA/Dec = %.4f %.4f' %
"""Create the cutout from one or more image planes based on the candidate object.
The object may be either a row from :class:`astropy.table.Table`, or a dictionary with at least
`x` and `y` keys present and containing the pixel coordinates of the objects in the image.
The cutout will be centered so that object center is inside its central pixel, and its size will
be :code:`2*ceil(radius) + 1` pixels.
:param image: The science image for `image` plane of the cutout
:param candidate: The candidate object that should at least contain `x` and `y` fields
:param radius: Cutout radius in pixels. Cutout will have a square shape with :code:`2*ceil(radius) + 1` width
:param mask: The mask image for `mask` plane of the cutout, optional
:param background: The background for `background` plane of the cutout, optional
:param diff: Difference image for `diff` plane of the cutout, optional
:param template: Template image for `template` plane of the cutout, optional
:param convolved: Convolved template image for `convolved` plane of the cutout, optional
:param err: Noise model image for `err` plane of the cutout, optional
:param footprint: Candidate footprint (boolean) image for `footprint` plane of the cutout, optional
:param header: The header for original image. It will be copied to `header` field of the cutout and modified accordingly to properly represent the shape and WCS of the cutout. Optional
:param wcs: WCS for the original image. Will be copied to `wcs` field of the cutout with appropriate adjustment of the center so that it properly represents the astrometric solution on the cutout. Takes precedence over `header` parameter in defining cutout WCS. Optional
:param time: Time (:class:`astropy.time.Time` or :class:`datetime.datetime` or a string representation compatible with them) of the original image acquisition, to be copied to `time` field of the cutout. Optional
:param filename: Filename of the original image, to be stored in `filename` field of the cutout. Optional
:param name: The object name, to be stored in the `name` field of the cutout. Optional
:returns: Cutout structure as described below.
Cutout is represented by a dictionary with at least the following fields:
- `image` - primary image plane, centered on the candidate position
- `mask`, `background`, `diff`, `template`, `convolved`, `err`, `footprint` - corresponding secondary image planes, if provided as parameters to the routine
- `header` - header of the original image modified to properly represent the cutout WCS, if provided as a parameter to the routine
- `wcs` - WCS solution for the original image, modified to properly represent the cutout WCS, if provided as a parameter to the routine
- `meta` - dictionary of additional metadata for the cutout. It will be populated with all fields of the candidate object, plus additionally:
- `time` - original image timestamp as :class:`astropy.time.Time` object, if provided
- `filename` - Original image filename, if provided
- `name` - object name. If not provided, and if the candidate has `ra` and `dec` fields set, the name will be automatically constructed in a JHHMMSS.SS+DDMMSS.S form
Try to apply some positional adjustment to the cutout in order to minimize the difference.
It will add one more image plane, 'adjusted', with the minimized difference between the original image and convolved template.
"""Try to apply some positional and scaling adjustment to the cutout in order to minimize the difference between the science image and the template.
It will add one more image plane, `adjusted`, with the optimized difference between the original image and convolved template.
If :code:`normalize=True`, the adjusted image will be normalized by the noise model (`err` plane of the cutout).
If `inner` is set to an integer value, only the central box with this size (in pixels) will be used for the optimization.
The optimization parameters are bounded by the `max_shift` and `max_scale` parameters.
If :code:`fit_bg=True`, the difference of image and convolved template background levels will be also fitted for as a free patameter. If not, for both planes the background level will be estimated using SExtractor *mode* algorithm (:code:`2.5*median - 1.5*mean` of unmasked regions) and subtracted prior to fitting using only shift and scale as free parameters.
:param cutout: Cutout structure as returned by :func:`stdpipe.cutouts.get_cutout`
:param max_shift: Upper bound for the possible positional adjustment in pixels. The shift will be limited to :code:`(-max_shift, max_shift)` range
:param max_scale: Upper bound for the possible scaling adjustment. The scale will be limited to :code:`(1/max_scale, max_scale)` range.
:param inner: If specified, only :code:`inner x inner` innermost pixels of the cutout will be used for the optimization
:param normalize: Whether to normalize the resulting `adjusted` cutout layer to the noise model (`err` layer)
:param fit_bg: Whether to include the difference in background levels between the science image and the template as a free parameter in the optimization
:param verbose: Whether to show verbose messages during the run of the function or not. May be either boolean, or a `print`-like function.
:returns: `True` if optimization succeeded, `False` if it failed.
On success, an additional plane `adjusted` with optimized difference between the science image and the template will be added to the cutout. Also, the following fields will be added to cutout `meta` dictionary:
If normalize=True, the adjusted image will be divided by the errors.
- `adjust_chi2_0` - chi-squared statistics before the optimization, computed inside the `inner` region if requested, or over the whole cutout otherwise
- `adjust_chi2` - chi-squared statistics after the optimization
- `adjust_df` - number of degrees of freedom
- `adjust_pval` - p-value corresponding to `adjust_chi2` and `adjust_df`
- `adjust_dx` - positional adjustment applied in `x` direction
- `adjust_dy` - positional adjustment applied in `y` direction
- `adjust_scale` - scaling adjustment applied
- `adjust_bg` - the value of science image background. Will be optimized if :code:`fit_bg=True`, or just estimated from the cutout prior to optimization
- `adjust_tbg` - the value of template background. Will be optimized if :code:`fit_bg=True`, or just estimated from the cutout prior to optimization
If inner is set to an integer value, only the central box with this size will be used for minimization.
"""
# Simple wrapper around print for logging in verbose mode only
"""Routine for displaying various image planes from the cutout structure returned by :func:`stdpipe.cutouts.get_cutout`.
The cutout planes are displayed in a single row, in the order defined by `planes` paremeters. Optionally, circular mark may be overlayed over the planes at the specified pixel position inside the cutout.
:param cutout: Cutout structure as returned by :func:`stdpipe.cutouts.get_cutout`
:param planes: List of names of cutout planes to show
:param fig: Matplotlib figure where to plot, optional
:param mark_x: `x` coordinate of the overlay mark in cutout coordinates, optional
:param mark_y: `y` coordinate of the overlay mark in cutout coordinates, optional
:param mark_r: Radius of the overlay mark in cutout coordinates in pixels, optional
:param title: The title to show above the cutouts, optional. If not provided, the title will be constructed from various pieces of cutout metadata, plus the contents of `additoonal_title` field, if provided
:param additional_title: Additional text to append to automatically generated title of the cutout figure.
:param \**kwargs: All additional parameters will be directly passed to :func:`stdpipe.plots.imshow` calls on individual images
