0
# Visualization
1

2
Interactive visualization tools for displaying linguistic analysis including dependency trees, named entities, and custom visualizations. spaCy's displaCy visualizer renders analysis results in HTML/SVG format for web browsers and Jupyter notebooks.
3

4
## Capabilities
5

6
### Rendering Functions
7

8
Core functions for generating HTML/SVG visualizations of linguistic analysis.
9

10
```python { .api }
11
def render(docs: Union[Doc, Span, List[Doc]], style: str = "dep",
12
           page: bool = False, minify: bool = False, 
13
           jupyter: bool = None, options: dict = None,
14
           manual: bool = False) -> str:
15
    """
16
    Render a visualization of linguistic analysis.
17
    
18
    Args:
19
        docs: Doc(s) or Span(s) to visualize
20
        style: Visualization style ('dep' or 'ent')
21
        page: Render as full HTML page  
22
        minify: Minify HTML output
23
        jupyter: Override Jupyter notebook detection
24
        options: Visualization options and settings
25
        manual: Don't parse Doc, use manual data
26
        
27
    Returns:
28
        HTML/SVG string of the visualization
29
    """
30

31
def serve(docs: Union[Doc, List[Doc]], style: str = "dep",
32
          port: int = 5000, host: str = "0.0.0.0",
33
          options: dict = None, manual: bool = False) -> None:
34
    """
35
    Serve visualizations on a web server.
36
    
37
    Args:
38
        docs: Doc(s) to visualize  
39
        style: Visualization style ('dep' or 'ent')
40
        port: Port number for web server
41
        host: Host address to bind to
42
        options: Visualization options and settings
43
        manual: Don't parse Doc, use manual data
44
    """
45
```
46

47
### Data Parsing Functions
48

49
Functions to extract visualization data from spaCy objects.
50

51
```python { .api }
52
def parse_deps(doc: Doc, options: dict = None) -> dict:
53
    """
54
    Parse a Doc object for dependency visualization.
55
    
56
    Args:
57
        doc: The Doc object to parse
58
        options: Visualization options
59
        
60
    Returns:
61
        Dictionary with dependency visualization data
62
    """
63

64
def parse_ents(doc: Doc, options: dict = None) -> dict:
65
    """
66
    Parse a Doc object for entity visualization.
67
    
68
    Args:
69
        doc: The Doc object to parse
70
        options: Visualization options
71
        
72
    Returns:
73
        Dictionary with entity visualization data
74
    """
75
```
76

77
### Renderer Classes
78

79
Classes that handle the actual rendering of visualizations.
80

81
```python { .api }
82
class DependencyRenderer:
83
    """Renderer for dependency parse visualizations."""
84
    
85
    style: str = "dep"
86
    
87
    def __init__(self, options: dict = None) -> None:
88
        """Initialize the dependency renderer."""
89
    
90
    def render(self, parsed: List[dict], page: bool = False, 
91
               minify: bool = False) -> str:
92
        """
93
        Render dependency visualization.
94
        
95
        Args:
96
            parsed: Parsed dependency data
97
            page: Render as full HTML page
98
            minify: Minify HTML output
99
            
100
        Returns:
101
            HTML/SVG string
102
        """
103

104
class EntityRenderer:
105
    """Renderer for named entity visualizations."""
106
    
107
    style: str = "ent"
108
    
109
    def __init__(self, options: dict = None) -> None:
110
        """Initialize the entity renderer."""
111
    
112
    def render(self, parsed: List[dict], page: bool = False,
113
               minify: bool = False) -> str:
114
        """
115
        Render entity visualization.
116
        
117
        Args:
118
            parsed: Parsed entity data
119
            page: Render as full HTML page  
120
            minify: Minify HTML output
121
            
122
        Returns:
123
            HTML/SVG string
124
        """
125
```
126

127
## Visualization Options
128

129
### Dependency Visualization Options
130

131
Configuration options for dependency tree visualizations:
132

133
```python
134
dep_options = {
135
    # Appearance
136
    "compact": False,        # Use compact arrow style
137
    "bg": "#ffffff",         # Background color
138
    "color": "#000000",      # Text color
139
    "font": "Arial",         # Font family
140
    "distance": 175,         # Distance between tokens
141
    "arrow_stroke": 2,       # Arrow line width
142
    "arrow_width": 10,       # Arrow head width
143
    "arrow_spacing": 20,     # Spacing between arrows
144
    "word_spacing": 45,      # Spacing between words
145
    "collapse_punct": True,  # Collapse punctuation arcs
146
    "collapse_phrases": False, # Collapse noun phrases
147
    
148
    # Filtering
149
    "fine_grained": False,   # Use fine-grained POS tags
150
    "add_lemma": False,      # Show lemmas below tokens
151
    "collapse_punct": True,  # Collapse punctuation dependencies
152
}
153
```
154

