CTIOGA2(1)

Command-line interface for Tioga

CTIOGA2(1)

NAME¶

ctioga2 - a command-line front-end for the Tioga plotting library

SYNOPSIS¶

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.

The corresponding command file would be:

#!/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.

Optional arguments: color color-map error-bar-color fill fill-color fill-transparency ignore_hooks legend line-style line-width marker marker-color marker-color-map marker-scale name region-side split-on-nan style where xaxis yaxis zaxis

Corresponding command: plot(dataset,option=...)

-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.

Optional arguments: color color-map error-bar-color fill fill-color fill-transparency legend line-style line-width marker marker-color marker-color-map marker-scale region-side split-on-nan style which xaxis yaxis zaxis

Corresponding command: plot-last(,option=...)

Curves styles¶

Set stylistic details of curves or other object drawn from data

-c, --color COLOR-OR-AUTO: Sets the color for subsequent curves, until cancelled with auto as argument.

Corresponding command: color(color-or-auto)

--color-map COLORMAP-OR-AUTO: Sets the Color map for subsequent curves, until cancelled with auto as argument.

Corresponding command: color-map(colormap-or-auto)

--color-set COLOR-SET: Chooses a set for the color of subsequent curves. Also sets color to auto, so that the set takes effect immediately

Corresponding command: color-set(color-set)

--error-bar-color COLOR-OR-AUTO: Sets the error bar color for subsequent curves, until cancelled with auto as argument.

Corresponding command: error-bar-color(color-or-auto)

--error-bar-color-set COLOR-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

Corresponding command: error-bar-color-set(color-set)

--fill FILL-UNTIL-OR-AUTO: Sets the Fill until for subsequent curves, until cancelled with auto as argument.

Corresponding command: fill(fill-until-or-auto)

--fill-color COLOR-OR-AUTO: Sets the fill color for subsequent curves, until cancelled with auto as argument.

Corresponding command: fill-color(color-or-auto)

--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

Corresponding command: fill-color-set(color-set)

--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

Corresponding command: fill-set(fill-until-set)

--fill-transparency FLOAT-OR-AUTO: Sets the Fill transparency for subsequent curves, until cancelled with auto as argument.

Corresponding command: fill-transparency(float-or-auto)

--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

Corresponding command: fill-transparency-set(float-set)

--line-style LINE-STYLE-OR-AUTO: Sets the line style for subsequent curves, until cancelled with auto as argument.

Corresponding command: line-style(line-style-or-auto)

--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

Corresponding command: line-style-set(line-style-set)

--line-width FLOAT-OR-AUTO: Sets the line width for subsequent curves, until cancelled with auto as argument.

Corresponding command: line-width(float-or-auto)

--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

Corresponding command: line-width-set(float-set)

-m, --marker MARKER-OR-AUTO: Sets the marker for subsequent curves, until cancelled with auto as argument.

Corresponding command: marker(marker-or-auto)

--marker-color COLOR-OR-AUTO: Sets the marker color for subsequent curves, until cancelled with auto as argument.

Corresponding command: marker-color(color-or-auto)

--marker-color-map COLORMAP-OR-AUTO: Sets the Marker color map for subsequent curves, until cancelled with auto as argument.

Corresponding command: marker-color-map(colormap-or-auto)

--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

Corresponding command: marker-color-set(color-set)

--marker-scale FLOAT-OR-AUTO: Sets the marker scale for subsequent curves, until cancelled with auto as argument.

Corresponding command: marker-scale(float-or-auto)

--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

Corresponding command: marker-scale-set(float-set)

--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

Corresponding command: marker-set(marker-set)

--region-side REGION-SIDE-OR-AUTO: Sets the region side for subsequent curves, until cancelled with auto as argument.

Corresponding command: region-side(region-side-or-auto)

--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

Corresponding command: region-side-set(region-side-set)

--[no-]split-on-nan: Sets the Split on NaN for subsequent curves, until cancelled with auto as argument.

Corresponding command: split-on-nan(boolean-or-auto)

