STILTS-TMATCH2(1)

📦
version 3.5.4 · 5 versions
, in ubuntu stonking

💫 STILTS-TMATCH2 — stilts-tmatch2 💫

okay bestie, sit DOWN, because we're doing stilts-tmatch2, aka Crossmatches 2 tables using flexible criteria. yes. TWO tables. FLEXIBLE criteria. the crossover event of the century 🎀

✨ SYNOPSIS ✨

stilts tmatch2 [in1=<table1>] [ifmt1=<in-format>] [in2=<table2>]
               [ifmt2=<in-format>] [icmd1=<cmds>] [icmd2=<cmds>]
               [ocmd=<cmds>]
               [omode=out|meta|stats|count|checksum|cgi|discard|topcat|samp|tosql|gui]
               [out=<out-table>] [ofmt=<out-format>] [matcher=<matcher-
               name>] [values1=<expr-list>] [values2=<expr-list>]
               [params=<match-params>] [tuning=<tuning-params>]
               [join=1and2|1or2|all1|all2|1not2|2not1|1xor2]
               [find=all|best|best1|best2] [fixcols=none|dups|all]
               [suffix1=<label>] [suffix2=<label>] [scorecol=<col-name>]
               [progress=none|log|time|profile]
               [runner=parallel|parallel<n>|parallel-
               all|sequential|classic|partest]

🌸 DESCRIPTION 🌸

tmatch2 is that girl. she's an efficient and highly configurable tool for crossmatching pairs of tables. 💅 like, she can match rows between tables based on their relative position in the sky, or — plot twist — using a whole buffet of other criteria: separation in some isotropic or anisotropic Cartesian space, identity of a key value, or literally some combination of all of the above. the full range of match criteria is discussed in SUN/256, so if you want the deep lore, that's where it lives 📖

and you get CHOICES, bestie. you can decide whether you want to identify all the matches or only the closest one, and what form the output table takes — for instance matched rows only, or all rows from one or both tables, or only the unmatched rows. main character energy, honestly 👑

if you simply want to match two tables based on sky position with a fixed maximum separation, you may find the tskymatch2 command easier to use. no shame in that, it's the beginner-friendly route 🦋

⚠️ Note: the duptag1 and duptag2 parameters have been replaced at version 1.4 by suffix1 and suffix2 for consistency with other table join tasks. rip to the old names, they served their time 💀

🎀 OPTIONS 🎀

  • in1=<table1> — the location of the first input table. and bestie, this is flexible-flexible. it 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 ifmt1 parameter. note that not all formats can be streamed in this way, so don't get cute.
    • 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, iykyk.

