SYNOPSIS

ctioga arguments ...

DESCRIPTION

ctioga is a command-line front-end to the wonderful Tioga plotting library. It aims at plotting quickly both data files and mathematical functions, with however the possibility of a high control over the details.

IMPORTANT NOTE

Please keep in mind while reading this that the main author of ctioga has more fun programming than writing documentation, which means that he is more willing to invest energy into new features of ctioga rather than keeping this manual page up-to-date. Best care is taken for ctioga to remain backward-compatible, which means that the information you'll find here will most probably never be misleading. However, not all the features might be documented at some point. The currently implemented features will be found using ctioga --help.

EXAMPLES

To get to the facts, let's start with a few examples:

ctioga File.dat

Produces a file Plot.pdf showing the second column of File.dat as a function of the first.

ctioga File.dat@2:3

Produces a file Plot.pdf showing the third column of File.dat as a function of the second.

ctioga File.dat@2:3 @4:5

Produces a file Plot.pdf showing the third column of File.dat as a function of the second and the fifth as a function of the fourth.

ctioga --math 'sin(x)'

Produces a file Plot.pdf showing the function sin(x).

ctioga --xpdf --math -l 'Cosine' 'cos(x)'

Produces a file Plot.pdf showing the function cos(x), nicely labeled with the text 'Cosine' and launches xpdf to display the file produced.

More examples and a rather complete tutorial can be found in the ./usr/share/doc/ctioga/examples/ directory on debian systems.

OPTIONS

ctioga works with the concept of backends: a backend is an object dealing with the data. Some read data from different kinds of files, others, like the math backend create data on demand from mathematical formulas. Backends work with data sets. A set is one curve.

ctioga's command line is made of of options, starting with '-' or '--', mixed with sets (all the rest). Options apply to the sets specified on their right; some (like --legend) only to the next one.

Basic style options

-c, --[no-]color [color]

specifies the color to be used for lines. It can be set to any valid Tioga color, or to auto to use ctioga's automatic color scheme (by default). When specified as --no-color it disables the display of the lines.

-m, --[no-]marker [marker]

enables or disable the use of markers. marker can be auto, no or a Tioga marker specification. Like with --color, auto makes the markers shift with every data set.

--marker-color color

exactly the same as --color except that it applies the the marker's color.

--line-style linestyle

sets the line style. As with previous parameters, auto turns on automatic change, and you can specify any Tioga line style. Using no removes completely lines.

--line-width width

sets the line width. This will be affected by any subsequent --rescale.

--[no-]interpolate

wheter to turn on automatic interpolation for the next curves or not. Automatic interpolation just transforms lines between two consecutive data points into cubic splines. It looks very good in many cases.

--error-bar-color color

ctioga version 1.4 has a support for error bars, and this options enables one to select their color. See discussion on the text backend below for more details about how to get error bars in the first place.

--drawing-order order

Have you ever wanted to have your markers in a different color and behind the lines ? You can use this option to do so. It takes an integer between 0 and 5, and specifies the order in which the lines, the markers and the error bars are drawn on the resulting PDF. The last will be the most visible in the end. Any invalid argument for order will show which numbers are valid and what they mean.

Transparency

--transparency transparency

--marker-transparency transparency

--error-bar-transparency transparency

Sets the transparency for drawing respectively lines, markers and error bars. The transparency is a number between 0 and 1, 0 meaning perfectly opaque and 1 absolutely invisible.

Fillings

From ctioga version 1.5, it is possible to fill spaces under the curves. You need to specify a y value where the filling will go to. The boundary for that has to be a horizontal line. It is specified using the --fill-type option:

--fill-type type

Sets the fill type for filling next curves. The fill type can be

none

for no filling

y_axis

to fill until the y = 0 line

bottom, top

to fill respectively to the bottom or to the top of the current graph

y = val

to fill until the y value val.

--fill-color color

The color for the fill. If specified neither by you nor by the current theme, it defaults to the current plotting color.

--fill-transparency trans

Sets the transparency for fills. I daresay, it looks very cool with a transparency of around 0.5.

Histograms

ctioga version 1.5 brings a much more powerful way to make histograms. Here are the functions dealing with that:

--hist type

All subsequent curves will be histograms. The 'type' of histogram used depends on the type argument. It can be no or off to stop making histograms, old-style to use the old style histograms: steps without sides. Then, you can use the same kind of specification as for the --fill option to specify the level at which the steps should start/stop. Important: please note that if you use something else than old-style for this argument and that you fill the resulting curves, the actual argument to --fill will be ignored and will be considered the same as the type one of the --hist option: not taking the same thing always leads to pretty disgusting results. However, please note that you need to use --fill with a valid argument to actually get a filled histogram.

--hist-left left

--hist-right right

Set respectively the position of the left or the right side of the step relative to its total size. If you want that the steps are joined, use respectively 0 and 1. Other values will change the apparent width of the steps. Please note that nothing prevents you from setting either value outside the [0,1] interval where these values make sense. But don't complain if it looks ugly.

