Merge branch 'main' into improve-release-process2

.pre-commit-config.yaml

@@ -10,8 +10,8 @@ repos:
       rev: 24.10.0
       hooks:
           - id: black
-    - repo: https://github.com/pre-commit/mirrors-prettier
-      rev: v4.0.0-alpha.8
+    - repo: https://github.com/rbubley/mirrors-prettier
+      rev: v3.4.2
       hooks:
           - id: prettier
     - repo: https://github.com/asottile/blacken-docs
@@ -23,7 +23,7 @@ repos:
       hooks:
           - id: isort
     - repo: https://github.com/pre-commit/mirrors-mypy
-      rev: v1.14.0
+      rev: v1.14.1
       hooks:
           - id: mypy
             additional_dependencies: [numpy, types-PyYAML]

README.md

@@ -85,6 +85,21 @@ Technologies that can be read into `SpatialData` objects using third-party libra
 
 This library is community maintained and is not officially endorsed by the aforementioned spatial technology companies. As such, we cannot offer any warranty of the correctness of the representation. Furthermore, we cannot ensure the correctness of the readers for every data version as the technologies evolve and update their formats. If you find a bug or notice a misrepresentation of the data please report it via our [Bug Tracking System](https://github.com/scverse/spatialdata-io/issues?q=sort%3Aupdated-desc+is%3Aissue+is%3Aopen) so that it can be addressed either by the maintainers of this library or by the community.
 
+## Solutions to common problems
+
+### Problem: I cannot visualize the data, everything is slow
+
+Solution: after parsing the data with `spatialdata-io` readers, you need to write it to Zarr and read it again. Otherwise the performance advantage given by the SpatialData Zarr format will not available.
+
+```python
+from spatialdata_io import xenium
+from spatialdata import read_zarr
+
+sdata = xenium("raw_data")
+sdata.write("data.zarr")
+sdata = read_zarr("sdata.zarr")
+```
+
 ## Citation
 
 Marconato, L., Palla, G., Yamauchi, K.A. et al. SpatialData: an open and universal data framework for spatial omics. Nat Methods (2024). https://doi.org/10.1038/s41592-024-02212-x

docs/api.md

@@ -1,5 +1,7 @@
 # API
 
+This section documents the Application Programming Interface (API) for the `spatialdata_io` package.
+
 ```{eval-rst}
 .. module:: spatialdata_io
 ```
@@ -10,6 +12,8 @@ I/O for the `spatialdata` project.
 
 ### Readers
 
+#### Spatial technologies
+
 ```{eval-rst}
 .. autosummary::
     :toctree: generated
@@ -18,6 +22,7 @@ I/O for the `spatialdata` project.
     cosmx
     curio
     dbit
+    experimental.iss
     mcmicro
     merscope
     seqfish
@@ -28,15 +33,15 @@ I/O for the `spatialdata` project.
     xenium
 ```
 
-### Experimental readers
+#### Data types
 
 ```{eval-rst}
-.. currentmodule:: spatialdata_io.experimental
-
 .. autosummary::
     :toctree: generated
 
-    iss
+    generic
+    image
+    geojson
 ```
 
 ### Conversion functions
@@ -47,18 +52,8 @@ I/O for the `spatialdata` project.
 .. autosummary::
     :toctree: generated
 
-```
-
-### Experimental conversion functions
-
-```{eval-rst}
-.. currentmodule:: spatialdata_io.experimental
-
-.. autosummary::
-    :toctree: generated
-
-    from_legacy_anndata
-    to_legacy_anndata
+    experimental.from_legacy_anndata
+    experimental.to_legacy_anndata
 ```
 
 ### Utility functions

docs/cli.md

@@ -0,0 +1,9 @@
+# CLI
+
+This section documents the Command Line Interface (CLI) for the `spatialdata_io` package.
+
+```{eval-rst}
+.. click:: spatialdata_io.__main__:cli
+    :prog: spatialdata_io
+    :nested: full
+```

docs/conf.py

@@ -57,6 +57,7 @@
     "sphinx_autodoc_typehints",
     "sphinx.ext.mathjax",
     "IPython.sphinxext.ipython_console_highlighting",
+    "sphinx_click",
     *[p.stem for p in (HERE / "extensions").glob("*.py")],
 ]
 

docs/index.md

@@ -7,6 +7,7 @@
 :maxdepth: 1
 
 api.md
+cli.md
 changelog.md
 contributing.md
 references.md

pyproject.toml

@@ -23,6 +23,7 @@ urls.Source = "https://github.com/scverse/spatialdata-io"
 urls.Home-page = "https://github.com/scverse/spatialdata-io"
 dependencies = [
     "anndata",
+    "click",
     "numpy",
     "scanpy",
     "spatialdata>=0.2.6",
@@ -50,6 +51,7 @@ doc = [
     "sphinxcontrib-bibtex>=1.0.0",
     "sphinx-autodoc-typehints",
     "sphinx-design",
+    "sphinx-click",
     # For notebooks
     "ipython>=8.6.0",
     "sphinx-copybutton",

src/spatialdata_io/__init__.py

@@ -1,9 +1,11 @@
 from importlib.metadata import version
 
+from spatialdata_io.converters.generic_to_zarr import generic_to_zarr
 from spatialdata_io.readers.codex import codex
 from spatialdata_io.readers.cosmx import cosmx
 from spatialdata_io.readers.curio import curio
 from spatialdata_io.readers.dbit import dbit
+from spatialdata_io.readers.generic import generic, geojson, image
 from spatialdata_io.readers.macsima import macsima
 from spatialdata_io.readers.mcmicro import mcmicro
 from spatialdata_io.readers.merscope import merscope
@@ -18,22 +20,42 @@
     xenium_explorer_selection,
 )
 
-__all__ = [
-    "curio",
-    "seqfish",
-    "visium",
-    "xenium",
+_readers_technologies = [
     "codex",
     "cosmx",
+    "curio",
+    "dbit",
+    "macsima",
     "mcmicro",
+    "merscope",
+    "seqfish",
     "steinbock",
     "stereoseq",
-    "merscope",
-    "xenium_aligned_image",
-    "xenium_explorer_selection",
-    "dbit",
+    "visium",
     "visium_hd",
-    "macsima",
+    "xenium",
 ]
 
+_readers_file_types = [
+    "generic",
+    "image",
+    "geojson",
+]
+
+_converters = [
+    "generic_to_zarr",
+]
+
+
+__all__ = (
+    [
+        "xenium_aligned_image",
+        "xenium_explorer_selection",
+    ]
+    + _readers_technologies
+    + _readers_file_types
+    + _converters
+)
+
+
 __version__ = version("spatialdata-io")