Navigation

LaTeX Options for Graphs

This module provides a class to hold, manipulate and employ various options for rendering a graph in \mbox{\rm\LaTeX}.

AUTHORS:

  • Robert Beezer (2009-05-20): GraphLatex class
  • Fidel Barerra Cruz (2009-05-20): tkz-graph commands to render a graph
  • Nicolas M. Thiery (2010-02): dot2tex/graphviz interface

LaTeX Versions of Graphs

Many mathematical objects in Sage have \mbox{\rm\LaTeX} representations, and graphs are no exception. For a graph g, the command view(g) or view(g, pdflatex=True), issued at the Sage command line or in the notebook, will create a graphic version of g. Similarly, latex(g) will return a (long) string that is a representation of the graph in \mbox{\rm\LaTeX}. Other ways of employing \mbox{\rm\LaTeX} in Sage, such as %latex in a notebook cell, or the Typeset checkbox in the notebook, will handle g appropriately.

To use \mbox{\rm\LaTeX} in Sage you of course need a working \mbox{\rm\TeX} installation and it will work best if you have the dvipng and convert utilities. For graphs you need the tkz-graph.sty and tkz-berge.sty style files of the tkz-graph package. You can find these at:

Customizing the output is accomplished in several ways. Suppose g is a graph, then g.set_latex_options() can be used to efficiently set or modify various options. Setting individual options, or querying options, can be accomplished by first using a command like opts = g.latex_options() to obtain a sage.graphs.graph_latex.GraphLatex object which has several methods to set and retrieve options. The following session illustrates the use of these commands. The full output of latex(g) is not included, but the two calls would produce different output due to the change of the style.

The range of possible options are carefully documented at sage.graphs.graph_latex.GraphLatex.set_option().

EXAMPLES:

An example using the tkz_graph format:

sage: g = graphs.PetersenGraph()
sage: g.set_latex_options(tkz_style = 'Classic')
sage: from sage.graphs.graph_latex import check_tkz_graph
sage: check_tkz_graph()  # random - depends on TeX installation
sage: latex(g)
\begin{tikzpicture}
...
\end{tikzpicture}
sage: opts = g.latex_options()
sage: opts
LaTeX options for Petersen graph: {'tkz_style': 'Classic'}
sage: opts.set_option('tkz_style', 'Art')
sage: opts.get_option('tkz_style')
'Art'
sage: opts
LaTeX options for Petersen graph: {'tkz_style': 'Art'}
sage: latex(g)
\begin{tikzpicture}
...
\end{tikzpicture}

An example using the optional dot2tex module:

sage: g = graphs.PetersenGraph()
sage: g.set_latex_options(format='dot2tex',prog='neato') # optional - requires dot2tex
sage: latex(g) # optional - requires dot2tex
\begin{tikzpicture}[>=latex,line join=bevel,]
...
\end{tikzpicture}

GraphLatex class and functions

class sage.graphs.graph_latex.GraphLatex(graph, **options)

Bases: sage.structure.sage_object.SageObject

A class to hold, manipulate and employ options for converting a graph to \mbox{\rm\LaTeX}.

This class serves two purposes. First it holds the values of various options designed to work with the tkz-graph \mbox{\rm\LaTeX} package for rendering graphs. As such, a graph that uses this class will hold a reference to it. Second, this class contains the code to convert a graph into the corresponding \mbox{\rm\LaTeX} constructs, returning a string.

EXAMPLES:

sage: from sage.graphs.graph_latex import GraphLatex
sage: opts = GraphLatex(graphs.PetersenGraph())
sage: opts
LaTeX options for Petersen graph: {}
sage: g = graphs.PetersenGraph()
sage: opts = g.latex_options()
sage: g == loads(dumps(g))
True
dot2tex_picture()

Calls dot2tex to construct a string of \mbox{\rm\LaTeX} commands representing a graph as a tikzpicture.

EXAMPLES:

sage: g = digraphs.ButterflyGraph(1)
sage: print g.latex_options().dot2tex_picture()  # optional - requires dot2tex and graphviz
\begin{tikzpicture}[>=latex,line join=bevel,]
%%
  \node ('0'+1) at (60bp,9bp) [draw,draw=none] {$\left(\text{0}, 1\right)$};
  \node ('0'+0) at (14bp,63bp) [draw,draw=none] {$\left(\text{0}, 0\right)$};
  \node ('1'+0) at (60bp,63bp) [draw,draw=none] {$\left(\text{1}, 0\right)$};
  \node ('1'+1) at (14bp,9bp) [draw,draw=none] {$\left(\text{1}, 1\right)$};
  \draw [->] ('1'+0) ..controls (60bp,47bp) and (60bp,37bp)  .. ('0'+1);
  \draw [->] ('0'+0) ..controls (29bp,46bp) and (38bp,35bp)  .. ('0'+1);
  \draw [->] ('0'+0) ..controls (14bp,47bp) and (14bp,37bp)  .. ('1'+1);
  \draw [->] ('1'+0) ..controls (45bp,46bp) and (36bp,35bp)  .. ('1'+1);
