AFNI program: 1dplot

Usage: 1dplot [options] tsfile ...
Graphs the columns of a *.1D time series file to the X11 screen.

Options:
 -install   = Install a new X11 colormap.
 -sep       = Plot each column in a separate sub-graph.
 -one       = Plot all columns together in one big graph.
                [default = -sep]
 -sepscl    = Plot each column in a separate sub-graph
              and allow each sub-graph to have a different
              y-scale.  -sepscl is meaningless with -one!

           ** The '-norm' options below can be useful for
               plotting data with different value ranges on
               top of each other using '-one':
 -norm2     = Independently scale each time series plotted to
              have L_2 norm = 1 (sum of squares).
 -normx     = Independently scale each time series plotted to
              have max absolute value = 1 (L_infinity norm).
 -norm1     = Independently scale each time series plotted to
              have max sum of absolute values = 1 (L_1 norm).

 -x  X.1D   = Use for X axis the data in X.1D.
              Note that X.1D should have one column
              of the same length as the columns in tsfile. 
 N.B.: -x will override -dx and -xzero; -xaxis still has effects
 -xl10 X.1D = Use log10(X.1D) as the X axis.

 -dx xx     = Spacing between points on the x-axis is 'xx'
                [default = 1] SYNONYMS: '-dt' and '-del'
 -xzero zz  = Initial x coordinate is 'zz' [default = 0]
                SYNONYMS: '-tzero' and '-start'
 -nopush    = Don't 'push' axes ranges outwards.
 -ignore nn = Skip first 'nn' rows in the input file
                [default = 0]
 -use mm    = Plot 'mm' points [default = all of them]
 -xlabel aa = Put string 'aa' below the x-axis
                [default = no axis label]
 -ylabel aa = Put string 'aa' to the left of the y-axis
                [default = no axis label]
 -plabel pp = Put string 'pp' atop the plot.
              Some characters, such as '_' have
              special formatting effects. You 
              can escape that with ''. For example:
        echo 2 4.5 -1 | 1dplot -plabel 'test_underscore' -stdin
              versus
        echo 2 4.5 -1 | 1dplot -plabel 'test\_underscore' -stdin
 -title pp = Same as -plabel, but only works with -ps/-png/-jpg options.

 -stdin     = Don't read from tsfile; instead, read from
              stdin and plot it. You cannot combine input
              from stdin and tsfile(s).  If you want to do so,
              use program 1dcat first.

 -ps        = Don't draw plot in a window; instead, write it
              to stdout in PostScript format.
             * If you view the result in 'gv', you should turn
               'anti-alias' off, and switch to landscape mode.
             * You can use the 'gs' program to convert PostScript
               to other formats; for example, a .bmp file:
            1dplot -ps ~/data/verbal/cosall.1D | 
             gs -r100 -sOutputFile=fred.bmp -sDEVICE=bmp256 -q -dBATCH -

 -jpg fname  } = Render plot to an image and save to a file named
 -jpeg fname } = 'fname', in JPEG mode or in PNG mode.
 -png fname  } = The default image width is 1024 pixels; to change
                 this value to 2000 pixels (say), do
                   setenv AFNI_1DPLOT_IMSIZE 2000
                 before running 1dplot.  Widths over 2000 may start
                 to look odd, and will run more slowly.
               * PNG files will be smaller than JPEG, and are
                 compressed without loss.
               * PNG output requires that the netpbm program
                 pnmtopng be installed somewhere in your PATH.

-ytran 'expr'    = Transform the data along the y-axis by
                   applying the expression to each input value.
                   For example:
                     -ytran 'log10(z)'
                   will take log10 of each input time series value
                   before plotting it.
                 * The expression should have one variable (any letter
                   from a-z will do), which stands for the time series
                   data to be transformed.
                 * An expression such as 'sqrt(x*x+i)' will use 'x'
                   for the time series value and use 'i' for the time
                   index (starting at 0) -- in this way, you can use
                   time-dependent transformations, if needed.
                 * This transformation applies to all input time series
                   (at present, there is no way to transform different
                   time series in distinct ways inside 1dplot).
                 * '-ytran' is applied BEFORE the various '-norm' options.

 -xaxis b:t:n:m  = Set the x-axis to run from value 'b' to
                   value 't', with 'n' major divisions and
                   'm' minor tic marks per major division.
                   For example:
                     -xaxis 0:100:5:20
                   Setting 'n' to 0 means no tic marks or labels.

 -yaxis b:t:n:m  = Similar to above, for the y-axis.  These
                   options override the normal autoscaling
                   of their respective axes.

 -ynames a b ... = Use the strings 'a', 'b', etc., as
                   labels to the right of the graphs,
                   corresponding to each input column.
                   These strings CANNOT start with the
                   '-' character.
             N.B.: Each separate string after '-ynames'
                   is taken to be a new label, until the
                   end of the command line or until some
                   string starts with a '-'.  In particular,
                   This means you CANNOT do something like
                     1dplot -ynames a b c file.1D
                   since the input filename 'file.1D' will
                   be used as a label string, not a filename.
                   Instead, you must put another option between
                   the end of the '-ynames' label list, OR you
                   can put a single '-' at the end of the label
                   list to signal its end:
                     1dplot -ynames a b c - file.1D

 -volreg         = Makes the 'ynames' be the same as the
                   6 labels used in plug_volreg for
                   Roll, Pitch, Yaw, I-S, R-L, and A-P
                   movements, in that order.

 -thick          = Each time you give this, it makes the line
                   thickness used for plotting a little larger.
                   [An alternative to using '-DAFNI_1DPLOT_THIK=...']

 -Dname=val      = Set environment variable 'name' to 'val'
                   for this run of the program only:
 1dplot -DAFNI_1DPLOT_THIK=0.01 -DAFNI_1DPLOT_COLOR_01=blue '1D:3 4 5 3 1 0'

