​
High-level description

The cassiopeia/plotting directory contains modules for visualizing phylogenetic trees and related data using various methods and libraries. It provides functionality for both local plotting using Matplotlib and Plotly, as well as cloud-based visualization using the iTOL (Interactive Tree Of Life) web service. The package also includes utilities for 3D tree visualization and color palette management.

​
What does it do?

This package enables researchers and data scientists to create visual representations of phylogenetic trees and associated data. It offers the following key functionalities:

  1. Local tree plotting using Matplotlib (static) and Plotly (interactive).
  2. Cloud-based tree visualization using iTOL, including the ability to upload trees and export visualizations.
  3. 3D tree visualization using PyVista.
  4. Creation of colorstrips and indel heatmaps to annotate trees with additional data.
  5. Utility functions for tree placement, color manipulation, and data preparation.

These visualizations help in analyzing the structure of phylogenetic trees, comparing different clades, and identifying patterns in associated metadata or genetic information.

​
Entry points

The main entry points for users of this package are:

  1. plot_matplotlib and plot_plotly functions in local.py for local tree plotting.
  2. upload_and_export_itol function in itol_utilities.py for cloud-based visualization using iTOL.
  3. Tree3D class in local_3d.py for 3D tree visualization.

The __init__.py file exports these key functions and classes, making them directly accessible when importing from cassiopeia.plotting.

​
Key Files

  1. local.py: Contains functions for local tree plotting using Matplotlib and Plotly.
  2. itol_utilities.py: Provides utilities for interacting with the iTOL web service.
  3. local_3d.py: Implements 3D tree visualization using PyVista.
  4. utilities.py: Contains various utility functions for tree placement, color manipulation, and data preparation.
  5. palettes.py: Defines a color palette for use in visualizations.

​
Dependencies

The package relies on several external libraries:

  • Matplotlib and Plotly for 2D plotting
  • PyVista for 3D visualization
  • itolapi for interacting with the iTOL web service
  • pandas and numpy for data manipulation
  • networkx for graph operations
  • OpenCV (cv2) for image processing in 3D visualization

​
Configuration

The package does not require extensive configuration. However, users can customize various aspects of the visualizations through function parameters, such as:

  • Tree orientation and layout
  • Color schemes and palettes
  • Metadata inclusion and representation
  • 3D visualization parameters

For iTOL-based visualizations, users need to provide their iTOL API key and project name, either directly or through a configuration file.

In summary, the cassiopeia/plotting package provides a comprehensive set of tools for visualizing phylogenetic trees and associated data, offering flexibility in terms of visualization methods and customization options to suit various research needs.

__init__.pyitol_utilities.py