pixsample samples data at the sky position represented by
each row from an all-sky map contained in a HEALPix-format pixel data file.
Such files are actually tables (usually in FITS format) in which the row
number corresponds to a HEALPix pixel index, and the pixel values are cell
contents; one or more columns may be present containing values for one or
more all-sky maps. The result of this command is to add a column to the
input table representing the pixel data at the position of each input row
for each of the data columns in the HEALPix table.
This command does not attempt to convert between coordinate
systems except as instructed, so it is important to know what coordinate
system the HEALPix file is in, and ensure that the coordinates supplied from
the input table match this. You may need to examine the documentation or
headers of the HEALPix file in question to find out. See the Examples
section for some examples.
There is a choice of how the sampling is done; the simplest way is
just to use the value of the pixel covering the indicated position. An
alternative is to average over a disc of given radius (perhaps a function of
the input row). Other options (e.g. max/min) could easily be added.
Although HEALPix is not a common format for storing image data in
general, it is used for storing a number of important all-sky data sets such
as the WMAP results and Schlegel dust maps. The NASA LAMBDA (Legacy Archive
for Microwave Background Data Analysis) archive has a number of maps in a
suitable format, including foreground data like predicted reddening as well
as CMB maps.
Note at present this command only supports all-sky, not partial,
HEALPix maps. Partial map support may be added at some point in the future
if there is demand.
- in=<table>
The location of the input table. This may take one of the
following forms:
- A filename.
- A URL.
- The special value "-", meaning standard input. In this
case the input format must be given explicitly using the ifmt
parameter. Note that not all formats can be streamed in this way.
- A scheme specification of the form
:<scheme-name>:<scheme-args>.
- A system command line with either a "<" character at
the start, or a "|" character at the end
("<syscmd" or "syscmd|"). This
executes the given pipeline and reads from its standard output. This will
probably only work on unix-like systems.
In any case, compressed data in one of the supported compression formats (gzip,
Unix compress or bzip2) will be decompressed transparently.
- ifmt=<in-format>
Specifies the format of the input table as specified by
parameter
in. The known formats are listed in SUN/256. This flag can be
used if you know what format your table is in. If it has the special value
(auto) (the default), then an attempt will be made to detect the format
of the table automatically. This cannot always be done correctly however, in
which case the program will exit with an error explaining which formats were
attempted. This parameter is ignored for scheme-specified tables.
- icmd=<cmds>
Specifies processing to be performed on the input table
as specified by parameter
in, before any other processing has taken
place. The value of this parameter is one or more of the filter commands
described in SUN/256. If more than one is given, they must be separated by
semicolon characters (";"). This parameter can be repeated multiple
times on the same command line to build up a list of processing steps. The
sequence of commands given in this way defines the processing pipeline which
is performed on the table.
Commands may alteratively be supplied in an external file, by
using the indirection character '@'. Thus a value of
"@filename" causes the file filename to be read for
a list of filter commands to execute. The commands in the file may be
separated by newline characters and/or semicolons, and lines which are blank
or which start with a '#' character are ignored.
- pixdata=<pix-table>
The location of the table containing the pixel data. The
data must be in the form of a HEALPix table, with one pixel per row in HEALPix
order. These files are typically, but not necessarily, FITS tables. A filename
or URL may be used, but a local file will be more efficient.
Some HEALPix format FITS tables seem to have rows which contain
1024-element arrays of pixels instead of single pixel values. This (rather
perverse?) format is not currently supported here, but if there is demand
support could be added.
- pfmt=<in-format>
File format for the HEALPix pixel data table. This is
usually, but not necessarily, FITS.
- pcmd=<cmds>
Specifies processing to be performed on pixel data table
as specified by parameter
pixdata, before any other processing has
taken place. The value of this parameter is one or more of the filter commands
described in SUN/256. If more than one is given, they must be separated by
semicolon characters (";"). This parameter can be repeated multiple
times on the same command line to build up a list of processing steps. The
sequence of commands given in this way defines the processing pipeline which
is performed on the table.
Commands may alteratively be supplied in an external file, by
using the indirection character '@'. Thus a value of
"@filename" causes the file filename to be read for
a list of filter commands to execute. The commands in the file may be
separated by newline characters and/or semicolons, and lines which are blank
or which start with a '#' character are ignored.
- ocmd=<cmds>
Specifies processing to be performed on the output table,
after all other processing has taken place. The value of this parameter is one
or more of the filter commands described in SUN/256. If more than one is
given, they must be separated by semicolon characters (";"). This
parameter can be repeated multiple times on the same command line to build up
a list of processing steps. The sequence of commands given in this way defines
the processing pipeline which is performed on the table.
Commands may alteratively be supplied in an external file, by
using the indirection character '@'. Thus a value of
"@filename" causes the file filename to be read for
a list of filter commands to execute. The commands in the file may be
separated by newline characters and/or semicolons, and lines which are blank
or which start with a '#' character are ignored.
- omode=out|meta|stats|count|checksum|cgi|discard|topcat|samp|tosql|gui
The mode in which the result table will be output. The
default mode is
out, which means that the result will be written as a
new table to disk or elsewhere, as determined by the
out and
ofmt parameters. However, there are other possibilities, which
correspond to uses to which a table can be put other than outputting it, such
as displaying metadata, calculating statistics, or populating a table in an
SQL database. For some values of this parameter, additional parameters
(
<mode-args>) are required to determine the exact behaviour.
Possible values are
- out
- meta
- stats
- count
- checksum
- cgi
- discard
- topcat
- samp
- tosql
- gui
Use the
help=omode flag or see SUN/256 for more information.
- out=<out-table>
The location of the output table. This is usually a
filename to write to. If it is equal to the special value "-" (the
default) the output table will be written to standard output.
This parameter must only be given if omode has its default
value of "out".
- ofmt=<out-format>
Specifies the format in which the output table will be
written (one of the ones in SUN/256 - matching is case-insensitive and you can
use just the first few letters). If it has the special value
"
(auto)" (the default), then the output filename will be
examined to try to guess what sort of file is required usually by looking at
the extension. If it's not obvious from the filename what output format is
intended, an error will result.
This parameter must only be given if omode has its default
value of "out".
- pixorder=nested|ring|(auto)
Selects the pixel ordering scheme used by the pixel data
file. There are two different ways of ordering pixels in a HEALPix file,
"ring" and "nested", and the sampler needs to know which
one is in use. If you know which is in use, choose the appropriate value for
this parameter; if
(auto) is used it will attempt to work it out from
headers in the file (the ORDERING header). If no reliable ordering scheme can
be determined, the command will fail with an error.
- stat=point|mean
Determines how the pixel values will be sampled to
generate an output value. The options are:
- point: Uses the value at the pixel covering the supplied position.
In this case the radius parameter is not used.
- mean: Averages the values over all the pixels within a radius given
by the radius parameter. This averaging is somewhat approximate;
all pixels which are mostly within the radius are averaged with equal
weights.
- lon=<expr>
Expression which evaluates to the longitude coordinate in
degrees in the input table at which positions are to be sampled from the pixel
data table. This will usually be the name or ID of a column in the input
table, or an expression involving one. If this coordinate does not match the
coordinate system used by the pixel data table, both coordinate systems must
be set using the
insys and
pixsys parameters.
- lat=<expr>
Expression which evaluates to the latitude coordinate in
degrees in the input table at which positions are to be sampled from the pixel
data table. This will usually be the name or ID of a column in the input
table, or an expression involving one. If this coordinate does not match the
coordinate system used by the pixel data table, both coordinate systems must
be set using the
insys and
pixsys parameters.
- insys=icrs|fk5|fk4|galactic|supergalactic|ecliptic
Specifies the sky coordinate system in which sample
positions are provided by the
lon/
lat parameters. If the sample
positions are given in the same coordinate system as that given by the pixel
data table, both the
insys and
pixsys parameters may be set
null.
The available coordinate systems are:
- icrs: ICRS (Right Ascension, Declination)
- fk5: FK5 J2000.0 (Right Ascension, Declination)
- fk4: FK4 B1950.0 (Right Ascension, Declination)
- galactic: IAU 1958 Galactic (Longitude, Latitude)
- supergalactic: de Vaucouleurs Supergalactic (Longitude,
Latitude)
- ecliptic: Ecliptic (Longitude, Latitude)
- pixsys=icrs|fk5|fk4|galactic|supergalactic|ecliptic
Specifies the sky coordinate system used for the HEALPix
data in the pixdata file. If the sample positions are given in the same
coordinate system as that given by the pixel data table, both the
insys
and
pixsys parameters may be set
null.
The available coordinate systems are:
- icrs: ICRS (Right Ascension, Declination)
- fk5: FK5 J2000.0 (Right Ascension, Declination)
- fk4: FK4 B1950.0 (Right Ascension, Declination)
- galactic: IAU 1958 Galactic (Longitude, Latitude)
- supergalactic: de Vaucouleurs Supergalactic (Longitude,
Latitude)
- ecliptic: Ecliptic (Longitude, Latitude)
- radius=<expr>
Determines the radius in degrees over which pixels will
be sampled to generate the output statistic in accordance with the value of
the
stat parameter. This will typically be a constant value, but it may
be an algebraic expression based on columns from the input table.
Not used if stat=point.