--style TEXT-OR-AUTO: Sets the Path style for subsequent curves, until cancelled with auto as argument.

Corresponding command: style(text-or-auto)

--style-set TEXT-SET: Chooses a set for the Path style of subsequent curves. Also sets style to auto, so that the set takes effect immediately

Corresponding command: style-set(text-set)

--zaxis TEXT-OR-AUTO: Sets the Name for the Z axis for subsequent curves, until cancelled with auto as argument.

Corresponding command: zaxis(text-or-auto)

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.

Corresponding command: auto-legend(boolean)

-l, --legend TEXT: Sets the legend for the next dataset. Overridden by the legend option to the plot command.

Corresponding command: legend(text)

--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.

Optional arguments: dy scale text_scale

Corresponding command: legend-inside(aligned-point,option=...)

--legend-line TEXT: Adds a line of text unrelated to any curve to the legend.

Optional arguments: align angle color justification scale shift

Corresponding command: legend-line(text,option=...)

--legend-style: Sets the various aspects of the style of the legends throught its options:

*: dy: the spacing between consecutive lines

*: scale: the overall scale of the legends

*: text_scale: the scale of the text (and the markers) inside the legends

: Optional arguments: dy scale text_scale

Corresponding command: legend-style(,option=...)

Switch between different kinds of plots¶

How to switch between different kinds of plot types

--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.

Corresponding command: xy-parametric()

