Stacking cubes
LineStacker.image.stack() stacks data cubes, FITS files or CASA
images (both can be mixed), around the sources of a coordinate list.
import LineStacker
import LineStacker.image
coords = LineStacker.readCatalog('sources.csv')
stacked = LineStacker.image.stack(
coords,
fEm=1897420620253.1646, # rest frequency of the line (Hz)
stampsize=16, # pixels
N_chans=31, # channels of the stack
outfile='stack.fits')
peak, spectrum, cube, missing = stacked
It returns the central pixel at the central channel, the spectrum of the
central pixel, the whole stacked cube as an array ordered (x, y, Stokes,
channel), and the number of sources missing from each channel (their cube
does not cover it).
Centring the lines
spectralMethod says what the spectral value of each coordinate (its z)
is:
spectralMethod
|
spectral value |
also needed |
'z' (default)
|
redshift of the line |
fEm (frequency cubes) or lEm (wavelength cubes)
|
'obsSpec'
|
observed frequency, wavelength or velocity of the line |
|
'channel'
|
channel of the line (0-based) |
|
fEm, lEm and observed values are in the spectral unit of the first cube
(Hz for CASA images, Angstrom for MUSE cubes, for example). The cubes must
all have the same kind of spectral axis (all frequency, or all wavelength,
or all radio velocity); other units are converted (a cube in GHz stacks with
cubes in Hz). Cubes whose spectral axis runs the other way are read
backwards, so all spectra share the orientation of the first source’s
cube. Non-linear spectral axes (WAVE-LOG, FREQ-TAB…) are refused for
line stacks, whatever spectralMethod, since the stack could not be given a
correct spectral axis; regrid such cubes to a linear axis first. Cubes in
different spectral reference frames (SPECSYS: LSRK, TOPOCENT…), or with
SPECSYS in some cubes only, give a warning: LineStacker does not convert
frames, so regrid such cubes to one frame first (with CASA’s imregrid, or
tclean(outframe=...)).
Intensity units
The cubes’ pixel units (BUNIT) are compared before stacking. Units that
differ only by a scale are converted to the unit of the first cube that
has one (a cube in mJy/beam stacks with cubes in Jy/beam); recognised but
physically different units (K and Jy/beam, Jy/pixel and Jy/beam) are an
error. Cubes without BUNIT, or with a unit astropy cannot read, give a
warning and are stacked without conversion.
N_chans channels are stacked around the line centre (default: the number
of channels of the first cube). By default each source contributes its
nearest channel to each stack channel. With regridFromZ=True (needs
spectralMethod='z') every spectrum is resampled by linear interpolation
so that all sources share the same rest-frame channel width: the width of
the source at the highest redshift (regridMethod='scaleToMax', default) or
the lowest ('scaleToMin'). This corrects the narrowing of lines of the
same rest-frame width at higher redshift. A stack channel interpolated from
a blank channel is blank for that source; one that falls exactly on a
channel takes its value.
'scaleToMax' makes the channels of the other sources wider. A wider
channel is the mean of the cube channels it covers, so all the data are used
and each source’s line flux is kept. conserveFlux=False gives the value of
the spectrum at the channel’s centre instead, as in LineStacker 1.x and
2.0.0 (see Channels made wider).
Weights
With method='mean' each stamp is weighted, channel by channel, by the
weight of its coordinate times the weighting asked for:
weighting
|
weight multiplied by |
None (default)
|
1: only the coordinates’ weights |
'sigma2'
|
1/σ², σ being the standard deviation of the source’s stamp |
'sigma2F'
|
1/σ² computed channel by channel |
'sigma'
|
1/σ (as for 'sigma2') |
'1/A'
|
1/A, A being the line amplitude: the maximum of the central-pixel spectrum. Only for lines visible source by source |
'pb'
|
the square of the primary-beam response at the source (see below) |
σ is computed from the stamp pixels that are not blank and lie outside
maskradius pixels of the source; set maskradius so that the source does
not count as noise. For 'sigma' the default mask radius is twice the beam’s
major axis.
Sources (or channels) without valid noise pixels, or without a positive line
amplitude for '1/A', get weight 0, with a warning. Weights must be finite
and not negative.
method='median' takes, for each pixel and channel, the median over the
sources whose cube covers that channel. It ignores weights.
Primary-beam weighting
For primary-beam corrected images, whose noise grows as 1/PB away from the
pointing centre, weighting by PB² is inverse-variance weighting.
primarybeam gives the primary beam of each cube:
# primary-beam images (e.g. tclean's .pb), one per cube, read at each
# source's position and line channel
LineStacker.image.stack(coords, imagenames=cubes, fEm=fEm,
weighting='pb', primarybeam=pb_images)
LineStacker.image.stack(coords, imagenames=cubes, fEm=fEm, weighting='pb',
primarybeam={'a.image': 'a.pb', 'b.image': 'b.pb'})
# a Gaussian beam of 12 m dishes, FWHM 1.13 λ/D, centred on the reference
# pixel of each image
pb = LineStacker.image.GaussianPrimaryBeam(dish=12.)
LineStacker.image.stack(coords, imagenames=cubes, fEm=fEm,
weighting='pb', primarybeam=pb)
A list gives one primary beam per cube, in the order of imagenames; one
path is enough for a single cube. Any function f(dx, dy, nu) returning the
response at offsets dx, dy (radians, east and north on the sky, from the
position of the image reference pixel) and frequency nu (Hz) can be used
too.
For line stacks, a primary-beam cube is read at the channel of each
source’s line, so it needs the same kind of spectral axis as the science
cube (a single-plane primary beam can always be used). For continuum
stacks, the response is the mean of the primary-beam image’s non-blank
planes at the source.
Continuum
continuum=True stacks images instead of lines. Images without a spectral
axis, or with a single channel, are always stacked as continuum, and so are
coordinates without a spectral value (a catalogue without z). Cubes with a
spectral axis are collapsed over their channels in memory, with a warning:
collapse='sum' (default), 'mean' or 'median'; blank channels are
ignored. Only the collapsed images are kept in memory. The result is the
same list as for lines, with a single channel; the FITS output is 2D when
the inputs had no spectral axis.
Output
outfile names the stacked cube: a name ending in .fits (or .fits.gz)
is written as FITS, any other name (stack.image) as a CASA image, which
needs casatools. outfile=None writes nothing. With verbose on (default)
LineStacker prints the full path of the file it wrote.
The header of the stacked cube:
Pixels without valid data in any source are NaN (blank).
Sky axes are offsets from the stacked position, (0, 0) at the stamp
centre, with the pixel size and orientation of the first cube (a rotated
grid is written with a PC matrix).
Spectral axis: for spectralMethod='z', the rest frame: the line at
fEm (or lEm), channels of the mean rest-frame width, RESTFRQ (or
RESTWAV) set, and SPECSYS='SOURCE' if the cubes give a frame;
otherwise an axis centred on the mean observed value of the lines.
Beam: BMAJ, BMIN are the means of the input beams and BPA their
mean as an axis (179° and 1° give 0°): an approximation of the stack’s
beam when the input beams differ.
BUNIT of the first cube that has one (other cubes are converted to it,
see above); for a continuum stack of collapsed cubes it is per channel
(‘sum’ adds channels), as the COLLAPSE keyword says. A continuum stack
of cubes with non-linear spectral axes has no spectral axis.
NSTACK (number of sources) and a HISTORY line with the method.
LineStacker aligns sources on their centres but does not reproject: cubes
with a different pixel size, orientation, projection (SIN, TAN…),
celestial frame (ICRS, FK5…) or distortion terms from the first one give a
warning, and their stamps are cut on their own grid. Reproject such cubes to
a common grid first (CASA’s imregrid) to use the stacked image spatially.
Even the central-pixel spectrum is only comparable between cubes of similar
beams and pixel sampling.
Other outputs: returnWeights=True writes weightFile.csv (ra, dec, z and
the weight of each source, per channel if they differ), saveSubCubes=True
saves the stamps as a NumPy file (outSubCubes.npy, with their pixel
positions in outCoordsFile.txt), and plotIt=True plots the stacked
spectrum and the number of sources per channel.
Reading cubes
LineStacker.image.readCube() reads a FITS file or a CASA image as a
NumPy array ordered (x, y, Stokes, channel), x along RA and y along Dec, as
LineStacker uses it, for plots and checks:
cube = LineStacker.image.readCube('stack.fits')
spectrum = cube[8, 8, 0, :]
FITS cubes can have their data in any HDU (hdul='auto' takes the first
one with an image, hdul=1 for MUSE cubes for instance) and their axes in
any order. Cubes are read once and cached; a cube is read again when its
file changes (checking costs about 0.1 ms per CASA image each time a cube is
used; LineStacker.cache_check = False trusts the cache instead).
LineStacker.image.clear_cache() frees the memory.
Blank pixels (NaN in FITS, masked pixels of CASA images) stay NaN. Stacks
leave them out pixel by pixel: a stacked pixel is the mean (or median) of
the sources that have a valid value there, and NaN if none has, as are
stack channels that no source’s cube covers. Pixels that are exactly 0 are
data like any other.