Man Linux: Main Page and Category List


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


       ctioga arguments ...


       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


       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.


       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

       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.


       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

               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

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

       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.

       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.

              Stop making histograms.

              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.

              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

              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

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

              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.

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

              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.

              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 !

              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

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

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

              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.

              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.

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

              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.

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

              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

   Legends and texts
       -l, --[no-]legend [legend]
              sets  the  legend  of  the  next dataset, or removes it from the
              legend display.

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

       -N, --no-legends
              are shortcuts for --no-auto-legend.

              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

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

              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

   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

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

              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.







       --math-samples number

       --math-xrange range

       --smooth number




              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.

              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

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

              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.

              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

              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.

              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.

              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.

              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

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

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

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

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


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

              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.

              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.

              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:


       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

       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

       --legend-inside tl


       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.


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


       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

       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


       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.


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


       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


       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.


       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.


       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.


       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.

              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.

              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

       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

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

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

           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

       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

       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:


       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

       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


              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:


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


       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.

                 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.


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


       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.

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

              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.

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

              Strips all points that are not NaN, mostly  useful  with  ctable

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

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


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


       ctioga  is  most  certainly  not  bug-free. You can use the facility at     to     report      any      bug      you      notice:     You
       can also use the same facility for feature requests.


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

       More information about Tioga and its rdoc documentation can be found at