Overview

#  rt-plot

Wrapper for ROOT plots. It interprets simple programs and draws
Program is read from standard input

  Command line flags:
  +++++++++++++++++++

    -b - batch mode. Terminates after end of input.
    -x - do not create window. Useful for batch creating of plots wisth standard
         size. If window is created all plot size will be determined by window
         size,
    -v - verbose. Echo input to stdout.
    -h - help on usage.



##  Language description

Program interprets simple line oriented language. Each line is a
command which are executed in order. Commands either add object to
plot or alter their state.  In latter case state of object which have
been added last is altered. If command couldn't be executed it's
ignored. Commands could contain keywords, number literals and string
literals enclosed in double quotes.


## List of commands

> exit
> quit

Exit program immediately

> clear

Remove all plots and reset all settings.

> save "file name"

Save current plot to file. PDF, PS, PNG and JPEG file formats are supported and
selected by file name. Files with extension `.rootpl' will be saved as list of
commands since last `clear'.



### Multiple pads

It's possible to arrange plot in several pad. Every pad is independent from
others. They are arranged in rows and columns. Every pad is either row/column of
more pads or plot.

In order to add row/column use:

> add row 
> add column

After this command interpreter enters row mode in which either new rows/columns
or new pads could be added. Every row/column must be finished by:

> end row
> end column


Individual pads in which one could plot could be used. They're only valid in
row/column mode. Weight controls size of pad in the row/column. Default weight
is 1.

> add pad
> add pad [weight]


After that one could use normal drawing commands. Pad is terminated by command

> end pad



### Plot

> plot ...
> add  ...

Add object to the plot. plot clear plot before adding new object
whereas add does not. All plotting commands follow same pattern:
plot/add command following by the plot type and information source.
It's either file name or - in which case data is supplied in the
stream. Data formats are specific to the plotters and should be
terminated by '<<<' line. If program encounters <<< line in other
contexts it's ignored. If data couldn't be parsed no plot is added.


> histogram

1D and 2D histogram in the format outputted by histogram-fill. For 1D
BinI and BinD are supported and Bin2D for 2D histograms. Histograms
support most of the options and all histogram specific ones.


> graph

Simple graph with optional error bars. Support all line and marker options.

Data format used by graph is shared by other plots. Data have optional header
which tells what kind of data every column holds. It starts with `#' and column
description are space separated. As general rule, if column no have meaning it's
ignored. For example `graph' ignore Z coordinate.
 
  + x,y,z   - X, Y or Z coordinate of point
  + dx,dy   - symmetric errors
  + ldx,ldy - lower part of asymmetric errors
  + udx,udy - upper part of asymmetric errors
  + _       - column is ignored

If both symmetric and at least one asymmetric error is specified then asymmetric
errors are used. If data for X coordinates is not specified then all surrogate
values are used: 0, 1, etc.

For common cases it's possible to omit header. Then columns will have following
meaning:

  1. List of Y coordinates. X coordinates are [0,1 .. ]
  2. X,Y pairs
  3. X,Y,ΔY triples. Error are symmetrical.


> barchart

Bar chart. Uses same data format as graph and accept X and Y coordinates. If X
is not specified surrogate values [0,1..] are used.


> poly

Polygon. Line and fill options are supported. Data format is (X,Y)
pairs and polygon is closed automatically.


> vline [x]

Vertical line at x. Its height is adjusted automatically so It covers
whole plot. All line options are supported. Lines do not participate in
automatic range adjustment.


> hline [y]

Horizontal line at y. Similar to vline.


> abline [k] [b]

Line with slope `k' and intercept `b'.


> vband [x1] [x2]

Vertical band from x1 to x2. Its height is adjusted automatically so
it covers whole plot. Line and fill options are supported.


> hband [y1] [y2]

Horizontal band from y1 to y2. Similar to vband.




### Set options

> set ...

Set options for object added last. If object doesn't support particular option
or there is no object at all it's a noop.


> set title "Plot title"

Set plot title.


