Debian Codegraph @

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

raw
1 % Copyright 2011 by Daniele Pighin
2 %
3 % This file may be distributed and/or modified
4 %
5 % 1. under the LaTeX Project Public License and/or
6 % 2. under the GNU Free Documentation License.
7 %
8 % See the file doc/generic/tikz-dependency/licenses/LICENSE for more details.
9
10 \documentclass[a4paper]{ltxdoc}
11 \def\pgfautoxrefs{1}
12
13 \usepackage[a4paper,left=2.25cm,right=2.25cm,top=2.5cm,bottom=2.5cm,nohead]{geometry}
14 \usepackage[utf8]{inputenc}
15
16 \usepackage{makeidx}
17 \makeindex
18
19 \usepackage{hyperref}
20 \hypersetup{%
21 pdftitle={The tikz-dependency package v2.0},
22 pdfsubject={A latex package based on tikz to draw dependency graphs},
23 pdfauthor={Daniele Pighin},
24 pdfkeywords={dependency parses, latex, tikz, pgf},
25 colorlinks=true, % use true to enable colors below:
26 linkcolor=blue,%red,
27 filecolor=blue,%magenta,
28 urlcolor=blue,%cyan,
29 citecolor=blue,
30 pdfborder=0 0 0,
31 }
32 \usepackage{tikz}
33 \makeatletter
34 \input{pgfmanual.code}
35 \makeatother
36 %\usepackage{pgfmanual}
37 \usepackage{calc} % NEEDED by pgfmanual-en-macros
38 \input{pgfmanual-en-macros}
39
40 \usepackage{tikz-dependency}
41 \usetikzlibrary{spy}
42 %\usepackage{palatino}
43
44 \newcommand{\pipeescape}{\catcode`\|=12}
45
46 \newcommand{\cmdname}[1]{\texttt{\color{red!75!black}\detokenize{#1}}}
47
48 \def\pkgname{\tikzname{}\texttt{-dependency}}
49
50 \newcommand{\options}[1][key-value-pairs]{\opt{\oarg{#1}}}
51
52 \newcommand{\note}[2]{
53 \begin{quote}
54 \textbf{#1}\par
55 #2
56 \end{quote}
57 }
58
59 \title{The \pkgname{} package}
60 \author{\normalsize Daniele Pighin\\\footnotesize{\href{mailto:[email protected]}{\texttt{[email protected]}}}\\\footnotesize{\url{http://danielepighin.net/cms}}}
61 \date{Version 1.1, January 2012}
62
63 \makeatletter
64 \definecolor{graphicbackground}{rgb}{0.96,0.96,0.8}
65 \def\tikzcd@bgcolor{graphicbackground}
66 \makeatother
67
68 \setlength{\parskip}{1ex}
69 \setlength{\parindent}{0pt}
70
71 \newcommand{\displayarrow}[2][]{\texttt{#2} & yelds \tikz[baseline=-2.5pt] \draw[#2-#2, line width=0.44pt, #1] (0,0) -- (1,0);}
72 \newcommand{\displayarrowstyle}[2][]{\texttt{#2} & yelds \tikz[baseline=-2.5pt] \draw[/commutative diagrams/current arrows, #2, #1] (0,0) -- (0.4,0);}
73
74 \begin{document}
75
76 \maketitle
77
78 If your work is in any way connected with linguistics or natural
79 language processing, chances are high that the moment will come when you will have
80 to draw a dependency graph:
81 \begin{center}
82 \resizebox{\linewidth}{!}{
83 {\pipeescape%
84 \begin{dependency}[label style={font=\bfseries,fill=black,text=white}]
85 \tikzstyle{root}=[fill=yellow, text=black, font=\bfseries]
86 \tikzstyle{postag}=[font=\tiny]
87 \tikzset{arg/.style={rounded corners,inner sep=.4ex,top color=#1!60,draw=#1!60!black}}
88 \tikzset{rolelab/.style={inner sep=1ex,top color=#1!60,draw=#1!60!black,text=black}}
89 \begin{deptext}[column sep=.4cm, row sep=.5ex, row 1/.style = postag]
90 NN \& MD \& VB \& PRP\$ \& NN \& RBR \\
91 \pkgname \& will \& make \& your \& life \& easier \\
92 \end{deptext}
93 \deproot[label style=root]{3}{root}
94 \depedge{3}{1}{nsubj}
95 \depedge{3}{2}{aux}
96 \depedge{5}{4}{poss}
97 \depedge{3}{5}{dobj}
98 \depedge{3}{6}{advmod}
99 \wordgroup[arg=green]{2}{3}{3}{pred}
100 \wordgroup[arg=red]{2}{1}{1}{a0}
101 \wordgroup[arg=blue]{2}{4}{6}{a1}
102 \groupedge[edge below,red!60!black,label style={rolelab=red}]{pred}{a0}{ARG0}{5ex}
103 \groupedge[edge below,blue!60!black,label style={rolelab=blue}]{pred}{a1}{ARG1}{5ex}
104 \end{dependency}%
105 } % pipeescape
106 \quad
107 \begin{dependency}[theme = simple]
108 \begin{deptext}[column sep=1em]
109 A \& hearing \& is \& scheduled \& on \& the \& issue \& today \& . \\
110 \end{deptext}
111 \deproot{3}{ROOT}
112 \depedge{2}{1}{ATT}
113 \depedge[edge start x offset=-6pt]{2}{5}{ATT}
114 \depedge{3}{2}{SBJ}
115 \depedge{3}{9}{PU}
116 \depedge{3}{4}{VC}
117 \depedge{4}{8}{TMP}
118 \depedge{5}{7}{PC}
119 \depedge[arc angle=50]{7}{6}{ATT}
120 \end{dependency}
121 } % resizebox
122 \end{center}
123
124 \begin{center}
125 \resizebox{\linewidth}{!}{%
126 \depstyle{inner bubble}{draw=gray!80, minimum height=20pt, rounded corners=8pt, inner sep=2pt, top color=gray!40, bottom color=white}
127 \depstyle{outer bubble}{draw=gray!80, minimum height=26pt, rounded corners=10pt, inner sep=5pt, top color=white, bottom color=gray!40}
128 \depstyle{ungrammatical}{edge below, edge style = {ultra thick, red}, label style = {below, text=red}, text only label}
129 \begin{dependency}[hide label, arc edge,
130 edge vertical padding=-2pt,
131 group style=outer bubble]
132 \begin{deptext}[column sep=1.4em]
133 a \& student \& whose \& mother \& and \& his \& father \& peter \& knows \\
134 \end{deptext}
135 \wordgroup{1}{3}{7}{chubby}
136 \wordgroup{1}{1}{2}{first} \depedge{2}{1}{}
137 \wordgroup[inner bubble]{1}{3}{4}{second} \depedge{4}{3}{}
138 \wordgroup[inner bubble]{1}{6}{7}{third} \depedge{7}{6}{}
139 \wordgroup{1}{8}{8}{fourth}
140 \wordgroup{1}{9}{9}{fifth}
141 \groupedge{fifth}{fourth}{}{0}
142 \groupedge[ungrammatical]{first}{second}{ungrammatical}{.5cm}
143 \groupedge[edge above]{second}{fifth}{}{1.5cm}
144 \groupedge[edge above]{fifth}{chubby}{}{1cm}
145 \end{dependency}%
146 \quad%
147 \begin{dependency}[edge style={green!60!black,very thick},
148 label style={fill=blue!60,font=\bfseries,text=white}]
149 \tikzstyle{POS}=[font=\footnotesize\bfseries,text=blue!60!black]
150 \tikzstyle{word}=[draw=blue!60!black, shade, text=black,
151 rotate=45, anchor=north east, inner sep=1ex,
152 font=\normalsize, top color=blue!60, rounded corners]
153 \begin{deptext}[column sep=.5cm, row sep=0, nodes={POS}]
154 PRP\$ \& NN \& RB \&[.5cm] VBZ \& VBG \& NN \\
155 \node [word] {My}; \&
156 \node [word] {dog}; \&
157 \node [word] {also}; \&
158 \node [word] {likes}; \&
159 \node [word] {eating}; \&
160 \node [word] {sausage}; \\
161 \end{deptext}
162 \deproot{4}{root}
163 \depedge[edge style={blue!60!black,ultra thick},
164 label style={fill=green!60,font=\bfseries,text=black, rotate=10}]{2}{1}{poss}
165 \depedge{4}{2}{nsubj}
166 \depedge{4}{3}{advmod}
167 \depedge{4}{5}{xcomp}
168 \depedge{5}{6}{dobj}
169 \end{dependency}%
170 } %resizebox
171 \end{center}
172
173 \tikzname{} already has all the needed facilities to draw and style a dependency
174 graph, but diving into the documentation just to understand how to draw one or two
175 trees may turn out to be rather overwhelming.
176
177 \pkgname{} is pretty flexible, and it can easily be used to draw quite complex graphs around sequences
178 of tokens, not necessarily related to dependency parsing or to language, as shown in this useless toy example:
179
180 \begin{center}
181 {\pipeescape
182 \begin{dependency}
183 \tikzstyle{default}=[fill=white, draw=black, text = blue, solid]
184 \tikzstyle{pinky}=[fill=pink, draw=pink!60!black, text = black, solid]
185 \tikzstyle{wasp}=[fill=black, draw=orange, text = yellow, solid]
186 \tikzstyle{cooltext}=[draw=#1!60!black, thick, shade, top color=#1!60, bottom color=white, rounded corners = 2pt]
187 \depkeys{label style=default, edge below, font=\footnotesize}
188 \begin{deptext}[column sep = 5pt, nodes={cooltext=orange}]
189 You \&[.3cm] can \&[.8cm] |[cooltext=blue]| easily \& exaggerate \& if \& you \& feel \& like \&[1cm] doing \& so \\
190 \end{deptext}
191 \depedge[hide label, dotted]{1}{2}{}
192 \depedge{1}{3}{link1}
193 \depedge[edge unit distance=1.25ex]{1}{10}{link2}
194 \depedge[edge above, label style={pinky}]{3}{2}{link3}
195 \depedge[edge above]{8}{6}{link4}
196 \depedge[edge unit distance=5ex, edge above, dotted]{8}{6}{or this?}
197 \depedge[label style={inner sep=1.5ex, scale=1.1}]{8}{9}{$\frac{e^{f(x)}}{g(x)}$}
198 \depedge[edge unit distance=4ex, label style={wasp}]{8}{10}{link6}
199 \depedge{5}{8}{link7}
200 \node (comment) [above of = \wordref{1}{1}] {Look at this one!};
201 \draw [->,out=-90,in=135] (comment) to (\wordref{1}{2});
202 \end{dependency}
203 }
204 \end{center}
205
206 Hopefully, this package will make your life a little bit easier, and allow you to draw a
207 dependency graph without too much \tikzname{} prior knowledge.
208 It will also allow you to draw cute graphs, which won't increase your impact
209 factor but may help making your papers look more pleasant and elegant.
210
211 \thispagestyle{empty}
212
213 \newpage
214
215 \tableofcontents
216
217 \thispagestyle{empty}
218
219 \newpage
220
221 \section{Installation}\label{sec:installation}
222
223 The simplest and fastest way to get things working is to copy the style file
224 |tikz-dependency.sty| in the root directory of your latex project.
225
226 Alternatively, you can install it as you would install any other \LaTeX\ package, by copying it in some directory searched by \LaTeX{} and running |texhash|.
227 The |texmf| directory under your home directory is most likely one of such directories (even though there are chances that it does not exist).
228 If there is no |texmf| directory under your home, than create it:
229 \begin{codeexample}[code only]
230 $ cd ~
231 $ mkdir -p texmf
232 \end{codeexample}
233
234 Extract the \pkgname{} under this directory:
235 \begin{codeexample}[code only]
236 $ cd texmf
237 $ tar xvzf /path/to/tikz-dependency.tar.gz
238 \end{codeexample}
239
240 Run |texhash| to let \LaTeX{} know about the newly installed package:
241 \begin{codeexample}[code only]
242 $ texhash texmf
243 \end{codeexample}
244 That should do it. Refer to \LaTeX\ documentation for more details or in case of non-standard \LaTeX{} installations.
245
246 Please, note that PGF/\tikzname{} version 2.10 is required for \pkgname{} to work as expected.
247
248 If \tikzname{} is not installed on your system, you can easily install it in the same way.
249 Visit \url{http://sourceforge.net/projects/pgf/} with your favorite browser, download the latest version of the package and uncompress in some of the directories searched by \LaTeX{}. The |texmf| directory under your home directory should be a good place to start:
250 \begin{codeexample}[code only]
251 $ cd ~
252 $ unzip /path/to/pgf_version.zip -d texmf
253 \end{codeexample}
254 Run |texhash|:
255 \begin{codeexample}[code only]
256 $ texhash texmf
257 \end{codeexample}
258 Everything should be fine now. For more detailed instructions on how to install \tikzname{}, please refer to its manual at \url{http://ftp.gui.uva.es/sites/ctan.org/graphics/pgf/base/doc/generic/pgf/pgfmanual.pdf}.
259
260 To use \pkgname{}, the first thing that you will need to do is to require it in your preamble:
261 \begin{codeexample}[code only]
262 \usepackage{tikz-dependency}
263 \end{codeexample}
264 \pkgname{} will automatically load \tikzname{} and its other requirements.
265
266
267 \section{A step-by-step introduction}\label{sec:stepbystep}
268
269 In this section you will see how simple it is to draw a dependency graph. We will go throw all the required steps one by one, from the creation of a suitable environment, to the actual drawing of the graph, to the optional steps that can make your graph look nicer.
270
271 We will start by trying to reproduce the following example:
272
273 \begin{center}
274 \begin{dependency}
275 \begin{deptext}[column sep=0.2cm]
276 My \&[.5cm] dog \& also \&[.7cm] likes \&[.4cm] eating \& sausage \\
277 \end{deptext}
278 \deproot{4}{root}
279 \depedge{2}{1}{poss}
280 \depedge{4}{2}{nsubj}
281 \depedge{4}{3}{advmod}
282 \depedge{4}{5}{xcomp}
283 \depedge{5}{6}{dobj}
284 \end{dependency}
285 \end{center}
286
287 But first let's agree on some terminology. I will call \textbf{words}\index{terminology!word} the tokens of the sentence, and \textbf{dependencies}\index{terminology!dependency} the relations between words. A dependency actually consists of two entities: the \textbf{edge}\index{terminology!edge} between the two words and its \textbf{label}\index{terminology!label}, which is the type of the relation.
288
289 \subsection{An environment to draw dependency graphs}
290
291 The first step will be to create a suitable environment to draw your dependency graphs.
292
293 \begin{environment}{{dependency}\options}
294 All the commands and configuration keys that you will see in this document are available within a |dependency| environment. Since it is an overloaded version of |tikzpicture|, all the things that you would do within a |tikzpicture| environment (such as drawing paths, edges, nodes, whatever) you can also do within a |dependency|. At the moment, the only reason why you'd rather use a |dependency| environment is because you can pass it some optional configuration keys (i.e., \options) that can affect the style of the whole dependency graph. The documentation of these configuration keys is scattered around the documentation, though many of them are described in Section~\ref{sec:styling}.
295 \end{environment}
296
297 So, to draw a new dependency tree you will generally start by writing something like this:
298
299 \begin{codeexample}[]
300 \begin{dependency}
301 % The code to actually draw the
302 % dependency graph will go here
303 \end{dependency}
304 \end{codeexample}
305
306 At this stage it looks pretty empty, so let's get started and fill it up with some contents.
307
308 \subsection{Writing the sentence}
309
310 \begin{environment}{{deptext}\options}
311 The |deptext| environment is used to lay out the words of the parsed sentence.
312
313 Within |deptext|, you will write a sentence separating each word with \cmdname{\&}\index{\texttt{\textbackslash\&}}\index{word separator}, similarly to what you would do in a |tabular| environment. Please, not that in this
314 case the separator is actually a \LaTeX\ command (i.e., a backslash followed by an ampersand), and
315 not just a simple ampersand. To terminate the sentence, add the command \cmdname{\\}\index{\texttt{\textbackslash\textbackslash}}\index{line separator} (i.e., two consecutive backslashes) after the last word, just as you would do to end a row in a table. The \options\ can bee used to change the way the sentence looks, and more details about it are coming soon.
316 \end{environment}
317
318 After adding the |deptext| environment with the text of our example sentence, the incomplete dependency graph would look like this:
319
320 \begin{codeexample}[]
321 \begin{dependency}
322 \begin{deptext}
323 My \& dog \& also \& likes \& eating \& sausage \\
324 \end{deptext}
325 \end{dependency}
326 \end{codeexample}
327
328 For the \tikzname{}-savvy user, |deptext| is just a wrapper around \tikzname{}'s own matrix environment. The matrix is a matrix of nodes, with nodes in empty cells and some default styling. All the \options\ passed to the |deptext| are first parsed by \pkgname, then handed to the underlying |matrix|. If you know what you are doing and you want more control on the final result, you can have it.
329
330 \subsection{Adding dependencies}\label{sec:adding-dependencies}
331
332 \begin{command}{\depedge\options\marg{from-word}\marg{to-word}\marg{label}}
333
334 This command is used to add dependencies between words. The \options\ argument is optional, and it can be used for styling the edge and its label (again, we will come to that part shortly). The three
335 mandatory arguments define the origin and destination of the dependency edge, and the label of the
336 dependency. The arguments \marg{from-word} and \marg{to-word} are the offsets of the words to be linked, counting from 1. \marg{label} is just any string, to be used as a label for the edge.
337 |\depedge| commands should be issued \emph{after} closing the |deptext| environment.
338 \end{command}
339
340 To draw an edge between the words \emph{eating} and \emph{sausage} in the example, you would set \marg{from-word} to 5, \marg{to-word} to 6 and \marg{label} to \emph{dobj}. After adding this first edge, the example looks as follows:
341
342 \begin{codeexample}[]
343 \begin{dependency}
344 \begin{deptext}
345 My \& dog \& also \& likes \& eating \& sausage \\
346 \end{deptext}
347 \depedge{5}{6}{dobj}
348 \end{dependency}
349 \end{codeexample}
350
351 By repeating this operation for all the dependencies in the sentence, we end up with a first complete version
352 of the dependency tree:
353
354 \begin{codeexample}[]
355 \begin{dependency}
356 \begin{deptext}
357 My \& dog \& also \& likes \& eating \& sausage \\
358 \end{deptext}
359 \depedge{2}{1}{poss}
360 \depedge{4}{2}{nsubj}
361 \depedge{4}{3}{advmod}
362 \depedge{4}{5}{xcomp}
363 \depedge{5}{6}{dobj}
364 \end{dependency}
365 \end{codeexample}
366
367 As you can see, \pkgname{} automatically does some basic routing of the edges of the graph, by drawing
368 dependency edges higher or lower depending on how far apart the two words are. The graph looks decent at
369 this stage, but it looks a little bit cramped and it could definitely use some more space between the words.
370
371 \subsection{Getting word spacing right}
372
373 You can either add some space between all words, or you can add some space between two specific words. Let's see how it is done.
374
375 \subsubsection{Setting the space between every two words}
376
377 When I first introduced the |deptext| environment, I said in passing that it can take some optional arguments. Since |deptext| is a wrapper around \tikzname{}'s own |matrix|, if you know some \tikzname{} you can pass to |deptext| any key-value pairs that |matrix| would understand. If you have absolutely no idea of how optional parameters (key-value configuration options) work in \tikzname{}, you are warmly invited to take a look at Appendix~\ref{sec:tikz}. If you do not understand what is going on, you will be able to copy the example but your ability to exploit the flexibility of the package will be largely impaired.
378
379 As far as we are concerned here, what we want to discuss is the |/tikz/column sep| configuration key, which can be used to add more space between all the words in the sentence.
380
381 In this documentation, I will always use the fully qualified name of a key when documenting it (see, for example, the description of |/tikz/column sep| immediately below. Anyway, you are not required to use the fully qualified name of keys when using them, and using their base name (e.g., |column sep|) is sufficient. In fact, in the examples I will generally use the shorter form.
382
383 \begin{key}{/tikz/column sep=\meta{length} (default 0cm)}
384 If you want to add, say, 0.2cm between every two words, you can do it so by passing |column sep=0.2cm| as the optional argument of the |deptext| environment.
385
386 \begin{codeexample}[]
387 \begin{dependency}
388 \begin{deptext}[column sep=0.2cm]
389 My \& dog \& also \& likes \& eating \& sausage \\
390 \end{deptext}
391 \depedge{2}{1}{poss}
392 \depedge{4}{2}{nsubj}
393 \depedge{4}{3}{advmod}
394 \depedge{4}{5}{xcomp}
395 \depedge{5}{6}{dobj}
396 \end{dependency}
397 \end{codeexample}
398
399 It looks better already, but the fact that some dependency labels are longer than the horizontal segment of the edge doesn't look to nice. So, we could increase the space between all the words, for example to 0.7cm:
400
401 \begin{codeexample}[]
402 \begin{dependency}
403 \begin{deptext}[column sep=0.7cm]
404 My \& dog \& also \& likes \& eating \& sausage \\
405 \end{deptext}
406 \depedge{2}{1}{poss}
407 \depedge{4}{2}{nsubj}
408 \depedge{4}{3}{advmod}
409 \depedge{4}{5}{xcomp}
410 \depedge{5}{6}{dobj}
411 \end{dependency}
412 \end{codeexample}
413
414 \end{key}
415
416 Now the labels are fine, but the words are a little bit too far apart, at least for my taste. So I would rather go back to |/tikz/column sep=0.2|, and find a more precise way of spacing only the problematic word pairs. In this case, they are adjacent words connected by a dependency with a long label, i.e., \emph{My/dog}, \emph{also/likes} and \emph{likes/eating}.
417
418 \subsubsection{Spacing word individually}
419
420 Additional space between two words can be added by using the optional argument of the \cmdname{\&} command that we used to separate words. For example, writing \cmdname{\&}|[0.5cm]| will add 0.5cm to the default word spacing set with via the |column sep| option. If we take care of the three problematic pairs individually, we can obtain something like this:
421
422 \begin{codeexample}[]
423 \begin{dependency}
424 \begin{deptext}[column sep=0.2cm]
425 My \&[.5cm] dog \& also \&[.7cm] likes \&[.4cm] eating \& sausage \\
426 \end{deptext}
427 \depedge{2}{1}{poss}
428 \depedge{4}{2}{nsubj}
429 \depedge{4}{3}{advmod}
430 \depedge{4}{5}{xcomp}
431 \depedge{5}{6}{dobj}
432 \end{dependency}
433 \end{codeexample}
434
435 \subsection{Adding a root node}
436
437 If you want to add a \index{root node} to the dependency graph, you can do so by means of the |\deproot| command.
438
439 \begin{command}{\deproot\options\marg{root-offset}\marg{label}}
440 It is basically a variant of |\depedge|. Instead of connecting two words, it will create a node labeled \meta{label} just above the word having offset \meta{root-offset}, and an arrow between them. In our example, the root word is the verb \emph{likes}, which occupies the fourth position:
441 \end{command}
442
443 \begin{codeexample}[]
444 \begin{dependency}
445 \begin{deptext}[column sep=0.2cm]
446 My \&[.5cm] dog \& also \&[.7cm] likes \&[.4cm] eating \& sausage \\
447 \end{deptext}
448 \depedge{2}{1}{poss}
449 \depedge{4}{2}{nsubj}
450 \depedge{4}{3}{advmod}
451 \depedge{4}{5}{xcomp}
452 \depedge{5}{6}{dobj}
453 \deproot{4}{root}
454 \end{dependency}
455 \end{codeexample}
456
457 This completes the crash course on the basics of dependency graph drawing. The next sections will tell you how to control edge positioning, how to build more complicated graphs with several layers of text, how to style the graphs to your liking and how to include your graphs in larger pictures.
458
459 \section{Multiple layers of text}
460
461 When drawing a dependency graph it is common to have a layer of part-of-speech (POS) tags just above the words. Achieving this with \pkgname{} is pretty straightforward. Since the |deptext| environment is already a matrix, all you have to do is to add another row of text to the matrix:
462
463 \begin{codeexample}[]
464 \begin{dependency}
465 \begin{deptext}[column sep=.5cm]
466 PRP\$ \& NN \& RB \&[.5cm] VBZ \& VBG \& NN \\
467 My \& dog \& also \& likes \& eating \& sausage \\
468 \end{deptext}
469 \deproot{4}{root}
470 \depedge{2}{1}{poss}
471 \depedge{4}{2}{nsubj}
472 \depedge{4}{3}{advmod}
473 \depedge{4}{5}{xcomp}
474 \depedge{5}{6}{dobj}
475 \end{dependency}
476 \end{codeexample}
477
478 In this case, we have added the POS tags on top of the words. Of course, we could have also added them below:
479
480 \begin{codeexample}[]
481 \begin{dependency}
482 \begin{deptext}[column sep=.7cm]
483 My \& dog \& also \& likes \& eating \& sausage \\
484 PRP\$ \& NN \& RB \&[.5cm] VBZ \& VBG \& NN \\
485 \end{deptext}
486 \deproot{4}{root}
487 \depedge{2}{1}{poss}
488 \depedge{4}{2}{nsubj}
489 \depedge{4}{3}{advmod}
490 \depedge{4}{5}{xcomp}
491 \depedge{5}{6}{dobj}
492 \end{dependency}
493 \end{codeexample}
494
495 \begin{key}{/tikz/row sep=\meta{length} (default 0cm)}
496 Similarly to how you can increase the space between columns in a matrix, you can also increase inter-row spacing. For example, to add 0.5ex between every two rows you can add |row sep=0.5ex| to the optional argument of the |deptext| environment:
497 \begin{codeexample}[]
498 \begin{dependency}
499 \begin{deptext}[column sep=.7cm, row sep=.5ex]
500 My \& dog \& also \& likes \& eating\\
501 PRP\$ \& NN \& RB \&[.5cm] VBZ \& VBG\\
502 \end{deptext}
503 \deproot{4}{root}
504 \depedge{2}{1}{poss}
505 \depedge{4}{2}{nsubj}
506 \depedge{4}{3}{advmod}
507 \depedge{4}{5}{xcomp}
508 \qquad
509 \end{dependency}
510 \quad
511 \begin{dependency}
512 \begin{deptext}[column sep=.7cm, row sep=2ex]
513 My \& dog \& also \& likes \& eating\\
514 PRP\$ \& NN \& RB \&[.5cm] VBZ \& VBG\\
515 \end{deptext}
516 \deproot{4}{root}
517 \depedge{2}{1}{poss}
518 \depedge{4}{2}{nsubj}
519 \depedge{4}{3}{advmod}
520 \depedge{4}{5}{xcomp}
521 \end{dependency}
522 \end{codeexample}
523 \end{key}
524
525 \section{More control over edges}
526
527 In Section~\ref{sec:adding-dependencies} I hinted to the fact that the height of the horizontal segment of a dependency edge is proportional to the distance between the linked words. As you may have already guessed, this can be a problem for \index{long dependencies}. Consider the following example, in which I added some more words and a long dependency:
528
529 \begin{codeexample}[]
530 \begin{dependency}
531 \begin{deptext}[column sep=0.2cm]
532 My \&[.5cm] dog \& also \&[.7cm] likes \&[.4cm] eating \& sausage \& and \& more \& words \\
533 \end{deptext}
534 \depedge{2}{1}{poss}
535 \depedge{4}{2}{nsubj}
536 \depedge{4}{3}{advmod}
537 \depedge{4}{5}{xcomp}
538 \depedge{5}{6}{dobj}
539 \deproot{4}{root}
540 \depedge{9}{1}{rather-long}
541 \end{dependency}
542 \end{codeexample}
543
544 To decide how high a dependency should be drawn, \pkgname{} uses the formula $s\vert x-y \vert$, where $x$ and $y$ are the offsets of the two words, and $s$ is the value of the optional parameter |/depgraph/edge unit distance|.
545
546 \begin{key}{/depgraph/edge unit distance=\meta{length} (default 3ex)}
547
548 This key represents the distance of the horizontal segment of the edge between two adjacent words. That is, if two words are 5 positions apart, the distance of the edge will be 5 times the value of |/depgraph/edge unit distance|. Whenever you draw a edge with |\depedge| you can override this value as part of the optional argument of the command. For example, by changing its value in the previous and setting it to |1.5ex| it is possible to halve the total height of the problematic edge:
549
550 \begin{codeexample}[]
551 \begin{dependency}
552 \begin{deptext}[column sep=0.2cm]
553 My \&[.5cm] dog \& also \&[.7cm] likes \&[.4cm] eating \& sausage \& and \& more \& words \\
554 \end{deptext}
555 \depedge{2}{1}{poss}
556 \depedge{4}{2}{nsubj}
557 \depedge{4}{3}{advmod}
558 \depedge{4}{5}{xcomp}
559 \depedge{5}{6}{dobj}
560 \deproot{4}{root}
561 \depedge[edge unit distance=1.5ex]{9}{1}{rather-long}
562 \end{dependency}
563 \end{codeexample}
564
565 |/depgraph/edge unit distance| can also be used to tune the distance of the root node\index{root node!distance} from the sentence. By default, the root node is set at a distance equal to 4 times the value of the parameter. By changing its value you can bring it closer of further:
566
567 \begin{codeexample}[]
568 \begin{dependency}
569 \begin{deptext}[column sep=0.2cm]
570 My \&[.5cm] dog \& also \&[.7cm] likes \&[.4cm] \dots \\
571 \end{deptext}
572 \depedge{2}{1}{poss}
573 \depedge{4}{2}{nsubj}
574 \depedge{4}{3}{advmod}
575 \deproot[edge unit distance=4ex]{4}{root}
576 \end{dependency}
577 \quad
578 \begin{dependency}
579 \begin{deptext}[column sep=0.2cm]
580 My \&[.5cm] dog \& also \&[.7cm] likes \&[.4cm] \dots \\
581 \end{deptext}
582 \depedge{2}{1}{poss}
583 \depedge{4}{2}{nsubj}
584 \depedge{4}{3}{advmod}
585 \deproot[edge unit distance=2ex]{4}{root}
586 \end{dependency}
587 \end{codeexample}
588
589 \end{key}
590
591 \begin{key}{/depgraph/edge height=\meta{length} (default 0pt)}
592
593 \textit{[New in version 1.2]}
594 As an alternative, |edge height| allows you to set explicitly the height of an edge.
595
596 \begin{codeexample}[]
597 \begin{dependency}
598 \begin{deptext}[column sep=0.2cm]
599 My \&[.5cm] dog \& also \&[.7cm] likes \&[.4cm] eating \& sausage \& and \& more \& words \\
600 \end{deptext}
601 \depedge{2}{1}{poss}
602 \depedge{4}{2}{nsubj}
603 \depedge{4}{3}{advmod}
604 \depedge{4}{5}{xcomp}
605 \depedge{5}{6}{dobj}
606 \deproot{4}{root}
607 \depedge[edge height=12ex]{9}{1}{rather-long}
608 \end{dependency}
609 \end{codeexample}
610
611 Setting |edge height| overrides the automatic calculation of the edge height. If you set |edge height| at the |dependency| level, all edges will be drawn at the same height, e.g.:
612
613 \begin{codeexample}[]
614 \begin{dependency}[edge height=2cm]
615 \begin{deptext}[column sep=0.2cm]
616 My \&[.5cm] dog \& also \&[.7cm] likes \&[.4cm] eating \& sausage \& and \& more \& words \\
617 \end{deptext}
618 \depedge{2}{1}{poss}
619 \depedge{4}{2}{nsubj}
620 \depedge{4}{3}{advmod}
621 \depedge{4}{5}{xcomp}
622 \depedge{5}{6}{dobj}
623 \deproot{4}{root}
624 \end{dependency}
625 \end{codeexample}
626
627 \noindent so maybe this is something that you will want to do only in very special cases.
628
629 \end{key}
630
631 At this point, you may be wondering: why are we always drawing dependencies above the text? Indeed, turning links around is not only possible, but also quite easy, and the next key-value pairs allow you to control this behaviour.
632
633 \begin{keylist}{/depgraph/edge above=\meta{boolean} (default true),/depgraph/edge below=\meta{boolean} (default false)}
634 These two keys control the position of the links, which can be drawn either above or below the layer(s) of text. You can pass any of them as part of the optional arguments of the |dependency| environment, and change the position of all the links in the graph at once. Writing the name of the key is sufficient, so writing |edge below=true| or just |edge below| produces the same result:
635 \begin{codeexample}[]
636 \begin{dependency}[edge below]
637 \begin{deptext}[column sep=.7cm]
638 My \& dog \& also \& likes \& eating \& sausage \\
639 PRP\$ \& NN \& RB \&[.5cm] VBZ \& VBG \& NN \\
640 \end{deptext}
641 \deproot{4}{root}
642 \depedge{2}{1}{poss}
643 \depedge{4}{2}{nsubj}
644 \depedge{4}{3}{advmod}
645 \depedge{4}{5}{xcomp}
646 \depedge{5}{6}{dobj}
647 \end{dependency}
648 \end{codeexample}
649 |/depgraph/edge below| and |/depgraph/edge above| can also be used to control the positioning of individual edges. In this case, you won't pass the keys to the |dependency| environment, but instead to a specific |\depedge| or |\deproot| whose behaviour you want to modify.
650 Say that you wanted all the edges to be drawn below, but the \emph{root} and \emph{poss} edges should be on top. You can pass |/depgraph/edge below| to |dependency|, and |/depgraph/edge above| to the two |\depedge|s to be placed above:
651 \begin{codeexample}[]
652 \begin{dependency}[edge below]
653 \begin{deptext}[column sep=.7cm]
654 My \& dog \& also \& likes \& eating \& sausage \\
655 PRP\$ \& NN \& RB \&[.5cm] VBZ \& VBG \& NN \\
656 \end{deptext}
657 \deproot[edge above]{4}{root}
658 \depedge[edge above]{2}{1}{poss}
659 \depedge{4}{2}{nsubj}
660 \depedge{4}{3}{advmod}
661 \depedge{4}{5}{xcomp}
662 \depedge{5}{6}{dobj}
663 \end{dependency}
664 \end{codeexample}
665 \end{keylist}
666
667 Other than |/depgraph/edge unit distance|, three more parameters can affect the way edges are drawn. As shown in Figure\ref{fig:edgedrawingparameters}, they control several aspects related to the spacing among edges and between edges and text, plus the inclination of the non-horizontal segments of the edge. All these properties can be set both at the |dependency| level (which will affect all the edges in the graph) or at the |\depedge| level, which will only affect individual links.
668
669 \begin{figure}
670 \begin{center}
671 \def\zw{10cm}
672 \def\zh{5cm}
673 \def\zx{3cm}
674 \def\zy{-3.5cm}
675 \begin{dependency}[spy using overlays={magnification=5, width=\zw, height=\zh}]
676 \tikzset{postag/.style = {font=\tiny}}
677 \begin{deptext}[column sep=.5cm, row sep=.1em, row 1/.style = postag]
678 PRP\$ \& NN \& RB \&[.5cm] VBZ \& VBG \& NN \\
679 My \& dog \& also \& likes \& eating \& sausage \\
680 \end{deptext}
681 \deproot{4}{root}
682 \depedge{2}{1}{poss}
683 \depedge{4}{2}{nsubj}
684 \depedge{4}{3}{advmod}
685 \depedge{4}{5}{xcomp}
686 \depedge{5}{6}{dobj}
687 \spy [draw=green, pink!80!black, connect spies]
688 on ($(\wordref{1}{4}.north) + (0,1ex)$)
689 in node [draw] at (\zx,\zy);
690 \node (bl) at ($(\zx,\zy) - .5*(\zw,\zh)$) {};
691 \node (tr) at ($(\zx,\zy) + .5*(\zw,\zh)$) {};
692 \draw[step=.2cm, help lines, pink] (bl) grid (tr);
693 \draw[step=1cm, pink] (bl) grid (tr);
694 \draw [blue, thick, |-|] ($(bl)+(4.26,1.5)$)
695 -- node [below left,font=\bfseries\ttfamily\small] {edge horizontal padding} ++(.75,0);
696 \draw [blue, thick, |-|] ($(bl)+(5.7,4.1)$)
697 -- node [above,font=\bfseries\ttfamily\small] {edge slant} ++(.6,0);
698 \draw [blue, thick, dotted] ($(bl)+(5.7,1.8)$) -- ++(0,2.3);
699 \draw [blue, thick, |-|] ($(bl)+(6.1,1.7)$)
700 -- node [right,font=\bfseries\ttfamily\small] {edge vertical padding} ++(0,-.7);
701 \end{dependency}
702 \end{center}
703 \caption{Edge-drawing parameters.}\label{fig:edgedrawingparameters}
704 \end{figure}
705
706 \begin{key}{/depgraph/edge slant=\meta{length} (default 3pt)}
707 |/depgraph/edge slant| controls the slant of the diagonal segments in a dependency edge. As shown in Figure~\ref{fig:edgedrawingparameters}, what it actually controls is the horizontal offset between the initial (final) of the edge and its first (second) corner. By default it is set to |3pt|, which makes the segments just slightly sloped. By setting it to |0|, you can make the lateral segments completely vertical; by increasing its value you can make the edges look less slender.
708 \begin{codeexample}[]
709 \begin{dependency}[edge slant=0] %edge slant=0
710 \begin{deptext}[column sep=.7cm]
711 My \& dog \& also \& likes \& eating \\
712 PRP\$ \& NN \& RB \& VBZ \& VBG \\
713 \end{deptext}
714 \deproot{4}{root}
715 \depedge{2}{1}{poss}
716 \depedge{4}{2}{nsubj}
717 \depedge{4}{3}{advmod}
718 \depedge{4}{5}{xcomp}
719 \end{dependency}
720 \quad
721 \begin{dependency}[edge slant=10pt] %edge slant=10pt
722 \begin{deptext}[column sep=.3cm]
723 My \&[.4cm] dog \& also \&[.7cm] likes \&[.5cm] eating \\
724 PRP\$ \& NN \& RB \& VBZ \& VBG \\
725 \end{deptext}
726 \deproot{4}{root}
727 \depedge{2}{1}{poss}
728 \depedge{4}{2}{nsubj}
729 \depedge{4}{3}{advmod}
730 \depedge{4}{5}{xcomp}
731 \end{dependency}
732 \end{codeexample}
733 \end{key}
734
735
736 \begin{key}{/depgraph/edge horizontal padding=\meta{length} (default 4pt)}
737 \pkgname{} employs a very simple strategy to avoid edges outgoing from and incoming into a word to start/terminate on the same spot, thus making it easier to understand the direction of a dependency. The algorithm is very simple: all incoming links arrive in the middle of a word; all outgoing links heading left leave the node from a point which is a little bit to the left; all those heading right leave from a spot a little bit to the right. |/depgraph/edge horizontal padding| is the value of this ``little bit''. By setting it to |0|, all the edges will come and go from the same spot in the middle of the word. By increasing its value, the incoming and outgoing edges on a word will look more apart.
738 \begin{codeexample}[]
739 \begin{dependency}[edge horizontal padding=0] %edge horizontal padding=0
740 \begin{deptext}[column sep=.7cm]
741 My \& dog \& also \& likes \& eating \\
742 PRP\$ \& NN \& RB \& VBZ \& VBG \\
743 \end{deptext}
744 \deproot{4}{root}
745 \depedge{2}{1}{poss}
746 \depedge{4}{2}{nsubj}
747 \depedge{4}{3}{advmod}
748 \depedge{4}{5}{xcomp}
749 \end{dependency}
750 \quad
751 \begin{dependency}[edge horizontal padding=10pt] %edge horizontal padding=10pt
752 \begin{deptext}[column sep=.7cm]
753 My \& dog \& also \&[.2cm] likes \& eating \\
754 PRP\$ \& NN \& RB \& VBZ \& VBG \\
755 \end{deptext}
756 \deproot{4}{root}
757 \depedge{2}{1}{poss}
758 \depedge{4}{2}{nsubj}
759 \depedge{4}{3}{advmod}
760 \depedge{4}{5}{xcomp}
761 \end{dependency}
762 \end{codeexample}
763 \end{key}
764
765 \begin{key}{/depgraph/edge vertical padding=\meta{length} (default 0ex)}
766 |/depgraph/edge vertical padding| is the extra distance between a word and incoming/outgoing edges. By increasing (decreasing) its value, you can send the edges further (bring them closer) to the text.
767 \begin{codeexample}[]
768 \begin{dependency}[edge vertical padding=-.5ex] %edge vertical padding=-.5ex
769 \begin{deptext}[column sep=.7cm]
770 My \& dog \& also \& likes \& eating \\
771 PRP\$ \& NN \& RB \& VBZ \& VBG \\
772 \end{deptext}
773 \deproot{4}{root}
774 \depedge{2}{1}{poss}
775 \depedge{4}{2}{nsubj}
776 \depedge{4}{3}{advmod}
777 \depedge{4}{5}{xcomp}
778 \end{dependency}
779 \quad
780 \begin{dependency}[edge vertical padding=1ex] %edge horizontal padding=1ex
781 \begin{deptext}[column sep=.7cm]
782 My \& dog \& also \&[.2cm] likes \& eating \\
783 PRP\$ \& NN \& RB \& VBZ \& VBG \\
784 \end{deptext}
785 \deproot{4}{root}
786 \depedge{2}{1}{poss}
787 \depedge{4}{2}{nsubj}
788 \depedge{4}{3}{advmod}
789 \depedge{4}{5}{xcomp}
790 \end{dependency}
791 \end{codeexample}
792 \end{key}
793
794 It may be worth repeating that even though you will generally want to set this properties at the |dependency| level, you can very well set them individually for each edge. And of course, you can combine them with all the properties that we saw before (e.g., |/depgraph/edge below|):
795 \begin{codeexample}[]
796 \begin{dependency}[edge vertical padding=.5ex]
797 \begin{deptext}[column sep=.7cm]
798 My \& dog \& also \&[.3cm] likes \& eating \\
799 PRP\$ \& NN \& RB \& VBZ \& VBG \\
800 \end{deptext}
801 \deproot{4}{root}
802 \depedge[edge vertical padding=0]{2}{1}{poss}
803 \depedge[edge below, edge vertical padding=.3cm]{4}{2}{nsubj}
804 \depedge[edge horizontal padding=10pt]{4}{3}{advmod}
805 \depedge[edge slant=0]{4}{5}{xcomp}
806 \end{dependency}
807 \end{codeexample}
808
809 \begin{keylist}[/depgraph]{arc edge=\meta{boolean} (default false),segmented edge=\meta{boolean} (default true)}
810 This key allows you to switch between the default, fancier edge shape (|/depgraph/segmented edge|) and the traditional arc-shaped edges used in dependency parsing literature. Can be used either within |dependency| (affect all the edges in the graph) or individual |\depedge| commands. Local overrides are also possible (as shown in the rightmost example).
811 \begin{codeexample}[]
812 \begin{dependency}[arc edge]
813 \begin{deptext}[column sep=.7cm]
814 My \& dog \& also \& likes \& eating \\
815 PRP\$ \& NN \& RB \& VBZ \& VBG \\
816 \end{deptext}
817 \deproot{4}{root}
818 \depedge{2}{1}{poss}
819 \depedge{4}{2}{nsubj}
820 \depedge{4}{3}{advmod}
821 \depedge{4}{5}{xcomp}
822 \end{dependency}
823 \quad
824 \begin{dependency}[segmented edge]
825 \begin{deptext}[column sep=.7cm]
826 My \& dog \& also \&[.2cm] likes \& eating \\
827 PRP\$ \& NN \& RB \& VBZ \& VBG \\
828 \end{deptext}
829 \deproot{4}{root}
830 \depedge{2}{1}{poss}
831 \depedge[arc edge]{4}{2}{nsubj}
832 \depedge{4}{3}{advmod}
833 \depedge{4}{5}{xcomp}
834 \end{dependency}
835 \end{codeexample}
836 \end{keylist}
837
838 \begin{key}{/depgraph/arc angle=\meta{decimal} (default 60)}
839 When using |/depgraph/arc edge|, this key controls the angle with which edges enter and exit the nodes. It has no effect when the edge is drawn using |/depgraph/segmented edge|.
840 \begin{codeexample}[]
841 \begin{dependency}[arc edge, arc angle=80]
842 \begin{deptext}[column sep=.7cm]
843 My \& dog \& also \& likes \& eating \\
844 PRP\$ \& NN \& RB \& VBZ \& VBG \\
845 \end{deptext}
846 \deproot{4}{root}
847 \depedge{2}{1}{poss}
848 \depedge{4}{2}{nsubj}
849 \depedge{4}{3}{advmod}
850 \depedge{4}{5}{xcomp}
851 \end{dependency}
852 \quad
853 \begin{dependency}[arc edge, arc angle = 40]
854 \begin{deptext}[column sep=.7cm]
855 My \& dog \& also \&[.2cm] likes \& eating \\
856 PRP\$ \& NN \& RB \& VBZ \& VBG \\
857 \end{deptext}
858 \deproot{4}{root}
859 \depedge{2}{1}{poss}
860 \depedge{4}{2}{nsubj}
861 \depedge{4}{3}{advmod}
862 \depedge{4}{5}{xcomp}
863 \end{dependency}
864 \end{codeexample}
865 \end{key}
866
867 \begin{key}{/depgraph/text only label=\meta{boolean} (default false)}
868 At least in my opinion, heavily drawn and filled labels don't look very well with |arc edge|. This flag allows you to show only the text of the label, without drawing the node around it. To prevent the label to be drawn just over the edge line, you may want to add either |above| or |below| to the |label style|, as in this example:
869 \begin{codeexample}[]
870 \begin{dependency}[arc edge, arc angle=80, text only label, label style={above}]
871 \begin{deptext}[column sep=.7cm]
872 My \& dog \& also \& likes \& eating \\
873 PRP\$ \& NN \& RB \& VBZ \& VBG \\
874 \end{deptext}
875 \deproot{4}{root}
876 \depedge{2}{1}{poss}
877 \depedge{4}{2}{nsubj}
878 \depedge[label style={below}]{4}{3}{advmod}
879 \depedge{4}{5}{xcomp}
880 \end{dependency}
881 \end{codeexample}
882 \end{key}
883
884 \begin{keylist}[/depgraph]{edge start offset x=\meta{length} (default 0),edge end offset x=\meta{length} (default 0)}
885 When using arc edges, some edges may overlap as in the following example:
886 \begin{codeexample}[]
887 \begin{dependency}[theme = simple]
888 \begin{deptext}[column sep=1em]
889 A \& hearing \& is \& scheduled \& on \& the \& issue \& today \& . \\
890 \end{deptext}
891 \deproot{3}{ROOT}
892 \depedge{2}{1}{ATT}
893 \depedge{2}{5}{ATT}
894 \depedge{3}{2}{SBJ}
895 \depedge{3}{9}{PU}
896 \depedge{3}{4}{VC}
897 \depedge{4}{8}{TMP}
898 \depedge{5}{7}{PC}
899 \depedge[arc angle=50]{7}{6}{ATT}
900 \end{dependency}
901 \end{codeexample}
902
903 These two keys allow you to shift the start/end point of the edge horizontally by the specified amount, so as to untangle the graph:
904
905 \begin{codeexample}[]
906 \begin{dependency}[theme = simple]
907 \begin{deptext}[column sep=1em]
908 A \& hearing \& is \& scheduled \& on \& the \& issue \& today \& . \\
909 \end{deptext}
910 \deproot{3}{ROOT}
911 \depedge{2}{1}{ATT}
912 \depedge[edge start x offset=-6pt]{2}{5}{ATT}
913 \depedge{3}{2}{SBJ}
914 \depedge{3}{9}{PU}
915 \depedge{3}{4}{VC}
916 \depedge{4}{8}{TMP}
917 \depedge{5}{7}{PC}
918 \depedge[arc angle=50]{7}{6}{ATT}
919 \end{dependency}
920 \end{codeexample}
921
922 \end{keylist}
923
924 \section{Node groups and group linking}
925
926 Another thing that you may want to do is to annotate relations between groups of nodes. I added this functionality thinking about semantic parsing, so that it would be possible to annotate on the same graph the syntactic and semantic layers of a sentence. You can think of many other ways of exploiting the functionality and use it for your own specific needs. Two new commands can be used to define word groups and to connect them.
927
928 \begin{command}{\wordgroup\options\marg{row-offset}\marg{word-offset-beg}\marg{word-offset-end}\marg{gid}}
929
930 This command creates a group spanning the words in the \marg{row-offset}-th row of the matrix from position \marg{word-offset-beg} to position \marg{word-offset-end}. \marg{gid} is a unique identifier for the group, that will be used to connect groups. From \tikzname{}' point of view, it is just the name of the node enclosing the group, so you can directly use it as you would use any other node.
931
932 \begin{codeexample}[]
933 \begin{dependency}
934 \begin{deptext}[column sep=.5cm, row sep=.1ex]
935 PRP\$ \& NN \& RB \&[.5cm] VBZ \& VBG \& NN \\
936 My \& dog \& also \& likes \& eating \& sausage \\
937 \end{deptext}
938 \deproot{4}{root}
939 \depedge{2}{1}{poss}
940 \depedge{4}{2}{nsubj}
941 \depedge{4}{3}{advmod}
942 \depedge{4}{5}{xcomp}
943 \depedge{5}{6}{dobj}
944 % group on 2nd row, from word 4 to word 4, labeled "pred"
945 \wordgroup{2}{4}{4}{pred}
946 % group on 2nd row, from word 1 to word 2, labeled "a0"
947 \wordgroup{2}{1}{2}{a0}
948 % group on 2nd row, from word 5 to word 6, labeled "a1"
949 \wordgroup{2}{5}{6}{a1}
950 \end{dependency}
951 \end{codeexample}
952 \end{command}
953
954 \begin{command}{\groupedge\options\marg{from-gid}\marg{to-gid}\marg{label}\marg{height}}
955
956 This command draws an edge with label \marg{label} from the group identified with \marg{from-gid} to the group identified \marg{to-grid}. The horizontal segment of the edge will be \marg{height} distant from the words. Just as |\depedge|, also |\groupedge| honors the global edge positioning set via |dependency|. Also in this case, you can use the keys |/depgraph/edge below| and |/depgraph/edge above| to override the directive locally. More generally, all the key-value pairs that can be passed to |\depedge| (e.g., |edge slant|) can also be used with |\groupedge|. The two macros actually do the same thing, with the difference that |\depedge| automatically calculates a default height for the edge based on the word-distance between its endpoints.
957 \begin{codeexample}[]
958 \begin{dependency}
959 \begin{deptext}[column sep=.5cm, row sep=.1ex]
960 PRP\$ \& NN \& RB \&[.5cm] VBZ \& VBG \& NN \\
961 My \& dog \& also \& likes \& eating \& sausage \\
962 \end{deptext}
963 \deproot{4}{root}
964 \depedge{2}{1}{poss}
965 \depedge{4}{2}{nsubj}
966 \depedge{4}{3}{advmod}
967 \depedge{4}{5}{xcomp}
968 \depedge{5}{6}{dobj}
969 \wordgroup{2}{4}{4}{pred}
970 \wordgroup{2}{1}{2}{a0}
971 \wordgroup{2}{5}{6}{a1}
972 \groupedge[edge below]{pred}{a0}{ARG0}{4ex} % pred -> a0 (ARG0, 4ex)
973 \groupedge[edge below]{pred}{a1}{ARG1}{6ex} % pred -> a1 (ARG1, 6ex)
974 \end{dependency}
975 \end{codeexample}
976 \end{command}
977
978 \section{Styling text, edges and labels}\label{sec:styling}
979
980 This section covers the ways in which you can customize the look of the building blocks of the dependency graph: words, groups, edges and edge labels. Styling requires some basic knowledge of \tikzname{} styling facilities. For those who really don't want to read to read the glorious manual of \tikzname{}\footnote{\url{http://ftp.gui.uva.es/sites/ctan.org/graphics/pgf/base/doc/generic/pgf/pgfmanual.pdf}} (you really should, for your own sake), in Appendix~\ref{sec:tikz} I do my best to try to summarize a minimum of information that should be enough to get you started.
981
982 \subsection{Using themes}
983
984 \index{themes}\index{theming}The simplest way to change the look and feel of your dependency graphs is to use a pre-defined \emph{theme}.
985
986 \begin{key}{/depgraph/theme=\meta{theme name} (default default)}
987 By passing this option to |dependency|, you can completely change the appearence of the graphs. At the moment of writing, the following five themes have been defined: |default|, |simple|, |night|, |brazil|, |grassy|, |iron|, |copper|. They look like this:
988
989 \begin{codeexample}[]
990 \begin{dependency}[theme=default]
991 \begin{deptext}[column sep=.5cm, row sep=.1ex]
992 PRP\$ \& NN \& RB \&[.5cm] VBZ \& VBG \& NN \\
993 My \& dog \& also \& likes \& eating \& sausage \\
994 \end{deptext}
995 \deproot{4}{root}
996 \depedge{2}{1}{poss}
997 \depedge{4}{2}{nsubj}
998 \depedge{4}{3}{advmod}
999 \depedge{4}{5}{xcomp}
1000 \depedge{5}{6}{dobj}
1001 \end{dependency}
1002 \end{codeexample}
1003
1004 \begin{codeexample}[]
1005 \begin{dependency}[theme=simple]
1006 \begin{deptext}[column sep=.5cm, row sep=.1ex]
1007 PRP\$ \& NN \& RB \&[.5cm] VBZ \& VBG \& NN \\
1008 My \& dog \& also \& likes \& eating \& sausage \\
1009 \end{deptext}
1010 \deproot{4}{root}
1011 \depedge{2}{1}{poss}
1012 \depedge{4}{2}{nsubj}
1013 \depedge{4}{3}{advmod}
1014 \depedge{4}{5}{xcomp}
1015 \depedge{5}{6}{dobj}
1016 \end{dependency}
1017 \end{codeexample}
1018
1019 \begin{codeexample}[]
1020 \begin{dependency}[theme=night]
1021 \begin{deptext}[column sep=.5cm, row sep=.1ex]
1022 PRP\$ \& NN \& RB \&[.5cm] VBZ \& VBG \& NN \\
1023 My \& dog \& also \& likes \& eating \& sausage \\
1024 \end{deptext}
1025 \deproot{4}{root}
1026 \depedge{2}{1}{poss}
1027 \depedge{4}{2}{nsubj}
1028 \depedge{4}{3}{advmod}
1029 \depedge{4}{5}{xcomp}
1030 \depedge{5}{6}{dobj}
1031 \end{dependency}
1032 \end{codeexample}
1033
1034 \begin{codeexample}[]
1035 \begin{dependency}[theme=brazil]
1036 \begin{deptext}[column sep=.5cm, row sep=.1ex]
1037 PRP\$ \& NN \& RB \&[.5cm] VBZ \& VBG \& NN \\
1038 My \& dog \& also \& likes \& eating \& sausage \\
1039 \end{deptext}
1040 \deproot{4}{root}
1041 \depedge{2}{1}{poss}
1042 \depedge{4}{2}{nsubj}
1043 \depedge{4}{3}{advmod}
1044 \depedge{4}{5}{xcomp}
1045 \depedge{5}{6}{dobj}
1046 \end{dependency}
1047 \end{codeexample}
1048
1049 \begin{codeexample}[]
1050 \begin{dependency}[theme=grassy]
1051 \begin{deptext}[column sep=.5cm, row sep=.1ex]
1052 PRP\$ \& NN \& RB \&[.5cm] VBZ \& VBG \& NN \\
1053 My \& dog \& also \& likes \& eating \& sausage \\
1054 \end{deptext}
1055 \deproot{4}{root}
1056 \depedge{2}{1}{poss}
1057 \depedge{4}{2}{nsubj}
1058 \depedge{4}{3}{advmod}
1059 \depedge{4}{5}{xcomp}
1060 \depedge{5}{6}{dobj}
1061 \end{dependency}
1062 \end{codeexample}
1063
1064 \begin{codeexample}[]
1065 \begin{dependency}[theme=iron]
1066 \begin{deptext}[column sep=.5cm, row sep=.1ex]
1067 PRP\$ \& NN \& RB \&[.5cm] VBZ \& VBG \& NN \\
1068 My \& dog \& also \& likes \& eating \& sausage \\
1069 \end{deptext}
1070 \deproot{4}{root}
1071 \depedge{2}{1}{poss}
1072 \depedge{4}{2}{nsubj}
1073 \depedge{4}{3}{advmod}
1074 \depedge{4}{5}{xcomp}
1075 \depedge{5}{6}{dobj}
1076 \end{dependency}
1077 \end{codeexample}
1078
1079 \begin{codeexample}[]
1080 \begin{dependency}[theme=copper]
1081 \begin{deptext}[column sep=.5cm, row sep=.1ex]
1082 PRP\$ \& NN \& RB \&[.5cm] VBZ \& VBG \& NN \\
1083 My \& dog \& also \& likes \& eating \& sausage \\
1084 \end{deptext}
1085 \deproot{4}{root}
1086 \depedge{2}{1}{poss}
1087 \depedge{4}{2}{nsubj}
1088 \depedge{4}{3}{advmod}
1089 \depedge{4}{5}{xcomp}
1090 \depedge{5}{6}{dobj}
1091 \end{dependency}
1092 \end{codeexample}
1093 \end{key}
1094
1095 \begin{keylist}[/depgraph]{edge theme=\meta{theme name} (default default),label theme=\meta{theme name} (default default),text theme=\meta{theme name} (default default)}
1096 Each of the aforementioned themes is actually a combination of three themes with the same name: one for edges, one for edge labels and one for the sentence text. These three themes can also be applied independently. So, for example, you could apply the |iron| theme globally and then use |copper| to draw the labels:
1097 \begin{codeexample}[]
1098 \begin{dependency}[theme=iron, label theme=copper]
1099 \begin{deptext}[column sep=.5cm, row sep=.1ex]
1100 PRP\$ \& NN \& RB \&[.5cm] VBZ \& VBG \& NN \\
1101 My \& dog \& also \& likes \& eating \& sausage \\
1102 \end{deptext}
1103 \deproot{4}{root}
1104 \depedge{2}{1}{poss}
1105 \depedge{4}{2}{nsubj}
1106 \depedge{4}{3}{advmod}
1107 \depedge{4}{5}{xcomp}
1108 \depedge{5}{6}{dobj}
1109 \end{dependency}
1110 \end{codeexample}
1111 \end{keylist}
1112
1113 Edges and labels can be styled locally, by passing the desired |theme|, |label theme| or |edge theme| to specific edges. In the following example, I will use |iron| as the base |theme|, globally overriding the |label theme| with |copper| and using |grassy| as the |theme| and |label theme| two special edges:
1114 \begin{codeexample}[]
1115 \begin{dependency}[theme=iron, label theme=copper]
1116 \begin{deptext}[column sep=.5cm, row sep=.1ex]
1117 PRP\$ \& NN \& RB \&[.5cm] VBZ \& VBG \& NN \\
1118 My \& dog \& also \& likes \& eating \& sausage \\
1119 \end{deptext}
1120 \deproot{4}{root}
1121 \depedge[theme=grassy]{2}{1}{poss}
1122 \depedge{4}{2}{nsubj}
1123 \depedge{4}{3}{advmod}
1124 \depedge[label theme=grassy]{4}{5}{xcomp}
1125 \depedge{5}{6}{dobj}
1126 \end{dependency}
1127 \end{codeexample}
1128
1129 \subsection{Styling elements individually}
1130
1131 \begin{keylist}{/depgraph/hide label=\meta{boolean} (default false),/depgraph/show label=\meta{boolean} (default true)}
1132 By default, all labels are visible. Add |hide label| to the \options{} of |\depedge| or |\groupedge| to prevent the bounding box and the text of the label to be drawn.
1133 \begin{codeexample}[]
1134 \begin{dependency}
1135 \begin{deptext}[column sep=.5cm, row sep=.1ex]
1136 PRP\$ \& NN \& RB \&[.5cm] VBZ \& VBG \& NN \\
1137 My \& dog \& also \& likes \& eating \& sausage \\
1138 \end{deptext}
1139 \deproot{4}{root}
1140 \depedge{2}{1}{poss}
1141 \depedge{4}{2}{nsubj}
1142 \depedge{4}{3}{advmod}
1143 \depedge{4}{5}{xcomp}
1144 \depedge[hide label]{5}{6}{dobj}
1145 \end{dependency}
1146 \end{codeexample}
1147 If added to the options of |dependency|, all the labels will be suppressed. Local overriding is still possible by adding the |/depgraph/show label| key:
1148 \begin{codeexample}[]
1149 \begin{dependency}[hide label]
1150 \begin{deptext}[column sep=.5cm, row sep=.1ex]
1151 PRP\$ \& NN \& RB \&[.5cm] VBZ \& VBG \& NN \\
1152 My \& dog \& also \& likes \& eating \& sausage \\
1153 \end{deptext}
1154 \deproot{4}{root}
1155 \depedge{2}{1}{poss}
1156 \depedge{4}{2}{nsubj}
1157 \depedge{4}{3}{advmod}
1158 \depedge{4}{5}{xcomp}
1159 \depedge[show label]{5}{6}{dobj}
1160 \end{dependency}
1161 \end{codeexample}
1162 Please, note that the labels are still there, only they are transparent.
1163 \end{keylist}
1164
1165
1166 \begin{stylekey}{/depgraph/edge style=\meta{style} (default \{\})}
1167 This style is applied to all the edges drawn by \pkgname{}. By setting its value you can alter the appearance of the dependency edges. The default style applied to every edge is:
1168 \begin{codeexample}[code only]
1169 \pgfkeys{%
1170 /depgraph/reserved/edge style/.style = {%
1171 ->, >=stealth, %arrow properties
1172 black, solid, line cap=round, %line properties
1173 rounded corners=2, %make corners round
1174 },%
1175 }
1176 \end{codeexample}
1177 By setting |edge style| at the |dependency| level, all the edges in the graph are affected:
1178 \begin{codeexample}[]
1179 \begin{dependency}[edge style={red,densely dotted}]
1180 \begin{deptext}[column sep=.5cm, row sep=.1ex]
1181 PRP\$ \& NN \& RB \&[.5cm] VBZ \& VBG \& NN \\
1182 My \& dog \& also \& likes \& eating \& sausage \\
1183 \end{deptext}
1184 \deproot{4}{root}
1185 \depedge{2}{1}{poss}
1186 \depedge{4}{2}{nsubj}
1187 \depedge{4}{3}{advmod}
1188 \depedge{4}{5}{xcomp}
1189 \depedge{5}{6}{dobj}
1190 \end{dependency}
1191 \end{codeexample}
1192 As always, local settings at the edge level take precedence over global settings:
1193 \begin{codeexample}[]
1194 \begin{dependency}[edge style={green!60!black,very thick}]
1195 \begin{deptext}[column sep=.5cm, row sep=.1ex]
1196 PRP\$ \& NN \& RB \&[.5cm] VBZ \& VBG \& NN \\
1197 My \& dog \& also \& likes \& eating \& sausage \\
1198 \end{deptext}
1199 \deproot{4}{root}
1200 \depedge[edge style={blue!60!black,ultra thick}]{2}{1}{poss}
1201 \depedge{4}{2}{nsubj}
1202 \depedge{4}{3}{advmod}
1203 \depedge{4}{5}{xcomp}
1204 \depedge{5}{6}{dobj}
1205 \end{dependency}
1206 \end{codeexample}
1207 \end{stylekey}
1208
1209 \begin{stylekey}{/depgraph/label style=\meta{style} (default \{\})}
1210 The default style applied to every label is the following:
1211 \begin{codeexample}[code only]
1212 \pgfkeys{%
1213 /depgraph/reserved/label style/.style = {%
1214 draw, solid, black, %the outline of the label
1215 scale=.7, %scale down the text, to make it smaller than the sentence text
1216 text=black, %color of the text
1217 text height=1.5ex, %needed to center text vertically
1218 text depth=0.25ex, %needed to center text vertically
1219 inner sep=.5ex, %padding between the text and the border of the node
1220 fill=white, %background color
1221 outer sep=0pt,
1222 rounded corners=2pt,
1223 anchor=mid,
1224 },%
1225 }
1226 \end{codeexample}
1227 The look of labels can be changed by defining the |label style| style, either locally to each edge or globally:
1228 \begin{codeexample}[]
1229 \begin{dependency}[edge style={green!60!black,very thick},
1230 label style={fill=yellow!60,font=\bfseries,thick}]
1231 \begin{deptext}[column sep=.5cm, row sep=.1ex]
1232 PRP\$ \& NN \& RB \&[.5cm] VBZ \& VBG \& NN \\
1233 My \& dog \& also \& likes \& eating \& sausage \\
1234 \end{deptext}
1235 \deproot{4}{root}
1236 \depedge[edge style={blue!60!black,ultra thick},
1237 label style={fill=green!60,font=\bfseries,text=black}]{2}{1}{poss}
1238 \depedge{4}{2}{nsubj}
1239 \depedge{4}{3}{advmod}
1240 \depedge{4}{5}{xcomp}
1241 \depedge{5}{6}{dobj}
1242 \end{dependency}
1243 \end{codeexample}
1244 \end{stylekey}
1245
1246 \begin{stylekey}{/depgraph/group style=\meta{style} (default \{\})}
1247 By default, when you create a group you will only see a box with rounded corners around the selected words:
1248 \begin{codeexample}[]
1249 \begin{dependency}
1250 \begin{deptext}[column sep=.5cm, row sep=.1ex]
1251 PRP\$ \& NN \& RB \&[.5cm] VBZ \& VBG \& NN \\
1252 My \& dog \& also \& likes \& eating \& sausage \\
1253 \end{deptext}
1254 \deproot{4}{root}
1255 \depedge{2}{1}{poss}
1256 \depedge{4}{2}{nsubj}
1257 \depedge{4}{3}{advmod}
1258 \depedge{4}{5}{xcomp}
1259 \depedge{5}{6}{dobj}
1260 \wordgroup{2}{1}{2}{a0}
1261 \wordgroup{2}{5}{6}{a1}
1262 \end{dependency}
1263 \end{codeexample}
1264 The |group style| property allows you to redefine this style according to your taste and needs:
1265 \begin{codeexample}[]
1266 \begin{dependency}
1267 \begin{deptext}[column sep=.5cm, row sep=.5ex]
1268 PRP\$ \& NN \& RB \&[.5cm] VBZ \& VBG \& NN \\
1269 My \& dog \& also \& likes \& eating \& sausage \\
1270 \end{deptext}
1271 \deproot{4}{root}
1272 \depedge{2}{1}{poss}
1273 \depedge{4}{2}{nsubj}
1274 \depedge{4}{3}{advmod}
1275 \depedge{4}{5}{xcomp}
1276 \depedge{5}{6}{dobj}
1277 \wordgroup[group style={fill=orange!40, draw=brown, inner sep=.6ex}]{2}{1}{2}{a0}
1278 \end{dependency}
1279 \end{codeexample}
1280 Please, keep in mind that a group is just a box drawn \emph{underneath} the word nodes. They have no text themselves, as the text that they surround is actually the text of some word node. Therefore, you cannot use |group style| to change in any way the rendering of the words they group.
1281 \end{stylekey}
1282
1283 \begin{stylekey}{/tikz/nodes=\meta{style} (default \{\})}
1284 This is an \tikzname{} style key used to render the nodes within a given scope. By using it within a |deptext|, you can assign a style to all the nodes in the matrix, i.e. the words in the sentence:
1285 \begin{codeexample}[]
1286 \begin{dependency}[edge style={green!60!black,very thick},
1287 label style={fill=blue!60,font=\bfseries,text=white}]
1288 \begin{deptext}[column sep=.5cm, row sep=.1ex,
1289 nodes={draw=red!80!black, shade, top color=red!60, rounded corners}]
1290 PRP\$ \& NN \& RB \&[.5cm] VBZ \& VBG \& NN \\
1291 My \& dog \& also \& likes \& eating \& sausage \\
1292 \end{deptext}
1293 \deproot{4}{root}
1294 \depedge[edge style={blue!60!black,ultra thick},
1295 label style={fill=green!60,font=\bfseries,text=black}]{2}{1}{poss}
1296 \depedge{4}{2}{nsubj}
1297 \depedge{4}{3}{advmod}
1298 \depedge{4}{5}{xcomp}
1299 \depedge{5}{6}{dobj}
1300 \end{dependency}
1301 \end{codeexample}
1302 The style can be overridden on a per-node basis, by using a special syntax understood by matrix that allows to set style properties of each node individually. To to so, you need to add \cmdname{|[}|<style>|\cmdname{]|} before every word that you want to restyle, where \meta{style} is a style definition. The following example shows how you would apply a different style to all the nodes in the second row:
1303 {\pipeescape
1304 \begin{codeexample}[]
1305 \begin{dependency}[edge style={green!60!black,very thick},
1306 label style={fill=blue!60,font=\bfseries,text=white}]
1307 \tikzstyle{POS}=[font=\footnotesize\bfseries,text=blue!60!black]
1308 \tikzstyle{word}=[draw=blue!60!black, shade, text=black,
1309 rotate=45, anchor=north east, inner sep=1ex,
1310 font=\normalsize, top color=blue!60, rounded corners]
1311 \begin{deptext}[column sep=.5cm, row sep=0, nodes={POS}]
1312 PRP\$ \& NN \& RB \&[.5cm] VBZ \& VBG \& NN \\
1313 |[word]| My \& |[word]| dog \& |[word]| also \&
1314 |[word]| likes \& |[word]| eating \& |[word]| sausage \\
1315 \end{deptext}
1316 \deproot{4}{root}
1317 \depedge[edge style={blue!60!black,ultra thick},
1318 label style={fill=green!60,font=\bfseries,text=black, rotate=10}]{2}{1}{poss}
1319 \depedge{4}{2}{nsubj}
1320 \depedge{4}{3}{advmod}
1321 \depedge{4}{5}{xcomp}
1322 \depedge{5}{6}{dobj}
1323 \end{dependency}
1324 \end{codeexample}
1325 }
1326 When using this syntax, you should always consider that the |nodes| style is in any case applied to \emph{every node} in the |matrix|, then the style specified for each node (if any) is appended. This fact has the subtle implication that all the nodes inherit all the properties set via |nodes|, and per-node styles must explicitly overwrite all the properties that they don't need to use. As a rule of thumb, you should use |nodes| to set properties that all the nodes will share, and then use per-node options to add or override options.
1327 \end{stylekey}
1328
1329 \subsection{Defining your own styles}
1330
1331 \begin{command}{\depstyle\marg{style-name}\marg{style-definition}}
1332
1333 Defining your own styles is a convenient way of using a consistent look for all your graphs across a document, at the same time avoiding a lot of unnecessary typing. |\depstyle| is a wrapper around |\tikzset| (see Section~\ref{sec:tikz}) with the advantage that you do not have to prepend |/depgraph| to all the styling keys that are defined by \pkgname{}. |\depstyle| automatically forwards to \tikzname{} all the keys that it does not how to handle.
1334
1335 In the following example I will define and use two styles. The first style results in thick blue edges, labels with a thick red outline, blue text and white background; the second style also uses a predefined themes.
1336
1337 \begin{codeexample}[]
1338 \depstyle{red and blue}{edge style = {thick, blue},
1339 label style = {thick, draw=red, text=blue, fill=white}}
1340 \depstyle{collage}{edge theme = grassy, label style={draw=orange,trapezium}}
1341 \begin{dependency}[red and blue]
1342 \begin{deptext}[column sep=.5cm, row sep=.5ex]
1343 PRP\$ \& NN \& RB \&[.5cm] VBZ \&[.2cm] VBG \& NN \\
1344 My \& dog \& also \& likes \& eating \& sausage \\
1345 \end{deptext}
1346 \deproot{4}{root}
1347 \depedge{2}{1}{poss}
1348 \depedge{4}{2}{nsubj}
1349 \depedge{4}{3}{advmod}
1350 \depedge[collage]{4}{5}{xcomp}
1351 \depedge[collage]{5}{6}{dobj}
1352 \end{dependency}
1353 \end{codeexample}
1354
1355 Note how the labels in the style |collage| inherit the background and the text color of |red and blue| labels. This happens because the |red and blue| style is applied at the |dependency| level, meaning that it is applied to all the labels. Then, the |collage| style is applied to the labels of the last two edges. Since this style only overrides the color of the outline (|draw|), all the other properties are inherited from |red and blue|.
1356 \end{command}
1357
1358 \section{Interaction with \tikzname{}}
1359
1360 Some function make it possible to reference the nodes in the graph so that it is easier to extend the graph with \tikzname{} drawing capabilities. Understanding what is going on here requires at least some basic knowledge of how to draw nodes and paths in \tikzname{}.
1361
1362 \begin{command}{\matrixref}
1363 Returns a reference to the |\matrix| used to lay out the sentence. You can use it to position other elements in the picture relative to it.
1364 \begin{codeexample}[]
1365 \begin{dependency}
1366 \begin{deptext}[column sep=.5cm, row sep=.1ex]
1367 PRP\$ \& NN \& RB \&[.5cm] VBZ \& VBG \& NN \\
1368 My \& dog \& also \& likes \& eating \& sausage \\
1369 \end{deptext}
1370 \deproot{4}{root}
1371 \depedge{2}{1}{poss}
1372 \depedge{4}{2}{nsubj}
1373 \depedge{4}{3}{advmod}
1374 \depedge{4}{5}{xcomp}
1375 \depedge{5}{6}{dobj}
1376 \foreach \a/\pos in {south/below of,north/above of,east/right of,west/left of} {
1377 \node (tmp) at (\matrixref.\a) [draw, circle, fill=red, inner sep=1pt] {};
1378 \node (tmp2) [\pos = tmp] {\a} -- (tmp);
1379 \draw [->] (tmp2) -- (tmp);
1380 };
1381 \end{dependency}
1382 \end{codeexample}
1383
1384 \end{command}
1385
1386 \begin{command}{\wordref\marg{row-offset}\marg{word-offset}}
1387
1388 Returns the reference to the matrix node in row \marg{row-offset} and column \marg{word-offset}.
1389
1390 \begin{codeexample}[]
1391 \begin{dependency}
1392 \begin{deptext}[column sep=.5cm, row sep=.1ex]
1393 PRP\$ \& NN \& RB \&[.5cm] VBZ \& VBG \& NN \\
1394 My \& dog \& also \& likes \& eating \& sausage \\
1395 \end{deptext}
1396 \deproot{4}{root}
1397 \depedge{2}{1}{poss}
1398 \depedge{4}{2}{nsubj}
1399 \depedge{4}{3}{advmod}
1400 \depedge{4}{5}{xcomp}
1401 \depedge{5}{6}{dobj}
1402 \node (silly1) [above right of = \wordref{1}{6}, xshift = 2cm] {Top right};
1403 \node (silly2) [below left of = \wordref{2}{1}, xshift = -2cm] {Bottom left};
1404 \draw [->, very thick, red] (silly1) -- (\wordref{1}{6});
1405 \draw [->, very thick, red] (silly2) -- (\wordref{2}{1});
1406 \end{dependency}
1407 \end{codeexample}
1408 \end{command}
1409
1410 \begin{command}{\rootref}
1411 Returns a reference to the node holding the root label.
1412 \begin{codeexample}[]
1413 \begin{dependency}
1414 \begin{deptext}[column sep=.5cm, row sep=.1ex]
1415 PRP\$ \& NN \& RB \&[.5cm] VBZ \& VBG \& NN \\
1416 My \& dog \& also \& likes \& eating \& sausage \\
1417 \end{deptext}
1418 \deproot{4}{root}
1419 \depedge{2}{1}{poss}
1420 \depedge{4}{2}{nsubj}
1421 \depedge{4}{3}{advmod}
1422 \depedge{4}{5}{xcomp}
1423 \depedge{5}{6}{dobj}
1424 \node (silly) [above right of = \rootref, xshift = 3cm] {This is the root node!};
1425 \draw [->, very thick, red] (silly) -- (\rootref);
1426 \draw [thick, blue] (\rootref)--(\wordref{1}{2})--(\wordref{2}{6})--(\rootref);
1427 \end{dependency}
1428 \end{codeexample}
1429
1430 \end{command}
1431
1432 \begin{commandlist}{\storelabelnode\marg{macro},\storefirstcorner\marg{macro},\storesecondcorner\marg{macro}}
1433 After adding a new edge with |\depedge| or |\groupedge|, three commands allow you to store the name of the nodes used to draw the label end the corners of the dependency edge. |\storelabelnode| can be used to store the name of the label in the macro \meta{macro}. You can then use \meta{macro} just as you would use any node, to draw something involving the label node. |\storefirstcorner| and |\storesecondcorner| work exactly in the same way, but they hold they point to the nodes holding the coordinates of the edge corners.
1434
1435 \begin{codeexample}[]
1436 \begin{dependency}
1437 \begin{deptext}[column sep=.5cm, row sep=.1ex]
1438 PRP\$ \& NN \& RB \&[.5cm] VBZ \& VBG \& NN \\
1439 My \& dog \& also \& likes \& eating \& sausage \\
1440 \end{deptext}
1441 \deproot{4}{root}
1442 \depedge{2}{1}{poss}
1443 \storelabelnode\firstlab
1444 \storefirstcorner\firstcorner
1445 \depedge{4}{2}{nsubj}
1446 \depedge{4}{3}{advmod}
1447 \depedge{4}{5}{xcomp}
1448 \depedge{5}{6}{dobj}
1449 \storelabelnode\secondlab
1450 \storesecondcorner\secondcorner
1451 \draw [<->,out=90,in=-90, thick, red] (\firstlab) to
1452 node [fill=red, text=white, font=\bfseries, above, near start, sloped]
1453 {labels!} (\secondlab);
1454 \draw [<->, out=-90,in=90, thick, blue!60] (\firstcorner) to
1455 node [fill=blue!60, text=white, font=\bfseries, above, near end, sloped]
1456 {edge corners!} (\secondcorner);
1457 \end{dependency}
1458 \end{codeexample}
1459 \end{commandlist}
1460
1461 \section{Answers to frequent or interesting questions}
1462
1463 This section shows practical examples of how to achieve specific results with \pkgname{} that may not seem that obvious.
1464
1465 \subsection{How do I change the shape of label nodes?}
1466
1467 By default, \pkgname{} uses \tikzname{}'s |rounded corners| shape to draw the labels, but you can use every shape that you want. By default, \tikzname{} defines the |rectangle|, |rounded corners| and |circle| shapes. More shapes are available via the |shapes| library, which \pkgname{} already loads for you. As always, for more information you can refer to \tikzname{} manual.
1468
1469 To change the shape of labels, you simply add the shape name to, |edge style|, as in the following examples:
1470
1471 \begin{codeexample}[]
1472 \begin{dependency}[label style = {circle}]
1473 \begin{deptext}[column sep=.5cm, row sep=.1ex]
1474 PRP\$ \& NN \& RB \&[.5cm] VBZ \\
1475 My \& dog \& also \& likes \& \dots \\
1476 \end{deptext}
1477 \deproot{4}{root}
1478 \depedge{2}{1}{poss}
1479 \depedge{4}{2}{nsubj}
1480 \depedge{4}{3}{advmod}
1481 \end{dependency}
1482 \qquad
1483 \begin{dependency}[label style = {trapezium}]
1484 \begin{deptext}[column sep=.5cm, row sep=.1ex]
1485 PRP\$ \& NN \& RB \&[.5cm] VBZ \\
1486 My \& dog \& also \& likes \& \dots \\
1487 \end{deptext}
1488 \deproot[label style = {star}]{4}{root}
1489 \depedge{2}{1}{poss}
1490 \depedge{4}{2}{nsubj}
1491 \depedge{4}{3}{advmod}
1492 \end{dependency}
1493 \end{codeexample}
1494
1495 \subsection{How do I draw bubble parses?}
1496
1497 Until a user of \pkgname{} asked me how to draw them, I was not even aware that these things existed. Anyway, it turns out that is quite simple to draw bubble parses with \pkgname{}, and that |\wordgroup| is basically all you need.
1498
1499 Until I or someone else writes some facilities to explicitly support these beauties, you will have to take care of the details explicitly. What you have to do is:
1500 \begin{itemize}
1501 \item use |\wordgroup| to create bubbles;
1502 \item use |inner sep| and |minimum height| with |group style| to create bubbles of the desired size;
1503 \item increase the values of |inner sep| and |minimum height| for more external bubbles;
1504 \item use |\groupedge| to create edges between bubbles.
1505 \end{itemize}
1506 \noindent The follow example should give you a good starting point:
1507
1508 \begin{codeexample}[]
1509 \depstyle{inner bubble}{draw=gray!80, minimum height=20pt, rounded corners=8pt,
1510 inner sep=2pt, top color=gray!40, bottom color=white}
1511 \depstyle{outer bubble}{draw=gray!80, minimum height=26pt, rounded corners=10pt,
1512 inner sep=5pt, top color=white, bottom color=gray!40}
1513 \depstyle{ungrammatical}{edge below, edge style = {ultra thick, red},
1514 label style = {below, text=red}, text only label}
1515 \begin{dependency}[hide label, arc edge,
1516 edge vertical padding=-2pt,
1517 group style=outer bubble]
1518 \begin{deptext}[column sep=1.4em]
1519 a \& student \& whose \& mother \& and \& his \& father \& peter \& knows \\
1520 \end{deptext}
1521 \wordgroup{1}{3}{7}{chubby}
1522 \wordgroup{1}{1}{2}{first} \depedge{2}{1}{}
1523 \wordgroup[inner bubble]{1}{3}{4}{second} \depedge{4}{3}{}
1524 \wordgroup[inner bubble]{1}{6}{7}{third} \depedge{7}{6}{}
1525 \wordgroup{1}{8}{8}{fourth}
1526 \wordgroup{1}{9}{9}{fifth}
1527 \groupedge{fifth}{fourth}{}{0}
1528 \groupedge[ungrammatical]{first}{second}{ungrammatical}{.5cm}
1529 \groupedge[edge above]{second}{fifth}{}{1.5cm}
1530 \groupedge[edge above]{fifth}{chubby}{}{1cm}
1531 \end{dependency}%
1532 \end{codeexample}
1533
1534 When using |fill| or |shade| with |\wordgroup|, as in the example, be aware of the fact that the nodes are drawn in the order that you write them down. For this reason, larger bubbles should always be drawn first, and the contained bubbles afterwards. Otherwise, the inner bubbles will be covered by the outer one.
1535
1536 \appendix
1537
1538 \section{\tikzname{} crash course} \label{sec:tikz}
1539
1540 \textbf{Disclaimer.} \textit{I am making a lot of rough simplifications here to make it possible to explain everything in as little space as possible. I really invite you to read the full version of the manual, if you haven't already. It is the only way to really appreciate the elegance and the full potential of \tikzname{}.}
1541
1542 \vspace{1cm}
1543
1544 PGF/\tikzname{} is a set of lower/higher level macros that allow you to draw extremely refined and sophisticated graphics directly in \LaTeX{}. If you don't know anything about it, then you are really missing on something, and you should run and check the manual\footnote{\url{http://ftp.gui.uva.es/sites/ctan.org/graphics/pgf/base/doc/generic/pgf/pgfmanual.pdf}}. I am repeating myself, but you really should.
1545
1546 \subsection{\texttt{\textbackslash pgfkeys} and \texttt{\textbackslash tikzset}}
1547
1548 \index{key!key-value pairs}
1549 \tikzname{} is basically built on top of |pgfkeys|, which is a very flexible and sophisticated system to store key-value pairs. \tikzname{} (and derived packages such as \pkgname{}) use this system for setting local or global variables, and to pass optional arguments to commands (macros) that can take a large number of configuration option.
1550
1551 The definition of virtually all \tikzname{} macros follows the template:
1552
1553 \cmdname\somecommand\options\marg{first}\dots\marg{last}
1554
1555 The first argument, optional, is a set of key-value pairs that can be used to set a bunch of options. It is thus possible to reduce to a minimum the number of mandatory arguments \marg{first}\dots\marg{last}, and keep a macro's interface lighter and simpler to use. A command first parses the key-value pairs, then do what it has to do based on the updated state of these variables.
1556
1557 Key names and values can contain spaces, values can be assigned via the |=| sign and commas can be used to separate assignments. Curly braces can be used for grouping values. So, for example, the assignment |variable one = {a, b}, vartwo = c| would result in the set |{a, b}| being assigned to |variable one| and |c| to |vartwo|.
1558
1559 The function which is responsible for parsing key-value pairs is |\pgfkeys|:
1560
1561 \begin{command}{\pgfkeys\marg{keys}}
1562 The |\pgfkeys| command parses a string containing a sequence of keys and stores their value, e.g.:
1563 \begin{codeexample}[code only]
1564 \pgfkeys{a=1, b=2, c={d=3,e=4}}
1565 \end{codeexample}
1566 In this case, the value of the key |a| is set to |a| and |b| to 2. |c| contains two keys, |d| and |e|, whose values are |3| and |4|, respectively. How this values can be accessed is of no interest for the scope of this document. We only want to be able to set those keys. Please, note that you can only set the values for keys that already exist. How a key can be created is also of no interest for us, as we only want to be able to change the values of existing keys.
1567 \end{command}
1568
1569 Keys can be arranged hierarchically, as in a directory structure. This property allows every sub-package to define its own protected space of keys, making it less likely to cause interaction problems. All \tikzname{} keys are stored under the root key |/tikz/|. So, for example, |/tikz/fill=blue| assigns the value |blue| to the |fill| key within the namespace |/tikz/|. \pkgname{} defines its own namespace, which is |/depgraph/|, and defines its own subset of keys that interact with \tikzname{}' own.
1570
1571 As a convenience function, \tikzname{} also defines the following macro:
1572
1573 \begin{command}{\tikzset\marg{keys}}
1574 |\tikzset| is just a wrapper around |\pgfkeys|, that prefixes all keys with |/tikz/|. The two following instructions are (for us) equivalent:
1575 \begin{codeexample}[code only]
1576 \pgfkeys{/tikz/text=red, /tikz/fill=white}
1577 \tikzset{text=red, fill=white}
1578 \end{codeexample}
1579 \end{command}
1580
1581 Some keys only have a name\index{key!without a value} and no value. Without going into details, it won't hurt to know that such keys are either \emph{binary}\index{key!binary} flags or one of a set of alternative options (\emph{choice} keys)\index{key!choice}, so that activating one automatically deactivates the other alternatives in the set.
1582
1583 Conveniently, |\pgfkeys| also define an inheritance mechanism that allows sub-packages to consume the keys that they can understand, and then pass on to \tikzname{} all the keys that haven't been handled. This fact also makes it possible for a user to specify a key without using its fully qualified name. When introducing a key for the first time, I generally use its fully qualified name, just to make it clear where it belongs. In the examples, though, I generally prefer to use a more compact notation and only use the ``base name'' of the keys.
1584
1585 \subsection{Basic styling notions}
1586
1587 A style is a set of key-value pairs (we have seen many already in the previous pages) that define the properties of some graphical object. As an example, |{draw=red, thick}| is a style (we will soon come to the meaning of these properties).
1588
1589 The simplest way to define a new style is with the |\tikzstyle| command:
1590
1591 \begin{command}{\tikzstyle\marg{name}=\options}
1592 \index{style!define new}
1593 Here, \marg{name} is just an identifier for your style (such as |my style|, or |very cool|, whatever). \options{} is a sequence of comma separated key-value pairs, e.g.:
1594 \begin{codeexample}[code only]
1595 \tikzstyle{my cool style} = [draw=black, fill=red]
1596 \end{codeexample}
1597 \index{style!update definition}
1598 Once a style is defined, you can ``add'' things to the style in at least two ways:
1599 \begin{itemize}
1600 \item By using the same syntax as before, but adding a |+| between \marg{name} and the |=| sign, e.g.,:
1601 \begin{codeexample}[code only]
1602 % before: my cool style = {draw=black, fill=red}
1603 \tikzstyle{my cool style} += [thick]
1604 % after: my cool style = {draw=black, fill=red, thick}
1605 \end{codeexample}
1606 \item By setting (via |\tikzset|) the special sub-property |.append style| of an already existent style, e.g.:
1607 \begin{codeexample}[code only]
1608 % before: my cool style = {draw=black, fill=red, thick}
1609 \tikzset{my cool style/.append style = {dotted}}
1610 % after: my cool style = {draw=black, fill=red, thick, dotted}
1611 \end{codeexample}
1612 \end{itemize}
1613 \end{command}
1614
1615 A dependency graph is built using two \tikzname{} primitives: \emph{nodes}\index{node} and \emph{paths}\index{path}. Dependency edges are paths. Edge labels and words in the sentence are nodes containing text. Word groups are also nodes, which are drawn on the layer \emph{underneath} the word nodes. They have no text themselves, as the text that they surround is actually the text of some word node.
1616
1617 Nodes have an \emph{outline}\index{outline} (i.e., a contour) and an \emph{area}\index{area} (the space inside the contour), and (generally) contain some text. All these properties can be styled independently, and the styling can be done either globally (in a way that affects all the graphics within a given scope) or locally (i.e., for each node individually). The same applies to paths, even though in this case you only have the outline to play with.
1618
1619 Let's briefly dive through the most relevant key-value pairs that can be used to configure these properties. My purpose here is just to provide a compact reference to understand the examples in the documentation.
1620
1621 \subsubsection{Outline properties}
1622 These describe the properties of lines. They apply to edges and to the contour of nodes (such as labels and words in the sentence)
1623 \begin{key}{/tikz/draw=\meta{color-spec}}
1624 This key tells tikz to actually draw the outline of a shape with the given color. If draw is not set, then the outline is not drawn. By default, outlines are not drawn. \meta{color-spec} can be a color name, such as |red|, |green| or |blue|, or a more complicated expression, such as |red!60!black|, which means ``make a new color made of red for 60\% of red, of black for the rest''. Colors can be specified in many other ways, which we won't cover here.
1625
1626 \end{key}
1627 \begin{keylist}[/tikz]{circle,ellipse,rectangle}
1628 Selecting one of this properties allows you to use a different shape to draw a node. When |draw| is selected, by default the node will be drawn as a |rectangle|.
1629 \end{keylist}
1630 \begin{key}{/tikz/rounded corners=\meta{length}}
1631 This property allows you to make corners round. The value that you assign to it is the amount of roundness.
1632 \end{key}
1633 \begin{keylist}[/tikz]{very thin,thin,thick,very thick}
1634 Can be used to set the width of a line. |thin| is the default value (corresponding to |0.4pt|).
1635 \end{keylist}
1636 \begin{keylist}[/tikz]{solid,dotted,loosely dotted,densely dotted,dashed,loosely dashed,densely dashed}
1637 Set the kind of line to be used to draw the outline. |solid| is the default (i.e. a continuous line).
1638 \end{keylist}
1639
1640 \subsubsection{Area properties}
1641 These describe the properties of areas. They apply to the background of nodes (such as labels, words in the sentence and word groups).
1642 \begin{key}{/tikz/fill=\meta{color-spec}}
1643 This key tells tikz to fill the inside of a shape (or a node) with a solid color. Color specification is the same as for |/tikz/draw|.
1644 \end{key}
1645 \begin{key}{/tikz/shade}
1646 Instead of filling the area with a solid color, fill it with a gradient.
1647 \end{key}
1648 \begin{keylist}[/tikz]{top color=\meta{color-spec},bottom color=\meta{color-spec},left color=\meta{color-spec},right color=\meta{color-spec}}
1649 Use these two keys to set up either a vertical or an horizontal gradient. Setting any of these properties automatically activates |shade|.
1650 \end{keylist}
1651 \begin{key}{/tikz/inner sep=\meta{length}}
1652 This parameter controls the distance between the outline of a node and its contents (e.g., the text inside the node).
1653 \end{key}
1654 \begin{keylist}[/tikz]{minimum height=\meta{length},minimum width=\meta{length}}
1655 By default, the size of a node is determined based on its content, i.e., it is just as big as to fit what's inside (plus padding and spacing, e.g., |inner sep|). By setting these keys, you can force a node to be at least as tall and/or wide as requested.
1656 \end{keylist}
1657
1658 \subsubsection{Text properties}
1659 These describe the properties of text boxes. They apply to the text of the sentence (the rows if the |matrix| wrapped by |deptext|) and to labels.
1660 \begin{key}{/tikz/text=\meta{color}}
1661 This key sets the color to be used to render the text.
1662 \end{key}
1663 \begin{key}{/tikz/font=\meta{fontmacros}}
1664 Set the font size/family/series/shape to be user to render the text. Every combination of these standard \LaTeX{} macros is a valid value for \meta{fontmacros}:
1665 |\normalsize|,
1666 |\small|,
1667 |\footnotesize|,
1668 |\tiny|,
1669 |\large|,
1670 |\huge|,
1671 |\rmfamily|,
1672 |\ttfamily|,
1673 |\sffamily|,
1674 |\mdseries|,
1675 |\bfseries|,
1676 |\upshape|,
1677 |\itshape|,
1678 |\scshape|,
1679 |\slshape|.
1680 \end{key}
1681
1682 \printindex
1683
1684 \end{document}