cellestial 0.49.0__tar.gz → 0.49.2__tar.gz

{cellestial-0.49.0 → cellestial-0.49.2}/PKG-INFO

@@ -1,17 +1,23 @@
 Metadata-Version: 2.4
 Name: cellestial
-Version: 0.49.0
-Summary: 
+Version: 0.49.2
+Summary: Interactive single-cell and spatial omics visualization library
 License-Expression: Apache-2.0
 License-File: LICENSE
+Keywords: anndata,bioinformatics,data-visualization,lets-plot,polars,single-cell,spatial-omics
 Author: Zaf4
 Author-email: zafermolbio@gmail.com
 Requires-Python: >=3.11,<4.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: Scientific/Engineering :: Visualization
 Provides-Extra: extras
 Requires-Dist: anndata (>=0.10.8,<1.0)
 Requires-Dist: lets-plot (>=4.9.0,<5.0.0)
@@ -23,6 +29,10 @@ Requires-Dist: scikit-image (>=0.23.1,<1.0)
 Requires-Dist: scvelo (>=0.3.3,<0.4.0) ; extra == "extras"
 Requires-Dist: spatialdata (>=0.7,<1.0)
 Requires-Dist: tqdm (>=4,<5)
+Project-URL: Documentation, https://cellestial.datavil.org
+Project-URL: Homepage, https://cellestial.datavil.org
+Project-URL: Issues, https://github.com/DataVil/Cellestial/issues
+Project-URL: Repository, https://github.com/DataVil/Cellestial
 Description-Content-Type: text/markdown
 
 # Cellestial
@@ -250,14 +260,14 @@ Cellestial mirrors most of `scanpy.pl` with a few naming shifts:
 - `groupby` becomes `group_by`, `var_names` becomes `keys`.
 - Saving is a separate `cl.save(plot, "umap.png")` call.
 