155
### Entity Visualization Options
156

157
Configuration options for named entity visualizations:
158

159
```python
160
ent_options = {
161
    # Entity types and colors
162
    "ents": ["PERSON", "ORG", "GPE", "MONEY"],  # Entity types to show
163
    "colors": {              # Custom colors for entity types
164
        "PERSON": "#aa9cfc",
165
        "ORG": "#7aecec", 
166
        "GPE": "#bfefff",
167
        "MONEY": "#e4e7d2"
168
    },
169
    
170
    # Appearance  
171
    "template": None,        # Custom HTML template
172
    "kb_url_template": None, # Knowledge base URL template
173
}
174
```
175

176
## Usage Examples
177

178
### Basic Dependency Visualization
179

180
```python
181
import spacy
182
from spacy import displacy
183

184
nlp = spacy.load("en_core_web_sm")
185
doc = nlp("Apple is looking at buying U.K. startup for $1 billion")
186

187
# Render dependency visualization
188
html = displacy.render(doc, style="dep", jupyter=False)
189
print(html)
190

191
# Display in Jupyter notebook
192
displacy.render(doc, style="dep", jupyter=True)
193

194
# Save to file
195
with open("dependency.html", "w") as f:
196
    f.write(displacy.render(doc, style="dep", page=True))
197
```
198

199
### Named Entity Visualization
200

201
```python
202
import spacy
203
from spacy import displacy
204

205
nlp = spacy.load("en_core_web_sm")
206
doc = nlp("Apple Inc. is looking at buying U.K. startup for $1 billion")
207

208
# Render entity visualization
209
html = displacy.render(doc, style="ent", jupyter=False)
210
print(html)
211

212
# Custom entity colors
213
colors = {"ORG": "#85C1E9", "GPE": "#F8C471", "MONEY": "#82E0AA"}
214
options = {"ents": ["ORG", "GPE", "MONEY"], "colors": colors}
215

216
html = displacy.render(doc, style="ent", options=options)
217
print(html)
218
```
219

220
### Visualizing Multiple Documents
221

222
```python
223
import spacy
224
from spacy import displacy
225

226
nlp = spacy.load("en_core_web_sm")
227

228
texts = [
229
    "Apple Inc. is an American technology company.",
230
    "Google was founded by Larry Page and Sergey Brin.",
231
    "Microsoft Corporation is based in Redmond, Washington."
232
]
233

234
docs = [nlp(text) for text in texts]
235

236
# Visualize multiple documents
237
html = displacy.render(docs, style="ent", page=True)
238

239
# Save multi-document visualization
240
with open("multiple_docs.html", "w") as f:
241
    f.write(html)
242
```
243

244
### Web Server Visualization
245

246
```python
247
import spacy
248
from spacy import displacy
249

250
nlp = spacy.load("en_core_web_sm")
251
docs = [nlp("Apple Inc. is buying a startup for $1 billion.")]
252

253
# Start visualization server
254
# This will open a web browser at http://localhost:5000
255
displacy.serve(docs, style="dep", port=5000)
256

257
# Serve on specific host and port
258
displacy.serve(docs, style="ent", host="127.0.0.1", port=8000)
259
```
260

261
### Custom Visualization Options
262

263
```python
264
import spacy
265
from spacy import displacy
266

267
nlp = spacy.load("en_core_web_sm")
268
doc = nlp("The quick brown fox jumps over the lazy dog")
269

270
# Custom dependency visualization options
271
dep_options = {
272
    "compact": True,
273
    "bg": "#f9f9f9",  
274
    "color": "#333333",
275
    "font": "Helvetica",
276
    "distance": 200,
277
    "arrow_stroke": 3,
278
    "arrow_width": 12,
279
    "fine_grained": True,
280
    "add_lemma": True
281
}
282

283
html = displacy.render(doc, style="dep", options=dep_options)
284

285
# Custom entity visualization options
286
doc2 = nlp("Apple Inc. CEO Tim Cook visited London, England")
287
ent_options = {
288
    "ents": ["PERSON", "ORG", "GPE"],
289
    "colors": {
290
        "PERSON": "#ff6b6b",
291
        "ORG": "#4ecdc4", 
292
        "GPE": "#45b7d1"
293
    }
294
}
295

296
html = displacy.render(doc2, style="ent", options=ent_options)
297
```
298

