Next Previous Up Contents
Next: Examples
Up: tskymatch2: Crossmatches 2 tables on sky position
Previous: tskymatch2: Crossmatches 2 tables on sky position
The usage of tskymatch2
is
stilts <stilts-flags> tskymatch2 ifmt1=<in-format> ifmt2=<in-format>
omode=<out-mode> <mode-args>
out=<out-table> ofmt=<out-format>
ra1=<expr/degs> dec1=<expr/degs>
ra2=<expr/degs> dec2=<expr/degs>
error=<value/arcsec> tuning=<healpix-k>
join=1and2|1or2|all1|all2|1not2|2not1|1xor2
find=best|all
[in1=]<table1> [in2=]<table2>
If you don't have the stilts
script installed,
write "java -jar stilts.jar
" instead of
"stilts
" - see Section 3.
The available <stilts-flags>
are listed
in Section 2.1.
Parameter values are assigned on the command line
as explained in Section 2.3.
They are as follows:
-
dec1 = <expr/degs>
- Value in degrees for the declination of positions in
table 1 to be matched.
This may simply be a column name, or it may be an
algebraic expression calculated from columns as explained
in Section 9.
If left blank, an attempt is made to guess from UCDs,
column names and unit annotations what expression to use.
-
dec2 = <expr/degs>
- Value in degrees for the declination of positions in
table 2 to be matched.
This may simply be a column name, or it may be an
algebraic expression calculated from columns as explained
in Section 9.
If left blank, an attempt is made to guess from UCDs,
column names and unit annotations what expression to use.
-
error = <value/arcsec>
- The maximum separation permitted between two objects
for them to count as a match. Units are arc seconds.
-
find = best|all
- Determines which matches are retained.
If
best
is selected,
then only the best match
between the two tables will be retained; in this case
the data from a row of either input table will appear in
at most one row of the output table.
If all
is selected, then all pairs of rows
from the two input tables which match the input criteria
will be represented in the output table.
[Default: best
]
-
ifmt1 = <in-format>
- Specifies the format of the first input table
(one of the known formats listed in Section 5.2.1).
This flag can be used if you know what format your input
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.
[Default: (auto)
]
-
ifmt2 = <in-format>
- Specifies the format of the second input table
(one of the known formats listed in Section 5.2.1).
This flag can be used if you know what format your input
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.
[Default: (auto)
]
-
in1 = <table1>
- The location of the first input table.
This is usually a filename or URL, and may point to a file
compressed in one of the supported compression formats
(Unix compress, gzip or bzip2).
If it is omitted, or equal to the special value "-",
the input table will be read from standard input.
In this case the input format must be given explicitly
using the
ifmt1
parameter.
-
in2 = <table2>
- The location of the second input table.
This is usually a filename or URL, and may point to a file
compressed in one of the supported compression formats
(Unix compress, gzip or bzip2).
If it is omitted, or equal to the special value "-",
the input table will be read from standard input.
In this case the input format must be given explicitly
using the
ifmt2
parameter.
-
join = 1and2|1or2|all1|all2|1not2|2not1|1xor2
- Determines which rows are included in the output table.
The matching algorithm determines which of the rows from
the first table correspond to which rows from the second.
This parameter determines what to do with that information.
Perhaps the most obvious thing is to write out a table
containing only rows which correspond to a row in both of
the two input tables. However, you may also want to see
the unmatched rows from one or both input tables,
or rows present in one table but unmatched in the other,
or other possibilities.
The options are:
-
1and2
: An output row for each row represented in both input tables
-
1or2
: An output row for each row represented in either or both of the input tables
-
all1
: An output row for each matched or unmatched row in table 1
-
all2
: An output row for each matched or unmatched row in table 2
-
1not2
: An output row only for rows which appear in the first table but are not matched in the second table
-
2not1
: An output row only for rows which appear in the second table but are not matched in the first table
-
1xor2
: An output row only for rows represented in one of the input tables but not the other one
[Default: 1and2
]
-
ofmt = <out-format>
- Specifies the format in which the output table will be written
(one of the ones in Section 5.2.2 - 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
".
[Default: (auto)
]
-
omode = <out-mode> <mode-args>
- 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
-
cgi
-
discard
-
topcat
-
samp
-
plastic
-
tosql
Use the help=omode
flag
or see Section 6.4 for more information.
[Default: out
]
-
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
".
[Default: -
]
-
ra1 = <expr/degs>
- Value in degrees for the right ascension of positions in
table 1 to be matched.
This may simply be a column name, or it may be an
algebraic expression calculated from columns as explained
in Section 9.
If left blank, an attempt is made to guess from UCDs,
column names and unit annotations what expression to use.
-
ra2 = <expr/degs>
- Value in degrees for the right ascension of positions in
table 2 to be matched.
This may simply be a column name, or it may be an
algebraic expression calculated from columns as explained
in Section 9.
If left blank, an attempt is made to guess from UCDs,
column names and unit annotations what expression to use.
-
tuning = <healpix-k>
- Tuning parameter that controls the pixel size used when
binning the rows.
The legal range is from
0 (corresponding to pixel size of about 60 degrees) to
20 (about 0.2 arcsec).
The value of this parameter will not affect the result
but may affect the performance in terms of CPU and memory
resources required.
A default value will be chosen based on the size of the
error
parameter, but it may be possible to improve performance by
adjusting the default value.
The value used can be seen by examining the progress output.
If your match is taking a long time or is failing from lack
of memory it may be worth trying different values
for this parameter.
Next Previous Up Contents
Next: Examples
Up: tskymatch2: Crossmatches 2 tables on sky position
Previous: tskymatch2: Crossmatches 2 tables on sky position
STILTS - Starlink Tables Infrastructure Library Tool Set
Starlink User Note256
STILTS web page:
http://www.starlink.ac.uk/stilts/
Author email:
m.b.taylor@bristol.ac.uk