> set grid
> set grid [on|off]
> set grid x
> set grid x [on|off]
> set grid y
> set grid y [on|off]

Set grid display on off.


> set [xaxis|yaxis|zaxis] ...

Set option for X, Y or Z axis


> set [xaxis|yaxis|zaxis] label -
> set [xaxis|yaxis|zaxis] label "Label"

Remove or set axis label


> set [xaxis|yaxis|zaxis] log
> set [xaxis|yaxis|zaxis] log on
> set [xaxis|yaxis|zaxis] log off

Turn log scale for given scale on/off. If no switch is given switches it on.


> set [xaxis|yaxis|zaxis] range -
> set [xaxis|yaxis|zaxis] range -      {real}
> set [xaxis|yaxis|zaxis] range {real} -
> set [xaxis|yaxis|zaxis] range {real} {real}

Set axis to automatically adjusted range (default) or to custom range. It's
possible to set manually only upper or lower limit.


> set ignore range
> set ignore range on
> set ignore range off

Exclude or include last object from automatic range adjustments.


> set palette {string}

Sets global palette for 2D plots.


> set error -
> set error cross
> set error band

Set style of errors for last object. It's either do not
display/crosses (default)/band.


> set line ...

Set line drawing options


> set line width {integer}

Set width of the line. 0 means that no line is drawn at all.


> set line color {color}

Set color of the line


> set line style "Style name"

Set style of the line (solid/dashed/dotted/etc.)


> set line type "Style name"

Set type of the line: straight line segments/splines/no line at all


> set line marker "Marker style"

Set optional marker for the line.


> set fill {color}

Set fill options.


> set hist ...

Set histogram specific options.


> set hist text
> set hist text on
> set hist text off

Set text display for histograms

> set hist text format -
> set hist text format {int}

Set number of digits to display in text view of the histogram


> set hist color
> set hist color on
> set hist color off

Set color map display for histograms. Only applicable to 2D histograms.


> set hist box
> set hist box on
> set hist box off

Set box plot mode for histograms. Only applicable to 2D histograms.


> set hist scatter
> set hist scatter on
> set hist scatter off

Set scatterplot mode for histograms. Only applicable to 2D histograms.


> set hist contour
> set hist contour on
> set hist contour off
> set hist contour {integer}

Set contour plot mode for histograms. Only applicable to 2D histograms.
With integer parameter it enable mode and sets number of contours to N.
Otherwise defaults to 10 when enabled.


> set hist palette
> set hist palette on
> set hist palette off

Draw palette for histogram. Only useful for histograms which use color map to
display.


> set silent
> set silent on
> set silent off

Set silent mode on off. In silent mode updates are not drawn unless silent mode
is disabled. It speed up drawing significantly.


### Legend

> legend add {x1} {y1} {x2} {y2}

Create new legend. Coordinates are in range [0,1]


> legend -

Remove legend


> legend add {string}

Add entry about last object to legend.


> legend add label {string}

Add string to legend


> legend add label {string} {string}

Add key-value pair to legend



## Constants

### Colors

Colors could be specified using either symbolic name or color number. Number
have same meaning as they have in the ROOT. Accepted symbolic names are register
independent. They are listed below:

  - white
  - black
  - red
  - green
  - blue
  - yellow
  - magenta
  - cyan
  - forest
  - violet


### Line styles and types

Possible line styles are described by string constant. Following string are
accepted:

  - solid       - solid line [default]
  - dash/dashed - dashed line
  - dotted      - dotted line
  - dash/dot    - dash-dot line

Also lines could be drawn either by connecting dots by straight
segmentas or using slines to get smooth curve

  - no/none        - no line drawn
  - line           - connect points using straight line segments [default]
  - spline/splines - connect points using splines


### Marker styles

Marker styles are encoded by strings as well.

  - no / none   - no marker [default]
  - dot / "." 
  - plus / "+"
  - star / "*"
  - "o"
  - "x"

### Palette

Available palettes

  - "deep sea" [default]
  - "grey scale"/"gray scale"
  - "dark body"/"black body"
  - "blue yellow"