--hist-width width

A convenience interface for the --hist-left and --hist-right options. Basically sets the left and right boundaries so that the apparent width of the step is width times its real size and that the results are centered on the interval.

--no-hist

Stop making histograms.

--[no-]histogram

This is the old option, here to keep old things working. It is the equivalent of either the --hist old-style option or the --no-hist one. Don't use it. Anyway, new histograms look way better !!

Themes and sets

--theme theme

chooses the theme. Themes are little pieces of Ruby code that can take care of many detail of presentation, to help you focus on the data you want to plot, and not on the details about presentation. ctioga will automatically load themes in the themes/ subdirectory of your rubylib/CTioga directory, and also on your personal $HOME/.ctioga/themes directory. A good place to start to write your own theme is to take the rubylib/CTioga/themes/demo.rb file and tweak it until it suits your needs.

--theme-list

lists all the themes ctioga found. If for some reason the theme you wrote doesn't show up here, you can give a try at the --debug flag, it should give relevant information about the problem.

--reset-theme

resets the current theme, which essentially means: select the default color/marker sets and reset them.

--mono

sets up a monochromatic display: color is set to Black and linestyle changes with every set. Strictly equivalent to --theme mono.

--color-set set

--marker-set set

--marker-color-set set

--line-style-set set

chooses the different color, marker, marker colors and linestyle sets available. The only way to get reliable data about available sets is to run ctioga --help, which lists them. To know how they look like, just try out dataset expansion:

ctioga --math 'sin(x) + 1##8'

Starting from ctioga version 1.8, you can use directly colors, markers and so on for sets, and you get a set with only this color/marker/linestyle.

Style manipulations

--skip-style

Does not use the next theme style, but skips to the next one.

-s, --same-style

Apply the same style to the next curve as to the last curve. This actually only applies to elements of style deemed that have been fed with the auto argument, which is nearly everything by default. Style can be further overridden by other style options.

--save-style name

Saves the style of the last curve under the name name.

--use-style name

Uses a previously saved style for the next curve. Same provisions as for --same-style apply. If name has not been saved yet, it is interpreted as the number of the style we're interested in. 0 is the first, 1 the second, -1 the last, -2 the one just before and so on. --same-style is therefore equivalent to --use-style -1 (unless a style with name -1 has been saved beforehand).

--reset-override

Resets the current style override. See the section CURVE STYLES below for a detailed explanation of what are overrides.

--save-override name

The pendant of the --save-style option, but for overrides only. See CURVE STYLES below.

--use-override name

Uses a previously saved override. See CURVE STYLES below.

Shortcuts

--short shortcut

Uses the given shortcut. Shortcuts are a quick way to add many command-line arguments at once. See the SHORTCUTS section below.

--short-list

Lists available shortcuts, along with the command-line arguments they expand into.

Edges and axes looks

--xaxis style

--yaxis style

Gives some style informations about the X or Y axes and edges. Valid arguments are: left, right, top, bottom, org that place axes only on the corresponding sides (org is the origin) with no edges. both sets edges on both sides. hidden, line, ticks, major, majornum and full which select the style for both edges and axes (hidden, line only, line with major and minor ticks, major ticks only, major ticks with numeric labels, and major and minor ticks with numeric labels). You can specify several items separated by commas.

--no-axes

Disable all axes and edges for the current plot.

--lines-color axis color

Selects the color for drawing background lines corresponding to the named axis. Lines are starting from major ticks. If you use that with both the X and Y axis, you'll have a background grid.

LaTeX options

--use package

Adds a \usepackage{package} in the LaTeX preamble of the file. This can be very useful to depend on custom style files for fonts or to use standard or personal macros.

--preamble string

Adds the given string on a line of its own inside the LaTeX preamble. This can give basically any kind of customization that the --use option cannot. You are however strongly encouraged to use --use whenever it is possible.

Global appearance

--[no-]background color

Sets the background color of the current plot, or removes it altogether for the current plot.

--[no-]watermark TEXT

Adds a text watermark at the back of the plot.

--watermark-color COLOR

Sets the color for the watermark.

--aspect-ratio ratio

sets the aspect ratio of the plot (the ratio of it's length over it's height). Deprecated, do not use !

--golden-ratio

sets the aspect ratio to the golden number. Looks good. Deprecated, do not use !

--xrange range

--yrange range

sets the current X or Y plotting range; arguments are in the form left:right where left or right can be omitted. If you swap them, the plot will be swapped as well. NOTE: these settings are completely uncorrelated with the ones from the mathematical backend.

--margin margin

sets a margin around data when plotting. If your plot has many data points near the edge, try something between 0.01 and 0.05. See the MARGINS section below for more explanations about how to specify margins.

--rescale factor

scales the current picture by factor. This is especially useful for subplots and insets, but it can be used anywhere.

