cellestial 0.52.0__tar.gz → 0.53.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 (65) hide show
  1. {cellestial-0.52.0 → cellestial-0.53.0}/PKG-INFO +1 -2
  2. cellestial-0.53.0/cellestial/datasets/datasets.py +382 -0
  3. {cellestial-0.52.0 → cellestial-0.53.0}/pyproject.toml +1 -2
  4. cellestial-0.52.0/cellestial/datasets/datasets.py +0 -766
  5. {cellestial-0.52.0 → cellestial-0.53.0}/LICENSE +0 -0
  6. {cellestial-0.52.0 → cellestial-0.53.0}/README.md +0 -0
  7. {cellestial-0.52.0 → cellestial-0.53.0}/cellestial/__init__.py +0 -0
  8. {cellestial-0.52.0 → cellestial-0.53.0}/cellestial/_version.py +0 -0
  9. {cellestial-0.52.0 → cellestial-0.53.0}/cellestial/datasets/__init__.py +0 -0
  10. {cellestial-0.52.0 → cellestial-0.53.0}/cellestial/frames/__init__.py +0 -0
  11. {cellestial-0.52.0 → cellestial-0.53.0}/cellestial/frames/build.py +0 -0
  12. {cellestial-0.52.0 → cellestial-0.53.0}/cellestial/frames/operations.py +0 -0
  13. {cellestial-0.52.0 → cellestial-0.53.0}/cellestial/layers/__init__.py +0 -0
  14. {cellestial-0.52.0 → cellestial-0.53.0}/cellestial/layers/_deferred.py +0 -0
  15. {cellestial-0.52.0 → cellestial-0.53.0}/cellestial/layers/arrow.py +0 -0
  16. {cellestial-0.52.0 → cellestial-0.53.0}/cellestial/layers/bracket.py +0 -0
  17. {cellestial-0.52.0 → cellestial-0.53.0}/cellestial/layers/ondata_legend.py +0 -0
  18. {cellestial-0.52.0 → cellestial-0.53.0}/cellestial/layers/outline.py +0 -0
  19. {cellestial-0.52.0 → cellestial-0.53.0}/cellestial/layers/stream.py +0 -0
  20. {cellestial-0.52.0 → cellestial-0.53.0}/cellestial/layers/utilities.py +0 -0
  21. {cellestial-0.52.0 → cellestial-0.53.0}/cellestial/single/__init__.py +0 -0
  22. {cellestial-0.52.0 → cellestial-0.53.0}/cellestial/single/base/__init__.py +0 -0
  23. {cellestial-0.52.0 → cellestial-0.53.0}/cellestial/single/base/base.py +0 -0
  24. {cellestial-0.52.0 → cellestial-0.53.0}/cellestial/single/basic/__init__.py +0 -0
  25. {cellestial-0.52.0 → cellestial-0.53.0}/cellestial/single/basic/bar.py +0 -0
  26. {cellestial-0.52.0 → cellestial-0.53.0}/cellestial/single/basic/scatter.py +0 -0
  27. {cellestial-0.52.0 → cellestial-0.53.0}/cellestial/single/common/__init__.py +0 -0
  28. {cellestial-0.52.0 → cellestial-0.53.0}/cellestial/single/common/xyplot.py +0 -0
  29. {cellestial-0.52.0 → cellestial-0.53.0}/cellestial/single/common/xyplots.py +0 -0
  30. {cellestial-0.52.0 → cellestial-0.53.0}/cellestial/single/core/__init__.py +0 -0
  31. {cellestial-0.52.0 → cellestial-0.53.0}/cellestial/single/core/dimensional.py +0 -0
  32. {cellestial-0.52.0 → cellestial-0.53.0}/cellestial/single/core/distribution.py +0 -0
  33. {cellestial-0.52.0 → cellestial-0.53.0}/cellestial/single/core/distributions.py +0 -0
  34. {cellestial-0.52.0 → cellestial-0.53.0}/cellestial/single/core/subdimensional.py +0 -0
  35. {cellestial-0.52.0 → cellestial-0.53.0}/cellestial/single/core/subdimensionals.py +0 -0
  36. {cellestial-0.52.0 → cellestial-0.53.0}/cellestial/single/core/utilities.py +0 -0
  37. {cellestial-0.52.0 → cellestial-0.53.0}/cellestial/single/differential/__init__.py +0 -0
  38. {cellestial-0.52.0 → cellestial-0.53.0}/cellestial/single/differential/markers.py +0 -0
  39. {cellestial-0.52.0 → cellestial-0.53.0}/cellestial/single/differential/utilities.py +0 -0
  40. {cellestial-0.52.0 → cellestial-0.53.0}/cellestial/single/differential/volcano.py +0 -0
  41. {cellestial-0.52.0 → cellestial-0.53.0}/cellestial/single/heatmap/__init__.py +0 -0
  42. {cellestial-0.52.0 → cellestial-0.53.0}/cellestial/single/heatmap/dotplot.py +0 -0
  43. {cellestial-0.52.0 → cellestial-0.53.0}/cellestial/single/heatmap/heatmap.py +0 -0
  44. {cellestial-0.52.0 → cellestial-0.53.0}/cellestial/single/heatmap/stacked_violin.py +0 -0
  45. {cellestial-0.52.0 → cellestial-0.53.0}/cellestial/single/heatmap/utilities.py +0 -0
  46. {cellestial-0.52.0 → cellestial-0.53.0}/cellestial/single/quick/__init__.py +0 -0
  47. {cellestial-0.52.0 → cellestial-0.53.0}/cellestial/single/quick/elbow.py +0 -0
  48. {cellestial-0.52.0 → cellestial-0.53.0}/cellestial/single/quick/highest.py +0 -0
  49. {cellestial-0.52.0 → cellestial-0.53.0}/cellestial/single/quick/ridge.py +0 -0
  50. {cellestial-0.52.0 → cellestial-0.53.0}/cellestial/spatial/__init__.py +0 -0
  51. {cellestial-0.52.0 → cellestial-0.53.0}/cellestial/spatial/spatial.py +0 -0
  52. {cellestial-0.52.0 → cellestial-0.53.0}/cellestial/spatial/spatials.py +0 -0
  53. {cellestial-0.52.0 → cellestial-0.53.0}/cellestial/spatial/utilities.py +0 -0
  54. {cellestial-0.52.0 → cellestial-0.53.0}/cellestial/themes/__init__.py +0 -0
  55. {cellestial-0.52.0 → cellestial-0.53.0}/cellestial/themes/_distributions.py +0 -0
  56. {cellestial-0.52.0 → cellestial-0.53.0}/cellestial/themes/_heatmaps.py +0 -0
  57. {cellestial-0.52.0 → cellestial-0.53.0}/cellestial/themes/_scatters.py +0 -0
  58. {cellestial-0.52.0 → cellestial-0.53.0}/cellestial/util/__init__.py +0 -0
  59. {cellestial-0.52.0 → cellestial-0.53.0}/cellestial/util/colors.py +0 -0
  60. {cellestial-0.52.0 → cellestial-0.53.0}/cellestial/util/dendrogram.py +0 -0
  61. {cellestial-0.52.0 → cellestial-0.53.0}/cellestial/util/errors.py +0 -0
  62. {cellestial-0.52.0 → cellestial-0.53.0}/cellestial/util/markers.py +0 -0
  63. {cellestial-0.52.0 → cellestial-0.53.0}/cellestial/util/operations.py +0 -0
  64. {cellestial-0.52.0 → cellestial-0.53.0}/cellestial/util/save.py +0 -0
  65. {cellestial-0.52.0 → cellestial-0.53.0}/cellestial/util/utilities.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: cellestial