%
\end{tikzpicture}

Note: there is a lot of overlap between what tkz_picture and dot2tex do. It would be best to merge them! dot2tex probably can work without graphviz if layout information is provided.

get_option(option_name)

Returns the current value of the named option.

INPUT:

  • option_name - the name of an option

OUTPUT:

If the name is not present in sage.graphs.graph_latex.__graphlatex_options it is an error to ask for it. If an option has not been set then the default value is returned. Otherwise, the value of the option is returned.

EXAMPLES:

sage: g = graphs.PetersenGraph()
sage: opts = g.latex_options()
sage: opts.set_option('tkz_style', 'Art')
sage: opts.get_option('tkz_style')
'Art'
sage: opts.set_option('tkz_style')
sage: opts.get_option('tkz_style') == "Normal"
True
sage: opts.get_option('bad_name')
...
ValueError: bad_name is not a Latex option for a graph.
latex()

Returns a string in \mbox{\rm\LaTeX} representing a graph.

This is the command that is invoked by _latex_() for a graph, so it returns a string of \mbox{\rm\LaTeX} commands that can be incorporated into a \mbox{\rm\LaTeX} document unmodified. The exact contents of this string are influenced by the options set via the methods sage.graphs.graph.GenericGraph.set_latex_options(), set_option(), and set_options().

Right now it only calls one procedure for creating strings using the tkz-graph package, but by passing in an option and implementing a new procedure, other packages could be supported in the future.

EXAMPLES:

sage: from sage.graphs.graph_latex import check_tkz_graph
sage: check_tkz_graph()  # random - depends on TeX installation
sage: g = graphs.CompleteGraph(2)
sage: opts = g.latex_options()
sage: print opts.latex()
\begin{tikzpicture}
%
\definecolor{col_a0}{rgb}{1.0,1.0,1.0}
\definecolor{col_a1}{rgb}{1.0,1.0,1.0}
%
%
\definecolor{col_lab_a0}{rgb}{0.0,0.0,0.0}
\definecolor{col_lab_a1}{rgb}{0.0,0.0,0.0}
%
%
\definecolor{col_a0-a1}{rgb}{0.0,0.0,0.0}
%
%
\GraphInit[vstyle=Normal]
%
\SetVertexMath
%
\SetVertexNoLabel
%
\renewcommand*{\VertexLightFillColor}{col_a0}
\Vertex[x=5.0cm,y=5.0cm]{a0}
\renewcommand*{\VertexLightFillColor}{col_a1}
\Vertex[x=0.0cm,y=0.0cm]{a1}
%
%
\AssignVertexLabel{a}{2}{
\color{col_lab_a0}{$0$},
\color{col_lab_a1}{$1$}
}
%
%
\renewcommand*{\EdgeColor}{col_a0-a1}
\Edge(a0)(a1)
%
%
\end{tikzpicture}
set_option(option_name, option_value=None)

Sets, modifies, clears a legitimate \mbox{\rm\LaTeX} option for rendering a graph.

INPUTS:

  • option_name - a string for a latex option contained in the list __graphlatex_options. A ValueError is raised if the option is not allowed.
  • option_value - a value for the option. If omitted, or set to None, the option is totally removed (i.e. cleared). The value is not checked here for correctness, but rather it is checked where it is employed.

The output can be either handled internaly by Sage, or delegated to the external software dot2tex and graphviz. This is controlled by the option ‘format’:

  • format – ‘dot2tex’ or ‘tkz_graph’ (default: ‘tkz_graph’). (TODO: find a better name)

Note: If format is ‘dot2tex’, then all the LaTeX generation will be delegated to dot2tex (which must be installed).

For tkz_graph, the possible option names, and associated values are given below. For precise details consult the documentation for the tkz-graph package:

  • tkz_style – a pre-defined tkz-graph style such as “Art” or “Normal”. Currently, the recognized styles are “Shade”, “Art”, “Normal”, “Dijkstra”, “Welsh”, “Classic”, and “Simple”. Any other value will not give an error, but if you run latex on the graph, then an unrecognized style will be treated as “Normal” (only for tkz_graph format).
  • layout – the layout used for coordinates of the vertices

