cassiopeia.pl.Tree3D#

class cassiopeia.pl.Tree3D(tree, labels=None, offset=1.0, downscale=1.0, cmap=None, attribute_key='spatial')[source]#

Create a 3D projection of a tree onto a 2D surface.

This class provides various wrappers around Pyvista, which is used for 3D rendering.

Example

# When labels aren’t available, they can be synthetically created by # using labels_from_coordinates, as so. The tree must contain spatial # coordinates in the cell meta. labels = cas.pl.labels_from_coordinates(tree)

tree3d = cas.pl.Tree3D(tree, labels) tree3d.add_image(img) # img is a np.array with the same shape as labels tree3d.plot()

Parameters:

tree CassiopeiaTree: The Cassiopeia tree to plot. The leaf names must be string-casted integers.
labels ndarray | NoneOptional[ndarray] (default: None): Optional numpy array containing cell labels on a 2D surface. This array must contain all the cells in the tree, but as integers. In None, the labels will be generated synthetically using labels_from_coordinates.
offset float (default: 1.0): Offset to give to tree and subclone shading. This option exists because in some cases if the tree and subclone shading is placed at the same height as the image, weird clipping happens.
downscale float (default: 1.0): Downscale all images by this amount. This option is recommended for more responsive visualization.
cmap List[str] | NoneOptional[List[str]] (default: None): Colormap to use. Defaults to the Godsnot color palette, as defined at scverse/scanpy
attribute_key str (default: 'spatial'): Attribute key to use as the integer labels for each leaf node. A column with the name {attribute_key}_label will be looked up in the cell meta.

Methods

init_label_mapping(key)[source]#: Initialize label mappings.

init_nodes()[source]#: Initialize node information.

init_subclones()[source]#: Initialize subclone grid.

get_mask(node)[source]#

Helper function to get a boolean mask of where certain subclades are.

Parameters:

node str: Node name to select cells

Return type:

ndarray

Returns:

Boolean mask where True indicates cells in the subclade marked by: node

create_grid()[source]#

Helper function to create a Pyvista ImageData object with the appropriate shape.

Return type:: ImageData

add_image(key, img)[source]#

Add an image so that it may be displayed with the tree.

Parameters:

key str: Identifiable name of the image.
img ndarray: Image as a Numpy array

cut_tree(root, time)[source]#

Cut the tree at a specific time after the time specified by the root.

Parameters:

root str: Root to calculate the time delta from.
time float: Time from root to cut the tree at.

Return type:

List[str]

Returns:

A list of leaf nodes for the cut tree. These nodes may be internal: nodes.

place_nodes(root, leaves)[source]#

Place a subset of nodes in xyz coordinates.

Only nodes in the path between root and each node in leaves are: placed.

Parameters:

root str: Root node of the tree. Does not have to be the actual root of the tree.
leaves List[str]: List of nodes at the bottom of the tree. May be internal nodes.

Return type:

ndarray

Returns:

A Numpy array of N x 3, where N is the total number of nodes in the: tree. Nodes that were not placed will have np.nan as its three coordinates. Each row is indexed to each node according to self.node_index.

place_branches(root, coordinates)[source]#

Place a subset of branches in xyz coordinates.

Only nodes in the path between root and each node that have valid coordinates in coordinates are placed.

Parameters:

root str: Root node of the tree. Does not have to be the actual root of the tree.
coordinates ndarray: Coordinates of nodes as produced by self.place_nodes.

Return type:

Dict[Tuple[str, str], ndarray]

Returns:

Dictionary of branch tuples (node1, node2) as keys and branch: coordinates as a Numpy arrays as values.

render_node(coords, radius)[source]#

Helper function to create a Pyvista object representing a node.

Parameters:

coords ndarray: XYZ coordinates as a 1-dimensional Numpy array
radius float: Radius of sphere

Return type:

Sphere

Returns:

Pyvista object representing a node.

render_branch(branch_coords, radius)[source]#

Helper function to create a Pyvista object representing a branch.

Parameters:

coords: XYZ coordinates as a 2-dimensional Numpy array
radius float: Radius of tube

Return type:

Tube

Returns:

Pyvista object representing a branch.

clear_node_actors()[source]#: Clear nodes from visualization.

clear_branch_actors()[source]#: Clear branches from visualization.

clear_subclone_actor()[source]#: Clear subclone shades from visualization.

clear_image_actors()[source]#: Clear images from visualization.

set_subclone_sigma(sigma)[source]#

Set subclone shade blur strength.

Parameters:

sigma float: Blur strength

set_height(height)[source]#

Set the height of the tree.

The height is defined as the number of branches from the root.

Parameters:

height: Cutoff height as an integer

set_time(time)[source]#

Set the time of the tree.

Parameters:

time float: Cutoff time

set_node_picking(flag)[source]#

Helper function to setup node selection.

Parameters:

flag bool: True to enable node selection, False otherwise.

set_shown_image(key, show)[source]#

Helper function to show an image.

Parameters:

key str: Image key
show bool: True to show, False otherwise.

set_root(root)[source]#

Helper function to set the root of the tree.

Parameters:

root str: Desired root node

set_selected_node_as_root()[source]#: Helper function to set the selected node as the root.

select_node_mesh(mesh)[source]#: Helper function remember the selected node.

select_node(node)[source]#

Helper function to select a node.

When a node is selected, its children nodes and branches are highlighted, including subclone shading. All other elements are dimmed out.

Parameters:

node str: Selected node

clear_picked_mesh()[source]#: Helper function to clear the selected mesh.

reset_selected_node()[source]#: Helper function to clear the selected node.

update_actors(actors, new_actors)[source]#

Helper function to update a set of actors.

Parameters:

actors {str: vtkActor}Dict[str, vtkActor]: Dictionary of actors that are currently displayed.
new_actors {str: vtkActor}Dict[str, vtkActor]: Dictionary of actors to replace the existing actors with.

update_texts()[source]#

Update displayed text.

The following text is updated. * The current root * The current time * The selected node (if one is selected)

update_images()[source]#: update displayed image(s).

update_branches()[source]#: Update displayed branches.

update_subclones()[source]#: Update displayed subclone shading.

add_blur_slider()[source]#: Add slider to control subclone blur strength.

add_height_slider()[source]#: Add slider to control tree height.

add_time_slider()[source]#: Add slider to control current time.

add_height_key_events()[source]#: Add key events such that pressing numbers from 1 through 9 controls the tree height.

add_image_checkboxes()[source]#

add_node_picking()[source]#: Enable node selection.

add_widgets()[source]#: Add widgets.

plot(plot_tree=True, add_widgets=True, show=True)[source]#

Display 3D render.

Parameters:

plot_tree bool (default: True): Immediately render the tree. If False, the initial plot will not have any tree rendered.
add_widgets bool (default: True): Add widgets to scene.
show bool (default: True): Whether to show the plot immmediately.

reset()[source]#: Helper function to reset everything.