Regrid ACSIS spectra into a data cube
Optionally, the output cube can be split up into several separate NDFs, each containing a spatial tile extracted from the full cube (see parameter JSATILES and TILEDIMS). These tiles abut exactly in pixel co-ordinates and can be combined (for example) using KAPPA:PASTE.
In addition, there is an option to divide the output up into separate polarisation angle bins (see parameter POLBINSIZE). If this option is selected, each tile is split up into several output NDFs (all within the same container file), each one containing the input data relating to a particular range of polarisation angle.
The full output cube can be either a regularly gridded tangent-plane projection of the sky, or a sparse array (see parameter SPARSE). If a tangent plane projection is selected, the parameters of the projection from sky to pixel grid co-ordinates can be specified using parameters CROTA, PIXSIZE, REFLAT, REFLON. Alternatively, parameter AUTOGRID can be set true, in which case projection parameters are determined automatically in a manner that favours projections that place samples centrally within pixels. Alternatively, a reference NDF can be supplied (see parameter REF), in which case the same pixel grid will be used for the output cube.
Variance values in the output can be calculated either on the basis of the spread of input dat avalues contributing to each output pixel, or on the basis of the system-noise temperature values supplied in the input NDFs (see parameter GENVAR).
"
AND"
scheme uses all input data
(thus reducing the noise in the output) and also minimises the number of bad pixels in the
output. However, the memory requirements of the "
AND"
scheme can be excessive. For
this reason, two other schemes, "
FIRST"
and "
OR"
, are provided which greatly reduce
the memory requirements, at the expense either of introducing more bad pixels into the
output ("
OR"
) or producing higher output noise levels ("
FIRST"
). The value supplied for
this parameter is used only if SPREAD is set to "
Nearest"
(otherwise "
AND"
is always
used):
"
FIRST"
– The bad-pixel mask in each output spectrum is inherited from the first input spectrum
that contributes to the output spectrum. Any subsequent input spectra that contribute to
the same output spectrum but which have a different bad-pixel mask are ignored. So an
output pixel will be bad if and only if the corresponding pixel in the first input NDF that
contributes to it is bad. Since this scheme ignores entire input spectra if they do not conform to
the expected bad-pixel mask, the noise in the output can be higher than using the other
schemes. However, this scheme has the benefit of using much less memory than the "
AND"
scheme, and will in general produce fewer bad pixels in the output than the "
OR"
scheme.
"
OR"
– The bad pixel mask in each output spectrum is the union (logical OR) of the bad pixel masks
for all input spectra that contribute to the output spectrum. So an output pixel will be bad if any of the
input pixels that contribute to it are bad. This scheme will in general produce more bad
output pixels than the "
FIRST"
scheme, but the non-bad output pixels will have a lower
noise because, unlike "
FIRST"
, all the contributing input data are coadded to produce the
good output pixels. Like "
FIRST"
, this scheme uses much less memory than "
AND"
.
"
AND"
– The bad pixel mask for each output spectrum is the intersection (logical AND) of the bad
pixel masks for all input spectra that contribute to the output spectrum. So an output pixel will be bad
only if all the input pixels that contribute to it are bad. This scheme will produce fewer bad output
pixels and will also give lower output noise levels than "
FIRST"
or "
OR"
, but at the expense of much
greater memory requirements.
["
OR"
]
A Domain name such as SKY, AXIS, PIXEL, etc.
An integer value giving the index of the required Frame.
An IRAS90 Sky Co-ordinate System (SCS) values such as EQUAT(J2000) (see SUN/163).
If a null (!) value is supplied, the positions will be stored in the current Frame of the output NDF. [!]
"
1996.8"
for example). Such values are interpreted as a Besselian epoch if less than
1984.0 and as a Julian epoch otherwise. "
Spread"
– the output Variance values are based on the spread of input data values contributing to
each output pixel. This option is not available if parameter SPARSE is set TRUE. If the BADMASK
value is "
OR"
or "
FIRST"
, then a single variance value will be produced for each output spectrum
(i.e. all channels in an output spectrum will have the same variance value). If BADMASK is "
AND"
,
then an independent variance value will be calculated for each channel in each output
spectrum.
"
Tsys"
– the output Variance values are based on the system noise temperature values supplied in the
input NDFs. Since each input spectrum is characterised by a single Tsys value, each output spectrum
will have a constant Variance value (i.e. all channels in an output spectrum will have the same
variance value).
"
None"
– no output Variance values are created.
["
Tsys"
]
"
OUT"
. If "
JSATILES"
is TRUE, the "
REF"
parameter is ignored. [FALSE] "
JSATILES"
is set TRUE, the zero-based indices of the created JSA tiles will be written to this
output parameter. The number of such indices is given the "
NTILE"
parameter "
OUT"
will be used as the root name to
which other strings are appended to create the name of each output NDF. PARAMS( 1 ) is required by all the above schemes. It is used to specify how many pixels on either side of the output position (that is, the output position corresponding to the centre of the input pixel) are to receive contributions from the input pixel. Typically, a value of 2 is appropriate and the minimum allowed value is 1 (i.e. one pixel on each side). A value of zero or fewer indicates that a suitable number of pixels should be calculated automatically. [0]
PARAMS( 2 ) is required only by the SombCos, Gauss, SincSinc, SincCos, and SincGauss schemes. For the SombCos, SincSinc, and SincCos schemes, it specifies the number of pixels at which the envelope of the function goes to zero. The minimum value is 1.0, and the run-time default value is 2.0. For the Gauss and SincGauss scheme, it specifies the full-width at half-maximum (FWHM) of the Gaussian envelope. The minimum value is 0.1, and the run-time default is 1.0. On astronomical images and spectra, good results are often obtained by approximately matching the FWHM of the envelope function, given by PARAMS(2), to the point-spread function of the input data. []
"
#"
in column one. These are comment lines, but if any comment line
has the form "
# SYSTEM=AZEL"
or "
# SYSTEM=TRACKING"
then it determines the
system in which the pointing correction are specified (SYSTEM defaults to AZEL). The last
comment line should be a space-separated list of column names, including "
TAI"
, "
DLON"
and "
DLAT"
. Each remaining line should contain numerical values for each column,
separated by white space. The TAI column should contain the TAI time given as an MJD. The
DLON and DLAT columns should give arc-distance offsets parallel to the longitude and
latitude axes, in arc-seconds. The TAI values should be monotonic increasing with row
number. The longitude and latitude axes are either AZEL or TRACKING as determined
by the SYSTEM value in the header comments. Blank lines are ignored. The DLON and
DLAT values are added onto the SMU jiggle positions stored in the JCMTSTATE extension
of the input NDFs. DLON and DLAT values for non-tabulated times are determined by
interpolation.
If you need to apply two sets of pointing corrections, one in TRACKING and one in AZEL, you can include two tables (one for each system) in a single text file. Both tables should use the format described above. The two tables must be separated by a line containing two or more minus signs with no leading spaces. [!]
"
analyser angle"
is the anti-clockwise angle from
celestial north (in the system chosen by parameter SYSTEM) to the axis of the "
effective
analyser"
- a rotating analyser that would have the same effect as the combination of fixed
analyser and half-wave plate actually present in the polarimeter. The supplied value for
POLBINSIZE will be modified if required to ensure that a whole number of bins is used to cover
the complete range of analyser angles (0 to 360 degrees). A separate output cube will be
created for each bin that is not empty, and each output NDF will contain a POLPACK
extension suitable for use with the POLPACK:POLCAL command. These NDFs are all stored
in a single HDS container file (one per tile) with the name specified by parameter OUT.
Within this container file, each cube will be held in a component with name of the form "
P<N>"
appended to the end, where "
<N>"
is an integer bin index. The largest value of N is written to output parameter NPOLBIN. If a null value
(!) is supplied, then a single output NDF (without POLPACK extension) is created for each tile,
containing all input data. "
JSA"
. If an NDF
is supplied, the output grid will be aligned with the supplied reference NDF. The NDF
need not be three-dimensional. For instance, a two-dimensional image can be supplied in
which case the spatial axes of the output cube will be aligned with the reference image
and the spectral axis will be inherited form the first input NDF. If "
JSA"
is supplied, the
JSA all-sky pixel grid will be used (note, the cube will still be created as a single NDF - if
multiple NDFs, one for each JSA tile, are required, the "
JSATILES"
parameter should beset
TRUE instead of using the "
REF"
parameter). If a null (!) value is supplied then the output
grid is determined by parameters AUTOGRID, REFLON, REFLAT, etc. [!] "
I"
is stored at pixel position (I,1) in the output cube (pixel Axis 2
will always have the value 1 – that is, Axis 2 is a degenerate axis that spans only a single
pixel).
In both cases, the third pixel axis in the output cube corresponds to spectral position (frequency, velocity, etc).
Whatever the setting of SPARSE, the output NDF’
s WCS component can be used to transform pixel
position into the corresponding (celestial longitude, celestial latitude, spectral position) values.
However, if SPARSE is TRUE, then the inverse transformation (i.e. from (long,lat,spec) to pixel
co-ordinates) will not be defined. This means, for instance, that if a sparse array is displayed as a
two-dimensional image, then it will not be possible to annotate the axes with WCS values. Also, whilst
KAPPA:WCSMOSAIC will succesfully align the data in a sparse array with a regularly gridded cube,
KAPPA:WCSALIGN will not, since WCSALIGN needs the inverse transformation to be
defined.
The dynamic default value for SPARSE depends on the value supplied for parameter AUTOGRID. If AUTOGRID is set FALSE, then SPARSE defaults to FALSE. If AUTOGRID is set TRUE, then the default for SPARSE will be TRUE if the algorithm described under the AUTOGRID parameter fails to find useful default grid parameters. If the AUTOGRID algorithm succeeds, the default for SPARSE will be FALSE. []
"
:"
) for the
parameter value. This will display a description of the required spectral co-ordinate system,
and then re-prompt for a new parameter value. The dynamic default is determined by
the SPECUNION parameter. [] "
Nearest"
is always assumed. SPREAD can take the following
values:
"
Linear"
– The input pixel value is divided bi-linearly between the four nearest output pixels.
Produces smoother output NDFs than the nearest-neighbour scheme.
"
Nearest"
– The input pixel value is assigned completely to the single nearest output pixel. This
scheme is much faster than any of the others.
"
Sinc"
– Uses the sinc(pi∗x)
kernel, where x is the pixel offset from the interpolation point (resampling) or transformed input pixel
centre (rebinning), and sinc(z)=sin(z)/z. Use of this scheme is not recommended.
"
SincSinc"
– Uses the sinc(pi∗x)sinc(k∗pi∗x)
kernel. A valuable general-purpose scheme, intermediate in its visual effect on NDFs between the
bi-linear and nearest-neighbour schemes.
"
SincCos"
– Uses the sinc(pi∗x)cos(k∗pi∗x)
kernel. Gives similar results to the "
Sincsinc"
scheme.
"
SincGauss"
– Uses the sinc(pi∗x)exp(-k∗x∗x)
kernel. Good results can be obtained by matching the FWHM of the envelope function to the
point-spread function of the input data (see parameter PARAMS).
"
Somb"
– Uses the somb(pi∗x)
kernel, where x is the pixel offset from the transformed input pixel centre, and
somb(z)=2∗J1(z)/z
(J1 is the first-order Bessel function of the first kind). This scheme is similar to the "
Sinc"
scheme.
"
SombCos"
– Uses the somb(pi∗x)cos(k∗pi∗x)
kernel. This scheme is similar to the "
SincCos"
scheme.
"
Gauss"
– Uses the exp(-k∗x∗x)
kernel. The FWHM of the Gaussian is given by parameter PARAMS(2), and the point at which to
truncate the Gaussian to zero is given by parameter PARAMS(1).
For further details of these schemes, see the descriptions of routine AST_REBINx in SUN/211. ["
Nearest"
]
"
TRACKING"
, in which case the system used will be which ever system was used as the tracking
system during in the observation. The value supplied for the CROTA parameter should refer to the
co-ordinate system specified by this parameter.
The choice of system also determines if the telescope is considered to be tracking a moving object such as a planet or asteroid. If system is GAPPT or AZEL, then each time slice in the input data will be shifted in order to put the base telescope position (given by TCS_AZ_BC1/2 in the JCMTSTATE extension of the input NDF) at the same pixel position that it had for the first time slice. For any other system, no such shifts are applied, even if the base telescope position is changing through the observation. [TRACKING]
"
BORDER"
(see KAPPA:SHOWQUAL). [0] "
JSATILES"
is set
TRUE.
For large data sets, it may sometimes be beneficial to break the output array up into a number of
smaller rectangular tiles, each created separately and stored in a separate output NDF. This can be
accomplished by supplying non-null values for the TILEDIMS parameter. If supplied, these values
give the nominal spatial size of each output tile, in pixels. Edge tiles may be thinner if the
TRIMTILES parameter is set TRUE. In order to avoid creating very thin tiles around the
edges, the actual tile size used for the edge tiles may be up to 10 % larger than the supplied
value. This creation of "
fat"
edge tiles may be prevented by supplying a negative value
for the tile size, in which case edge tiles will never be wider than the supplied absolute
value.
If only one value is supplied, the supplied value is duplicated to create square tiles.
Tiles are created in a raster fashion, from bottom left to top right of the spatial
extent. The NDF file name specified by "
out"
is modified for each tile by appending "
_<N>"
to the end of it, where <N>
is the integer tile index (starting at 1). The number of tiles used to cover the entire output cube is
written to output parameter NTILES. The tiles all share the same projection and so can be
simply pasted together in pixel co-ordinates to reconstruct the full size output array. The
tiles are centred so that the reference position (given by REFLON and REFLAT) falls at
the centre of a tile. If a tile receives no input data, then no corresponding output NDF
is created, but the tile is still included in the tile numbering scheme. If a null (!) value is
supplied for TILEDIMS, then the entire output array is created as a single tile and
stored in a single output NDF with the name given by parameter OUT (without any "
_<N>"
appendage). [!]
A FITS extension is added to the output NDF containing any keywords that are common to all input NDFs. To be included in the output FITS extension, a FITS keyword must be present in the NDF extension of every input NDF, and it must have the same value in all input NDFs. In addition, certain headers that relate to start and end events are propagated from the oldest and newest files respectively.
The output NDF will contain an extension named "
SMURF"
containing two NDFs named "
EXP_TIME"
and "
EFF_TIME"
. In addition, if parameter SPREAD is set to "
Nearest"
, a third NDF
called "
TSYS"
will be created. Each of these NDFs is 2-dimensional, with the same pixel bounds as
the spatial axes of the main output NDF, so that a pixel in one of these NDFs corresponds to a
spectrum in the main output NDF. EXP_TIME holds the sum of the total exposure times (Ton
+ Toff)
for the input spectra that contributed to each output spectrum. EFF_TIME holds the sum of the
effective integration times (Teff) for the input spectra that contributed to each output spectrum, scaled
up by a factor of 4 in order to normalise it to the reported exposure times in EXP_TIME. TSYS holds
the effective system temperature for each output spectrum. The TSYS array is not created if GENVAR
is "
None"
or if SPREAD is not "
Nearest"
.
FITS keywords EXP_TIME, EFF_TIME and MEDTSYS are added to the output FITS extension. The EXP_TIME and EFF_TIME keywords hold the median values of the EXP_TIME and EFF_TIME arrays (stored in the SMURF extension of the output NDF). The MEDTSYS keyword holds the median value of the TSYS array (also stored in the SMURF extension of the output NDF). If any of these values cannot be calculated for any reason, the corresponding FITS keyword is assigned a blank value.
FITS keywords NUMTILES and TILENUM are added to the output FITS header. These are the number of tiles used to hold the output data, and the index of the NDF containing the header, in the range 1 to NUMTILES. See parameter TILEDIMS.