reporting¶
Cluster reports — peak/cluster geometry plus atlas labels.
The peak/sub-peak geometry comes from get_clusters_table;
the cluster masks and mass-weighted labels are computed locally so we can
attribute every voxel of every cluster to one or more atlases.
Classes:
| Name | Description |
|---|---|
ClusterReport | Result of BrainData.cluster_report. |
Methods:
| Name | Description |
|---|---|
cluster_report_data | Compute cluster report DataFrames + thresholded BrainData. |
Classes¶
ClusterReport¶
ClusterReport(peaks: pl.DataFrame, clusters: pl.DataFrame, stat_img: BrainData) -> NoneResult of BrainData.cluster_report.
Attributes:
| Name | Type | Description |
|---|---|---|
peaks | DataFrame | Polars DataFrame, one row per peak (incl. sub-peaks). Columns cluster_id, x, y, z (mm), peak_stat, volume_mm3, n_voxels, then one Utf8 column per atlas. cluster_id shares the integer id space of clusters (they are joinable); sub-peaks carry their parent cluster’s id. |
clusters | DataFrame | Polars DataFrame, one row per cluster. Columns cluster_id, peak_x, peak_y, peak_z, mean_stat, volume_mm3, n_voxels, then one Utf8 column per atlas (mass-weighted top regions). |
stat_img | BrainData | BrainData with the thresholded stat map (sub-cluster voxels and clusters smaller than cluster_threshold zeroed). |
Methods:
| Name | Description |
|---|---|
plot | Render an overview glass brain + one slice figure per cluster. |
to_csv | Write peaks.csv and clusters.csv into output_dir. |
Methods¶
plot¶
plot(*, output_dir: str | Path | None = None) -> list[tuple[str, Figure]] | NoneRender an overview glass brain + one slice figure per cluster.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
output_dir | str | Path | None | If given, save overview.png and cluster_NN.png files into the directory and return None. If omitted, return a list of (label, matplotlib.figure.Figure) tuples without writing to disk. | None |
Returns:
| Type | Description |
|---|---|
list [ tuple [ str , Figure ]] | None | None when output_dir is set, else a list of |
list [ tuple [ str , Figure ]] | None | (label, figure) tuples. |
to_csv¶
to_csv(output_dir: str | Path) -> NoneWrite peaks.csv and clusters.csv into output_dir.
Methods¶
cluster_report_data¶
cluster_report_data(bd: BrainData, *, stat_threshold: float | None = 3.0, cluster_threshold: int = 10, two_sided: bool = True, min_distance: float = 8.0, atlas: str | Sequence[str] = DEFAULT_ATLASES, prob_threshold: float = 5.0) -> tuple[pl.DataFrame, pl.DataFrame, BrainData]Compute cluster report DataFrames + thresholded BrainData.
Pure function — the BrainData facade BrainData.cluster_report
wraps the result in a ClusterReport.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
bd | BrainData | BrainData with a 3D stat map (single sample). | required |
stat_threshold | float | None | Voxel-level threshold. None means treat bd as already thresholded (skip voxel filtering, keep all non-zero voxels). | 3.0 |
cluster_threshold | int | Minimum cluster size in voxels. | 10 |
two_sided | bool | Report negative clusters as separate clusters. | True |
min_distance | float | Minimum distance (mm) between sub-peaks. Passed to get_clusters_table. | 8.0 |
atlas | str | Sequence [ str ] | Atlas name or list of names from list_atlases. | DEFAULT_ATLASES |
prob_threshold | float | Drop probabilistic-atlas regions below this %. | 5.0 |
Returns:
| Type | Description |
|---|---|
tuple [ DataFrame , DataFrame , BrainData ] | Tuple (peaks, clusters, thresholded_bd). |