--padding padding

Sets the padding for the current object and subsequent ones to padding. The latter should be in the form of left,right,bottom,top or left,right,bottomandtop or leftandright,bottomandtop or all. Each of the elements can be a valid (absolute) TeX dimension, such as 10cm or 12pt, or a number, in which case the dimension is relative to the current graph (but be careful in grids, as it is relative to the whole graph, and not simply to the current element). See the section LAYOUT below for an explanation of what is the padding.

Subplots and assimilated...

--x2, --y2

Use an alternative x or y axis until the matching --end is encountered. Useful to plot, say, two different data that have different Y values but share the same X values.

--inset spec

Starts an inset at position spec. See the INSETS section for more details about the exact specification. The plot decorations (title, labels) are outside the box specified by spec.

--zoom-inset spec

This is very much like the --inset option, except that the new inset starts with all the curves that have already been added to its parent. This is really useful to zoom into particular places of the curves, using the --xrange and --yrange options. Legend is not added for the curves duplicated this way.

--next-inset spec

Leaves the current inset/subplot and starts a new inset at the given position. See the INSETS section for more details. NB: you need to --end the current --x2 or --y2 specification before using that, else you'll get rather unexpected results.

--subplot spec

--next-subplot spec

these two options have the same effet as --inset and --next-inset, with the exception that, unlike for insets, the decorations (title, labels) are inside the box delimited by spec.

--disable-legends

No legend will be taken into account after this switch for the current subplot.

--enable-legends

Reverts --disable-legends.

--grid spec

Start a grid with a number of column or rows given by spec, which can be either column=nb or row=nb. You start a new plot by using the --next option.

--col

Starts a column of plots sharing the same X range. New plots start with --next.

--[no-]auto-next, --auto-next-expanded

After the use of this option, ctioga considers that there is a --next before every single data set specification on the command-line (except the first one). The negation permits to cancel this behavior. With --auto-next-expanded, ctioga first performs dataset expansion and places --next before the resulting datasets.

--region

Starts a filled region. This is primarily used for filling space between curves. See the FILLED REGIONS section below for a more complete explanation.

--region-color color

Sets the color used for filling the current region.

--region-transparency transparency

Sets the transparency of the region's fill.

--region-dont-display

No curve in the region will be displayed. They will only be used to delimit the filled region.

--region-debug

Helps understanding how the filling works by tampering with the style of the plots inside the region to fill them so as to represent the actual clipping path: the filled region will be the one coloured by the colors of all the plots.

--region-invert-rule

Reverts the rule for delimiting the filling region. See the FILLED REGIONS section below.

--region-fill-twice

Fills the region twice, using opposite rules for determining the filling region. You really should have a look at the FILLED REGIONS section below to understand that. It will probably give better results in the case of intersecting curves.

--end

Ends the current subplot, grid, inset or region.

Labels and titles (including tick labels)

-x, --[no-]xlabel label

sets the x axis label of the current plot, or removes it.

-y, --[no-]ylabel [label]

sets the y axis label of the current plot, or removes it.

-t, --[no-]title [title]

sets the title of the current plot, or removes it.

--side what align

--lcolor what color

--position what where

--angle what angle

--scale what scale

--shift what shift

--align what align

--just what just

Sets respectively the side, color, position, angle, scale, shift, alignement or justification of the what label, where what can be either title, xlabel, ylabel, xticks or yticks.

Please note that the color attribute is not available for tick labels.

Legends and texts

-l, --[no-]legend [legend]

sets the legend of the next dataset, or removes it from the legend display.

--[no-]auto-legend

ctioga automatically provides default legends for plots that don't have one. This option allows one to turn this off and back on.

-N, --no-legends

are shortcuts for --no-auto-legend.

--[no-]separate-legends

For inclusion of a graph in an article, it is sometimes useful to be able to include the legend "pictogram" (the small image next to the text) directly from within the article, and not on the graph. With this option, automatic legending is turned off, and ctioga produces files of the form Plot_legend_00.pdf, Plot_legend_01.pdf, aso. which contains only the small pictograms. You can then include those in your article with the \includegraphics command to make your own in-text legend.

--fontsize nb

Sets the default TeX font size for text. It is passed directly to TeX without interpretation, so mistakes in this parameter might result in very cryptic error messages.

--legend-scale scale

Changes the default scale for the legends. This does influence the size of the text and the pictograms, and also to some extent the positioning of the legends.

--legend-pos spec

Sets the legend position on one of the side of the plot. spec is in the form side,size,delta where side is left, right, top, bottom, size is the fraction of the page that will be dedicated to the plot (best take it rather smaller than 1...) and delta, optional, is the fraction of the page that should be left blank between the legend and the plot itself.

--legend-inside spec

Position te legend inside the plot. The specification spec is the nearly same as for insets, see the INSETS section for more information.

--legend-dy dimension

The distance between two lines of the legend, in terms of the height of one text line.

