This HTML automatically generated with rman for NEMO
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)
https://www.astro.uni-bonn.de/hisurvey/euhou/LABprofile/index.php
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
24-jul-2023 added URL to web simulator PJT
Table of Contents