Frames, cubes and blinking

Some data is a sequence: the planes of a cube, the reads of a ramp, frames taken one after another, or two epochs of the same field. Pixel Clarity shows these one at a time in a single view, with a slider to step through them and the view kept as you go, so that changes stand out.

The examples use frames, eight FITS files in which an asteroid moves across part of the sample field, and epochs, two images of the field in which one star has brightened.

Cubes

A 3-dimensional image (a FITS cube, an ASDF or HDF5 array, or a NumPy array in the kernel) opens with a slider for its first axis. [ and ] step through the planes, and the space bar plays them. The stretch stays as it is from plane to plane, unless you unlock the limits.

import numpy as np
from astropy.io import fits
import pixel_clarity as pc

cube = np.stack([fits.getdata(f) for f in frames])
pc.show(cube, title="eight frames as a cube", scale="asinh", limits="99.5", height=400)

Stacks of files

Frames written one per file make a stack: the same slider and play, across files. active picks the frame shown first. Here, frame 3 of 8; drag the slider to watch the asteroid move:

pc.stack(frames, active=3, scale="asinh", limits="99.5", height=400)

A folder or a glob pattern works too, in name order: pc.stack("frames/*.fits").

Plotting a region through the frames

Draw a region (a circle on a star, say) and press g. A plot of the region’s statistics through every plane or frame opens below the image: the mean, median, sum, standard deviation, minimum or maximum, optionally divided by its median so curves of different regions compare. The x axis is the frame number, or a header keyword that is a number in every frame (an exposure time, say); for a cube, the plane number or its third WCS axis. Add more regions to compare them on the same plot. It’s a quick light curve, or a check that a ramp is linear.

Subtracting a frame

What changes from frame to frame often hides under what doesn’t: a detector’s bias pattern, a bright sky, the stars that stay put. subtract= shows each frame less a reference, made where the data is, so the readout, histogram, region statistics and plots are all of the difference. Here each frame less the first, opened on the sixth; only the asteroid is left:

pc.stack(frames, active=5, subtract="first", limits="zscale", cmap="RdBu_r", height=400)

The reference can be "first", "previous" (each frame less the one before), "ramp" (the first read of each ramp of a cube with four or more axes), a frame number (from 0), a (first, last) pair (the mean of those frames), or another image of the same size, such as a bias or a dark: pc.show(raw, subtract=bias). divide=True divides by it instead. In the viewer, the Δ button by the slider (or Shift+D) turns it on and off and picks the reference; holding \ shows the raw values, and the readout gives both frames’ values. A plot of a region through the frames is then of each frame less its reference: the scatter of a difference of two reads is the read noise, say.

Blinking

Blinking flips between images of one field to show what changed: a variable star, a supernova, a moving object, or an artifact on one image only. pc.blink shows the images one at a time, lined up by their sky coordinates, so images of different sizes, pixel scales and orientations still match while you zoom and pan.

pc.blink(epochs, names=["before", "after"], scale="asinh", limits="99.5")

[ and ] step between the images, and the space bar blinks them automatically, at the rate picked beside the play button. The readout, histogram and region statistics follow the image shown, and regions stay where they are on the sky, so a circle on the variable star measures it in each epoch.

Images without sky coordinates line up pixel for pixel. In the viewer, k turns blinking on or off in any mosaic, and blink=True does the same from Python:

pc.mosaic(["night1.fits", "night2.fits"], blink=True)   # the same as pc.blink([...])