For the ‘dot2tex’ format, the possible option names and associated values are given below:

  • prog – the program used for the layout. It must be a string corresponding to one of the software of the graphviz suite: ‘dot’, ‘neato’, ‘twopi’, ‘circo’ or ‘fdp’.
  • edge_label – a boolean (default: False). Whether to display the labels on edges.
  • edge_colors – a color. Can be used to set a global color to the edge of the graph.
  • color_by_label - a boolean (default: False). Colors the edges according to their labels (only for dot2tex format)

EXAMPLES:

Set, then modify, then clear the tkz_style option, and finally show an error for an unrecognized option name:

sage: g = graphs.PetersenGraph()
sage: opts = g.latex_options()
sage: opts
LaTeX options for Petersen graph: {}
sage: opts.set_option('tkz_style', 'foo')
sage: opts
LaTeX options for Petersen graph: {'tkz_style': 'foo'}
sage: opts.set_option('tkz_style', 'bar')
sage: opts
LaTeX options for Petersen graph: {'tkz_style': 'bar'}
sage: opts.set_option('tkz_style')
sage: opts
LaTeX options for Petersen graph: {}
sage: opts.set_option('bad_name', 'nonsense')
...
ValueError: bad_name is not a LaTeX option for a graph.

See Graph.layout_graphviz() for installation instructions for graphviz and dot2tex. Further more, pgf >= 2.00 should be available inside LaTeX’s tree for LaTeX compilation (e.g. when using view). In case your LaTeX distribution does not provide it, here are short instructions:

  • download pgf from http://sourceforge.net/projects/pgf/
  • unpack it in /usr/share/texmf/tex/generic (depends on your system)
  • clean out remaining pgf files from older version
  • run texhash
set_options(**kwds)

Set several \mbox{\rm\LaTeX} options for a graph all at once.

INPUTS:

  • kwds - any number of option/value pairs to se many graph latex options at once (a variable number, in any order). Existing values are overwritten, new values are added. Existing values can be cleared by setting the value to None. Errors are raised in the set_option() method.

EXAMPLES:

sage: g = graphs.PetersenGraph()
sage: opts = g.latex_options()
sage: opts.set_options(tkz_style = 'Welsh')
sage: opts.get_option('tkz_style')
'Welsh'
tkz_picture()

Return a string of \mbox{\rm\LaTeX} commands representing a graph as a tikzpicture.

This routine interprets the graph’s properties and the options in _options to render the graph with commands from the tkz-graph \mbox{\rm\LaTeX} package.

This requires that the \mbox{\rm\LaTeX} optional packages tkz-graph and tkz-berge be installed. You may also need a current version of the pgf package. If the tkz-graph and tkz-berge packages are present in the system’s TeX installation, the appropriate \\usepackage{} commands will be added to the \mbox{\rm\LaTeX} preamble as part of the initialization of the graph. If these two packages are not present, then this command will return a warning on its first use, but will return a string that could be used elsewhere, such as a \mbox{\rm\LaTeX} document.

For more information about tkz-graph you can visit http://altermundus.com/pages/graph.html

EXAMPLES:

sage: from sage.graphs.graph_latex import check_tkz_graph
sage: check_tkz_graph()  # random - depends on TeX installation
sage: g = graphs.CompleteGraph(3)
sage: opts = g.latex_options()
sage: print opts.tkz_picture()
\begin{tikzpicture}
%
\definecolor{col_a0}{rgb}{1.0,1.0,1.0}
\definecolor{col_a1}{rgb}{1.0,1.0,1.0}
\definecolor{col_a2}{rgb}{1.0,1.0,1.0}
%
%
\definecolor{col_lab_a0}{rgb}{0.0,0.0,0.0}
\definecolor{col_lab_a1}{rgb}{0.0,0.0,0.0}
\definecolor{col_lab_a2}{rgb}{0.0,0.0,0.0}
%
%
\definecolor{col_a0-a1}{rgb}{0.0,0.0,0.0}
\definecolor{col_a0-a2}{rgb}{0.0,0.0,0.0}
\definecolor{col_a1-a2}{rgb}{0.0,0.0,0.0}
%
%
\GraphInit[vstyle=Normal]
%
\SetVertexMath
%
\SetVertexNoLabel
%
\renewcommand*{\VertexLightFillColor}{col_a0}
\Vertex[x=2.5cm,y=5.0cm]{a0}
\renewcommand*{\VertexLightFillColor}{col_a1}
\Vertex[x=0.0cm,y=0.0cm]{a1}
\renewcommand*{\VertexLightFillColor}{col_a2}
\Vertex[x=5.0cm,y=0.0cm]{a2}
%
%
\AssignVertexLabel{a}{3}{
\color{col_lab_a0}{$0$},
\color{col_lab_a1}{$1$},
\color{col_lab_a2}{$2$}
}
%
%
\renewcommand*{\EdgeColor}{col_a0-a1}
\Edge(a0)(a1)
\renewcommand*{\EdgeColor}{col_a0-a2}
\Edge(a0)(a2)
\renewcommand*{\EdgeColor}{col_a1-a2}
\Edge(a1)(a2)
%
%
\end{tikzpicture}