-See the [migration guide](sphinx/migrating_from_scanpy.rst) for a side-by-side mapping.
+See the [migration guide](https://cellestial.datavil.org/migrating_from_scanpy.html) for a side-by-side mapping.
 
 ## Documentation
 
-- [Quickstart](sphinx/quickstart.rst) — guided tour of the API.
-- [Features](sphinx/features.rst) — tooltips, layers, grids, colors, faceting.
-- [API reference](sphinx/API.rst) — every function.
-- [Migrating from Scanpy](sphinx/migrating_from_scanpy.rst).
+- [Quickstart](https://cellestial.datavil.org/quickstart.html) — guided tour of the API.
+- [Features](https://cellestial.datavil.org/features.html) — tooltips, layers, grids, colors, faceting.
+- [API reference](https://cellestial.datavil.org/API.html) — every function.
+- [Migrating from Scanpy](https://cellestial.datavil.org/migrating_from_scanpy.html).
 
 ## License
 

{cellestial-0.49.0 → cellestial-0.49.2}/README.md

@@ -223,14 +223,14 @@ Cellestial mirrors most of `scanpy.pl` with a few naming shifts:
 - `groupby` becomes `group_by`, `var_names` becomes `keys`.
 - Saving is a separate `cl.save(plot, "umap.png")` call.
 
-See the [migration guide](sphinx/migrating_from_scanpy.rst) for a side-by-side mapping.
+See the [migration guide](https://cellestial.datavil.org/migrating_from_scanpy.html) for a side-by-side mapping.
 
 ## Documentation
 
-- [Quickstart](sphinx/quickstart.rst) — guided tour of the API.
-- [Features](sphinx/features.rst) — tooltips, layers, grids, colors, faceting.
-- [API reference](sphinx/API.rst) — every function.
-- [Migrating from Scanpy](sphinx/migrating_from_scanpy.rst).
+- [Quickstart](https://cellestial.datavil.org/quickstart.html) — guided tour of the API.
+- [Features](https://cellestial.datavil.org/features.html) — tooltips, layers, grids, colors, faceting.
+- [API reference](https://cellestial.datavil.org/API.html) — every function.
+- [Migrating from Scanpy](https://cellestial.datavil.org/migrating_from_scanpy.html).
 
 ## License
 

{cellestial-0.49.0 → cellestial-0.49.2}/cellestial/__init__.py

@@ -37,7 +37,15 @@ from cellestial.single import (
     xyplots,
 )
 from cellestial.spatial import spatial, spatials
-from cellestial.util import get_figure, get_figures, get_mapping, retrieve, save
+from cellestial.util import (
+    get_figure,
+    get_figures,
+    get_mapping,
+    marker_genes,
+    marker_genes_dict,
+    retrieve,
+    save,
+)
 from cellestial.util.colors import (
     BLUE,
     CHERRY,
@@ -84,6 +92,8 @@ __all__ = [
     "get_mapping",
     "heatmap",
     "highest_expressed_genes",
+    "marker_genes",
+    "marker_genes_dict",
     "markers",
     "matrixplot",
     "ondata_legend",

{cellestial-0.49.0 → cellestial-0.49.2}/cellestial/layers/arrow.py

@@ -2,11 +2,14 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING, Literal
 
+import polars as pl
 from lets_plot import (
+    aes,
     arrow,
     element_blank,
     element_text,
     geom_blank,
+    geom_path,
     geom_segment,
     theme,
 )
@@ -19,6 +22,111 @@ if TYPE_CHECKING:
     from lets_plot.plot.core import FeatureSpecArray, PlotSpec
     from polars import DataFrame
 
+# fraction of each axis arm drawn as the arrowhead-bearing tip segment;
+# lets_plot caps the arrowhead to ~half the segment length, so the tip must be
+# long enough to render a full-size head
+_TIP_FRACTION = 0.3
+
+
+def _axis_arrow_layers(
+    frame: DataFrame,
+    *,
+    x: str,
+    y: str,
+    length: float,
+    size: float,
+    color: str,
+    angle: float,
+    arrow_kwargs: dict | None = None,
+) -> FeatureSpecArray:
+    """
+    Build the arrow-axis as an L-shaped path plus two arrowhead tip segments.
+
+    The semi-square L is one continuous `geom_path` that stops short of each
+    open end so the corner joins cleanly with no overlap. Each tip is completed
+    by a `geom_segment` carrying the arrowhead, meeting the path end-to-end.
+
+    Parameters
+    ----------
+    frame : `polars.DataFrame`
+        DataFrame holding the `x` and `y` columns.
+    x : str
+        Name of the x axis column.
+    y : str
+        Name of the y axis column.
+    length : float
+        Length of each axis arm as a fraction of its data range.
+    size : float
+        Line width of the path and tip segments.
+    color : str
+        Color of the path and tip segments.
+    angle : float
+        Angle of the arrowhead in degrees.
+    arrow_kwargs : dict | None
+        Additional parameters for the `arrow` layer.
+
+    Returns
+    -------
+    `FeatureSpecArray`
+        The path and tip-segment layers.
+    """
+    arrow_kwargs = arrow_kwargs or {}
+
+    x_min = frame[x].min()
+    x_max = frame[x].max()
+    y_min = frame[y].min()
+    y_max = frame[y].max()
+
+    # find total difference between the max and min for both axis
+    x_diff = x_max - x_min
+    y_diff = y_max - y_min
+
+    # find the ends of the arrows
+    xend = x_min + length * x_diff
+    yend = y_min + length * y_diff
+
+    # adjust bottom ends of arrows
+    adjust_rate = 0.025
+    x0 = x_min - x_diff * adjust_rate
+    y0 = y_min - y_diff * adjust_rate
+
+    # tip segments carry the arrowheads; the path stops short of each tip
+    tip_x = (xend - x0) * _TIP_FRACTION
+    tip_y = (yend - y0) * _TIP_FRACTION
+
+    # semi-square L (stopping short of both tips), drawn as one connected path
+    path_frame = pl.DataFrame(
+        {"x": [xend - tip_x, x0, x0], "y": [y0, y0, yend - tip_y]}
+    )
+
+    layers = geom_path(
+        data=path_frame,
+        mapping=aes(x="x", y="y"),
+        color=color,
+        size=size,
+    )
+    # X axis tip
+    layers += geom_segment(
+        x=xend - tip_x,
+        y=y0,
+        xend=xend,
+        yend=y0,
+        color=color,
+        size=size,
+        arrow=arrow(angle, **arrow_kwargs),
+    )
+    # Y axis tip
+    layers += geom_segment(
+        x=x0,
+        y=yend - tip_y,
+        xend=x0,
+        yend=yend,
+        color=color,
+        size=size,
+        arrow=arrow(angle, **arrow_kwargs),
+    )
+    return layers
+
 
 def _modify_axis(
     frame: DataFrame,
@@ -45,13 +153,13 @@ def _modify_axis(
     axis_type : {'axis', 'arrow'} | None
         Whether to use regular axis or arrows as the axis.
     arrow_size : float
-        Size of the arrow.
+        Width of the axis lines.
     arrow_color : str
         Color of the arrow.
     arrow_angle : float
         Angle of the arrow head in degrees.
     arrow_length : float
-        Length of the arrow head (px).
+        Span of each axis line as a fraction of its data range (0.25 covers 25%).
 
     Returns
     -------
@@ -86,44 +194,14 @@ def _modify_axis(
             axis_title_x=element_text(hjust=arrow_length / 2.5),  # better than 2
             axis_title_y=element_text(hjust=arrow_length / 2.5),
         )
-        x_max = frame[x].max()
-        x_min = frame[x].min()
-        y_max = frame[y].max()
-        y_min = frame[y].min()
-
-        # find total difference between the max and min for both axis
-        x_diff = x_max - x_min  # ty:ignore[unsupported-operator]
-        y_diff = y_max - y_min  # ty:ignore[unsupported-operator]
-
-        # find the ends of the arrows
-        # ensure the arrow length is the same for both axis
-        xend = x_min + arrow_length * x_diff
-        yend = y_min + arrow_length * y_diff
-
-        # adjust bottom ends of arrows
-        adjust_rate = 0.025
-        x0 = x_min - x_diff * adjust_rate
-        y0 = y_min - y_diff * adjust_rate
-
-        # X axis
-        new_layer += geom_segment(
-            x=x0,
-            y=y0,
-            xend=xend,
-            yend=y0,
-            color=arrow_color,
+        new_layer += _axis_arrow_layers(
+            frame,
+            x=x,
+            y=y,
+            length=arrow_length,
             size=arrow_size,
-            arrow=arrow(arrow_angle),
-        )
-        # Y axis
-        new_layer += geom_segment(
-            x=x0,
-            y=y0,
-            xend=x0,
-            yend=yend,
             color=arrow_color,
-            size=arrow_size,
-            arrow=arrow(arrow_angle),
+            angle=arrow_angle,
         )
     else:
         msg = f"expected 'axis' or 'arrow' for 'axis_type' argument, but received {axis_type}"
@@ -151,13 +229,13 @@ def arrow_axis(
         regardless of which plot the resulting layer is added to. When `None`,
         the layer is deferred and introspects the plot it is added to via `+`.
     size : float
-        Size of the arrow.
+        Width of the axis lines.
     color : str
         Color of the arrow.
     angle : float
         Angle of the arrow head in degrees.
     length : float
-        Length of the arrow head (px).
+        Span of each axis line as a fraction of its data range (0.25 covers 25%).
     **arrow_kwargs
         Additional parameters for the `arrow` layer.
         For more information on arrow parameters, see:
@@ -172,6 +250,10 @@ def arrow_axis(
     MissingAestheticError
         If `x` or `y` cannot be inferred from the receiving plot.
 
+    Notes
+    -----
+    Uses `geom_path` to draw the axis lines and `geom_segment` for the arrowheads.
+
     Examples
     --------
     Without arrow.
@@ -242,43 +324,15 @@ def arrow_axis(
             axis_title_x=element_text(hjust=length / 2.5),  # better than 2
             axis_title_y=element_text(hjust=length / 2.5),
         )
-        x_max = frame[x].max()
-        x_min = frame[x].min()
-        y_max = frame[y].max()
-        y_min = frame[y].min()
-
-        # find total difference between the max and min for both axis
-        x_diff = x_max - x_min
-        y_diff = y_max - y_min
-
-        # find the ends of the arrows
-        xend = x_min + length * x_diff
-        yend = y_min + length * y_diff
-
-        # adjust bottom ends of arrows
-        adjust_rate = 0.025
-        x0 = x_min - x_diff * adjust_rate
-        y0 = y_min - y_diff * adjust_rate
-
-        # X axis
-        new_layer += geom_segment(
-            x=x0,
-            y=y0,
-            xend=xend,
-            yend=y0,
-            color=color,
+        new_layer += _axis_arrow_layers(
+            frame,
+            x=x,
+            y=y,
+            length=length,
             size=size,
-            arrow=arrow(angle, **arrow_kwargs),
-        )
-        # Y axis
-        new_layer += geom_segment(
-            x=x0,
-            y=y0,
-            xend=x0,
-            yend=yend,
             color=color,
-            size=size,
-            arrow=arrow(angle, **arrow_kwargs),
+            angle=angle,
+            arrow_kwargs=arrow_kwargs,
         )
         return new_layer
 

{cellestial-0.49.0 → cellestial-0.49.2}/cellestial/single/core/dimensional.py

@@ -116,9 +116,9 @@ def dimensional(
     axis_type : {'axis', 'arrow'} | None
         Whether to use regular axis or arrows as the axis.
     arrow_length : float, default=0.25
-        Length of the arrow head (px).
+        Span of each axis line as a fraction of its data range (0.25 covers 25%).
     arrow_size : float, default=1
-        Size of the arrow.
+        Width of the axis lines.
     arrow_color : str, default='#3f3f3f'
         Color of the arrows.
     arrow_angle : float, default=10

{cellestial-0.49.0 → cellestial-0.49.2}/cellestial/single/core/distribution.py

@@ -1,222 +1,16 @@
 from __future__ import annotations
 
-from collections.abc import Sequence
 from typing import TYPE_CHECKING, Any, Literal
 
-import polars as pl
 from anndata import AnnData
-from lets_plot import (
-    aes,
-    geom_boxplot,
-    geom_jitter,
-    geom_point,
-    geom_sina,
-    geom_violin,
-    ggplot,
-    ggtb,
-    position_dodge,
-    position_jitterdodge,
-)
 from lets_plot.plot.core import FeatureSpec, PlotSpec
 
-from cellestial.frames import build_frame
-from cellestial.themes import _THEME_DIST
-from cellestial.util import (
-    _determine_axis,
-    _resolve_tooltips,
-    _select_variable_keys,
-    _validate_tooltips,
-    _warn,
-)
-from cellestial.util.errors import UnsupportedDataTypeError
+from cellestial.single.core.utilities import _distribution
 
 if TYPE_CHECKING:
-    from lets_plot.plot.core import PlotSpec
-
+    from collections.abc import Sequence
 
-def _distribution(
-    data: AnnData,
-    key: str | Sequence[str],
-    *,
-    group_by: str | None = None,
-    mapping: FeatureSpec | None = None,
-    geom: Literal["violin", "boxplot"] = "violin",
-    axis: Literal[0, 1] | None = None,
-    color: str | None = None,
-    fill: str | None = None,
-    threshold: float | None = None,
-    add_keys: Sequence[str] | str | None = None,
-    tooltips: Literal["none"] | Sequence[str] | FeatureSpec | None = None,
-    geom_fill: str | None = None,
-    geom_color: str | None = None,
-    point_color: str = "#1f1f1f",
-    point_alpha: float = 0.7,
-    point_size: float = 0.5,
-    point_geom: Literal["jitter", "point", "sina"] = "jitter",
-    point_mapping: FeatureSpec | None = None,
-    observations_name: str = "Barcode",
-    variables_name: str = "Variable",
-    show_points: bool = True,
-    interactive: bool = False,
-    value_column: str = "value",
-    variable_column: str = "variable",
-    point_kwargs: dict[str, Any] | None = None,
-    **geom_kwargs,
-) -> PlotSpec:
-    # Handling Data types
-    if not isinstance(data, AnnData):
-        msg = f"Unsupported data type: `{type(data)}`"
-        raise UnsupportedDataTypeError(msg)
-
-    # HANDLE: mapping
-    mapping = mapping or aes()
-    point_mapping = point_mapping or aes()
-
-    # merge standalone color/fill into mapping
-    _mapping = mapping.as_dict()
-    if color is not None and "color" not in _mapping:
-        _mapping["color"] = color
-    if fill is not None and "fill" not in _mapping:
-        _mapping["fill"] = fill
-    mapping = aes(**_mapping)
-
-    mapping_color = _mapping.get("color")
-    mapping_fill = _mapping.get("fill")
-
-    # convert to list if single string
-    if isinstance(key, str):
-        keys = [key]
-    elif isinstance(key, Sequence):
-        keys = list(key)
-
-    # handle value_column if single key is provided
-    if len(keys) == 1:
-        value_column = keys[0]
-
-    # determine separator (group_by)
-    group_by = group_by or mapping_fill or mapping_color
-    # initialize point kwargs if necessary
-    point_kwargs = {} if point_kwargs is None else dict(point_kwargs)
-
-    # determine index to unpivot
-    index = list(
-        dict.fromkeys(c for c in (group_by, mapping_fill, mapping_color) if c is not None)
-    )
-    if add_keys is not None:
-        if isinstance(add_keys, str):
-            add_keys = [add_keys]
-        index.extend(add_keys)
-
-    # DETERMINE: axis if not provided
-    axis = _determine_axis(data=data, keys=keys) if axis is None else axis
-
-    # BUILD: the DataFrame
-    variable_keys = _select_variable_keys(data=data, keys=keys)
-    variable_keys.extend(_select_variable_keys(data=data, keys=add_keys))
-    frame = build_frame(
-        data=data,
-        variable_keys=variable_keys,
-        axis=axis,
-        observations_name=observations_name,
-        variables_name=variables_name,
-    )
-
-    if group_by is not None:
-        frame = frame.filter(pl.col(group_by).is_not_null())
-
-    frame = frame.unpivot(
-        on=keys, index=index, value_name=value_column, variable_name=variable_column
-    )
-    frame = frame.drop_nulls(subset=[value_column])
-    if threshold is not None:
-        frame = frame.filter(pl.col(value_column) >= threshold)
-    if group_by is None:
-        group_by = variable_column
-    elif len(keys) > 1 and group_by != variable_column:
-        _warn(
-            f"Multiple keys provided; `group_by={group_by!r}` cannot share the "
-            f"x-axis with the variable column. Falling back to "
-            f"`group_by={variable_column!r}`. For a per-key panel, use the plural variant."
-        )
-        group_by = variable_column
-
-    # HANDLE: tooltips
-    tooltips = _resolve_tooltips(
-        tooltips,
-        data=data,
-        variable_keys=variable_keys,
-        defaults=[variable_column, value_column],
-    )
-    _validate_tooltips(tooltips, frame)
-
-    # BUILD: the plot
-    dst = ggplot(data=frame) + _THEME_DIST
-
-    # add the geom layer
-    if geom == "violin":
-        dst += geom_violin(
-            mapping=aes(
-                x=group_by,
-                y=value_column,
-                **mapping.as_dict(),
-            ),
-            fill=geom_fill,
-            color=geom_color,
-            tooltips=frame.columns,
-            **geom_kwargs,
-        )
-    elif geom == "boxplot":
-        dst += geom_boxplot(
-            mapping=aes(
-                x=group_by,
-                y=value_column,
-                **mapping.as_dict(),
-            ),
-            fill=geom_fill,
-            color=geom_color,
-            tooltips=frame.columns,
-            **geom_kwargs,
-        )
-
-    # handle the points (jitter,point,sina)
-    if show_points:
-        if point_geom in ["jitter", "point", "sina"]:
-            geom_functions = {
-                "jitter": geom_jitter,
-                "point": geom_point,
-                "sina": geom_sina,
-            }
-            dodge_width = geom_kwargs.get("width", 0.95)
-            positions = {
-                "jitter": position_jitterdodge(dodge_width=dodge_width),
-                "point": position_dodge(width=dodge_width),
-                "sina": None,
-            }
-            geom_function = geom_functions.get(point_geom, geom_jitter)
-            if "position" not in point_kwargs:
-                position = positions.get(point_geom, position_jitterdodge())
-            else:
-                position = point_kwargs.pop("position")
-
-            point_kwargs.update(color=point_color, alpha=point_alpha, size=point_size)
-            for key in point_mapping.as_dict():
-                point_kwargs.pop(key, None)
-            dst += geom_function(
-                data=frame,
-                mapping=aes(x=group_by, y=value_column, **point_mapping.as_dict()),
-                tooltips=tooltips,
-                position=position,
-                **point_kwargs,
-            )
-        else:
-            msg = "point_geom must be one of ['jitter','point','sina']."
-            raise ValueError(msg)
-
-    # handle interactive
-    if interactive:
-        dst += ggtb(size_zoomin=-1)
-
-    return dst
+    from lets_plot.plot.core import PlotSpec
 
 
 def violin(

{cellestial-0.49.0 → cellestial-0.49.2}/cellestial/single/core/subdimensional.py

@@ -90,9 +90,9 @@ def umap(
     axis_type : {'axis', 'arrow'} | None
         Whether to use regular axis or arrows as the axis.
     arrow_length : float, default=0.25
-        Length of the arrow head (px).
+        Span of each axis line as a fraction of its data range (0.25 covers 25%).
     arrow_size : float, default=1
-        Size of the arrow.
+        Width of the axis lines.
     arrow_color : str, default='#3f3f3f'
         Color of the arrows.
     arrow_angle : float, default=10
@@ -261,9 +261,9 @@ def tsne(
     axis_type : {'axis', 'arrow'} | None
         Whether to use regular axis or arrows as the axis.
     arrow_length : float, default=0.25
-        Length of the arrow head (px).
+        Span of each axis line as a fraction of its data range (0.25 covers 25%).
     arrow_size : float, default=1
-        Size of the arrow.
+        Width of the axis lines.
     arrow_color : str, default='#3f3f3f'
         Color of the arrows.
     arrow_angle : float, default=10
@@ -432,9 +432,9 @@ def pca(
     axis_type : {'axis', 'arrow'} | None
         Whether to use regular axis or arrows as the axis.
     arrow_length : float, default=0.25
-        Length of the arrow head (px).
+        Span of each axis line as a fraction of its data range (0.25 covers 25%).
     arrow_size : float, default=1
-        Size of the arrow.
+        Width of the axis lines.
     arrow_color : str, default='#3f3f3f'
         Color of the arrows.
     arrow_angle : float, default=10
@@ -606,9 +606,9 @@ def expression(
     axis_type : {'axis', 'arrow'} | None
         Whether to use regular axis or arrows as the axis.
     arrow_length : float, default=0.25
-        Length of the arrow head (px).
+        Span of each axis line as a fraction of its data range (0.25 covers 25%).
     arrow_size : float, default=1
-        Size of the arrow.
+        Width of the axis lines.
     arrow_color : str, default='#3f3f3f'
         Color of the arrows.
     arrow_angle : float, default=10