Merge branch 'docs-api' into v2.1

bento/__init__.py

@@ -1,6 +1,7 @@
-from . import io
-from . import plotting as pl
-from . import tools as tl
 from . import _utils as ut
 from . import geometry as geo
+from . import plotting as pl
+from . import tools as tl
+from . import io
+from .io import prep
 from .plotting import _colors as colors

bento/geometry/_geometry.py

@@ -321,6 +321,7 @@ def set_points_metadata(
         sdata.points[points_key] = sdata.points[points_key].assign(**{name: series})
 
 
+
 def set_shape_metadata(
     sdata: SpatialData,
     shape_key: str,
@@ -380,7 +381,7 @@ def _check_points_sync(sdata, points_key):
     points = sdata.points[points_key]
     if points.attrs["spatialdata_attrs"]["instance_key"] not in points.columns:
         raise ValueError(
-            f"Points {points_key} not synced to instance_key shape element. Run bento.io.format_sdata() to setup SpatialData object for bento-tools."
+            f"Points {points_key} not synced to instance_key shape element. Run bento.io.prep() to setup SpatialData object for bento-tools."
         )
 
 
@@ -407,5 +408,5 @@ def _check_shape_sync(sdata, shape_key, instance_key):
         and shape_key not in sdata.shapes[instance_key].columns
     ):
         raise ValueError(
-            f"Shape {shape_key} not synced to instance_key shape element. Run bento.io.format_sdata() to setup SpatialData object for bento-tools."
+            f"Shape {shape_key} not synced to instance_key shape element. Run bento.io.prep() to setup SpatialData object for bento-tools."
         )

bento/io/__init__.py

@@ -1 +1 @@
-from ._io import format_sdata
+from ._io import prep

bento/io/_io.py

@@ -4,19 +4,21 @@
 warnings.filterwarnings("ignore")
 
 from spatialdata._core.spatialdata import SpatialData
-from spatialdata.models import ShapesModel, TableModel
+from spatialdata.models import TableModel
 
 from ..geometry import sjoin_points, sjoin_shapes
 
 
-def format_sdata(
+def prep(
     sdata: SpatialData,
     points_key: str = "transcripts",
-    feature_key: str  = "feature_name",
+    feature_key: str = "feature_name",
     instance_key: str = "cell_boundaries",
     shape_keys: List[str] = ["cell_boundaries", "nucleus_boundaries"],
 ) -> SpatialData:
-    """Converts shape indices to strings and indexes points to shapes and add as columns to `data.points[point_key]`.
+    """Computes spatial indices for elements in SpatialData to enable usage of bento-tools.
+    
+    Specifically, this function indexes points to shapes and joins shapes to the instance shape. It also computes a count table for the points.
 
     Parameters
     ----------
@@ -61,22 +63,22 @@ def format_sdata(
             shape_sjoin.append(shape_key)
 
     if len(point_sjoin) > 0:
-        sdata = sjoin_points(
-            sdata=sdata, points_key=points_key, shape_keys=point_sjoin
-        )
+        sdata = sjoin_points(sdata=sdata, points_key=points_key, shape_keys=point_sjoin)
     if len(shape_sjoin) > 0:
         sdata = sjoin_shapes(
             sdata=sdata, instance_key=instance_key, shape_keys=shape_sjoin
-        )  
+        )
 
     # Recompute count table
-    table = TableModel.parse(sdata.aggregate(
-        values=points_key,
-        instance_key=instance_key,
-        by=instance_key,
-        value_key=feature_key,
-        aggfunc="count",
-    ).table)
+    table = TableModel.parse(
+        sdata.aggregate(
+            values=points_key,
+            instance_key=instance_key,
+            by=instance_key,
+            value_key=feature_key,
+            aggfunc="count",
+        ).table
+    )
 
     del sdata.table
     sdata.table = table

bento/plotting/__init__.py

@@ -1,5 +1,5 @@
-from ._multidimensional import flux_summary, obs_stats
+from ._multidimensional import flux_summary, shape_stats
 
 from ._lp import lp_diff_discrete, lp_dist, lp_genes
 from ._plotting import points, density, shapes, flux, fluxmap, fe
-from ._signatures import colocation, factor
+from ._signatures import colocation, factor

bento/plotting/_lp.py

@@ -120,8 +120,8 @@ def lp_genes(
 
 @savefig
 def lp_diff_discrete(sdata: SpatialData, phenotype: str, fname: str = None):
-    """Visualize gene pattern frequencies between groups of cells by plotting
-    log2 fold change and -log10p, similar to volcano plot. Run after :func:`bento.tl.lp_diff()`
+    """Visualize gene pattern frequencies between groups of cells. Plots the
+    log2 fold change and -log10 p-value of each gene, similar to volcano plot. Run after :func:`bento.tl.lp_diff_discrete()`
 
     Parameters
     ----------

bento/plotting/_plotting.py

@@ -67,6 +67,46 @@ def points(
     fname=None,
     **kwargs,
 ):
+    """
+    Plot points scatter.
+
+    Parameters
+    ----------
+    data : SpatialData
+        Spatial formatted SpatialData object
+    hue : str, optional
+        Variable name to color points by, by default None
+    hue_order : list, optional
+        Order of hue levels, by default None
+    size : str, optional
+        Variable name to size points by, by default None
+    style : str, optional
+        Variable name to style points by, by default None
+    shapes : list, optional 
+        List of shape names to plot, by default None. If None, will plot cell and nucleus shapes by default.
+    hide_outside : bool, optional
+        Whether to hide molecules outside of cells, by default True
+    title : str, optional
+        Title of plot, by default None
+    dx : float, optional    
+        Size of scalebar in units, by default 0.1
+    units : str, optional
+        Units of scalebar, by default "um"
+    square : bool, optional
+        Whether to make axis square, by default False
+    axis_visible : bool, optional
+        Whether to show axis, by default False
+    frame_visible : bool, optional
+        Whether to show frame, by default True
+    ax : matplotlib.axes.Axes, optional
+        Axis to plot on, by default None. If None, will use current axis.
+    sync_shapes : bool, optional
+        Whether to synchronize shapes with points, by default True
+    shapes_kws : dict, optional
+        Keyword arguments for shapes, by default {}
+    fname : str, optional
+        Filename to save figure to, by default None. If None, will not save figure.
+    """
 
     points = _prepare_points_df(
         sdata, 
@@ -108,6 +148,44 @@ def density(
     fname=None,
     **kwargs,
 ):
+    """
+    Plot points as 2D density.
+
+    Parameters
+    ----------
+    data : SpatialData
+        Spatial formatted SpatialData object
+    kind : str, optional
+        Type of density plot, by default "hist". Options: "hist", "kde"
+    hue : str, optional
+        Variable name to color points by, by default None
+    hue_order : list, optional
+        Order of hue levels, by default None
+    shapes : list, optional 
+        List of shape names to plot, by default None. If None, will plot cell and nucleus shapes by default.
+    hide_outside : bool, optional
+        Whether to hide molecules outside of cells, by default True
+    title : str, optional
+        Title of plot, by default None
+    dx : float, optional    
+        Size of scalebar in units, by default 0.1
+    units : str, optional
+        Units of scalebar, by default "um"
+    square : bool, optional
+        Whether to make axis square, by default False
+    axis_visible : bool, optional
+        Whether to show axis, by default False
+    frame_visible : bool, optional
+        Whether to show frame, by default True
+    ax : matplotlib.axes.Axes, optional
+        Axis to plot on, by default None. If None, will use current axis.
+    sync_shapes : bool, optional
+        Whether to synchronize shapes with points, by default True
+    shape_kws : dict, optional
+        Keyword arguments for shapes, by default {}
+    fname : str, optional
+        Filename to save figure to, by default None. If None, will not save figure.
+    """
 
     points = _prepare_points_df(
         sdata,
@@ -147,6 +225,39 @@ def shapes(
     fname=None,
     **kwargs,
 ):
+    """Plot shape layers.
+
+    Parameters
+    ----------
+    data : SpatialData
+        Spatial formatted SpatialData
+    shapes : list, optional
+        List of shapes to plot, by default None. If None, will plot cell and nucleus shapes by default.
+    color : str, optional
+        Color name, by default None. If None, will use default theme color.
+    color_style : "outline" or "fill"
+        Whether to color the outline or fill of the shape, by default "outline".
+    hide_outside : bool, optional
+        Whether to hide molecules outside of cells, by default True.
+    dx : float, optional
+        Size of scalebar in units, by default 0.1.
+    units : str, optional
+        Units of scalebar, by default "um".
+    axis_visible : bool, optional
+        Whether to show axis, by default False.
+    frame_visible : bool, optional
+        Whether to show frame, by default True.
+    title : str, optional
+        Title of plot, by default None.
+    square : bool, optional
+        Whether to make axis square, by default False.
+    ax : matplotlib.axes.Axes, optional
+        Axis to plot on, by default None. If None, will use current axis.
+    sync_shapes : bool, optional
+        Whether to synchronize shapes with points, by default True.
+    fname : str, optional
+        Filename to save figure to, by default None. If None, will not save figure.
+    """
 
     if shapes and not isinstance(shapes, list):
         shapes = [shapes]
@@ -176,23 +287,6 @@ def _shapes(
     ax=None,
     **kwargs,
 ):
-    """Plot layer(s) of shapes.
-
-    Parameters
-    ----------
-    data : SpatialData
-        Spatial formatted SpatialData
-    shapes : list, optional
-        List of shapes to plot, by default None. If None, will plot cell and nucleus shapes by default.
-    color : str, optional
-        Color name, by default None. If None, will use default theme color.
-    color_style : "outline" or "fill"
-        Whether to color the outline or fill of the shape, by default "outline".
-    hide_outside : bool, optional
-        Whether to hide molecules outside of cells, by default True.
-    ax : matplotlib.axes.Axes, optional
-        Axis to plot on, by default None. If None, will use current axis.
-    """
     if shapes is None:
         shapes = [instance_key, nucleus_key]
 
@@ -271,6 +365,39 @@ def flux(
     fname=None,
     **kwargs,
 ):
+    """Plot colorized representation of RNAflux embedding.
+
+    Parameters
+    ----------
+    data : SpatialData
+        Spatial formatted SpatialData
+    res : float, optional
+        Resolution of fluxmap, by default 0.05
+    shapes : list, optional
+        List of shapes to plot, by default None. If None, will plot cell and nucleus shapes by default.
+    hide_outside : bool, optional
+        Whether to hide molecules outside of cells, by default True.
+    axis_visible : bool, optional
+        Whether to show axis, by default False.
+    frame_visible : bool, optional
+        Whether to show frame, by default True.
+    title : str, optional
+        Title of plot, by default None.
+    dx : float, optional
+        Size of scalebar in units, by default 0.1.
+    units : str, optional
+        Units of scalebar, by default "um".
+    square : bool, optional
+        Whether to make axis square, by default False.
+    ax : matplotlib.axes.Axes, optional
+        Axis to plot on, by default None. If None, will use current axis.
+    sync_shapes : bool, optional
+        Whether to synchronize shapes with points, by default True.
+    shape_kws : dict, optional
+        Keyword arguments for shapes, by default {}.
+    fname : str, optional
+        Filename to save figure to, by default None. If None, will not save figure.
+    """
 
     if ax is None:
         ax = plt.gca()
@@ -301,6 +428,45 @@ def fe(
     fname=None,
     **kwargs,
 ):
+    """Plot spatial heatmap of flux enrichment scores.
+    
+    Parameters
+    ----------
+    data : SpatialData
+        Spatial formatted SpatialData
+    gs : str
+        Gene set name
+    res : float, optional
+        Resolution of fluxmap, by default 0.05
+    shapes : list, optional    
+        List of shape names to plot, by default None. If None, will plot cell and nucleus shapes by default.
+    cmap : str, optional
+        Colormap, by default None. If None, will use red2blue colormap.
+    cbar : bool, optional
+        Whether to show colorbar, by default True
+    hide_outside : bool, optional
+        Whether to hide molecules outside of cells, by default True.
+    axis_visible : bool, optional
+        Whether to show axis, by default False.
+    frame_visible : bool, optional
+        Whether to show frame, by default True.
+    title : str, optional
+        Title of plot, by default None.
+    dx : float, optional
+        Size of scalebar in units, by default 0.1.
+    units : str, optional
+        Units of scalebar, by default "um".
+    square : bool, optional
+        Whether to make axis square, by default False.
+    ax : matplotlib.axes.Axes, optional
+        Axis to plot on, by default None. If None, will use current axis.
+    sync_shapes : bool, optional
+        Whether to synchronize shapes with points, by default True.
+    shape_kws : dict, optional
+        Keyword arguments for shapes, by default {}.
+    fname : str, optional
+        Filename to save figure to, by default None. If None, will not save figure.
+    """
 
     if ax is None:
         ax = plt.gca()