3
- Version: 0.52.0
3
+ Version: 0.53.0
4
4
  Summary: Interactive single-cell and spatial omics visualization library
5
5
  License-Expression: Apache-2.0
6
6
  License-File: LICENSE
@@ -24,7 +24,6 @@ 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: mudata (>=0.3.8,<0.4.0)
26
26
  Requires-Dist: polars[pyarrow] (>=1.30.0,<2.0.0)
27
- Requires-Dist: pooch (>=1.8.2,<2.0.0) ; extra == "extras"
28
27
  Requires-Dist: scanpy[leiden] (>=1.10.4,<2.0.0) ; extra == "extras"
29
28
  Requires-Dist: scikit-image (>=0.23.1,<1.0)
30
29
  Requires-Dist: scvelo (>=0.3.3,<0.4.0) ; extra == "extras"
@@ -0,0 +1,382 @@
1
+ import re
2
+ import shutil
3
+ from os import PathLike
4
+ from pathlib import Path
5
+
6
+ from anndata import AnnData, read_h5ad
7
+
8
+ _GLOBAL_CACHE = Path.home() / ".cache" / "cellestial" / "datasets"
9
+
10
+ _UUID_PATTERN = re.compile(
11
+ r"[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}",
12
+ re.IGNORECASE,
13
+ )
14
+
15
+
16
+ def _resolve_cache_file(
17
+ cache_directory: str | Path | PathLike,
18
+ filename: str,
19
+ *,
20
+ use_cache: bool,
21
+ bring: bool,
22
+ ) -> Path:
23
+ """
24
+ Prepare the cache directory and return the target cache file path.
25
+
26
+ Creates `cache_directory` if missing. When `bring` is True and the user
27
+ points at a non-default directory that doesn't yet contain `filename`,
28
+ copies the file from `_GLOBAL_CACHE` if it exists there. When `use_cache`
29
+ is False, removes the target cache file so it will be regenerated.
30
+ """
31
+ if not isinstance(cache_directory, Path):
32
+ cache_directory = Path(cache_directory)
33
+
34
+ if not cache_directory.exists():
35
+ cache_directory.mkdir(parents=True)
36
+
37
+ cache_file = cache_directory / filename
38
+
39
+ if use_cache and bring and cache_directory != _GLOBAL_CACHE and not cache_file.exists():
40
+ global_cache_file = _GLOBAL_CACHE / filename
41
+ if global_cache_file.exists():
42
+ print(f"Bringing cached file from {global_cache_file} to {cache_file}")
43
+ shutil.copy(global_cache_file, cache_file)
44
+
45
+ if not use_cache and cache_file.exists():
46
+ print(f"Removing existing cache: {cache_file}")
47
+ cache_file.unlink()
48
+
49
+ return cache_file
50
+
51
+
52
+ def pbmc3k(
53
+ cache_directory: str | Path | PathLike = _GLOBAL_CACHE,
54
+ *,
55
+ use_cache: bool = True,
56
+ bring: bool = True,
57
+ ) -> AnnData:
58
+ """
59
+ Download and load the preprocessed pbmc3k dataset.
60
+
61
+ Parameters
62
+ ----------
63
+ cache_directory : str | Path | PathLike
64
+ Directory where the `.h5ad` file is cached.
65
+ use_cache : bool, default=True
66
+ If True, load from the cached file when present. If False, remove any
67
+ existing cached file and re-download.
68
+ bring : bool, default=True
69
+ If True and `cache_directory` is not the default global cache, copy the
70
+ file from the global cache when it already exists there. Set to False
71
+ to disable this behavior.
72
+
73
+ Returns
74
+ -------
75
+ AnnData
76
+ The preprocessed pbmc3k dataset.
77
+
78
+ Raises
79
+ ------
80
+ OSError
81
+ If the downloaded file size does not match the expected size.
82
+ """
83
+ return from_url(
84
+ "https://huggingface.co/datasets/datavil/pbmc3k/resolve/main/pbmc3k_pped.h5ad",
85
+ cache_directory=cache_directory,
86
+ use_cache=use_cache,
87
+ bring=bring,
88
+ )
89
+
90
+
91
+ def pancreas(
92
+ cache_directory: str | Path | PathLike = _GLOBAL_CACHE,
93
+ *,
94
+ use_cache: bool = True,
95
+ bring: bool = True,
96
+ ) -> AnnData:
97
+ """
98
+ Download and load the preprocessed endocrinogenesis day-15 pancreas dataset.
99
+
100
+ Parameters
101
+ ----------
102
+ cache_directory : str | Path | PathLike
103
+ Directory where the `.h5ad` file is cached.
104
+ use_cache : bool, default=True
105
+ If True, load from the cached file when present. If False, remove any
106
+ existing cached file and re-download.
107
+ bring : bool, default=True
108
+ If True and `cache_directory` is not the default global cache, copy the
109
+ file from the global cache when it already exists there. Set to False
110
+ to disable this behavior.
111
+
112
+ Returns
113
+ -------
114
+ AnnData
115
+ The preprocessed pancreas dataset with velocity computed.
116
+
117
+ Raises
118
+ ------
119
+ OSError
120
+ If the downloaded file size does not match the expected size.
121
+ """
122
+ return from_url(
123
+ "https://huggingface.co/datasets/datavil/pancreas/resolve/main/endocrinogenesis_day15_pped.h5ad",
124
+ cache_directory=cache_directory,
125
+ use_cache=use_cache,
126
+ bring=bring,
127
+ )
128
+
129
+
130
+ def from_url(
131
+ url: str,
132
+ *,
133
+ name: str | None = None,
134
+ cache_directory: str | Path | PathLike = _GLOBAL_CACHE,
135
+ use_cache: bool = True,
136
+ bring: bool = True,
137
+ ) -> AnnData:
138
+ """
139
+ Download and load an `.h5ad` dataset from a direct HTTP(S) URL.
140
+
141
+ Parameters
142
+ ----------
143
+ url : str
144
+ Direct URL to a downloadable `.h5ad` file.
145
+ name : str, optional
146
+ Name for the cached file (without extension). If omitted, the cache
147
+ filename is derived from the URL's last path segment.
148
+ cache_directory : str | Path | PathLike
149
+ Directory where the `.h5ad` file is cached.
150
+ use_cache : bool, default=True
151
+ If True, load from the cached file when present. If False, remove any
152
+ existing cached file and regenerate from scratch.
153
+ bring : bool, default=True
154
+ If True and `cache_directory` is not the default global cache, copy the
155
+ file from the global cache when it already exists there. Set to False
156
+ to disable this behavior.
157
+
158
+ Returns
159
+ -------
160
+ AnnData
161
+ The downloaded dataset.
162
+
163
+ Raises
164
+ ------
165
+ ValueError
166
+ If `name` is not given and no filename can be derived from `url`.
167
+ OSError
168
+ If the downloaded file size does not match the expected size.
169
+
170
+ Notes
171
+ -----
172
+ Generic loader for any host that serves an AnnData `.h5ad` file at a
173
+ stable URL (CELLxGENE, Zenodo, Figshare, S3 buckets, etc.).
174
+ """
175
+ from urllib.parse import urlparse
176
+ from urllib.request import urlopen
177
+
178
+ from tqdm import tqdm
179
+
180
+ if name is not None:
181
+ filename = f"{name}.h5ad"
182
+ else:
183
+ filename = Path(urlparse(url).path).name
184
+ if not filename:
185
+ message = "Could not derive a filename from the URL; pass `name=...` explicitly."
186
+ raise ValueError(message)
187
+
188
+ cache_file = _resolve_cache_file(cache_directory, filename, use_cache=use_cache, bring=bring)
189
+
190
+ if cache_file.exists():
191
+ return read_h5ad(cache_file)
192
+
193
+ print(f"No cache at {cache_file} !")
194
+ print(f"Downloading from {url} ...")
195
+
196
+ block_size = 1024 * 1024
197
+ # Stream to a .part file and atomically rename on success, so an interrupted
198
+ # download cannot poison the cache.
199
+ partial_file = cache_file.with_name(cache_file.name + ".part")
200
+
201
+ with urlopen(url) as response:
202
+ total_size = int(response.headers.get("Content-Length", 0))
203
+ progress_bar = tqdm(
204
+ total=total_size, unit="iB", unit_scale=True, desc=f"Downloading {filename}"
205
+ )
206
+
207
+ try:
208
+ with partial_file.open("wb") as file:
209
+ while chunk := response.read(block_size):
210
+ progress_bar.update(len(chunk))
211
+ file.write(chunk)
212
+
213
+ if total_size != 0 and progress_bar.n != total_size:
214
+ message = (
215
+ f"Download incomplete: expected {total_size} bytes, got {progress_bar.n}."
216
+ )
217
+ raise OSError(message) # noqa: TRY301
218
+
219
+ partial_file.replace(cache_file)
220
+ except BaseException:
221
+ if partial_file.exists():
222
+ partial_file.unlink()
223
+ raise
224
+ finally:
225
+ progress_bar.close()
226
+
227
+ print(f"Saved to {cache_file}")
228
+
229
+ return read_h5ad(cache_file)
230
+
231
+
232
+ def from_cellxgene(
233
+ source: str,
234
+ *,
235
+ name: str | None = None,
236
+ cache_directory: str | Path | PathLike = _GLOBAL_CACHE,
237
+ use_cache: bool = True,
238
+ bring: bool = True,
239
+ ) -> AnnData:
240
+ """
241
+ Download and load a dataset from CELLxGENE by URL or UUID.
242
+
243
+ Parameters
244
+ ----------
245
+ source : str
246
+ A CELLxGENE dataset UUID (e.g.
247
+ `7cdea341-ca7a-40fd-8192-b8ecb2d7b91e`) or a full `.h5ad` URL (e.g.
248
+ `https://datasets.cellxgene.cziscience.com/<uuid>.h5ad`).
249
+ name : str, optional
250
+ Name for the cached file (without extension). Defaults to the dataset
251
+ UUID parsed from `source`.
252
+ cache_directory : str | Path | PathLike
253
+ Directory where the `.h5ad` file is cached.
254
+ use_cache : bool, default=True
255
+ If True, load from the cached file when present. If False, remove any
256
+ existing cached file and regenerate from scratch.
257
+ bring : bool, default=True
258
+ If True and `cache_directory` is not the default global cache, copy the
259
+ file from the global cache when it already exists there. Set to False
260
+ to disable this behavior.
261
+
262
+ Returns
263
+ -------
264
+ AnnData
265
+ The downloaded dataset.
266
+
267
+ Raises
268
+ ------
269
+ ValueError
270
+ If `source` is neither a CELLxGENE dataset UUID nor a URL containing one.
271
+ OSError
272
+ If the downloaded file size does not match the expected size.
273
+
274
+ Notes
275
+ -----
276
+ Thin wrapper around `from_url` that accepts a CELLxGENE dataset UUID
277
+ directly and constructs the canonical download URL.
278
+ """
279
+ match = _UUID_PATTERN.search(source)
280
+ if match is None:
281
+ message = (
282
+ f"source must be a CELLxGENE dataset UUID or a URL containing one, got {source!r}"
283
+ )
284
+ raise ValueError(message)
285
+
286
+ uuid = match.group(0)
287
+ url = (
288
+ source
289
+ if source.startswith(("http://", "https://"))
290
+ else f"https://datasets.cellxgene.cziscience.com/{uuid}.h5ad"
291
+ )
292
+
293
+ return from_url(
294
+ url,
295
+ name=name or uuid,
296
+ cache_directory=cache_directory,
297
+ use_cache=use_cache,
298
+ bring=bring,
299
+ )
300
+
301
+
302
+ def breast_cancer_atlas(
303
+ cache_directory: str | Path | PathLike = _GLOBAL_CACHE,
304
+ *,
305
+ use_cache: bool = True,
306
+ bring: bool = True,
307
+ ) -> AnnData:
308
+ """
309
+ Download and load the breast cancer cell atlas from CELLxGENE.
310
+
311
+ Parameters
312
+ ----------
313
+ cache_directory : str | Path | PathLike
314
+ Directory where the `.h5ad` file is cached.
315
+ use_cache : bool, default=True
316
+ If True, load from the cached file when present. If False, remove any
317
+ existing cached file and regenerate from scratch.
318
+ bring : bool, default=True
319
+ If True and `cache_directory` is not the default global cache, copy the
320
+ file from the global cache when it already exists there. Set to False
321
+ to disable this behavior.
322
+
323
+ Returns
324
+ -------
325
+ AnnData
326
+ The breast cancer atlas dataset.
327
+
328
+ Raises
329
+ ------
330
+ OSError
331
+ If the downloaded file size does not match the expected size.
332
+
333
+ Notes
334
+ -----
335
+ Thin wrapper around `from_cellxgene` with the atlas UUID baked in.
336
+ """
337
+ return from_cellxgene(
338
+ "7cdea341-ca7a-40fd-8192-b8ecb2d7b91e",
339
+ name="breast_cancer_atlas",
340
+ cache_directory=cache_directory,
341
+ use_cache=use_cache,
342
+ bring=bring,
343
+ )
344
+
345
+
346
+ def human_lymph_node(
347
+ cache_directory: str | Path | PathLike = _GLOBAL_CACHE,
348
+ *,
349
+ use_cache: bool = True,
350
+ bring: bool = True,
351
+ ) -> AnnData:
352
+ """
353
+ Download and load the preprocessed V1 Human Lymph Node Visium spatial dataset.
354
+
355
+ Parameters
356
+ ----------
357
+ cache_directory : str | Path | PathLike
358
+ Directory where the `.h5ad` file is cached.
359
+ use_cache : bool, default=True
360
+ If True, load from the cached file when present. If False, remove any
361
+ existing cached file and re-download.
362
+ bring : bool, default=True
363
+ If True and `cache_directory` is not the default global cache, copy the
364
+ file from the global cache when it already exists there. Set to False
365
+ to disable this behavior.
366
+
367
+ Returns
368
+ -------
369
+ AnnData
370
+ The preprocessed V1 Human Lymph Node Visium dataset with clusters and UMAP.
371
+
372
+ Raises
373
+ ------
374
+ OSError
375
+ If the downloaded file size does not match the expected size.
376
+ """
377
+ return from_url(
378
+ "https://huggingface.co/datasets/datavil/human_lymph_node/resolve/main/V1_Human_Lymph_Node_pped.h5ad",
379
+ cache_directory=cache_directory,
380
+ use_cache=use_cache,
381
+ bring=bring,
382
+ )
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "cellestial"
3
- version = "0.52.0"
3
+ version = "0.53.0"
4
4
  description = "Interactive single-cell and spatial omics visualization library"
5
5
  authors = [
6
6
  { name = "Zaf4", email = "zafermolbio@gmail.com" },
@@ -48,7 +48,6 @@ Issues = "https://github.com/DataVil/Cellestial/issues"
48
48
  [project.optional-dependencies]
49
49
  extras = [
50
50
  "matplotlib>=3.9,<4.0",
51
- "pooch>=1.8.2,<2.0.0",
52
51
  "scanpy[leiden]>=1.10.4,<2.0.0",
53
52
  "scvelo>=0.3.3,<0.4.0",
54
53
  ]