:orphan: .. _ahelp_1dcat: ***** 1dcat ***** .. contents:: :local: | .. code-block:: none Usage: 1dcat [options] a.1D b.1D ... where each file a.1D, b.1D, etc. is a 1D file. In the simplest form, a 1D file is an ASCII file of numbers arranged in rows and columns. 1dcat takes as input one or more 1D files, and writes out a 1D file containing the side-by-side concatenation of all or a subset of the columns from the input files. * Output goes to stdout (the screen); redirect (e.g., '>') to save elsewhere. * All files MUST have the same number of rows! * Any header lines (i.e., lines that start with '#') will be lost. * For generic 1D file usage help and information, see '1dplot -help' ----------- TSV files: [Sep 2018] ----------- * 1dcat can now also read .tsv files, which are columns of values separated by tab characters (tsv = tab separated values). The first row of a .tsv file is a set of column labels. After the header row, each column is either all numbers, or is a column of strings. For example Col 1 Col 2 Col 3 3.2 7.2 Elvis 8.2 -1.2 Sinatra 6.66 33.3 20892 In this example, the column labels contain spaces, which are NOT separators; the only column separator used in a .tsv file is the tab character. The first and second columns are converted to number columns, since every value (after the label/header row) is a numeric string. The third column is stored as strings, since some of the entries are not valid numbers. * 1dcat can deal with a mix of .1D and .tsv files. The .tsv file header rows are NOT output by default, since .1D files don't have such headers. * The usual output from 1dcat is NOT a .tsv file - blanks are used for separators. You can use the '-tsvout' option to get TSV formatted output. * If you mix .1D and .tsv files, the number of data rows in each file must be the same. Since the header row in a .tsv file is NOT used here, the total number of lines in a .tsv file must be 1 more than the number of lines in a .1D file for the two files to match in this program. * The purpose of supporting .tsv files is for eventual compatibility with the BIDS format http://bids.neuroimaging.io - which uses .tsv files extensively to provide auxiliary information for (F)MRI datasets. * Column selectors (like '[0,3]') can be used on .tsv files, but row selectors (like '{0,3..5}') cannot be used on .tsv files - at this time :( * You can also select a column in a .tsv file by using the label at the top of of the column. A BIDS-related example: 1dcat sub-666_task-XXX_events.tsv'[onset,duration,trial_type,reaction_time]' A similar example, which outputs a list of the trial types in an imaging run: 1dcat sub-666_task-XXX_events.tsv'[trial_type]' | sort | uniq * Since .1D files don't have headers, the label method of column selection doesn't work with such inputs; you must use integer column selectors on .1D files. * NOTE WELL: The string 'N/A' or 'n/a' in a column that is otherwise numeric will be considered to be a number, and will be replaced on input with the mean of the "true" numbers in the column -- there is no concept of missing data in an AFNI .1D file. ++ If you don't like this, well ... too bad for you. * NOTE WELL: 1dcat now also allows comma separated value (.csv) files. These are treated the same as .tsv files, with a header line, et cetera. -------- OPTIONS: -------- -tsvout = Output in a TSV (.tsv) format, where the values in each row are separated by tabs, not blanks. Also, a header line will be provided, as TSV files require. -csvout = Output in a CSV (.csv) format, where the values in each row are separated by commas, not blanks. Also, a header line will be provided, as CSV files require. -nonconst = Columns that are identically constant should be omitted from the output. -nonfixed = Keep only columns that are marked as 'free' in the 3dAllineate header from '-1Dparam_save'. If there is no such header, all columns are kept. * NOTE: -nconst and -nonfixed don't have any effect on .tsv/.csv files, and the use of these options has NOT been tested at all when the inputs are mixture of .tsv/.csv and .1D files. -form FORM = Format of the numbers to be output. You can also substitute -form FORM with shortcuts such as -i, -f, or -c. For help on -form's usage, and its shortcut versions see ccalc's help for the option of the same name. -stack = Stack the columns of the resultant matrix in the output. You can't use '-stack' with .tsv/.csv files :( -sel SEL = Apply the same column/row selection string to all filenames on the command line. For example: 1dcat -sel '[0,2]' f1.1D f2.1D is the same as: 1dcat f1.1D'[1,2]' f2.1D'[1,2]' The advantage of the option is that it allows wildcard use in file specification so that you can run something like: 1dcat -sel '[0,2]' f?.1D -OKempty: Exit quietly when encountering an empty file on disk. Note that if the file is poorly formatted, it might be considered empty. EXAMPLE: -------- Input file 1: 1 2 3 4 Input file 2: 5 6 7 8 1dcat data1.1D data2.1D > catout.1D Output file: 1 5 2 6 3 7 4 8 ++ Compile date = Mar 24 2024 {AFNI_24.0.17:linux_ubuntu_16_64}