refactor sopa.stats -> sopa.spatial

docs/api/spatial.md

@@ -0,0 +1,23 @@
+::: sopa.spatial.mean_distance
+    options:
+      show_root_heading: true
+
+::: sopa.spatial.geometrize_niches
+    options:
+      show_root_heading: true
+
+::: sopa.spatial.niches_geometry_stats
+    options:
+      show_root_heading: true
+
+::: sopa.spatial.cells_to_groups
+    options:
+      show_root_heading: true
+
+::: sopa.spatial.spatial_neighbors
+    options:
+      show_root_heading: true
+
+::: sopa.spatial.prepare_network
+    options:
+      show_root_heading: true

sopa/stats/__init__.py → sopa/spatial/__init__.py

@@ -1,3 +1,3 @@
 from ._build import spatial_neighbors
 from .morpho import geometrize_niches, niches_geometry_stats
-from .distance import cells_to_groups, mean_distance
+from .distance import cells_to_groups, mean_distance, prepare_network

sopa/stats/_build.py → sopa/spatial/_build.py

@@ -137,6 +137,6 @@ def _build_connectivity(
 
 
 def _check_has_delaunay(adata: AnnData):
-    message = " key not in adata.obsp, consider running the delaunay graph (e.g., `from sopa.stats import spatial_neighbors; spatial_neighbors(adata, [0, 40])`)"
+    message = " key not in adata.obsp, consider running the delaunay graph (e.g., `from sopa.spatial import spatial_neighbors; spatial_neighbors(adata, [0, 40])`)"
     assert "spatial_connectivities" in adata.obsp, "spatial_connectivities" + message
     assert "spatial_distances" in adata.obsp, "spatial_distances" + message

sopa/stats/distance.py → sopa/spatial/distance.py

@@ -99,4 +99,62 @@ def mean_distance(
         df_distances.replace(0, np.nan, inplace=True)
 
     df_distances[group_key] = adata.obs[group_key]
-    return df_distances.groupby(group_key, observed=False).mean()
+    df_distances = df_distances.groupby(group_key, observed=False).mean()
+    df_distances.columns.name = target_group_key
+
+    return df_distances
+
+
+def prepare_network(
+    adata: AnnData,
+    cell_type_key: str,
+    niche_key: str,
+    clip_weight: float = 3,
+    node_colors: tuple[str] = ("#5c7dc4", "#f05541"),
+    node_sizes: float = (1.3, 5),
+) -> tuple[pd.DataFrame, dict, dict, dict]:
+    """Create a dataframe representing weights between cell-types and/or niches.
+    This can be later use to plot a cell-type/niche represention of a whole slide
+    using the netgraph library.
+
+    Args:
+        adata: An `AnnData` object
+        cell_type_key: Key of `adata.obs` containing the cell types
+        niche_key: Key of `adata.obs` containing the niches
+        clip_weight: Maximum weight
+        node_colors: Tuple of (cell-type color, niche color)
+        node_sizes: Tuple of (cell-type size, niche size)
+
+    Returns:
+        A DataFrame of weights between cell-types and/or niches, and three dict for netgraph display
+    """
+    node_color, node_size, node_shape = {}, {}, {}
+
+    log.info("Computing all distances for the 4 pairs of categories")
+    weights = mean_distance(adata, cell_type_key)
+    top_right = mean_distance(adata, cell_type_key, niche_key)
+    bottom_left = mean_distance(adata, niche_key, cell_type_key)
+    bottom_right = mean_distance(adata, niche_key, niche_key)
+
+    for pop in weights.index:
+        node_color[pop] = node_colors[0]
+        node_size[pop] = node_sizes[0]
+        node_shape[pop] = "o"
+
+    for niche in bottom_right.index:
+        node_color[niche] = node_colors[1]
+        node_size[niche] = node_sizes[1]
+        node_shape[niche] = "h"
+
+    # assemble dataframe per-block
+    bottom_left[bottom_right.columns] = bottom_right
+    weights[top_right.columns] = top_right
+    weights = pd.concat([weights, bottom_left], axis=0).copy()
+
+    # convert distances to symmetric weights
+    weights = 1 / weights
+    np.fill_diagonal(weights.values, 0)
+    weights = weights.clip(0, clip_weight)
+    weights = (weights.T + weights) / 2
+
+    return weights, node_color, node_size, node_shape

sopa/stats/morpho.py → sopa/spatial/morpho.py

@@ -112,7 +112,7 @@ def _clean_components(
 def niches_geometry_stats(
     adata: AnnData | SpatialData,
     niche_key: str,
-    aggregation: str | list[str] = "mean",
+    aggregation: str | list[str] = "min",
     key_added_suffix: str = "_distance_to_niche_",
     **geometrize_niches_kwargs: str,
 ) -> gpd.GeoDataFrame:
@@ -130,7 +130,7 @@ def niches_geometry_stats(
         niche_key: Key of `adata.obs` containing the niches
         aggregation: Aggregation mode. Either one string such as `"min"`, or a list such as `["mean", "min"]`.
         key_added_suffix: Suffix added in the DataFrame columns. Defaults to "_distance_to_niche_".
-        geometrize_niches_kwargs: Kwargs to the `sopa.stats.geometrize_niches` function
+        geometrize_niches_kwargs: Kwargs to the `sopa.spatial.geometrize_niches` function
 
     Returns:
         A `DataFrame` of shape `n_niches * n_statistics`