in any case, compressed data in one of the supported compression formats (gzip, Unix compress or bzip2) will be decompressed transparently. ✨ magic, but make it transparent.

  • ifmt1=<in-format> — specifies the format of the first input table as specified by parameter in1. the known formats are listed in SUN/256. this flag can be used if you know what format your table is in (iconic, confident, love that for you). if it has the special value (auto) — which is 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 😭 (she's trying her best). this parameter is ignored for scheme-specified tables.
  • in2=<table2> — the location of the second input table. same energy as in1, it 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 ifmt2 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. 💖

  • ifmt2=<in-format> — specifies the format of the second input table as specified by parameter in2. 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. 🫶
  • icmd1=<cmds> — specifies processing to be performed on the first input table as specified by parameter in1, 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 — yes bestie, stack them, layer them, serve looks 💅. the sequence of commands given in this way defines the processing pipeline which is performed on the table.

commands may alternatively 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. a backslash character \ at the end of a line joins it with the following line. no cap. 🔥

  • icmd2=<cmds> — specifies processing to be performed on the second input table as specified by parameter in2, 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 alternatively 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. a backslash character \ at the end of a line joins it with the following line. 🌈

  • ocmd=<cmds> — specifies processing to be performed on the output table, after all other processing has taken place (so it's the last one to the party, but she still eats 🍓). 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 alternatively 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. a backslash character \ at the end of a line joins it with the following line. 💜

  • 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 the result will be written as a new table to disk or elsewhere, as determined by the out and ofmt parameters. but — and this is the fun part — 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, so read carefully, bestie 👀

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. don't be out here passing out when omode is set to something else, that's a vibe check fail.
  • 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, so you can be lazy, we support you 🦋). 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 😭
🚨 same rule, bestie: this parameter must only be given if omode has its default value of out.
  • matcher=<matcher-name> — defines the nature of the matching that will be performed. depending on the name supplied, this may be positional matching using celestial or Cartesian coordinates, exact matching on the value of a string column, or other things. a list and explanation of the available matching algorithms is given in SUN/256. ✨ the value supplied for this parameter determines the meanings of the values required by the params, values* and tuning parameter(s) — so basically she's the one setting the rules of the whole game 💅
  • values1=<expr-list> — bestie, this is literally the glow-up list for table 1 🌟 It defines the values from table 1 that get used to work out whether a match has happened. Usually they're coordinate values like RA and Dec, and maybe some per-row error values too — but the exact values you need are decided by the kind of match, which is decided by matcher. So depending on the match type, the number and the type of values required will be different. Multiple values get separated by whitespace; if there's whitespace inside a single value it has to be 'quoted' or "quoted". The elements of the expression list are commonly just column names, but they can also be algebraic expressions calculated from zero or more columns, as explained in SUN/256. 💅
  • values2=<expr-list> — same energy as values1 but for table 2 🦋 It defines the values from table 2 used to determine whether a match has occurred. Typically coordinate values such as RA and Dec plus maybe per-row error values, though what's actually required depends on the match kind chosen by matcher — and the number and type of values needed changes with the match kind. Multiple values → separate with whitespace; whitespace inside a single value → 'quoted' or "quoted". Elements are commonly just column names, but may be algebraic expressions calculated from zero or more columns, as explained in SUN/256. ✨
  • params=<match-params> — the ✨settings✨ of the match. This is typically one or more tolerances, like error radii. It may contain zero or more values, and the values that are required depend on the match type selected by the matcher parameter. Got multiple values? Separate them with spaces, and any value that contains a space can be 'quoted' or "quoted". 🎀
  • tuning=<tuning-params> — the lil' knobs for tuning the matching process, if that's appropriate 👑 May contain zero or more values; which values are permitted depends on the match type selected by matcher. Multiple values get separated by spaces, and values containing a space can be 'quoted' or "quoted". If you don't supply this optional parameter at all, sensible defaults will be chosen for you. No cap. 🫶
  • join=1and2|1or2|all1|all2|1not2|2not1|1xor2 — decides which rows make it into the output table 🎟️ The matching algorithm figures out which rows from the first table correspond to which rows from the second, and this parameter decides what we do with that intel. The most obvious move is to write out a table with only the rows that correspond to a row in both input tables. But you might also want the unmatched rows from one or both input tables, or rows present in one table but unmatched in the other, or other possibilities entirely. The options:
    • 1and2 — an output row for each row represented in both input tables (INNER JOIN)
    • 1or2 — an output row for each row represented in either or both of the input tables (FULL OUTER JOIN)
    • all1 — an output row for each matched or unmatched row in table 1 (LEFT OUTER JOIN)
    • all2 — an output row for each matched or unmatched row in table 2 (RIGHT OUTER JOIN)
    • 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
  • find=all|best|best1|best2 — what even happens when a row in one table could be matched by more than one row in the other table?? 😭 The options:
    • all — all matches. Every match between the two tables is included in the result, and rows from both input tables may appear multiple times in the result.
    • best — best match, symmetric. The best pairs are selected in a way that treats the two tables symmetrically. Any input row that appears in one result pair is disqualified from appearing in any other result pair, so each row from both input tables will appear in at most one row in the result.
    • best1 — best match for each Table 1 row. For each row in table 1, only the best match from table 2 appears in the result. Each row from table 1 appears a maximum of once in the result, but rows from table 2 may appear multiple times.
    • best2 — best match for each Table 2 row. For each row in table 2, only the best match from table 1 appears in the result. Each row from table 2 appears a maximum of once in the result, but rows from table 1 may appear multiple times.

Okay so the differences between best, best1 and best2 are a bit subtle, ngl 🫠 In cases where it's obvious which object in each table is the best match for which object in the other, choosing between these options won't affect the result. But in crowded fields — where the distance between objects within one or both tables is typically similar to or smaller than the specified match radius — it will make a difference. In that case one of the asymmetric options (best1 or best2) is usually more appropriate than best, but bestie you're gonna have to think about which one suits your requirements. The performance (time and memory usage) of the match may also differ between these options, especially if one table is much bigger than the other. 👀

  • fixcols=none|dups|all — controls how input columns get renamed before they're used in the output table. The choices:
    • none — columns are not renamed
    • dups — columns which would otherwise have duplicate names in the output get renamed to indicate which table they came from
    • all — all columns get renamed to indicate which table they came from

If columns are renamed, the new names are determined by the suffix* parameters. 🎀

  • suffix1=<label> — if fixcols is set so input columns get renamed for insertion into the output table, this parameter decides how that renaming goes down. It gives a suffix which is appended to all renamed columns from table 1. 💖
  • suffix2=<label> — same deal, table 2 edition 🦋 If fixcols is set so input columns get renamed for insertion into the output table, this parameter determines how the renaming is done. It gives a suffix appended to all renamed columns from table 2.
  • scorecol=<col-name> — names a column in the output table that holds the "match score" for each pairwise match 🏆 What that column means depends on the chosen matcher, but it typically represents a distance of some kind between the two matching points. If a null value is chosen, no score column gets inserted into the output table at all. The default value of this parameter depends on matcher.
  • progress=none|log|time|profile — should info about the progress of the match be output to the standard error stream while it's running? 👀 For lengthy matches this is a genuinely useful reassurance and can give you guidance on how much longer it'll take. It can also be useful as a performance diagnostic. The options:
    • none — no progress is shown
    • log — progress information is shown
    • time — progress information and some time profiling information is shown
    • profile — progress information and limited time/memory profiling information are shown
  • runner=parallel|parallel<n>|parallel-all|sequential|classic|partest — picks the threading implementation 🧵 The options are currently:
    • parallel — uses the multithreaded implementation for large tables, with default parallelism, which is the smaller of 6 and the number of available processors
    • parallel<n> — uses the multithreaded implementation for large tables, with parallelism given by the supplied value <n>
    • parallel-all — uses the multithreaded implementation for large tables, with a parallelism given by the number of available processors
    • sequential — uses the multithreaded implementation but with only a single thread
    • classic — uses the legacy sequential implementation
    • partest — uses the multithreaded implementation even when tables are small

The parallel* options should normally run faster than sequential or classic (which are provided mainly for testing purposes), at least for large matches and where multiple processing cores are available. 🔥

The default value "parallel" is currently limited to a parallelism of 6, since larger values yield diminishing returns given that some parts of the matching algorithms run sequentially (Amdahl's Law), and using too many threads can sometimes end up doing more work or impacting other operations on the same machine. But bestie, you can absolutely experiment with other concurrencies, e.g. "parallel16" to run on 16 cores (if available) or "parallel-all" to run on all available cores. ✨

The value of this parameter should make no difference to the matching results. If you notice any discrepancies please report them. 🙈

🌈 SEE ALSO

If the package stilts-doc is installed, the full documentation SUN/256 is available in HTML format:

file:///usr/share/doc/stilts/sun256/index.html

📚

💜 VERSION

STILTS version 3.5.4-debian

This is the Debian version of Stilts, which lack the support of some file formats and network protocols. For differences see:

file:///usr/share/doc/stilts/README.Debian

👑

🎀 AUTHOR

Mark Taylor (Bristol University)

And that's a wrap, bestie 💅 This whole page is from STILTS-TMATCH2(1) — Debian's Stilts 3.5.4-debian, dated Mar 2017 — so go forth, match those tables, and slay the crowded fields 🌸🦋 no cap.

📦 where this page comes from