--xy-plot: Switch (back) to standard XY plots (ctioga's default)

Corresponding command: xy-plot()

--xyz-map: Switch to XYZ maps, ie plots where the color at a XY location is given by its Z value.

Corresponding command: xyz-map()

Plot coordinates¶

Plot coordinates

--margin FLOAT: Leaves a margin around the data points. Expressed in relative size of the whole plot.

Corresponding command: margin(float)

--xfact FLOAT: Alias for xscale.

Corresponding command: xfact(float)

--[no-]xlog: Uses a logarithmic scale for the X axis.

Corresponding command: xlog(boolean)

--xoffset FLOAT: Adds the given offset to all X coordinates.

Corresponding command: xoffset(float)

--xrange PARTIAL-FLOAT-RANGE: Sets the range of the X coordinates.

Corresponding command: xrange(partial-float-range)

--xscale FLOAT: Multiplies the X coordinates by this factor.

Corresponding command: xscale(float)

--yfact FLOAT: Alias for yscale.

Corresponding command: yfact(float)

--[no-]ylog: Uses a logarithmic scale for the Y axis.

Corresponding command: ylog(boolean)

--yoffset FLOAT: Adds the given offset to all Y coordinates.

Corresponding command: yoffset(float)

--yrange PARTIAL-FLOAT-RANGE: Sets the range of the Y coordinates.

Corresponding command: yrange(partial-float-range)

--yscale FLOAT: Multiplies the Y coordinates by this factor.

Corresponding command: yscale(float)

Graphics primitives¶

Tioga graphics primitives

--draw DRAWING-SPEC: Tries to emulate the old --draw behavior of ctioga. Don't use it for new things.

Corresponding command: draw(drawing-spec)

--draw-arrow POINT POINT: Directly draws arrow on the current plot

Optional arguments: color head_color head_marker head_scale line_style line_width tail_color tail_marker tail_scale

Corresponding command: draw-arrow(point,point,option=...)

--draw-contour LEVEL: Directly draws contour on the current plot

Optional arguments: closed color style width

Corresponding command: draw-contour(level,option=...)

--draw-line POINT POINT: Directly draws line on the current plot

Optional arguments: color line_style line_width

Corresponding command: draw-line(point,point,option=...)

--draw-marker POINT MARKER: Directly draws marker on the current plot

Optional arguments: alignment angle color fill_color horizontal_scale justification scale stroke_color vertical_scale

Corresponding command: draw-marker(point,marker,option=...)

--draw-string-marker POINT TEXT: Directly draws marker on the current plot

Optional arguments: alignment angle color fill_color font horizontal_scale justification scale stroke_color vertical_scale

Corresponding command: draw-string-marker(point,text,option=...)

--draw-tangent DATA-POINT: Directly draws tangent on the current plot

Optional arguments: color head_color head_marker head_scale line_style line_width nbavg tail_color tail_marker tail_scale xextent xfrom xto yextent yfrom yto

Corresponding command: draw-tangent(data-point,option=...)

--draw-text POINT TEXT: Directly draws text on the current plot

Optional arguments: alignment angle color font justification scale

Corresponding command: draw-text(point,text,option=...)

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

Optional arguments: range samples vars

Corresponding command: gnuplot(,option=...)

--gnuplot-range RANGE: The plotting X range, such as 0:2

Corresponding command: gnuplot-range(range)

--gnuplot-samples SAMPLES: The number of samples

Corresponding command: gnuplot-samples(samples)

--gnuplot-vars VARS: A colon-separated override of local variables, such as a=1;b=3;c=5

Corresponding command: gnuplot-vars(vars)

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

Optional arguments: log samples trange xrange

Corresponding command: math(,option=...)

--[no-]math-log: Space samples logarithmically

Corresponding command: math-log(log)

--math-samples SAMPLES: The number of points

Corresponding command: math-samples(samples)

--math-trange TRANGE: T range (a:b) (parametric plot)

Corresponding command: math-trange(trange)

--math-xrange XRANGE: X range (a:b)

Corresponding command: math-xrange(xrange)

The 'text' backend: Text format¶

The commands in this group drive the behaviour of the text backend; see its documentation for more information

--text: Selects the 'text' backend

Optional arguments: col header-line parameters separator skip split

Corresponding command: text(,option=...)

--text-col COL: Which columns to use when the @1:2 syntax is not used

Corresponding command: text-col(col)

--text-header-line HEADER-LINE: Regular expression indicating the header line (containing column names) (default /^##/

Corresponding command: text-header-line(header-line)

--text-parameters PARAMETERS: Regular expression for extracting parameters from a file. Defaults to nil (ie nothing)

Corresponding command: text-parameters(parameters)

--text-separator SEPARATOR: The columns separator. Defaults to / +/

Corresponding command: text-separator(separator)

--text-skip SKIP: Number of lines to be skipped at the beginning of the file

Corresponding command: text-skip(skip)

--[no-]text-split: If true, splits files into subsets on blank/non number lines

Corresponding command: text-split(split)

LaTeX¶

Commands providing control over the LaTeX output (preamble, packages...)

--preamble TEXT: Adds the given string to the LaTeX preamble of the output.

Corresponding command: preamble(text)

--use TEXT: Adds a command to include the LaTeX package into the preamble. The arguments, if given, are given within [square backets].

Optional arguments: arguments

Corresponding command: use(text,option=...)

--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}

Corresponding command: utf8()

Subplots and assimilated¶

Subplots and assimilated

--end: Leaves the current subobject.

Corresponding command: end()

--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.

Corresponding command: frame-margins(frame-margins)

--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.

Corresponding command: gradient(color,color)

--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.

Corresponding command: inset(box)

--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.

Corresponding command: next-inset(box)

--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.

Corresponding command: padding(dimension)

--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.

: Optional arguments: what

Corresponding command: plot-scale(float,option=...)

--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).

Optional arguments: color reversed_color reversed_transparency transparency

Corresponding command: region(,option=...)

--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.

Optional arguments: bottom dx dy left right top

Corresponding command: setup-grid(text,option=...)

--zoom-inset BOX: Zooms are currently not implemented yet.

Corresponding command: zoom-inset(box)

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:

*: decoration

: Optional arguments: decoration location stroke_color transform

Corresponding command: axis-style(axis,option=...)

--background-lines AXIS COLOR-OR-FALSE: Sets the color of the background lines for the given axis.

Optional arguments: style width

Corresponding command: background-lines(axis,color-or-false,option=...)

--bottom AXIS-DECORATION: Sets the type of the bottom axis.

