0
# Visualization & Interoperability
1

2
Tree visualization, plotting, and integration with external phylogenetic software and databases. DendroPy supports ASCII tree plots, LaTeX TikZ output, and comprehensive interfaces to external tools including PAUP*, RAxML, R, and phylogenetic databases.
3

4
## Capabilities
5

6
### Tree Visualization
7

8
Classes for generating visual representations of phylogenetic trees in various formats.
9

10
```python { .api }
11
class AsciiTreePlot:
12
    """
13
    ASCII-based tree visualization for console output.
14
    
15
    Parameters:
16
    - tree: Tree object to visualize
17
    - display_width: Maximum width for tree display
18
    - show_internal_node_labels: Display internal node labels
19
    - leaf_spacing_factor: Spacing between leaf nodes
20
    """
21
    
22
    def __init__(self, **kwargs): ...
23
    
24
    def compose(self, tree, **kwargs):
25
        """
26
        Generate ASCII representation of tree.
27
        
28
        Parameters:
29
        - tree: Tree to visualize
30
        - width: Display width in characters
31
        - margin: Left margin for tree display
32
        - show_edge_lengths: Include branch lengths in display
33
        - edge_length_format: Format string for branch lengths
34
        - node_label_compose_fn: Function for composing node labels
35
        
36
        Returns:
37
        str: ASCII art representation of tree
38
        """
39
    
40
    def write(self, tree, dest, **kwargs):
41
        """Write ASCII tree to file or stream."""
42

43
class TikzTreePlot:
44
    """
45
    LaTeX TikZ tree visualization for publication-quality figures.
46
    
47
    Parameters:
48
    - tree: Tree object to plot
49
    - tikz_options: TikZ-specific formatting options
50
    """
51
    
52
    def __init__(self, **kwargs): ...
53
    
54
    def compose(self, tree, **kwargs):
55
        """
56
        Generate TikZ code for tree visualization.
57
        
58
        Parameters:
59
        - tree: Tree to plot
60
        - tree_layout: Layout algorithm ('rectangular', 'slanted', 'radial')
61
        - scale_factor: Scaling factor for branch lengths
62
        - node_label_compose_fn: Function for node label formatting
63
        - edge_style_compose_fn: Function for edge styling
64
        - node_style_compose_fn: Function for node styling
65
        
66
        Returns:
67
        str: TikZ LaTeX code for tree
68
        """
69
    
70
    def write(self, tree, dest, **kwargs):
71
        """Write TikZ code to file or stream."""
72
```
73

74
### External Software Integration
75

76
Classes for interfacing with popular phylogenetic analysis software.
77

