cellestial 0.49.2__tar.gz → 0.50.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (64) hide show
  1. {cellestial-0.49.2 → cellestial-0.50.1}/PKG-INFO +9 -11
  2. {cellestial-0.49.2 → cellestial-0.50.1}/README.md +7 -9
  3. {cellestial-0.49.2 → cellestial-0.50.1}/cellestial/layers/arrow.py +1 -3
  4. {cellestial-0.49.2 → cellestial-0.50.1}/cellestial/single/common/xyplot.py +14 -8
  5. {cellestial-0.49.2 → cellestial-0.50.1}/cellestial/single/common/xyplots.py +27 -0
  6. {cellestial-0.49.2 → cellestial-0.50.1}/cellestial/single/core/dimensional.py +41 -7
  7. {cellestial-0.49.2 → cellestial-0.50.1}/cellestial/single/core/distribution.py +31 -0
  8. {cellestial-0.49.2 → cellestial-0.50.1}/cellestial/single/core/distributions.py +59 -1
  9. {cellestial-0.49.2 → cellestial-0.50.1}/cellestial/single/core/subdimensional.py +51 -0
  10. {cellestial-0.49.2 → cellestial-0.50.1}/cellestial/single/core/subdimensionals.py +146 -1
  11. {cellestial-0.49.2 → cellestial-0.50.1}/cellestial/single/core/utilities.py +32 -10
  12. {cellestial-0.49.2 → cellestial-0.50.1}/cellestial/single/differential/utilities.py +0 -2
  13. {cellestial-0.49.2 → cellestial-0.50.1}/cellestial/single/quick/ridge.py +69 -8
  14. {cellestial-0.49.2 → cellestial-0.50.1}/cellestial/spatial/spatial.py +29 -8
  15. {cellestial-0.49.2 → cellestial-0.50.1}/cellestial/spatial/spatials.py +48 -3
  16. {cellestial-0.49.2 → cellestial-0.50.1}/cellestial/spatial/utilities.py +21 -10
  17. {cellestial-0.49.2 → cellestial-0.50.1}/cellestial/util/markers.py +8 -3
  18. {cellestial-0.49.2 → cellestial-0.50.1}/cellestial/util/utilities.py +2 -2
  19. {cellestial-0.49.2 → cellestial-0.50.1}/pyproject.toml +2 -2
  20. {cellestial-0.49.2 → cellestial-0.50.1}/LICENSE +0 -0
  21. {cellestial-0.49.2 → cellestial-0.50.1}/cellestial/__init__.py +0 -0
  22. {cellestial-0.49.2 → cellestial-0.50.1}/cellestial/_version.py +0 -0
  23. {cellestial-0.49.2 → cellestial-0.50.1}/cellestial/datasets/__init__.py +0 -0
  24. {cellestial-0.49.2 → cellestial-0.50.1}/cellestial/datasets/datasets.py +0 -0
  25. {cellestial-0.49.2 → cellestial-0.50.1}/cellestial/frames/__init__.py +0 -0
  26. {cellestial-0.49.2 → cellestial-0.50.1}/cellestial/frames/build.py +0 -0
  27. {cellestial-0.49.2 → cellestial-0.50.1}/cellestial/frames/operations.py +0 -0
  28. {cellestial-0.49.2 → cellestial-0.50.1}/cellestial/layers/__init__.py +0 -0
  29. {cellestial-0.49.2 → cellestial-0.50.1}/cellestial/layers/_deferred.py +0 -0
  30. {cellestial-0.49.2 → cellestial-0.50.1}/cellestial/layers/bracket.py +0 -0
  31. {cellestial-0.49.2 → cellestial-0.50.1}/cellestial/layers/ondata_legend.py +0 -0
  32. {cellestial-0.49.2 → cellestial-0.50.1}/cellestial/layers/outline.py +0 -0
  33. {cellestial-0.49.2 → cellestial-0.50.1}/cellestial/layers/stream.py +0 -0
  34. {cellestial-0.49.2 → cellestial-0.50.1}/cellestial/layers/utilities.py +0 -0
  35. {cellestial-0.49.2 → cellestial-0.50.1}/cellestial/single/__init__.py +0 -0
  36. {cellestial-0.49.2 → cellestial-0.50.1}/cellestial/single/base/__init__.py +0 -0
  37. {cellestial-0.49.2 → cellestial-0.50.1}/cellestial/single/base/base.py +0 -0
  38. {cellestial-0.49.2 → cellestial-0.50.1}/cellestial/single/basic/__init__.py +0 -0
  39. {cellestial-0.49.2 → cellestial-0.50.1}/cellestial/single/basic/bar.py +0 -0
  40. {cellestial-0.49.2 → cellestial-0.50.1}/cellestial/single/basic/scatter.py +0 -0
  41. {cellestial-0.49.2 → cellestial-0.50.1}/cellestial/single/common/__init__.py +0 -0
  42. {cellestial-0.49.2 → cellestial-0.50.1}/cellestial/single/core/__init__.py +0 -0
  43. {cellestial-0.49.2 → cellestial-0.50.1}/cellestial/single/differential/__init__.py +0 -0
  44. {cellestial-0.49.2 → cellestial-0.50.1}/cellestial/single/differential/markers.py +0 -0
  45. {cellestial-0.49.2 → cellestial-0.50.1}/cellestial/single/differential/volcano.py +0 -0
  46. {cellestial-0.49.2 → cellestial-0.50.1}/cellestial/single/heatmap/__init__.py +0 -0
  47. {cellestial-0.49.2 → cellestial-0.50.1}/cellestial/single/heatmap/dotplot.py +0 -0
  48. {cellestial-0.49.2 → cellestial-0.50.1}/cellestial/single/heatmap/heatmap.py +0 -0
  49. {cellestial-0.49.2 → cellestial-0.50.1}/cellestial/single/heatmap/stacked_violin.py +0 -0
  50. {cellestial-0.49.2 → cellestial-0.50.1}/cellestial/single/heatmap/utilities.py +0 -0
  51. {cellestial-0.49.2 → cellestial-0.50.1}/cellestial/single/quick/__init__.py +0 -0
  52. {cellestial-0.49.2 → cellestial-0.50.1}/cellestial/single/quick/elbow.py +0 -0
  53. {cellestial-0.49.2 → cellestial-0.50.1}/cellestial/single/quick/highest.py +0 -0
  54. {cellestial-0.49.2 → cellestial-0.50.1}/cellestial/spatial/__init__.py +0 -0
  55. {cellestial-0.49.2 → cellestial-0.50.1}/cellestial/themes/__init__.py +0 -0
  56. {cellestial-0.49.2 → cellestial-0.50.1}/cellestial/themes/_distributions.py +0 -0
  57. {cellestial-0.49.2 → cellestial-0.50.1}/cellestial/themes/_heatmaps.py +0 -0
  58. {cellestial-0.49.2 → cellestial-0.50.1}/cellestial/themes/_scatters.py +0 -0
  59. {cellestial-0.49.2 → cellestial-0.50.1}/cellestial/util/__init__.py +0 -0
  60. {cellestial-0.49.2 → cellestial-0.50.1}/cellestial/util/colors.py +0 -0
  61. {cellestial-0.49.2 → cellestial-0.50.1}/cellestial/util/dendrogram.py +0 -0
  62. {cellestial-0.49.2 → cellestial-0.50.1}/cellestial/util/errors.py +0 -0
  63. {cellestial-0.49.2 → cellestial-0.50.1}/cellestial/util/operations.py +0 -0
  64. {cellestial-0.49.2 → cellestial-0.50.1}/cellestial/util/save.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: cellestial