Optional arguments: location stroke_color transform

Corresponding command: bottom(axis-decoration,option=...)

--label-style LABEL: Sets the style of the given label (see the type label for more information).

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.

Optional arguments: align angle color justification scale shift text

Corresponding command: label-style(label,option=...)

--left AXIS-DECORATION: Sets the type of the left axis.

Optional arguments: location stroke_color transform

Corresponding command: left(axis-decoration,option=...)

--new-zaxis TEXT: Creates a named Z axis that can display information from Z color maps

Optional arguments: bar_shift bar_size decoration location stroke_color transform

Corresponding command: new-zaxis(text,option=...)

--no-title: Removes the title of the current plot.

Corresponding command: no-title()

--no-xlabel: Removes the X label for the current plot.

Corresponding command: no-xlabel()

--no-ylabel: Removes the Y label for the current plot.

Corresponding command: no-ylabel()

--right AXIS-DECORATION: Sets the type of the right axis.

Optional arguments: location stroke_color transform

Corresponding command: right(axis-decoration,option=...)

-t, --title TEXT: Sets the title of the current plot.

Optional arguments: align angle color justification scale shift

Corresponding command: title(text,option=...)

--top AXIS-DECORATION: Sets the type of the top axis.

Optional arguments: location stroke_color transform

Corresponding command: top(axis-decoration,option=...)

--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)

Corresponding command: x2()

--xaxis AXIS: Sets the default axis for the X axis for all subsequent commands take rely on default axes (such as plot, xrange, yrange...).

Corresponding command: xaxis(axis)

-x, --xlabel TEXT: Sets the X label of the current plot.

Optional arguments: align angle color justification scale shift

Corresponding command: xlabel(text,option=...)

--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)

Corresponding command: y2()

--yaxis AXIS: Sets the default axis for the Y axis for all subsequent commands take rely on default axes (such as plot, xrange, yrange...).

Corresponding command: yaxis(axis)

-y, --ylabel TEXT: Sets the Y label of the current plot.

Optional arguments: align angle color justification scale shift

Corresponding command: ylabel(text,option=...)

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.

Corresponding command: background(color-or-false)

--watermark TEXT: Watermark...

Optional arguments: alignment angle color fill_color font horizontal_scale justification scale stroke_color vertical_scale

Corresponding command: watermark(text,option=...)

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.

Corresponding command: clean(boolean)

--[no-]eps: When this feature is on, all produced PDF files are converted to EPS using the pdftops program (from the xpdf tools suite).

Corresponding command: eps(boolean)

--[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.

Corresponding command: mark(boolean)

-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.

Corresponding command: name(figure name)

--open: Uses open (available on MacOS) to view the PDF files produced by ctioga2.

Corresponding command: open()

-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.

Corresponding command: output-now(figure name)

--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).

Corresponding command: output-and-reset()

-O, --output-directory TEXT: Sets the directory to which files will be plot. It defaults to the current directory.

Corresponding command: output-directory(text)

-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).

Optional arguments: count-legend

Corresponding command: page-size(text,option=...)

--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.

Optional arguments: oversampling scale

Corresponding command: png(resolution,option=...)

--[no-]svg: When this feature is on, all produced PDF files are converted to SVG using the neat pdf2svg program.

Corresponding command: svg(boolean)

--viewer TEXT: Sets the command for viewing the PDF file after ctioga2 has been run.

Corresponding command: viewer(text)

-X, --xpdf: Uses xpdf to view the PDF files produced by ctioga2.

Corresponding command: xpdf()

Data stack manipulation¶

Commands for manipulation of the data stack

--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 !

Corresponding command: dataset-hook(commands)

--dataset-hook-add COMMANDS: Adds the given commands to the dataset hook. See dataset-hook for more information about the dataset hook.

Corresponding command: dataset-hook-add(commands)

--dataset-hook-clear: Clears the dataset hook. See dataset-hook for more information.

Corresponding command: dataset-hook-clear()

--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.