78
```python { .api }
79
class PaupService:
80
    """
81
    Interface to PAUP* phylogenetic analysis software.
82
    
83
    Parameters:
84
    - paup_path: Path to PAUP* executable
85
    - suppress_input_file_cleanup: Keep temporary input files
86
    - suppress_output_file_cleanup: Keep temporary output files
87
    """
88
    
89
    def __init__(self, **kwargs): ...
90
    
91
    def run(self, commands, **kwargs):
92
        """
93
        Execute PAUP* commands.
94
        
95
        Parameters:
96
        - commands: List of PAUP* command strings
97
        - input_data: Character matrix or tree data for analysis
98
        - timeout: Maximum execution time in seconds
99
        
100
        Returns:
101
        str: PAUP* output text
102
        """
103
    
104
    def estimate_tree(self, char_matrix, **kwargs):
105
        """
106
        Estimate phylogenetic tree from character data.
107
        
108
        Parameters:
109
        - char_matrix: CharacterMatrix for tree estimation
110
        - search_method: Tree search algorithm ('nj', 'mp', 'ml')
111
        - search_options: Additional search parameters
112
        
113
        Returns:
114
        Tree: Estimated phylogenetic tree
115
        """
116
    
117
    def bootstrap_trees(self, char_matrix, num_replicates=100, **kwargs):
118
        """
119
        Generate bootstrap trees.
120
        
121
        Parameters:
122
        - char_matrix: Character data for bootstrap analysis
123
        - num_replicates: Number of bootstrap replicates
124
        - search_method: Tree search method for each replicate
125
        
126
        Returns:
127
        TreeList: Collection of bootstrap trees
128
        """
129

130
class RaxmlRunner:
131
    """
132
    Interface to RAxML maximum likelihood phylogenetic software.
133
    
134
    Parameters:
135
    - raxml_path: Path to RAxML executable
136
    - temp_dir: Directory for temporary files
137
    """
138
    
139
    def __init__(self, **kwargs): ...
140
    
141
    def estimate_tree(self, char_matrix, **kwargs):
142
        """
143
        Estimate maximum likelihood tree using RAxML.
144
        
145
        Parameters:
146
        - char_matrix: Character data for tree estimation
147
        - substitution_model: Evolutionary model ('GTRGAMMA', etc.)
148
        - num_runs: Number of independent ML searches
149
        - bootstrap_replicates: Number of bootstrap replicates
150
        - random_seed: Random seed for reproducibility
151
        
152
        Returns:
153
        Tree: Best ML tree from RAxML analysis
154
        """
155
    
156
    def bootstrap_analysis(self, char_matrix, **kwargs):
157
        """
158
        Perform bootstrap analysis with RAxML.
159
        
160
        Parameters:
161
        - char_matrix: Character data
162
        - num_replicates: Number of bootstrap replicates
163
        - substitution_model: Evolutionary model
164
        
165
        Returns:
166
        TreeList: Bootstrap trees with support values
167
        """
168

169
class RService:
170
    """
171
    Interface to R statistical computing environment.
172
    
173
    Parameters:
174
    - r_path: Path to R executable
175
    - r_libs: Additional R library paths
176
    """
177
    
178
    def __init__(self, **kwargs): ...
179
    
180
    def run(self, r_script, **kwargs):
181
        """
182
        Execute R script and return results.
183
        
184
        Parameters:
185
        - r_script: R code to execute
186
        - data_objects: Python objects to pass to R
187
        - return_objects: R objects to return to Python
188
        
189
        Returns:
190
        dict: Results from R execution
191
        """
192
    
193
    def tree_to_ape(self, tree):
194
        """Convert DendroPy tree to R APE phylo object."""
195
    
196
    def tree_from_ape(self, ape_tree):
197
        """Convert R APE phylo object to DendroPy tree."""
198

199
class Rspr:
200
    """
201
    Interface to RSPR (Rooted Subtree Prune and Regraft) software.
202
    
203
    Parameters:
204
    - rspr_path: Path to RSPR executable
205
    """
206
    
207
    def __init__(self, **kwargs): ...
208
    
209
    def spr_distance(self, tree1, tree2, **kwargs):
210
        """
211
        Calculate SPR distance between trees.
212
        
213
        Parameters:
214
        - tree1, tree2: Trees for distance calculation
215
        - rooted: Whether trees should be treated as rooted
216
        
217
        Returns:
218
        int: SPR distance between trees
219
        """
220

221
class SeqGenRunner:
222
    """
223
    Interface to Seq-Gen sequence simulation software.
224
    
225
    Parameters:
226
    - seqgen_path: Path to Seq-Gen executable
227
    """
228
    
229
    def __init__(self, **kwargs): ...
230
    
231
    def generate_sequences(self, tree, **kwargs):
232
        """
233
        Generate sequences using Seq-Gen.
234
        
235
        Parameters:
236
        - tree: Tree for sequence simulation
237
        - seq_len: Length of sequences to generate
238
        - substitution_model: Evolution model ('HKY', 'GTR', etc.)
239
        - rate_params: Model-specific rate parameters
240
        
241
        Returns:
242
        CharacterMatrix: Simulated sequence alignment
243
        """
244
```
245

246
### Database Integration
247

248
Classes for accessing phylogenetic and biological databases.
249

