Load a TreeData file (.h5td, or legacy .h5ad) into the session.

Use this for existing datasets that already contain trees, expression, and/or a character matrix. Returns a dataset_id handle plus a summary of contents.

Args: path: Absolute path to a .h5td/.h5ad file.

Import a character-matrix CSV into a new TreeData, ready for reconstruction.

The CSV must have cell ids in the first column and one column per character; integer states, with missing_state for dropout and unmodified_state for the uncut state. The matrix is stored in obsm[characters_key].

Args: csv_path: Absolute path to the character-matrix CSV. characters_key: obsm key to store the matrix under (default "characters"). missing_state: Sentinel for missing/dropout entries (default -1). unmodified_state: Sentinel for the uncut/unmodified state (default 0).

Load a built-in pycea example lineage-tracing dataset (downloaded on first use).

Great for demos and testing without your own data. Each returns a TreeData with a tree and (for most) expression, ready for plotting and heritability.

Datasets:

• "packer19": C. elegans embryo lineage (option {"tree": "full"|"observed"}).

• "yang22": mouse tumor phylogenies (option {"tumors": "3435_NT_T1"}).

• "koblan25": prime-editing lineage tracing (option {"experiment": "tumor"}).

Args: name: One of packer19, yang22, koblan25. options: Keyword args forwarded to the pycea.datasets loader.

Inspect a loaded dataset: shape, tree keys, obsm/obs/layers/uns keys.

List all datasets currently loaded in the session.

Persist a dataset to a .h5td file (default: /.h5td).

Returns the absolute path written.

Export a reconstructed tree to a Newick string.

Args: dataset_id: Dataset handle. tree_key: Which tree in tdata.obst to export. record_branch_lengths: Include branch lengths in the Newick. record_node_names: Include internal node names in the Newick.

Reconstruct a lineage tree from a dataset's character matrix.

The tree is written into tdata.obst[key_added] as a rooted networkx DiGraph.

Methods:

• "greedy": Cassiopeia-Greedy (fast, top-down; good default).

• "nj": Neighbor-Joining (distance-based).

• "upgma": UPGMA (distance-based, ultrametric).

• "ilp": Steiner-tree ILP (exact; requires Gurobi; small trees only).

• "hybrid": greedy top + ILP bottom (requires Gurobi).

Args: dataset_id: Dataset handle (must contain a character matrix in obsm). method: One of greedy, nj, upgma, ilp, hybrid. key_added: obst key for the new tree (defaults to the method name). characters_key: obsm key holding the character matrix. priors: Whether to use mutation priors from uns["priors"] if present. extra_options: Advanced solver kwargs passed through (e.g. {"root": "midpoint"} for nj, {"top_solver": "greedy"} for hybrid).

Compute a pairwise dissimilarity map over cells (useful before nj/upgma).

Stores the result in tdata.obsp[key_added]. Returns a short confirmation.

Args: dataset_id: Dataset handle. method: Dissimilarity metric (e.g. nonmissing_hamming, weighted_hamming, hamming). characters_key: obsm key holding the character matrix. key_added: obsp key to store the distance map under.

Rank features by heritability on a tree (Moran's I / Geary's C autocorrelation).

Answers "which genes are most heritable on this lineage tree?". Builds tree neighbors, then computes spatial autocorrelation of each feature over that graph. Requires an expression/feature matrix in .X (or a named layer): var_names are the features scored. Results are also stored in tdata.uns["moranI"]/["gearyC"].

Args: dataset_id: Dataset handle. tree_key: Which tree in obst to use. keys: Feature names to score (default: all var_names). n_neighbors: Number of tree neighbors per cell for the connectivity graph. method: "moran" (Moran's I) or "geary" (Geary's C). layer: Optional layer to use instead of .X. top_n: Number of top-ranked features to return.

Partition a tree into clades at a given depth; labels written to obs[key_added].

Infer internal-node states for the given keys (obs cols / var / obsm) on a tree.

Methods include "mean" (continuous) and parsimony-based (Fitch-Hartigan / Sankoff) depending on the data. Results are written as node attributes on the tree.

Compute the total parsimony (number of mutations) of a tree given its characters.

Compare two trees in the same dataset.

Metrics:

• "rf": Robinson-Foulds distance (also returns RF/RF_max as normalized).

• "triplets": mean fraction of triplets correctly resolved.

Plot a lineage tree, optionally with a character-matrix / annotation heatmap.

Renders with pycea and returns the figure inline plus the path it was saved to. Use keys to draw annotation bars beside the leaves -- pass the character-matrix obsm key (e.g. "characters"), obs columns, or gene names to visualize alongside the tree.

Args: dataset_id: Dataset handle. tree_key: Which tree in obst to plot. keys: Annotation(s) to draw beside the tree (obsm key, obs cols, or var_names). polar: Draw the tree radially instead of rectangularly. branch_color: Edge color, or an edge/obs attribute name to color by. node_color: Optional node color or attribute name. annotation_width: Width of each annotation column (fraction of plot). depth_key: Node attribute to use for depth/branch lengths (default: topological). width: Figure width in inches. height: Figure height in inches. dpi: Figure resolution. save_path: Where to write the PNG (default: /plots/_.png).

Simulate a ground-truth tree topology and register it as a new dataset.

Methods:

• "complete_binary": a complete binary tree (pass e.g. {"depth": 6} or {"num_cells": 64} in extra_options).

• "birth_death": a birth-death process (pass e.g. {"birth_rate": 1.0, "death_rate": 0.0, "num_extant": 100} in extra_options).

The tree is stored in obst[key_added]. Follow with simulate_characters to add a character matrix for benchmarking reconstruction.

Args: method: "complete_binary" or "birth_death". key_added: obst key for the simulated tree. extra_options: Keyword args forwarded to the cassiopeia.sim function.

Simulate a lineage-tracing character matrix on a dataset's simulated tree.

Populates obsm["characters"] via stochastic Cas9-style tracing, optionally adding heritable/stochastic missing data and sequencing noise.

Args: dataset_id: Dataset handle containing a simulated tree. mutation_rate: Per-site mutation (cut) rate. number_of_cassettes: Number of independent cassettes. size_of_cassette: Number of characters per cassette. number_of_states: Number of possible indel states per character. add_missing: Apply cassiopeia.sim.missing_data after tracing. add_noise: Apply cassiopeia.sim.noise (miscalls) after tracing. extra_options: Extra kwargs forwarded to stochastic_tracing.

Launch the cellxlineage interactive web viewer on a dataset.

Accepts a loaded dataset_id (persisted to .h5td automatically) or a path to an existing .h5td file. Spawns cellxlineage launch as a background process and returns the URL and PID (stop it with the PID when done).

Requires the optional cellxlineage package to be installed (see the error message if it is missing). Note: this starts a long-running web server on the host running the MCP server.

Args: dataset_id_or_path: A loaded dataset_id or a path to a .h5td file. port: Port to serve on. host: Host/interface to bind.