You may also select a subset of columns to display using
a tsfile specification like 'fred.1D[0,3,5]', indicating
that columns #0, #3, and #5 will be the only ones plotted.
For more details on this selection scheme, see the output
of '3dcalc -help'.

Example: graphing a 'dfile' output by 3dvolreg, when TR=5:
   1dplot -volreg -dx 5 -xlabel Time 'dfile[1..6]'

You can also input more than one tsfile, in which case the files
will all be plotted.  However, if the files have different column
lengths, the shortest one will rule.

The colors for the line graphs cycle between black, red, green, and
blue.  You can alter these colors by setting Unix environment
variables of the form AFNI_1DPLOT_COLOR_xx -- cf. README.environment.
You can alter the thickness of the lines by setting the variable
AFNI_1DPLOT_THIK to a value between 0.00 and 0.05 -- the units are
fractions of the page size.

LABELS
------
Besides normal alphabetic text, the various labels can include some
special characters, using TeX-like escapes starting with '\'.
Also, the '^' and '_' characters denote super- and sub-scripts,
respectively.  The following command shows many of the escapes:
 1deval -num 100 -expr 'J0(t/4)' | 1dplot -stdin -thick \
 -xlabel '\alpha\beta\gamma\delta\epsilon\zeta\eta^{\oplus\dagger}\times c' \
 -ylabel 'Bessel Function \green J_0(t/4)'     \
 -plabel '\Upsilon\Phi\Chi\Psi\Omega\red\leftrightarrow\blue\partial^{2}f/\partial x^2'

TIMESERIES (1D) INPUT
---------------------
A timeseries file is in the form of a 1D or 2D table of ASCII numbers;
for example:   3 5 7
               2 4 6
               0 3 3
               7 2 9
This example has 4 rows and 3 columns.  Each column is considered as
a timeseries in AFNI.  The convention is to store this type of data
in a filename ending in '.1D'.

** COLUMN SELECTION WITH [] **
When specifying a timeseries file to an command-line AFNI program, you
can select a subset of columns using the '[...]' notation:
  'fred.1D[5]'            ==> use only column #5
  'fred.1D[5,9,17]'       ==> use columns #5, #9, and #17
  'fred.1D[5..8]'         ==> use columns #5, #6, #7, and #8
  'fred.1D[5..13(2)]'     ==> use columns #5, #7, #9, #11, and #13
Column indices start at 0.  You can use the character '$'
to indicate the last column in a 1D file; for example, you
can select every third column in a 1D file by using the selection list
  'fred.1D[0..$(3)]'      ==> use columns #0, #3, #6, #9, ....

** ROW SELECTION WITH {} **
Similarly, you select a subset of the rows using the '{...}' notation:
  'fred.1D{0..$(2)}'      ==> use rows #0, #2, #4, ....
You can also use both notations together, as in
  'fred.1D[1,3]{1..$(2)}' ==> columns #1 and #3; rows #1, #3, #5, ....

** DIRECT INPUT OF DATA ON THE COMMAND LINE WITH 1D: **
You can also input a 1D time series 'dataset' directly on the command
line, without an external file. The 'filename' for such input has the
general format
  '1D:n_1@val_1,n_2@val_2,n_3@val_3,...'
where each 'n_i' is an integer and each 'val_i' is a float.  For
example
   -a '1D:5@0,10@1,5@0,10@1,5@0'
specifies that variable 'a' be assigned to a 1D time series of 35,
alternating in blocks between values 0 and value 1.
 * Spaces or commas can be used to separate values.
 * A '|' character can be used to start a new input "line":
   Try 1dplot '1D: 3 4 3 5 | 3 5 4 3'

** TRANSPOSITION WITH \' **
Finally, you can force most AFNI programs to tranpose a 1D file on
input by appending a single ' character at the end of the filename.
N.B.: Since the ' character is also special to the shell, you'll
      probably have to put a \ character before it. Examples:
       1dplot '1D: 3 2 3 4 | 2 3 4 3'   and
       1dplot '1D: 3 2 3 4 | 2 3 4 3'\'
When you have reached this level of understanding, you are ready to
take the AFNI Jedi Master test.  I won't insult you by telling you
where to find this examination.

++ Compile date = Jul  2 2009