250
```python { .api }
251
class GbifDb:
252
    """
253
    Interface to Global Biodiversity Information Facility (GBIF) database.
254
    
255
    Parameters:
256
    - api_key: GBIF API key for authenticated access
257
    - cache_dir: Directory for caching downloaded data
258
    """
259
    
260
    def __init__(self, **kwargs): ...
261
    
262
    def taxon_search(self, query, **kwargs):
263
        """
264
        Search for taxonomic information.
265
        
266
        Parameters:
267
        - query: Taxonomic search query
268
        - limit: Maximum number of results
269
        - rank: Taxonomic rank filter
270
        
271
        Returns:
272
        list: Taxonomic records matching query
273
        """
274
    
275
    def occurrence_search(self, taxon_key, **kwargs):
276
        """
277
        Search for species occurrence records.
278
        
279
        Parameters:
280
        - taxon_key: GBIF taxon identifier
281
        - geographic_bounds: Geographic bounding box
282
        - date_range: Date range for occurrences
283
        
284
        Returns:
285
        list: Occurrence records for taxon
286
        """
287

288
class GbifOccurrenceDb(GbifDb):
289
    """Specialized interface for GBIF occurrence data."""
290
    
291
    def download_occurrences(self, taxa, **kwargs):
292
        """Download occurrence data for multiple taxa."""
293

294
class GenBankResourceStore:
295
    """
296
    Interface to NCBI GenBank database.
297
    
298
    Parameters:
299
    - api_key: NCBI API key for enhanced access
300
    - email: Email address for NCBI Entrez access
301
    - cache_dir: Directory for caching sequence data
302
    """
303
    
304
    def __init__(self, **kwargs): ...
305
    
306
    def fetch_sequences(self, accession_ids, **kwargs):
307
        """
308
        Fetch sequences by GenBank accession numbers.
309
        
310
        Parameters:
311
        - accession_ids: List of GenBank accession numbers
312
        - sequence_type: Type of sequences ('nucleotide', 'protein')
313
        - format: Output format ('fasta', 'genbank')
314
        
315
        Returns:
316
        CharacterMatrix: Retrieved sequences
317
        """
318
    
319
    def search_sequences(self, query, **kwargs):
320
        """
321
        Search GenBank using query terms.
322
        
323
        Parameters:
324
        - query: Search query string
325
        - database: GenBank database ('nuccore', 'protein')
326
        - max_results: Maximum number of results
327
        
328
        Returns:
329
        list: Search results with accession numbers
330
        """
331

332
class GenBankNucleotide:
333
    """GenBank nucleotide sequence interface."""
334
    
335
    def __init__(self, accession, **kwargs): ...
336
    def fetch_sequence(self): ...
337

338
class GenBankDna(GenBankNucleotide):
339
    """GenBank DNA sequence interface."""
340

341
class GenBankRna(GenBankNucleotide):
342
    """GenBank RNA sequence interface."""
343

344
class GenBankProtein:
345
    """GenBank protein sequence interface."""
346
    
347
    def __init__(self, accession, **kwargs): ...
348
    def fetch_sequence(self): ...
349
```
350

351
### Web Service Integration
352

353
Classes for integrating with phylogenetic web services and online tools.
354

355
```python { .api }
356
class ItolService:
357
    """
358
    Interface to iTOL (Interactive Tree of Life) web service.
359
    
360
    Parameters:
361
    - api_key: iTOL API key for authenticated access
362
    - project_name: Name for iTOL project organization
363
    """
364
    
365
    def __init__(self, **kwargs): ...
366
    
367
    def upload_tree(self, tree, **kwargs):
368
        """
369
        Upload tree to iTOL for visualization.
370
        
371
        Parameters:
372
        - tree: Tree object to upload
373
        - tree_name: Display name for tree
374
        - public: Whether tree should be publicly accessible
375
        - annotations: Additional annotation data
376
        
377
        Returns:
378
        str: iTOL tree ID for accessing uploaded tree
379
        """
380
    
381
    def create_annotation_file(self, annotations, **kwargs):
382
        """
383
        Create iTOL annotation file for tree visualization.
384
        
385
        Parameters:
386
        - annotations: Annotation data for tree nodes/leaves
387
        - annotation_type: Type of annotation ('color', 'symbol', etc.)
388
        - output_format: iTOL annotation format
389
        
390
        Returns:
391
        str: Formatted annotation data for iTOL
392
        """
393
    
394
    def download_image(self, tree_id, **kwargs):
395
        """
396
        Download rendered tree image from iTOL.
397
        
398
        Parameters:
399
        - tree_id: iTOL tree identifier
400
        - image_format: Output format ('png', 'svg', 'pdf')
401
        - resolution: Image resolution for raster formats
402
        
403
        Returns:
404
        bytes: Image data
405
        """
406
```
407

408
### Third-Party Library Integration
409

410
Integration with other Python scientific computing and phylogenetic libraries.
411