--legend-line text

Adds a line of text without any pictogram to the legend.

--[no-]legend-frame [type]

If type is round or square, draws a (rounded or square) frame around the legends. Best used in combination with the vh:x,y --legend-inside specifications. If none, cancels the drawing of the frame.

--[no-]legend-color [color]

Sets the color of the frame to be drawn when --legend-frame is on, or cancels the drawing of the frame (this way, you can have a filled box without a line around).

--[no-]legend-background [color]

Sets the background color of the legend frame to color, or stops drawing a background for the legend frame. Works only when a legend frame is being drawn.

--[no-]legend-transparency [value]

Sets the transparency value for the background of the legend to value, or make the legend fully opaque.

--legend-line-width value

Sets the line width for drawing the frame around the legend.

--legend-line-style style

Sets the line style for drawing the frame around the legend.

Axis manipulations

--xfact f, --yfact f

Scales the x or the y values by a factor of f. This can be useful to change the units in a graph. If say, you have x data expressed in meters, but in the range of nanometers, you can use --x-fact 1e9 and use nanometers units...

--xoffset f, --yoffset f

Adds the f to the x or y values. This applies after multiplication by --xfact or --yfact, if the latter is applicable. Useful for instance to convert on the fly Celsius degrees to kelvins.

--[no-]xlog, --[no-]ylog

Swicthes on or off the log scale for the axes. These options must appear before any data set. ctioga
 will most probably fail if they don't.

Note: this option has no effect on the sample rate of the math backend. You probably want to use --math-log in addition to this to get a decent output when using the math backend.

--reset-transformations

Resets all the offset, scales and log options applied so far.

--comma, --decimal SEP

uses SEP as a decimal separator for axis (or a comma for --comma, obviously). It is based on LaTeX black magic, so it might fail from time to time. Please do report cases when it does.

Real size options

-r, --real-size size

Turns on the real size mode for ctioga. size should look like 10cmx12in. The PDF file produced will have exactly the size requested, with the plot filling as much as possible. You can include it in your documents with the TeX command \includegraphics.

--frame-margins margin

With the --real-size option, when the sizes are small, the text around the plot can be clipped off the graph. Try to set the margin a bit higher with this parameter (try something like 0.2, and go on increasing until you find something decent). Important note: with the new layout mechanism introduced in ctioga version 1.6, it is no longer necessary to use this option, except in the most desperate cases. See the section LAYOUT below.

Graphics primitives

--draw spec

Adds a graphic primitive to the current graph, using the specification spec. See the GRAPHIC PRIMITIVES section below for more details about the specifications.

--draw-help

Lists the graphic primitives currently known to ctioga, along with the options they currently handle and pointers to the appropriate functions in the Tioga documentation. By construction, the output of this function will always be a perfect reflection of the capabilities of ctioga.

Backend-related options

See the sections BACKENDS and FILTERS for more details.

--text

--text-skip

--text-baseline

--multitext

--multitext-skip

--math

--math-samples number

--math-xrange range

--smooth number

--sort

--filter-pop

--filter-clear

and more...

Miscellaneous options

--xpdf

runs xpdf on the PDF file produced to see the results.

--open

runs open on the PDF file produced to see the results.

--viewer viewer

opens the PDF file produced with viewer.

--no-viewer

cancels the opening of the file if requested earlier (such as in a configuration file, see next section).

--args file

Reads command-line arguments or options, one per line, from file. An option and its arguments must be on separated lines. This can be useful to avoid excessive quoting for complex plots

--[no-]cleanup