Optional arguments: number

Corresponding command: join-datasets(,option=...)

-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.

Optional arguments: ignore_hooks name where

Corresponding command: load(dataset,option=...)

--make-contour FLOAT: Optional arguments: ignore_hooks name where which

Corresponding command: make-contour(float,option=...)

--merge-datasets: Optional arguments: number

Corresponding command: merge-datasets(,option=...)

-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.

Optional arguments: save which

Corresponding command: print-dataset(,option=...)

--xy-reglin: Optional arguments: linear which

Corresponding command: xy-reglin(,option=...)

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.

Corresponding command: edit-command(text)

--edit-group TEXT: Edit the given group in an editor. It will only work from the top directory of a ctioga2 source tree.

Corresponding command: edit-group(text)

--edit-type TEXT: Edit the given type in an editor. It will only work from the top directory of a ctioga2 source tree.

Corresponding command: edit-type(text)

--list-commands: List all commands known to ctioga2

Optional arguments: format raw

Corresponding command: list-commands(,option=...)

--list-groups: List all command groups known to ctioga2

Optional arguments: raw

Corresponding command: list-groups(,option=...)

--list-types: List all types known to ctioga2

Optional arguments: raw

Corresponding command: list-types(,option=...)

--version-raw: Prints the raw version number, without any other decoration and newline.

Corresponding command: version-raw()

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.

Corresponding command: avg-dup()

--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.

Corresponding command: avg-dup-last()

--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.

Corresponding command: cherry-pick(text)

--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.

Corresponding command: cherry-pick-last(text)

--smooth-last INTEGER: Smooth the data using a simple (naive even) gaussian filter. Good for producing 'lines to guide the eye'

Corresponding command: smooth-last(integer)

--sort: Install the sort-last command as a dataset hook (see dataset-hook): all subsequent datasets will be sorted according to their X values.

Corresponding command: sort()

--sort-last: Sorts the last dataset pushed unto the stack according to X values. Can be used as a filter.

See also sort.

Corresponding command: sort-last()

--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.

Corresponding command: trim(integer)

--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.

Corresponding command: trim-last(integer)

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.

Corresponding command: debug()

--echo: Writes the whole command-line used to standard error, quoted in such a way that it should be usable directly for copy/paste.

Corresponding command: echo()

-e, --eval COMMANDS: Runs the given strings as commands, as if given from a command file.

Corresponding command: eval(commands)

-f, --file FILE: Reads the file and runs commands found in them, using the ctioga language.

ctioga2 -f my_file.ct2

Corresponding command: include(file)

-h, --help: Prints helps about short and long options available when run from the command-line.

Optional arguments: pager

Corresponding command: command-line-help(,option=...)

-v, --verbose: With this on, ctioga2 outputs quite a fair amount of informative messages.

Corresponding command: verbose()

-V, --version: Prints the version of ctioga in use

Corresponding command: version()

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.

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

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 or off: 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. Specifications vary for now...

@todo to be written later on.

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 false to say that nothing should be drawn.

color-set: Sets of color

colormap: A Z color map

odo document !

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.

data-point: A point from a Dataset.

odo document ;-)...

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).

drawing-spec: A ctioga 1 --draw specification.

file: A file name.

fill-until: The Y values until which a filled curve will be filled. Generally a number, but it can also be:

*: axis (or xaxis), which means 0

*: bottom, to fill until the bottom of the graph

*: top, to fill until the top

*: none, meaning 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-or-auto: Same thing as float, 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.

internal-format: Output format for internals.

justification: Horizontal aligment for text. 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.

odo document !

level: A level on a XYZ map (that is, just a Z value).

line-style: A line style, 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

: 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.

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.

text: Plain text.

text-or-auto: Same thing as text, or auto to let the style factory handle automatically.

text-set: Sets of text

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.

Source file:	ctioga2.1.en.gz (from ctioga2 0.2-4)
Source last updated:	2012-06-23T23:58:05Z
Converted to HTML:	2017-06-07T16:54:11Z