r"""
*****
LaTeX
*****
Export NetworkX graphs in LaTeX format using the TikZ library within TeX/LaTeX.
Usually, you will want the drawing to appear in a figure environment so
you use ``to_latex(G, caption="A caption")``. If you want the raw
drawing commands without a figure environment use :func:`to_latex_raw`.
And if you want to write to a file instead of just returning the latex
code as a string, use ``write_latex(G, "filename.tex", caption="A caption")``.
To construct a figure with subfigures for each graph to be shown, provide
``to_latex`` or ``write_latex`` a list of graphs, a list of subcaptions,
and a number of rows of subfigures inside the figure.
To be able to refer to the figures or subfigures in latex using ``\\ref``,
the keyword ``latex_label`` is available for figures and `sub_labels` for
a list of labels, one for each subfigure.
We intend to eventually provide an interface to the TikZ Graph
features which include e.g. layout algorithms.
Let us know via github what you'd like to see available, or better yet
give us some code to do it, or even better make a github pull request
to add the feature.
The TikZ approach
=================
Drawing options can be stored on the graph as node/edge attributes, or
can be provided as dicts keyed by node/edge to a string of the options
for that node/edge. Similarly a label can be shown for each node/edge
by specifying the labels as graph node/edge attributes or by providing
a dict keyed by node/edge to the text to be written for that node/edge.
Options for the tikzpicture environment (e.g. "[scale=2]") can be provided
via a keyword argument. Similarly default node and edge options can be
provided through keywords arguments. The default node options are applied
to the single TikZ "path" that draws all nodes (and no edges). The default edge
options are applied to a TikZ "scope" which contains a path for each edge.
Examples
========
>>> G = nx.path_graph(3)
>>> nx.write_latex(G, "just_my_figure.tex", as_document=True)
>>> nx.write_latex(G, "my_figure.tex", caption="A path graph", latex_label="fig1")
>>> latex_code = nx.to_latex(G) # a string rather than a file
You can change many features of the nodes and edges.
>>> G = nx.path_graph(4, create_using=nx.DiGraph)
>>> pos = {n: (n, n) for n in G} # nodes set on a line
>>> G.nodes[0]["style"] = "blue"
>>> G.nodes[2]["style"] = "line width=3,draw"
>>> G.nodes[3]["label"] = "Stop"
>>> G.edges[(0, 1)]["label"] = "1st Step"
>>> G.edges[(0, 1)]["label_opts"] = "near start"
>>> G.edges[(1, 2)]["style"] = "line width=3"
>>> G.edges[(1, 2)]["label"] = "2nd Step"
>>> G.edges[(2, 3)]["style"] = "green"
>>> G.edges[(2, 3)]["label"] = "3rd Step"
>>> G.edges[(2, 3)]["label_opts"] = "near end"
>>> nx.write_latex(G, "latex_graph.tex", pos=pos, as_document=True)
Then compile the LaTeX using something like ``pdflatex latex_graph.tex``
and view the pdf file created: ``latex_graph.pdf``.
If you want **subfigures** each containing one graph, you can input a list of graphs.
>>> H1 = nx.path_graph(4)
>>> H2 = nx.complete_graph(4)
>>> H3 = nx.path_graph(8)
>>> H4 = nx.complete_graph(8)
>>> graphs = [H1, H2, H3, H4]
>>> caps = ["Path 4", "Complete graph 4", "Path 8", "Complete graph 8"]
>>> lbls = ["fig2a", "fig2b", "fig2c", "fig2d"]
>>> nx.write_latex(graphs, "subfigs.tex", n_rows=2, sub_captions=caps, sub_labels=lbls)
>>> latex_code = nx.to_latex(graphs, n_rows=2, sub_captions=caps, sub_labels=lbls)
>>> node_color = {0: "red", 1: "orange", 2: "blue", 3: "gray!90"}
>>> edge_width = {e: "line width=1.5" for e in H3.edges}
>>> pos = nx.circular_layout(H3)
>>> latex_code = nx.to_latex(H3, pos, node_options=node_color, edge_options=edge_width)
>>> print(latex_code)
\documentclass{report}
\usepackage{tikz}
\usepackage{subcaption}
<BLANKLINE>
\begin{document}
\begin{figure}
\begin{tikzpicture}
\draw
(1.0, 0.0) node[red] (0){0}
(0.707, 0.707) node[orange] (1){1}
(-0.0, 1.0) node[blue] (2){2}
(-0.707, 0.707) node[gray!90] (3){3}
(-1.0, -0.0) node (4){4}
(-0.707, -0.707) node (5){5}
(0.0, -1.0) node (6){6}
(0.707, -0.707) node (7){7};
\begin{scope}[-]
\draw[line width=1.5] (0) to (1);
\draw[line width=1.5] (1) to (2);
\draw[line width=1.5] (2) to (3);
\draw[line width=1.5] (3) to (4);
\draw[line width=1.5] (4) to (5);
\draw[line width=1.5] (5) to (6);
\draw[line width=1.5] (6) to (7);
\end{scope}
\end{tikzpicture}
\end{figure}
\end{document}
Notes
-----
If you want to change the preamble/postamble of the figure/document/subfigure
environment, use the keyword arguments: `figure_wrapper`, `document_wrapper`,
`subfigure_wrapper`. The default values are stored in private variables
e.g. ``nx.nx_layout._DOCUMENT_WRAPPER``
References
----------
TikZ: https://tikz.dev/
TikZ options details: https://tikz.dev/tikz-actions
"""
import numbers
import os
import networkx as nx
__all__ = [
"to_latex_raw",
"to_latex",
"write_latex",
]
[docs]
@nx.utils.not_implemented_for("multigraph")
def to_latex_raw(
G,
pos="pos",
tikz_options="",
default_node_options="",
node_options="node_options",
node_label="label",
default_edge_options="",
edge_options="edge_options",
edge_label="label",
edge_label_options="edge_label_options",
):
"""Return a string of the LaTeX/TikZ code to draw `G`
This function produces just the code for the tikzpicture
without any enclosing environment.
Parameters
==========
G : NetworkX graph
The NetworkX graph to be drawn
pos : string or dict (default "pos")
The name of the node attribute on `G` that holds the position of each node.
Positions can be sequences of length 2 with numbers for (x,y) coordinates.
They can also be strings to denote positions in TikZ style, such as (x, y)
or (angle:radius).
If a dict, it should be keyed by node to a position.
If an empty dict, a circular layout is computed by TikZ.
tikz_options : string
The tikzpicture options description defining the options for the picture.
Often large scale options like `[scale=2]`.
default_node_options : string
The draw options for a path of nodes. Individual node options override these.
node_options : string or dict
The name of the node attribute on `G` that holds the options for each node.
Or a dict keyed by node to a string holding the options for that node.
node_label : string or dict
The name of the node attribute on `G` that holds the node label (text)
displayed for each node. If the attribute is "" or not present, the node
itself is drawn as a string. LaTeX processing such as ``"$A_1$"`` is allowed.
Or a dict keyed by node to a string holding the label for that node.
default_edge_options : string
The options for the scope drawing all edges. The default is "[-]" for
undirected graphs and "[->]" for directed graphs.
edge_options : string or dict
The name of the edge attribute on `G` that holds the options for each edge.
If the edge is a self-loop and ``"loop" not in edge_options`` the option
"loop," is added to the options for the self-loop edge. Hence you can
use "[loop above]" explicitly, but the default is "[loop]".
Or a dict keyed by edge to a string holding the options for that edge.
edge_label : string or dict
The name of the edge attribute on `G` that holds the edge label (text)
displayed for each edge. If the attribute is "" or not present, no edge
label is drawn.
Or a dict keyed by edge to a string holding the label for that edge.
edge_label_options : string or dict
The name of the edge attribute on `G` that holds the label options for
each edge. For example, "[sloped,above,blue]". The default is no options.
Or a dict keyed by edge to a string holding the label options for that edge.
Returns
=======
latex_code : string
The text string which draws the desired graph(s) when compiled by LaTeX.
See Also
========
to_latex
write_latex
"""
i4 = "\n "
i8 = "\n "
# set up position dict
# TODO allow pos to be None and use a nice TikZ default
if not isinstance(pos, dict):
pos = nx.get_node_attributes(G, pos)
if not pos:
# circular layout with radius 2
pos = {n: f"({round(360.0 * i / len(G), 3)}:2)" for i, n in enumerate(G)}
for node in G:
if node not in pos:
raise nx.NetworkXError(f"node {node} has no specified pos {pos}")
posnode = pos[node]
if not isinstance(posnode, str):
try:
posx, posy = posnode
pos[node] = f"({round(posx, 3)}, {round(posy, 3)})"
except (TypeError, ValueError):
msg = f"position pos[{node}] is not 2-tuple or a string: {posnode}"
raise nx.NetworkXError(msg)
# set up all the dicts
if not isinstance(node_options, dict):
node_options = nx.get_node_attributes(G, node_options)
if not isinstance(node_label, dict):
node_label = nx.get_node_attributes(G, node_label)
if not isinstance(edge_options, dict):
edge_options = nx.get_edge_attributes(G, edge_options)
if not isinstance(edge_label, dict):
edge_label = nx.get_edge_attributes(G, edge_label)
if not isinstance(edge_label_options, dict):
edge_label_options = nx.get_edge_attributes(G, edge_label_options)
# process default options (add brackets or not)
topts = "" if tikz_options == "" else f"[{tikz_options.strip('[]')}]"
defn = "" if default_node_options == "" else f"[{default_node_options.strip('[]')}]"
linestyle = f"{'->' if G.is_directed() else '-'}"
if default_edge_options == "":
defe = "[" + linestyle + "]"
elif "-" in default_edge_options:
defe = default_edge_options
else:
defe = f"[{linestyle},{default_edge_options.strip('[]')}]"
# Construct the string line by line
result = " \\begin{tikzpicture}" + topts
result += i4 + " \\draw" + defn
# load the nodes
for n in G:
# node options goes inside square brackets
nopts = f"[{node_options[n].strip('[]')}]" if n in node_options else ""
# node text goes inside curly brackets {}
ntext = f"{{{node_label[n]}}}" if n in node_label else f"{{{n}}}"
result += i8 + f"{pos[n]} node{nopts} ({n}){ntext}"
result += ";\n"
# load the edges
result += " \\begin{scope}" + defe
for edge in G.edges:
u, v = edge[:2]
e_opts = f"{edge_options[edge]}".strip("[]") if edge in edge_options else ""
# add loop options for selfloops if not present
if u == v and "loop" not in e_opts:
e_opts = "loop," + e_opts
e_opts = f"[{e_opts}]" if e_opts != "" else ""
# TODO -- handle bending of multiedges
els = edge_label_options[edge] if edge in edge_label_options else ""
# edge label options goes inside square brackets []
els = f"[{els.strip('[]')}]"
# edge text is drawn using the TikZ node command inside curly brackets {}
e_label = f" node{els} {{{edge_label[edge]}}}" if edge in edge_label else ""
result += i8 + f"\\draw{e_opts} ({u}) to{e_label} ({v});"
result += "\n \\end{scope}\n \\end{tikzpicture}\n"
return result
_DOC_WRAPPER_TIKZ = r"""\documentclass{{report}}
\usepackage{{tikz}}
\usepackage{{subcaption}}
\begin{{document}}
{content}
\end{{document}}"""
_FIG_WRAPPER = r"""\begin{{figure}}
{content}{caption}{label}
\end{{figure}}"""
_SUBFIG_WRAPPER = r""" \begin{{subfigure}}{{{size}\textwidth}}
{content}{caption}{label}
\end{{subfigure}}"""
[docs]
def to_latex(
Gbunch,
pos="pos",
tikz_options="",
default_node_options="",
node_options="node_options",
node_label="node_label",
default_edge_options="",
edge_options="edge_options",
edge_label="edge_label",
edge_label_options="edge_label_options",
caption="",
latex_label="",
sub_captions=None,
sub_labels=None,
n_rows=1,
as_document=True,
document_wrapper=_DOC_WRAPPER_TIKZ,
figure_wrapper=_FIG_WRAPPER,
subfigure_wrapper=_SUBFIG_WRAPPER,
):
"""Return latex code to draw the graph(s) in `Gbunch`
The TikZ drawing utility in LaTeX is used to draw the graph(s).
If `Gbunch` is a graph, it is drawn in a figure environment.
If `Gbunch` is an iterable of graphs, each is drawn in a subfigure environment
within a single figure environment.
If `as_document` is True, the figure is wrapped inside a document environment
so that the resulting string is ready to be compiled by LaTeX. Otherwise,
the string is ready for inclusion in a larger tex document using ``\\include``
or ``\\input`` statements.
Parameters
==========
Gbunch : NetworkX graph or iterable of NetworkX graphs
The NetworkX graph to be drawn or an iterable of graphs
to be drawn inside subfigures of a single figure.
pos : string or list of strings
The name of the node attribute on `G` that holds the position of each node.
Positions can be sequences of length 2 with numbers for (x,y) coordinates.
They can also be strings to denote positions in TikZ style, such as (x, y)
or (angle:radius).
If a dict, it should be keyed by node to a position.
If an empty dict, a circular layout is computed by TikZ.
If you are drawing many graphs in subfigures, use a list of position dicts.
tikz_options : string
The tikzpicture options description defining the options for the picture.
Often large scale options like `[scale=2]`.
default_node_options : string
The draw options for a path of nodes. Individual node options override these.
node_options : string or dict
The name of the node attribute on `G` that holds the options for each node.
Or a dict keyed by node to a string holding the options for that node.
node_label : string or dict
The name of the node attribute on `G` that holds the node label (text)
displayed for each node. If the attribute is "" or not present, the node
itself is drawn as a string. LaTeX processing such as ``"$A_1$"`` is allowed.
Or a dict keyed by node to a string holding the label for that node.
default_edge_options : string
The options for the scope drawing all edges. The default is "[-]" for
undirected graphs and "[->]" for directed graphs.
edge_options : string or dict
The name of the edge attribute on `G` that holds the options for each edge.
If the edge is a self-loop and ``"loop" not in edge_options`` the option
"loop," is added to the options for the self-loop edge. Hence you can
use "[loop above]" explicitly, but the default is "[loop]".
Or a dict keyed by edge to a string holding the options for that edge.
edge_label : string or dict
The name of the edge attribute on `G` that holds the edge label (text)
displayed for each edge. If the attribute is "" or not present, no edge
label is drawn.
Or a dict keyed by edge to a string holding the label for that edge.
edge_label_options : string or dict
The name of the edge attribute on `G` that holds the label options for
each edge. For example, "[sloped,above,blue]". The default is no options.
Or a dict keyed by edge to a string holding the label options for that edge.
caption : string
The caption string for the figure environment
latex_label : string
The latex label used for the figure for easy referral from the main text
sub_captions : list of strings
The sub_caption string for each subfigure in the figure
sub_latex_labels : list of strings
The latex label for each subfigure in the figure
n_rows : int
The number of rows of subfigures to arrange for multiple graphs
as_document : bool
Whether to wrap the latex code in a document environment for compiling
document_wrapper : formatted text string with variable ``content``.
This text is called to evaluate the content embedded in a document
environment with a preamble setting up TikZ.
figure_wrapper : formatted text string
This text is evaluated with variables ``content``, ``caption`` and ``label``.
It wraps the content and if a caption is provided, adds the latex code for
that caption, and if a label is provided, adds the latex code for a label.
subfigure_wrapper : formatted text string
This text evaluate variables ``size``, ``content``, ``caption`` and ``label``.
It wraps the content and if a caption is provided, adds the latex code for
that caption, and if a label is provided, adds the latex code for a label.
The size is the vertical size of each row of subfigures as a fraction.
Returns
=======
latex_code : string
The text string which draws the desired graph(s) when compiled by LaTeX.
See Also
========
write_latex
to_latex_raw
"""
if hasattr(Gbunch, "adj"):
raw = to_latex_raw(
Gbunch,
pos,
tikz_options,
default_node_options,
node_options,
node_label,
default_edge_options,
edge_options,
edge_label,
edge_label_options,
)
else: # iterator of graphs
sbf = subfigure_wrapper
size = 1 / n_rows
N = len(Gbunch)
if isinstance(pos, str | dict):
pos = [pos] * N
if sub_captions is None:
sub_captions = [""] * N
if sub_labels is None:
sub_labels = [""] * N
if not (len(Gbunch) == len(pos) == len(sub_captions) == len(sub_labels)):
raise nx.NetworkXError(
"length of Gbunch, sub_captions and sub_figures must agree"
)
raw = ""
for G, pos, subcap, sublbl in zip(Gbunch, pos, sub_captions, sub_labels):
subraw = to_latex_raw(
G,
pos,
tikz_options,
default_node_options,
node_options,
node_label,
default_edge_options,
edge_options,
edge_label,
edge_label_options,
)
cap = f" \\caption{{{subcap}}}" if subcap else ""
lbl = f"\\label{{{sublbl}}}" if sublbl else ""
raw += sbf.format(size=size, content=subraw, caption=cap, label=lbl)
raw += "\n"
# put raw latex code into a figure environment and optionally into a document
raw = raw[:-1]
cap = f"\n \\caption{{{caption}}}" if caption else ""
lbl = f"\\label{{{latex_label}}}" if latex_label else ""
fig = figure_wrapper.format(content=raw, caption=cap, label=lbl)
if as_document:
return document_wrapper.format(content=fig)
return fig
[docs]
@nx.utils.open_file(1, mode="w")
def write_latex(Gbunch, path, **options):
"""Write the latex code to draw the graph(s) onto `path`.
This convenience function creates the latex drawing code as a string
and writes that to a file ready to be compiled when `as_document` is True
or ready to be ``import`` ed or ``include`` ed into your main LaTeX document.
The `path` argument can be a string filename or a file handle to write to.
Parameters
----------
Gbunch : NetworkX graph or iterable of NetworkX graphs
If Gbunch is a graph, it is drawn in a figure environment.
If Gbunch is an iterable of graphs, each is drawn in a subfigure
environment within a single figure environment.
path : filename
Filename or file handle to write to
options : dict
By default, TikZ is used with options: (others are ignored)::
pos : string or dict or list
The name of the node attribute on `G` that holds the position of each node.
Positions can be sequences of length 2 with numbers for (x,y) coordinates.
They can also be strings to denote positions in TikZ style, such as (x, y)
or (angle:radius).
If a dict, it should be keyed by node to a position.
If an empty dict, a circular layout is computed by TikZ.
If you are drawing many graphs in subfigures, use a list of position dicts.
tikz_options : string
The tikzpicture options description defining the options for the picture.
Often large scale options like `[scale=2]`.
default_node_options : string
The draw options for a path of nodes. Individual node options override these.
node_options : string or dict
The name of the node attribute on `G` that holds the options for each node.
Or a dict keyed by node to a string holding the options for that node.
node_label : string or dict
The name of the node attribute on `G` that holds the node label (text)
displayed for each node. If the attribute is "" or not present, the node
itself is drawn as a string. LaTeX processing such as ``"$A_1$"`` is allowed.
Or a dict keyed by node to a string holding the label for that node.
default_edge_options : string
The options for the scope drawing all edges. The default is "[-]" for
undirected graphs and "[->]" for directed graphs.
edge_options : string or dict
The name of the edge attribute on `G` that holds the options for each edge.
If the edge is a self-loop and ``"loop" not in edge_options`` the option
"loop," is added to the options for the self-loop edge. Hence you can
use "[loop above]" explicitly, but the default is "[loop]".
Or a dict keyed by edge to a string holding the options for that edge.
edge_label : string or dict
The name of the edge attribute on `G` that holds the edge label (text)
displayed for each edge. If the attribute is "" or not present, no edge
label is drawn.
Or a dict keyed by edge to a string holding the label for that edge.
edge_label_options : string or dict
The name of the edge attribute on `G` that holds the label options for
each edge. For example, "[sloped,above,blue]". The default is no options.
Or a dict keyed by edge to a string holding the label options for that edge.
caption : string
The caption string for the figure environment
latex_label : string
The latex label used for the figure for easy referral from the main text
sub_captions : list of strings
The sub_caption string for each subfigure in the figure
sub_latex_labels : list of strings
The latex label for each subfigure in the figure
n_rows : int
The number of rows of subfigures to arrange for multiple graphs
as_document : bool
Whether to wrap the latex code in a document environment for compiling
document_wrapper : formatted text string with variable ``content``.
This text is called to evaluate the content embedded in a document
environment with a preamble setting up the TikZ syntax.
figure_wrapper : formatted text string
This text is evaluated with variables ``content``, ``caption`` and ``label``.
It wraps the content and if a caption is provided, adds the latex code for
that caption, and if a label is provided, adds the latex code for a label.
subfigure_wrapper : formatted text string
This text evaluate variables ``size``, ``content``, ``caption`` and ``label``.
It wraps the content and if a caption is provided, adds the latex code for
that caption, and if a label is provided, adds the latex code for a label.
The size is the vertical size of each row of subfigures as a fraction.
See Also
========
to_latex
"""
path.write(to_latex(Gbunch, **options))