wether or not to remove all files created by the plot apart from the pdf output. This is not a good thing is case you want to include the picture inside a LaTeX file. In the latter case, you might want to prefer the next option. Important note: from ctioga version 1.5, this option is on by default (I'm fed up to always forget it and clean up manually afterwards).

--tex-cleanup

removes all files produced except the _figure.pdf and _figure.txt as those ones are used for inclusion in LaTeX documents using the \tiogafigure Tioga-provided commands.

--clean-all

removes all files produced, after displaying the PDF file produced (if you did ask to display something).

--include file

file is read and evaluated as ruby code. See next section for more informations.

--save-dir dir

files will be created in the directory dir rather than in the current directory.

--name name

the base name for files will be name rather than Plot.

--output name

Asks ctioga to write the figure created up to this flag to the file name.pdf just as if you had written --name name and stopped the command-line here. Further output is still produced. This can be used to create animations, such as:

ctioga --math 'sin(x)' --output One_sine 'cos(x)' --name Two_sines

which produces two files: One_sine.pdf that contains only the 'sin(x)' curve, and Two_sines.pdf that contains both 'sin(x)' and 'cos(x)' curves.

--display-commandline

the command-line used to make the plot is written in black at the bottom of the plot. No care is taken to ensure it doesn't overwrite any existing drawing. It can come in useful when sending image to someone or when one forgets too quickly how to make plots (which is the case of the author of ctioga). Now, ctioga includes by default the command-line as a comment of the produced PDF file. Tools like pdfinfo can be used to retrieve it, see the --mark command just below.

--[no-]mark

ctioga can fill the creator meta-information field of the produced PDF file with the command-line. This is a useful feature, as you can use pdfinfo(1) to see which command-line was used to produce a given file (it is also displayed in acroread(1)). However, it can sometimes prove to be painful, as the text is interpreted by TeX and causes funny errors. This is why it is switched off by default. You can turn it on (and back off) with this switch.

--echo

writes the ctioga command-line on standard output. Especially useful for examples found in the tests/ directory, but you might find uses for that too.

--quiet, --verbose, --debug

These options choose the verbosity level of ctioga. With --quiet, only errors are reported, while you get increasing amount of messages with --verbose which culminates in --debug. The latter is so full of information you'll probably never find anything unless you wrote ctioga.

--version

Writes the version of ctioga on standard output and exits.

Alternative outputs

--eps

With this option, ctioga does not call pdflatex, but rather transforms the intermediate PDF file into an EPS file using pdftops (from xpdf) and then calls latex followed by dvips to produce an EPS file. This results essentially in a difference in the type of the fonts used, and can ease the integration of ctioga graphs into pure LaTeX document (not generated with pdfLaTeX).

--png widthxheight

Runs ctioga as usual, but converts the produced PDF file into a PNG file of size widthxheight with the convert program from ImageMagick. The PDF file produced is not deleted. This option also changes the real size of the graph to match the size of the PNG file produced (on postscript point for one pixel). This can always be changed later on.

--png-oversampling nb

The conversion to PNG will use a resolution of nb times more pixels in each dimension before rescaling. The higher this number, the better the antialiasing will be. Output is fairly decent with numbers around 2 (the default) to 3. You might need to tweak this option if you use --real-size after the --png option.

--svg

Runs ctioga as usual, and then converts the produced PDF file into a SVG file using pdf2svg.

Debugging options

--debug

This options enables some debugging output, especially when things don't quite end up as expected. It is more designed for developpers, though. See above, too.

--debug-patterns

Produces two more graphes, called Test_patterns and Test_patterns_right that show if the alignment of the graphes produced by ctioga with the given command-line options are correctly aligned. If somehow you find that it is not, you should file a bug report (with the full command-line and the PDF files produced).

INSETS

Starting from release 1.8, ctioga provides three ways to specify the position of insets, subplots and inner legends:

x,y:w[xh]

centers the object at position x,y with a width of w and a height of h, or w if h was not specified. All values are from 0 to 1, relative to the container.

x1,y1;x2,y2

places the object with the exact border coordinates given by x1,y1 and x2,y2. As for the other ways, all positions are between 0 and 1 and relative to the container.

hxw[+|-]x[+|-]y

A X Geometry-like specification. The box will be of height h and of width w and the point x,y is the left (+) or right (-) top (+) or bottom (-) corner of the box.

Legend box

The --legend-inside can take an inset specification as argument. However, from version 1.9, it can also take another form:

vh:x,y

where v is the vertical centering (t for top, c for center and b for bottom), h is the horizontal centering (l for left, c for center and r for right), and x and y are the coordinates. For instance

--legend-inside tl:0.5,0.5

will place the top left of the legends at the exact center of the drawings.

Starting from ctioga version 1.10, it is possible to omit altogether the positions. To put the legend in the top left of the graph, simply use:

--legend-inside tl

LAYOUT

Since ctioga version 1.6, a relatively complex layout system has been incorporated to the code. The layout is responsible mainly for leaving enough space around plots so you can actually see labels and ticks. As of version 1.8, only one parameter of the layout system is accessible: something I call the padding. It represents the minimal amount of space that should be left on the sides of a graph. The actual space left may be bigger due to the presence of elements, such as labels. You can control it via the --padding option.

CONFIGURATION FILES

At startup, ctioga looks for a .ctiogarc file in the current directory and in the $HOME directory. This file is then read and evaluated as ruby code. The functions provided in this file are then made available to the backends. You can use it for two purposes:

*

define your own functions that can be called by backends such as the --math backend.

*

before starting to process the command-line, if a function ctioga_defaults is defined, ctioga runs it. It can be used to set default values for ctioga. You are strongly advised to look at the file plotmaker.rb to see what you actually can modify. This function is run in the context of the PlotMaker instance created.

*

before doing the actual plotting, ctioga looks for a function named ctioga_init and if it finds it, it calls it passing it the FigureMaker object used to make the plots. You can use that function to customize the appearance of the graphes. You will find Tioga's rdoc documentation really useful for doing so.

The files passed to ctioga with the --include option are treated exactly the same way, and in the order they are found. From the description above, you can guess that it's pretty useless to have a ctioga_defaults in such a file, as it will not be taken into account (although this could be interesting as well).

GRAPHIC PRIMITIVES

Starting from ctioga 1.4, it is now possible to add simple graphic elements to a graph, such as text labels, markers and arrows. It is additionally possible to add tangent to the last curve plotted. You should be somewhat familiar with the Tioga documentation to make the best of them, although simple use should be straightforward.

You use graphic primitives with the --draw option. It takes a single argument (a long one), which is further broken into separate words in the same way the shell would do it. This argument must have the following form:

what: mandatory arguments option1=thing option2=thing...

In this, what is the graphic primitive that can be used, the mandatory arguments must always be specified; they often are coordinates of meaningful points. Optional arguments follow a key=value syntax, and can be completely omitted. Their name is the same as in the dictionnary in the Tioga function. See the --draw-help command-line switch for a list of supported keys.

Points are specified using x,y values. Please note the absence of space between the coordinates.

ctioga understands the following primitives:

arrow: tail head

Draws an arrow from the point tail to the point head.

line: tail head

Same thing as the arrow primitive, excepted that arrow heads and tails are disabled by default.

hrule: point size

Draws a horizontal ruler at the given point of the given size.

vrule: point size

Draws a vertical ruler at the given point of the given size.

text: point text

Places a TeX text at the location point. Please note that you need to quote text if there are spaces or quotation marks inside.

marker: point marker

This is the pendant of text for markers.

tangent: spec

This is not strictly speaking a graphics primitive, but it comes in very handy to place tangents to a curve. See below for the meaning of spec. (not documented yet)

All these primitives accept additional options. It would be too long to describe them here, but the --draw-help option lists them all and gives pointers to the function in the Tioga documentation where you will find documentation about them.

For example, to place a piece of text at the origin, use

--draw 'text: 0,0 Some text '

Note the quotes within quotes around Some text. To do the same, but text tilting 45 degree from horizontal and with a nice (!) pink color, this would do:

--draw 'text: 0,0 Some text angle=45 color=Pink'

CURVE STYLES

ctioga has a pretty advanced mechanism for choosing a style for a curve. This mechanism has been designed to provide maximum flexibility while keeping the command-line to its minimal. Styles are the result of the interaction of two elements

*

the theme, which is providing a base for the style of a curve

*

the override, that is any style-related options that have been passed on the command-line.

When ctioga needs to know the style of the next curve, it first asks the theme to provide one. Usually, the styles provided by the themes will change at every curve. Then, the style is modified taking the override into account. A --color Red command-line option sets the color override to Red, which means that every single curve after that, until the override is changed, will be red.

A --color auto option removes the override for color, so that the actual color used is the theme's one.

The default override is to set the markers to no, so that by default no markers are present. The use of --reset-override restores the default override (which would remove markers...).

Finally, the --save-style option saves the style effectively used for the last curve. The --use-style option prevents ctioga from asking the theme to provide a base style, but rather uses the saved style as if the theme had provided it.

SHORTCUTS

Starting from ctioga 1.7, it is possible to use shortcuts on the command-line. Shortcuts are used with the --short option and expand into a series of command-line arguments. For instance, --short cloud expands into --marker auto --marker-scale 0.2 --line-style no, which is very convenient to make dot clouds. You can list available shortcuts along with what they expand to with the --short-list option. You can define shortcuts in your ~/.ctiogarc file with something in the spirit of

Shortcut.new('pink', '--color', 'Pink', '--marker-color', 'Pink')

This line defines a pink shortcut that expands to --color Pink --marker-color Pink. You use it simply by passing the --short pink option to ctioga. Better, if it does not conflict with existing options, you can use it directly as --pink.

passing Be sure to separate all arguments (which you would separate with spaces on the command-line) with commas, and to enclose them in single or double quotes. Failing to do so will most likely result in ctioga complaining about unknown options.

You can make sure ctioga sees these definitions with the --short-list option. If they don't show up there, you might have either a compilation problem in you ~/.ctiogarc file, or you simply didn't really write it there...

MARGIN SPECIFICATION

Several options accept a specification for margins. You need to remember that Tioga, and hence ctioga counts margins as a fraction of the total relevant length from the given side. So, if the right margin is at 0.2, it means that it will take the right 20% of the image. The specification is

left,right,top,bottom

where each of the component is a number between 0 and 1. All distances are always relative to the direct container: margins for the whole plot are relative to the size of the whole plot.

FILLED REGIONS

With the --region option, you start a filled region, which means that all subsequent plots until the next --end option will serve, in addition to be displayed normally, as a way to delimit the region where the fill will occur, according to the following simple rule: every odd plot will be closed by a line at the top of the figure, every even one by a line at the bottom. The resulting path will be used as a clipping path for the region. To understand which region will be filled, imagine that every curve is filled in the normal way to the top or the bottom of the plot. The colored region will be the one filled by all curves. The --region-debug does precisely this and can be of a really great help to understand what is actually happening.

If the --region-invert-rule option is in order, the above rule gets reversed: every odd plot is closed to the bottom and every even one to the top. With the --region-fill-twice option, the region is filled twice, once with each rule.

To make simple things simple, if you just want to be filling the space between two non-intersecting curves, just put the lower one firs or use --region-invert-rule if you don't want that. For relatively simple intersecting curves, you might want to try --region-fill-twice, as it tends to do what one wants (in my humble opinion).

For more complex stuff, you can use the --region-dont-display to specify complex shapes and clip them. You can use multiple --region to get the desired effect.

BACKENDS

ctioga is based on the concept of Backends. Backends are classes that deal with acquiring the data. This can mean generate the data on the fly (like what the math backend does), reading it from a text file (the text) backend or from binary files or databases (backends yet to be written). For some backends, you can provide additional information with command-line switches. For some, a given set of command-line switches are necessary for good operation (not applicable yet).

Set expansion

Most of the backends come with a feature called set expansion : it is possible to compactly transform a single set specification into several different data sets. For instance, file@1:2##4 is transformed into file@1:2 file@1:3 file@1:4.

There are three patterns recognised by most of the backends:

n##m

where n and m are numbers, is expanded into all the numbers from n to m included.

#<n<code>m>

is expanded into the Ruby code code with variable i ranging from n to m. The value the block is returning is replaced in the set specification. This way, #<1<i**2>4> expands into 1 4 9 16. Please note the absence of spaces around n and m.

#<var=n<code>m>

Although it looks very much like the previous one, this one is much easier to work with: the previous expands to a block of Ruby code, which means that you're likely to get into compilation errors. This way, however, expands the string code, replacing any occurence of the variable named var by an integer value from n to m. Contrary to the previous expressions, you can put arbitrary spaces.

The second and third expansions, though in appearance very similar, have completely different applications.

The second, #<var=n<code>m>, works with a real Ruby expression that must return a String object, or something that can be cast to a String, such as a number. This expansion can be used for instance to plot every second column of a file, using the following specification:

ctioga file.dat@'1:#<2<i*2>6>'

ctioga will expand that to the value of the expression i*2 with i ranging from 2 to 6. What we obtain is:

ctioga file.dat@'1:4' file.dat@'1:6' ... file.dat@'1:12'

The second expansion is well adapted to dirty tricks about data files. In principle, it is the most powerful expansion, as you get full ruby interpretation. But it can be delicate, as you need to think in terms of Ruby expressions.

On the other hand, in the third, #<var=n<code>m> you define a variable whose name will be replaced by all the numbers from n to m. In particular, we can't try the same trick as above: using

ctioga file.dat@'1:#<n=2<n*2>6>'

will result in ctioga expanding that into:

ctioga file.dat@'1:2*2' file.dat@'1:3*2' ... file.dat@'1:6*2'

which is completely different than above. On the other hand, this expansion is much more suited to change a parameter that must appear in several places in the expansion, such as the followin:

ctioga --math '#<n = 2< sin(n*x)/n>10>'

which plots sin(n*x)/n for all n values from 2 to 10.

That is possible to do with the second expansion, but it is way heavier:

ctioga --math '#<2<sin(#{i}*x)/#{i}>10>'

Note that the quotes are necessary, as we want to get a ruby string, and not the result of the computation of sin(i*x)/i, which will most likely result in a Ruby error, because it does not know about any x.

The text backend

Select it with the option --text. It accepts four options:

--text-skip number

when reading subsequent files, the file number lines of the file are skipped.

--text-baseline set

this specifies that set should act as a baseline for every subsequent set. That is, the Y values of this set will be substracted to every single subsequent set. Use no to cancel baseline.

--text-col spec

which column specification to use in case no one is specified. No expansion is performed here.

--text-separator regexp

a Ruby regular expression that designates the column separator. For instance, for CSV files, you could use , or ; or, even better '/[,;]/'.

It reads text files in a simple format (numbers separated with spaces) and seperates them in columns. The first column in the file is 1, and so on. You can access to the index of the line with the column number 0 (like in gnuplot).

The general syntax of a data set is file@x_col:y_col with the following meaning:

file

is the name of the file where the data is. If it is omitted, the last file opened by the backend is used.

x_col:y_col

are column specifications. If they are simple numbers, the corresponding columns are used: 3:1 asks to plot the first column as a function of the third. On the contrary if they contain at least one $ sign, then they are interpreted as a function of the columns, where $n represents the nth column: $2**2:$1*$3 asks to plot the product of column 1 and 3 as a function of the square of the second. Arbitrary expressions can be used, as well as functions defined in configuration or included files. Please note that in the latter case you will most probably need to quote the arguments with single quotes to prevent the shell from tampering with your arguments.

If the @x_col:y_col is omitted, then it defaults to @1:2, or the the value given to the --text-col option if the latter was specified before.

The text backend supports an extansion to the set expansion mechanism described earlier, in that you can ommit the trailing number in a n##m specification. In this case, the last digit is taken to be the number of the last column in the file. If file.dat has 4 columns, file.dat@1:2## is exactly equivalent to file.dat@1:2##4.

Starting from ctioga version 1.4, the text bacjend supports error bars. You do it using extra column specifications, such as in the following:

file.dat:1:2:xeabs=3:yeabs=4

This column specification means that column 3 will be taken as absolute errors on the x values and column 4 as the absolute error on the y values, both of the being symmetric: for y, for instance, you get the value in the column 2 plus or minus the one in column 4 as an error bar.

Quite a few different specifiers are available in place of xeabs and yeabs. For instance, for x error bars:

xeabs

specifies an absolute symmetric error

xeup

specifies the absolute error above the x values.

xedown

the absolute error below the x values.

xerel

plays the same role as xeabs but for relative values (expressed in fractions of the corresponding value).

xerdown and xerup

are the equivalent of xeup and xedown for relative values.

xmin

and xmax directly specify the position of the left and right position of the error bar.

The yeabs and so on are the pendant of the xeabs for the y values. Specifications can be abbreviated to the smallest unambiguous possibilities.

--[no-]text-split

Starting from version 1.9, at the request of Ivars Finvers, it is possible to separate a text file into subsets at blank lines, a bit like what gnuplot is doing. Subsets can be reached using a syntax in the spirit of

ctioga --text-split file.dat#12

that shows the 12th subset of file.dat.

The multitext backend

Select it with the option --multitext. It recognizes the option --multitext-skip which is the equivalent of --text-skip. It exists to provide the ability of plotting columns from different data files and works similarly to the --text backend with a stricter syntax:

[file1@x_col]:[file2@y_col]

Nothing can be ommited, especially not the square braces. Nevertheless, it can handle arbitrarily complicated mathematical expression such as

[file1@x_col1]-[file2@x_col2]:[file3@y_col1]/[file4@y_col2]

Note that the files should all have the same number of lines and that you should avoid for example division by 0. You will also need to quote the arguments to avoid shell expansion.

The expansion mechanism explained in the text backend also works, with the exception that the last column has to be specified.

The math backend

Select it with the option --math. It accepts two options

--math-xrange range

specifies the range over which to plot, in the form xmin:xmax

--math-samples number

the number of points used for the computation. They are distributed homogeneously in the range.

--[no-]math-log

with this option, the samples are spaced logarithmically instead of linealy. Good in combination with --xlog.

You can use arbitrary functions of x with this backend, such as sin(x), x**2 + 2*x, etc... You will probably need to quote the arguments to prevent shell expansion.

The gnuplot backend

This backend is an attempt to use files that make plots with gnuplot. In particular, it can be really useful to write a series of functions and fits using gnuplot, profiting from its abilities while benefitting from ctioga's better-looking output.

In short, this backend sends the file to gnuplot and intercept its output with the table terminal. You should not have to modify the original file to use with ctioga, but that might fail some times (please file a bug report then).

Note : this is just a backend, and in its way it will only provide ctioga with data. In particular, all formatting options in the gnuplot file are lost !

You select it with the --gnuplot option.

Options:

--gnuplot-range range

overrides range specification for plots from the file

--gnuplot-vars vars

a colon-separated list of variables that will override the ones from the file.

For the examples, we'll use the following ctioga.gnuplot file:

set term postscript a = 10 b = 4 plot [2:12] x**2 - a*x + b

It can be found in the examples/ directory in the source tarball. Try this:

ctioga --gnuplot ctioga.gnuplot

ctioga --gnuplot --gnuplot-range -2:2 ctioga.gnuplot

ctioga --gnuplot ctioga.gnuplot --gnuplot-vars 'a=11; b=3' ctioga.gnuplot

FILTERS

Each backend can have as many filters as you wish. They are applied in the order with which they come on the command-line. You can view it as a stack where the bottom filters are applied first, and new filters go on top. Each backend has its own stack.

--filter-pop

Pops the last filter pushed onto the current backend's stack.

--filter-clear

Clears all filters of the current backend.

--smooth number

Applies a gaussian-like convolution filter of size number onto the data. For better results, number should be odd to have a clear middle for the convolution kernel.

--sort

Sorts the X data.

--trim number

Keeps only one point every number in the data. Useful to reduce PDF size and displaying time for curves with wild oversampling.

--norm

Normalizes the input data so that the maximum absolute value is 1. It does not change its sign.

--cumulate

Sums all points as they are read. Do not mistake this for integration.

--strip

Strips all points that are not NaN, mostly useful with ctable (1).

--avgdup

Averages all Y values of the same X value. Sorts data at the same time.

--stddev

Averages successive Y values with the same X value, and set error bars to reflect standard deviation around the average. Dead useful.

AUTHOR

ctioga was written by Vincent Fourmond with the help of Jean-Julien Fleck. Tioga was written by Bill Paxton.