TESTS:

Graphs with preset layouts that are vertical or horizontal can cause problems. First test is a horizontal layout on a path with three vertices.

sage: from sage.graphs.graph_latex import check_tkz_graph
sage: check_tkz_graph()  # random - depends on TeX installation
sage: g = graphs.PathGraph(3)
sage: opts = g.latex_options()
sage: print opts.tkz_picture()
\begin{tikzpicture}
%
\definecolor{col_a0}{rgb}{1.0,1.0,1.0}
\definecolor{col_a1}{rgb}{1.0,1.0,1.0}
\definecolor{col_a2}{rgb}{1.0,1.0,1.0}
%
%
\definecolor{col_lab_a0}{rgb}{0.0,0.0,0.0}
\definecolor{col_lab_a1}{rgb}{0.0,0.0,0.0}
\definecolor{col_lab_a2}{rgb}{0.0,0.0,0.0}
%
%
\definecolor{col_a0-a1}{rgb}{0.0,0.0,0.0}
\definecolor{col_a1-a2}{rgb}{0.0,0.0,0.0}
%
%
\GraphInit[vstyle=Normal]
%
\SetVertexMath
%
\SetVertexNoLabel
%
\renewcommand*{\VertexLightFillColor}{col_a0}
\Vertex[x=0.0cm,y=2.5cm]{a0}
\renewcommand*{\VertexLightFillColor}{col_a1}
\Vertex[x=2.5cm,y=2.5cm]{a1}
\renewcommand*{\VertexLightFillColor}{col_a2}
\Vertex[x=5.0cm,y=2.5cm]{a2}
%
%
\AssignVertexLabel{a}{3}{
\color{col_lab_a0}{$0$},
\color{col_lab_a1}{$1$},
\color{col_lab_a2}{$2$}
}
%
%
\renewcommand*{\EdgeColor}{col_a0-a1}
\Edge(a0)(a1)
\renewcommand*{\EdgeColor}{col_a1-a2}
\Edge(a1)(a2)
%
%
\end{tikzpicture}

Scaling to a bounding box is problematic for graphs with just one vertex, or none.

sage: from sage.graphs.graph_latex import check_tkz_graph
sage: check_tkz_graph()  # random - depends on TeX installation
sage: g = graphs.CompleteGraph(1)
sage: opts = g.latex_options()
sage: print opts.tkz_picture()
\begin{tikzpicture}
%
\definecolor{col_a0}{rgb}{1.0,1.0,1.0}
%
%
\definecolor{col_lab_a0}{rgb}{0.0,0.0,0.0}
%
%
%
%
\GraphInit[vstyle=Normal]
%
\SetVertexMath
%
\SetVertexNoLabel
%
\renewcommand*{\VertexLightFillColor}{col_a0}
\Vertex[x=2.5cm,y=2.5cm]{a0}
%
%
\AssignVertexLabel{a}{1}{
\color{col_lab_a0}{$0$}
}
%
%
%
%
\end{tikzpicture}
sage.graphs.graph_latex.check_tkz_graph()

Checks if the proper \mbox{\rm\LaTeX} packages for the tikzpicture environment are installed in the user’s environment, and issue a warning otherwise.

The warning is only issued on the first call to this function. So any doctest that illustrates the use of the tkz-graph packages should call this once as having random output to exhaust the warnings before testing output.

See also sage.misc.latex.check_file()

TESTS:

sage: from sage.graphs.graph_latex import check_tkz_graph
sage: check_tkz_graph()  # random - depends on TeX installation
sage: check_tkz_graph()  # at least the second time, so no output
sage.graphs.graph_latex.have_tkz_graph()

Returns True if the proper \mbox{\rm\LaTeX} packages for the tikzpicture environment are installed in the user’s environment, namely tikz, tkz-graph and tkz-berge.

The result is cached.

See also sage.misc.latex.has_file()

TESTS:

sage: from sage.graphs.graph_latex import have_tkz_graph
sage: have_tkz_graph()  # random - depends on TeX installation
sage: have_tkz_graph() in [True, False]
True

Table Of Contents

Previous topic

A collection of constructors of common graphs.

Next topic

A module for dealing with lists of graphs.

This Page

Navigation

© Copyright 2005--2010, The Sage Development Team. Created using Sphinx 0.6.3.