412
```python { .api }
413
# BioPython integration
414
def tree_to_biopython(dendropy_tree):
415
    """
416
    Convert DendroPy tree to BioPython Phylo tree.
417
    
418
    Parameters:
419
    - dendropy_tree: DendroPy Tree object
420
    
421
    Returns:
422
    Bio.Phylo tree object
423
    """
424

425
def tree_from_biopython(biopython_tree, **kwargs):
426
    """
427
    Convert BioPython Phylo tree to DendroPy tree.
428
    
429
    Parameters:
430
    - biopython_tree: BioPython Phylo tree object
431
    - taxon_namespace: TaxonNamespace for converted tree
432
    
433
    Returns:
434
    dendropy.Tree: Converted tree object
435
    """
436

437
def char_matrix_to_biopython(dendropy_matrix):
438
    """Convert DendroPy character matrix to BioPython alignment."""
439

440
def char_matrix_from_biopython(biopython_alignment, **kwargs):
441
    """Convert BioPython alignment to DendroPy character matrix."""
442

443
# ETE integration  
444
def tree_to_ete(dendropy_tree):
445
    """Convert DendroPy tree to ETE tree."""
446

447
def tree_from_ete(ete_tree, **kwargs):
448
    """Convert ETE tree to DendroPy tree."""
449

450
# APE (R) integration via rpy2
451
def tree_to_ape_via_rpy2(dendropy_tree):
452
    """Convert DendroPy tree to R APE phylo object via rpy2."""
453

454
def tree_from_ape_via_rpy2(ape_tree, **kwargs):
455
    """Convert R APE phylo object to DendroPy tree via rpy2."""
456
```
457

458
### Utility Functions for Interoperability
459

460
Utility functions that support integration with external tools and formats.
461

462
```python { .api }
463
def write_mesquite_file(data_objects, dest, **kwargs):
464
    """
465
    Write data in Mesquite-compatible format.
466
    
467
    Parameters:
468
    - data_objects: Trees and/or character matrices
469
    - dest: Output file path or stream
470
    - include_trees: Whether to include tree data
471
    - include_characters: Whether to include character data
472
    """
473

474
def export_for_beast(trees, char_matrices, dest, **kwargs):
475
    """
476
    Export data in BEAST XML format.
477
    
478
    Parameters:
479
    - trees: Tree data for BEAST analysis
480
    - char_matrices: Character matrices for analysis
481
    - dest: Output XML file path
482
    - analysis_type: Type of BEAST analysis
483
    """
484

485
def export_for_mrbayes(char_matrix, dest, **kwargs):
486
    """
487
    Export character matrix in MrBayes NEXUS format.
488
    
489
    Parameters:
490
    - char_matrix: Character data for MrBayes
491
    - dest: Output NEXUS file path
492
    - include_mrbayes_block: Add MrBayes command block
493
    """
494

495
def validate_external_dependencies():
496
    """
497
    Check availability of external software dependencies.
498
    
499
    Returns:
500
    dict: Status of external software (installed/missing)
501
    """
502

503
def get_external_tool_version(tool_name):
504
    """
505
    Get version information for external phylogenetic software.
506
    
507
    Parameters:
508
    - tool_name: Name of external tool ('paup', 'raxml', etc.)
509
    
510
    Returns:
511
    str: Version string or None if not available
512
    """
513
```
514

515
### Configuration and Error Handling
516

517
Classes and functions for managing external tool configuration and error handling.
518

519
```python { .api }
520
class ExternalToolConfiguration:
521
    """
522
    Configuration manager for external phylogenetic tools.
523
    
524
    Parameters:
525
    - tool_paths: Dictionary mapping tool names to executable paths
526
    - temp_dir: Directory for temporary files
527
    - cleanup_temp_files: Whether to clean up temporary files
528
    """
529
    
530
    def __init__(self, **kwargs): ...
531
    
532
    def set_tool_path(self, tool_name, path):
533
        """Set executable path for external tool."""
534
    
535
    def get_tool_path(self, tool_name):
536
        """Get configured path for external tool."""
537
    
538
    def validate_tools(self):
539
        """Validate that all configured tools are accessible."""
540

541
# Interoperability exceptions
542
class ExternalToolError(Exception):
543
    """Raised when external tool execution fails."""
544

545
class ExternalToolNotFoundError(Exception):
546
    """Raised when external tool executable is not found."""
547

548
class ExternalToolTimeoutError(Exception):
549
    """Raised when external tool execution times out."""
550

551
class UnsupportedFormatConversionError(Exception):
552
    """Raised when format conversion is not supported."""
553
```