Debian Codegraph @

texmf-dist/doc/latex/tikz-network/tikz-network.tex

raw
1 % =============================================================================
2 % File : tikz-network.tex -- The manual for the package tikz-network
3 % Author : Juergen Hackl <[email protected]>
4 % Creation : 2018-07-30
5 % Time-stamp: <Thu 2019-08-15 11:22 juergen>
6 %e
7 % Copyright (c) 2019 Juergen Hackl <[email protected]>
8 %
9 % This program is free software: you can redistribute it and/or modify
10 % it under the terms of the GNU General Public License as published by
11 % the Free Software Foundation, either version 3 of the License, or
12 % (at your option) any later version.
13 %
14 % This program is distributed in the hope that it will be useful,
15 % but WITHOUT ANY WARRANTY; without even the implied warranty of
16 % MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 % GNU General Public License for more details.
18 %
19 % You should have received a copy of the GNU General Public License
20 % along with this program. If not, see <http://www.gnu.org/licenses/>.
21 % =============================================================================
22
23 \documentclass[a4paper,twosided,notoc]{tufte-book}
24 \usepackage{siunitx}
25 \hypersetup{colorlinks}% uncomment this line if you prefer colored hyperlinks (e.g., for onscreen viewing)
26
27 %%
28 % Book metadata
29 \title{tikz-network\\manual}
30 \author[J\"urgen Hackl]{J\"urgen Hackl}
31 \publisher{Version 1.1}
32
33 %%
34 % If they're installed, use Bergamo and Chantilly from www.fontsite.com.
35 % They're clones of Bembo and Gill Sans, respectively.
36 %\IfFileExists{bergamo.sty}{\usepackage[osf]{bergamo}}{}% Bembo
37 %\IfFileExists{chantill.sty}{\usepackage{chantill}}{}% Gill Sans
38
39 %\usepackage{microtype}
40
41 \usepackage{framed}
42 \definecolor{shadecolor}{HTML}{abd7e6}%{cmyk}{0.49,0.22,.15,0}
43 \definecolor{hlcolor}{HTML}{057498}%{cmyk}{0.49,0.22,.15,0}
44 \FrameSep0pt
45
46 \usepackage{tikz}
47 \usetikzlibrary{backgrounds}
48 \tikzset{background rectangle/.style={fill=yellow!30}}
49
50
51 %%
52 % Just some sample text
53 \usepackage{lipsum}
54
55 %%
56 % For nicely typeset tabular material
57 \usepackage{booktabs}
58 \usepackage{tabularx}
59
60 %%
61 % For graphics / images
62 \usepackage{graphicx}
63 \setkeys{Gin}{width=\linewidth,totalheight=\textheight,keepaspectratio}
64 \graphicspath{{data/}}
65
66 % The fancyvrb package lets us customize the formatting of verbatim
67 % environments. We use a slightly smaller font.
68 \usepackage{fancyvrb}
69 \fvset{fontsize=\normalsize}
70
71 %%
72 % Prints argument within hanging parentheses (i.e., parentheses that take
73 % up no horizontal space). Useful in tabular environments.
74 \newcommand{\hangp}[1]{\makebox[0pt][r]{(}#1\makebox[0pt][l]{)}}
75
76 %%
77 % Prints an asterisk that takes up no horizontal space.
78 % Useful in tabular environments.
79 \newcommand{\hangstar}{\makebox[0pt][l]{*}}
80
81 %%
82 % Prints a trailing space in a smart way.
83 \usepackage{xspace}
84
85 %%
86 % needed for its \numberwithin command
87 \usepackage{amsmath}
88
89 %%
90 % Some shortcuts for Tufte's book titles. The lowercase commands will
91 % produce the initials of the book title in italics. The all-caps commands
92 % will print out the full title of the book in italics.
93 \newcommand{\vdqi}{\textit{VDQI}\xspace}
94 \newcommand{\ei}{\textit{EI}\xspace}
95 \newcommand{\ve}{\textit{VE}\xspace}
96 \newcommand{\be}{\textit{BE}\xspace}
97 \newcommand{\VDQI}{\textit{The Visual Display of Quantitative Information}\xspace}
98 \newcommand{\EI}{\textit{Envisioning Information}\xspace}
99 \newcommand{\VE}{\textit{Visual Explanations}\xspace}
100 \newcommand{\BE}{\textit{Beautiful Evidence}\xspace}
101
102 \newcommand{\TL}{Tufte-\LaTeX\xspace}
103
104 % Prints the month name (e.g., January) and the year (e.g., 2008)
105 \newcommand{\monthyear}{%
106 \ifcase\month\or January\or February\or March\or April\or May\or June\or
107 July\or August\or September\or October\or November\or
108 December\fi\space\number\year
109 }
110
111
112 % Prints an epigraph and speaker in sans serif, all-caps type.
113 \newcommand{\openepigraph}[2]{%
114 %\sffamily\fontsize{14}{16}\selectfont
115 \begin{fullwidth}
116 \sffamily\large
117 \begin{doublespace}
118 \noindent\allcaps{#1}\\% epigraph
119 \noindent\allcaps{#2}% author
120 \end{doublespace}
121 \end{fullwidth}
122 }
123
124 % Inserts a blank page
125 \newcommand{\blankpage}{\newpage\hbox{}\thispagestyle{empty}\newpage}
126
127 \usepackage{units}
128
129 % Typesets the font size, leading, and measure in the form of 10/12x26 pc.
130 \newcommand{\measure}[3]{#1/#2$\times$\unit[#3]{pc}}
131
132 % Macros for typesetting the documentation
133 \newcommand{\hlred}[1]{\textcolor{hlcolor}{#1}}% prints in red
134 \newcommand{\hangleft}[1]{\makebox[0pt][r]{#1}}
135 \newcommand{\hairsp}{\hspace{1pt}}% hair space
136 \newcommand{\hquad}{\hskip0.5em\relax}% half quad space
137 \newcommand{\TODO}{\textcolor{red}{\bf TODO!}\xspace}
138 \newcommand{\na}{\quad--}% used in tables for N/A cells
139 \providecommand{\XeLaTeX}{X\lower.5ex\hbox{\kern-0.15em\reflectbox{E}}\kern-0.1em\LaTeX}
140 \newcommand{\tXeLaTeX}{\XeLaTeX\index{XeLaTeX@\protect\XeLaTeX}}
141 % \index{\texttt{\textbackslash xyz}@\hangleft{\texttt{\textbackslash}}\texttt{xyz}}
142 \newcommand{\tuftebs}{\symbol{'134}}% a backslash in tt type in OT1/T1
143 \newcommand{\doccmdnoindex}[2][]{\texttt{\tuftebs#2}}% command name -- adds backslash automatically (and doesn't add cmd to the index)
144 \newcommand{\doccmddef}[2][]{%
145 \hlred{\texttt{\tuftebs#2}}\label{cmd:#2}%
146 \ifthenelse{\isempty{#1}}%
147 {% add the command to the index
148 \index{#2 command@\protect\hangleft{\texttt{\tuftebs}}\texttt{#2}}% command name
149 }%
150 {% add the command and package to the index
151 \index{#2 command@\protect\hangleft{\texttt{\tuftebs}}\texttt{#2} (\texttt{#1} package)}% command name
152 \index{#1 package@\texttt{#1} package}\index{packages!#1@\texttt{#1}}% package name
153 }%
154 }% command name -- adds backslash automatically
155 \newcommand{\doccmd}[2][]{%
156 \texttt{\tuftebs#2}%
157 \ifthenelse{\isempty{#1}}%
158 {% add the command to the index
159 \index{#2 command@\protect\hangleft{\texttt{\tuftebs}}\texttt{#2}}% command name
160 }%
161 {% add the command and package to the index
162 \index{#2 command@\protect\hangleft{\texttt{\tuftebs}}\texttt{#2} (\texttt{#1} package)}% command name
163 \index{#1 package@\texttt{#1} package}\index{packages!#1@\texttt{#1}}% package name
164 }%
165 }% command name -- adds backslash automatically
166 \newcommand{\docopt}[1]{\ensuremath{\langle}\textrm{\textit{#1}}\ensuremath{\rangle}}% optional command argument
167 \newcommand{\docarg}[1]{\textrm{\textit{#1}}}% (required) command argument
168 %%%\newenvironment{docspec}{\begin{shaded}\begin{quotation}\ttfamily\parskip0pt\parindent0pt\ignorespaces}{\end{quotation}\end{shaded}}% command specification environment
169 \newenvironment{docspecdef}{\begin{quotation}\ttfamily\parskip0pt\parindent0pt\ignorespaces}{\end{quotation}}% command specification environment
170 \newcommand{\docenv}[1]{\texttt{#1}\index{#1 environment@\texttt{#1} environment}\index{environments!#1@\texttt{#1}}}% environment name
171 \newcommand{\docenvdef}[1]{\hlred{\texttt{#1}}\label{env:#1}\index{#1 environment@\texttt{#1} environment}\index{environments!#1@\texttt{#1}}}% environment name
172 \newcommand{\docpkg}[1]{\texttt{#1}\index{#1 package@\texttt{#1} package}\index{packages!#1@\texttt{#1}}}% package name
173 \newcommand{\doccls}[1]{\texttt{#1}}% document class name
174 \newcommand{\docclsopt}[1]{\texttt{#1}\index{#1 class option@\texttt{#1} class option}\index{class options!#1@\texttt{#1}}}% document class option name
175 \newcommand{\docclsoptdef}[1]{\hlred{\texttt{#1}}\label{clsopt:#1}\index{#1 class option@\texttt{#1} class option}\index{class options!#1@\texttt{#1}}}% document class option name defined
176 \newcommand{\docmsg}[2]{\bigskip\begin{fullwidth}\noindent\ttfamily#1\end{fullwidth}\medskip\par\noindent#2}
177 \newcommand{\docfilehook}[2]{\texttt{#1}\index{file hooks!#2}\index{#1@\texttt{#1}}}
178 \newcommand{\doccounter}[1]{\texttt{#1}\index{#1 counter@\texttt{#1} counter}}
179
180 %%
181 % Example environment
182
183 % Create counter
184 \newcounter{doccount}
185
186 \newenvironment{docspec}{%
187 \bigskip\noindent% create a vertical offset to previous material
188 \refstepcounter{doccount}% increment the environment's counter
189 \llap{\parbox{1.5cm}{\hfill\small\thedoccount}\hspace{2mm}}\vspace{-9mm}
190 \begin{shaded}
191 }
192 {\vspace{-5mm}\end{shaded}}% command specification environment
193 \numberwithin{doccount}{chapter}
194
195 % Numerate the sections
196 \setcounter{secnumdepth}{2}
197
198 \setcounter{tocdepth}{3}
199
200 \newenvironment{docspeca}{\begin{shaded}}
201 {\vspace{-5mm}\end{shaded}}% command specification environment
202
203
204
205 \usepackage{etoolbox}
206
207 \makeatletter
208 \patchcmd{\ttlh@hang}{\parindent\z@}{\parindent\z@\leavevmode}{}{}
209 %\patchcmd{\ttlh@hang}{\noindent}{}{}{}
210 \patchcmd{\ttlh@hang}{\noindent}{}{}{}
211 \makeatother
212
213
214 % chapter format
215 \titleformat{\chapter}%
216 {\huge\rmfamily\itshape}% format applied to label+text
217 {\llap{\parbox{1.5cm}{\hfill\itshape\huge\thechapter}\hspace{2mm}}}% label
218 {0em}% horizontal separation between label and title body
219 {}% before the title body
220 []% after the title body
221
222 % section format
223 \titleformat{\section}%
224 {\normalfont\Large\itshape}% format applied to label+text
225 {\llap{\parbox{1.0cm}{\hfill\thesection}\hspace{2mm}}}% label
226 {0em}% horizontal separation between label and title body
227 {}% before the title body
228 []% after the title body
229
230 % subsection format
231 \titleformat{\subsection}%
232 {\normalfont\large\itshape}% format applied to label+text
233 {\llap{\parbox{1.5cm}{\hfill\thesubsection}\hspace{2mm}}}% label
234 {0em}% horizontal separation between label and title body
235 {}% before the title body
236 []% after the title body
237
238 \newcommand{\pkg}{\doccls{tikz-network}\xspace}
239 \newcommand{\tikzsym}{Ti\emph{k}Z }
240
241 \usepackage{listings}
242 \lstset{ %
243 basicstyle=\small\linespread{.8}\ttfamily,
244 commentstyle=\itshape\color{black!70},
245 stepnumber=2,
246 showspaces=false,
247 showstringspaces=false,
248 showtabs=false,
249 tabsize=2,
250 captionpos=b,
251 breaklines=true,
252 breakatwhitespace=false,
253 title=\lstname,
254 escapeinside={+*}{*+},
255 morekeywords={*,...},
256 stringstyle=\ttfamily,
257 emphstyle={\color{red}\bfseries},
258 }
259
260 \usepackage{tikz-network}
261
262
263 % Generates the index
264 \usepackage{makeidx}
265 \makeindex
266
267 \renewcommand{\chaptermark}[1]{%
268 \markboth{#1}{}}
269
270 \fancyhead[LE]{\thepage\quad\smallcaps{\newlinetospace{\leftmark}}}
271
272 \begin{document}
273
274
275 %\maketitle
276
277 \thispagestyle{empty}
278
279 \begin{fullwidth}%
280 \sffamily%
281 \fontsize{18}{20}\selectfont\par\noindent\textcolor{darkgray}{\allcaps{\thanklessauthor}}%
282 \vspace{11.5pc}%
283 \fontsize{36}{40}\selectfont\par\noindent\textcolor{darkgray}{\allcaps{\thanklesstitle}}%
284 \vspace{3cm}
285 \begin{center}
286 \includegraphics[width=14cm]{data/front.pdf}%
287 \end{center}
288 \vfill%
289 \fontsize{14}{16}\selectfont\par\noindent\allcaps{\thanklesspublisher}%
290 \end{fullwidth}%
291
292
293 \newpage
294
295 \begin{fullwidth}
296 % \begin{tikzpicture}[remember picture, overlay]
297 % \node[rectangle,inner sep=2pt,fill=red!30,draw=black,text width=12cm] at ($(current page.center)+(0,6)$) {%
298 % The \pkg package is still under development. Hence, changes in the commands and functionality cannot be excluded.
299 % };
300 % \end{tikzpicture}
301
302 ~\vfill
303 \thispagestyle{empty}
304 \setlength{\parindent}{0pt}
305 \setlength{\parskip}{\baselineskip}
306
307
308 \par\smallcaps{\pkg}
309 \par\smallcaps{\thanklesspublisher}
310 \par\smallcaps{\url{https://github.com/hackl/tikz-network}}
311
312 \par\textit{Released, \monthyear}
313
314 Copyright \copyright\ \the\year\ \thanklessauthor
315
316 This program is free software: you can redistribute it and/or modify
317 it under the terms of the GNU General Public License as published by
318 the Free Software Foundation, either version 3 of the License, or
319 (at your option) any later version.
320
321 This program is distributed in the hope that it will be useful,
322 but WITHOUT ANY WARRANTY; without even the implied warranty of
323 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
324 GNU General Public License for more details.
325
326 You should have received a copy of the GNU General Public License
327 along with this program. If not, see \url{https://www.gnu.org/licenses/}.
328
329
330 \end{fullwidth}
331
332 \begin{fullwidth}
333 \tableofcontents
334 \end{fullwidth}
335
336 \cleardoublepage
337 \chapter{Introduction}
338
339 In recent years, complex network theory becomes more and more popular within the scientific community. Besides a solid mathematical base on which these theories are built on, a visual representation of the networks allow communicating complex relationships to a broad audience.
340
341 Nowadays, a variety of great visualization tools are available, which helps to structure, filter, manipulate and of course to visualize the networks. However, they come with some limitations, including the need for specific software tools, difficulties to embed the outputs properly in a \LaTeX~file (e.g. font type, font size, additional equations and math symbols needed, \dots) and challenges in the post-processing of the graphs, without rerunning the software tools again.
342
343 In order to overcome this issues, the package \pkg was created. Some of the features are:
344
345 \begin{itemize}
346 \item \LaTeX~ is a standard for scientific publications and widely used
347 \item beside \LaTeX~ no other software is needed
348 \item no programming skills are needed
349 \item simple to use but allows 100\% control over the output
350 \item easy for post-processing (e.g. adding drawings, texts, equations,\dots)
351 \item same fonts, font sizes, mathematical symbols, \dots as in the document
352 \item no quality loss of the output due to the pdf format
353 \item networks are easy to adapt or modify for lectures or small examples
354 \item able to visualize larger networks
355 \item three-dimensional visualization of (multilayer) networks
356 \item compatible with other visualization tools
357 \end{itemize}
358 \newpage
359
360 \section{How to read this manual?}
361
362 The aim of this manual is to describe the use of the \pkg library for visualizing networks. To ensure an easy use of the elements and to keep the clarity, this manual is structured as follows:
363 \begin{itemize}
364 \item In Chapter \ref{chap:simple_networks} the elements to create simple networks (by hand) in a plane are explained. Thereby, the use of the commands \doccmd{Vertex} and \doccmd{Edge} are shown.
365 \item How to create complex networks from external files\footnote{e.g. \doccls{igraph} or \doccls{networkx}} are explained in Chapter \ref{chap:complex_networks}. The main commands, therefore are \doccmd{Vertices} and \doccmd{Edges} which are using the same options as in the simple case.
366 \item In Chapter \ref{chap:multilayer_networks}, the visualization of multilayer networks is explained. Additional visualization tools such as \doccmd{Plane} and \docenv{Layer} are introduced.
367 \item The default settings used and how they can be modified is explained in Chapter \ref{chap:default_settings}.
368 \item Information about troubleshooting and support is given in Chapter \ref{chap:troubleshooting}
369 \item Since this is the alpha version (0.1) of the package, features which will be probably added and commands which have to be fixed are listed in Appendix \ref{chap:todo}.
370 \end{itemize}
371
372 \subsection{A few explanations}
373
374 The images in this manual are created with the \pkg library or \tikzsym. The code used for this is
375 specified for each image.
376 \begin{marginfigure}[30mm]
377 \centering
378 \begin{tikzpicture}%[framed]
379 \filldraw (-.2,.2) circle (2pt) (.2,.2) circle (2pt);
380 \draw (0,0) circle (5mm) (-.3,-.1) .. controls (0,-.3) .. (.3,-.1);
381 \end{tikzpicture}
382 \end{marginfigure}
383
384 \begin{docspec}
385 \begin{lstlisting}
386 \begin{tikzpicture}
387 \filldraw (-.2,.2) circle (2pt) (.2,.2) circle (2pt);
388 \draw (0,0) circle (5mm) (-.3,-.1) .. controls (0,-.3) .. (.3,-.1);
389 \end{tikzpicture}
390 \end{lstlisting}
391 \end{docspec}
392
393 Special additions which are needed for a better understanding are shown in orange but are not in the sample code available.
394
395 \begin{marginfigure}[23mm]
396 \centering
397 \begin{tikzpicture}%[framed]
398 \filldraw [orange] (0,0) circle (2pt)
399 (1,1) circle (2pt)
400 (2,1) circle (2pt)
401 (2,0) circle (2pt);
402 \draw (0,0) .. controls (1,1) and (2,1) .. (2,0);
403 \end{tikzpicture}
404 \end{marginfigure}
405
406 \begin{docspec}
407 \begin{lstlisting}
408 \begin{tikzpicture}
409 \draw (0,0) .. controls (1,1) and (2,1) .. (2,0);
410 \end{tikzpicture}
411 \end{lstlisting}
412 \end{docspec}
413
414 \subsection{Inputs}
415 \label{sec:inputs}
416
417 The commands in the \pkg library (e.g. \doccmd{Vertex}, \doccmd{Edge}) always start with capital letters and DO NOT need a semicolon <<;>> at the end. Boolean arguments start also with capital letters (e.g. \docopt{NoLabel}). Arguments which need an user input, use are written in small letters (e.g. \docopt{color}).
418
419 Basically, one can distinguish between the mandatory argument $\{~\}$ and the optional argument $[~]$. The first values must be entered compulsory. By contrast, nothing has to be entered for the optional input. Additional features (e.g. \docopt{size})) can be activated when entering optional parameters.
420
421 When entering size values the base unit is always predefined in $[cm]$\footnote{The default unit can be changed with \doccmd{SetDefaultUnit}; see Section~\ref{sec:gerneral_settings}}, except for line widths which are dedined in $[pt]$. Percentage values $\%$ are always specified as decimal values; for example, $100\% = 1.0 $ and $ 10 \% $ corresponds to $ 0.1 $.
422
423
424 \subsection{Additional help}
425
426 Is the manual not enough, occur some ambiguities or some \tikzsym commands are unclear, please have a look in the ``\tikzsym and PGF Manual'' from Till Tantau\footnote{\url{http://mirror.switch.ch/ftp/mirror/tex/graphics/pgf/base/doc/pgfmanual.pdf}}.
427
428 Should you have any further questions, please do not hesitate to contact me.
429
430 \section{Installation}
431 \label{sec:Installation}
432
433 Actually, we can hardly speak of an installation since only the necessary package \pkg must be loaded in the preamble of your document.
434
435 The current release of the package is available via CTAN\footnote{\url{https://ctan.org/pkg/tikz-network}}. A release candidate for the next version of \pkg is available on github\footnote{\url{https://github.com/hackl/}}
436
437 Is the package installed or the style file is stored in the folder of the main file, so the library can be imported, as the following example shows:
438
439 \begin{docspec}
440 \begin{lstlisting}
441 % ------------
442 % header
443 \documentclass{scrreprt}
444
445 % ------------
446 % packages
447 \usepackage{tikz-network}
448 \end{lstlisting}
449 \end{docspec}
450
451 \section{Additional necessary packages}
452
453 To use all commands and options of \tikzsym, possibly some packages need to be reloaded. These missing files (or their names) appear in the error log when you convert the file. However, for the package described in this manual, it is sufficient to use the library and the \tikzsym standard commands.
454
455 \chapter{Simple Networks}
456 \label{chap:simple_networks}
457
458 \section{Vertex}
459 \label{sec:vertex}
460 On essential command is \doccmddef{Vertex}, which allow placing vertices in the document and modify their appearance.
461 \begin{docspecdef}
462 \doccmd{Vertex}[\docopt{local options}]\{\docarg{Name}\}
463 \end{docspecdef}
464 In order to be able to place a vertex, a non-empty \docarg{Name} argument is required. This argument defines the vertex's reference name, which must be unique. Mathematical symbols are not allowed as name as well as no blank spaces. The \docarg{Name} should not be confused with the \docopt{label}, that is used for display; for example one may want to display $A_1$ while the name will be \docarg{A1}.
465
466 For a \doccmd{Vertex} the following options are available:
467
468 \begin{table}[h]\index{Vertex!options}
469 \footnotesize%
470 \begin{center}
471 \begin{tabular}{lccl}
472 \toprule
473 Option & Default & Type &Definition \\
474 \midrule
475 x & 0 & measure& x-coordinate \\
476 y & 0 & measure& y-coordinate \\
477 size & \{\} & measure& diameter of the circle\\
478 color & \{\} & color & fill color of vertex\\
479 opacity & \{\} & number & opacity of the fill color \\
480 shape & \{\} & string & shape of the vertex\\
481 label & \{\} & string & label \\
482 fontsize & \{\} & string & font size of the label\\
483 fontcolor & \{\} & color & font color of the label\\
484 fontscale & \{\} & number & scale of the label\\
485 position & center& value$^a$ & label position\\
486 distance & 0 & measure & label distance from the center \\
487 style & \{\} & string & additional \tikzsym styles \\
488 layer & \{\} & number & assigned layer of the vertex \\
489 \midrule
490 NoLabel & false & Boolean & delete the label \\
491 IdAsLabel & false & Boolean & uses the \docarg{Name} as label \\
492 Math & false & Boolean & displays the label in math mode \\
493 RGB & false & Boolean & allow RGB colors \\
494 Pseudo & false & Boolean & create a pseudo vertex\\
495 \bottomrule
496 \end{tabular}
497 \scriptsize
498 \\$^a$ either measure or string
499 \end{center}
500 \caption{Local options for the \doccmd{Vertex} command.}
501 \label{tab:vertex_options}
502 \end{table}
503
504 The order how the options are entered does not matter. Changes to the default Vertex layout can be made with \doccmd{SetVertexStyle}\footnote{see Section \ref{sec:vertex_style}}
505
506 \begin{docspecdef}
507 \doccmd{Vertex}[\docopt{x}=\docarg{measure},\docopt{y}=\docarg{measure}]\{\docarg{Name}\}
508 \end{docspecdef}
509
510 The location of the vertices are determined by Cartesian coordinates in \docopt{x} and \docopt{y}. The coordinates are optional. If no coordinates are determined the vertex will be placed at the origin ($0,0$). The entered \docarg{measures} are in default units (\si{cm}). Changing the unites (locally) can be done by adding the unit to the \docarg{measure}\footnote{e.g. x=\SI{1}{in}}. Changes to the default setting can be made with \doccmd{SetDefaultUnit}\footnote{see Section \ref{sec:gerneral_settings}}.
511
512 %\newpage
513 \begin{marginfigure}[6mm]
514 \centering
515 \begin{tikzpicture}
516 \Vertex{A}
517 \Vertex[x=1,y=1]{B}
518 \Vertex[x=2]{C}
519 \node at (0,0)[font=\footnotesize,orange]{\textbf{A}};
520 \node at (1,1)[font=\footnotesize,orange]{\textbf{B}};
521 \node at (2,0)[font=\footnotesize,orange]{\textbf{C}};
522 \end{tikzpicture}
523 \end{marginfigure}
524
525 \begin{docspec}
526 \begin{lstlisting}
527 \begin{tikzpicture}
528 \Vertex{A}
529 \Vertex[x=1,y=1]{B}
530 \Vertex[x=2]{C}
531 \end{tikzpicture}
532 \end{lstlisting}
533 \end{docspec}
534
535 \begin{docspecdef}
536 \doccmd{Vertex}[\docopt{size}=\docarg{measure}]\{\docarg{Name}\}
537 \end{docspecdef}
538
539 The diameter of the vertex can be changed with the option \docopt{size}. Per default a vertex has \SI{0.6}{cm} in diameter. Also, here the default units are \si{cm} and have not to be added to the \docarg{measure}.
540
541 \begin{marginfigure}[34mm]
542 \centering
543 \begin{tikzpicture}
544 \Vertex[size=.3]{A}
545 \Vertex[x=1,size=.7]{B}
546 \Vertex[x=2.3,size=1]{C}
547 \end{tikzpicture}
548 \end{marginfigure}
549
550 \begin{docspec}
551 \begin{lstlisting}
552 \begin{tikzpicture}
553 \Vertex[size=.3]{A}
554 \Vertex[x=1,size=.7]{B}
555 \Vertex[x=2.3,size=1]{C}
556 \end{tikzpicture}
557 \end{lstlisting}
558 \end{docspec}
559
560 \begin{docspecdef}
561 \doccmd{Vertex}[\docopt{color}=\docarg{color}]\{\docarg{Name}\}
562 \end{docspecdef}
563
564 To change the fill color of each vertex individually, the option \docopt{color} has to be used. Without the option \docopt{RGB} set, the default \tikzsym and \LaTeX~ colors can be applied.
565
566 \begin{marginfigure}[34mm]
567 \centering
568 \begin{tikzpicture}
569 \Vertex[color = blue]{A}
570 \Vertex[x=1,color=red]{B}
571 \Vertex[x=2,color=green!70!blue]{C}
572 \end{tikzpicture}
573 \end{marginfigure}
574
575 \begin{docspec}
576 \begin{lstlisting}
577 \begin{tikzpicture}
578 \Vertex[color = blue]{A}
579 \Vertex[x=1,color=red]{B}
580 \Vertex[x=2,color=green!70!blue]{C}
581 \end{tikzpicture}
582 \end{lstlisting}
583 \end{docspec}
584
585 \begin{docspecdef}
586 \doccmd{Vertex}[\docopt{opacity}=\docarg{number}]\{\docarg{Name}\}
587 \end{docspecdef}
588
589 With the option \docopt{opacity} the opacity of the vertex fill color can be modified. The range of the \docarg{number} lies between $0$ and $1$. Where $0$ represents a fully transparent fill and $1$ a solid fill.
590
591 \begin{marginfigure}[34mm]
592 \centering
593 \begin{tikzpicture}
594 \draw[thick,orange,dashed] (-.5,0) -- (2.5,0);
595 \Vertex[opacity = 1]{A}
596 \Vertex[x=1,opacity =.7]{B}
597 \Vertex[x=2,opacity =.2]{C}
598 \end{tikzpicture}
599 \end{marginfigure}
600
601 \begin{docspec}
602 \begin{lstlisting}
603 \begin{tikzpicture}
604 \Vertex[opacity = 1]{A}
605 \Vertex[x=1,opacity =.7]{B}
606 \Vertex[x=2,opacity =.2]{C}
607 \end{tikzpicture}
608 \end{lstlisting}
609 \end{docspec}
610
611 \begin{docspecdef}
612 \doccmd{Vertex}[\docopt{shape}=\docarg{string}]\{\docarg{Name}\}
613 \end{docspecdef}
614
615 With the option \docopt{shape} the shape of the vertex can be modified. Thereby the shapes implemented in \tikzsym can be used, including: \docarg{circle}, \docarg{rectangle}, \docarg{diamond}, \docarg{trapezium}, \docarg{semicircle}, \docarg{isosceles triangle}, \dots.
616
617 \begin{marginfigure}[34mm]
618 \centering
619 \begin{tikzpicture}
620 \Vertex[shape = rectangle]{A}
621 \Vertex[x=1,shape = diamond]{B}
622 \Vertex[x=2,shape = isosceles triangle]{C}
623 \end{tikzpicture}
624 \end{marginfigure}
625
626 \begin{docspec}
627 \begin{lstlisting}
628 \begin{tikzpicture}
629 \Vertex[shape = rectangle]{A}
630 \Vertex[x=1,shape = diamond]{B}
631 \Vertex[x=2,shape = isosceles triangle]{C}
632 \end{tikzpicture}
633 \end{lstlisting}
634 \end{docspec}
635
636 \begin{docspecdef}
637 \doccmd{Vertex}[\docopt{label}=\docarg{string}]\{\docarg{Name}\}
638 \end{docspecdef}
639
640 In \pkg there are several ways to define the labels of the vertices and edges. The common way is via the option \docopt{label}. Here, any \docarg{string} argument can be used, including blank spaces. The environment \$ \$ can be used to display mathematical expressions.
641
642 \begin{marginfigure}[34mm]
643 \centering
644 \begin{tikzpicture}
645 \Vertex[label=foo]{A}
646 \Vertex[x=1,label=bar]{B}
647 \Vertex[x=2,label=$u_1$]{C}
648 \end{tikzpicture}
649 \end{marginfigure}
650
651 \begin{docspec}
652 \begin{lstlisting}
653 \begin{tikzpicture}
654 \Vertex[label=foo]{A}
655 \Vertex[x=1,label=bar]{B}
656 \Vertex[x=2,label=$u_1$]{C}
657 \end{tikzpicture}
658 \end{lstlisting}
659 \end{docspec}
660
661 \begin{docspecdef}
662 \doccmd{Vertex}[\docopt{label}=\docarg{string},\docopt{fontsize}=\docarg{string}]\{\docarg{Name}\}
663 \end{docspecdef}
664
665 The font size of the \docopt{label} can be modified with the option \docopt{fontsize}. Here common \LaTeX~ font size commands\footnote{e.g. \doccmd{tiny}, \doccmd{scriptsize}, \doccmd{footnotesize}, \doccmd{small}, \dots.} can be used to change the size of the label.
666
667 \begin{marginfigure}[10mm]
668 \centering
669 \begin{tikzpicture}
670 \Vertex[label=foo,fontsize=\normalsize]{A}
671 \Vertex[x=1,label=bar,fontsize=\tiny]{B}
672 \Vertex[x=2,label=$u_1$,fontsize=\large]{C}
673 \end{tikzpicture}
674 \end{marginfigure}
675
676 \begin{docspec}
677 \begin{lstlisting}
678 \begin{tikzpicture}
679 \Vertex[label=foo,fontsize=\normalsize]{A}
680 \Vertex[x=1,label=bar,fontsize=\tiny]{B}
681 \Vertex[x=2,label=$u_1$,fontsize=\large]{C}
682 \end{tikzpicture}
683 \end{lstlisting}
684 \end{docspec}
685
686 \begin{docspecdef}
687 \doccmd{Vertex}[\docopt{label}=\docarg{string},\docopt{fontcolor}=\docarg{color}]\{\docarg{Name}\}
688 \end{docspecdef}
689
690 The color of the \docopt{label} can be changed with the option \docopt{fontcolor}. Currently, only the default \tikzsym and \LaTeX~ colors are supported\footnote{\TODO Add RGB option!}.
691
692 \begin{marginfigure}[8mm]
693 \centering
694 \begin{tikzpicture}
695 \Vertex[label=foo,fontcolor=blue]{A}
696 \Vertex[x=1,label=bar,fontcolor=magenta]{B}
697 \Vertex[x=2,label=$u_1$,fontcolor=red]{C}
698 \end{tikzpicture}
699 \end{marginfigure}
700
701 \begin{docspec}
702 \begin{lstlisting}
703 \begin{tikzpicture}
704 \Vertex[label=foo,fontcolor=blue]{A}
705 \Vertex[x=1,label=bar,fontcolor=magenta]{B}
706 \Vertex[x=2,label=$u_1$,fontcolor=red]{C}
707 \end{tikzpicture}
708 \end{lstlisting}
709 \end{docspec}
710
711 \begin{docspecdef}
712 \doccmd{Vertex}[\docopt{label}=\docarg{string},\docopt{fontscale}=\docarg{number}]\{\docarg{Name}\}
713 \end{docspecdef}
714
715 Contrary to the option \docopt{fontsize}, the option \docopt{fontscale} does not change the font size itself but scales the curent font size up or down. The \docarg{number} defines the scale, where numbers between $0$ and $1$ down scale the font and numbers greater then $1$ up scale the label. For example $0.5$ reduces the size of the font to $50\%$ of its originial size, while $1.2$ scales the font to $120\%$.
716
717 \begin{marginfigure}[34mm]
718 \centering
719 \begin{tikzpicture}
720 \Vertex[label=foo,fontscale=0.5]{A}
721 \Vertex[x=1,label=bar,fontscale=1]{B}
722 \Vertex[x=2,label=$u_1$,fontscale=2]{C}
723 \end{tikzpicture}
724 \end{marginfigure}
725
726 \begin{docspec}
727 \begin{lstlisting}
728 \begin{tikzpicture}
729 \Vertex[label=foo,fontscale=0.5]{A}
730 \Vertex[x=1,label=bar,fontscale=1]{B}
731 \Vertex[x=2,label=$u_1$,fontscale=2]{C}
732 \end{tikzpicture}
733 \end{lstlisting}
734 \end{docspec}
735
736 \begin{docspecdef}
737 \doccmd{Vertex}[\docopt{label}=\docarg{string},\docopt{position}=\docarg{value},\docopt{distance}=\docarg{number}]\{\docarg{Name}\}
738 \end{docspecdef}
739
740 Per default the \docopt{position} of the \docopt{label} is in the \docarg{center} of the vertex. Classical \tikzsym commands\footnote{e.g. \docarg{above}, \docarg{below}, \docarg{left}, \docarg{right}, \docarg{above left}, \docarg{above right},\dots} can be used to change the \docopt{position} of the \docopt{label}. Instead, using such command, the position can be determined via an angle, by entering a \docarg{number} between $-360$ and $360$. The origin ($0^\circ$) is the $y$ axis. A positive \docarg{number} change the \docopt{position} counter clockwise, while a negative \docarg{number} make changes clockwise.
741
742 With the option, \docopt{distance} the distance between the vertex and the label can be changed.
743
744 \begin{marginfigure}[31mm]
745 \centering
746 \begin{tikzpicture}
747 \Vertex[label=A,position=below]{A}
748 \Vertex[x=1,label=B,position=below,distance=2mm]{B}
749 \Vertex[x=2,label=C,position=30,distance=1mm]{C}
750 \draw[orange,dashed](2,0) --++ (7mm,0mm)(2,0)--++(30:7mm);
751 \draw[orange,->] (2.5,0) arc (0:30:5mm);
752 \node[orange] (x) at (2.6,-.2) {$30^\circ$};
753 \end{tikzpicture}
754 \end{marginfigure}
755
756 \begin{docspec}
757 \begin{lstlisting}
758 \begin{tikzpicture}
759 \Vertex[label=A,position=below]{A}
760 \Vertex[x=1,label=B,position=below,distance=2mm]{B}
761 \Vertex[x=2,label=C,position=30,distance=1mm]{C}
762 \end{tikzpicture}
763 \end{lstlisting}
764 \end{docspec}
765
766 \begin{docspecdef}
767 \doccmd{Vertex}[\docopt{style}=\{\docarg{string}\}]\{\docarg{Name}\}
768 \end{docspecdef}
769
770 Any other \tikzsym style option or command can be entered via the option \docopt{style}. Most of these commands can be found in the ``\tikzsym and PGF Manual''. Contain the commands additional options (e.g.\docopt{shading}=\docarg{ball}), then the argument for the \docopt{style} has to be between $\{~\}$ brackets.
771
772 \begin{marginfigure}[32mm]
773 \centering
774 \begin{tikzpicture}
775 \Vertex[style={color=green}]{A}
776 \Vertex[x=1,style=dashed]{B}
777 \Vertex[x=2,style={shading=ball}]{C}
778 \end{tikzpicture}
779 \end{marginfigure}
780
781 \begin{docspec}
782 \begin{lstlisting}
783 \begin{tikzpicture}
784 \Vertex[style={color=green}]{A}
785 \Vertex[x=1,style=dashed]{B}
786 \Vertex[x=2,style={shading=ball}]{C}
787 \end{tikzpicture}
788 \end{lstlisting}
789 \end{docspec}
790
791 \begin{docspecdef}
792 \doccmd{Vertex}[\docopt{IdAsLabel}]\{\docarg{Name}\}
793 \end{docspecdef}
794 \begin{docspecdef}
795 \doccmd{Vertex}[\docopt{NoLabel},\docopt{label}=\docarg{string}]\{\docarg{Name}\}
796 \end{docspecdef}
797
798 \docopt{IdAsLabel} is a Boolean option which assigns the \docarg{Name} of the vertex as label. On the contrary, \docopt{NoLabel} suppress all labels.
799
800 \begin{marginfigure}[32mm]
801 \centering
802 \begin{tikzpicture}
803 \Vertex[IdAsLabel]{A}
804 \Vertex[x=1,label=B,NoLabel]{B}
805 \Vertex[x=2,IdAsLabel,NoLabel]{C}
806 \end{tikzpicture}
807 \end{marginfigure}
808
809 \begin{docspec}
810 \begin{lstlisting}
811 \begin{tikzpicture}
812 \Vertex[IdAsLabel]{A}
813 \Vertex[x=1,label=B,NoLabel]{B}
814 \Vertex[x=2,IdAsLabel,NoLabel]{C}
815 \end{tikzpicture}
816 \end{lstlisting}
817 \end{docspec}
818
819 \begin{docspecdef}
820 \doccmd{Vertex}[\docopt{Math},\docopt{label}=\docarg{string}]\{\docarg{Name}\}
821 \end{docspecdef}
822
823 The option \docopt{Math} allows transforming labels into mathematical expressions without using the \$~\$ environment. In combination with \docopt{IdAsLabel} allows this option also mathematical expressions by the definition of the vertex \docarg{Name}.
824
825 %\newpage
826 \begin{marginfigure}[32mm]
827 \centering
828 \begin{tikzpicture}
829 \Vertex[IdAsLabel]{A1}
830 \Vertex[x=1,label=B_1,Math]{B}
831 \Vertex[x=2,Math,IdAsLabel]{C_1}
832 \end{tikzpicture}
833 \end{marginfigure}
834
835 \begin{docspec}
836 \begin{lstlisting}
837 \begin{tikzpicture}
838 \Vertex[IdAsLabel]{A1}
839 \Vertex[x=1,label=B_1,Math]{B}
840 \Vertex[x=2,Math,IdAsLabel]{C_1}
841 \end{tikzpicture}
842 \end{lstlisting}
843 \end{docspec}
844
845
846 \begin{docspecdef}
847 \doccmd{Vertex}[\docopt{RGB},\docopt{color}=\docarg{RGB values}]\{\docarg{Name}\}
848 \end{docspecdef}
849
850 In order to display RGB colors for the vertex fill color, the option \docopt{RGB} has to be entered. In combination with this option, the \docopt{color} hast to be a list with the \docarg{RGB
851 values}, separated by <<,>> and within $\{~\}$.\footnote{e.g. the RGB code for white: $\{255,255,255\}$}
852
853 \begin{marginfigure}[4mm]
854 \centering
855 \begin{tikzpicture}
856 \Vertex[RGB,color={127,201,127}]{A}
857 \Vertex[x=1,RGB,color={190,174,212}]{B}
858 \Vertex[x=2,RGB,color={253,192,134}]{C}
859 \end{tikzpicture}
860 \end{marginfigure}
861
862 \begin{docspec}
863 \begin{lstlisting}
864 \begin{tikzpicture}
865 \Vertex[RGB,color={127,201,127}]{A}
866 \Vertex[x=1,RGB,color={190,174,212}]{B}
867 \Vertex[x=2,RGB,color={253,192,134}]{C}
868 \end{tikzpicture}
869 \end{lstlisting}
870 \end{docspec}
871
872 \begin{docspecdef}
873 \doccmd{Vertex}[\docopt{Pseudo}]\{\docarg{Name}\}
874 \end{docspecdef}
875
876 The option \docopt{Pseudo} creates a pseudo vertex, where only the vertex name and the vertex coordinate will be drawn. Edges etc, can still be assigned to this vertex.
877
878 \begin{marginfigure}[32mm]
879 \centering
880 \begin{tikzpicture}
881 \Vertex{A}
882 \Vertex[x=2,Pseudo]{B}
883 \end{tikzpicture}
884 \end{marginfigure}
885
886 \begin{docspec}
887 \begin{lstlisting}
888 \begin{tikzpicture}
889 \Vertex{A}
890 \Vertex[x=2,Pseudo]{B}
891 \end{tikzpicture}
892 \end{lstlisting}
893 \end{docspec}
894
895
896
897 \begin{docspecdef}
898 \doccmd{Vertex}[\docopt{layer}=\docarg{number}]\{\docarg{Name}\}
899 \end{docspecdef}
900
901 With the option \docopt{layer} the vertex can be assigned to a specific layer. More about this option and the use of layers is explained in Chapter~\ref{chap:multilayer_networks}.
902
903 \newpage
904
905 \section{Edge}
906 \label{sec:edge}
907
908 The second essential command is an \doccmddef{Edge}, which allow connecting two vertices.
909
910 \begin{docspecdef}
911 \doccmd{Edge}[\docopt{local options}](\docarg{Vertex i})(\docarg{Vertex j})
912 \end{docspecdef}
913
914 Edges can be generated between one or two vertices. In the first case, a self-loop will be generated. As mandatory arguments the \docarg{Names} of the vertices which should be connected must be entered between $(~)$ brackets. In case of a directed edge, the order is important. An edge is created from \docarg{Vertex i} (origin) to \docarg{Vertex j} (destination).
915
916 For an \doccmd{Edge} the following options are available:
917
918 \begin{table}[h]\index{Edge!options}
919 \footnotesize%
920 \begin{center}
921 \begin{tabular}{lccl}
922 \toprule
923 Option & Default & Type &Definition \\
924 \midrule
925 lw & \{\} & measure & line width of the edge \\
926 color & \{\} & color & edge color\\
927 opacity & \{\} & number & opacity of the edge \\
928 bend & 0 & number & angle out/in of the vertex \\
929 label & \{\} & string & label \\
930 fontsize & \{\} & string & font size of the label\\
931 fontcolor & \{\} & color & font color of the label\\
932 fontscale & \{\} & number & scale of the label\\
933 position & \{\} & string & label position\\
934 distance & 0.5 & number & label distance from vertex i\\
935 style & \{\} & string & additional \tikzsym styles \\
936 \midrule
937 path & \{\} & list & path over several vertices\\
938 \midrule
939 loopsize & 1cm & measure & size parameter of the self-loop\\
940 loopposition& 0 & number & orientation of the self-loop \\
941 loopshape & 90 & number & loop angle out/in of the vertex \\
942 \midrule
943 Direct & false & Boolean & allow directed edges \\
944 Math & false & Boolean & displays the label in math mode \\
945 RGB & false & Boolean & allow RGB colors \\
946 NotInBG & false & Boolean & edge is not in the background layer\\
947 \bottomrule
948 \end{tabular}
949 \scriptsize
950 \end{center}
951 \caption{Local options for the \doccmd{Edge} command.}
952 \label{tab:edge_options}
953 \end{table}
954
955 The options \docopt{loopsize}, \docopt{loopposition}, and \docopt{loopsize} are only for self-loops available.
956
957 \begin{docspecdef}
958 \doccmd{Edge}(\docarg{Vertex i})(\docarg{Vertex j})
959 \end{docspecdef}
960
961 An edge is created between \docarg{Vertex i} and \docarg{Vertex j}.
962
963 \begin{marginfigure}[28mm]
964 \centering
965 \begin{tikzpicture}
966 \Vertex{A} \Vertex[x=2]{B}
967 \Edge(A)(B)
968 \end{tikzpicture}
969 \end{marginfigure}
970
971 \begin{docspec}
972 \begin{lstlisting}
973 \begin{tikzpicture}
974 \Vertex{A} \Vertex[x=2]{B}
975 \Edge(A)(B)
976 \end{tikzpicture}
977 \end{lstlisting}
978 \end{docspec}
979
980 \begin{docspecdef}
981 \doccmd{Edge}[\docopt{lw}=\docarg{measure}](\docarg{Vertex i})(\docarg{Vertex j})
982 \end{docspecdef}
983
984 The line width of an edge can be modified with the option \docopt{lw}. Here, the unit of the \docarg{measure} has to be specified. The default value is \SI{1.5}{pt}.
985
986 \newpage
987 \begin{marginfigure}[6mm]
988 \centering
989 \begin{tikzpicture}
990 \Vertex{A} \Vertex[x=2]{B} \Vertex[x=2,y=-1]{C}
991 \Edge[lw=3pt](A)(B)
992 \Edge[lw=5pt](A)(C)
993 \end{tikzpicture}
994 \end{marginfigure}
995
996 \begin{docspec}
997 \begin{lstlisting}
998 \begin{tikzpicture}
999 \Vertex{A} \Vertex[x=2]{B} \Vertex[x=2,y=-1]{C}
1000 \Edge[lw=3pt](A)(B)
1001 \Edge[lw=5pt](A)(C)
1002 \end{tikzpicture}
1003 \end{lstlisting}
1004 \end{docspec}
1005
1006 %\newpage
1007
1008 \begin{docspecdef}
1009 \doccmd{Edge}[\docopt{color}=\docarg{color}](\docarg{Vertex i})(\docarg{Vertex j})
1010 \end{docspecdef}
1011
1012 To change the line color of each edge individually, the option \docopt{color} has to be used. Without the option \docopt{RGB} set, the default \tikzsym and \LaTeX~ colors can be applied.
1013
1014 \begin{marginfigure}[30mm]
1015 \centering
1016 \begin{tikzpicture}
1017 \Vertex{A} \Vertex[x=2]{B} \Vertex[x=2,y=-1]{C}
1018 \Edge[color=red](A)(B)
1019 \Edge[color=green!70!blue](A)(C)
1020 \end{tikzpicture}
1021 \end{marginfigure}
1022
1023 \begin{docspec}
1024 \begin{lstlisting}
1025 \begin{tikzpicture}
1026 \Vertex{A} \Vertex[x=2]{B} \Vertex[x=2,y=-1]{C}
1027 \Edge[color=red](A)(B)
1028 \Edge[color=green!70!blue](A)(C)
1029 \end{tikzpicture}
1030 \end{lstlisting}
1031 \end{docspec}
1032
1033 \begin{docspecdef}
1034 \doccmd{Edge}[\docopt{opacity}=\docarg{number}](\docarg{Vertex i})(\docarg{Vertex j})
1035 \end{docspecdef}
1036
1037 With the option \docopt{opacity} the opacity of the edge line can be modified. The range of the \docarg{number} lies between $0$ and $1$. Where $0$ represents a fully transparent fill and $1$ a solid fill.
1038
1039 \begin{marginfigure}[30mm]
1040 \centering
1041 \begin{tikzpicture}
1042 \Vertex{A} \Vertex[x=2]{B} \Vertex[x=2,y=-1]{C}
1043 \fill [orange] (.9,.2) rectangle (1.1,-.7);
1044 \EdgesNotInBG
1045 \Edge[opacity=.7](A)(B)
1046 \Edge[opacity=.2](A)(C)
1047 \end{tikzpicture}
1048 \end{marginfigure}
1049
1050 \begin{docspec}
1051 \begin{lstlisting}
1052 \begin{tikzpicture}
1053 \Vertex{A} \Vertex[x=2]{B} \Vertex[x=2,y=-1]{C}
1054 \Edge[opacity=.7](A)(B)
1055 \Edge[opacity=.2](A)(C)
1056 \end{tikzpicture}
1057 \end{lstlisting}
1058 \end{docspec}
1059
1060 \begin{docspecdef}
1061 \doccmd{Edge}[\docopt{bend}=\docarg{number}](\docarg{Vertex i})(\docarg{Vertex j})
1062 \end{docspecdef}
1063
1064 The shape of the edge can be modified with the \docopt{bend} option. If nothing is specified a straight edge, between the vertices, is drawn. The \docarg{number} defines the angle in which the edge is diverging from its straight connection. A positive \docarg{number} bend the edge counter clockwise, while a negative \docarg{number} make changes clockwise.
1065
1066 \begin{marginfigure}[32mm]
1067 \centering
1068 \begin{tikzpicture}
1069 \Vertex{A}
1070 \Vertex[x=2]{B}
1071 \Edge[bend=45](A)(B)
1072 \Edge[bend=-70](A)(B)
1073 \draw[orange,dashed](0,0) -- (20mm,0mm)(0,0)--(45:10mm);
1074 \draw[orange,->] (.5,0) arc (0:45:5mm);
1075 \draw[orange,dashed](0,0)--(-70:10mm);
1076 \draw[orange,->] (.5,0) arc (0:-70:5mm);
1077 \node[orange] (x) at (1,.25) {$45^\circ$};
1078 \node[orange] (x) at (1,-.35) {$70^\circ$};
1079 \draw[orange,dashed] (2,0)--++(135:10mm);
1080 \draw[orange,->] (1.5,0) arc (180:135:5mm);
1081 \draw[orange,dashed] (2,0)--++(-110:10mm);
1082 \draw[orange,->] (1.5,0) arc (-180:-110:5mm);
1083 \end{tikzpicture}
1084 \end{marginfigure}
1085
1086 \begin{docspec}
1087 \begin{lstlisting}
1088 \begin{tikzpicture}
1089 \Vertex{A} \Vertex[x=2]{B}
1090 \Edge[bend=45](A)(B)
1091 \Edge[bend=-70](A)(B)
1092 \end{tikzpicture}
1093 \end{lstlisting}
1094 \end{docspec}
1095
1096 \begin{docspecdef}
1097 \doccmd{Edge}[\docopt{label}=\docarg{string}](\docarg{Vertex i})(\docarg{Vertex j})
1098 \end{docspecdef}
1099
1100 An edge is labeled with the option \docopt{label}. For the label any \docarg{string} argument can be used, including blank spaces. The environment \$ \$ can be used to display mathematical expressions.
1101
1102 \begin{marginfigure}[30mm]
1103 \centering
1104 \begin{tikzpicture}
1105 \Vertex{A} \Vertex[x=2]{B}
1106 \Edge[label=X](A)(B)
1107 \end{tikzpicture}
1108 \end{marginfigure}
1109
1110 \begin{docspec}
1111 \begin{lstlisting}
1112 \begin{tikzpicture}
1113 \Vertex{A} \Vertex[x=2]{B}
1114 \Edge[label=X](A)(B)
1115 \end{tikzpicture}
1116 \end{lstlisting}
1117 \end{docspec}
1118
1119 \begin{docspecdef}
1120 \doccmd{Edge}[\docopt{label}=\docarg{string},\docopt{fontsize}=\docarg{string}](\docarg{Vertex i})(\docarg{Vertex j})
1121 \end{docspecdef}
1122
1123 The font size of the \docopt{label} can be modified with the option \docopt{fontsize}. Here common \LaTeX~ font size commands\footnote{e.g. \doccmd{tiny}, \doccmd{scriptsize}, \doccmd{footnotesize}, \doccmd{small}, \dots.} can be used to change the size of the label.
1124
1125 \begin{marginfigure}[25mm]
1126 \centering
1127 \begin{tikzpicture}
1128 \Vertex{A} \Vertex[x=2]{B} \Vertex[x=2,y=-1]{C}
1129 \Edge[label=X,fontsize=\large](A)(B)
1130 \Edge[label=Y,fontsize=\tiny](A)(C)
1131 \end{tikzpicture}
1132 \end{marginfigure}
1133
1134 \begin{docspec}
1135 \begin{lstlisting}
1136 \begin{tikzpicture}
1137 \Vertex{A} \Vertex[x=2]{B} \Vertex[x=2,y=-1]{C}
1138 \Edge[label=X,fontsize=\large](A)(B)
1139 \Edge[label=Y,fontsize=\tiny](A)(C)
1140 \end{tikzpicture}
1141 \end{lstlisting}
1142 \end{docspec}
1143
1144 \begin{docspecdef}
1145 \doccmd{Edge}[\docopt{label}=\docarg{string},\docopt{fontcolor}=\docarg{color}](\docarg{Vertex i})(\docarg{Vertex j})
1146 \end{docspecdef}
1147
1148 The color of the \docopt{label} can be changed with the option \docopt{fontcolor}. Currently, only the default \tikzsym and \LaTeX~ colors are supported \footnote{\TODO Add RGB option!}.
1149
1150 \begin{marginfigure}[1mm]
1151 \centering
1152 \begin{tikzpicture}
1153 \Vertex{A} \Vertex[x=2]{B} \Vertex[x=2,y=-1]{C}
1154 \Edge[label=X,fontcolor=blue](A)(B)
1155 \Edge[label=Y,fontcolor=red](A)(C)
1156 \end{tikzpicture}
1157 \end{marginfigure}
1158
1159 \begin{docspec}
1160 \begin{lstlisting}
1161 \begin{tikzpicture}
1162 \Vertex{A} \Vertex[x=2]{B} \Vertex[x=2,y=-1]{C}
1163 \Edge[label=X,fontcolor=blue](A)(B)
1164 \Edge[label=Y,fontcolor=red](A)(C)
1165 \end{tikzpicture}
1166 \end{lstlisting}
1167 \end{docspec}
1168
1169
1170 \begin{docspecdef}
1171 \doccmd{Edge}[\docopt{label}=\docarg{string},\docopt{fontscale}=\docarg{color}](\docarg{Vertex i})(\docarg{Vertex j})
1172 \end{docspecdef}
1173
1174 Contrary to the option \docopt{fontsize}, the option \docopt{fontscale} does not change the font size itself but scales the curent font size up or down. The \docarg{number} defines the scale, where numbers between $0$ and $1$ down scale the font and numbers greater then $1$ up scale the label. For example $0.5$ reduces the size of the font to $50\%$ of its originial size, while $1.2$ scales the font to $120\%$.
1175
1176 \begin{marginfigure}[30mm]
1177 \centering
1178 \begin{tikzpicture}
1179 \Vertex{A} \Vertex[x=2]{B} \Vertex[x=2,y=-1]{C}
1180 \Edge[label=X,fontscale=.5](A)(B)
1181 \Edge[label=Y,fontscale=1.2](A)(C)
1182 \end{tikzpicture}
1183 \end{marginfigure}
1184
1185 \begin{docspec}
1186 \begin{lstlisting}
1187 \begin{tikzpicture}
1188 \Vertex{A} \Vertex[x=2]{B} \Vertex[x=2,y=-1]{C}
1189 \Edge[label=X,fontscale=.5](A)(B)
1190 \Edge[label=Y,fontscale=2](A)(C)
1191 \end{tikzpicture}
1192 \end{lstlisting}
1193 \end{docspec}
1194
1195 \begin{docspecdef}
1196 \doccmd{Edge}[\docopt{label}=\docarg{string},\docopt{position}=\docarg{string}](\docarg{Vertex i})(\docarg{Vertex j})
1197 \end{docspecdef}
1198
1199 Per default the \docopt{label} is positioned in between both vertices in the center of the line. Classical \tikzsym commands\footnote{e.g. \docarg{above}, \docarg{below}, \docarg{left}, \docarg{right}, \docarg{above left}, \docarg{above right},\dots} can be used to change the \docopt{position} of the \docopt{label}.
1200 %\newpage
1201
1202 \begin{marginfigure}[6mm]
1203 \centering
1204 \begin{tikzpicture}
1205 \Vertex{A} \Vertex[x=2]{B} \Vertex[x=2,y=-1]{C}
1206 \Edge[label=X,position=above](A)(B)
1207 \Edge[label=Y,position={below left=2mm}](A)(C)
1208 \end{tikzpicture}
1209 \end{marginfigure}
1210
1211 \begin{docspec}
1212 \begin{lstlisting}
1213 \begin{tikzpicture}
1214 \Vertex{A} \Vertex[x=2]{B} \Vertex[x=2,y=-1]{C}
1215 \Edge[label=X,position=above](A)(B)
1216 \Edge[label=Y,position={below left=2mm}](A)(C)
1217 \end{tikzpicture}
1218 \end{lstlisting}
1219 \end{docspec}
1220
1221 \begin{docspecdef}
1222 \doccmd{Edge}[\docopt{label}=\docarg{string},\docopt{distance}=\docarg{number}](\docarg{Vertex i})(\docarg{Vertex j})
1223 \end{docspecdef}
1224
1225 The label position between the vertices can be modified with the \docopt{distance} option. Per default the \docopt{label} is centered between both vertices. The position is expressed as the percentage of the length between the vertices, e.g. of \docopt{distance}=$0.7$, the label is placed at 70\% of the edge length away of \docarg{Vertex i}.
1226
1227 \newpage
1228 \begin{marginfigure}[6mm]
1229 \centering
1230 \begin{tikzpicture}
1231 \Vertex{A} \Vertex[x=2]{B}
1232 \Edge[label=X,distance=.7](A)(B)
1233 \draw[orange,|->|] (.3,-.5) --++ (0.98,0) node[pos=.5,above]{$0.7$};
1234 \draw[orange,|<->|] (.3,.5) --++ (1.4,0) node[pos=.5,below]{$1.0$};
1235 \end{tikzpicture}
1236 \end{marginfigure}
1237
1238 \begin{docspec}
1239 \begin{lstlisting}
1240 \begin{tikzpicture}
1241 \Vertex{A} \Vertex[x=2]{B}
1242 \Edge[label=X,distance=.7](A)(B)
1243 \end{tikzpicture}
1244 \end{lstlisting}
1245 \end{docspec}
1246
1247 \begin{docspecdef}
1248 \doccmd{Edge}[\docopt{style}=\docarg{string}](\docarg{Vertex i})(\docarg{Vertex j})
1249 \end{docspecdef}
1250
1251 Any other \tikzsym style option or command can be entered via the option \docopt{style}. Most of these commands can be found in the ``\tikzsym and PGF Manual''. Contain the commands additional options (e.g.\docopt{shading}=\docarg{ball}), then the argument for the \docopt{style} has to be between $\{~\}$ brackets.
1252
1253 \begin{marginfigure}[30mm]
1254 \centering
1255 \begin{tikzpicture}
1256 \Vertex{A} \Vertex[x=2]{B}
1257 \Edge[style={dashed}](A)(B)
1258 \end{tikzpicture}
1259 \end{marginfigure}
1260
1261 \begin{docspec}
1262 \begin{lstlisting}
1263 \begin{tikzpicture}
1264 \Vertex{A} \Vertex[x=2]{B}
1265 \Edge[style={dashed}](A)(B)
1266 \end{tikzpicture}
1267 \end{lstlisting}
1268 \end{docspec}
1269
1270
1271 \begin{docspecdef}
1272 \doccmd{Edge}[\docopt{path}=\docarg{list}](\docarg{Vertex i})(\docarg{Vertex j})
1273 \end{docspecdef}
1274
1275 In order to draw a finite sequence of edges which connect a sequence of vertices and/or coordinates, the option \docopt{path} can be used\footnote{\TODO currently labels and bend edges are not supported!}. The argument for this option has to be a list element indicated by $\{~\}$ brackets, containing the \docarg{Names} of the intermediated vertices. New coordinates, i.e. there is no vertex located, can be insert with $\{\docopt{x},\docopt{y}\}$. Arguments of the list, have to be seperated by commas <<,>>.
1276
1277
1278 \begin{marginfigure}[18mm]
1279 \centering
1280 \begin{tikzpicture}
1281 \Vertex{A} \Vertex[x=2]{B} \Vertex[x=2,y=-1]{C}
1282 \Edge[path={A,{0,-1},C,B}](A)(B)
1283 \end{tikzpicture}
1284 \end{marginfigure}
1285
1286 \begin{docspec}
1287 \begin{lstlisting}
1288 \begin{tikzpicture}
1289 \Vertex{A} \Vertex[x=2]{B} \Vertex[x=2,y=-1]{C}
1290 \Edge[path={A,{0,-1},C,B}](A)(B)
1291 \end{tikzpicture}
1292 \end{lstlisting}
1293 \end{docspec}
1294
1295 %\newpage
1296
1297 \begin{docspecdef}
1298 \doccmd{Edge}(\docarg{Vertex i})(\docarg{Vertex i})
1299 \end{docspecdef}
1300
1301 Self-loops are created by using the same vertex as origin and destination. Beside the options explained above, there are three self-loop specific options: \docopt{loopsize}, \docopt{loopposition}, and \docopt{loopshape}.
1302
1303 \begin{marginfigure}[28mm]
1304 \centering
1305 \begin{tikzpicture}
1306 \Vertex{A}
1307 \Edge(A)(A)
1308 \end{tikzpicture}
1309 \end{marginfigure}
1310
1311 \begin{docspec}
1312 \begin{lstlisting}
1313 \begin{tikzpicture}
1314 \Vertex{A}
1315 \Edge(A)(A)
1316 \end{tikzpicture}
1317 \end{lstlisting}
1318 \end{docspec}
1319
1320 \begin{docspecdef}
1321 \doccmd{Edge}[\docopt{loopsize}=\docarg{measure}](\docarg{Vertex i})(\docarg{Vertex i})
1322 \end{docspecdef}
1323
1324 With the option \docopt{loopsize} the length of the edge can be modified. The \docarg{measure} value has to be insert together with its units. Per default the \docopt{loopsize} is \SI{1}{cm}.
1325
1326 \newpage
1327 \begin{marginfigure}[2mm]
1328 \centering
1329 \begin{tikzpicture}
1330 \Vertex{A} \Vertex[x=1.3]{B}
1331 \Edge[loopsize=.5cm](A)(A)
1332 \Edge[loopsize=1.5cm](B)(B)
1333 \end{tikzpicture}
1334 \end{marginfigure}
1335
1336 \begin{docspec}
1337 \begin{lstlisting}
1338 \begin{tikzpicture}
1339 \Vertex{A} \Vertex[x=1.3]{B}
1340 \Edge[loopsize=.5cm](A)(A)
1341 \Edge[loopsize=1.5cm](B)(B)
1342 \end{tikzpicture}
1343 \end{lstlisting}
1344 \end{docspec}
1345
1346 \begin{docspecdef}
1347 \doccmd{Edge}[\docopt{loopposition}=\docarg{number}](\docarg{Vertex i})(\docarg{Vertex i})
1348 \end{docspecdef}
1349
1350 The position of the self-loop is defined via the rotation angle around the vertex. The origin ($0^\circ$) is the $y$ axis. A positive \docarg{number} change the \docopt{loopposition} counter clockwise, while a negative \docarg{number} make changes clockwise.
1351
1352 \begin{marginfigure}[28mm]
1353 \centering
1354 \begin{tikzpicture}
1355 \Vertex{A}
1356 \Vertex[x=1.5]{B}
1357 \Edge[loopposition=45](A)(A)
1358 \Edge[loopposition=-70](B)(B)
1359 \draw[orange,dashed](0,0) -- (10mm,0mm)(0,0)--(45:10mm);
1360 \draw[orange,->] (.5,0) arc (0:45:5mm);
1361 \node[orange] (x) at (1,.35) {$45^\circ$};
1362 \draw[orange,dashed](1.5,0)--++(-70:10mm);
1363 \draw[orange,dashed](1.5,0)--++(10mm,0);
1364 \draw[orange,->] (1.9,0) arc (0:-70:5mm);
1365 \node[orange] (x) at (2.3,-.45) {$70^\circ$};
1366 \end{tikzpicture}
1367 \end{marginfigure}
1368
1369 \begin{docspec}
1370 \begin{lstlisting}
1371 \begin{tikzpicture}
1372 \Vertex{A} \Vertex[x=1.5]{B}
1373 \Edge[loopposition=45](A)(A)
1374 \Edge[loopposition=-70](B)(B)
1375 \end{tikzpicture}
1376 \end{lstlisting}
1377 \end{docspec}
1378
1379 \begin{docspecdef}
1380 \doccmd{Edge}[\docopt{loopshape}=\docarg{number}](\docarg{Vertex i})(\docarg{Vertex i})
1381 \end{docspecdef}
1382
1383 The shape of the self-loop is defined by the enclosing angle. The shape can be changed by decreasing or increasing the argument value of the \docopt{loopshape} option.
1384
1385 \begin{marginfigure}[28mm]
1386 \centering
1387 \begin{tikzpicture}
1388 \Vertex{A}
1389 \Edge[loopshape=45](A)(A)
1390 \draw[orange,dashed](0,0) -- (-22.5:13mm)(0,0)--(22.5:13mm);
1391 \draw[orange,->] (1.2,0) arc (0:22.5:12mm);
1392 \draw[orange,->] (1.2,0) arc (0:-22.5:12mm);
1393 \node[orange] (x) at (1.5,0) {$45^\circ$};
1394 \end{tikzpicture}
1395 \end{marginfigure}
1396
1397 \begin{docspec}
1398 \begin{lstlisting}
1399 \begin{tikzpicture}
1400 \Vertex{A}
1401 \Edge[loopshape=45](A)(A)
1402 \end{tikzpicture}
1403 \end{lstlisting}
1404 \end{docspec}
1405
1406 %\newpage
1407
1408 \begin{docspecdef}
1409 \doccmd{Edge}[\docopt{Direct}](\docarg{Vertex i})(\docarg{Vertex j})
1410 \end{docspecdef}
1411
1412 Directed edges are created by enabling the option \docopt{Direct}. The arrow is drawn from \docarg{Vertex i} to \docarg{Vertex j}.
1413
1414 \begin{marginfigure}[28mm]
1415 \centering
1416 \begin{tikzpicture}
1417 \Vertex{A} \Vertex[x=2]{B}
1418 \Edge[Direct](A)(B)
1419 \end{tikzpicture}
1420 \end{marginfigure}
1421
1422 \begin{docspec}
1423 \begin{lstlisting}
1424 \begin{tikzpicture}
1425 \Vertex{A} \Vertex[x=2]{B}
1426 \Edge[Direct](A)(B)
1427 \end{tikzpicture}
1428 \end{lstlisting}
1429 \end{docspec}
1430
1431
1432 \begin{docspecdef}
1433 \doccmd{Edge}[Math, label=\docopt{string}](\docarg{Vertex i})(\docarg{Vertex j})
1434 \end{docspecdef}
1435
1436 The option \docopt{Math} allows transforming labels into mathematical expressions without using the \$~\$ environment.
1437
1438 \begin{marginfigure}[28mm]
1439 \centering
1440 \begin{tikzpicture}
1441 \Vertex{A} \Vertex[x=2]{B}
1442 \Edge[Math,label=X_1](A)(B)
1443 \end{tikzpicture}
1444 \end{marginfigure}
1445
1446 \begin{docspec}
1447 \begin{lstlisting}
1448 \begin{tikzpicture}
1449 \Vertex{A} \Vertex[x=2]{B}
1450 \Edge[Math,label=X_1](A)(B)
1451 \end{tikzpicture}
1452 \end{lstlisting}
1453 \end{docspec}
1454
1455 \begin{docspecdef}
1456 \doccmd{Edge}[RBG, color=\docopt{RGB value}](\docarg{Vertex i})(\docarg{Vertex j})
1457 \end{docspecdef}
1458
1459 In order to display RGB colors for the line color of the edge, the option \docopt{RGB} has to be entered. In combination with this option, the \docopt{color} hast to be a list with the \docarg{RGB
1460 values}, separated by <<,>> and within $\{~\}$.\footnote{e.g. the RGB code for white: $\{255,255,255\}$}
1461
1462 \newpage
1463
1464 \begin{marginfigure}[10mm]
1465 \centering
1466 \begin{tikzpicture}
1467 \Vertex{A} \Vertex[x=2]{B} \Vertex[x=2,y=-1]{C}
1468 \Edge[RGB,color={127,201,127}](A)(B)
1469 \Edge[RGB,color={253,192,134}](A)(C)
1470 \end{tikzpicture}
1471 \end{marginfigure}
1472
1473 \begin{docspec}
1474 \begin{lstlisting}
1475 \begin{tikzpicture}
1476 \Vertex{A} \Vertex[x=2]{B} \Vertex[x=2,y=-1]{C}
1477 \Edge[RGB,color={127,201,127}](A)(B)
1478 \Edge[RGB,color={253,192,134}](A)(C)
1479 \end{tikzpicture}
1480 \end{lstlisting}
1481 \end{docspec}
1482
1483 \begin{docspecdef}
1484 \doccmd{Edge}[\docopt{NotInBG}]\{\docarg{filename}\}
1485 \end{docspecdef}
1486
1487 Per default, the edge is drawn on the background layer of the \docarg{tikzpicture}. I.e. objects which are created after the edges appear also on top of them. To turn this off, the option \docopt{NotInBG} has to be enabled. Changes to the default setting can be made with \doccmd{EdgesNotInBG} or \doccmd{EdgesInBG}\footnote{See Section \ref{sec:edge_style}}.
1488
1489 \begin{marginfigure}[6mm]
1490 \centering
1491 \begin{tikzpicture}
1492 \Vertex{A} \Vertex[x=2]{B} \Vertex[x=1,y=-.5]{C}
1493 \Vertex[y=-1]{D} \Vertex[x=2,y=-1]{E}
1494 \Edge[bend=-30](A)(B)
1495 \Edge[bend=30,NotInBG](D)(E)
1496 \end{tikzpicture}
1497 \end{marginfigure}
1498
1499 \begin{docspec}
1500 \begin{lstlisting}
1501 \begin{tikzpicture}
1502 \Vertex{A} \Vertex[x=2]{B} \Vertex[x=1,y=-.5]{C}
1503 \Vertex[y=-1]{D} \Vertex[x=2,y=-1]{E}
1504 \Edge[bend=-30](A)(B)
1505 \Edge[bend=30,NotInBG](D)(E)
1506 \end{tikzpicture}
1507 \end{lstlisting}
1508 \end{docspec}
1509
1510 \newpage
1511 \section{Text}
1512 \label{sec:text}
1513
1514 While \tikzsym offers multiple ways to label objects and create text elements, a simplified command \doccmddef{Text} is implemented, which allow placing and modifying text to the networks.
1515 \begin{docspecdef}
1516 \doccmd{Text}[\docopt{local options}]\{\docarg{string}\}
1517 \end{docspecdef}
1518 In order to be able to create a text, a non-empty \docarg{string} argument is required. This argument is the actual text added to the figure. Mathematical symbols are entered in the same way as in a normal \LaTeX~document, i.e. between \$~\$.
1519
1520 For a \doccmd{Text} the following options are available:
1521
1522 \begin{table}[h]\index{Text!options}
1523 \footnotesize%
1524 \begin{center}
1525 \begin{tabular}{lccl}
1526 \toprule
1527 Option & Default & Type &Definition \\
1528 \midrule
1529 x & 0 & measure & x-coordinate \\
1530 y & 0 & measure & y-coordinate \\
1531 fontsize & \{\} & fontsize & font size of the text\\
1532 color & \{\} & color & color of the text\\
1533 opacity & \{\} & number & opacity of the text \\
1534 position & center& string & position of the text to the origin\\
1535 distance & \SI{0}{cm} & measure & distance from the origin \\
1536 rotation & 0 & number & rotation of the text \\
1537 anchor & \{\} & string & anchor of the text \\
1538 width & \{\} & number & width of the text box \\
1539 style & \{\} & string & additional \tikzsym styles \\
1540 layer & \{\} & number & assigned layer of the text \\
1541 \midrule
1542 RGB & false & Boolean & allow RGB colors \\
1543 \bottomrule
1544 \end{tabular}
1545 \scriptsize
1546 \end{center}
1547 \caption{Local options for the \doccmd{Text} command.}
1548 \label{tab:text_options}
1549 \end{table}
1550
1551 The order how the options are entered does not matter. Changes to the default Text layout can be made with \doccmd{SetTextStyle}\footnote{see Section \ref{sec:text_style}}
1552
1553 \begin{docspecdef}
1554 \doccmd{Text}[\docopt{x}=\docarg{measure},\docopt{y}=\docarg{measure}]\{\docarg{string}\}
1555 \end{docspecdef}
1556
1557 The location of the text is determined by Cartesian coordinates in \docopt{x} and \docopt{y}. The coordinates are optional. If no coordinates are determined the text will be placed at the origin ($0,0$). The entered \docarg{measures} are in default units (\si{cm}). Changing the unites (locally) can be done by adding the unit to the \docarg{measure}\footnote{e.g. x=\SI{1}{in}}. Changes to the default setting can be made with \doccmd{SetDefaultUnit}\footnote{see Section \ref{sec:gerneral_settings}}.
1558
1559 \begin{marginfigure}[6mm]
1560 \centering
1561 \begin{tikzpicture}
1562 \Text{A}
1563 \Text[x=1,y=1]{B}
1564 \Text[x=2]{C}
1565 \end{tikzpicture}
1566 \end{marginfigure}
1567
1568 \begin{docspec}
1569 \begin{lstlisting}
1570 \begin{tikzpicture}
1571 \Text{A}
1572 \Text[x=1,y=1]{B}
1573 \Text[x=2]{C}
1574 \end{tikzpicture}
1575 \end{lstlisting}
1576 \end{docspec}
1577
1578
1579 \begin{docspecdef}
1580 \doccmd{Text}[\docopt{fontsize}=\docarg{font size}]\{\docarg{string}\}
1581 \end{docspecdef}
1582
1583 The font size of the text can be changed with the option \docopt{fontsize}. Per default the font size of the text is defined as \doccmd{normalsize}.
1584
1585 \begin{marginfigure}[34mm]
1586 \centering
1587 \begin{tikzpicture}
1588 \Text[fontsize=\small]{A}
1589 \Text[x=1,fontsize=\LARGE]{B}
1590 \Text[x=2,fontsize=\Huge]{C}
1591 \end{tikzpicture}
1592 \end{marginfigure}
1593
1594 \begin{docspec}
1595 \begin{lstlisting}
1596 \begin{tikzpicture}
1597 \Text[fontsize=\small]{A}
1598 \Text[x=1,fontsize=\LARGE]{B}
1599 \Text[x=2,fontsize=\Huge]{C}
1600 \end{tikzpicture}
1601 \end{lstlisting}
1602 \end{docspec}
1603
1604 \begin{docspecdef}
1605 \doccmd{Text}[\docopt{color}=\docarg{color}]\{\docarg{string}\}
1606 \end{docspecdef}
1607
1608 To change the text color individually, the option \docopt{color} has to be used. Without the option \docopt{RGB} set, the default \tikzsym and \LaTeX~ colors can be applied.
1609
1610 \begin{marginfigure}[34mm]
1611 \centering
1612 \begin{tikzpicture}
1613 \Text[color = blue]{A}
1614 \Text[x=1,color=red]{B}
1615 \Text[x=2,color=green!70!blue]{C}
1616 \end{tikzpicture}
1617 \end{marginfigure}
1618
1619 \begin{docspec}
1620 \begin{lstlisting}
1621 \begin{tikzpicture}
1622 \Text[color = blue]{A}
1623 \Text[x=1,color=red]{B}
1624 \Text[x=2,color=green!70!blue]{C}
1625 \end{tikzpicture}
1626 \end{lstlisting}
1627 \end{docspec}
1628
1629
1630 \begin{docspecdef}
1631 \doccmd{Text}[\docopt{opacity}=\docarg{number}]\{\docarg{string}\}
1632 \end{docspecdef}
1633
1634 With the option \docopt{opacity} the opacity of the text can be modified. The range of the \docarg{number} lies between $0$ and $1$. Where $0$ represents a fully transparent text and $1$ a solid text.
1635
1636 \begin{marginfigure}[34mm]
1637 \centering
1638 \begin{tikzpicture}
1639 \draw[thick,orange,dashed] (-.5,0) -- (2.5,0);
1640 \Text[opacity = 1]{A}
1641 \Text[x=1,opacity =.7]{B}
1642 \Text[x=2,opacity =.2]{C}
1643 \end{tikzpicture}
1644 \end{marginfigure}
1645
1646 \begin{docspec}
1647 \begin{lstlisting}
1648 \begin{tikzpicture}
1649 \Text[opacity = 1]{A}
1650 \Text[x=1,opacity =.7]{B}
1651 \Text[x=2,opacity =.2]{C}
1652 \end{tikzpicture}
1653 \end{lstlisting}
1654 \end{docspec}
1655
1656
1657
1658 \begin{docspecdef}
1659 \doccmd{Text}[\docopt{position}=\docarg{string},\docopt{distance}=\docarg{measure}]\{\docarg{string}\}
1660 \end{docspecdef}
1661
1662 Per default the \docopt{position} of the text is in the \docarg{center} of the origin. Classical \tikzsym commands\footnote{e.g. \docarg{above}, \docarg{below}, \docarg{left}, \docarg{right}, \docarg{above left}, \docarg{above right},\dots} can be used to change the \docopt{position} of the text.
1663
1664 With the option, \docopt{distance} the distance between the text and the origin can be changed.
1665
1666 \begin{marginfigure}[20mm]
1667 \centering
1668 \begin{tikzpicture}
1669 \filldraw [orange] (0,0) circle (2pt);
1670 \draw[<-,orange] (0.1,0) --++ (0.5,0) node [pos=1,right]{origin ($0,0$)};
1671 \Text[position=above]{above}
1672 \Text[position=below]{below}
1673 \Text[position=left,distance=5mm]{left}
1674 \Text[position=above right,distance=5mm]{above right}
1675 \end{tikzpicture}
1676 \end{marginfigure}
1677
1678 \begin{docspec}
1679 \begin{lstlisting}
1680 \begin{tikzpicture}
1681 \Text[position=above]{above}
1682 \Text[position=below]{below}
1683 \Text[position=left,distance=5mm]{left}
1684 \Text[position=above right,distance=5mm]{above right}
1685 \end{tikzpicture}
1686 \end{lstlisting}
1687 \end{docspec}
1688
1689
1690 \begin{docspecdef}
1691 \doccmd{Text}[\docopt{rotation}=\docarg{number}]\{\docarg{string}\}
1692 \end{docspecdef}
1693
1694 With the \docopt{rotation}, the text can be rotated by entering a \docarg{number} between $-360$ and $360$. The origin ($0^\circ$) is the $y$ axis. A positive \docarg{number} change the \docopt{position} counter clockwise, while a negative \docarg{number} make changes clockwise.
1695
1696 \begin{marginfigure}[31mm]
1697 \centering
1698 \begin{tikzpicture}
1699 \Text[rotation = 30]{A}
1700 \Text[x=1,rotation = 45]{B}
1701 \Text[x=2,rotation = 75]{C}
1702 \draw[orange,dashed](2,0) --++ (7mm,0mm)(2,0)--++(75:7mm);
1703 \draw[orange,->] (2.5,0) arc (0:75:5mm);
1704 \node[orange] (x) at (2.6,-.2) {$75^\circ$};
1705 \end{tikzpicture}
1706 \end{marginfigure}
1707
1708 \begin{docspec}
1709 \begin{lstlisting}
1710 \begin{tikzpicture}
1711 \Text[rotation=30]{A}
1712 \Text[x=1,rotation=45]{B}
1713 \Text[x=2,rotation=75]{C}
1714 \end{tikzpicture}
1715 \end{lstlisting}
1716 \end{docspec}
1717 \newpage
1718
1719 \begin{docspecdef}
1720 \doccmd{Text}[\docopt{anchor}=\docarg{string}]\{\docarg{string}\}
1721 \end{docspecdef}
1722
1723 With the option \docopt{anchor} the alignment of the text can be changed. Per default the text will be aligned centered. Classical \tikzsym commands\footnote{e.g. \docarg{north}, \docarg{east}, \docarg{south}, \docarg{west}, \docarg{north east}, \docarg{north west},\dots} can be used to change the alignment of the text.
1724
1725 \begin{marginfigure}[5mm]
1726 \centering
1727 \begin{tikzpicture}
1728 \filldraw [orange] (0,0) circle (2pt);
1729 \filldraw [orange] (1,0) circle (2pt);
1730 \filldraw [orange] (2,0) circle (2pt);
1731 \Text[anchor=north east]{NE}
1732 \Text[x=1,anchor = south]{S}
1733 \Text[x=2,anchor =south west]{SW}
1734 \end{tikzpicture}
1735 \end{marginfigure}
1736
1737 \begin{docspec}
1738 \begin{lstlisting}
1739 \begin{tikzpicture}
1740 \Text[anchor=north east]{NE}
1741 \Text[x=1,anchor = south]{S}
1742 \Text[x=2,anchor =south west]{SW}
1743 \end{tikzpicture}
1744 \end{lstlisting}
1745 \end{docspec}
1746
1747
1748 \begin{docspecdef}
1749 \doccmd{Text}[\docopt{width}=\docarg{measure}]\{\docarg{string}\}
1750 \end{docspecdef}
1751
1752 With the option \docopt{width} enabled, the text will break after the entered \docarg{measure}.
1753
1754 \begin{marginfigure}[25mm]
1755 \centering
1756 \begin{tikzpicture}
1757 \draw[|<->|,orange] (-1.25,.7) --++ (2.5,0) node [pos=.5,above]{2.5cm};
1758 \Text[width=2.5cm]{This might be a very long text.}
1759 \end{tikzpicture}
1760 \end{marginfigure}
1761
1762 \begin{docspec}
1763 \begin{lstlisting}
1764 \begin{tikzpicture}
1765 \Text[width=2.5cm]{This might be a very long text.}
1766 \end{tikzpicture}
1767 \end{lstlisting}
1768 \end{docspec}
1769
1770 \begin{docspecdef}
1771 \doccmd{Text}[\docopt{style}=\{\docarg{string}\}]\{\docarg{string}\}
1772 \end{docspecdef}
1773
1774 Any other \tikzsym style option or command can be entered via the option \docopt{style}. Most of these commands can be found in the ``\tikzsym and PGF Manual''. Contain the commands additional options (e.g.\docopt{fill}=\docarg{red}), then the argument for the \docopt{style} has to be between $\{~\}$ brackets.
1775
1776 \begin{marginfigure}[32mm]
1777 \centering
1778 \begin{tikzpicture}
1779 \Text[style={draw,rectangle}]{A}
1780 \Text[x=1,style={fill=red}]{B}
1781 \Text[x=2,style={fill=blue,circle,opacity=.3}]{C}
1782 \end{tikzpicture}
1783 \end{marginfigure}
1784
1785 \begin{docspec}
1786 \begin{lstlisting}
1787 \begin{tikzpicture}
1788 \Text[style={draw,rectangle}]{A}
1789 \Text[x=1,style={fill=red}]{B}
1790 \Text[x=2,style={fill=blue,circle,opacity=.3}]{C}
1791 \end{tikzpicture}
1792 \end{lstlisting}
1793 \end{docspec}
1794
1795 \begin{docspecdef}
1796 \doccmd{Text}[\docopt{RGB},\docopt{color}=\docarg{RGB values}]\{\docarg{string}\}
1797 \end{docspecdef}
1798
1799 In order to display RGB colors for the text color, the option \docopt{RGB} has to be entered. In combination with this option, the \docopt{color} hast to be a list with the \docarg{RGB values}, separated by <<,>> and within $\{~\}$.\footnote{e.g. the RGB code for white: $\{255,255,255\}$}
1800
1801 \begin{marginfigure}[7mm]
1802 \centering
1803 \begin{tikzpicture}
1804 \Text[RGB,color={127,201,127}]{A}
1805 \Text[x=1,RGB,color={190,174,212}]{B}
1806 \Text[x=2,RGB,color={253,192,134}]{C}
1807 \end{tikzpicture}
1808 \end{marginfigure}
1809
1810 \begin{docspec}
1811 \begin{lstlisting}
1812 \begin{tikzpicture}
1813 \Text[RGB,color={127,201,127}]{A}
1814 \Text[x=1,RGB,color={190,174,212}]{B}
1815 \Text[x=2,RGB,color={253,192,134}]{C}
1816 \end{tikzpicture}
1817 \end{lstlisting}
1818 \end{docspec}
1819
1820 \begin{docspecdef}
1821 \doccmd{layer}[\docopt{layer}=\docarg{number}]\{\docarg{string}\}
1822 \end{docspecdef}
1823
1824 With the option \docopt{layer} the text can be assigned to a specific layer. More about this option and the use of layers is explained in Chapter~\ref{chap:multilayer_networks}.
1825
1826 \chapter{Complex Networks}
1827 \label{chap:complex_networks}
1828
1829 While in Chapter~\ref{chap:simple_networks} the building blocks of the networks are introduced, here the main strength of the \pkg package is explained. This includes creating networks based on data, obtained from other sources (e.g. Python, R, GIS). The idea is that the layout will be done by this external sources and \pkg is used make some changes and to recreate the networks in \LaTeX.
1830
1831 \section{Vertices}
1832 \label{sec:vertices}
1833
1834 The \doccmddef{Vertices} command is the extension of the \doccmd{Vertex} command. Instead of a single vertex, a set of vertices will be drawn. This set of vertices is defined in an external file but can be modified with \doccmd{Vertices}.
1835 \begin{docspecdef}
1836 \doccmd{Vertices}[\docopt{global options}]\{\docarg{filename}\}
1837 \end{docspecdef}
1838
1839 The vertices have to be stored in a clear text file\footnote{e.g. .txt, .tex, .csv, .dat, \dots}, preferentially in a \texttt{.csv} format. The first row should contain the headings, which are equal to the options defined in Table \ref{tab:vertex_options}. Option are separated by a comma <<,>>. Each new row is corresponds to a new vertex.
1840 \marginnote[8mm]{File: vertices.csv}
1841 \begin{docspec}
1842 \begin{lstlisting}
1843 id, x, y ,size,color ,opacity,label,IdAsLabel,NoLabel
1844 A, 0, 0, .4 ,green , .9 , a , false , false
1845 B, 1, .7, .6 , , .5 , b , false , false
1846 C, 2, 1, .8 ,orange, .3 , c , false , true
1847 D, 2, 0, .5 ,red , .7 , d , true , false
1848 E,.2,1.5, .5 ,gray , , e , false , false
1849 \end{lstlisting}
1850 \end{docspec}
1851
1852 Only the \docopt{id} value is mandatory for a vertex and corresponds to the \docarg{Name} argument of a single \doccmd{Vertex}. Therefore, the same rules and naming conventions apply as for the \docarg{Name} argument: no mathematical expressions, no blank spaces, and the \docopt{id} must be unique! All other options are optional. No specific order of the options must be maintained. If no value is entered for an option, the default value will be chosen\footnote{\TODO This is NOT valid for Boolean options, here values for all vertices have to be entered.}. The \docarg{filename} should not contain blank spaces or special characters. The vertices are drawn by the command \doccmd{Vertex} with the \docarg{filename} plus file format (e.g. \texttt{.csv}). If the vertices file is not in the same directory as the main \LaTeX~file, also the path has to be specified.
1853
1854 \newpage
1855 \begin{marginfigure}[2mm]
1856 \centering
1857 \begin{tikzpicture}
1858 \Vertices{data/vertices.csv}
1859 \end{tikzpicture}
1860 \end{marginfigure}
1861
1862 \begin{docspec}
1863 \begin{lstlisting}
1864 \begin{tikzpicture}
1865 \Vertices{data/vertices.csv}
1866 \end{tikzpicture}
1867 \end{lstlisting}
1868 \end{docspec}
1869
1870 Predefined \doccmd{Vertex} options can be overruled by the \docopt{global options} of the \doccmd{Vertices} command; I.e. these options apply for all vertices in the file. For the \doccmd{Vertices} the following options are available:
1871
1872 \begin{table}[h]\index{Vertices!options}
1873 \footnotesize%
1874 \begin{center}
1875 \begin{tabular}{lccl}
1876 \toprule
1877 Option & Default & Type &Definition \\
1878 \midrule
1879 size & \{\} & measure& diameter of the circles\\
1880 color & \{\} & color & fillcolor of vertices\\
1881 opacity & \{\} & number & opacity of the fill color \\
1882 style & \{\} & string & additional \tikzsym styles \\
1883 layer & \{\} & number & assigned layer of the vertices \\
1884 \midrule
1885 NoLabel & false & Boolean & delete the labels \\
1886 IdAsLabel & false & Boolean & uses the \docarg{Names} as labels \\
1887 Math & false & Boolean & displays the labels in math mode \\
1888 RGB & false & Boolean & allow RGB colors \\
1889 Pseudo & false & Boolean & create a pseudo vertices\\
1890 \bottomrule
1891 \end{tabular}
1892 \scriptsize
1893 \end{center}
1894 \caption{Global options for the \doccmd{Vertices} command.}
1895 \label{tab:vertices_options}
1896 \end{table}
1897
1898 The use of these options are similar to the options for a single \doccmd{Vertex} defined in Section~\ref{sec:vertex}.
1899
1900 \begin{docspecdef}
1901 \doccmd{Vertices}[\docopt{size}=\docarg{measure}]\{\docarg{filename}\}
1902 \end{docspecdef}
1903
1904 The diameter of the vertices can be changed with the option \docopt{size}. Per default a vertex has \SI{0.6}{cm} in diameter. Also, here the default units are \si{cm} and have not to be added to the \docarg{measure}.
1905
1906 \begin{marginfigure}[28mm]
1907 \centering
1908 \begin{tikzpicture}
1909 \Vertices[size=.6]{data/vertices.csv}
1910 \end{tikzpicture}
1911 \end{marginfigure}
1912
1913 \begin{docspec}
1914 \begin{lstlisting}
1915 \begin{tikzpicture}
1916 \Vertices[size=.6]{data/vertices.csv}
1917 \end{tikzpicture}
1918 \end{lstlisting}
1919 \end{docspec}
1920
1921 \begin{docspecdef}
1922 \doccmd{Vertices}[\docopt{color}=\docarg{color}]\{\docarg{filename}\}
1923 \end{docspecdef}
1924
1925 To change the fill color for all vertices, the option \docopt{color} has to be used. Without the option \docopt{RGB} set, the default \tikzsym and \LaTeX~ colors can be applied.
1926
1927 \begin{marginfigure}[22mm]
1928 \centering
1929 \begin{tikzpicture}
1930 \Vertices[color=green!70!blue]{data/vertices.csv}
1931 \end{tikzpicture}
1932 \end{marginfigure}
1933
1934 \begin{docspec}
1935 \begin{lstlisting}
1936 \begin{tikzpicture}
1937 \Vertices[color=green!70!blue]{data/vertices.csv}
1938 \end{tikzpicture}
1939 \end{lstlisting}
1940 \end{docspec}
1941
1942 \begin{docspecdef}
1943 \doccmd{Vertices}[\docopt{opacity}=\docarg{number}]\{\docarg{filename}\}
1944 \end{docspecdef}
1945
1946 With the option \docopt{opacity} the opacity of all vertices fills colors can be modified. The range of the \docarg{number} lies between $0$ and $1$. Where $0$ represents a fully transparent fill and $1$ a solid fill.
1947
1948 \newpage
1949 \begin{marginfigure}[2mm]
1950 \centering
1951 \begin{tikzpicture}
1952 \Vertices[opacity=.3]{data/vertices.csv}
1953 \end{tikzpicture}
1954 \end{marginfigure}
1955
1956 \begin{docspec}
1957 \begin{lstlisting}
1958 \begin{tikzpicture}
1959 \Vertices[opacity=.3]{data/vertices.csv}
1960 \end{tikzpicture}
1961 \end{lstlisting}
1962 \end{docspec}
1963
1964
1965 \begin{docspecdef}
1966 \doccmd{Vertices}[\docopt{style}=\docarg{string}]\{\docarg{filename}\}
1967 \end{docspecdef}
1968
1969 Any other \tikzsym style option or command can be entered via the option \docopt{style}. Most of these commands can be found in the ``\tikzsym and PGF Manual''. Contain the commands additional options (e.g.\docopt{shading}=\docarg{ball}), then the argument for the \docopt{style} has to be between $\{~\}$ brackets.
1970
1971 \begin{marginfigure}[25mm]
1972 \centering
1973 \begin{tikzpicture}
1974 \Vertices[style={shading=ball,blue}]{data/vertices.csv}
1975 \end{tikzpicture}
1976 \end{marginfigure}
1977
1978 \begin{docspec}
1979 \begin{lstlisting}
1980 \begin{tikzpicture}
1981 \Vertices[style={shading=ball,blue}]{data/vertices.csv}
1982 \end{tikzpicture}
1983 \end{lstlisting}
1984 \end{docspec}
1985
1986
1987 \begin{docspecdef}
1988 \doccmd{Vertices}[\docopt{IdAsLabel}]\{\docarg{filename}\}
1989 \end{docspecdef}
1990 \begin{docspecdef}
1991 \doccmd{Vertices}[\docopt{NoLabel}]\{\docarg{filename}\}
1992 \end{docspecdef}
1993
1994 \docopt{IdAsLabel} is a Boolean option which assigns the \docopt{id} of the single vertices as labels. On the contrary, \docopt{NoLabel} suppress all labels.
1995
1996 \begin{marginfigure}[22mm]
1997 \centering
1998 \begin{tikzpicture}
1999 \Vertices[IdAsLabel]{data/vertices.csv}
2000 %\node at (2,1)[font=\scriptsize]{C};
2001 \end{tikzpicture}
2002 \end{marginfigure}
2003
2004 \begin{docspec}
2005 \begin{lstlisting}
2006 \begin{tikzpicture}
2007 \Vertices[IdAsLabel]{data/vertices.csv}
2008 \end{tikzpicture}
2009 \end{lstlisting}
2010 \end{docspec}
2011
2012 \begin{marginfigure}[2mm]
2013 \centering
2014 \begin{tikzpicture}
2015 \Vertices[NoLabel]{data/vertices.csv}
2016 \end{tikzpicture}
2017 \end{marginfigure}
2018
2019 \begin{docspec}
2020 \begin{lstlisting}
2021 \begin{tikzpicture}
2022 \Vertices[NoLabel]{data/vertices.csv}
2023 \end{tikzpicture}
2024 \end{lstlisting}
2025 \end{docspec}
2026
2027
2028 \begin{docspecdef}
2029 \doccmd{Vertices}[\docopt{RGB}]\{\docarg{filename}\}
2030 \end{docspecdef}
2031
2032 In order to display RGB colors for the vertex fill colors, the option \docopt{RGB} has to be entered. Additionally, the RGB values have to be specified in the file where the vertices are stored. Each value has its own column with the caption \docopt{R}, \docopt{G}, and \docopt{B}.
2033
2034 \marginnote[8mm]{File: vertices\_RGB.csv}
2035 \begin{docspec}
2036 \begin{lstlisting}
2037 id, x, y ,size, color,opacity,label, R , G , B
2038 A, 0, 0, .4 , green, .9 , a ,255, 0, 0
2039 B, 1, .7, .6 , , .5 , b , 0,255, 0
2040 C, 2, 1, .8 ,orange, .3 , c , 0, 0,255
2041 D, 2, 0, .5 , red, .7 , d , 10,120,255
2042 E,.2,1.5, .5 , gray, , e , 76, 55,255
2043 \end{lstlisting}
2044 \end{docspec}
2045
2046 The ``normal'' color definition can also be part of the vertex definition. If the option \docopt{RGB} is not set, then the colors under \docopt{color} are applied.
2047
2048 \newpage
2049 \begin{marginfigure}[3mm]
2050 \centering
2051 \begin{tikzpicture}
2052 \Vertices[RGB]{data/vertices_RGB.csv}
2053 \end{tikzpicture}
2054 \end{marginfigure}
2055
2056 \begin{docspec}
2057 \begin{lstlisting}
2058 \begin{tikzpicture}
2059 \Vertices[RGB]{data/vertices_RGB.csv}
2060 \end{tikzpicture}
2061 \end{lstlisting}
2062 \end{docspec}
2063
2064
2065 \begin{docspecdef}
2066 \doccmd{Vertices}[\docopt{Pseudo}]\{\docarg{filename}\}
2067 \end{docspecdef}
2068
2069 The option \docopt{Pseudo} creates a pseudo vertices, where only the names and the coordinates of the vertices wil be drawn. Edges etc, can still be assigned to these vertices.
2070
2071 \begin{docspecdef}
2072 \doccmd{Vertices}[\docopt{layer}=\docarg{number}]\{\docarg{filename}\}
2073 \end{docspecdef}
2074
2075 With the option \docopt{layer}, only the vertices on the selected layer are plotted. More about this option and the use of layers is explained in Chapter~\ref{chap:multilayer_networks}.
2076
2077 \newpage
2078 \section{Edges}
2079 \label{sec:edges}
2080
2081 The \doccmddef{Edges} command is the extension of the \doccmd{Edge} command. Instead of a single edge, a set of edges will be drawn. This set of edges is defined in an external file but can be modified with \doccmd{Edges}.
2082 \begin{docspecdef}
2083 \doccmd{Edges}[\docopt{global options}]\{\docarg{filename}\}
2084 \end{docspecdef}
2085
2086 Like the vertices, the edges have to be stored in a clear text file\footnote{e.g. .txt, .tex, .csv, .dat, \dots}, preferentially in a \texttt{.csv} format. The first row should contain the headings, which are equal to the options defined in Table \ref{tab:edge_options}. Option are separated by a comma <<,>>. Each new row is corresponds to a new edge.
2087
2088 \marginnote[8mm]{File: edges.csv}
2089 \begin{docspec}
2090 \begin{lstlisting}
2091 u,v,label,lw,color ,opacity,bend, R , G , B ,Direct
2092 A,B, ab ,.5,red , 1 , 30, 0,120,255,false
2093 B,C, bc ,.7,blue , 1 , -60, 76, 55,255,false
2094 B,D, bd ,.5,blue , .5 , -60, 76, 55,255,false
2095 A,E, ae , 1,green , 1 , 75,255, 0, 0,true
2096 C,E, ce , 2,orange, 1 , 0,150,150,150,false
2097 A,A, aa ,.3,black , .5 , 75,255, 0 ,0,false
2098 \end{lstlisting}
2099 \end{docspec}
2100
2101 The mandatory values are the \docopt{u} and \docopt{v} argument, which corresponds to the \docarg{Vertex i} and \docarg{Vertex j} arguments of a single \doccmd{Edge}. Edges can only create if a vertex exists with the same \docarg{Name}. All other options are optional. No specific order of the options must be maintained. If no value is entered for an option, the default value will be chosen\footnote{\TODO This is NOT valid for Boolean options, here values for all vertices have to be entered.}. The \docarg{filename} should not contain blank spaces or special characters. The edges are drawn by the command \doccmd{Edges} with the \docarg{filename} plus file format (e.g. \texttt{.csv}). If the edges file is not in the same directory as the main \LaTeX~file, also the path has to be specified. In order to draw edges, first, the vertices have to be generated. Only then, edges can be assigned.
2102
2103 \begin{marginfigure}[18mm]
2104 \centering
2105 \begin{tikzpicture}
2106 \Vertices{data/vertices.csv}
2107 \Edges{data/edges.csv}
2108 \end{tikzpicture}
2109 \end{marginfigure}
2110
2111 \begin{docspec}
2112 \begin{lstlisting}
2113 \begin{tikzpicture}
2114 \Vertices{data/vertices.csv}
2115 \Edges{data/edges.csv}
2116 \end{tikzpicture}
2117 \end{lstlisting}
2118 \end{docspec}
2119
2120 Predefined \doccmd{Edge} options can be overruled by the \docopt{global options} of the \doccmd{Edges} command; I.e. these options apply for all edges in the file. For the \doccmd{Edges} the following options are available:
2121
2122 \newpage
2123 \begin{table}[h]\index{Edges!options}
2124 \footnotesize%
2125 \begin{center}
2126 \begin{tabular}{lccl}
2127 \toprule
2128 Option & Default & Type &Definition \\
2129 \midrule
2130 lw & \{\} & measure & line width of the edge \\
2131 color & \{\} & color & edge color\\
2132 opacity & \{\} & number & opacity of the edge \\
2133 style & \{\} & string & additional \tikzsym styles \\
2134 vertices & \{\} & file & vertices were the edges are assigned to\\
2135 layer & \{\} & number & edges in specific layers \\
2136 \midrule
2137 Direct & false & Boolean & allow directed edges \\
2138 Math & false & Boolean & displays the labels in math mode \\
2139 NoLabel & false & Boolean & delete the labels\\
2140 RGB & false & Boolean & allow RGB colors \\
2141 NotInBG & false & Boolean & edges are not in the background layer\\
2142 \bottomrule
2143 \end{tabular}
2144 \scriptsize
2145 \end{center}
2146 \caption{Global options for the \doccmd{Edges} command.}
2147 \label{tab:edges_options}
2148 \end{table}
2149
2150 The use of these options are similar to the options for a single \doccmd{Edge} defined in Section~\ref{sec:edge}.
2151
2152 \begin{docspecdef}
2153 \doccmd{Edges}[\docopt{lw}=\docarg{measure}]\{\docarg{filename}\}
2154 \end{docspecdef}
2155
2156 The line width of the edges can be modified with the option \docopt{lw}. Here, the unit of the \docarg{measure} can be specified, otherwise, it is in \si{pt}.
2157
2158 \begin{marginfigure}[35mm]
2159 \centering
2160 \begin{tikzpicture}
2161 \Vertices{data/vertices.csv}
2162 \Edges[lw=2.5]{data/edges.csv}
2163 \end{tikzpicture}
2164 \end{marginfigure}
2165
2166 \begin{docspec}
2167 \begin{lstlisting}
2168 \begin{tikzpicture}
2169 \Vertices{data/vertices.csv}
2170 \Edges[lw=2.5]{data/edges.csv}
2171 \end{tikzpicture}
2172 \end{lstlisting}
2173 \end{docspec}
2174
2175 \begin{docspecdef}
2176 \doccmd{Edges}[\docopt{color}=\docarg{color}]\{\docarg{filename}\}
2177 \end{docspecdef}
2178
2179 To change the line color of all edges, the option \docopt{color} has to be used. Without the option \docopt{RGB} set, the default \tikzsym and \LaTeX~ colors can be applied.
2180
2181 \begin{marginfigure}[20mm]
2182 \centering
2183 \begin{tikzpicture}
2184 \Vertices{data/vertices.csv}
2185 \Edges[color=green!70!blue]{data/edges.csv}
2186 \end{tikzpicture}
2187 \end{marginfigure}
2188
2189 \begin{docspec}
2190 \begin{lstlisting}
2191 \begin{tikzpicture}
2192 \Vertices{data/vertices.csv}
2193 \Edges[color=green!70!blue]{data/edges.csv}
2194 \end{tikzpicture}
2195 \end{lstlisting}
2196 \end{docspec}
2197
2198 \begin{docspecdef}
2199 \doccmd{Edges}[\docopt{opacity}=\docarg{number}]\{\docarg{filename}\}
2200 \end{docspecdef}
2201
2202 With the option \docopt{opacity} the opacity of all edge lines can be modified. The range of the \docarg{number} lies between $0$ and $1$. Where $0$ represents a fully transparent fill and $1$ a solid fill.
2203
2204 \begin{marginfigure}[20mm]
2205 \centering
2206 \begin{tikzpicture}
2207 \Vertices{data/vertices.csv}
2208 \Edges[opacity=0.3]{data/edges.csv}
2209 \end{tikzpicture}
2210 \end{marginfigure}
2211
2212 \begin{docspec}
2213 \begin{lstlisting}
2214 \begin{tikzpicture}
2215 \Vertices{data/vertices.csv}
2216 \Edges[opacity=0.3]{data/edges.csv}
2217 \end{tikzpicture}
2218 \end{lstlisting}
2219 \end{docspec}
2220
2221 \newpage
2222 \begin{docspecdef}
2223 \doccmd{Edges}[\docopt{style}=\docarg{string}]\{\docarg{filename}\}
2224 \end{docspecdef}
2225
2226 Any other \tikzsym style option or command can be entered via the option \docopt{style}. Most of these commands can be found in the ``\tikzsym and PGF Manual''.
2227
2228 \begin{marginfigure}[25mm]
2229 \centering
2230 \begin{tikzpicture}
2231 \Vertices{data/vertices.csv}
2232 \Edges[style={dashed}]{data/edges.csv}
2233 \end{tikzpicture}
2234 \end{marginfigure}
2235
2236 \begin{docspec}
2237 \begin{lstlisting}
2238 \begin{tikzpicture}
2239 \Vertices{data/vertices.csv}
2240 \Edges[style={dashed}]{data/edges.csv}
2241 \end{tikzpicture}
2242 \end{lstlisting}
2243 \end{docspec}
2244
2245
2246 \begin{docspecdef}
2247 \doccmd{Edges}[\docopt{Direct}]\{\docarg{filename}\}
2248 \end{docspecdef}
2249
2250 Directed edges are created by enabling the option \docopt{Direct}. The arrow is drawn from \docopt{u} to \docopt{v}.
2251
2252 \begin{marginfigure}[15mm]
2253 \centering
2254 \begin{tikzpicture}
2255 \Vertices{data/vertices.csv}
2256 \Edges[Direct]{data/edges.csv}
2257 \end{tikzpicture}
2258 \end{marginfigure}
2259
2260 \begin{docspec}
2261 \begin{lstlisting}
2262 \begin{tikzpicture}
2263 \Vertices{data/vertices.csv}
2264 \Edges[Direct]{data/edges.csv}
2265 \end{tikzpicture}
2266 \end{lstlisting}
2267 \end{docspec}
2268
2269 \begin{docspecdef}
2270 \doccmd{Edges}[Math]\{\docarg{filename}\}
2271 \end{docspecdef}
2272
2273 The option \docopt{Math} allows transforming labels into mathematical expressions without using the \$~\$ environment.
2274
2275 \begin{docspecdef}
2276 \doccmd{Edges}[\docopt{NoLabel}]\{\docarg{filename}\}
2277 \end{docspecdef}
2278
2279 The option \docopt{NoLabel} suppress all edge labels.
2280
2281 \begin{marginfigure}[30mm]
2282 \centering
2283 \begin{tikzpicture}
2284 \Vertices{data/vertices.csv}
2285 \Edges[NoLabel]{data/edges.csv}
2286 \end{tikzpicture}
2287 \end{marginfigure}
2288
2289 \begin{docspec}
2290 \begin{lstlisting}
2291 \begin{tikzpicture}
2292 \Vertices{data/vertices.csv}
2293 \Edges[NoLabel]{data/edges.csv}
2294 \end{tikzpicture}
2295 \end{lstlisting}
2296 \end{docspec}
2297
2298 \begin{docspecdef}
2299 \doccmd{Edges}[\docopt{RGB}]\{\docarg{filename}\}
2300 \end{docspecdef}
2301
2302 In order to display RGB colors for the edge line colors, the option \docopt{RGB} has to be entered. Additionally, the RGB values have to be specified in the file where the vertices are stored. Each value has its own column with the caption \docopt{R}, \docopt{G}, and \docopt{B}. The ``normal'' color definition can also be part of the vertex definition. If the option \docopt{RGB} is not set, then the colors under \docopt{color} are applied.
2303
2304 \begin{marginfigure}[34mm]
2305 \centering
2306 \begin{tikzpicture}
2307 \Vertices{data/vertices.csv}
2308 \Edges[RGB]{data/edges.csv}
2309 \end{tikzpicture}
2310 \end{marginfigure}
2311
2312 \begin{docspec}
2313 \begin{lstlisting}
2314 \begin{tikzpicture}
2315 \Vertices{data/vertices.csv}
2316 \Edges[RGB]{data/edges.csv}
2317 \end{tikzpicture}
2318 \end{lstlisting}
2319 \end{docspec}
2320
2321
2322 \begin{docspecdef}
2323 \doccmd{Edges}[\docopt{NotInBG}]\{\docarg{filename}\}
2324 \end{docspecdef}
2325
2326 Per default, the edges are drawn on the background layer of the \docarg{tikzpicture}. I.e. objects which are created after the edges appear also on top of them. To turn this off, the option \docopt{NotInBG} has to be enabled.
2327
2328 \begin{docspecdef}
2329 \doccmd{Edges}[\docopt{vertices}=\docarg{filename}]\{\docarg{filename}\}
2330 \end{docspecdef}
2331
2332 Edges can be assigned to a specific set of \doccmd{Vertices} with the option \docopt{vertices}. Thereby the argument \docarg{filename} is the same as used for the \doccmd{Vertices} command. This option might be necessary if multiple \doccmd{Vertices} are created and edges are assigned at the end.
2333
2334 \begin{docspecdef}
2335 \doccmd{Edges}[\docopt{layer}=\{\docarg{{layer $\alpha$}},\docarg{{layer $\beta$}}\}]\{\docarg{filename}\}
2336 \end{docspecdef}
2337
2338 With the option \docopt{layer} only the edges between layer $\alpha$ and $\beta$ are plotted. The argument is a tuple of both layers indicated by $\{~,~\}$. More about this option and the use of layers is explained in Chapter~\ref{chap:multilayer_networks}.
2339
2340
2341
2342 \chapter{Multilayer Networks}
2343 \label{chap:multilayer_networks}
2344
2345 One of the main purposes of the \pkg package is the illustration of multilayer network structures. Thereby, all the previous commands can be used. A multilayer network is represented as a three-dimensional object, where each layer is located at a different $z$ plane. In order to enable this functionality, the option \docopt{multilayer} has to be used at the beginning of the \docenvdef{tikzpicture}.
2346
2347 \section{Simple Networks}
2348 \label{sec:simple_networks}
2349
2350
2351 \begin{docspecdef}
2352 \doccmd{Vertex}[\docopt{layer}=\docarg{number}]\{\docarg{Name}\}
2353 \end{docspecdef}
2354
2355 With the option \docopt{layer} the vertex can be assigned to a specific layer. Layers are defined by numbers (e.g. $1$, $2$, $3$,\dots). Working with the \docopt{multilayer} option, each \doccmd{Vertex} has to be assigned to a specific layer. For the edge assignment no additional information is needed.
2356
2357 \begin{marginfigure}[45mm]
2358 \centering
2359 \begin{tikzpicture}[multilayer]
2360 \begin{Layer}[layer=2]
2361 \draw[orange,very thick] (0,0) rectangle (2.5,1);
2362 \draw[step=.5, orange,draw opacity=.5] (0,0) grid (2.5,1);
2363 \end{Layer}
2364 \Vertex[x=.5,y=.5,IdAsLabel,layer=1]{A}
2365 \Vertex[x=1.5,y=.5,IdAsLabel,layer=1]{B}
2366 \Vertex[x=1.5,y=.5,IdAsLabel,layer=2]{C}
2367 \Edge[bend=60](A)(B)
2368 \Edge(C)(C)
2369 \Edge[style=dashed](B)(C)
2370 \end{tikzpicture}
2371 \end{marginfigure}
2372
2373 \begin{docspec}
2374 \begin{lstlisting}
2375 \begin{tikzpicture}[multilayer]
2376 \Vertex[x=0.5,IdAsLabel,layer=1]{A}
2377 \Vertex[x=1.5,IdAsLabel,layer=1]{B}
2378 \Vertex[x=1.5,IdAsLabel,layer=2]{C}
2379 \Edge[bend=60](A)(B)
2380 \Edge[style=dashed](B)(C)
2381 \Edge(C)(C)
2382 \end{tikzpicture}
2383 \end{lstlisting}
2384 \end{docspec}
2385
2386 Enabling the option \docopt{multilayer}, returns the network in a two-dimensional plane, like the networks discussed before. Setting the argument \docopt{multilayer}=\docarg{3d}, the network is rendered in a three-dimensional representation. Per default, the layer with the lowest number is on the top. This and the spacing between the layers can be changed with the command \doccmd{SetLayerDistance}.
2387
2388 \begin{marginfigure}[45mm]
2389 \centering
2390 \begin{tikzpicture}[multilayer=3d]
2391 \SetLayerDistance{-1.5}
2392 \begin{Layer}[layer=1]
2393 \draw[orange,very thick] (0,0) rectangle (2.5,1);
2394 \draw[step=.5, orange,draw opacity=.5] (0,0) grid (2.5,1);
2395 \node at (0,0)[below right,orange]{Layer 1};
2396 \end{Layer}
2397 \begin{Layer}[layer=2]
2398 \draw[orange,very thick] (0,0) rectangle (2.5,1);
2399 \draw[step=.5, orange,draw opacity=.5] (0,0) grid (2.5,1);
2400 \node at (0,0)[below right,orange]{Layer 2};
2401 \end{Layer}
2402 \Vertex[x=0.5,y=.5,IdAsLabel,layer=1]{A}
2403 \Vertex[x=1.5,y=.5,IdAsLabel,layer=1]{B}
2404 \Vertex[x=1.5,y=.5,IdAsLabel,layer=2]{C}
2405 \Edge[bend=60](A)(B)
2406 \Edge(C)(C)
2407 \Edge[style=dashed](B)(C)
2408 \end{tikzpicture}
2409 \end{marginfigure}
2410
2411 \begin{docspec}
2412 \begin{lstlisting}
2413 \begin{tikzpicture}[multilayer=3d]
2414 \Vertex[x=0.5,IdAsLabel,layer=1]{A}
2415 \Vertex[x=1.5,IdAsLabel,layer=1]{B}
2416 \Vertex[x=1.5,IdAsLabel,layer=2]{C}
2417 \Edge[bend=60](A)(B)
2418 \Edge[style=dashed](B)(C)
2419 \Edge(C)(C)
2420 \end{tikzpicture}
2421 \end{lstlisting}
2422 \end{docspec}
2423
2424
2425 \section{Complex Networks}
2426
2427 Similar as in Chapter \ref{chap:complex_networks} introduced, layers can be assigned to the vertices by adding a column \docopt{layer} to the file where the vertices are stored.
2428
2429 \marginnote[8mm]{File: ml\_vertices.csv}
2430 \begin{docspec}
2431 \begin{lstlisting}
2432 id, x, y ,size, color,opacity,label,layer
2433 A, 0, 0, .4 , green, .9 , a , 1
2434 B, 1, .7, .6 , , .5 , b , 1
2435 C, 2, 1, .8 ,orange, .3 , c , 1
2436 D, 2, 0, .5 , red, .7 , d , 2
2437 E,.2,1.5, .5 , gray, , e , 1
2438 F,.1, .5, .7 , blue, .3 , f , 2
2439 G, 2, 1, .4 , cyan, .7 , g , 2
2440 H, 1, 1, .4 ,yellow, .7 , h , 2
2441 \end{lstlisting}
2442 \end{docspec}
2443
2444 \marginnote[8mm]{File: ml\_edges.csv}
2445 \begin{docspec}
2446 \begin{lstlisting}
2447 u,v,label,lw,color ,opacity,bend,Direct
2448 A,B, ab ,.5,red , 1 , 30,false
2449 B,C, bc ,.7,blue , 1 , -60,false
2450 A,E, ae , 1,green , 1 , 45,true
2451 C,E, ce , 2,orange, 1 , 0,false
2452 A,A, aa ,.3,black , .5 , 75,false
2453 C,G, cg , 1,blue , .5 , 0,false
2454 E,H, eh , 1,gray , .5 , 0,false
2455 F,A, fa ,.7,red , .7 , 0,true
2456 D,F, df ,.7,cyan , 1 , 30,true
2457 F,H, fh ,.7,purple, 1 , 60,false
2458 D,G, dg ,.7,blue , .7 , 60,false
2459 \end{lstlisting}
2460 \end{docspec}
2461
2462 With the commands \doccmd{Vertices} and \doccmd{Edges}, the network can be created automatically. Again the \doccmd{Vertices} vertices should be performed first and then the command \doccmd{Edges}.
2463
2464 \begin{marginfigure}[25mm]
2465 \centering
2466 \begin{tikzpicture}[multilayer=3d]
2467 \SetLayerDistance{-1.5}
2468 \Vertices[NoLabel,opacity=0]{data/ml_vertices.csv}
2469 \begin{Layer}[layer=2]
2470 \draw[orange,very thick] (-.5,-.5) rectangle (2.5,2);
2471 \draw[step=.5, orange,draw opacity=.5] (-.5,-.5) grid (2.5,2);
2472 \node at (-.5,-.5)[below right,orange]{Layer 2};
2473 \end{Layer}
2474 \Edges[NotInBG,layer={2,2}]{data/ml_edges.csv}
2475 \Edges[NotInBG,layer={1,2}]{data/ml_edges.csv}
2476 \Vertices[layer=2]{data/ml_vertices.csv}
2477 \begin{Layer}[layer=1]
2478 \draw[orange,very thick,fill=white,fill opacity=.7] (-.5,-.5) rectangle (2.5,2);
2479 \draw[step=.5, orange,draw opacity=.5] (-.5,-.5) grid (2.5,2);
2480 \node at (-.5,-.5)[below right,orange]{Layer 1};
2481 \end{Layer}
2482 \Edges[NotInBG,layer={1,1}]{data/ml_edges.csv}
2483 \Vertices[layer=1]{data/ml_vertices.csv}
2484 \end{tikzpicture}
2485 \end{marginfigure}
2486
2487 \begin{docspec}
2488 \begin{lstlisting}
2489 \begin{tikzpicture}[multilayer=3d]
2490 \Vertices{data/ml_vertices.csv}
2491 \Edges{data/ml_edges.csv}
2492 \end{tikzpicture}
2493 \end{lstlisting}
2494 \end{docspec}
2495
2496 \begin{docspecdef}
2497 \doccmd{Vertices}[\docopt{layer}=\docarg{number}]\{\docarg{filename}\}
2498 \end{docspecdef}
2499 \begin{docspecdef}
2500 \doccmd{Edges}[\docopt{layer}=\{\docarg{{layer $\alpha$}},\docarg{{layer $\beta$}}\}]\{\docarg{filename}\}
2501 \end{docspecdef}
2502
2503 With the \doccmd{Vertices} option \docopt{layer} only the vertices on the selected layer are plotted. While, with the \doccmd{Edges} option \docopt{layer}, the edges between layer $\alpha$ and $\beta$ are plotted. The argument is a tuple of both layers indicated by $\{~,~\}$.
2504
2505 \begin{marginfigure}[30mm]
2506 \centering
2507 \begin{tikzpicture}[multilayer=3d]
2508 \SetLayerDistance{-1.5}
2509 \begin{Layer}[layer=1]
2510 \draw[orange,very thick,fill=white,fill opacity=.7] (-.5,-.5) rectangle (2.5,2);
2511 \draw[step=.5, orange,draw opacity=.5] (-.5,-.5) grid (2.5,2);
2512 \node at (-.5,-.5)[below right,orange]{Layer 1};
2513 \end{Layer}
2514 \Vertices[layer=1]{data/ml_vertices.csv}
2515 \Edges[NotInBG,layer={1,1}]{data/ml_edges.csv}
2516 \end{tikzpicture}
2517 \end{marginfigure}
2518
2519 \begin{docspec}
2520 \begin{lstlisting}
2521 \begin{tikzpicture}[multilayer=3d]
2522 \Vertices[layer=1]{data/ml_vertices.csv}
2523 \Edges[layer={1,1}]{data/ml_edges.csv}
2524 \end{tikzpicture}
2525 \end{lstlisting}
2526 \end{docspec}
2527
2528 \newpage
2529
2530 Plotting edges without defining first the vertices can be done with the \doccmd{Edges} option \docopt{vertices}. This allows modifying specific sets of Edges.
2531
2532 \begin{marginfigure}[15mm]
2533 \centering
2534 \begin{tikzpicture}[multilayer=3d]
2535 \SetLayerDistance{-1.5}
2536 \Edges[vertices=data/ml_vertices.csv,layer={1,2},style=dashed]{data/ml_edges.csv}
2537 \end{tikzpicture}
2538 \end{marginfigure}
2539
2540 \begin{docspec}
2541 \begin{lstlisting}
2542 \begin{tikzpicture}[multilayer=3d]
2543 \Edges[vertices=data/ml_vertices.csv,
2544 layer={1,2},style=dashed]{data/ml_edges.csv}
2545 \end{tikzpicture}
2546 \end{lstlisting}
2547 \end{docspec}
2548
2549 \section{Layers and Layouts}
2550
2551 Besides adding vertices and edges to specific layers, every other \tikzsym object can be drawn on such a layer using the \docenvdef{Layer} environment. With the option \docopt{layer}=\docarg{layer $\alpha$}, the position of the canvas can be assigned to the specific layer.
2552
2553 \begin{docspecdef}
2554 \doccmd{begin}\{\docenv{Layer}\}[\docopt{layer}=\docarg{layer $\alpha$}]
2555
2556 \doccmd{end}\{\docenv{Layer}\}
2557 \end{docspecdef}
2558
2559 \begin{marginfigure}[40mm]
2560 \centering
2561 \begin{tikzpicture}[multilayer=3d]
2562 \SetLayerDistance{-1.5}
2563 \begin{Layer}[layer=1]
2564 \draw[very thick] (-.5,-.5) rectangle (2.5,2);
2565 \node at (-.5,-.5)[below right]{Layer 1};
2566 \end{Layer}
2567 \Vertices[layer=1]{data/ml_vertices.csv}
2568 \Edges[layer={1,1}]{data/ml_edges.csv}
2569 \end{tikzpicture}
2570 \end{marginfigure}
2571
2572 \begin{docspec}
2573 \begin{lstlisting}
2574 \begin{tikzpicture}[multilayer=3d]
2575 \begin{Layer}[layer=1]
2576 \draw[very thick] (-.5,-.5) rectangle (2.5,2);
2577 \node at (-.5,-.5)[below right]{Layer 1};
2578 \end{Layer}
2579 \Vertices[layer=1]{data/ml_vertices.csv}
2580 \Edges[layer={1,1}]{data/ml_edges.csv}
2581 \end{tikzpicture}
2582 \end{lstlisting}
2583 \end{docspec}
2584
2585 \begin{docspecdef}
2586 \doccmd{SetLayerDistance}\{\docarg{measure}\}
2587 \end{docspecdef}
2588
2589 With the command \doccmddef{SetLayerDistance} the distance between the layers and their orientation can be modified. Per default the distance is set to $-2$\doccmd{DefaultUnit} (here \si{cm}). A negative number implies that layers with a higher number will be stacked below layers with a smaller number.
2590
2591 \begin{docspecdef}
2592 \doccmd{SetCoordinates}[\docopt{xAngle}=\docarg{number},\docopt{yAngle}=\docarg{number},\docopt{zAngle}=\docarg{number}, \docopt{xLength}=\docarg{number},\docopt{yLength}=\docarg{number},\docopt{zLength}=\docarg{number}]
2593 \end{docspecdef}
2594
2595 The perspective of the three-dimensional plot can be modified by changing the orientation of the coordinate system, which is done with the command \doccmddef{SetCoordinates}. Here the angle and the length of each axis can be modified. Angles are defined as a \docarg{number} in the range between $-360$ and $360$. Per default, the lengths of the axes are defined by the identity matrix, i.e. no distortion. If the length ratio is changed $x$, $y$, and/or $z$ values are distorted. The \doccmd{SetCoordinates} command has to be entered before the \docopt{multilayer} option is called!
2596
2597 \begin{marginfigure}[25mm]
2598 \centering
2599 \SetCoordinates[xAngle=-30,yLength=1.2,xLength=.8]
2600 \begin{tikzpicture}[multilayer=3d]
2601 \SetLayerDistance{-1.5}
2602 \begin{Layer}[layer=1]
2603 \draw[orange,very thick,fill=white,fill opacity=.7] (-.5,-.5) rectangle (2.5,2);
2604 \draw[step=.5, orange,draw opacity=.5] (-.5,-.5) grid (2.5,2);
2605 \node at (-.5,-.5)[below right,orange]{Layer 1};
2606 \end{Layer}
2607 \Vertices[layer=1]{data/ml_vertices.csv}
2608 \Edges[NotInBG,layer={1,1}]{data/ml_edges.csv}
2609 \end{tikzpicture}
2610 \end{marginfigure}
2611
2612 \begin{docspec}
2613 \begin{lstlisting}
2614 \SetCoordinates[xAngle=-30,yLength=1.2,xLength=.8]
2615 \begin{tikzpicture}[multilayer=3d]
2616 \Vertices[layer=1]{data/ml_vertices.csv}
2617 \Edges[layer={1,1}]{data/ml_edges.csv}
2618 \end{tikzpicture}
2619 \end{lstlisting}
2620 \end{docspec}
2621 \newpage
2622 \section{Plane}
2623
2624 To support the illustration of multilayer networks, the background of the layer can be simply visualized with the command \doccmddef{Plane}, which allow to draw boundaries, grids and include images to the layer.
2625 \begin{docspecdef}
2626 \doccmd{Plane}[\docopt{options}]
2627 \end{docspecdef}
2628 No obligatory arguments are needed. For a \doccmd{Plane} the following options are available:
2629
2630 \begin{table}[h]\index{Plane!options}
2631 \footnotesize%
2632 \begin{center}
2633 \begin{tabular}{lccl}
2634 \toprule
2635 Option & Default & Type &Definition \\
2636 \midrule
2637 x & 0 & measure& x-coordinate of the origin\\
2638 y & 0 & measure& y-coordinate of the origin\\
2639 width & \SI{5}{cm} & measure& width of the plane\\
2640 height & \SI{5}{cm} & measure& height of the plane\\
2641 color & vertexfill & color & fill color of the plane \\
2642 opacity & 0.3 & number & opacity of the fill color \\
2643 grid & \{\} & measure& spacing of the grid\\
2644 image & \{\} & file & path to the image file \\
2645 style & \{\} & string & additional \tikzsym styles \\
2646 layer & 1 & number & layer where the plane is located\\
2647 \midrule
2648 RGB & false & Boolean & allow RGB colors \\
2649 NoFill & false & Boolean & disable fill color \\
2650 NoBorder & false & Boolean & disable border line \\
2651 ImageAndFill&false & Boolean & allow image and fill color \\
2652 InBG & false & Boolean & plane is in the background layer\\
2653 \bottomrule
2654 \end{tabular}
2655 \scriptsize
2656 \\$^a$ either measure or string
2657 \end{center}
2658 \caption{Options for the \doccmd{Plane} command.}
2659 \label{tab:plane_options}
2660 \end{table}
2661
2662 \begin{docspecdef}
2663 \doccmd{Plane}[\docopt{x}=\docarg{measure},\docopt{y}=\docarg{measure},\docopt{width}=\docarg{measure},\docopt{height}=\docarg{measure}]
2664 \end{docspecdef}
2665
2666 A \doccmd{Plane} is a rectangle with origin (\docopt{x},\docopt{y}), a given \docopt{width} and \docopt{height}. The origin is defined in the left lower corner and per default $(0,0)$. The plane is default \SI{5}{cm} (width) by \SI{5}{cm} (height). This default options can be changed with \doccmd{SetPlaneWidth} and \doccmd{SetPlaneHeight}\footnote{See Section \ref{sec:plane_style}.}
2667
2668 \begin{marginfigure}%[45mm]
2669 \centering
2670 \begin{tikzpicture}[multilayer=3d]
2671 \Plane[x=-.5,y=-.5,width=3,height=2.5]
2672 \begin{Layer}[layer=1]
2673 \filldraw [orange] (-.5,-.5) circle (3pt);
2674 \node [orange,anchor=south west] at (-.5,-.5) {origin};
2675 \draw[|<->|,orange] (-.5,-.8) --++ (3,0) node [pos=.5,below]{width};
2676 \draw[|<->|,orange] (2.8,-.5) --++ (0,2.5) node [pos=.5,below,sloped]{height};
2677 \end{Layer}
2678 \end{tikzpicture}
2679 \end{marginfigure}
2680
2681 \begin{docspec}
2682 \begin{lstlisting}
2683 \begin{tikzpicture}[multilayer=3d]
2684 \Plane[x=-.5,y=-.5,width=3,height=2.5]
2685 \end{tikzpicture}
2686 \end{lstlisting}
2687 \end{docspec}
2688
2689
2690 \begin{docspecdef}
2691 \doccmd{Plane}[\docopt{color}=\docarg{color}]
2692 \end{docspecdef}
2693
2694 To change the fill color of each plane individually, the option \docopt{color} has to be used. Without the option \docopt{RGB} set, the default \tikzsym and \LaTeX~ colors can be applied. Per default the default vertex color is used.
2695
2696 \begin{marginfigure}[22mm]
2697 \centering
2698 \begin{tikzpicture}[multilayer=3d]
2699 \Plane[x=-.5,y=-.5,width=3,height=2.5,color=green!70!blue]
2700 \end{tikzpicture}
2701 \end{marginfigure}
2702
2703 \begin{docspec}
2704 \begin{lstlisting}
2705 \begin{tikzpicture}[multilayer=3d]
2706 \Plane[x=-.5,y=-.5,width=3,height=2.5,color=green!70!blue]
2707 \end{tikzpicture}
2708 \end{lstlisting}
2709 \end{docspec}
2710
2711 \newpage
2712
2713 \begin{docspecdef}
2714 \doccmd{Plane}[\docopt{opacity}=\docarg{number}]
2715 \end{docspecdef}
2716
2717 With the option \docopt{opacity} the opacity of the plane fill color can be modified. The range of the \docarg{number} lies between $0$ and $1$. Where $0$ represents a fully transparent fill and $1$ a solid fill. Per default the opacity is set to $0.3$.
2718
2719 \begin{marginfigure}[22mm]
2720 \centering
2721 \begin{tikzpicture}[multilayer=3d]
2722 \Plane[x=-.5,y=-.5,width=3,height=2.5,opacity=.7]
2723 \end{tikzpicture}
2724 \end{marginfigure}
2725
2726 \begin{docspec}
2727 \begin{lstlisting}
2728 \begin{tikzpicture}[multilayer=3d]
2729 \Plane[x=-.5,y=-.5,width=3,height=2.5,opacity=.7]
2730 \end{tikzpicture}
2731 \end{lstlisting}
2732 \end{docspec}
2733
2734
2735 \begin{docspecdef}
2736 \doccmd{Plane}[\docopt{grid}=\docarg{measure}]
2737 \end{docspecdef}
2738
2739 With the option \docopt{grid} a grid will be drawn on top of the plane. The argument of this option defines the spacing between the grid lines. The entered \docarg{measures} are in default units (\si{cm}). Changing the unites (locally) can be done by adding the unit to the \docarg{measure}\footnote{e.g. x=\SI{5}{mm}}. Changes to the default setting can be made with \doccmd{SetDefaultUnit}\footnote{see Section \ref{sec:gerneral_settings}}.
2740
2741 \begin{marginfigure}%[22mm]
2742 \centering
2743 \begin{tikzpicture}[multilayer=3d]
2744 \Plane[x=-.5,y=-.5,width=3,height=2.5,grid=5mm]
2745 \begin{Layer}[layer=1]
2746 \draw[<->,orange] (2,-.7) --++ (.5,0) node [pos=.5,below]{5mm};
2747 \draw[<->,orange] (2.7,-.5) --++ (0,.5) node [pos=.5,below,sloped]{5mm};
2748 \end{Layer}
2749 \end{tikzpicture}
2750 \end{marginfigure}
2751
2752 \begin{docspec}
2753 \begin{lstlisting}
2754 \begin{tikzpicture}[multilayer=3d]
2755 \Plane[x=-.5,y=-.5,width=3,height=2.5,grid=5mm]
2756 \end{tikzpicture}
2757 \end{lstlisting}
2758 \end{docspec}
2759
2760
2761 \begin{docspecdef}
2762 \doccmd{Plane}[\docopt{image}=\docarg{file}]
2763 \end{docspecdef}
2764
2765 An image can be assigned to a plane with the option \docopt{image}. The argument is the file name and the folder where the image is stored. The width and height of the figure is scaled to the size of the plane. Without the option \docopt{ImageAndFill} the image overwrite the color options.
2766
2767 \begin{marginfigure}[22mm]
2768 \centering
2769 \begin{tikzpicture}[multilayer=3d]
2770 \Plane[x=-.5,y=-.5,width=3,height=2.5,image=data/plane.png]
2771 \end{tikzpicture}
2772 \end{marginfigure}
2773
2774 \begin{docspec}
2775 \begin{lstlisting}
2776 \begin{tikzpicture}[multilayer=3d]
2777 \Plane[x=-.5,y=-.5,width=3,height=2.5,image=data/plane.png]
2778 \end{tikzpicture}
2779 \end{lstlisting}
2780 \end{docspec}
2781
2782 \begin{docspecdef}
2783 \doccmd{Plane}[\docopt{style}=\docarg{string}]
2784 \end{docspecdef}
2785
2786 Any other \tikzsym style option or command can be entered via the option \docopt{style}. Most of these commands can be found in the ``\tikzsym and PGF Manual''. Contain the commands additional options (e.g.\docopt{inner color}=\docarg{color}), then the argument for the \docopt{style} has to be between $\{~\}$ brackets.
2787
2788 \begin{marginfigure}[22mm]
2789 \centering
2790 \begin{tikzpicture}[multilayer=3d]
2791 \Plane[x=-.5,y=-.5,width=3,height=2.5,style={dashed,inner color=white,outer color=red!80}]
2792 \end{tikzpicture}
2793 \end{marginfigure}
2794
2795 \begin{docspec}
2796 \begin{lstlisting}
2797 \begin{tikzpicture}[multilayer=3d]
2798 \Plane[x=-.5,y=-.5,width=3,height=2.5,style={dashed,inner color=white,outer color=red!80}]
2799 \end{tikzpicture}
2800 \end{lstlisting}
2801 \end{docspec}
2802
2803 \begin{docspecdef}
2804 \doccmd{Plane}[\docopt{layer}=\docarg{number}]
2805 \end{docspecdef}
2806
2807 With the option \docopt{layer}=\docarg{layer $\alpha$}, the position of the plane can be assigned to a specific layer. Per default the plane is drawn on layer $1$.
2808
2809 \newpage
2810 \begin{marginfigure}%[22mm]
2811 \centering
2812 \begin{tikzpicture}[multilayer=3d]
2813 \SetLayerDistance{-1.5}
2814 \Plane[x=-.5,y=-.5,width=3,height=2.5,color=green,layer=2]
2815 \Plane[x=-.5,y=-.5,width=3,height=2.5]
2816 \Text[x=-.5,y=-.5,layer=2,color=orange,anchor=north west,fontsize=\normalsize]{Layer 2}
2817 \Text[x=-.5,y=-.5,layer=1,color=orange,anchor=north west,fontsize=\normalsize]{Layer 2}
2818 \end{tikzpicture}
2819 \end{marginfigure}
2820
2821 \begin{docspec}
2822 \begin{lstlisting}
2823 \begin{tikzpicture}[multilayer=3d]
2824 \SetLayerDistance{-1.5}
2825 \Plane[x=-.5,y=-.5,width=3,height=2.5,color=green,layer=2]
2826 \Plane[x=-.5,y=-.5,width=3,height=2.5]
2827 \end{tikzpicture}
2828 \end{lstlisting}
2829 \end{docspec}
2830
2831 \begin{docspecdef}
2832 \doccmd{Plane}[\docopt{RGB},\docopt{color}=\docarg{RGB values}]
2833 \end{docspecdef}
2834
2835 In order to display RGB colors for the plane fill color, the option \docopt{RGB} has to be entered. In combination with this option, the \docopt{color} hast to be a list with the \docarg{RGB
2836 values}, separated by <<,>> and within $\{~\}$.\footnote{e.g. the RGB code for white: $\{255,255,255\}$}
2837
2838 \begin{marginfigure}
2839 \centering
2840 \begin{tikzpicture}[multilayer=3d]
2841 \Plane[x=-.5,y=-.5,width=3,height=2.5,RGB,color={0,0,0}]
2842 \end{tikzpicture}
2843 \end{marginfigure}
2844
2845 \begin{docspec}
2846 \begin{lstlisting}
2847 \begin{tikzpicture}[multilayer=3d]
2848 \Plane[x=-.5,y=-.5,width=3,height=2.5,RGB,color={0,0,0}]
2849 \end{tikzpicture}
2850 \end{lstlisting}
2851 \end{docspec}
2852
2853
2854 \begin{docspecdef}
2855 \doccmd{Plane}[\docopt{NoFill}]
2856 \end{docspecdef}
2857 \begin{docspecdef}
2858 \doccmd{Plane}[\docopt{NoBorder}]
2859 \end{docspecdef}
2860
2861 \docopt{NoFill} is a Boolean option which disables the fill color of the plane and \docopt{NoBorder} is a Boolean option which suppress the border line of the plane.
2862
2863 \begin{marginfigure}[16mm]
2864 \centering
2865 \begin{tikzpicture}[multilayer=3d]
2866 \SetLayerDistance{-1.5}
2867 \Plane[x=-.5,y=-.5,width=3,height=2.5,layer=2,NoFill]
2868 \Plane[x=-.5,y=-.5,width=3,height=2.5,NoBorder]
2869 \Text[x=-.5,y=-.5,layer=2,color=orange,anchor=north west,fontsize=\normalsize]{Layer 2}
2870 \Text[x=-.5,y=-.5,layer=1,color=orange,anchor=north west,fontsize=\normalsize]{Layer 2}
2871 \end{tikzpicture}
2872 \end{marginfigure}
2873
2874 \begin{docspec}
2875 \begin{lstlisting}
2876 \begin{tikzpicture}[multilayer=3d]
2877 \SetLayerDistance{-1.5}
2878 \Plane[x=-.5,y=-.5,width=3,height=2.5,layer=2,NoFill]
2879 \Plane[x=-.5,y=-.5,width=3,height=2.5,NoBorder]
2880 \end{tikzpicture}
2881 \end{lstlisting}
2882 \end{docspec}
2883
2884 \begin{docspecdef}
2885 \doccmd{Plane}[\docopt{ImageAndFill}]
2886 \end{docspecdef}
2887
2888 With the option \docopt{ImageAndFill} both, image and fill color can be drawn on a plane. The option \docopt{opacity} is applied to both objects.
2889
2890 \begin{marginfigure}[18mm]
2891 \centering
2892 \begin{tikzpicture}[multilayer=3d]
2893 \Plane[x=-.5,y=-.5,width=3,height=2.5,image=data/plane.png,color=red,opacity=.4,ImageAndFill]
2894 \end{tikzpicture}
2895 \end{marginfigure}
2896
2897 \begin{docspec}
2898 \begin{lstlisting}
2899 \begin{tikzpicture}[multilayer=3d]
2900 \Plane[x=-.5,y=-.5,width=3,height=2.5,image=data/plane.png,color=red,opacity=.4,ImageAndFill]
2901 \end{tikzpicture}
2902 \end{lstlisting}
2903 \end{docspec}
2904
2905 \begin{docspecdef}
2906 \doccmd{Plane}[\docopt{InBG}]
2907 \end{docspecdef}
2908
2909 A plane is drawn on the current layer of the \docarg{tikzpicture}. I.e. objects which are created after the plane appear on top of it and objects created before below of it. With the option \docopt{InBG} enabled, the plane is drawn on the background layer of the \docarg{tikzpicture}.
2910
2911 \chapter{Default Settings}
2912 \label{chap:default_settings}
2913
2914 In order to customize the look of the networks, each layout setting used can be modified and adapted. There are three categories: General settings, vertex style, and edge style.
2915
2916 \section{General Settings}
2917 \label{sec:gerneral_settings}
2918
2919 With the general settings mainly the sizes, distances and measures of the networks can be modified.
2920
2921 \begin{docspecdef}
2922 \doccmd{SetDefaultUnit}\{\docarg{unit}\}
2923 \end{docspecdef}
2924
2925 The command \doccmddef{SetDefaultUnit} allows to change the units used for drawing the network\footnote{Except the line width, which are defined in \si{pt}.}, including diameters of the vertices, $x$ and $y$ coordinates or the distance between the layers. The default unit is \si{cm}.
2926
2927 \begin{docspecdef}
2928 \doccmd{SetDistanceScale}\{\docarg{number}\}
2929 \end{docspecdef}
2930
2931 With the command \doccmddef{SetDistanceScale}, the distance between the vertices can be scaled. Per default \SI{1}{cm} entered corresponds to \SI{1}{cm} drawn, i.e. \doccmd{SetDistanceScale}\{1\}. Decreasing or increasing the scale changes the drawing distances between the vertices.
2932
2933 \begin{docspecdef}
2934 \doccmd{SetLayerDistance}\{\docarg{measure}\}
2935 \end{docspecdef}
2936
2937 With the command \doccmddef{SetLayerDistance} the distance between the layers and their orientation can be modified. Per default, the distance is set to $-2$. A negative number implies that layers with a higher number will be stacked below layers with a smaller number.
2938
2939 \begin{docspecdef}
2940 \doccmd{SetCoordinates}[\docopt{xAngle}=\docarg{number},\docopt{yAngle}=\docarg{number},\docopt{zAngle}=\docarg{number}, \docopt{xLength}=\docarg{number},\docopt{yLength}=\docarg{number},\docopt{zLength}=\docarg{number}]
2941 \end{docspecdef}
2942
2943 The perspective of the three-dimensional plot can be modified by changing the orientation of the coordinate system, which is done with the command \doccmddef{SetCoordinates}. Here the angle and the length of each axis can be modified. Angles are defined as a \docarg{number} in the range between $-360$ and $360$. Per default, the length of the axes are defined by the identity matrix, i.e. no distortion. If the length ratio is changed $x$, $y$, and/or $z$ values are distorted. The \doccmd{SetCoordinates} command has to be entered before the \docopt{multilayer} option is called!
2944
2945 \section{Vertex Style}
2946 \label{sec:vertex_style}
2947
2948 The appearance of the vertices can be modified with the command \doccmddef{SetVertexStyle}. This command will change the default settings of the vertices in the network.
2949
2950 \begin{docspecdef}
2951 \doccmd{SetVertexStyle}[\docarg{document options}]
2952 \end{docspecdef}
2953
2954 The following options are available:
2955
2956 \begin{table}[h]\index{Vertex!style}
2957 \footnotesize%
2958 \begin{center}
2959 \begin{tabularx}{\textwidth}{lccX}
2960 \toprule
2961 Option & Default & Type &Definition \\
2962 \midrule
2963 Shape & circle & text & shape of the vertex \\
2964 InnerSep & 2pt & measure & separation space which will be added inside the shape \\
2965 OuterSep & 0pt & measure & separation space outside the background path \\
2966 MinSize & 0.6\doccmd{DefaultUnit} & measure & diameter (size) of the vertex \\
2967 FillColor & vertexfill & color & color of the vertex \\
2968 FillOpacity & 1 & number & opacity of the vertex \\
2969 LineWidth & 1pt & measure & line width of the vertex boundary \\
2970 LineColor & black & color & line color of the vertex boundary \\
2971 LineOpacity & 1 & number & line opacity of the vertex boundary \\
2972 TextFont & \doccmd{scriptsize} & fontsize & font size of the vertex label \\
2973 TextColor & black & color & color of the vertex label \\
2974 TextOpacity & 1 & number & opacity of the vertex label \\
2975 TextRotation & 0 & number & initial rotation of the vertex \\
2976 \bottomrule
2977 \end{tabularx}
2978 \scriptsize
2979 \end{center}
2980 \caption{Document style options for the vertices.}
2981 \label{tab:vertex_style}
2982 \end{table}
2983
2984
2985 \section{Edge Style}
2986 \label{sec:edge_style}
2987
2988 The appearance of the edges can be modified with the command \doccmddef{SetEdgeStyle}. This command will change the default settings of the edges in the network.
2989
2990 \begin{docspecdef}
2991 \doccmd{SetEdgeStyle}[\docarg{document options}]
2992 \end{docspecdef}
2993
2994 The following options are available:
2995
2996 \begin{table}[h]\index{Edge!style}
2997 \footnotesize%
2998 \begin{center}
2999 \begin{tabularx}{\textwidth}{lccX}
3000 \toprule
3001 Option & Default & Type &Definition \\
3002 \midrule
3003 LineWidth & 1.5pt & measure & width of the edge \\
3004 Color & black!75 & color & color of the edge \\
3005 Opacity & 1 & number & opacity of the edge \\
3006 Arrow & -latex & text & arrow shape of the directed edge \\
3007 TextFont & \doccmd{scriptsize} & fontsize & font size of the edge label \\
3008 TextOpacity & 1 & number & opacity of the edge label \\
3009 TextFillColor & white & color & fill color of the edge label \\
3010 TextFillOpacity & 1 & number & fill opacity of the edge label \\
3011 InnerSep & 0pt & measure & separation space which will be added inside the shape \\
3012 OuterSep & 1pt & measure & separation space outside the background path \\
3013 TextRotation & 0 & number & initial rotation of the edge label \\
3014 \bottomrule
3015 \end{tabularx}
3016 \scriptsize
3017 \end{center}
3018 \caption{Document style options for the edges.}
3019 \label{tab:edge_style}
3020 \end{table}
3021
3022 \begin{docspecdef}
3023 \doccmd{EdgesNotInBG}
3024 \end{docspecdef}
3025
3026 \begin{docspecdef}
3027 \doccmd{EdgesInBG}
3028 \end{docspecdef}
3029
3030 Per default edges are drawn on the background layer, with the command \doccmddef{EdgesNotInBG} this can be disabled, while the command \doccmddef{EdgesInBG} restores the default setting.
3031
3032 \section{Text Style}
3033 \label{sec:text_style}
3034
3035 The appearance of the text can be modified with the command \doccmddef{SetTextStyle}. This command will change the default settings of the text.
3036
3037 \begin{docspecdef}
3038 \doccmd{SetTextStyle}[\docarg{document options}]
3039 \end{docspecdef}
3040
3041 The following options are available:
3042
3043 \begin{table}[h]\index{Text!style}
3044 \footnotesize%
3045 \begin{center}
3046 \begin{tabularx}{\textwidth}{lccX}
3047 \toprule
3048 Option & Default & Type &Definition \\
3049 \midrule
3050 TextFont & \doccmd{normalsize} & fontsize & font size of the text \\
3051 TextOpacity & 1 & number & opacity of the text \\
3052 TextColor & black & color & color of the text \\
3053 TextOpacity & 1 & number & opacity of the text \\
3054 InnerSep & 2pt & measure & separation space which will be added inside the shape \\
3055 OuterSep & 0pt & measure & separation space outside the background path \\
3056 TextRotation & 0 & number & initial rotation of the text \\
3057 \bottomrule
3058 \end{tabularx}
3059 \scriptsize
3060 \end{center}
3061 \caption{Document style options for the planes.}
3062 \label{tab:plane_style}
3063 \end{table}
3064
3065
3066 \section{Plane Style}
3067 \label{sec:plane_style}
3068
3069 The appearance of the planes can be modified with the command \doccmddef{SetPlaneStyle}. This command will change the default settings of the planes.
3070
3071 \begin{docspecdef}
3072 \doccmd{SetPlaneStyle}[\docarg{document options}]
3073 \end{docspecdef}
3074
3075 The following options are available:
3076
3077 \begin{table}[h]\index{Plane!style}
3078 \footnotesize%
3079 \begin{center}
3080 \begin{tabularx}{\textwidth}{lccX}
3081 \toprule
3082 Option & Default & Type &Definition \\
3083 \midrule
3084 LineWidth & 1.5pt & measure & width of the border line \\
3085 LineColor & black & color & color of the border line \\
3086 LineOpacity & 1 & number & opacity of the border line \\
3087 FillColor & vertexfill & color & fill color of the plane \\
3088 FillOpacity & 0.3 & number & fill opacity of the plane \\
3089 GridLineWidth & 0.5pt & measure & width of the grid lines \\
3090 GridColor & black & color & color of the grid lines \\
3091 GridOpacity & 0.5 & number & opacity of the grid lines \\
3092 \bottomrule
3093 \end{tabularx}
3094 \scriptsize
3095 \end{center}
3096 \caption{Document style options for the planes.}
3097 \label{tab:plane_style}
3098 \end{table}
3099
3100 \begin{docspecdef}
3101 \doccmd{SetPlaneWidth}\{\docarg{measure}\}
3102 \end{docspecdef}
3103 \begin{docspecdef}
3104 \doccmd{SetPlaneHeight}\{\docarg{measure}\}
3105 \end{docspecdef}
3106
3107 With the commands \doccmd{SetPlaneWidth} and \doccmd{SetPlaneHeight} the default size of the planes can be modified.
3108
3109
3110
3111
3112 \chapter{Troubleshooting and Support}
3113 \label{chap:troubleshooting}
3114
3115 \section{\pkg Website}\label{sec:website}
3116 The website for the \pkg packages is located at
3117 \url{https://github.com/hackl/tikz-network}. There, you'll find the actual version of the source code, a bug tracker, and the documentation.
3118
3119 \section{Getting Help}\label{sec:getting-help}
3120 If you've encountered a problem with one of the \pkg commands, have a
3121 question, or would like to report a bug, please send an email to me or visit our website.
3122
3123 To help me troubleshoot the problem more quickly, please try to compile your
3124 document using the \docclsopt{debug} class option and send the generated
3125 \texttt{.log} file to the mailing list with a brief description of the problem.
3126
3127
3128 \section{Errors, Warnings, and Informational Messages}\label{sec:tl-messages}
3129 The following is a list of all of the errors, warnings, and other messages generated by the \pkg classes and a brief description of their meanings.
3130 \index{error messages}\index{warning messages}\index{debug messages}
3131
3132 % Errors
3133 \docmsg{Error: ! TeX capacity exceeded, sorry [main memory size=5000000].}{%
3134 The considered network is to large and \texttt{pdflatex} runs out of memory. This problem can be solved by using \texttt{lualatex} or \texttt{xetex} instead.}
3135
3136 \section{Package Dependencies}\label{sec:dependencies}
3137 The following is a list of packages that the \pkg package rely upon. Packages marked with an asterisk are optional.
3138 \begin{multicols}{2}
3139 \begin{itemize}
3140 \item etex
3141 \item xifthen
3142 \item xkeyval
3143 \item datatool
3144 \item tikz
3145 \begin{itemize}
3146 \item arrows
3147 \item positioning
3148 \item 3d
3149 \item fit
3150 \item calc
3151 \item backgrounds
3152 \end{itemize}
3153 \end{itemize}
3154 \end{multicols}
3155
3156 \appendix
3157 \chapter{ToDo}
3158 \label{chap:todo}
3159
3160 \section{Code to fix}
3161 \begin{itemize}
3162 \item change default entries for Boolean options in the vertices file.
3163 \end{itemize}
3164
3165 \section{Documentation}
3166 \begin{itemize}
3167 \item add indices to the manual.
3168 \item extended tutorial/example to the document.
3169 \item clean-up and document the .sty file.
3170 \end{itemize}
3171
3172 \section{Features}
3173 \begin{itemize}
3174 \item add a spherical coordinate system
3175 \end{itemize}
3176
3177 \section{Add-ons}
3178 \begin{itemize}
3179 \item add QGIS to tikz-network compiler
3180 \end{itemize}
3181
3182
3183 \chapter{Add-ons}
3184 \label{chap:todo}
3185
3186 \section{Python networks to \tikzsym with network2tikz}
3187 \label{sec:python_to_tikz}
3188
3189 \subsection{Introduction}
3190
3191 \texttt{\href{https://github.com/hackl/network2tikz}{network2tikz}} is a Python tool for converting network visualizations into \pkg figures, for native inclusion into your LaTeX documents.
3192
3193 \texttt{network2tikz} works with Python 3 and supports (currently) the following Python network modules:
3194
3195 \begin{itemize}
3196 \item \texttt{\href{https://github.com/hackl/cnet}{cnet}}
3197 \item \texttt{\href{http://igraph.org/python/}{python-igraph}}
3198 \item \texttt{\href{https://networkx.github.io/}{networkx}}
3199 \item \texttt{\href{https://github.com/IngoScholtes/pathpy}{pathpy}}
3200 \item default node/edge lists
3201 \end{itemize}
3202
3203 The output of \texttt{network2tikz} is a \pkg figure. Because you are not only getting an image of your network, but also the LaTeX source file, you can easily post-process the figures (e.g. adding drawings, texts, equations,...).
3204
3205 Since \textit{a picture is worth a thousand words} a small example:
3206
3207 \begin{marginfigure}[65mm]
3208 \centering
3209 \begin{tikzpicture}[scale=.8]
3210 %\clip (0,0) rectangle (6,6);
3211 \Vertex[x=0.785,y=2.375,color=red,opacity=0.5,label=Alice]{a}
3212 \Vertex[x=5.215,y=5.650,color=blue,opacity=0.5,label=Bob]{b}
3213 \Vertex[x=3.819,y=0.350,color=red,opacity=0.5,label=Claire]{c}
3214 \Vertex[x=4.654,y=2.051,color=blue,opacity=0.5,label=Dennis]{d}
3215 \Edge[,bend=-8.531](a)(c)
3216 \Edge[,bend=-8.531](c)(d)
3217 \Edge[,bend=-8.531](d)(b)
3218 \Edge[,bend=-8.531](a)(b)
3219 \end{tikzpicture}
3220 \end{marginfigure}
3221
3222 \begin{docspeca}
3223 \begin{lstlisting}
3224 #!/usr/bin/python -tt
3225 # -*- coding: utf-8 -*-
3226
3227 nodes = ['a','b','c','d']
3228 edges = [('a','b'), ('a','c'), ('c','d'),('d','b')]
3229 gender = ['f', 'm', 'f', 'm']
3230 colors = {'m': 'blue', 'f': 'red'}
3231
3232 style = {}
3233 style['node_label'] = ['Alice', 'Bob', 'Claire', 'Dennis']
3234 style['node_color'] = [colors[g] for g in gender]
3235 style['node_opacity'] = .5
3236 style['edge_curved'] = .1
3237
3238 from network2tikz import plot
3239 plot((nodes,edges),'network.tex',**style)
3240 \end{lstlisting}
3241 \end{docspeca}
3242
3243 (see above) gives
3244
3245 \begin{docspeca}
3246 \begin{lstlisting}
3247 \documentclass{standalone}
3248 \usepackage{tikz-network}
3249 \begin{document}
3250 \begin{tikzpicture}
3251 \clip (0,0) rectangle (6,6);
3252 \Vertex[x=0.785,y=2.375,color=red,opacity=0.5,label=Alice]{a}
3253 \Vertex[x=5.215,y=5.650,color=blue,opacity=0.5,label=Bob]{b}
3254 \Vertex[x=3.819,y=0.350,color=red,opacity=0.5,label=Claire]{c}
3255 \Vertex[x=4.654,y=2.051,color=blue,opacity=0.5,label=Dennis]{d}
3256 \Edge[,bend=-8.531](a)(c)
3257 \Edge[,bend=-8.531](c)(d)
3258 \Edge[,bend=-8.531](d)(b)
3259 \Edge[,bend=-8.531](a)(b)
3260 \end{tikzpicture}
3261 \end{document}
3262 \end{lstlisting}
3263 \end{docspeca}
3264
3265 Tweaking the plot is straightforward and can be done as part of your LaTeX workflow.
3266
3267
3268 \subsection{Installation}
3269
3270 \texttt{network2tikz} is available from the \href{https://pypi.org/project/network2tikz/}{Python Package Index}, so simply type
3271
3272 \begin{docspeca}
3273 \begin{lstlisting}
3274 pip install -U network2tikz
3275 \end{lstlisting}
3276 \end{docspeca}
3277
3278 to install/update. If your are intersted in the development version of the module check out the \href{https://github.com/hackl/network2tikz}{github repository}.
3279
3280 \subsection{Usage}
3281
3282 \begin{enumerate}
3283 \item Generate, manipulation, and study of the structure, dynamics, and functions of your complex networks as usual, with your preferred python module.
3284
3285 \item Instead of the default plot functions (e.g. \texttt{igraph.plot()} or \texttt{networkx.draw()}) invoke \texttt{network2tikz} by
3286
3287 \begin{docspeca}
3288 \begin{lstlisting}
3289 plot(G,'mytikz.tex')
3290 \end{lstlisting}
3291 \end{docspeca}
3292
3293 to store your network visualisation as the TikZ file \texttt{mytikz.tex}. Load the module with:
3294
3295 \begin{docspeca}
3296 \begin{lstlisting}
3297 from network2tikz import plot
3298 \end{lstlisting}
3299 \end{docspeca}
3300
3301 \textbf{Advanced usage:}
3302
3303 Of course, you always can improve your plot by manipulating the generated LaTeX file, but why not do it directly in Python? To do so, all visualization options available in \pkg are also implemented in \texttt{network2tikz}. The appearance of the plot can be modified by keyword arguments.\footnote{For a detailed explanation, please see Section \ref{sec:plot_function}.}
3304
3305 \begin{docspeca}
3306 \begin{lstlisting}
3307 my_style = {}
3308 plot(G,'mytikz.tex',**my_style)
3309 \end{lstlisting}
3310 \end{docspeca}
3311
3312 The arguments follow the options described above in the manual.
3313
3314 Additionally, if you are more interested in the final output and not only the \texttt{.tex} file, used
3315
3316 \begin{docspeca}
3317 \begin{lstlisting}
3318 plot(G,'mypdf.pdf')
3319 \end{lstlisting}
3320 \end{docspeca}
3321
3322 to save your plot as a pdf, or
3323
3324 \begin{docspeca}
3325 \begin{lstlisting}
3326 plot(G)
3327 \end{lstlisting}
3328 \end{docspeca}
3329
3330 to create a temporal plot and directly show the result, i.e. similar to the matplotlib function \texttt{show()}. Finally, you can also create a node and edge list, which can be read and easily modified (in a post-processing step) as showd above.
3331
3332 \begin{docspeca}
3333 \begin{lstlisting}
3334 plot(G,'mycsv.csv')
3335 \end{lstlisting}
3336 \end{docspeca}
3337
3338 \item Compile the figure or add the contents of \texttt{mytikz.tex} into your LaTeX source code. With the option \docopt{standalone}=\docarg{false} only the \tikzsym figure will be saved, which can then be easily included in your \LaTeX~ document via \doccmd{input}\{\texttt{/path/to/mytikz.tex}\}.
3339
3340 \subsection{Simple example}
3341
3342 For illustration purpose, a similar network as in the \href{http://igraph.org/python/doc/tutorial/tutorial.html}{python-igraph tutorial} is used. If you are using another Python network module, and like to follow this example, please have a look at the \href{https://github.com/hackl/network2tikz/tree/master/examples}{provided examples}.
3343
3344 \end{enumerate}
3345
3346
3347 Create network object and add some edges.
3348
3349 \begin{docspeca}
3350 \begin{lstlisting}
3351 #!/usr/bin/python -tt
3352 # -*- coding: utf-8 -*-
3353
3354 import igraph
3355 from network2tikz import plot
3356
3357 net = igraph.Graph([(0,1), (0,2), (2,3), (3,4), (4,2), (2,5), (5,0), (6,3),
3358 (5,6), (6,6)],directed=True)
3359 \end{lstlisting}
3360 \end{docspeca}
3361
3362 Adding node and edge properties.
3363
3364 \begin{docspeca}
3365 \begin{lstlisting}
3366 net.vs["name"] = ["Alice", "Bob", "Claire", "Dennis", "Esther", "Frank", "George"]
3367 net.vs["age"] = [25, 31, 18, 47, 22, 23, 50]
3368 net.vs["gender"] = ["f", "m", "f", "m", "f", "m", "m"]
3369 net.es["is_formal"] = [False, False, True, True, True, False, True, False,
3370 False, False]
3371 \end{lstlisting}
3372 \end{docspeca}
3373
3374 Already now the network can be plotted.
3375 \begin{marginfigure}[5mm]
3376 \centering
3377 \begin{tikzpicture}[scale=.8]
3378 %\clip (0,0) rectangle (6,6);
3379 \Vertex[x=3.629,y=0.350]{a}
3380 \Vertex[x=3.449,y=5.457]{b}
3381 \Vertex[x=2.647,y=5.650]{c}
3382 \Vertex[x=1.013,y=3.477]{d}
3383 \Vertex[x=4.987,y=2.834]{e}
3384 \Vertex[x=4.490,y=5.182]{f}
3385 \Vertex[x=2.808,y=4.470]{g}
3386 \Edge[](a)(b)
3387 \Edge[](a)(c)
3388 \Edge[](c)(d)
3389 \Edge[](d)(e)
3390 \Edge[](e)(c)
3391 \Edge[](c)(f)
3392 \Edge[](f)(a)
3393 \Edge[](f)(g)
3394 \Edge[](g)(d)
3395 \Edge[](g)(g)
3396 \end{tikzpicture}
3397 \end{marginfigure}
3398
3399 \begin{docspeca}
3400 \begin{lstlisting}
3401 plot(net)
3402 \end{lstlisting}
3403 \end{docspeca}
3404
3405 Per default, the node positions are assigned uniform random. In order to create a layout, the layout methods of the network packages can be used. Or the position of the nodes can be directly assigned, in form of a dictionary, where the key is the node id and the value is a tuple of the node position in $x$ and $y$.
3406
3407 \begin{docspeca}
3408 \begin{lstlisting}
3409 layout = {0: (4.3191, -3.5352), 1: (0.5292, -0.5292),
3410 2: (8.6559, -3.8008), 3: (12.4117, -7.5239),
3411 4: (12.7, -1.7069), 5: (6.0022, -9.0323),
3412 6: (9.7608, -12.7)}
3413 plot(net,layout=layout)
3414 \end{lstlisting}
3415 \end{docspeca}
3416
3417 \begin{marginfigure}[5mm]
3418 \centering
3419 \begin{tikzpicture}[scale=.8]
3420 \clip (0,0) rectangle (6,6);
3421 \Vertex[x=2.000,y=4.341]{a}
3422 \Vertex[x=0.350,y=5.650]{b}
3423 \Vertex[x=3.889,y=4.225]{c}
3424 \Vertex[x=5.524,y=2.604]{d}
3425 \Vertex[x=5.650,y=5.137]{e}
3426 \Vertex[x=2.733,y=1.947]{f}
3427 \Vertex[x=4.370,y=0.350]{g}
3428 \Edge[](a)(b)
3429 \Edge[](a)(c)
3430 \Edge[](c)(d)
3431 \Edge[](d)(e)
3432 \Edge[](e)(c)
3433 \Edge[](c)(f)
3434 \Edge[](f)(a)
3435 \Edge[](f)(g)
3436 \Edge[](g)(d)
3437 \Edge[](g)(g)
3438 \end{tikzpicture}
3439 \end{marginfigure}
3440
3441
3442 This should open an external pdf viewer showing a visual representation of the network, something like the one on the following figure:
3443
3444 We can simply re-using the previous layout object here, but we also specified that we need a bigger plot ($8 \times 8$ cm) and a larger margin around the graph to fit the self loop and potential labels (1 cm).\footnote{Per default, all size values are based on cm, and all line widths are defined in pt units. With the general option \docopt{units} this can be changed, see Section \ref{sec:plot_function}.}
3445
3446 \begin{docspeca}
3447 \begin{lstlisting}
3448 plot(net, layout=layout, canvas=(8,8), margin=1)
3449 \end{lstlisting}
3450 \end{docspeca}
3451
3452 \begin{marginfigure}[5mm]
3453 \centering
3454 \begin{tikzpicture}[scale=.8]
3455 %\clip (0,0) rectangle (8.0,8.0);
3456 \Vertex[x=2.868,y=5.518]{a}
3457 \Vertex[x=1.000,y=7.000]{b}
3458 \Vertex[x=5.006,y=5.387]{c}
3459 \Vertex[x=6.858,y=3.552]{d}
3460 \Vertex[x=7.000,y=6.419]{e}
3461 \Vertex[x=3.698,y=2.808]{f}
3462 \Vertex[x=5.551,y=1.000]{g}
3463 \Edge[](a)(b)
3464 \Edge[](a)(c)
3465 \Edge[](c)(d)
3466 \Edge[](d)(e)
3467 \Edge[](e)(c)
3468 \Edge[](c)(f)
3469 \Edge[](f)(a)
3470 \Edge[](f)(g)
3471 \Edge[](g)(d)
3472 \Edge[](g)(g)
3473 \end{tikzpicture}
3474 \end{marginfigure}
3475
3476 In to keep the properties of the visual representation of your network separate from the network itself. You can simply set up a Python dictionary containing the keyword arguments you would pass to \texttt{plot} and then use the double asterisk (\texttt{**}) operator to pass your specific styling attributes to \texttt{plot}:
3477
3478 \begin{docspeca}
3479 \begin{lstlisting}
3480 color_dict = {'m': 'blue', 'f': 'red'}
3481 visual_style = {}
3482
3483 # Node options
3484 visual_style['vertex_size'] = .5
3485 visual_style['vertex_color'] = [color_dict[g] for g in net.vs['gender']]
3486 visual_style['vertex_opacity'] = .7
3487 visual_style['vertex_label'] = net.vs['name']
3488 visual_style['vertex_label_position'] = 'below'
3489
3490 # Edge options
3491 visual_style['edge_width'] = [1 + 2 * int(f) for f in net.es('is_formal')]
3492 visual_style['edge_curved'] = 0.1
3493
3494 # General options and plot command.
3495 visual_style['layout'] = layout
3496 visual_style['canvas'] = (8,8)
3497 visual_style['margin'] = 1
3498
3499 # Plot command
3500 plot(net,**visual_style)
3501 \end{lstlisting}
3502 \end{docspeca}
3503
3504 \begin{marginfigure}[5mm]
3505 \centering
3506 \begin{tikzpicture}[scale=.8]
3507 %\clip (0,0) rectangle (8.0,8.0);
3508 \Vertex[x=2.868,y=5.518,size=0.5,color=red,opacity=0.7,label=Alice,position=below]{a}
3509 \Vertex[x=1.000,y=7.000,size=0.5,color=blue,opacity=0.7,label=Bob,position=below]{b}
3510 \Vertex[x=5.006,y=5.387,size=0.5,color=red,opacity=0.7,label=Claire,position=below]{c}
3511 \Vertex[x=6.858,y=3.552,size=0.5,color=blue,opacity=0.7,label=Dennis,position=below]{d}
3512 \Vertex[x=7.000,y=6.419,size=0.5,color=red,opacity=0.7,label=Esther,position=below]{e}
3513 \Vertex[x=3.698,y=2.808,size=0.5,color=blue,opacity=0.7,label=Frank,position=below]{f}
3514 \Vertex[x=5.551,y=1.000,size=0.5,color=blue,opacity=0.7,label=George,position=below]{g}
3515 \Edge[,lw=1.0,bend=-8.531,Direct](a)(b)
3516 \Edge[,lw=1.0,bend=-8.531,Direct](a)(c)
3517 \Edge[,lw=3.0,bend=-8.531,Direct](c)(d)
3518 \Edge[,lw=3.0,bend=-8.531,Direct](d)(e)
3519 \Edge[,lw=3.0,bend=-8.531,Direct](e)(c)
3520 \Edge[,lw=1.0,bend=-8.531,Direct](c)(f)
3521 \Edge[,lw=3.0,bend=-8.531,Direct](f)(a)
3522 \Edge[,lw=1.0,bend=-8.531,Direct](f)(g)
3523 \Edge[,lw=1.0,bend=-8.531,Direct](g)(g)
3524 \Edge[,lw=1.0,bend=-8.531,Direct](g)(d)
3525 \end{tikzpicture}
3526 \end{marginfigure}
3527
3528
3529 Beside showing the network, we can also generate the latex source file, which can be used and modified later on. This is done by adding the output file name with the ending \texttt{'.tex'}.
3530
3531
3532 \begin{docspeca}
3533 \begin{lstlisting}
3534 plot(net,'network.tex',**visual_style)
3535 \end{lstlisting}
3536 \end{docspeca}
3537
3538 produces
3539
3540 \begin{fullwidth}
3541 \begin{minipage}{17cm}
3542 \begin{docspeca}
3543 \begin{lstlisting}
3544 \documentclass{standalone}
3545 \usepackage{tikz-network}
3546 \begin{document}
3547 \begin{tikzpicture}
3548 \clip (0,0) rectangle (8.0,8.0);
3549 \Vertex[x=2.868,y=5.518,size=0.5,color=red,opacity=0.7,label=Alice,position=below]{a}
3550 \Vertex[x=1.000,y=7.000,size=0.5,color=blue,opacity=0.7,label=Bob,position=below]{b}
3551 \Vertex[x=5.006,y=5.387,size=0.5,color=red,opacity=0.7,label=Claire,position=below]{c}
3552 \Vertex[x=6.858,y=3.552,size=0.5,color=blue,opacity=0.7,label=Dennis,position=below]{d}
3553 \Vertex[x=7.000,y=6.419,size=0.5,color=red,opacity=0.7,label=Esther,position=below]{e}
3554 \Vertex[x=3.698,y=2.808,size=0.5,color=blue,opacity=0.7,label=Frank,position=below]{f}
3555 \Vertex[x=5.551,y=1.000,size=0.5,color=blue,opacity=0.7,label=George,position=below]{g}
3556 \Edge[,lw=1.0,bend=-8.531,Direct](a)(b)
3557 \Edge[,lw=1.0,bend=-8.531,Direct](a)(c)
3558 \Edge[,lw=3.0,bend=-8.531,Direct](c)(d)
3559 \Edge[,lw=3.0,bend=-8.531,Direct](d)(e)
3560 \Edge[,lw=3.0,bend=-8.531,Direct](e)(c)
3561 \Edge[,lw=1.0,bend=-8.531,Direct](c)(f)
3562 \Edge[,lw=3.0,bend=-8.531,Direct](f)(a)
3563 \Edge[,lw=1.0,bend=-8.531,Direct](f)(g)
3564 \Edge[,lw=1.0,bend=-8.531,Direct](g)(g)
3565 \Edge[,lw=1.0,bend=-8.531,Direct](g)(d)
3566 \end{tikzpicture}
3567 \end{document}
3568 \end{lstlisting}
3569 \end{docspeca}
3570 \end{minipage}
3571 \end{fullwidth}
3572
3573 Instead of the tex file, a node and edge list can be generates, which can also be used with the library.
3574
3575
3576 \begin{docspeca}
3577 \begin{lstlisting}
3578 plot(net,'network.csv',**visual_style)
3579 \end{lstlisting}
3580 \end{docspeca}
3581
3582 The node list \texttt{network\_nodes.csv}.
3583
3584 \begin{docspeca}
3585 \begin{lstlisting}
3586 id,x,y,size,color,opacity,label,position
3587 a,2.868,5.518,0.5,red,0.7,Alice,below
3588 b,1.000,7.000,0.5,blue,0.7,Bob,below
3589 c,5.006,5.387,0.5,red,0.7,Claire,below
3590 d,6.858,3.552,0.5,blue,0.7,Dennis,below
3591 e,7.000,6.419,0.5,red,0.7,Esther,below
3592 f,3.698,2.808,0.5,blue,0.7,Frank,below
3593 g,5.551,1.000,0.5,blue,0.7,George,below
3594 \end{lstlisting}
3595 \end{docspeca}
3596
3597 The edge list \texttt{network\_edges.csv}.
3598
3599 \begin{docspeca}
3600 \begin{lstlisting}
3601 u,v,lw,bend,Direct
3602 a,b,1.0,-8.531,true
3603 a,c,1.0,-8.531,true
3604 c,d,3.0,-8.531,true
3605 d,e,3.0,-8.531,true
3606 e,c,3.0,-8.531,true
3607 c,f,1.0,-8.531,true
3608 f,a,3.0,-8.531,true
3609 f,g,1.0,-8.531,true
3610 g,g,1.0,-8.531,true
3611 g,d,1.0,-8.531,true
3612 \end{lstlisting}
3613 \end{docspeca}
3614
3615 \subsection{The plot function in detail}
3616 \label{sec:plot_function}
3617
3618 \begin{docspecdef}
3619 \texttt{network2tikz.plot}(\docarg{network}, \docopt{filename}=\docarg{None}, \docopt{type}= \docarg{None}, \docopt{**kwds})
3620 \end{docspecdef}
3621
3622 \textbf{Parameters}
3623
3624 \begin{description}
3625 \item[network] : network object
3626
3627 Network to be drawn. The network can be a \texttt{cnet}, \texttt{networkx}, \texttt{igraph}, \texttt{pathpy} object, or a tuple of a node list and edge list.
3628
3629 \item[filename] : file, string or None, optional (default = None)
3630
3631 File or filename to save. The file ending specifies the output. i.e. is the file ending with \texttt{.tex} a tex file will be created; if the file ends with '.pdf' a pdf is created; if the file ends with \texttt{.csv}, two csv files are generated \texttt{filename\_nodes.csv} and \texttt{filename\_edges.csv}. If the filename is a tuple of strings, the first entry will be used to name the node list and the second entry for the edge list; and if no ending and no type is defined a temporary pdf file is compiled and shown.
3632
3633 \item[type] : str or None, optional (default = None)
3634
3635 Type of the output file. If no ending is defined trough the filename, the type of the output file can be specified by the type option. Currently the following output types are supported: \texttt{'tex'}, \texttt{'pdf'}, \texttt{'csv'} and \texttt{'dat'}.
3636
3637 \item[kwds] : keyword arguments, optional (default= no attributes)
3638
3639 Attributes used to modify the appearance of the plot. For details see below.
3640
3641 \end{description}
3642
3643 \textbf{Keyword arguments for node styles}
3644
3645 \begin{description}
3646 \item[node\_size] : size of the node. The default is 0.6 cm.
3647
3648 \item[node\_color] : color of the nodes. The default is light blue. Colors can
3649 be specified either by common color names, or by 3-tuples of floats
3650 (ranging between 0 and 255 for the R, G and B components).
3651
3652 \item[node\_opacity] : opacity of the nodes. The default is 1. The range of the
3653 number lies between 0 and 1. Where 0 represents a fully transparent fill
3654 and 1 a solid fill.
3655
3656 \item[node\_label] : labels drawn next to the nodes.
3657
3658 \item[node\_label\_position] : Per default the position of the label is in the
3659 center of the node. Classical \tikzsym commands can be used to change the
3660 position of the label. Instead, using such command, the position can be
3661 determined via an angle, by entering a number between -360 and 360. The
3662 origin (0) is the $y$ axis. A positive number change the position counter
3663 clockwise, while a negative number make changes clockwise.
3664
3665 \item[node\_label\_distance] : distance between the node and the label.
3666
3667 \item[node\_label\_color] : color of the label.
3668
3669 \item[node\_label\_size] : font size of the label.
3670
3671 \item[node\_shape] : shape of the vertices. Possibilities are:
3672 'circle', 'rectangle', 'triangle', and any other Tikz shape
3673
3674 \item[node\_style] : Any other Tikz style option or command can be entered via
3675 the option style. Most of these commands can be found in the "TikZ and
3676 PGF Manual". Contain the commands additional options (e.g. shading =
3677 ball), then the argument for the style has to be between \{ \} brackets.
3678
3679 \item[node\_layer] : the node can be assigned to a specific layer.
3680
3681 \item[node\_label\_off] : is Boolean option which suppress all labels.
3682
3683 \item[node\_label\_as\_id] : is a Boolean option which assigns the node id as label.
3684
3685 \item[node\_math\_mode] : is a Boolean option which transforms the labels into
3686 mathematical expressions without using the \$ \$ environment.
3687
3688 \item[node\_pseudo] : is a Boolean option which creates a pseudo node, where only
3689 the node name and the node coordinate will be provided.
3690 \end{description}
3691
3692 \textbf{Keyword arguments for edge styles}
3693
3694 \begin{description}
3695 \item[edge\_width] : width of the edges. The default unit is point (pt).
3696
3697 \item[edge\_color] : color of the edges. The default is gray. Colors can
3698 be specified either by common color names, or by 3-tuples of floats
3699 (ranging between 0 and 255 for the R, G and B components).
3700
3701 \item[edge\_opacity] : opacity of the edges. The default is 1. The range of the
3702 number lies between 0 and 1. Where 0 represents a fully transparent fill
3703 and 1 a solid fill.
3704
3705 \item[edge\_curved] : whether the edges should be curved. Positive numbers
3706 correspond to edges curved in a counter-clockwise direction, negative
3707 numbers correspond to edges curved in a clockwise direction. Zero
3708 represents straight edges.
3709
3710 \item[edge\_label] : labels drawn next to the edges.
3711
3712 \item[edge\_label\_position] : Per default the label is positioned in between
3713 both nodes in the center of the line. Classical Tikz commands can be used to
3714 change the position of the label.
3715
3716 \item[edge\_label\_distance] : The label position between the nodes can be
3717 modified with the distance option. Per default the label is centered
3718 between both nodes. The position is expressed as the percentage of the
3719 length between the nodes, e.g. of distance = 0.7, the label is placed at
3720 70\% of the edge length away of Vertex i.
3721
3722 \item[edge\_label\_color] : color of the label.
3723
3724 \item[edge\_label\_size] : font size of the label.
3725
3726 \item[edge\_style] : Any other Tikz style option or command can be entered via
3727 the option style. Most of these commands can be found in the "TikZ and
3728 PGF Manual". Contain the commands additional options (e.g. shading =
3729 ball), then the argument for the style has to be between \{ \} brackets.
3730
3731 \item[edge\_arrow\_size] : arrow size of the edges.
3732
3733 \item[edge\_arrow\_width] : width of the arrowhead on the edge.
3734
3735 \item[edge\_loop\_size] : modifies the length of the edge. The measure value has
3736 to be insert together with its units. Per default the loop size is 1 cm.
3737
3738 \item[edge\_loop\_position] : The position of the self-loop is defined via the
3739 rotation angle around the node. The origin (0) is the y axis. A positive
3740 number change the loop position counter clockwise, while a negative
3741 number make changes clockwise.
3742
3743 \item[edge\_loop\_shape] : The shape of the self-loop is defined by the enclosing
3744 angle. The shape can be changed by decreasing or increasing the argument
3745 value of the loop shape option.
3746
3747 \item[edge\_directed] : is a Boolean option which transform edges to directed
3748 arrows. If the network is already defined as directed network this option
3749 is not needed, except to turn off the direction for one or more edges.
3750
3751 \item[edge\_math\_mode] : is a Boolean option which transforms the labels into
3752 mathematical expressions without using the \$ \$ environment.
3753
3754 \item[edge\_not\_in\_bg] : Per default, the edge is drawn on the background layer
3755 of the tikz picture. I.e. objects which are created after the edges
3756 appear also on top of them. To turn this off, the option edge\_not\_in\_bg
3757 has to be enabled.
3758
3759 \end{description}
3760
3761 \textbf{Keyword arguments for layout styles}
3762
3763 \begin{description}
3764 \item[layout] : dict or string, optional (default = None)
3765 A dictionary with the node positions on a 2-dimensional plane. The
3766 key value of the dict represents the node id while the value
3767 represents a tuple of coordinates (e.g. n = (x,y)). The initial
3768 layout can be placed anywhere on the 2-dimensional plane.
3769
3770 Instead of a dictionary, the algorithm used for the layout can be defined
3771 via a string value. Currently, supported are:
3772
3773 \begin{description}
3774 \item[Random layout], where the nodes are uniformly at random placed in the
3775 unit square. This algorithm can be enabled with the keywords:
3776 ``Random'', ``random'', ``rand'', or \texttt{None}.
3777
3778 \item[Fruchterman-Reingold force-directed algorithm]. In this algorithm, the
3779 nodes are represented by steel rings and the edges are springs between
3780 them. The attractive force is analogous to the spring force and the
3781 repulsive force is analogous to the electrical force. The basic idea is
3782 to minimize the energy of the system by moving the nodes and changing
3783 the forces between them. This algorithm can be enabled with the
3784 keywords: ``Fruchterman-Reingold'', ``fruchterman\_reingold'', ``fr'',
3785 ``spring\_layout'', ``spring layout'', ``FR''.
3786
3787 \end{description}
3788
3789 \begin{table}[h]
3790 \footnotesize%
3791 \begin{center}
3792 \begin{tabular}{ll}
3793 \toprule
3794 Keys & Other valid keys \\
3795 \midrule
3796 Random & Random, random, rand, None \\
3797 Fruchterman-Reingold & Fruchterman-Reingold, fruchterman\_reingold, fr \\
3798 & spring\_layout, spring layout, FR \\
3799 \bottomrule
3800 \end{tabular}
3801 \scriptsize
3802 \end{center}
3803 \caption{Algorithms keyword naming convention.}
3804 \label{tab:algo_keywords}
3805 \end{table}
3806
3807 \item[force] : float, optional (default = None)
3808 Optimal distance between nodes. If None the distance is set to
3809 $1/\sqrt{n}$ where $n$ is the number of nodes. Increase this value to move
3810 nodes farther apart.
3811
3812 \item[positions] : dict or None optional (default = None)
3813 Initial positions for nodes as a dictionary with node as keys and values
3814 as a coordinate list or tuple. If None, then use random initial
3815 positions.
3816
3817 \item[fixed] : list or None, optional (default = None)
3818 Nodes to keep fixed at initial position.
3819
3820 \item[iterations] : int, optional (default = 50)
3821 Maximum number of iterations taken
3822
3823 \item[threshold]: float, optional (default = 1e-4)
3824 Threshold for relative error in node position changes. The iteration
3825 stops if the error is below this threshold.
3826
3827 \item[weight] : string or None, optional (default = None)
3828 The edge attribute that holds the numerical value used for the edge
3829 weight. If None, then all edge weights are 1.
3830
3831 \item[dimension] : int, optional (default = 2)
3832 Dimension of layout. Currently, only plots in 2 dimension are supported.
3833
3834 \item[seed] : int or None, optional (default = None)
3835 Set the random state for deterministic node layouts. If int, \texttt{seed} is
3836 the seed used by the random number generator, if None, the a random seed
3837 by created by the numpy random number generator is used.
3838 \end{description}
3839
3840 \textbf{Keyword arguments for general options}
3841
3842 \begin{description}
3843 \item[units] : string or tuple of strings, optional (default = ('cm','pt'))
3844 Per default, all size values are based on cm, and all line widths are
3845 defined in pt units. Whit this option the input units can be
3846 changed. Currently supported are: Pixel 'px', Points 'pt',
3847 Millimeters 'mm', and Centimeters 'cm'. If a single value is entered as
3848 unit all inputs have to be defined using this unit. If a tuple of units
3849 is given, the sizes are defined with the first entry the line widths with
3850 the second entry.
3851
3852 \item[layout] : dict
3853 A dictionary with the node positions on a 2-dimensional plane. The
3854 key value of the dict represents the node id while the value
3855 represents a tuple of coordinates (e.g. n = (x,y)). The initial
3856 layout can be placed anywhere on the 2-dimensional plane.
3857
3858 \item[margins] : None, int, float or dict, optional (default = None)
3859 The margins define the 'empty' space from the canvas border. If no
3860 margins are defined, the margin will be calculated based on the maximum
3861 node size, to avoid clipping of the nodes. If a single int or float is
3862 defined all margins using this distances. To define different the margin
3863 sizes for all size a dictionary with in the form of
3864 \texttt{\{'top':2,'left':1,'bottom':2,'right':.5\}} has to be used.
3865
3866 \item[canvas] : None, tuple of int or floats, optional (default = (6,6))
3867 Canvas or figure\_size defines the size of the plot. The values entered as
3868 a tuple of numbers where the first number is width of the figure and the
3869 second number is the height of the figure. If the option \texttt{units} is not
3870 used the size is specified in cm. Per default the canvas is $6 \times 6$ cm.
3871
3872 \item[keep\_aspect\_ratio] : bool, optional (default = True)
3873 Defines whether to keep the aspect ratio of the current layout. If
3874 \texttt{False}, the layout will be rescaled to fit exactly into the
3875 available area in the canvas (i.e. removed margins). If \texttt{True}, the
3876 original aspect ratio of the layout will be kept and it will be
3877 centered within the canvas.
3878
3879 \item[standalone] : bool, optional (default = True)
3880 If this option is true, a standalone latex file will be created. i.e. the
3881 figure can be compiled from this output file. If standalone is false,
3882 only the tikz environment is stored in the tex file, and can be imported
3883 in an existing tex file.
3884
3885 \item[clean] : bool, optional (default = True)
3886 Whether non-pdf files created that are created during compilation should
3887 be removed.
3888
3889 \item[clean\_tex] : bool, optional (default = True)
3890 Also remove the generated tex file.
3891
3892 \item[compiler] : str or None, optional (default = None)
3893 The name of the LaTeX compiler to use. If it is None, cnet will choose a
3894 fitting one on its own. Starting with \texttt{latexmk} and then \texttt{pdflatex}.
3895
3896 \item[compiler\_args] : list or None, optional (default = None)
3897 Extra arguments that should be passed to the LaTeX compiler. If this is
3898 None it defaults to an empty list.
3899
3900 \item[silent] : bool, optional (default = True)
3901 Whether to hide compiler output or not.
3902
3903 \end{description}
3904
3905 \textbf{Keyword naming convention}
3906
3907 In the style dictionary multiple keywords can be used to address attributes. These keywords will be converted to an unique key word, used in the remaining code. This allows to keep the keywords used in \texttt{igraph}.
3908
3909 \begin{table}[h]\index{Edge!options}
3910 \footnotesize%
3911 \begin{center}
3912 \begin{tabular}{ll}
3913 \toprule
3914 Keys & Other valid keys \\
3915 \midrule
3916 node & vertex, v, n \\
3917 edge & link, l, e \\
3918 margins & margin \\
3919 canvas & bbox, figure\_size \\
3920 units & unit \\
3921 fixed & fixed\_nodes, fixed\_vertices, fixed\_n, fixed\_v\\
3922 positions & initial\_positions, node\_positions, vertex\_positions, n\_positions, v\_positions\\
3923 \bottomrule
3924 \end{tabular}
3925 \scriptsize
3926 \end{center}
3927 \caption{Keyword naming convention.}
3928 \label{tab:keywords}
3929 \end{table}
3930
3931
3932 %%
3933 % The back matter contains appendices, bibliographies, indices, glossaries, etc.
3934
3935
3936
3937
3938
3939
3940
3941 \backmatter
3942
3943 \bibliography{sample-handout}
3944 \bibliographystyle{plainnat}
3945
3946
3947 \printindex
3948
3949 \end{document}
3950
3951 % =============================================================================
3952 %%% Local Variables:
3953 %%% mode: latex
3954 %%% TeX-master: t
3955 %%% End: