cellestial 0.53.0__tar.gz → 0.55.0__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.53.0 → cellestial-0.55.0}/PKG-INFO +1 -1
  2. {cellestial-0.53.0 → cellestial-0.55.0}/cellestial/__init__.py +2 -0
  3. {cellestial-0.53.0 → cellestial-0.55.0}/cellestial/_version.py +1 -0
  4. {cellestial-0.53.0 → cellestial-0.55.0}/cellestial/frames/build.py +4 -7
  5. {cellestial-0.53.0 → cellestial-0.55.0}/cellestial/frames/operations.py +3 -5
  6. {cellestial-0.53.0 → cellestial-0.55.0}/cellestial/layers/outline.py +1 -1
  7. {cellestial-0.53.0 → cellestial-0.55.0}/cellestial/single/base/base.py +2 -3
  8. {cellestial-0.53.0 → cellestial-0.55.0}/cellestial/single/common/xyplot.py +2 -3
  9. {cellestial-0.53.0 → cellestial-0.55.0}/cellestial/single/core/dimensional.py +13 -3
  10. {cellestial-0.53.0 → cellestial-0.55.0}/cellestial/single/core/subdimensional.py +5 -1
  11. {cellestial-0.53.0 → cellestial-0.55.0}/cellestial/single/core/utilities.py +2 -3
  12. {cellestial-0.53.0 → cellestial-0.55.0}/cellestial/single/differential/markers.py +2 -3
  13. {cellestial-0.53.0 → cellestial-0.55.0}/cellestial/single/differential/utilities.py +3 -5
  14. {cellestial-0.53.0 → cellestial-0.55.0}/cellestial/single/differential/volcano.py +2 -3
  15. {cellestial-0.53.0 → cellestial-0.55.0}/cellestial/single/heatmap/dotplot.py +2 -3
  16. {cellestial-0.53.0 → cellestial-0.55.0}/cellestial/single/heatmap/heatmap.py +2 -3
  17. {cellestial-0.53.0 → cellestial-0.55.0}/cellestial/single/heatmap/stacked_violin.py +2 -3
  18. {cellestial-0.53.0 → cellestial-0.55.0}/cellestial/single/heatmap/utilities.py +2 -3
  19. {cellestial-0.53.0 → cellestial-0.55.0}/cellestial/single/quick/elbow.py +2 -3
  20. {cellestial-0.53.0 → cellestial-0.55.0}/cellestial/single/quick/highest.py +2 -3
  21. {cellestial-0.53.0 → cellestial-0.55.0}/cellestial/single/quick/ridge.py +5 -3
  22. {cellestial-0.53.0 → cellestial-0.55.0}/cellestial/spatial/spatial.py +7 -3
  23. {cellestial-0.53.0 → cellestial-0.55.0}/cellestial/spatial/utilities.py +2 -3
  24. {cellestial-0.53.0 → cellestial-0.55.0}/cellestial/util/__init__.py +6 -1
  25. {cellestial-0.53.0 → cellestial-0.55.0}/cellestial/util/errors.py +7 -0
  26. {cellestial-0.53.0 → cellestial-0.55.0}/cellestial/util/markers.py +2 -3
  27. {cellestial-0.53.0 → cellestial-0.55.0}/cellestial/util/operations.py +139 -0
  28. {cellestial-0.53.0 → cellestial-0.55.0}/cellestial/util/utilities.py +25 -3
  29. {cellestial-0.53.0 → cellestial-0.55.0}/pyproject.toml +1 -1
  30. {cellestial-0.53.0 → cellestial-0.55.0}/LICENSE +0 -0
  31. {cellestial-0.53.0 → cellestial-0.55.0}/README.md +0 -0
  32. {cellestial-0.53.0 → cellestial-0.55.0}/cellestial/datasets/__init__.py +0 -0
  33. {cellestial-0.53.0 → cellestial-0.55.0}/cellestial/datasets/datasets.py +0 -0
  34. {cellestial-0.53.0 → cellestial-0.55.0}/cellestial/frames/__init__.py +0 -0
  35. {cellestial-0.53.0 → cellestial-0.55.0}/cellestial/layers/__init__.py +0 -0
  36. {cellestial-0.53.0 → cellestial-0.55.0}/cellestial/layers/_deferred.py +0 -0
  37. {cellestial-0.53.0 → cellestial-0.55.0}/cellestial/layers/arrow.py +0 -0
  38. {cellestial-0.53.0 → cellestial-0.55.0}/cellestial/layers/bracket.py +0 -0
  39. {cellestial-0.53.0 → cellestial-0.55.0}/cellestial/layers/ondata_legend.py +0 -0
  40. {cellestial-0.53.0 → cellestial-0.55.0}/cellestial/layers/stream.py +0 -0
  41. {cellestial-0.53.0 → cellestial-0.55.0}/cellestial/layers/utilities.py +0 -0
  42. {cellestial-0.53.0 → cellestial-0.55.0}/cellestial/single/__init__.py +0 -0
  43. {cellestial-0.53.0 → cellestial-0.55.0}/cellestial/single/base/__init__.py +0 -0
  44. {cellestial-0.53.0 → cellestial-0.55.0}/cellestial/single/basic/__init__.py +0 -0
  45. {cellestial-0.53.0 → cellestial-0.55.0}/cellestial/single/basic/bar.py +0 -0
  46. {cellestial-0.53.0 → cellestial-0.55.0}/cellestial/single/basic/scatter.py +0 -0
  47. {cellestial-0.53.0 → cellestial-0.55.0}/cellestial/single/common/__init__.py +0 -0
  48. {cellestial-0.53.0 → cellestial-0.55.0}/cellestial/single/common/xyplots.py +0 -0
  49. {cellestial-0.53.0 → cellestial-0.55.0}/cellestial/single/core/__init__.py +0 -0
  50. {cellestial-0.53.0 → cellestial-0.55.0}/cellestial/single/core/distribution.py +0 -0
  51. {cellestial-0.53.0 → cellestial-0.55.0}/cellestial/single/core/distributions.py +0 -0
  52. {cellestial-0.53.0 → cellestial-0.55.0}/cellestial/single/core/subdimensionals.py +0 -0
  53. {cellestial-0.53.0 → cellestial-0.55.0}/cellestial/single/differential/__init__.py +0 -0
  54. {cellestial-0.53.0 → cellestial-0.55.0}/cellestial/single/heatmap/__init__.py +0 -0
  55. {cellestial-0.53.0 → cellestial-0.55.0}/cellestial/single/quick/__init__.py +0 -0
  56. {cellestial-0.53.0 → cellestial-0.55.0}/cellestial/spatial/__init__.py +0 -0
  57. {cellestial-0.53.0 → cellestial-0.55.0}/cellestial/spatial/spatials.py +0 -0
  58. {cellestial-0.53.0 → cellestial-0.55.0}/cellestial/themes/__init__.py +0 -0
  59. {cellestial-0.53.0 → cellestial-0.55.0}/cellestial/themes/_distributions.py +0 -0
  60. {cellestial-0.53.0 → cellestial-0.55.0}/cellestial/themes/_heatmaps.py +0 -0
  61. {cellestial-0.53.0 → cellestial-0.55.0}/cellestial/themes/_scatters.py +0 -0
  62. {cellestial-0.53.0 → cellestial-0.55.0}/cellestial/util/colors.py +0 -0
  63. {cellestial-0.53.0 → cellestial-0.55.0}/cellestial/util/dendrogram.py +0 -0
  64. {cellestial-0.53.0 → cellestial-0.55.0}/cellestial/util/save.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: cellestial
