Clusterizer

damicore_clusterizer partitions the tree graph with FastGreedy community detection.

Functions

damicore_clusterizer.cluster_tree(tree_path: str | Path, output_dir: str | Path, *, config: ClusterConfig | None = None) → ClusterResult

Cluster every node in an unrooted tree and project communities to leaves.

Takes tree.json as the tree stage writes it and runs FastGreedy over the whole tree graph, internal nodes included, then keeps only the leaves of each community. A community made entirely of internal nodes therefore disappears, which is why cluster_count can be lower than community_count. Cluster numbers are assigned by sorting the groups by their object ids, so the numbering depends on the tree rather than on FastGreedy’s internal ordering. Writes membership.csv and clusters.json into output_dir; both must be absent, since neither is overwritten. output_dir is created before that check, so a call rejected for the conflict still leaves the directory behind.

Raises:

ClusterizerError – config.num_clusters exceeds the leaf count (configuration_error); the tree artifact is missing, unparsable, not a valid unrooted binary tree, or carries a branch length of zero or too small for a finite reciprocal weight (tree_format_error); the resulting communities do not cover every leaf (clusterization_error); the outputs already exist (output_directory_conflict_error).

Models

class damicore_clusterizer.ClusterConfig(*, num_clusters: Annotated[int | None, Ge(ge=1)] = None)
num_clusters: int | None
class damicore_clusterizer.ClusterResult(*, membership_path: Path, clusters_path: Path, community_count: Annotated[int, Ge(ge=0)], cluster_count: Annotated[int, Ge(ge=0)], modularity: Annotated[float, AllowInfNan(allow_inf_nan=False)], timing: Annotated[float, Ge(ge=0)])
membership_path: Path
clusters_path: Path
community_count: int
cluster_count: int
modularity: float
timing: float

Errors

class damicore_clusterizer.ClusterizerError(message: str, *, code: str = 'clusterizer_error', **context: object)