User guide¶

Donuts computes the translational shift between two images of the same star field. It has been used with great success for multiple instruments including defocused observations.

To measure the shifts present in a series of images requires the definition of a reference frame. An image must be chosen from the series to be the reference. This is treated as 0,0 in the translational coordinate syst. Donuts then measures the shift of each subsequent image with respect to the reference. Reference images should be free from unwanted artefacts (satellite trails etc.)

Example usage¶

The example below shows typical usage of the donuts api:

>>> from donuts import Donuts
>>> reference_image_name = 'image1.fits'
>>> science_image_names = ['image2.fits', 'image2.fits']
>>> # Construct a donuts object
>>> d = Donuts(
...   refimage=reference_image_name,
...   image_ext=0,
...   overscan_width=20,
...   prescan_width=20,
...   border=64,
...   normalise=True,
...   exposure='EXPOSURE',
...   subtract_bkg=True,
...   ntiles=32)
>>> # for each image, compute the x/y translation required
... # to align the images onto the reference image
>>> for image in science_image_names:
...     shift_result = d.measure_shift(checkimage=image)
...     x = shift_result.x
...     y = shift_result.y
...     # Also check out shift_result.sky_background
...     print(x, y)

Further detail¶

More explanation of the Donuts constructor parameters are given below.

Defining the reference image¶

The following section describes some settings that can be applied to each image. It is important that the process applied to the reference image is applied to each science image to ensure that only the field position changes between images, hence the settings chosen during initialization are used for each subseqient image.

Image extension¶

The fits image extension to be used in the calculation is set with the image_ext parameter, which defaults to 0 (the primary HDU). If your image is in another extension, specify it here.

Prescan and overscan removal¶

If your images contain either prescan or overscan regions, set the width of each using the prescan_width and overscan_width values (both default to 0).

Recommended image corrections¶

Each correction below is optional but is recommended. If you find that an extra correction is required please submit an issue on our Github Issues page.

Border¶

Border pixels typically have a non-linear response and are recommended to be excluded. To remove the edge N pixels of the image before aligning, use the border parameter. This defaults to 64. Set this parameter to 0 if you wish to ignore the border exclusion.

Exposure time normalisation¶

Exposure time normalisation can be enabled through the normalise parameter, and the exposure time chosen with the exposure parameter, which defaults to EXPTIME. By default this feature is on. This allows for varying exposure times without the need for separate analysis.

Background subtraction¶

By design, Donuts will lock onto the most dominant ‘feature’ in a series of images. Under normal circumstances this will be the forrest of stellar profiles in the collapsed image projections. However, under new moon conditions for example, a strong vignetting pattern might be the dominant feature and will result in poor performance. Subtracting the sky background fixes this. The sky background is calculated using the median pixel value in a coarse grid ntiles by ntiles on each image. The median-sampled coarse grid is then interpolated and resampled back to the resolution of the data array and subtracted from each image. This removes any strong gradients or vignetting that may dominate the shift calculation.

Summary of object settings¶

A summary of the object’s settings can be seen using:

>>> d.print_summary()

Computing per-image offsets¶

With a Donuts object, the x/y translation required to align the image into the reference image is given by the measure_shift() method, which returns an Image object. e.g.:

>>> shift_result = d.measure_shift(checkimage='image.fits')
>>> x, y = shift_result.x, shift_result.y

x and y are returned in pixel units.

Looking at the computation intermediate products¶

The Image object returned by measure_shift() contains some products of the image normalisation procedure. Products available are:

raw_region: the image pixels used, contained in the trimmed region of the chip
sky_background: the computed sky background in raw_region
backsub_region: the sky-subtracted region used for image alignment
proj_x/proj_y: the 1-D image projection arrays calculated from backsub_region

Navigation