NAME
ctioga - a command-line front-end for the Tioga plotting library
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.
ENVIRONMENT VARIABLE
If a CTIOGA environement variable is found, it is taken as a part of
the command line, with some differences however:
* it is parsed before the command line;
* if a --include file option is present, the file’s ctioga_defaults
function will be taken into account;
* it’s contents don’t show up in the --display-commandline display.
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.
BUGS
ctioga is most certainly not bug-free. You can use the facility at
rubyforge.org to report any bug you notice:
http://rubyforge.org/tracker/?func=add&group_id=1477&atid=5773. You
can also use the same facility for feature requests.
SEE ALSO
xpdf(1), pdflatex(1), open(1), gnuplot(1)
On debian systems, you will find some data files, some commented
examples of configuration files and most importantly a tutorial along
with a tutorial.sh shell script demonstrating the commands used in the
tutorial in the /usr/share/doc/ctioga/examples directory. Please note
that you will need to copy this files somewhere where you have write
access to be able to run the tutorial (or use some Tioga magic changing
the output dir).
It also includes a tests/ directory containing test shell scripts.
Runnning these shell scripts should give you a decent idea of ctioga’s
possibilities while assuring that it did install properly.
Useful documentation, including an illustrated version of the tutorial
and instructions on bug reporting, can be found on ctioga’s website, at
http://sciyag.rubyforge.org/ctioga.
More information about Tioga and its rdoc documentation can be found at
http://www.kitp.ucsb.edu/~paxton/tioga.html