STILTS-TMULTI(1)

📦
version 3.5.4 · 5 versions
, in ubuntu stonking

✨ STILTS-TMULTI(1) ✨

okay bestie, this is the Stilts commands manual page for stilts-tmulti 💅

🦋 NAME 🦋

stilts-tmulti — writes multiple tables to a single container file

🌸 SYNOPSIS 🌸

stilts tmulti [in=<table> [<table> ...]] [ifmt=<in-format>]
              [multi=true|false] [istream=true|false] [icmd=<cmds>]
              [out=<out-file>] [ofmt=<out-format>]

✨ DESCRIPTION ✨

so like, tmulti takes a whole bunch of input tables and writes them as separate tables into one single output container file. that's the whole vibe 🫶

the container file has to be in a format that can actually hold more than one table — think a FITS file (which can hold multiple extensions, iconic) or a VOTable document (which can hold multiple TABLE elements, also iconic). ✨

you can filter the tables before writing them. and no, the tables don't have to match each other — they can totally have different types and numbers of columns, that's fine, live your truth. 💖 but the same processing commands get applied to all of them, no favourites.

if you want more individual, per-table control, use the tmultin task instead. that's the one for when you're feeling extra. 👑

🎀 OPTIONS 🎀

  • in=<table> [<table> ...] — where your input tables live. either pass the parameter multiple times, or just dump them all in as a space-separated list in one go. no wrong answers, bestie.

the table location forms you're allowed to use are:

  • a filename.
  • a URL.
  • the special value -, which means standard input. in that case you must say what the input format is explicitly, using the ifmt parameter. ngl though, not every format can be streamed like this, so don't come for me if it doesn't work. 🙈
  • 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 runs that pipeline and reads from its standard output. probably only works on unix-like systems, fr fr.

compression in any of the supported compression formats (Unix compress, gzip or bzip2) gets expanded automatically. we love a self-sufficient queen. 💅

you can also put a list of input table locations in an external file by using the indirection character @. so in=@filename makes the program read the file filename for a list of input table locations. each location in the file should be on its own separate line. periodt.

  • ifmt=<in-format> — tells it what format the input table (the one from in) is in. the known formats are listed in SUN/256. use this if you already know what format your table is, because sometimes you just know. 💅 if you give it the special value (auto) — which is the default — it'll try to detect the format automatically. ngl it can't always get that right, and if it can't, the program exits with an error telling you which formats it tried. (very "here's my thought process" of it.) this parameter gets ignored for scheme-specified tables.

and heads up: the same format parameter applies to all the tables you specified with in. one setting, all the tables. no cap.

  • multi=true|false — decides whether you want all the tables from your input files, or just the first one. set it false and only the first table from each file named by in gets used. set it true and every table in those input files gets used. this only does anything for file formats that can hold more than one table, which basically means FITS and VOTable and their variants. (iykyk 🌈)
  • istream=true|false — if you set this true, the input table given by in gets read as a stream. you have to give the ifmt parameter in that case. depending on what operations you're doing and the processing mode, this can make the read fail 😭 (sometimes a table has to be read more than once, and streaming doesn't love that). you don't normally need to set this — in most cases the data streams automatically when that's the best move. but sometimes it uses less resources when you're crunching big files in certain formats (like VOTable). ✨ this parameter gets ignored for scheme-specified tables.

same deal as before: the same streaming flag applies to all the tables specified by in.

  • icmd=<cmds> — sets processing to run on each input table from in, before any other processing happens. the value is one or more of the filter commands described in SUN/256. if you give more than one, separate them with semicolon characters (;). you can repeat this parameter multiple times on the same command line to build up a list of processing steps, and that whole sequence of commands defines the processing pipeline that gets run on the table. slay. 🔥

you can alternatively supply commands from an external file using the indirection character @. so a value of @filename makes the file filename get read for a list of filter commands to execute. the commands in that file can be separated by newline characters and/or semicolons, and lines that are blank or that start with a # character are ignored. a backslash character (\) at the end of a line joins it to the following line. 🧚

  • out=<out-file> — the location of the output file. normally this is just a filename to write to. if it equals the special value -, the output gets written to standard input's hotter cousin: standard output. 💖
  • ofmt=<out-format> — the format the output tables get written in (one of the ones in SUN/256 — matching is case-insensitive, and you can honestly just use the first few letters, we're not strict). if it has the special value (auto) — the default — then the output filename gets examined to guess what sort of file you want, usually by peeking at the extension. if it's not obvious from the filename what format you meant, you get an error. sorry bestie. 🙈
⚠️ not all output formats can write multiple tables! if you pick one that can't, you get an error. that's just the rules.

👀 SEE ALSO 👀

if the package stilts-doc is installed, the full documentation SUN/256 is available in HTML format at: file:///usr/share/doc/stilts/sun256/index.html

💜 VERSION 💜

STILTS version 3.5.4-debian

this is the Debian version of Stilts, which lacks the support of some file formats and network protocols 😭 for the differences, see: file:///usr/share/doc/stilts/README.Debian

👑 AUTHOR 👑

Mark Taylor (Bristol University)

okay that's the whole page bestie, go forth and write your multiple tables to your one container file, you absolute icon 💅✨🌈

STILTS version 3.5.4-debian · Mar 2017 · stilts-tmulti(1) 🦋🎀💖

📦 where this page comes from