3
- Version: 0.53.0
3
+ Version: 0.55.0
4
4
  Summary: Interactive single-cell and spatial omics visualization library
5
5
  License-Expression: Apache-2.0
6
6
  License-File: LICENSE
@@ -41,6 +41,7 @@ from cellestial.util import (
41
41
  get_figure,
42
42
  get_figures,
43
43
  get_mapping,
44
+ layout,
44
45
  marker_genes,
45
46
  marker_genes_dict,
46
47
  retrieve,
@@ -92,6 +93,7 @@ __all__ = [
92
93
  "get_mapping",
93
94
  "heatmap",
94
95
  "highest_expressed_genes",
96
+ "layout",
95
97
  "marker_genes",
96
98
  "marker_genes_dict",
97
99
  "markers",
@@ -20,6 +20,7 @@ def versions():
20
20
  """
21
21
  packages = [
22
22
  "cellestial",
23
+ "lets-plot",
23
24
  "scanpy",
24
25
  "anndata",
25
26
  "polars",
@@ -8,7 +8,7 @@ import polars as pl
8
8
  from anndata import AnnData
9
9
  from scipy.sparse import issparse
10
10
 
11
- from cellestial.util.errors import UnsupportedDataTypeError, VariableNotFoundError
11
+ from cellestial.util.errors import VariableNotFoundError, _unsupported_data_type
12
12
 
13
13
  if TYPE_CHECKING:
14
14
  from collections.abc import Sequence
@@ -104,8 +104,7 @@ def anndata_observations_frame(
104
104
  """
105
105
  # Check if data is an AnnData object
106
106
  if not isinstance(data, AnnData):
107
- msg = f"Unsupported data type: `{type(data)}`"
108
- raise UnsupportedDataTypeError(msg)
107
+ raise _unsupported_data_type(data, AnnData)
109
108
  if not isinstance(data.obs, pd.DataFrame): # in case of Dataset2D
110
109
  part = data.obs.to_memory()
111
110
  else:
@@ -213,8 +212,7 @@ def anndata_variables_frame(
213
212
  """
214
213
  # PART 1: INITIALIZE
215
214
  if not isinstance(data, AnnData):
216
- msg = f"Unsupported data type: `{type(data)}`"
217
- raise UnsupportedDataTypeError(msg)
215
+ raise _unsupported_data_type(data, AnnData)
218
216
  if not isinstance(data.var, pd.DataFrame): # in case of Dataset2D
219
217
  part = data.var.to_memory()
220
218
  else:
@@ -413,7 +411,6 @@ def build_frame(
413
411
  msg = "`axis` parameter must be specified, 0 for observations, 1 for variables."
414
412
  raise ValueError(msg)
415
413
  else:
416
- msg = f"Unsupported data type: `{type(data)}`"
417
- raise UnsupportedDataTypeError(msg)
414
+ raise _unsupported_data_type(data, AnnData, SpatialData)
418
415
 
419
416
  return frame
@@ -6,7 +6,7 @@ from anndata import AnnData
6
6
  from polars import DataFrame
7
7
  from scipy.sparse import issparse
8
8
 
9
- from cellestial.util.errors import UnsupportedDataTypeError
9
+ from cellestial.util.errors import UnsupportedDataTypeError, _unsupported_data_type
10
10
 
11
11
 
12
12
  def _highest_expressed_genes_frame(
@@ -54,8 +54,7 @@ def _highest_expressed_genes_frame(
54
54
  # BUILD: polars frame keyed by gene name
55
55
  frame = pl.DataFrame({gene: X_top_normalized[:, i] for i, gene in enumerate(genes)})
56
56
  else:
57
- msg = f"Unsupported data type: `{type(data)}`"
58
- raise UnsupportedDataTypeError(msg)
57
+ raise _unsupported_data_type(data, AnnData)
59
58
 
60
59
  return frame
61
60
 
@@ -90,7 +89,6 @@ def _pca_variance_frame(
90
89
  }
91
90
  )
92
91
  else:
93
- msg = f"Unsupported data type: `{type(data)}`"
94
- raise UnsupportedDataTypeError(msg)
92
+ raise _unsupported_data_type(data, AnnData)
95
93
 
96
94
  return frame
@@ -38,7 +38,7 @@ def _get_density_boundaries(
38
38
  groups = [[g] if isinstance(g, str) else list(g) for g in groups]
39
39
 
40
40
  requested = {g for group in groups for g in group}
41
- available = set(frame.get_column(group_by).unique().to_list())
41
+ available = set(frame.get_column(group_by).drop_nulls().unique().to_list())
42
42
  missing = requested - available
43
43
  if missing:
44
44
  msg = (
@@ -7,7 +7,7 @@ from lets_plot import ggplot
7
7
 
8
8
  from cellestial.frames import build_frame
9
9
  from cellestial.util import _determine_axis
10
- from cellestial.util.errors import UnsupportedDataTypeError
10
+ from cellestial.util.errors import _unsupported_data_type
11
11
 
12
12
  if TYPE_CHECKING:
13
13
  from collections.abc import Sequence
@@ -93,8 +93,7 @@ def plot(
93
93
  """
94
94
  # Handling Data types
95
95
  if not isinstance(data, AnnData):
96
- msg = f"Unsupported data type: `{type(data)}`"
97
- raise UnsupportedDataTypeError(msg)
96
+ raise _unsupported_data_type(data, AnnData)
98
97
 
99
98
  # BUILD: the dataframe
100
99
  if mapping is not None:
@@ -21,7 +21,7 @@ from cellestial.util import (
21
21
  _select_variable_keys,
22
22
  _validate_tooltips,
23
23
  )
24
- from cellestial.util.errors import UnsupportedDataTypeError
24
+ from cellestial.util.errors import _unsupported_data_type
25
25
 
26
26
  if TYPE_CHECKING:
27
27
  from collections.abc import Sequence
@@ -158,8 +158,7 @@ def xyplot(
158
158
  """
159
159
  # Handling Data types
160
160
  if not isinstance(data, AnnData):
161
- msg = f"Unsupported data type: `{type(data)}`"
162
- raise UnsupportedDataTypeError(msg)
161
+ raise _unsupported_data_type(data, AnnData)
163
162
 
164
163
  # HANDLE: mapping
165
164
  _mapping = aes(x=x, y=y)
@@ -24,12 +24,14 @@ from cellestial.themes import _THEME_DIMENSION
24
24
  from cellestial.util import (
25
25
  _collect_aes_columns,
26
26
  _color_gradient,
27
+ _reject_sequence_key,
28
+ _require_feature_key,
27
29
  _resolve_embedding_key,
28
30
  _resolve_tooltips,
29
31
  _validate_tooltips,
30
32
  _warn,
31
33
  )
32
- from cellestial.util.errors import UnsupportedDataTypeError
34
+ from cellestial.util.errors import _unsupported_data_type
33
35
 
34
36
  if TYPE_CHECKING:
35
37
  from lets_plot.plot.core import PlotSpec
@@ -171,6 +173,10 @@ def dimensional(
171
173
  ------
172
174
  UnsupportedDataTypeError
173
175
  If `data` is not a supported single-cell data object.
176
+ TypeError
177
+ If `key` is a sequence of keys; use `dimensionals` for multiple keys.
178
+ KeyNotFoundError
179
+ If `key` is not found in observation metadata or variable names.
174
180
  KeyError
175
181
  If `xy` does not contain exactly two dimensions.
176
182
 
@@ -205,8 +211,12 @@ def dimensional(
205
211
  """
206
212
  # HANDLE: Data types
207
213
  if not isinstance(data, AnnData):
208
- msg = f"Unsupported data type: `{type(data)}`"
209
- raise UnsupportedDataTypeError(msg)
214
+ raise _unsupported_data_type(data, AnnData)
215
+
216
+ # HANDLE: key
217
+ _reject_sequence_key(key, singular="dimensional", plural="dimensionals")
218
+ if frame is None:
219
+ _require_feature_key(data, key)
210
220
 
211
221
  # HANDLE: mapping
212
222
  mapping = mapping or aes()
@@ -3,7 +3,7 @@ from __future__ import annotations
3
3
  from typing import TYPE_CHECKING, Literal
4
4
 
5
5
  from cellestial.single.core.dimensional import dimensional
6
- from cellestial.util import _is_variable_key
6
+ from cellestial.util import _is_variable_key, _reject_sequence_key
7
7
  from cellestial.util.errors import VariableNotFoundError
8
8
 
9
9
  if TYPE_CHECKING:
@@ -169,6 +169,7 @@ def umap(
169
169
  cl.umap(data,key="CD14",axis_type="arrow",color_high="red")
170
170
 
171
171
  """
172
+ _reject_sequence_key(key, singular="umap", plural="umaps")
172
173
  return dimensional(
173
174
  data=data,
174
175
  key=key,
@@ -360,6 +361,7 @@ def tsne(
360
361
  cl.tsne(data,key="CD14",axis_type="arrow",color_high="red")
361
362
 
362
363
  """ # noqa: D403
364
+ _reject_sequence_key(key, singular="tsne", plural="tsnes")
363
365
  return dimensional(
364
366
  data=data,
365
367
  key=key,
@@ -551,6 +553,7 @@ def pca(
551
553
  cl.pca(data,key="CD14",axis_type="arrow",color_high="red")
552
554
 
553
555
  """
556
+ _reject_sequence_key(key, singular="pca", plural="pcas")
554
557
  return dimensional(
555
558
  data=data,
556
559
  key=key,
@@ -729,6 +732,7 @@ def expression(
729
732
  cl.expression(data,key="CD14",axis_type="arrow",color_high="red")
730
733
 
731
734
  """
735
+ _reject_sequence_key(key, singular="expression", plural="expressions")
732
736
  if not _is_variable_key(data, key):
733
737
  msg = f"'{key}' is not present in `variable` names"
734
738
  raise VariableNotFoundError(msg)
@@ -28,7 +28,7 @@ from cellestial.util import (
28
28
  _validate_tooltips,
29
29
  _warn,
30
30
  )
31
- from cellestial.util.errors import UnsupportedDataTypeError
31
+ from cellestial.util.errors import _unsupported_data_type
32
32
 
33
33
  if TYPE_CHECKING:
34
34
  from lets_plot.plot.core import PlotSpec
@@ -68,8 +68,7 @@ def _distribution(
68
68
  ) -> PlotSpec:
69
69
  # Handling Data types
70
70
  if not isinstance(data, AnnData):
71
- msg = f"Unsupported data type: `{type(data)}`"
72
- raise UnsupportedDataTypeError(msg)
71
+ raise _unsupported_data_type(data, AnnData)
73
72
 
74
73
  # HANDLE: mapping
75
74
  mapping = mapping or aes()
@@ -24,7 +24,7 @@ from lets_plot.plot.core import FeatureSpec, LayerSpec
24
24
 
25
25
  from cellestial.single.differential.utilities import _build_markers_frame
26
26
  from cellestial.util import _share_axis, _share_labels
27
- from cellestial.util.errors import UnsupportedDataTypeError
27
+ from cellestial.util.errors import _unsupported_data_type
28
28
 
29
29
  if TYPE_CHECKING:
30
30
  from lets_plot.plot.subplots import SupPlotsSpec
@@ -204,8 +204,7 @@ def markers(
204
204
  """
205
205
  # HANDLE: Data types
206
206
  if not isinstance(data, AnnData):
207
- msg = f"Unsupported data type: `{type(data)}`"
208
- raise UnsupportedDataTypeError(msg)
207
+ raise _unsupported_data_type(data, AnnData)
209
208
 
210
209
  if groups is not None and (not isinstance(groups, Sequence) or isinstance(groups, str)):
211
210
  msg = "`groups` must be a Sequence of strings or None"
@@ -7,7 +7,7 @@ import polars as pl
7
7
  from anndata import AnnData
8
8
 
9
9
  from cellestial.single.heatmap.utilities import _resolve_rank_genes_groups_key
10
- from cellestial.util.errors import KeyNotFoundError, UnsupportedDataTypeError
10
+ from cellestial.util.errors import KeyNotFoundError, _unsupported_data_type
11
11
 
12
12
  if TYPE_CHECKING:
13
13
  from collections.abc import Sequence
@@ -132,8 +132,7 @@ def _build_volcano_frame(
132
132
  }
133
133
  )
134
134
  else:
135
- msg = f"Unsupported data type: `{type(data)}`"
136
- raise UnsupportedDataTypeError(msg)
135
+ raise _unsupported_data_type(data, AnnData)
137
136
 
138
137
  # CRITICAL PARTS: Dataframe Operations
139
138
  # 1. -log10(pvalue) transform
@@ -303,5 +302,4 @@ def _build_markers_frame(
303
302
 
304
303
  return frame, list(selected), str(stored_group_by)
305
304
 
306
- msg = f"Unsupported data type: `{type(data)}`"
307
- raise UnsupportedDataTypeError(msg)
305
+ raise _unsupported_data_type(data, AnnData)
@@ -24,7 +24,7 @@ from lets_plot.plot.core import FeatureSpec, LayerSpec
24
24
  from cellestial.single.differential.utilities import _build_volcano_frame
25
25
  from cellestial.themes import _THEME_SCATTER_BASE
26
26
  from cellestial.util import _share_axis, _share_labels
27
- from cellestial.util.errors import UnsupportedDataTypeError
27
+ from cellestial.util.errors import _unsupported_data_type
28
28
 
29
29
  # Default volcano palette (matches the conventional EnhancedVolcano-style look):
30
30
  # brick-red for up, soft cornflower-blue for down, medium-gray for non-significant.
@@ -206,8 +206,7 @@ def volcano(
206
206
  """
207
207
  # HANDLE: Data types
208
208
  if not isinstance(data, AnnData):
209
- msg = f"Unsupported data type: `{type(data)}`"
210
- raise UnsupportedDataTypeError(msg)
209
+ raise _unsupported_data_type(data, AnnData)
211
210
 
212
211
  # BUILD: dataframe via the helper
213
212
  frame = _build_volcano_frame(
@@ -37,7 +37,7 @@ from cellestial.util import (
37
37
  _validate_tooltips,
38
38
  _warn,
39
39
  )
40
- from cellestial.util.errors import UnsupportedDataTypeError
40
+ from cellestial.util.errors import _unsupported_data_type
41
41
 
42
42
  if TYPE_CHECKING:
43
43
  from collections.abc import Mapping, Sequence
@@ -261,8 +261,7 @@ def dotplot(
261
261
  """
262
262
  # HANDLE: Data types
263
263
  if not isinstance(data, AnnData):
264
- msg = f"Unsupported data type: `{type(data)}`"
265
- raise UnsupportedDataTypeError(msg)
264
+ raise _unsupported_data_type(data, AnnData)
266
265
 
267
266
  if markers:
268
267
  keys, group_by = _resolve_rank_genes_groups_args(
@@ -39,7 +39,7 @@ from cellestial.util import (
39
39
  _get_dendrogram_path_frame,
40
40
  _warn,
41
41
  )
42
- from cellestial.util.errors import UnsupportedDataTypeError
42
+ from cellestial.util.errors import _unsupported_data_type
43
43
 
44
44
  if TYPE_CHECKING:
45
45
  from collections.abc import Mapping, Sequence
@@ -311,8 +311,7 @@ def heatmap(
311
311
 
312
312
  """
313
313
  if not isinstance(data, AnnData):
314
- msg = f"Unsupported data type: `{type(data)}`"
315
- raise UnsupportedDataTypeError(msg)
314
+ raise _unsupported_data_type(data, AnnData)
316
315
 
317
316
  if markers:
318
317
  keys, group_by = _resolve_rank_genes_groups_args(
@@ -35,7 +35,7 @@ from cellestial.util import (
35
35
  _resolve_tooltips,
36
36
  _validate_tooltips,
37
37
  )
38
- from cellestial.util.errors import UnsupportedDataTypeError
38
+ from cellestial.util.errors import _unsupported_data_type
39
39
 
40
40
  if TYPE_CHECKING:
41
41
  from collections.abc import Mapping, Sequence
@@ -284,8 +284,7 @@ def stacked_violin(
284
284
  """
285
285
  # HANDLE: Data types
286
286
  if not isinstance(data, AnnData):
287
- msg = f"Unsupported data type: `{type(data)}`"
288
- raise UnsupportedDataTypeError(msg)
287
+ raise _unsupported_data_type(data, AnnData)
289
288
 
290
289
  if markers:
291
290
  keys, group_by = _resolve_rank_genes_groups_args(
@@ -10,7 +10,7 @@ from lets_plot import aes, geom_path, geom_text
10
10
  from scipy.stats import gaussian_kde
11
11
 
12
12
  from cellestial.util import _warn
13
- from cellestial.util.errors import DuplicateKeysError, KeyNotFoundError, UnsupportedDataTypeError
13
+ from cellestial.util.errors import DuplicateKeysError, KeyNotFoundError, _unsupported_data_type
14
14
 
15
15
  if TYPE_CHECKING:
16
16
  from collections.abc import Sequence
@@ -685,8 +685,7 @@ def _extract_rank_genes_groups(
685
685
 
686
686
  return keys, str(stored_group_by)
687
687
 
688
- msg = f"Unsupported data type: `{type(data)}`"
689
- raise UnsupportedDataTypeError(msg)
688
+ raise _unsupported_data_type(data, AnnData)
690
689
 
691
690
 
692
691
  def _resolve_rank_genes_groups_args(
@@ -16,7 +16,7 @@ from lets_plot import (
16
16
 
17
17
  from cellestial.frames import _pca_variance_frame
18
18
  from cellestial.themes import _THEME_SCATTER_BASE
19
- from cellestial.util.errors import UnsupportedDataTypeError
19
+ from cellestial.util.errors import _unsupported_data_type
20
20
 
21
21
  if TYPE_CHECKING:
22
22
  from lets_plot.plot.core import FeatureSpec, PlotSpec
@@ -120,8 +120,7 @@ def elbow(
120
120
  """
121
121
  # Handling Data types
122
122
  if not isinstance(data, AnnData):
123
- msg = f"Unsupported data type: `{type(data)}`"
124
- raise UnsupportedDataTypeError(msg)
123
+ raise _unsupported_data_type(data, AnnData)
125
124
 
126
125
  # BUILD: variance ratio frame
127
126
  frame = _pca_variance_frame(
@@ -12,7 +12,7 @@ from lets_plot import (
12
12
 
13
13
  from cellestial.frames import _highest_expressed_genes_frame
14
14
  from cellestial.themes import _THEME_HIGHEST
15
- from cellestial.util.errors import UnsupportedDataTypeError
15
+ from cellestial.util.errors import _unsupported_data_type
16
16
 
17
17
  if TYPE_CHECKING:
18
18
  from lets_plot.plot.core import FeatureSpec, PlotSpec
@@ -115,8 +115,7 @@ def highest_expressed_genes(
115
115
  """
116
116
  # Handling Data types
117
117
  if not isinstance(data, AnnData):
118
- msg = f"Unsupported data type: `{type(data)}`"
119
- raise UnsupportedDataTypeError(msg)
118
+ raise _unsupported_data_type(data, AnnData)
120
119
 
121
120
  # HANDLE: mapping
122
121
  defaults = aes(x=variable_column, y=value_column, fill=variable_column).as_dict()
@@ -18,11 +18,12 @@ from cellestial.frames import build_frame
18
18
  from cellestial.util import (
19
19
  _collect_aes_columns,
20
20
  _determine_axis,
21
+ _reject_sequence_key,
21
22
  _resolve_tooltips,
22
23
  _validate_tooltips,
23
24
  _warn,
24
25
  )
25
- from cellestial.util.errors import UnsupportedDataTypeError
26
+ from cellestial.util.errors import _unsupported_data_type
26
27
 
27
28
  if TYPE_CHECKING:
28
29
  from collections.abc import Sequence
@@ -149,8 +150,9 @@ def ridge(
149
150
  """
150
151
  # Handling Data types
151
152
  if not isinstance(data, AnnData):
152
- msg = f"Unsupported data type: `{type(data)}`"
153
- raise UnsupportedDataTypeError(msg)
153
+ raise _unsupported_data_type(data, AnnData)
154
+
155
+ _reject_sequence_key(key, singular="ridge", plural="ridges")
154
156
 
155
157
  # HANDLE: mapping
156
158
  mapping = mapping or aes()
@@ -26,11 +26,12 @@ from cellestial.util import (
26
26
  _collect_aes_columns,
27
27
  _color_gradient,
28
28
  _fill_gradient,
29
+ _reject_sequence_key,
29
30
  _resolve_tooltips,
30
31
  _validate_tooltips,
31
32
  _warn,
32
33
  )
33
- from cellestial.util.errors import UnsupportedDataTypeError
34
+ from cellestial.util.errors import _unsupported_data_type
34
35
 
35
36
  if TYPE_CHECKING:
36
37
  from typing import Literal
@@ -196,6 +197,8 @@ def spatial(
196
197
  ------
197
198
  UnsupportedDataTypeError
198
199
  If `data` is not a supported spatial data object.
200
+ TypeError
201
+ If `key` is a sequence of keys; use `spatials` for multiple keys.
199
202
  KeyError
200
203
  If a requested table, image, shape, or coordinate system is missing.
201
204
  ValueError
@@ -267,8 +270,9 @@ def spatial(
267
270
  from spatialdata import SpatialData
268
271
 
269
272
  if not isinstance(data, (AnnData, SpatialData)):
270
- msg = f"Unsupported data type: `{type(data)}`"
271
- raise UnsupportedDataTypeError(msg)
273
+ raise _unsupported_data_type(data, AnnData, SpatialData)
274
+
275
+ _reject_sequence_key(key, singular="spatial", plural="spatials")
272
276
 
273
277
  image_array, spot_coordinates, polygon_frame, data = _spatial_components(
274
278
  data,
@@ -8,7 +8,7 @@ import polars as pl
8
8
  from anndata import AnnData
9
9
 
10
10
  from cellestial.util import _warn
11
- from cellestial.util.errors import UnsupportedDataTypeError
11
+ from cellestial.util.errors import _unsupported_data_type
12
12
 
13
13
  if TYPE_CHECKING:
14
14
  from numpy.typing import NDArray
@@ -404,5 +404,4 @@ def _spatial_components(
404
404
  _warn(f"no images found for library `{library_id}`")
405
405
  return image_array, spot_coordinates, None, data
406
406
 
407
- msg = f"Unsupported data type: `{type(data)}`"
408
- raise UnsupportedDataTypeError(msg)
407
+ raise _unsupported_data_type(data, AnnData, SpatialData)
@@ -3,7 +3,7 @@ from cellestial.util.dendrogram import (
3
3
  _get_dendrogram_path_frame,
4
4
  )
5
5
  from cellestial.util.markers import marker_genes, marker_genes_dict
6
- from cellestial.util.operations import get_figure, get_figures, get_mapping, retrieve
6
+ from cellestial.util.operations import get_figure, get_figures, get_mapping, layout, retrieve
7
7
  from cellestial.util.save import save
8
8
  from cellestial.util.utilities import (
9
9
  _collect_aes_columns,
@@ -13,6 +13,8 @@ from cellestial.util.utilities import (
13
13
  _is_observation_key,
14
14
  _is_variable_key,
15
15
  _range_inclusive,
16
+ _reject_sequence_key,
17
+ _require_feature_key,
16
18
  _resolve_embedding_key,
17
19
  _resolve_tooltips,
18
20
  _select_variable_keys,
@@ -34,6 +36,8 @@ __all__ = [
34
36
  "_is_observation_key",
35
37
  "_is_variable_key",
36
38
  "_range_inclusive",
39
+ "_reject_sequence_key",
40
+ "_require_feature_key",
37
41
  "_resolve_embedding_key",
38
42
  "_resolve_tooltips",
39
43
  "_select_variable_keys",
@@ -46,6 +50,7 @@ __all__ = [
46
50
  "get_figure",
47
51
  "get_figures",
48
52
  "get_mapping",
53
+ "layout",
49
54
  "marker_genes",
50
55
  "marker_genes_dict",
51
56
  "retrieve",
@@ -63,3 +63,10 @@ class SpatialLibraryError(Exception):
63
63
 
64
64
  class CellestialWarning(UserWarning):
65
65
  """Base category for warnings raised by cellestial."""
66
+
67
+
68
+ def _unsupported_data_type(received: object, *expected: type) -> UnsupportedDataTypeError:
69
+ """Build an `UnsupportedDataTypeError` naming the expected and received types."""
70
+ expected_names = " or ".join(cls.__name__ for cls in expected)
71
+ received_name = type(received).__name__
72
+ return UnsupportedDataTypeError(f"Expected {expected_names}, but received `{received_name}`.")
@@ -4,7 +4,7 @@ from collections.abc import Sequence
4
4
 
5
5
  from anndata import AnnData
6
6
 
7
- from cellestial.util.errors import KeyNotFoundError, UnsupportedDataTypeError
7
+ from cellestial.util.errors import KeyNotFoundError, _unsupported_data_type
8
8
 
9
9
 
10
10
  def _marker_names_per_group(
@@ -71,8 +71,7 @@ def _marker_names_per_group(
71
71
 
72
72
  markers = {group: [str(gene) for gene in names[group][:n_genes]] for group in selected}
73
73
  else:
74
- msg = f"Unsupported data type: `{type(data)}`"
75
- raise UnsupportedDataTypeError(msg)
74
+ raise _unsupported_data_type(data, AnnData)
76
75
 
77
76
  return markers
78
77
 
@@ -18,6 +18,145 @@ def _grid_figures(grid: SupPlotsSpec) -> list[PlotSpec]:
18
18
  return vars(grid)["_SupPlotsSpec__figures"]
19
19
 
20
20
 
21
+ def _normalize_widths(
22
+ plots: Sequence[Sequence[PlotSpec | SupPlotsSpec]],
23
+ widths: Sequence[float] | Sequence[Sequence[float]] | None,
24
+ ) -> list[list[float] | None]:
25
+ """Resolve `widths` into one width vector (or None) per row."""
26
+ if widths is None:
27
+ return [None] * len(plots)
28
+
29
+ if not isinstance(widths, Sequence) or isinstance(widths, str):
30
+ msg = f"`widths` must be a flat or nested sequence, but received {type(widths)}"
31
+ raise TypeError(msg)
32
+
33
+ is_nested = any(isinstance(row_widths, (list, tuple)) for row_widths in widths)
34
+ if is_nested:
35
+ if not all(isinstance(row_widths, (list, tuple)) for row_widths in widths):
36
+ msg = "`widths` mixes numbers and sub-lists; use a fully nested list, one per row."
37
+ raise ValueError(msg)
38
+ if len(widths) != len(plots):
39
+ msg = f"nested `widths` has {len(widths)} rows but `plots` has {len(plots)} rows."
40
+ raise ValueError(msg)
41
+ for index, (row, row_widths) in enumerate(zip(plots, widths, strict=True)):
42
+ if len(row_widths) != len(row):
43
+ msg = (
44
+ f"`widths[{index}]` has {len(row_widths)} values "
45
+ f"but row {index} has {len(row)} plots."
46
+ )
47
+ raise ValueError(msg)
48
+ return [list(row_widths) for row_widths in widths]
49
+
50
+ # flat widths: broadcast to every row, valid only when all rows share that length.
51
+ uneven = [index for index, row in enumerate(plots) if len(row) != len(widths)]
52
+ if uneven:
53
+ msg = (
54
+ f"flat `widths` of length {len(widths)} cannot broadcast to rows {uneven} "
55
+ "with differing plot counts; pass a nested `widths` instead."
56
+ )
57
+ raise ValueError(msg)
58
+ return [list(widths) for _ in plots]
59
+
60
+
61
+ def layout(
62
+ plots: Sequence[Sequence[PlotSpec | SupPlotsSpec] | PlotSpec | SupPlotsSpec],
63
+ *,
64
+ widths: Sequence[float] | Sequence[Sequence[float]] | None = None,
65
+ heights: Sequence[float] | None = None,
66
+ hspace: float | None = None,
67
+ vspace: float | None = None,
68
+ ) -> SupPlotsSpec:
69
+ """
70
+ Arrange plots into a grid of rows, where each inner list is one row.
71
+
72
+ Unlike a uniform grid, rows may hold different numbers of plots. Each row is
73
+ sized independently, so cells in different rows do not share column boundaries.
74
+
75
+ Parameters
76
+ ----------
77
+ plots : Sequence[Sequence[PlotSpec | SupPlotsSpec] | PlotSpec | SupPlotsSpec]
78
+ A sequence of rows. Each element is either a sequence of plots or a single
79
+ plot, which is treated as a one-plot row.
80
+ widths : Sequence[float] | Sequence[Sequence[float]] | None, default=None
81
+ Relative cell widths within each row. A nested sequence assigns widths
82
+ per row (each inner length must match that row's plot count). A flat
83
+ sequence is broadcast to every row and is only valid when all rows have
84
+ the same plot count. `None` distributes widths equally.
85
+ heights : Sequence[float] | None, default=None
86
+ Relative row heights, one value per row. `None` distributes heights equally.
87
+ hspace : float | None, default=None
88
+ Horizontal spacing between cells within a row, in pixels.
89
+ vspace : float | None, default=None
90
+ Vertical spacing between rows, in pixels.
91
+
92
+ Returns
93
+ -------
94
+ SupPlotsSpec
95
+ The composed grid.
96
+
97
+ Raises
98
+ ------
99
+ TypeError
100
+ If `plots` is not a nested sequence or `widths` is of an unexpected type.
101
+ ValueError
102
+ If any row is empty, or `widths`/`heights` lengths do not match the layout.
103
+
104
+ Examples
105
+ --------
106
+ Arrange plots into ragged rows.
107
+
108
+ .. jupyter-execute ::
109
+
110
+ import scanpy as sc
111
+ from lets_plot import *
112
+
113
+ import cellestial as cl
114
+
115
+ data = cl.datasets.pbmc3k(cache_directory="data")
116
+
117
+ first = cl.umap(data, key="CD14", axis_type="arrow")
118
+ second = cl.tsne(data, key="MALAT1", axis_type="arrow")
119
+ third = cl.umap(data, key="leiden", axis_type="arrow")
120
+
121
+ cl.layout(
122
+ [[first, second],
123
+ third],
124
+ widths=[[1, 2], [1]],
125
+ heights=[1, 1],
126
+ )
127
+
128
+ """
129
+ if not isinstance(plots, Sequence) or isinstance(plots, str):
130
+ msg = f"`plots` must be a nested sequence of rows, but received {type(plots)}"
131
+ raise TypeError(msg)
132
+ if len(plots) == 0:
133
+ msg = "`plots` must contain at least one row."
134
+ raise ValueError(msg)
135
+ plot_rows: list[list[PlotSpec | SupPlotsSpec]] = []
136
+ for index, row in enumerate(plots):
137
+ if isinstance(row, (PlotSpec, SupPlotsSpec)): # a bare plot becomes its own row.
138
+ plot_rows.append([row])
139
+ continue
140
+ if not isinstance(row, Sequence) or isinstance(row, str):
141
+ msg = f"row {index} must be a plot or a sequence of plots, but received {type(row)}"
142
+ raise TypeError(msg)
143
+ if len(row) == 0:
144
+ msg = f"row {index} is empty; every row must contain at least one plot."
145
+ raise ValueError(msg)
146
+ plot_rows.append(list(row))
147
+
148
+ if heights is not None and len(heights) != len(plot_rows):
149
+ msg = f"`heights` has {len(heights)} values but `plots` has {len(plot_rows)} rows."
150
+ raise ValueError(msg)
151
+
152
+ row_widths = _normalize_widths(plot_rows, widths)
153
+ rows = [
154
+ gggrid(row, ncol=len(row), widths=row_widths[index], hspace=hspace)
155
+ for index, row in enumerate(plot_rows)
156
+ ]
157
+ return gggrid(rows, ncol=1, heights=heights, vspace=vspace)
158
+
159
+
21
160
  def get_figure(grid: SupPlotsSpec, index: int) -> PlotSpec:
22
161
  """
23
162
  Get a single figure from a grid (SupPlotsSpec) by index.
@@ -25,7 +25,7 @@ from lets_plot import (
25
25
  from lets_plot.plot.core import FeatureSpec
26
26
  from lets_plot.plot.subplots import SupPlotsSpec
27
27
 
28
- from cellestial.util.errors import CellestialWarning, KeyNotFoundError, UnsupportedDataTypeError
28
+ from cellestial.util.errors import CellestialWarning, KeyNotFoundError, _unsupported_data_type
29
29
 
30
30
  _PACKAGE_ROOT = str(Path(__file__).parents[1])
31
31
 
@@ -401,6 +401,29 @@ def _wrap_legend(
401
401
  return legend
402
402
 
403
403
 
404
+ def _reject_sequence_key(key: object, *, singular: str, plural: str) -> None:
405
+ """Reject a non-string sequence where a single key is expected, pointing to the plural API."""
406
+ if key is None or isinstance(key, str):
407
+ return
408
+ if isinstance(key, Sequence):
409
+ msg = (
410
+ f"`{singular}` plots a single key but received {len(key)} keys. "
411
+ f"Use `{plural}` for multiple keys."
412
+ )
413
+ raise TypeError(msg)
414
+
415
+
416
+ def _require_feature_key(data: AnnData, key: str | None) -> None:
417
+ """Validate that a provided color key resolves to a known column or variable."""
418
+ if key is None:
419
+ return
420
+ if isinstance(data, AnnData):
421
+ if key in data.obs.columns or key in data.var_names:
422
+ return
423
+ msg = f"Key `{key}` not found.\nLooked in observation metadata and variable (gene) names."
424
+ raise KeyNotFoundError(msg)
425
+
426
+
404
427
  def _is_variable_key(data: AnnData, key: str | None) -> bool:
405
428
  if key is None:
406
429
  return False
@@ -646,8 +669,7 @@ def _resolve_embedding_key(
646
669
  candidates = list(data.obsm.keys())
647
670
  shapes = {key: data.obsm[key].shape[1] for key in candidates}
648
671
  else:
649
- msg = f"Unsupported data type: `{type(data)}`"
650
- raise UnsupportedDataTypeError(msg)
672
+ raise _unsupported_data_type(data, AnnData)
651
673
 
652
674
  target = f"X_{dimensions.upper()}"
653
675
  needed = max(xy)
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "cellestial"
3
- version = "0.53.0"
3
+ version = "0.55.0"
4
4
  description = "Interactive single-cell and spatial omics visualization library"
5
5
  authors = [
6
6
  { name = "Zaf4", email = "zafermolbio@gmail.com" },
File without changes
File without changes