utilities.py - Stanza Demo

High-level description

This file contains utility functions for plotting phylogenetic trees locally using libraries like Matplotlib and Plotly. It provides functions for placing tree nodes and branches on a coordinate system, generating color strips for annotations, and creating indel heatmaps.

Code Structure

The code consists of several independent utility functions that can be used for plotting phylogenetic trees. These functions include: degrees_to_radians, polar_to_cartesian, polars_to_cartesians, place_tree, place_colorstrip, generate_random_color, get_random_indel_colors, get_indel_colors, hex_to_rgb, rgb_to_hex, and prepare_alleletable.

References

This file references the CassiopeiaTree class from cassiopeia.data and the convert_alleletable_to_lineage_profile function from cassiopeia.preprocess.utilities.

Symbols

`degrees_to_radians`

Description

Converts an angle from degrees to radians.

Inputs

Name	Type	Description
degrees	float	Angle in degrees.

Outputs

Name	Type	Description
float	float	Angle in radians.

`polar_to_cartesian`

Description

Converts polar coordinates (angle and radius) to Cartesian coordinates (x and y).

Inputs

Name	Type	Description
degrees	float	Angle in degrees.
r	float	Radius.

Outputs

Name	Type	Description
Tuple[float, float]	Tuple[float, float]	A tuple containing the x and y coordinates.

`polars_to_cartesians`

Description

Converts a list of polar coordinates to a list of Cartesian coordinates.

Inputs

Name	Type	Description
degrees	List[float]	List of angles in degrees.
rs	List[float]	List of radii.

Outputs

Name	Type	Description
Tuple[List[float], List[float]]	Tuple[List[float], List[float]]	Two lists, containing the x and y coordinates respectively.

`place_tree`

Description

Computes the coordinates of nodes and branches in a CassiopeiaTree for visualization. It supports both rectangular and polar coordinate systems and offers options for customizing the tree layout.

Inputs

Name	Type	Description
tree	CassiopeiaTree	The tree to place on the coordinate grid.
depth_key	Optional[str]	The node attribute to use as the depth of the nodes. If not provided, the distances from the root are used.
orient	Union[Literal[“down”, “up”, “left”, “right”], float]	The orientation of the tree. Can be “down”, “up”, “left”, “right” for rectangular plots, or a number for polar plots.
depth_scale	float	Scale the depth of the tree by this amount.
width_scale	float	Scale the width of the tree by this amount.
extend_branches	bool	Extend branch lengths to equalize distances from the root to all nodes.
angled_branches	bool	Display branches as angled lines instead of straight lines.
polar_interpolation_threshold	float	Threshold for adding interpolation points in polar plots to smooth out large angles.
polar_interpolation_step	float	Interpolation step for polar plots.
add_root	bool	Add a synthetic root node to the tree.

Outputs

Name	Type	Description
Tuple[Dict[str, Tuple[float, float]], Dict[Tuple[str, str], Tuple[List[float], List[float]]]]	Tuple[Dict[str, Tuple[float, float]], Dict[Tuple[str, str], Tuple[List[float], List[float]]]]	Two dictionaries: the first contains node coordinates, and the second contains branch coordinates.

Internal Logic

The function first places the leaves of the tree, then iteratively places internal nodes based on the positions of their children. It supports both rectangular and polar coordinate systems and offers options for customizing the tree layout, such as extending branches, angling branches, and adding a synthetic root node.

`place_colorstrip`

Description

Computes the coordinates of boxes for a color strip annotation, which can be used to visualize categorical or continuous data alongside the tree.

Inputs

Name	Type	Description
anchor_coords	Dict[str, Tuple[float, float]]	Dictionary of anchor coordinates for the color strip boxes.
width	float	Width of the box.
height	float	Height of the box.
spacing	float	Space between consecutive color strips.
loc	Literal[“left”, “right”, “up”, “down”, “polar”]	Location of the boxes relative to the anchors.

Outputs

Name	Type	Description
Tuple[Dict[str, Tuple[List[float], List[float]]], Dict[str, Tuple[float, float]]]	Tuple[Dict[str, Tuple[List[float], List[float]]], Dict[str, Tuple[float, float]]]	A dictionary of box coordinates and a dictionary of new anchor coordinates.

`generate_random_color`

Description

Generates a random RGB color within specified ranges for each color channel.

