AFNI program: 1dcat

Output of -help


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 = Oct 31 2024 {AFNI_24.3.06:linux_ubuntu_24_64}
This page auto-generated on Thu Oct 31 09:41:02 PM EDT 2024