299
### Manual Data Visualization
300

301
```python
302
from spacy import displacy
303

304
# Manual dependency data
305
manual_dep_data = [
306
    {
307
        "words": [
308
            {"text": "Apple", "tag": "NNP"},
309
            {"text": "is", "tag": "VBZ"},
310
            {"text": "great", "tag": "JJ"}
311
        ],
312
        "arcs": [
313
            {"start": 0, "end": 1, "label": "nsubj", "dir": "left"},
314
            {"start": 1, "end": 2, "label": "acomp", "dir": "right"}
315
        ]
316
    }
317
]
318

319
html = displacy.render(manual_dep_data, style="dep", manual=True)
320

321
# Manual entity data
322
manual_ent_data = [
323
    {
324
        "text": "Apple Inc. is a technology company in Cupertino.",
325
        "ents": [
326
            {"start": 0, "end": 10, "label": "ORG"},
327
            {"start": 39, "end": 48, "label": "GPE"}
328
        ]
329
    }
330
]
331

332
html = displacy.render(manual_ent_data, style="ent", manual=True)
333
```
334

335
### Advanced Customization
336

337
```python
338
import spacy
339
from spacy import displacy
340

341
nlp = spacy.load("en_core_web_sm")
342

343
# Filter specific dependencies  
344
def filter_deps(doc):
345
    """Custom function to filter dependencies."""
346
    filtered_deps = []
347
    for token in doc:
348
        if token.dep_ not in ["punct", "det", "aux"]:
349
            filtered_deps.append({
350
                "start": token.i,
351
                "end": token.head.i,
352
                "label": token.dep_,
353
                "dir": "left" if token.i > token.head.i else "right"
354
            })
355
    return filtered_deps
356

357
doc = nlp("The quick brown fox jumps over the lazy dog")
358

359
# Create custom visualization data
360
words = [{"text": token.text, "tag": token.pos_} for token in doc]
361
arcs = filter_deps(doc)
362

363
manual_data = [{"words": words, "arcs": arcs}]
364
html = displacy.render(manual_data, style="dep", manual=True)
365
```
366

367
### Jupyter Notebook Integration
368

369
```python
370
# In Jupyter notebook
371
import spacy
372
from spacy import displacy
373

374
nlp = spacy.load("en_core_web_sm")
375
doc = nlp("Apple Inc. is looking at buying U.K. startup for $1 billion")
376

377
# Auto-detects Jupyter and displays inline
378
displacy.render(doc, style="dep")
379
displacy.render(doc, style="ent")
380

381
# Force Jupyter rendering
382
displacy.render(doc, style="dep", jupyter=True)
383

384
# Explicitly disable Jupyter for HTML string
385
html_string = displacy.render(doc, style="dep", jupyter=False)
386
```
387

388
### Batch Visualization Processing
389

390
```python
391
import spacy
392
from spacy import displacy
393
import os
394

395
nlp = spacy.load("en_core_web_sm")
396

397
texts = [
398
    "Apple Inc. announced new products.",
399
    "Google develops artificial intelligence.", 
400
    "Microsoft partners with OpenAI.",
401
    "Tesla builds electric vehicles.",
402
    "Amazon operates cloud services."
403
]
404

405
# Process and visualize all documents
406
docs = list(nlp.pipe(texts))
407

408
# Create individual visualizations
409
for i, doc in enumerate(docs):
410
    html = displacy.render(doc, style="ent", page=True)
411
    filename = f"doc_{i}.html"
412
    with open(filename, "w") as f:
413
        f.write(html)
414
    print(f"Saved {filename}")
415

416
# Create combined visualization
417
combined_html = displacy.render(docs, style="ent", page=True)
418
with open("combined.html", "w") as f:
419
    f.write(combined_html)
420
```
421

422
### Export and Customization
423

424
```python
425
import spacy
426
from spacy import displacy
427

428
nlp = spacy.load("en_core_web_sm")
429
doc = nlp("The CEO of Apple Inc. announced new products")
430

431
# Get raw visualization data
432
dep_data = displacy.parse_deps(doc)
433
ent_data = displacy.parse_ents(doc)
434

435
print("Dependency data:", dep_data)
436
print("Entity data:", ent_data)
437

438
# Modify data before rendering
439
ent_data[0]["ents"].append({
440
    "start": 0, "end": 3, "label": "TITLE"
441
})
442

443
# Render modified data
444
html = displacy.render(ent_data, style="ent", manual=True)
445
```