tee
Overview¶
kgtk tee copies its input file (standard input by default) to its primary output file (stdout by default)
and to a secondary output file (specified by --into-file).
This command defaults to --mode=NONE since it doesn't attach special meaning
to particular columns.
Debugging Pipes¶
The primary use envisioned for this command is as a tap in complex pipes, recording intermediary files that werld normally not be written to a persistent file system.
The option --enable=FALSE may be used to disable writing to the secondary output file.
This may be used in a pipe or script to disable the secondary files when not needed, potentially
loading to a significant performance improvement.
kgtk tee might be used in place of kgtk cat at the head of a pipe
when the input to the pipe is a single file and the intent is to make a copy of that
file for debugging or to record the inputs to a particular invocation of the pipeline or
script.
Copying Files¶
kgtk tee may also be useful to copy an input KGTK file to two output KGTK
files, equivalent to running kgtk cat twice. However, this is not its
primary intended purpose.
Usage¶
usage: kgtk tee [-h] [-i INPUT_FILE] [-o OUTPUT_FILE] --into-file INTO_FILE
[--enable [ENABLE]] [-v [optional True|False]]
Copy the primary input to the primary output, making a copy to a specified file. This can be used to make a copy of a pipe's data.
This command defaults to --mode=NONE so it will work with TSV files that do not follow KGTK column naming conventions.
optional arguments:
-h, --help show this help message and exit
-i INPUT_FILE, --input-file INPUT_FILE
The KGTK input file. (May be omitted or '-' for
stdin.)
-o OUTPUT_FILE, --output-file OUTPUT_FILE
The KGTK output file. (May be omitted or '-' for
stdout.)
--into-file INTO_FILE
The tee output file (Required)
--enable [ENABLE] When True, enable copying the data stream to the
--into-file. (default=True).
-v [optional True|False], --verbose [optional True|False]
Print additional progress messages (default=False).
Examples¶
Sample Data¶
Suppose that file1.tsv contains the following table in KGTK format:
kgtk cat -i examples/docs/tee-file1.tsv
| node1 | label | node2 | location | years |
|---|---|---|---|---|
| john | zipcode | 12345 | home | 10 |
| john | zipcode | 12346 | ||
| peter | zipcode | 12040 | home | |
| peter | zipcode | 12040 | cabin | |
| peter | zipcode | 12040 | work | 5 |
| peter | zipcode | 12040 | 6 | |
| steve | zipcode | 45601 | 3 | |
| steve | zipcode | 45601 | 4 | |
| steve | zipcode | 45601 | 5 | |
| steve | zipcode | 45601 | home | 1 |
| steve | zipcode | 45601 | work | 2 |
| steve | zipcode | 45601 | cabin |
Tee in a Pipe¶
kgtk cat -i examples/docs/tee-file1.tsv \
/ tee --into-file tee-out.tsv
| node1 | label | node2 | location | years |
|---|---|---|---|---|
| john | zipcode | 12345 | home | 10 |
| john | zipcode | 12346 | ||
| peter | zipcode | 12040 | home | |
| peter | zipcode | 12040 | cabin | |
| peter | zipcode | 12040 | work | 5 |
| peter | zipcode | 12040 | 6 | |
| steve | zipcode | 45601 | 3 | |
| steve | zipcode | 45601 | 4 | |
| steve | zipcode | 45601 | 5 | |
| steve | zipcode | 45601 | home | 1 |
| steve | zipcode | 45601 | work | 2 |
| steve | zipcode | 45601 | cabin |
kgtk cat -i tee-out.tsv
| node1 | label | node2 | location | years |
|---|---|---|---|---|
| john | zipcode | 12345 | home | 10 |
| john | zipcode | 12346 | ||
| peter | zipcode | 12040 | home | |
| peter | zipcode | 12040 | cabin | |
| peter | zipcode | 12040 | work | 5 |
| peter | zipcode | 12040 | 6 | |
| steve | zipcode | 45601 | 3 | |
| steve | zipcode | 45601 | 4 | |
| steve | zipcode | 45601 | 5 | |
| steve | zipcode | 45601 | home | 1 |
| steve | zipcode | 45601 | work | 2 |
| steve | zipcode | 45601 | cabin |
Tee Starting a Pipe¶
kgtk tee -i examples/docs/tee-file1.tsv \
--into-file tee-out.tsv
| node1 | label | node2 | location | years |
|---|---|---|---|---|
| john | zipcode | 12345 | home | 10 |
| john | zipcode | 12346 | ||
| peter | zipcode | 12040 | home | |
| peter | zipcode | 12040 | cabin | |
| peter | zipcode | 12040 | work | 5 |
| peter | zipcode | 12040 | 6 | |
| steve | zipcode | 45601 | 3 | |
| steve | zipcode | 45601 | 4 | |
| steve | zipcode | 45601 | 5 | |
| steve | zipcode | 45601 | home | 1 |
| steve | zipcode | 45601 | work | 2 |
| steve | zipcode | 45601 | cabin |
kgtk cat -i tee-out.tsv
| node1 | label | node2 | location | years |
|---|---|---|---|---|
| john | zipcode | 12345 | home | 10 |
| john | zipcode | 12346 | ||
| peter | zipcode | 12040 | home | |
| peter | zipcode | 12040 | cabin | |
| peter | zipcode | 12040 | work | 5 |
| peter | zipcode | 12040 | 6 | |
| steve | zipcode | 45601 | 3 | |
| steve | zipcode | 45601 | 4 | |
| steve | zipcode | 45601 | 5 | |
| steve | zipcode | 45601 | home | 1 |
| steve | zipcode | 45601 | work | 2 |
| steve | zipcode | 45601 | cabin |
Tee Making Two Copies¶
kgtk tee -i examples/docs/tee-file1.tsv \
-o tee-out1.tsv \
--into-file tee-out2.tsv
kgtk cat -i tee-out1.tsv
| node1 | label | node2 | location | years |
|---|---|---|---|---|
| john | zipcode | 12345 | home | 10 |
| john | zipcode | 12346 | ||
| peter | zipcode | 12040 | home | |
| peter | zipcode | 12040 | cabin | |
| peter | zipcode | 12040 | work | 5 |
| peter | zipcode | 12040 | 6 | |
| steve | zipcode | 45601 | 3 | |
| steve | zipcode | 45601 | 4 | |
| steve | zipcode | 45601 | 5 | |
| steve | zipcode | 45601 | home | 1 |
| steve | zipcode | 45601 | work | 2 |
| steve | zipcode | 45601 | cabin |
kgtk cat -i tee-out2.tsv
| node1 | label | node2 | location | years |
|---|---|---|---|---|
| john | zipcode | 12345 | home | 10 |
| john | zipcode | 12346 | ||
| peter | zipcode | 12040 | home | |
| peter | zipcode | 12040 | cabin | |
| peter | zipcode | 12040 | work | 5 |
| peter | zipcode | 12040 | 6 | |
| steve | zipcode | 45601 | 3 | |
| steve | zipcode | 45601 | 4 | |
| steve | zipcode | 45601 | 5 | |
| steve | zipcode | 45601 | home | 1 |
| steve | zipcode | 45601 | work | 2 |
| steve | zipcode | 45601 | cabin |