HTML automatically generated with rman
Table of Contents
hispectrum - HI spectrum extraction and gridder
hispectrum [parameter=value]
hispectrum can perform any of the following functions:
1) List
the scan positions of a given HI survey dataset.
2) Extract a single spectrum
from the combined HI surveys. It does this by simply searching through
the databases until the distance to the requested position is less than
a required miniumum distance. It can also report the nearest or take an
average of the spectra within a search radius. See the mode= keyword below.
3) Combine, weigh and grid spectra from the combined HI surveys into a
velocity-position-position (VLB) datacube. This is generally a time- and
disk-consuming task, since a temporary list of relevant scans is written
to disk into a scratch file. Note that creating a datacube is done by gridding
in X and Y, while the Velocity axis is sampled (interpolated) from a predefined
set of values (normally regular, like the grid in X and Y).
The HI survey
databases live in either your current directory or the directory given
by the environment variable HI_DIR, and can be compressed (.Z or .gz) (see
hi(5NEMO)
).
The following parameters are recognized in any order
if the keyword is also given:
- hi=HI_id
- Input dataset id’s to combine {hh,pk,ar,bl,ww,kj,lb}.
Minimum match is applied. See also hi(5NEMO)
for survey id’s. [No default].
- lon=l
- Desired galactic longitude (l)
to find a single spectrum. Must be
in the range 0..360 degrees. If none supplied, all scan positions in the
database will be shown. This keyword is only active when cube gridding (see
cube= below) has not been selected.
- lat=b
- Desired galactic latitude (b)
to find a single spectrum. Must be in the range -90..90 degrees. See comments
above.
- vlsr=vmin:vmax:vstep
- Velocity value samples (km/s, in LSR units),
on which the output spectrum is interpolated. If none choosen, the original
raw data will be shown. When gridding a datacube (see cube= below), you
must specify these output velocities since different datasets are on different
velocity scales (note: the user should compensate for interpolation using
the bscale/bzero keywords below). When a requested velocity is outside the
range of the raw data, 0.0 is returned in the spectrum. Default: none.
- cube=fits_file
- Output cube, if requested. This file will be in standard fits(5NEMO)
format.
Default: none, a single spectrum or all scan positions are listed (see
lat= and lon= above).
- xgrid=xmin,xmax,step
- X-range (min and max) and step,
in the output cube (see also projection=). If xmin is negative, the galactic
center will be properly placed somewhere in the middle of the grid. Note
these values are the centers of the first and last pixel requested, not
the edges of the pixels. Default: none.
- ygrid=ymin,ymax,step
- Y-range (min
and max) and step, in the output cube Note these values are the centers
of the first and last pixel requested. Default: none.
- bscale=scale_factor(s)
- Scale factors applied to input spectra. See also bzero=. One value for each
input dataset much be given (see hi= above). Default: 1.0.
- bzero=offset(s)
- Offset applied to input spectra after scaling (bscale=). One for each input
dataset much be given (see hi= above). Default: 0.0.
- weight=factor(s)
- Relative
weight factor given to a dataset when they are combined. One for each input
dataset much be given (see hi= above). Default: 1.0
- ncell=
- Number of neighbor
cells to use in gridding. Default: 0 (only the scans in the cell of interest
are taken into account).
- sigma=
- Weighting distance (in degrees) with which
data from neighboring pixels are used to combine. Currently the weighing
function ... [Default: 1].
- dist=
- Minimum distance when to stop searching for
a single spectrum. Only used if you want to override the one in the database
(it is probably not a good idea to use this keyword and let the database
choose a value). Default: not used, the internal database value (see hi.h:
hi_defs[].dist_min) is used.
- mode=first|aver|near
- Modes in single spectrum
search. Possible modes are first, average, and nearest. Minimum match applies.
[Default: first].
- clip=
- Range of brightness temperatures which to include
or exclude from the gridding. Note clipping occurs AFTER the data has been
rescaled with the bzero,bscale parameters(see above). Default: none. ** not
implemented **
- outfreq=
- Status output frequency (debug=1). Searching the
databases for valid scans is very time consuming, and it’s useful to keep
the user informed. Use 0 if no status output requested. Default: 100.
- projection=
- Projection. Valid projections are cartesian, in which galactic longitude
(l)
and latitude (b) are gridded, npolar and spolar grid the north-polar
and south-polar cap resp. (xgrid= and ygrid= are also in degrees, and measure
the degrees away from the polar cap), cos and aitoff. For npolar the galactic
center is at the bottom, running clockwise, for spolar at the top, running
counter clockwise. [Default: cartesian.
- projpar=
- Optional parameters associated
with a projection. Currently only used for cos and aitoff where they are
used to override the central longitude (the default being the mean of xmin
and xmax).
- headline=comments
- Comments added to table/fits file. Default:
none.
The following example lists all scan positions (l, b, ra,
dec) for the (Heiles&Habing) Hat Creek high latitude survey. Note the output
is very large (134932 scans) and has been redirected to a file hh.pos:
% hispectrum in=hh > hh.pos
This second example extracts a spectrum in the form of an ascii table. You
can plot it using NEMO’s tabplot program, or go into a mongo-type program:
% hispectrum in=hh lon=45 lat=20 > hh.45.20.spectrum
The third example grids a portion of the sky into a VLB (velocity-longitude-latitude)
FITS cube:
% hispectrum in=hh,pk vlsr=-100:100:2 xgrid=200,300,2 ygrid=-30,30,2
\
cube=cube1.fits
Program is disk space intensive: a scratch file with all velocity
interpolated scans within the ROI (Region Of Interest: xgrid, ygrid) will
be created; this will need about 4 * nscans * nv bytes. In addition the
output datacube will be 4 * nv * nx * ny in size. nx, ny are the number
of pixels in X and Y, nv those requested in velocity. The factor of 4 from
the assumption that a C-float needs 4 bytes storage.
Velocity interpolation
is enforced, but when gridding and combining multiple dataset proper bscale
factor’s need to be used to get the correct answer. I.e. each dataset should
be multiplied with the ratio of the channel separation of original divided
by new (interpolated) cube.
hispectrum uses an internal fortran-to-c interface,
and is unlikely to work on Unix versions where this is very different from
the default BSD convention.
There is no check on available diskspace (scratch
spectra plus gridded output data cube) before the program starts. To estimate
the size of the scratch file is difficult.
Although gridding in X and Y
is forced to be regular, the one in V is not forced to be. The CDELT1 written
in the FITS file will be wrong in this case.
If the number of spectra per
pixel is larger than a compiler defined value (MAXSCAN) the program will
crash after all the hard work of sorting spectra has been done; this will
happen in the middle of writing the output FITS file.
Only scans with known
format (as defined in hi.h are understood. No provisions for some free format
has been made yet.
$HI_DIR/ directory, or colon separated searchpath, where the ascii
(raw) scans live.
$NEMO/usr/bima/hi source code
hiXXXXXX scratch file (see mktemp) with scans for the cube gridding
hi(5NEMO)
, fitsio(3NEMO)
, tabplot(3NEMO)
, himap(1NEMO)
, fitstohi(1NEMO)
Peter Teuben, William T. Reach (decode.f)
29-Jun-92 V0.0 Created: simple spectrum extraction PJT
1-jul-92 V0.1 cube gridder - using nearest cells PJT
6-jul-92 V0.2 added HI_DIR, deleted nx=, ny= PJT
8-nov-92 V0.3 10% faster code, but using 50% more memory PJT
17-sep-93 V0.6 added mode= for single spectrum search PJT
2-apr-94 V0.6a fixed bug in WW decoding PJT
6-apr-94 V0.7 sigma=0 now default; delete scratchfile PJT
29-sep-95 V0.8 added npolar/spolar projection options PJT
x-mar-96 V0.9 added cosb averagin, gridding options PJT
Table of Contents