3
- Version: 0.49.2
3
+ Version: 0.50.1
4
4
  Summary: Interactive single-cell and spatial omics visualization library
5
5
  License-Expression: Apache-2.0
6
6
  License-File: LICENSE
@@ -20,7 +20,7 @@ Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
20
20
  Classifier: Topic :: Scientific/Engineering :: Visualization
21
21
  Provides-Extra: extras
22
22
  Requires-Dist: anndata (>=0.10.8,<1.0)
23
- Requires-Dist: lets-plot (>=4.9.0,<5.0.0)
23
+ Requires-Dist: lets-plot (>=4.10.0,<5.0.0)
24
24
  Requires-Dist: matplotlib (>=3.9,<4.0) ; extra == "extras"
25
25
  Requires-Dist: polars[pyarrow] (>=1.30.0,<2.0.0)
26
26
  Requires-Dist: pooch (>=1.8.2,<2.0.0) ; extra == "extras"
@@ -44,12 +44,10 @@ Description-Content-Type: text/markdown
44
44
  [![Powered by Polars](https://img.shields.io/badge/Powered%20by-Polars-377eb8?logo=polars&logoColor=white)](https://www.pola.rs/)
45
45
  [![Graphics: Lets-Plot](https://img.shields.io/badge/Graphics-Lets--Plot-FF00CC?logo=jetbrains&logoColor=white)](https://lets-plot.org/)
46
46
 
47
- <img align="right" src="assets/cellestial.svg" alt="Cellestial Logo" width="300">
47
+ <img align="left" src="https://raw.githubusercontent.com/datavil/cellestial/master/assets/cellestial.anim.svg" alt="Cellestial Logo" width="280">
48
48
 
49
49
  The __Grammar of Graphics__ for single-cell omics.
50
50
 
51
- ## Introduction
52
-
53
51
  __Cellestial__ is an interactive and a highly customizable _Single-Cell_ & _Spatial_ omics data visualization library. Built on top [Lets-Plot](https://lets-plot.org/), it offers a ggplot-like layered and modular approach offering __high customizability__ and __publication-ready figures__.
54
52
 
55
53
  Cellestial is highly integrated with scverse's [AnnData](https://github.com/scverse/anndata) with room for integration with any upcoming single-cell omics data type in the Python single-cell omics ecosystem.
@@ -90,7 +88,7 @@ cl.umap(
90
88
  ```
91
89
 
92
90
  <p align="center">
93
- <img src="assets/first-umap.svg" alt="UMAP coloured by cell type" width="600">
91
+ <img src="https://raw.githubusercontent.com/datavil/cellestial/master/assets/first-umap.svg" alt="UMAP coloured by cell type" width="600">
94
92
  </p>
95
93
 
96
94
  ## Examples
@@ -120,7 +118,7 @@ gggrid(
120
118
  </details>
121
119
 
122
120
  <p align="center">
123
- <img src="assets/spatial-categorical.svg" alt="Spatial categorical overlay" width="800">
121
+ <img src="https://raw.githubusercontent.com/datavil/cellestial/master/assets/spatial-categorical.svg" alt="Spatial categorical overlay" width="800">
124
122
  </p>
125
123
 
126
124
  ### Dimensionality reduction with layers
@@ -157,7 +155,7 @@ gggrid([outlined, streamed])
157
155
  </details>
158
156
 
159
157
  <p align="center">
160
- <img src="assets/dimensionality-layers.svg" alt="UMAP with cluster outlines and velocity stream" width="800">
158
+ <img src="https://raw.githubusercontent.com/datavil/cellestial/master/assets/dimensionality-layers.svg" alt="UMAP with cluster outlines and velocity stream" width="800">
161
159
  </p>
162
160
 
163
161
  ### Marker genes
@@ -194,7 +192,7 @@ cl.heatmap(
194
192
  </details>
195
193
 
196
194
  <p align="center">
197
- <img src="assets/heatmap.svg" alt="Marker gene heatmap" width="700">
195
+ <img src="https://raw.githubusercontent.com/datavil/cellestial/master/assets/heatmap.svg" alt="Marker gene heatmap" width="700">
198
196
  </p>
199
197
 
200
198
  ### Statistical comparisons
@@ -226,7 +224,7 @@ cl.boxplot(
226
224
  </details>
227
225
 
228
226
  <p align="center">
229
- <img src="assets/boxplot-bracket.svg" alt="Boxplot with significance brackets" width="600">
227
+ <img src="https://raw.githubusercontent.com/datavil/cellestial/master/assets/boxplot-bracket.svg" alt="Boxplot with significance brackets" width="600">
230
228
  </p>
231
229
 
232
230
  ### Ridge plots
@@ -248,7 +246,7 @@ cl.ridge(
248
246
  </details>
249
247
 
250
248
  <p align="center">
251
- <img src="assets/ridge.svg" alt="Ridge plot of B2M expression" width="600">
249
+ <img src="https://raw.githubusercontent.com/datavil/cellestial/master/assets/ridge.svg" alt="Ridge plot of B2M expression" width="600">
252
250
  </p>
253
251
 
254
252
  ## Migrating from Scanpy
@@ -7,12 +7,10 @@
7
7
  [![Powered by Polars](https://img.shields.io/badge/Powered%20by-Polars-377eb8?logo=polars&logoColor=white)](https://www.pola.rs/)
8
8
  [![Graphics: Lets-Plot](https://img.shields.io/badge/Graphics-Lets--Plot-FF00CC?logo=jetbrains&logoColor=white)](https://lets-plot.org/)
9
9
 
10
- <img align="right" src="assets/cellestial.svg" alt="Cellestial Logo" width="300">
10
+ <img align="left" src="https://raw.githubusercontent.com/datavil/cellestial/master/assets/cellestial.anim.svg" alt="Cellestial Logo" width="280">
11
11
 
12
12
  The __Grammar of Graphics__ for single-cell omics.
13
13
 
14
- ## Introduction
15
-
16
14
  __Cellestial__ is an interactive and a highly customizable _Single-Cell_ & _Spatial_ omics data visualization library. Built on top [Lets-Plot](https://lets-plot.org/), it offers a ggplot-like layered and modular approach offering __high customizability__ and __publication-ready figures__.
17
15
 
18
16
  Cellestial is highly integrated with scverse's [AnnData](https://github.com/scverse/anndata) with room for integration with any upcoming single-cell omics data type in the Python single-cell omics ecosystem.
@@ -53,7 +51,7 @@ cl.umap(
53
51
  ```
54
52
 
55
53
  <p align="center">
56
- <img src="assets/first-umap.svg" alt="UMAP coloured by cell type" width="600">
54
+ <img src="https://raw.githubusercontent.com/datavil/cellestial/master/assets/first-umap.svg" alt="UMAP coloured by cell type" width="600">
57
55
  </p>
58
56
 
59
57
  ## Examples
@@ -83,7 +81,7 @@ gggrid(
83
81
  </details>
84
82
 
85
83
  <p align="center">
86
- <img src="assets/spatial-categorical.svg" alt="Spatial categorical overlay" width="800">
84
+ <img src="https://raw.githubusercontent.com/datavil/cellestial/master/assets/spatial-categorical.svg" alt="Spatial categorical overlay" width="800">
87
85
  </p>
88
86
 
89
87
  ### Dimensionality reduction with layers
@@ -120,7 +118,7 @@ gggrid([outlined, streamed])
120
118
  </details>
121
119
 
122
120
  <p align="center">
123
- <img src="assets/dimensionality-layers.svg" alt="UMAP with cluster outlines and velocity stream" width="800">
121
+ <img src="https://raw.githubusercontent.com/datavil/cellestial/master/assets/dimensionality-layers.svg" alt="UMAP with cluster outlines and velocity stream" width="800">
124
122
  </p>
125
123
 
126
124
  ### Marker genes
@@ -157,7 +155,7 @@ cl.heatmap(
157
155
  </details>
158
156
 
159
157
  <p align="center">
160
- <img src="assets/heatmap.svg" alt="Marker gene heatmap" width="700">
158
+ <img src="https://raw.githubusercontent.com/datavil/cellestial/master/assets/heatmap.svg" alt="Marker gene heatmap" width="700">
161
159
  </p>
162
160
 
163
161
  ### Statistical comparisons
@@ -189,7 +187,7 @@ cl.boxplot(
189
187
  </details>
190
188
 
191
189
  <p align="center">
192
- <img src="assets/boxplot-bracket.svg" alt="Boxplot with significance brackets" width="600">
190
+ <img src="https://raw.githubusercontent.com/datavil/cellestial/master/assets/boxplot-bracket.svg" alt="Boxplot with significance brackets" width="600">
193
191
  </p>
194
192
 
195
193
  ### Ridge plots
@@ -211,7 +209,7 @@ cl.ridge(
211
209
  </details>
212
210
 
213
211
  <p align="center">
214
- <img src="assets/ridge.svg" alt="Ridge plot of B2M expression" width="600">
212
+ <img src="https://raw.githubusercontent.com/datavil/cellestial/master/assets/ridge.svg" alt="Ridge plot of B2M expression" width="600">
215
213
  </p>
216
214
 
217
215
  ## Migrating from Scanpy
@@ -95,9 +95,7 @@ def _axis_arrow_layers(
95
95
  tip_y = (yend - y0) * _TIP_FRACTION
96
96
 
97
97
  # semi-square L (stopping short of both tips), drawn as one connected path
98
- path_frame = pl.DataFrame(
99
- {"x": [xend - tip_x, x0, x0], "y": [y0, y0, yend - tip_y]}
100
- )
98
+ path_frame = pl.DataFrame({"x": [xend - tip_x, x0, x0], "y": [y0, y0, yend - tip_y]})
101
99
 
102
100
  layers = geom_path(
103
101
  data=path_frame,
@@ -26,6 +26,7 @@ if TYPE_CHECKING:
26
26
  from collections.abc import Sequence
27
27
 
28
28
  from lets_plot.plot.core import PlotSpec
29
+ from polars import DataFrame
29
30
 
30
31
 
31
32
  def xyplot(
@@ -33,6 +34,7 @@ def xyplot(
33
34
  x: str,
34
35
  y: str,
35
36
  *,
37
+ frame: DataFrame | None = None,
36
38
  mapping: FeatureSpec | None = None,
37
39
  axis: Literal[0, 1] | None = None,
38
40
  tooltips: Literal["none"] | Sequence[str] | FeatureSpec | None = None,
@@ -53,6 +55,9 @@ def xyplot(
53
55
  The key for the x-axis.
54
56
  y : str
55
57
  The key for the y-axis.
58
+ frame : DataFrame | None, default=None
59
+ A prebuilt frame to plot from. If provided, the frame is used directly and
60
+ building from `data` is skipped. Must contain the `x`, `y` and mapping columns.
56
61
  mapping : FeatureSpec | None, default=None
57
62
  Additional aesthetic mappings for the plot, the result of `aes()`.
58
63
  axis : {0,1} | None, default=None
@@ -180,14 +185,15 @@ def xyplot(
180
185
 
181
186
  # BUILD: the dataframe
182
187
  axis = _determine_axis(data=data, keys=_keys) if axis is None else axis
183
- frame = build_frame(
184
- data=data,
185
- variable_keys=variable_keys,
186
- axis=axis,
187
- observations_name=observations_name,
188
- variables_name=variables_name,
189
- include_dimensions=include_dimensions,
190
- )
188
+ if frame is None:
189
+ frame = build_frame(
190
+ data=data,
191
+ variable_keys=variable_keys,
192
+ axis=axis,
193
+ observations_name=observations_name,
194
+ variables_name=variables_name,
195
+ include_dimensions=include_dimensions,
196
+ )
191
197
  _validate_tooltips(tooltips, frame)
192
198
 
193
199
  # BUILD: the scatterplot
@@ -5,7 +5,9 @@ from typing import TYPE_CHECKING, Literal
5
5
  from lets_plot import gggrid, ggtb
6
6
  from lets_plot.plot.core import FeatureSpec, LayerSpec
7
7
 
8
+ from cellestial.frames import build_frame
8
9
  from cellestial.single.common.xyplot import xyplot
10
+ from cellestial.util import _determine_axis, _select_variable_keys
9
11
  from cellestial.util.errors import ConfilictingLengthError
10
12
 
11
13
  if TYPE_CHECKING:
@@ -185,6 +187,30 @@ def xyplots(
185
187
  msg = f"Length of x ({len(x)}) and y ({len(y)}) must be the same, or one of them must be of length 1."
186
188
  raise ConfilictingLengthError(msg)
187
189
 
190
+ # BUILD: one shared frame for all pairs, instead of rebuilding per pair.
191
+ # Mirrors `xyplot`'s build over the union of x/y and shared mapping keys.
192
+ mapping_keys = (
193
+ [key for key in mapping.as_dict().values() if key is not None] if mapping else []
194
+ )
195
+ all_keys = list(dict.fromkeys([*x, *y, *mapping_keys]))
196
+ variable_keys = _select_variable_keys(data=data, keys=all_keys)
197
+ # embedding (X_-prefixed) keys are not features; they request `include_dimensions`
198
+ feature_keys = list(all_keys)
199
+ if not include_dimensions:
200
+ for key in all_keys:
201
+ if key.startswith("X_"):
202
+ include_dimensions = True
203
+ feature_keys.remove(key)
204
+ axis = _determine_axis(data=data, keys=feature_keys) if axis is None else axis
205
+ frame = build_frame(
206
+ data=data,
207
+ variable_keys=variable_keys,
208
+ axis=axis,
209
+ observations_name=observations_name,
210
+ variables_name=variables_name,
211
+ include_dimensions=include_dimensions,
212
+ )
213
+
188
214
  # build plots
189
215
  plots = []
190
216
  for xi, yi in zip(x, y, strict=True):
@@ -192,6 +218,7 @@ def xyplots(
192
218
  data,
193
219
  x=xi,
194
220
  y=yi,
221
+ frame=frame,
195
222
  mapping=mapping,
196
223
  axis=axis,
197
224
  tooltips=tooltips,
@@ -33,18 +33,22 @@ from cellestial.util.errors import UnsupportedDataTypeError
33
33
 
34
34
  if TYPE_CHECKING:
35
35
  from lets_plot.plot.core import PlotSpec
36
+ from polars import DataFrame
36
37
 
37
38
 
38
39
  def dimensional(
39
40
  data: AnnData,
40
41
  key: str | None = None,
41
42
  *,
43
+ frame: DataFrame | None = None,
42
44
  mapping: FeatureSpec | None = None,
43
45
  dimensions: Literal["umap", "pca", "tsne"] = "umap",
44
46
  use_key: str | None = None,
45
47
  xy: tuple[int, int] | Sequence[int] = (1, 2),
46
48
  size: float | None = 0.8,
47
49
  variable_keys: Sequence[str] | str | None = None,
50
+ groups: Sequence[str] | str | None = None,
51
+ drop: Sequence[str] | str | None = None,
48
52
  tooltips: Literal["none"] | Sequence[str] | FeatureSpec | None = None,
49
53
  interactive: bool = False,
50
54
  observations_name: str = "Barcode",
@@ -76,6 +80,9 @@ def dimensional(
76
80
  key : str, default=None
77
81
  The key (cell feature) to color the points by.
78
82
  e.g., 'leiden' or 'louvain' to color by clusters or gene name for expression.
83
+ frame : DataFrame | None, default=None
84
+ A prebuilt frame to plot from. If provided, the frame is used directly and
85
+ building from `data` is skipped. Must contain the embedding and key columns.
79
86
  mapping : FeatureSpec | None, default=None
80
87
  Additional aesthetic mappings for the plot, the result of `aes()`.
81
88
  dimensions : {'umap', 'pca', 'tsne'}, default='umap'
@@ -92,6 +99,12 @@ def dimensional(
92
99
  The size of the points.
93
100
  variable_keys : str | Sequence[str] | None, default=None
94
101
  Variable keys to add to the DataFrame. If None, no additional keys are added.
102
+ groups : str | Sequence[str] | None, default=None
103
+ Show only specific groups, keeping points where `key` matches any of
104
+ them. Categorical keys only.
105
+ drop : str | Sequence[str] | None, default=None
106
+ Drop specific groups, filtering out points where `key` matches any of
107
+ them. Categorical keys only.
95
108
  tooltips: {'none'} | Sequence[str] | FeatureSpec | None, default=None
96
109
  Tooltips to show when hovering over the geom.
97
110
  Accepts Sequence[str] or result of `layer_tooltips()` for more complex tooltips.
@@ -222,15 +235,36 @@ def dimensional(
222
235
  )
223
236
 
224
237
  # BUILD: dataframe
225
- frame = build_frame(
226
- data=data,
227
- variable_keys=variable_keys,
228
- axis=0,
229
- observations_name=observations_name,
230
- include_dimensions=max(xy),
231
- )
238
+ if frame is None:
239
+ frame = build_frame(
240
+ data=data,
241
+ variable_keys=variable_keys,
242
+ axis=0,
243
+ observations_name=observations_name,
244
+ include_dimensions=max(xy),
245
+ )
232
246
  _validate_tooltips(tooltips, frame)
233
247
 
248
+ # HANDLE: groups filter (categorical-only)
249
+ if groups is not None and key is not None:
250
+ if isinstance(groups, str):
251
+ groups = [groups]
252
+ if frame[key].dtype == pl.Categorical:
253
+ frame = frame.filter(pl.col(key).is_in(list(groups)))
254
+ else:
255
+ msg = f"key `{key}` is not categorical, `groups` filter ignored"
256
+ _warn(msg)
257
+
258
+ # HANDLE: drop filter (categorical-only)
259
+ if drop is not None and key is not None:
260
+ if isinstance(drop, str):
261
+ drop = [drop]
262
+ if frame[key].dtype == pl.Categorical:
263
+ frame = frame.filter(~pl.col(key).is_in(list(drop)).fill_null(False))
264
+ else:
265
+ msg = f"key `{key}` is not categorical, `drop` filter ignored"
266
+ _warn(msg)
267
+
234
268
  # BUILD: scatter plot
235
269
  if "size" in mapping.as_dict():
236
270
  size = None
@@ -11,13 +11,17 @@ if TYPE_CHECKING:
11
11
  from collections.abc import Sequence
12
12
 
13
13
  from lets_plot.plot.core import PlotSpec
14
+ from polars import DataFrame
14
15
 
15
16
 
16
17
  def violin(
17
18
  data: AnnData,
18
19
  key: str | Sequence[str],
19
20
  *,
21
+ frame: DataFrame | None = None,
20
22
  group_by: str | None = None,
23
+ groups: Sequence[str] | str | None = None,
24
+ drop: Sequence[str] | str | None = None,
21
25
  mapping: FeatureSpec | None = None,
22
26
  axis: Literal[0, 1] | None = None,
23
27
  color: str | None = None,
@@ -51,9 +55,18 @@ def violin(
51
55
  key : str | Sequence[str]
52
56
  The key(s) to get the values (numerical).
53
57
  e.g., 'total_counts' or a gene name.
58
+ frame : DataFrame | None, default=None
59
+ A prebuilt frame to plot from. If provided, the frame is used directly and
60
+ building from `data` is skipped. Must contain the `key` and grouping columns.
54
61
  group_by : str | None, default=None
55
62
  Column to group observations on the x-axis.
56
63
  If not provided, falls back to `fill`, `color`, or the variable column.
64
+ groups : str | Sequence[str] | None, default=None
65
+ Show only specific groups, keeping rows where `group_by` matches any
66
+ of them. Categorical grouping columns only.
67
+ drop : str | Sequence[str] | None, default=None
68
+ Drop specific groups, filtering out rows where `group_by` matches any
69
+ of them. Categorical grouping columns only.
57
70
  mapping : FeatureSpec | None, default=None
58
71
  Additional aesthetic mappings for the plot, the result of `aes()`.
59
72
  axis : {0,1} | None, default=None
@@ -210,7 +223,10 @@ def violin(
210
223
  return _distribution(
211
224
  data=data,
212
225
  key=key,
226
+ frame=frame,
213
227
  group_by=group_by,
228
+ groups=groups,
229
+ drop=drop,
214
230
  mapping=mapping,
215
231
  geom="violin",
216
232
  axis=axis,
@@ -241,7 +257,10 @@ def boxplot(
241
257
  data: AnnData,
242
258
  key: str | Sequence[str],
243
259
  *,
260
+ frame: DataFrame | None = None,
244
261
  group_by: str | None = None,
262
+ groups: Sequence[str] | str | None = None,
263
+ drop: Sequence[str] | str | None = None,
245
264
  mapping: FeatureSpec | None = None,
246
265
  axis: Literal[0, 1] | None = None,
247
266
  color: str | None = None,
@@ -275,9 +294,18 @@ def boxplot(
275
294
  key : str | Sequence[str]
276
295
  The key(s) to get the values (numerical).
277
296
  e.g., 'total_counts' or a gene name.
297
+ frame : DataFrame | None, default=None
298
+ A prebuilt frame to plot from. If provided, the frame is used directly and
299
+ building from `data` is skipped. Must contain the `key` and grouping columns.
278
300
  group_by : str | None, default=None
279
301
  Column to group observations on the x-axis.
280
302
  If not provided, falls back to `fill`, `color`, or the variable column.
303
+ groups : str | Sequence[str] | None, default=None
304
+ Show only specific groups, keeping rows where `group_by` matches any
305
+ of them. Categorical grouping columns only.
306
+ drop : str | Sequence[str] | None, default=None
307
+ Drop specific groups, filtering out rows where `group_by` matches any
308
+ of them. Categorical grouping columns only.
281
309
  mapping : FeatureSpec | None, default=None
282
310
  Additional aesthetic mappings for the plot, the result of `aes()`.
283
311
  axis : {0,1} | None, default=None
@@ -428,7 +456,10 @@ def boxplot(
428
456
  return _distribution(
429
457
  data=data,
430
458
  key=key,
459
+ frame=frame,
431
460
  group_by=group_by,
461
+ groups=groups,
462
+ drop=drop,
432
463
  mapping=mapping,
433
464
  geom="boxplot",
434
465
  axis=axis,
@@ -5,8 +5,14 @@ from typing import TYPE_CHECKING, Any, Literal
5
5
  from lets_plot import gggrid, ggtb
6
6
  from lets_plot.plot.core import FeatureSpec, LayerSpec
7
7
 
8
+ from cellestial.frames import build_frame
8
9
  from cellestial.single.core.distribution import boxplot, violin
9
- from cellestial.util import _share_axis, _share_ticks
10
+ from cellestial.util import (
11
+ _determine_axis,
12
+ _select_variable_keys,
13
+ _share_axis,
14
+ _share_ticks,
15
+ )
10
16
 
11
17
  if TYPE_CHECKING:
12
18
  from collections.abc import Sequence
@@ -20,6 +26,8 @@ def violins(
20
26
  keys: Sequence[str],
21
27
  *,
22
28
  group_by: str | None = None,
29
+ groups: Sequence[str] | str | None = None,
30
+ drop: Sequence[str] | str | None = None,
23
31
  mapping: FeatureSpec | None = None,
24
32
  axis: Literal[0, 1] | None = None,
25
33
  color: str | None = None,
@@ -70,6 +78,12 @@ def violins(
70
78
  group_by : str | None, default=None
71
79
  Column to group observations on the x-axis.
72
80
  If not provided, falls back to `fill`, `color`, or the variable column.
81
+ groups : str | Sequence[str] | None, default=None
82
+ Show only specific groups, keeping rows where `group_by` matches any
83
+ of them. Categorical grouping columns only.
84
+ drop : str | Sequence[str] | None, default=None
85
+ Drop specific groups, filtering out rows where `group_by` matches any
86
+ of them. Categorical grouping columns only.
73
87
  mapping : FeatureSpec | None, default=None
74
88
  Additional aesthetic mappings for the plot, the result of `aes()`.
75
89
  axis : {0,1} | None, default=None
@@ -196,12 +210,30 @@ def violins(
196
210
  ncol=2,
197
211
  )
198
212
  """
213
+ # BUILD: one shared (wide) frame for all keys, instead of rebuilding per key.
214
+ # Axis is resolved once over all keys; mixed-axis key sets raise in `_determine_axis`.
215
+ axis = _determine_axis(data=data, keys=keys) if axis is None else axis
216
+ if isinstance(add_keys, str):
217
+ add_keys = [add_keys]
218
+ variable_keys = _select_variable_keys(data=data, keys=keys)
219
+ variable_keys.extend(_select_variable_keys(data=data, keys=add_keys))
220
+ frame = build_frame(
221
+ data=data,
222
+ variable_keys=variable_keys,
223
+ axis=axis,
224
+ observations_name=observations_name,
225
+ variables_name=variables_name,
226
+ )
227
+
199
228
  plots = []
200
229
  for i, key in enumerate(keys):
201
230
  plot = violin(
202
231
  data=data,
203
232
  key=key,
233
+ frame=frame,
204
234
  group_by=group_by,
235
+ groups=groups,
236
+ drop=drop,
205
237
  mapping=mapping,
206
238
  axis=axis,
207
239
  color=color,
@@ -259,6 +291,8 @@ def boxplots(
259
291
  keys: Sequence[str],
260
292
  *,
261
293
  group_by: str | None = None,
294
+ groups: Sequence[str] | str | None = None,
295
+ drop: Sequence[str] | str | None = None,
262
296
  mapping: FeatureSpec | None = None,
263
297
  axis: Literal[0, 1] | None = None,
264
298
  color: str | None = None,
@@ -309,6 +343,12 @@ def boxplots(
309
343
  group_by : str | None, default=None
310
344
  Column to group observations on the x-axis.
311
345
  If not provided, falls back to `fill`, `color`, or the variable column.
346
+ groups : str | Sequence[str] | None, default=None
347
+ Show only specific groups, keeping rows where `group_by` matches any
348
+ of them. Categorical grouping columns only.
349
+ drop : str | Sequence[str] | None, default=None
350
+ Drop specific groups, filtering out rows where `group_by` matches any
351
+ of them. Categorical grouping columns only.
312
352
  mapping : FeatureSpec | None, default=None
313
353
  Additional aesthetic mappings for the plot, the result of `aes()`.
314
354
  axis : {0,1} | None, default=None
@@ -432,12 +472,30 @@ def boxplots(
432
472
  ncol=2,
433
473
  )
434
474
  """
475
+ # BUILD: one shared (wide) frame for all keys, instead of rebuilding per key.
476
+ # Axis is resolved once over all keys; mixed-axis key sets raise in `_determine_axis`.
477
+ axis = _determine_axis(data=data, keys=keys) if axis is None else axis
478
+ if isinstance(add_keys, str):
479
+ add_keys = [add_keys]
480
+ variable_keys = _select_variable_keys(data=data, keys=keys)
481
+ variable_keys.extend(_select_variable_keys(data=data, keys=add_keys))
482
+ frame = build_frame(
483
+ data=data,
484
+ variable_keys=variable_keys,
485
+ axis=axis,
486
+ observations_name=observations_name,
487
+ variables_name=variables_name,
488
+ )
489
+
435
490
  plots = []
436
491
  for i, key in enumerate(keys):
437
492
  plot = boxplot(
438
493
  data=data,
439
494
  key=key,
495
+ frame=frame,
440
496
  group_by=group_by,
497
+ groups=groups,
498
+ drop=drop,
441
499
  mapping=mapping,
442
500
  axis=axis,
443
501
  color=color,