Quick Start¶

Basic usage¶

from densitree import SPADE

# X is any (n_cells, n_features) array
spade = SPADE(n_clusters=30, downsample_target=0.1, random_state=42)
labels = spade.fit_predict(X)

With a pandas DataFrame¶

Column names are automatically preserved in the result:

import pandas as pd
from densitree import SPADE

df = pd.read_csv("cytometry_data.csv")
markers = ["CD3", "CD4", "CD8", "CD19", "CD56"]

spade = SPADE(n_clusters=30, downsample_target=0.1, random_state=42)
spade.fit(df[markers])

# Cluster stats include median_CD3, median_CD4, etc.
print(spade.result_.cluster_stats_)

Visualization¶

# Static matplotlib plot
fig = spade.result_.plot_tree(color_by="CD3", backend="matplotlib")
fig.savefig("tree.png", dpi=150)

# Interactive plotly plot
fig = spade.result_.plot_tree(color_by="CD3", backend="plotly")
fig.show()

Example SPADE tree

Choosing parameters¶

Parameter	Default	Guidance
`n_clusters`	50	20--100 depending on expected complexity. More clusters = finer resolution but noisier tree.
`downsample_target`	0.05	Fraction of cells retained. Lower = faster but may lose structure. 0.05--0.2 typical.
`knn`	5	Neighborhood size for density estimation. 5--10 for most datasets.
`transform`	`"arcsinh"`	Use `"arcsinh"` for cytometry (cofactor=5 for CyTOF, 150 for flow), `"log"` for counts, `None` if pre-transformed.
`cofactor`	150.0	Arcsinh denominator. 5.0 for CyTOF, 150.0 for fluorescence.