Inputs

Name	Type	Description
r_range	Tuple[float, float]	Range of values for the red channel.
g_range	Tuple[float, float]	Range of values for the green channel.
b_range	Tuple[float, float]	Range of values for the blue channel.
random_state	Optional[np.random.RandomState]	Random state for reproducibility.

Outputs

Name	Type	Description
Tuple[int, int, int]	Tuple[int, int, int]	A tuple containing the randomly generated RGB color values.

`get_random_indel_colors`

Description

Assigns random HSV colors to each unique indel in a lineage profile.

Inputs

Name	Type	Description
lineage_profile	pd.DataFrame	Lineage profile containing indel observations.
random_state	Optional[np.random.RandomState]	Random state for reproducibility.

Outputs

Name	Type	Description
pd.DataFrame	pd.DataFrame	A DataFrame mapping indels to HSV colors.

`get_indel_colors`

Description

Maps indels to HSV colors based on their prior probabilities, with rarer indels receiving brighter colors.

Inputs

Name	Type	Description
indel_priors	pd.DataFrame	DataFrame mapping indels to probabilities.
random_state	Optional[np.random.RandomState]	Random state for reproducibility.

Outputs

Name	Type	Description
pd.DataFrame	pd.DataFrame	A DataFrame mapping indels to HSV colors.

`hex_to_rgb`

Description

Converts a hexadecimal color code to an RGB tuple.

Inputs

Name	Type	Description
value	str	Hexadecimal color code (e.g., “#FF0000”).

Outputs

Name	Type	Description
Tuple[int, int, int]	Tuple[int, int, int]	A tuple containing the RGB color values.

`rgb_to_hex`

Description

Converts an RGB tuple to a hexadecimal color code.

Inputs

Name	Type	Description
rgb	Tuple[int, int, int]	A tuple containing the RGB color values.

Outputs

Name	Type	Description
str	str	Hexadecimal color code (e.g., “#FF0000”).

`prepare_alleletable`

Description

Prepares an allele table for plotting by generating indel colors and creating a lineage profile.

Inputs

Name	Type	Description
allele_table	pd.DataFrame	Allele table containing indel observations.
leaves	List[str]	List of leaf node names in the tree.
indel_priors	Optional[pd.DataFrame]	DataFrame mapping indels to probabilities.
random_state	Optional[np.random.RandomState]	Random state for reproducibility.

Outputs

Name	Type	Description
Tuple[pd.DataFrame, pd.DataFrame]	Tuple[pd.DataFrame, pd.DataFrame]	A tuple containing the lineage profile and indel colors as DataFrames.

Internal Logic

The function first converts the allele table to a lineage profile using the convert_alleletable_to_lineage_profile function. Then, it generates indel colors either randomly or based on prior probabilities, depending on whether indel_priors is provided.

​High-level description

​Code Structure

​References

​Symbols

​degrees_to_radians

​Description

​Inputs

​Outputs

​polar_to_cartesian

​Description

​Inputs

​Outputs

​polars_to_cartesians

​Description

​Inputs

​Outputs

​place_tree

​Description

​Inputs

​Outputs

​Internal Logic

​place_colorstrip

​Description

​Inputs

​Outputs

​generate_random_color

​Description

​Inputs

​Outputs

​get_random_indel_colors

​Description

​Inputs

​Outputs

​get_indel_colors

​Description

​Inputs

​Outputs

​hex_to_rgb

​Description

​Inputs

​Outputs

​rgb_to_hex

​Description

​Inputs

​Outputs

​prepare_alleletable

​Description

​Inputs

​Outputs

​Internal Logic

High-level description

Code Structure

References

Symbols

`degrees_to_radians`

Description

Inputs

Outputs

`polar_to_cartesian`

Description

Inputs

Outputs

`polars_to_cartesians`

Description

Inputs

Outputs

`place_tree`

Description

Inputs

Outputs

Internal Logic

`place_colorstrip`

Description

Inputs

Outputs

`generate_random_color`

Description

Inputs

Outputs

`get_random_indel_colors`

Description

Inputs

Outputs

`get_indel_colors`

Description

Inputs

Outputs

`hex_to_rgb`

Description

Inputs

Outputs

`rgb_to_hex`

Description

Inputs

Outputs

`prepare_alleletable`

Description

Inputs

Outputs

Internal Logic