table of contents
CTIOGA2(1) | Command-line interface for Tioga | CTIOGA2(1) |
NAME¶
ctioga2 - a command-line front-end for the Tioga plotting librarySYNOPSIS¶
ctioga2 arguments ...DESCRIPTION¶
ctioga2 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. The main feature that was introduced compared to the old ctioga is that it is now possible to use command files for ctioga2: every single command-line option corresponds to a command, whose name is written. Just give the command the same arguments as to the command-line option. To read a command file, feed it to the -f command-line option.EXAMPLES¶
Here are a few examples, both from command-line and using the corresponding files.- ctioga2 File.dat
- Produces a file Plot.pdf showing the second column of File.dat as a function of the first.
#!/usr/bin/env ctioga2 -f
plot(File.dat)
OPTIONS¶
Plots¶
Plots- --plot DATASET
- Use the current backend to load the given datasets onto the data stack and
plot them. It is a combination of the load and the plot-last
commands; you might want to see their documentation.
- -p, --plot-last
- Plots the last dataset pushed onto the data stack (or the one specified
with the which option), with the current style. All aspects of the curve
style (colors, markers, line styles...) can be overridden through the use
of options.
Curves styles¶
Set stylistic details of curves or other object drawn from data- --[no-]clipped
- Sets the clipped for subsequent curves, until cancelled with auto as
argument.
- -c, --color COLOR-OR-FALSE-OR-AUTO
- Sets the line color for subsequent curves, until cancelled with auto as
argument.
- --color-map COLORMAP-OR-AUTO
- Sets the color map for the subsequent curves, until cancelled by an auto
argument.
Color maps are used for 3D plots, ie under the effet of contour,
xyz-map and xy-parametric.
- --color-set COLOR-OR-FALSE-SET
- Chooses a set for the line color of subsequent curves. Also sets
color to auto, so that the set takes effect immediately
- --[no-]contour-conrec
- If on, the subsequent curves will use the CONREC algorithm for contouring.
In the opposite case, the contouring algorithm of Gri is used.
Only useful when contour is in effect.
- --contour-minor-number INTEGER-OR-AUTO
- Sets the number of minor level lines between major ones (approx) for
subsequent curves, until cancelled with auto as argument.
- --contour-minor-scale FLOAT-OR-AUTO
- Sets the relative scale of minor level lines for subsequent curves, until
cancelled with auto as argument.
- --contour-minor-style LINE-STYLE-OR-AUTO
- Sets the minor ticks line style for subsequent curves, until cancelled
with auto as argument.
- --contour-number INTEGER-OR-AUTO
- Sets the overall number of level lines for subsequent curves, until
cancelled with auto as argument.
- --depth INTEGER-OR-AUTO
- Sets the depth for subsequent curves, until cancelled with auto as
argument.
- --error-bar-color COLOR-OR-FALSE-OR-AUTO
- Sets the error bar color for subsequent curves, until cancelled with auto
as argument.
- --error-bar-color-set COLOR-OR-FALSE-SET
- Chooses a set for the error bar color of subsequent curves. Also sets
error-bar-color to auto, so that the set takes effect immediately
- --fill FILL-UNTIL-OR-AUTO
- Sets the Fill until for subsequent curves, until cancelled with auto as
argument.
- --fill-color COLOR-OR-AUTO
- Sets the fill color for subsequent curves, until cancelled with auto as
argument.
- --fill-color-set COLOR-SET
- Chooses a set for the fill color of subsequent curves. Also sets
fill-color to auto, so that the set takes effect immediately
- --fill-set FILL-UNTIL-SET
- Chooses a set for the Fill until of subsequent curves. Also sets
fill to auto, so that the set takes effect immediately
- --fill-transparency FLOAT-OR-AUTO
- Sets the fill transparency for subsequent curves, until cancelled with
auto as argument.
- --fill-transparency-set FLOAT-SET
- Chooses a set for the fill transparency of subsequent curves. Also sets
fill-transparency to auto, so that the set takes effect immediately
- --line-style LINE-STYLE-OR-AUTO
- Sets the line style for subsequent curves, until cancelled with auto as
argument.
- --line-style-set LINE-STYLE-SET
- Chooses a set for the line style of subsequent curves. Also sets
line-style to auto, so that the set takes effect immediately
- --line-width FLOAT-OR-AUTO
- Sets the line width for subsequent curves, until cancelled with auto as
argument.
- --line-width-set FLOAT-SET
- Chooses a set for the line width of subsequent curves. Also sets
line-width to auto, so that the set takes effect immediately
- -m, --marker MARKER-OR-AUTO
- Sets the marker for subsequent curves, until cancelled with auto as
argument.
- --marker-color COLOR-OR-AUTO
- Sets the marker color for subsequent curves, until cancelled with auto as
argument.
- --marker-color-map COLORMAP-OR-AUTO
- Sets the color map for markers for subsequent curves, until cancelled with
auto as argument.
- --marker-color-set COLOR-SET
- Chooses a set for the marker color of subsequent curves. Also sets
marker-color to auto, so that the set takes effect immediately
- --marker-min-scale FLOAT-OR-FALSE-OR-AUTO
- Sets the marker scale for subsequent curves, until cancelled with auto as
argument.
- --marker-scale FLOAT-OR-AUTO
- Sets the marker scale for subsequent curves, until cancelled with auto as
argument.
- --marker-scale-set FLOAT-SET
- Chooses a set for the marker scale of subsequent curves. Also sets
marker-scale to auto, so that the set takes effect immediately
- --marker-set MARKER-SET
- Chooses a set for the marker of subsequent curves. Also sets marker
to auto, so that the set takes effect immediately
- --path-style TEXT-OR-AUTO
- Sets the path style for subsequent curves, until cancelled with auto as
argument.
- --path-style-set TEXT-SET
- Chooses a set for the path style of subsequent curves. Also sets
path-style to auto, so that the set takes effect immediately
- --region-side REGION-SIDE-OR-AUTO
- Sets the region side for subsequent curves, until cancelled with auto as
argument.
- --region-side-set REGION-SIDE-SET
- Chooses a set for the region side of subsequent curves. Also sets
region-side to auto, so that the set takes effect immediately
- --[no-]split-on-nan
- In general, the NaN (not a number, ie invalid data points in the dataset)
in a dataset are silently ignored. When this option is on, the lines of
xy-plot-style plots are split upon encountering a NaN.
- --zaxis TEXT-OR-AUTO
- Sets the name of the zaxis for the subsequent curves. This must be an axis
that has been previously created using new-zaxis.
This axis will be used to display the colormaps of the following curve.
Legends¶
Commands to specify legends and tweak their look.- --[no-]auto-legend
- When this option is in effect (off by default), all datasets get a legend,
their 'dataset name', unless another legend is manually specified.
- -l, --legend TEXT
- Sets the legend for the next dataset. Overridden by the legend option to
the plot command.
- --legend-inside ALIGNED-POINT
- Using this command sets the position of the legends for the current
(sub)plot inside it, at the precise location given.
As a shortcut, legend-inside also takes all the options that
legend-style takes, with the same effect.
- --legend-line TEXT
- Adds a line of text unrelated to any curve to the legend.
The options controlling the aspect of the legend are documented in the
define-text-style command.
- --legend-multicol
- Following legends will be layed out in multiple columns, until a call to
legend-multicol-end.
- --legend-multicol-end
- Stop layout out legends in several columns
- --legend-style
- Sets the various aspects of the style of the legends throught its options:
- *
- dy: the spacing between the baseline of consecutive lines; it is deprecated now in favor of vpadding;
- *
- vpadding: the space left between the bottom of a line and the top of the next one;
- *
- scale: the overall scale of the legends
- *
- text-scale: the scale of the text (and the markers) inside the legends
- The frame- options control the drawing of a frame around the legend; they
have the same meaning as corresponding ones of define-box-style
with the frame- bit dropped.
Switch between different kinds of plots¶
How to switch between different kinds of plot types- --contour
- Switch to contour plots for later curves. Contour plots need three columns
(X,Y,Z). They have major and minor lines.
- --histogram
- Switch to drawing histograms.
- --xy-parametric
- Switch to XY parametric plots, that is standard XY plots whose appearance
(such as color, marker color, and, potentially, marker kinds and more) are
governed by one (or more ?) Z values.
- --xy-plot
- Switch (back) to standard XY plots (ctioga's default)
- --xyz-map
- Switch to XYZ maps, ie plots where the color at a XY location is given by
its Z value.
Plot coordinates¶
Plot coordinates- --margin FLOAT
- Leaves a margin around the data points. Expressed in relative size of the
whole plot.
- --xfact FLOAT
- Alias for xscale.
- --[no-]xlog
- Uses a logarithmic scale for the X axis.
- --xoffset FLOAT
- Adds the given offset to all X coordinates.
- --xrange PARTIAL-FLOAT-RANGE
- Sets the range of the X coordinates.
- --xscale FLOAT
- Multiplies the X coordinates by this factor.
- --yfact FLOAT
- Alias for yscale.
- --[no-]ylog
- Uses a logarithmic scale for the Y axis.
- --yoffset FLOAT
- Adds the given offset to all Y coordinates.
- --yrange PARTIAL-FLOAT-RANGE
- Sets the range of the Y coordinates.
- --yscale FLOAT
- Multiplies the Y coordinates by this factor.
Graphics primitives¶
Tioga graphics primitives- --draw DRAWING-SPEC
- Tries to emulate the old --draw behavior of ctioga. Don't use it for new
things.
- --draw-arrow POINT POINT
- Draws arrow on the current plot, using the given style. For more
information on the available options, see the define-arrow-style
command.
- --draw-box POINT POINT
- Draws box on the current plot, using the given style. For more information
on the available options, see the define-box-style command.
- --draw-color-list POINT DIMENSION
- Directly draws the list of all named colors on the current plot
- --draw-color-set-list POINT DIMENSION
- Directly draws the list of all color sets on the current plot
- --draw-contour LEVEL
- Directly draws contour on the current plot
- --draw-image FILE TOP-LEFT BOTTOM-RIGHT
- Draws image on the current plot, using the given style. For more
information on the available options, see the define-image-style
command.
- --draw-line POINT POINT
- Draws line on the current plot, using the given style. For more
information on the available options, see the define-line-style
command.
- --draw-line-style-list POINT DIMENSION
- Directly draws the list of all named line styles on the current plot
- --draw-marker POINT MARKER
- Draws marker on the current plot, using the given style. For more
information on the available options, see the define-marker-style
command.
- --draw-marker-list POINT DIMENSION
- Directly draws the list of all named markers on the current plot
- --draw-marker-set-list POINT DIMENSION
- Directly draws the list of all marker sets on the current plot
- --draw-string-marker POINT TEXT
- Draws marker on the current plot, using the given style. For more
information on the available options, see the define-marker-style
command.
- --draw-tangent DATA-POINT
- Directly draws tangent on the current plot
- --draw-text POINT TEXT
- Draws text on the current plot, using the given style. For more
information on the available options, see the define-text-style
command.
The 'direct' backend: Direct format¶
The commands in this group drive the behaviour of the direct backend; see its documentation for more information- --direct
- Selects the 'direct' backend
The 'gnuplot' backend: Gnuplot files¶
The commands in this group drive the behaviour of the gnuplot backend; see its documentation for more information- --gnuplot
- Selects the 'gnuplot' backend
- --gnuplot-range RANGE
- The plotting X range, such as 0:2
- --gnuplot-samples SAMPLES
- The number of samples
- --gnuplot-vars VARS
- A colon-separated override of local variables, such as a=1;b=3;c=5
The 'math' backend: Mathematical functions¶
The commands in this group drive the behaviour of the math backend; see its documentation for more information- --math
- Selects the 'math' backend
- --[no-]math-log
- Space samples logarithmically
- --math-samples SAMPLES
- The number of points
- --math-trange TRANGE
- T range (a:b) (parametric plot)
- --math-xrange XRANGE
- X range (a:b)
The 'text' backend: Text format¶
The commands in this group drive the behaviour of the text backend; see its documentation for more information- --csv
- Now parse the following data files as CSV.
text /separator=/[,;]/
- --text
- Selects the 'text' backend
- --text-col COL
- Which columns to use when the @1:2 syntax is not used
- --text-header-line HEADER-LINE
- Regular expression indicating the header line (containing column names)
(default /^##/
- --text-parameters PARAMETERS
- Regular expression for extracting parameters from a file. Defaults to nil
(ie nothing)
- --text-separator SEPARATOR
- The columns separator. Defaults to / +/
- --text-skip SKIP
- Number of lines to be skipped at the beginning of the file
- --[no-]text-split
- If true, splits files into subsets on blank/non number lines
LaTeX¶
Commands providing control over the LaTeX output (preamble, packages...)- --preamble TEXT
- Adds the given string to the LaTeX preamble of the output.
- --set-global-font
- Set global font. Sets the size of everything, including that of text that
has already been used.
- --use TEXT
- Adds a command to include the LaTeX package into the preamble. The
arguments, if given, are given within [square backets].
- --utf8
- Makes ctioga2 use UTF-8 for all text. It is exactly equivalent to the
command preamble with the argument:
sepackage[utf8]{inputenc}sepackage[T1]{fontenc}
Subplots and assimilated¶
Subplots and assimilated- --end
- Leaves the current subobject.
- --frame-margins FRAME-MARGINS
- Sets the margins for the current plot. Margins are the same things as the
position (such as specified for and inset). Using this within an inset or
more complex plots might produce unexpected results. The main use of this
function is to control the padding around simple plots.
- --gradient COLOR COLOR
- All the curves between this command and the corresponding end will
have their color set to a weighted average of the colors given as
argument. This gives a neat gradient effect.
- --inset BOX
- Starts a new inset within the given box.
If no graph has been started yet, it just creates a new graph using the
given box. In short, it does what it seems it should.
- --next-inset BOX
- Has the same effet as end followed by inset.
Particularly useful for chaining subgraphs. In that case, you might be
interested in the grid box specification and setup-grid.
- --padding DIMENSION
- When the frame-margins is set to automatic, ctioga2 leaves that
much space around the plot on the sides where there are no labels.
- --plot-scale FLOAT
- Applies a scaling factor to the whole current subplot. Depending on the 'what' option (default text), the scale applies to:
- *
- text ('text' or 'both')
- *
- marker size ('text' or 'both')
- *
- line widths ('lines' or 'both') Scaling also applies to all elements of the plot that were added before the call to plot-scale.
- --region
- The curves up to the corresponding end will be considered for
delimiting a colored region between them. The actual position of the
curves with respect to the region can be fine-tuned using the
region-side command (or the corresponding option to plot).
- --setup-grid TEXT
- Sets up a grid of the given layout (such as 2x1). After this command,
arguments such as grid:0,1 can be used as the box argument of
inset and next-inset commands.
Alternatively, the layout can be specified as 1,2,1x1,4, in which case there
are three columns and two rows; the second column is 2 times larger than
the other ones, while the second row is four times larger than the first.
- --text-adjust-mode TEXT-ADJUST-MODE
- When this is on (the default), ctioga2 tries to be smart about the size of
the text bits around the plot. However, this can be bothersome at times,
so you can disable that with this command.
Axes and labels¶
Axes and labels- --axis-style AXIS
- This command can be used to set various aspects of the style of the given
axis, through its various options, which are documented in more details in
the define-axis-style command -- excepted for the ticks bit which
are documented in the ticks command.
If the option also-axes is specified, the style is also applied to the
comma-separated list of axes it contains.
- --background-lines AXIS COLOR-OR-FALSE
- Sets the color of the background lines for the given axis.
- --bottom AXIS-DECORATION
- Sets the type of the bottom axis.
The options have the same meaning as for define-axis-style, see that
command for more information.
- --clear-axes
- Removes all the axes and their associated labels
- --drawing-frame
- Setup a drawing frame, ie a frame in which the top-left point is at 0,0,
with X and Y values positive over the whole frame, and counted in
centimeters (or with the unit given using the /units option, ie /units=mm
expressed in millimeters or /units=12pt expressed in multiple of 12 TeX
points).
- --label-style LABEL
- Sets the style of the given label (see the type label for more
information). See define-text-style for detailed information about
the meaning of the options.
The option text permits to also set the text of the label (does not work for
ticks).
For tick labels, setting the color option also sets the color for the lines
of the corresponding axis. If you don't want that, you can override the
color using the stroke-color option of axis-style. This will only
work with Tioga version 1.11 or greater.
- --left AXIS-DECORATION
- Sets the type of the left axis.
The options have the same meaning as for define-axis-style, see that
command for more information.
- --new-zaxis TEXT
- Creates a named Z axis that can display information from Z color maps
- --no-title
- Removes the title of the current plot.
- --no-xlabel
- Removes the X label for the current plot.
- --no-ylabel
- Removes the Y label for the current plot.
- --right AXIS-DECORATION
- Sets the type of the right axis.
The options have the same meaning as for define-axis-style, see that
command for more information.
- --ticks AXIS
- This command can be used to control the location of major and minor ticks and the text of their labels for the given axis. Options available:
- *
- format the format of the tick labels, using a sprintf-like syntax (see below)
- *
- format-last the format of the last of the tick labels (useful to include an overall "power-of-ten" factor
- *
- major a space or comma-separated list of the positions of the major (labeled) ticks
- *
- minor same for the minor ticks
- *
- label a comma-separated list of the tick labels (must be the same number of elements as that of the major list). If you must include a comma inside, then use || as a separator.
- Format is a normal sprintf format, with the following additional special codes:
- *
- %p the "common power of 10": if you divide the tick values by 10 to the power %p, the smallest absolute value will be between 1 and 10 (excluding 0 of course)
- *
- %b... is the tick value divided by this common power of 10. You *must* follow this spec by a usual sprintf format: %b.3g would get you a number with 3 significant digits
- -t, --title TEXT
- Sets the title of the current plot.
- --top AXIS-DECORATION
- Sets the type of the top axis.
The options have the same meaning as for define-axis-style, see that
command for more information.
- --x2
- Switches to using the top axis for X axis for the subsequent curves, and
turns on full decoration for the right axis. Shortcut for:
xaxis top
axis-style top /decoration=full
- --xaxis AXIS
- Sets the default axis for the X axis for all subsequent commands take rely
on default axes (such as plot, xrange, yrange...).
- -x, --xlabel TEXT
- Sets the X label of the current plot.
- --y2
- Switches to using the right axis for Y axis for the subsequent curves, and
turns on full decoration for the right axis. Shortcut for:
yaxis right
axis-style right /decoration=full
- --yaxis AXIS
- Sets the default axis for the Y axis for all subsequent commands take rely
on default axes (such as plot, xrange, yrange...).
- -y, --ylabel TEXT
- Sets the Y label of the current plot.
Background¶
Commands dealing with the aspect of the background of a plot (excluding background lines, which are linked to axes).- --background COLOR-OR-FALSE
- Sets the background color for the current (and subsequent?) plot.
- --watermark TEXT
- Sets a watermark for the background of the current plot.
Default styles¶
Commands for defining default styles. All commands take the name of the style to redefine. Different styles live in a different name space, so there is no risk naming an axis and a text style with the same name. All styles for a given type inherit from the style name base. ctioga2 does not support changing a style after its use. It may affect only the following objects or all the ones that were created from the beginning, depending on the context. For safety, only define style before issueing any graphics command. ctioga2 may support at a later time loading style files, but that is not the case for now.- --define-arrow-style TEXT
- Sets the default style for arrows. All arrow styles descend from the base style. Use a style different than base by passing its name as the /base-style option to the draw-arrow command. Meaning of the style parameters:
- *
- color, style and width: same as in define-line-style
- *
- head-marker, tail-marker: a marker to be used for the head or for the tail
- *
- head-scale, tail-scale: scale of the head or tail markers
- *
- head-angle, tail-angle: rotate the head or the tail by that many degrees
- *
- head-color, tail-color: the color of the head or tail
- --define-axis-style TEXT
- Sets the style for a whole axis. All axis styles descend from the base style. Horizontal and vertical axis styles descend from the x and y styles, and plot sides are styled with the left, right, top and bottom styles. Axis styles have lots of parameters:
- *
- axis-label- and tick-label- parameters are title style parameters whose meaning is given in define-title-style, that affect ticks and axis labels
- *
- decoration: a axis-decoration that specify which ticks and tick labels to draw
- *
- background-lines- parameters define the style of background lines, as in define-line-style
- --define-background-style TEXT
- Sets the style for plot background. All background styles descend from the base style. In addition, the background of a plot is change by the style name background. Meaning of the style parameters:
- *
- watermark: the text of the watermark
- *
- all watermark_ styles have the same meaning as in define-text-style, as the watermark is a string marker
- *
- background_color: the color of the background
- --define-box-style TEXT
- Sets the default style for boxes. All box styles descend from the base style. Use a style different than base by passing its name as the /base-style option to the draw-box command. Meaning of the style parameters:
- *
- color, style and width: same as in define-line-style
- *
- fill-color: fill color for the box
- *
- fill-transparency: the transparency for the fill, from 0 to 1
- --define-image-style TEXT
- Sets the default style for the named image.
- --define-line-style TEXT
- Sets the default style for lines. All line styles descend from the base style. Use a style different than base by passing its name as the /base-style option to the draw-line command. Meaning of the style parameters:
- *
- color: the color of the line, see color
- *
- style: the line style, see line-style
- *
- width: the line width (in points)
-
--define-line-style base /color=Pink makes all lines pink (unless overriden by the /color option to draw-line), while
--define-line-style line-pink /color=Pink only affect those to which the /base-style=line-pink style option was given.
- --define-marker-style TEXT
- Sets the style for marker and marker strings. All marker and marker string styles descend from the base style. Use a style different than base by passing its name as the /base-style option to the draw-marker or draw-string-marker commands. Meaning of the style parameters:
- *
- alignment, justification, angle, color and scale: as in define-text-style
- *
- fill-color and stroke_color: markers are both stroked and filled, you can control all colors in one go using color or specifying each with fill-color and stroke_color
- *
- font: is a PDF font number (from 1 to 14), only used for marker strings
- *
- horizontal-scale, vertical-scale: scales the marker only horizontally or vertically
- --define-text-style TEXT
- Sets the default style for texts. All text styles descend from the base style. Use a style different than base by passing its name as the /base-style option to the draw-text command. Meaning of the style parameters:
- *
- alignment: vertical alignment
- *
- justification: horizontal alignment
- *
- angle: angle in degrees to the horizontal (or default orientation in some cases)
- *
- color: text color
- *
- scale: text scale
- --define-title-style TEXT
- Sets the style for title. All title styles descend from the base style. In addition, the title of a plot is addressed by the style name title. Meaning of the style parameters:
- *
- alignment, justification, angle, color and scale: as in define-text-style
- *
- text: sets the title text
- *
- loc: the side on which to display the title, a location
- *
- shift: the distance away from the plot in text size units (maybe a dimension should be better later)
- *
- position: shift from the center (parallel to the plot side)
Output setup¶
Commands in this group deal with various aspects of the production of output files:- *
- output file location
- *
- post-processing (including automatic display)
- *
- cleanup...
- --[no-]clean
- When this is on (the default), ctioga2 automatically cleans up
intermediate files produced by Tioga. When LaTeX fails, it can be useful
to have a closer look at them, so disable it to be able to look into them.
- --[no-]eps
- When this feature is on, all produced PDF files are converted to EPS using
the pdftops program (from the xpdf tools suite).
- --[no-]mark
- When this feature is on (which is the default, as it comes in very
useful), the 'title' field of the PDF informations is set to the
command-line that resulted in the PDF file. Disable it if you don't want
any information to leak.
Please note that this will not log the values of the CTIOGA2_PRE and
CTIOGA2_POST variables, so you might still get a different output if you
make heavy use of those.
- -n, --name FIGURE_NAME
- Sets the name of the figure, which is also the base name for the output
file. This has nothing to do with the title of the plot, which can be set
using the command title.
If the name contains a %, it is interpreted by ctioga2 as a printf-like
format. It will attempt to find the first file that does not exist,
feeding it with increasing numbers.
The default value is now Plot-%03d, which means you'll get increasing
numbers automatically.
- --open
- Uses open (available on MacOS) to view the PDF files produced by ctioga2.
- -o, --output FIGURE_NAME
- Writes a figure with the given name (see name) and keeps the
current state. This can be used to create an animation.
- --output-and-reset
- Writes the current figure and starts a fresh one. All non-graphical
information are kept (curves loaded, figure names, preamble, and so on).
- -O, --output-directory TEXT
- Sets the directory to which files will be plot. It defaults to the current
directory.
- -r, --page-size TEXT
- Sets the size of the output PDF file, in real units. Takes arguments in
the form of 12cm x 3in (spaces can be omitted).
- --png RESOLUTION
- Turns all produced PDF files into PNG images of the given resolution using
convert. This also has for effect to set the page-size to the
resolution divided by the 'scale' option in Postscript points. By default,
2 pixels are rendered for 1 final to produce a nicely antialiased image.
Use the 'oversampling' option to change that, in case the output looks too
pixelized. This option only affects conversion time.
- --[no-]svg
- When this feature is on, all produced PDF files are converted to SVG using
the neat pdf2svg program.
- --viewer TEXT
- Sets the command for viewing the PDF file after ctioga2 has been run.
- -X, --xpdf
- Uses xpdf to view the PDF files produced by ctioga2. If xpdf is not found, then it tries to guess which viewers are available:
- *
- on windows, it uses the system file associations to open the PDF file
- *
- on mac, it uses the open command
- *
- on linux, it tries, mime-open, and if that is missing, falls back to commonly available PDF viewers.
Data stack manipulation¶
Commands for manipulation of the data stack- --apply-formula TEXT
- Applies a formula to the last dataset (or the named one)
- --compute-contour FLOAT
- Computes the contour at the given level for the given dataset (or the last
on the stack if none is specified) and pushes it onto the data stack.
You can further manipulate it as usual.
- --dataset-hook COMMANDS
- The dataset hook is a series of commands such as those in the command
files that are run every time after a dataset is added onto the data
stack. Its main use is to provide automatic filtering of data, but any
arbitrary command can be used, so enjoy !
- --dataset-hook-add COMMANDS
- Adds the given commands to the dataset hook. See dataset-hook for
more information about the dataset hook.
- --dataset-hook-clear
- Clears the dataset hook. See dataset-hook for more information.
- --drop STORED-DATASET
- Removes the given dataset from the stack.
Can become useful when dealing with large datasets, some of which are only
used as intermediates for apply-formula or compute-contour,
for instance.
- -j, --join-datasets
- Pops the last two (or number, if it is specified) datasets from the stack,
concatenates them (older last) and push them back onto the stack. The name
option can be used to give a name to the new dataset.
- -L, --load DATASET
- Use the current backend to load the given dataset(s) onto the data stack.
If the name option is given, the last dataset loaded this way (if dataset
expansion occurs) gets named, or, if it contains a %d (or similar
construct), each dataset gets named with %d replace with the number of the
dataset within the expansion (starting at 0). This name can be used to
further use the dataset without remembering its number. See the type
stored-dataset for more information.
- --make-contour FLOAT
-
- --merge-datasets
- This commands merges data with matching X values from a dataset (by
default the one before the last) into the last one. Data points that have
no corresponding X value in the current dataset are simply ignored.
This can be used to build 3D datasets for xyz-map or
xy-parametric.
- -P, --print-dataset
- Prints to standard output data contained in the last dataset pushed onto
the stack, or the given stored dataset if the which option is given.
- --show-stack
- Displays the current contents of the dataset stack.
Mostly used for debugging when operations like merge-datasets or
join-datasets don't work as expected.
- --xy-reglin
-
This command will get documented some day.
Introspection¶
Commands displaying information about the internals of ctioga2, such as known types/commands/backends...- --edit-command TEXT
- Edit the given command in an editor. It will only work from the top
directory of a ctioga2 source tree.
- --edit-group TEXT
- Edit the given group in an editor. It will only work from the top
directory of a ctioga2 source tree.
- --edit-type TEXT
- Edit the given type in an editor. It will only work from the top directory
of a ctioga2 source tree.
- --list-commands
- List all commands known to ctioga2
- --list-groups
- List all command groups known to ctioga2
- --list-styles
- Lists all available color sets, marker sets and the like.
- --list-types
- List all types known to ctioga2
- --version-raw
- Prints the raw version number, without any other decoration and newline.
Filters¶
The commands in this group act upon the last dataset pushed unto the data stack: they can be viewed as filters.- --avg-dup
- Install the avg-dup-last command as a dataset hook (see
dataset-hook): all datasets acquired after this is on will be
averaged if they have identical successive values of X.
- --avg-dup-last
- Averages successive points with identical X values. This algorithm is
naive with respect to the min/max values and averages them just as well,
whereas one might expect something more clever.
To average over identical X values when they are not successive in the
dataset, you might want to hand it over to sort-last first.
- --cherry-pick TEXT
- Install the cherry-pick-last command as a dataset hook (see
dataset-hook): all points for which the formula returns false for
subsequent datasets will be removed.
- --cherry-pick-last TEXT
- Removes the data from the last dataset in the data stack for which the
formula returns false.
See also the cherry-pick command to apply the selection to all
datasets.
You might find it much easier to use the /where option of the plot or
load commands.
- --smooth-last INTEGER
- Smooth the data using a simple (naive even) gaussian filter. Good for
producing 'lines to guide the eye'
- --sort
- Install the sort-last command as a dataset hook (see
dataset-hook): all subsequent datasets will be sorted according to
their X values.
- --sort-last
- Sorts the last dataset pushed unto the stack according to X values. Can be
used as a filter.
See also sort.
- --trim INTEGER
- Install the trim-last command as a dataset hook (see
dataset-hook): all subsequent datasets will be trimmed to keep only
every n point.
- --trim-last INTEGER
- Only keeps one every ? data point on the last dataset pushed unto the data
stack. Useful when data have too many points to avoid creating heavy PDF
files that take ages to display with no additional benefits.
This operation is very crude and does not average data.
See also trim.
General commands¶
General scope commands- --debug
- With this on, ctioga2 writes a whole lot of debugging information. You
probably will not need that unless you intend to file a bug report or to
tackle a problem yourself.
- --echo
- Writes the whole command-line used to standard error, quoted in such a way
that it should be usable directly for copy/paste.
- -e, --eval COMMANDS
- Runs the given strings as commands, as if given from a command file.
- -f, --file FILE
- Reads the file and runs commands found in them, using the ctioga language.
ctioga2 -f my_file.ct2 If the /log is on, then all messages are written to a -log.txt file instead of to the terminal.
- -h, --help
- Prints helps about short and long options available when run from the
command-line.
- --ruby-run FILE
- Reads the file and runs the Ruby code found inside, a bit like Ruby would
do with the require command, excepted that ctioga2 does not follow Ruby's
file searching rules: you have to specify the full path.
- --set TEXT TEXT
- Sets the value of the variable (first argument) to the given second
argument. No parsing is done.
- -v, --verbose
- With this on, ctioga2 outputs quite a fair amount of informative messages.
- -V, --version
- Prints the version of ctioga in use
TYPES¶
Most of the commands accept one or more arguments, which have different types. Here are the meanings of those types.- aligned-point
- A point together with alignment specifications, used to place some elements such as legends for instance, that require alignment information. The first two letters represent the alignment:
- *
- t for top
- *
- b for bottom
- *
- c for center
- *
- l for left and
- *
- r for right
- These letters can optionally be followed by the exact location of the point in frame coordinates. If not provided, a reasonable default value is chosen. Examples:
- *
- tl is a point at the top left of the frame aligned to the top and left;
- *
- cl:0.1,0.6 is vertically centered and aligned to the left, and positioned 10% from the left and 60% from the bottom.
- alignment
- Vertical aligment for text. Can be one of:
- *
- t or top
- *
- c, center, m or midheight (vertically centered)
- *
- B, Baseline or baseline to align at the baseline
- *
- b or bottom
- aspect-ratio
- How the draw-image command respects the original image aspect ratio:
- *
- ignore (the default) ignores the original aspect ratio
- *
- expand expand the original box to respect aspect ratio
- *
- contract contract the original box to respect aspect ratio
- axis
- The name of the axis of a plot. It can be:
- *
- left, top, bottom or right;
- *
- x, xaxis, y, yaxis, which return one of the above depending on the preferences of the current plot (see xaxis and yaxis to change them);
- *
- one of the named axes, such as the ones created by new-zaxis.
- axis-decoration
- Kinds of decoration on a axis line, such as nothing, lines, ticks, tick labels. Possible values:
- *
- hidden, off, no, none: no axis at all
- *
- line: only a line
- *
- ticks: only ticks
- *
- major: only major ticks
- *
- major-num: major ticks along with their labels
- *
- full: major ticks and labels + minor ticks
- axis-or-auto
- Same thing as axis, or auto to let the style factory handle automatically.
- bijection
- A pair of functions of x specifying a bidirectional coordinate transformation separated by a double colon (::), in the order from::to. Each of the functions must be valid Ruby code - it is not exactly mathematical functions, in particular Ruby does not like floats which are missing digits on either side of the dot : for instance, .3 and 1. are not valid. Sorry. In most of the usual cases, the coordinate transform is an involution, that is from and to is the same function (this is the case for a/x). In this case, you can omit the second function.
- boolean
- Yes or no.
- boolean-or-auto
- Same thing as boolean, or auto to let the style factory handle automatically.
- box
- The specification for a box, such as an inset. It can be a grid specification, such as grid:0,1. For this to work, a grid must have been setup beforehand using setup-grid. It can also be an aligned-point together with a width and optionally a height in frame coordinates, such as:
- *
- cc:0.3: a box in the center of size 30% width and 30% height;
- *
- bl:0.1,0.2:0.7,0.2 a box starting from the point at 10% from the left and 20% from the bottom, with a width of 70% and a height of 20%.
- box-shape
- The shape of a box. It can be:
- *
- square for a plain square box
- *
- round for a rounded box
- color
- A color. It can take three forms:
- *
- a named color, see http://tioga.rubyforge.org/doc/classes/Tioga/ColorConstants.html for the list of color names.
- *
- an HTML color: for instance, #f00 or #ff0000 is red;
- *
- a list of three numbers between 0 and 1: 1,0,0 is red too.
- color-or-auto
- Same thing as color, or auto to let the style factory handle automatically.
- color-or-false
- A color, or none to say that nothing should be drawn.
- color-or-false-or-auto
- Same thing as color-or-false, or auto to let the style factory handle automatically.
- color-or-false-set
- Sets of color-or-false
- color-set
- Sets of color
- colormap
- A Z color map. It takes the form Color1--Color2--Color3.... All colors can optionally be followed by a number. For instance, for Red--Blue--Pink--Green, the colors are evenly spaced. In the case Red--Blue(0.1)--Pink(0.2)--Green, the Blue to Pink strech is located between Z values 0.1 and 0.2. If a prefix hls: or wheel: is present, then linear interpolation is done in the HLS colorspace instead of the RGB one (the default). If a suffix :sym:_value_ is present, then the colormap is symmetric around that value. It is also possible to directly use a color-set, in which case eveything works as if the colors of the color-set had been given directly, without Z values.
- colormap-or-auto
- Same thing as colormap, or auto to let the style factory handle automatically.
- commands
- ctioga2 commands, such as the ones that could be found in command files.
- cumulative-histograms
- How to specify that histograms should be stacked. Can be:
- *
- a positive number, in which case the following histograms will be added to the numbered one (0 is the first)
- *
- no/false, in which case the following histograms are not stacked
- *
- next, in which case the following histograms get stacked on a new slot
- data-point
- A point from an already-loaded Dataset. You have two ways to choose the point:
- *
- @13 takes the 13th point in the last dataset;
- *
- 0.2 takes the point the closest to 20% of the dataset.
- If you need another dataset than the last one, give its number or named within brackets: {-2}0.2 is the point closest to the 20% of the one-before-last dataset.
- dataset
- One expandable dataset.
- dimension
- A dimension, in absolute units, or in units of text height, figure, frame or page coordinates. It is in the form value unit where value is a number and unit can be one of pt, bp, in, cm (absolute units, same meaning as in TeX), dy (1.0 dy is the height of a text line), figure or f (for figure coordinates, i.e. the coordinates of the plot), frame or F (1.0 frame is the full size of the current subplot) and page or p (1.0 page is the whole height/width of the output file). It can also be auto, which is 1.0 in frame units (ie the width or the height of the current plot).
- dimension-or-no
- A dimension, or no or none.
- drawing-spec
- A ctioga 1 --draw specification.
- file
- A file name.
- fill-until
- How to close the path of a curve to fill it. Can be:
- *
- bottom, top, left, right to fill until the named side of the plot
- *
- axis or xaxis to fill until the X axis (ie y = 0)
- *
- yaxis to fill until the Y axis (ie x = 0)
- *
- x:value or x=value to fill until the given X value
- *
- y:value or y=value to fill until the given Y value
- *
- close for just closing the path (doesn't look good in general)
- *
- none for no fill
- fill-until-or-auto
- Same thing as fill-until, or auto to let the style factory handle automatically.
- fill-until-set
- Sets of fill-until
- float
- A floating-point number.
- float-list
- A list of space-separated or comma-separated floating point numbers.
- float-or-auto
- Same thing as float, or auto to let the style factory handle automatically.
- float-or-false
- A floating-point number, or none.
- float-or-false-or-auto
- Same thing as float-or-false, or auto to let the style factory handle automatically.
- float-range
- A beginning:end range.
- float-set
- Sets of float
- frame-margins
- Margins around a plot, ie the distance from the side of the plot to the corresponding side of the container (most likely the whole PDF). It can take three forms:
- *
- dimension (applies to all sides)
- *
- left_right, top_bottom
- *
- left, right, top, bottom
- Each of these elements is a valid dimension. It can also be auto, in which case the position of the margins is computed automatically to accomodate the various labels/ticks.
- integer
- An integer.
- integer-or-auto
- Same thing as integer, or auto to let the style factory handle automatically.
- internal-format
- Output format for internals.
- justification
- Horizontal aligment of the (with respect to its location). Can be one of:
- *
- l or left
- *
- c, center
- *
- r, right
- label
- The name of an label. It can be:
- *
- title to mean the current plot's title.
- *
- axis_tick or axis_ticks or simply axis, where axis is a a valid axis. It designates the ticks of the named axis.
- *
- axis_label, same as above but targets the label of the named axis.
- latex-font
- A LaTeX font. @todo document !
- level
- A level on a XYZ map (that is, just a Z value).
- line-style
- A line style, which is one of solid, dots, dashes, small_dots, a series of comma-separated numbers which are the length of the strokes and gaps, or no, none or off to mean no line.
- line-style-or-auto
- Same thing as line-style, or auto to let the style factory handle automatically.
- line-style-set
- Sets of line-style
- location
- A position on the plot, referenced with respect to the sides. Can be:
- *
- left
- *
- right
- *
- top
- *
- bottom
- *
- x0, for the x = 0 position
- *
- y0, for the y = 0 position
- In addition, there will one day be the possibility to specify an offset from these locations. But that is still something to do.
- marker
- A Tioga Marker, ie either a name from the list at http://tioga.rubyforge.org/doc/Tioga/MarkerConstants.html, such as Box, Star, Spade or two or three comma-separated numbers, _font_, _number_ and _width_. _font_ defines the font (standard PDF fonts, from 1 to 14), _number_ the number of the character within the font (between 0 and 255), and if _width_ is specified, the marker is stroked and not filled, and the number is the line width for the stroke.
- marker-or-auto
- Same thing as marker, or auto to let the style factory handle automatically.
- marker-set
- Sets of marker
- partial-float-range
- A beginning:end range, where either of the endpoints can be ommitted.
- pdf-font
- A number between 1 and 14 that designates one of the 14 standard PDF fonts. (see for instance http://tioga.rubyforge.org/doc/classes/Tioga/MarkerConstants.html for more information).
- point
- A given point on a figure.
- regexp
- A plain string or a regular expression (the latter being enclosed within /.../).
- region-side
- Within a region, designates the position of the curve with respect to the region:
- *
- above
- *
- below
- *
- ignore if this curve is not to be taken into account
- region-side-or-auto
- Same thing as region-side, or auto to let the style factory handle automatically.
- region-side-set
- Sets of region-side
- stored-dataset
- A dataset that has already been loaded. It is either:
- *
- A number, in which case it specifies the index inside the stack. 0 is the first on that was pushed onto the stack (the oldest dataset), 1 the second, -1 the last one, -2 the one before the last and so on. (it works just like Ruby's arrays).
- *
- The name of a named dataset.
- style-aspect
- This type designs which aspect of the style of a xy-parametric plot is controlled by a certain Z value. It can take the following values:
- *
- marker_color: the color for the markers
- *
- marker_size/marker_scale: the size of the markers
- text
- Plain text.
- text-adjust-mode
- Mode for text size adjustment
- *
- old for the old style heuristics
- *
- both for both the old style heuristics and the measures, taking whichever of those is the biggest
- *
- measure for only measured text size (but watch out for axis ticks !)
- text-align
- Horizontal aligment for text within its box. Only of use for texts with a given text width. Can be one of:
- *
- l or left
- *
- c, center
- *
- r, right
- *
- no or none to not issue aligning commands, in which case you get full LaTeX-justified paragraphs (probably with a lot of hyphens).
- text-list
- A list of comma-separated texts. If you must include a comma inside the texts, then use || as a separator.
- text-or-auto
- Same thing as text, or auto to let the style factory handle automatically.
- text-set
- Sets of text
- ticks-side
- On what side of an axis line are the ticks positioned:
- *
- inside: on the inside
- *
- outside: on the outside
- *
- both: on both the inside and the outside
ENVIRONMENT VARIABLES¶
If the environment variables CTIOGA2_PRE or CTIOGA2_POST are set, they are split into words according to shell rules (see the Shellwords.shellwords ruby function for more information) and prepended or appended to the command-line arguments. They don't leave any trace in the actual command-line (so, for instance, --echo won't be aware of them).AUTHOR¶
ctioga2 was written by Vincent Fourmond. Tioga was written by Bill Paxton.BUGS¶
ctioga2 is most certainly not bug-free. You can use the facility at rubyforge.org to report any bug you notice: http://rubyforge.org/tracker/?group_id=8218. You can also use the same facility for feature requests and to provide use with patches. Alternatively, you can use the forums at http://rubyforge.org/forum/?group_id=8218 or the ctioga2-users@rubyforge.org mailing list to report any kind of problems or suggestions.SEE ALSO¶
xpdf(1), pdflatex(1), open(1), gnuplot(1), ctioga(1) (the original ctioga) The original tarball includes an examples/ with various examples demonstrating different features of ctioga2, and in particular the different ways to use it: command-line or command-file. It also includes a tests/ directory containing test shell scripts. Runnning these shell scripts should give you a decent idea of ctioga2's possibilities while assuring that it did install properly. Useful information, documentation and most up-to-date news can be found at ctioga2's website, at http://ctioga2.rubyforge.org/. More information about Tioga and its rdoc documentation can be found at http://www.kitp.ucsb.edu/~paxton/tioga.html.Sun 16 Mar 18:22:35 CET 2014 | Version 0.10 |