From 33006d784de5be29c47216b232adb6ceb758331a Mon Sep 17 00:00:00 2001 From: LucaMarconato <2664412+LucaMarconato@users.noreply.github.com> Date: Thu, 13 Jul 2023 17:42:40 +0200 Subject: [PATCH 1/4] fix docs --- README.md | 9 ++++++--- docs/index.md | 16 ++++++++++------ docs/installation.md | 34 +++++++++++++++++++++++++++++++--- 3 files changed, 47 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index d465c1dc..15b2d49b 100644 --- a/README.md +++ b/README.md @@ -11,12 +11,11 @@ SpatialData is a data framework that comprises a FAIR storage format and a colle - [spatialdata-io](https://github.com/scverse/spatialdata-io): load data from common spatial omics technologies into spatialdata. - [spatialdata-plot](https://github.com/scverse/spatialdata-plot): Static plotting library for spatialdata. -- [napari-spatialdata](https://github.com/scverse/napari-spatialdata): napari plugin for interactive exploration and annotation of spatialdata. +- [napari-spatialdata](https://github.com/scverse/napari-spatialdata): napari plugin for interactive exploration and annotation of spatial data. ![SpatialDataOverview](https://github.com/scverse/spatialdata/assets/1120672/cb91071f-12a7-4b8e-9430-2b3a0f65e52f) - **The library is currently under review.** We expect there to be changes as the community provides feedback. -- To get involved in the discussion, or if you need help to get started, you are welcome to join our [`scverse` Zulip chat](https://imagesc.zulipchat.com/#narrow/stream/329057-scverse/topic/segmentation) and our [scverse discourse forum](https://discourse.scverse.org/). - The SpatialData storage format is built on top of the [OME-NGFF](https://ngff.openmicroscopy.org/latest/) specification. ## Getting started @@ -27,6 +26,8 @@ Please refer to the [documentation][link-docs]. In particular: - [Design doc][link-design-doc]. - [Example notebooks][link-notebooks]. +Another useful resource to get started is the source code of the [`spatialdata-io`](https://github.com/scverse/spatialdata-io) package, which shows example of how to read data from common technologies. + ## Installation Check out the docs for more complete [installation instructions](https://spatialdata.scverse.org/en/latest/installation.html). To get started with the "batteries included" installation, you can install via pip: @@ -35,9 +36,11 @@ Check out the docs for more complete [installation instructions](https://spatial pip install "spatialdata[extra]" ``` +Note: if you are using a Mac with an M1/M2 chip, please follow the installation instructions. + ## Contact -For questions and help requests, you can reach out in the [scverse discourse][scverse-discourse]. +- To get involved in the discussion, or if you need help to get started, you are welcome to join our [`scverse` Zulip chat](https://imagesc.zulipchat.com/#narrow/stream/329057-scverse/topic/segmentation) and our [scverse discourse forum](https://discourse.scverse.org/). If you found a bug, please use the [issue tracker][issue-tracker]. ## Citation diff --git a/docs/index.md b/docs/index.md index f97708b8..0b84221d 100644 --- a/docs/index.md +++ b/docs/index.md @@ -8,9 +8,9 @@ SpatialData is a data framework that comprises a FAIR storage format and a collection of python libraries for performant access, alignment, and processing of uni- and multi-modal spatial omics datasets. This page provides documentation on how to install, use, and extend the core `spatialdata` library. See the links below to learn more about other packages in the SpatialData ecosystem. -- [spatialdata-io][]: load data from common spatial omics technologies into `spatialdata`. -- [spatialdata-plot][]: Static plotting library for `spatialdata`. -- [napari-spatialdata][]: napari plugin for interactive exploration and annotation of `spatialdata`. +- `spatialdata-io`: load data from common spatial omics technologies into `spatialdata` ([repository][spatialdata-io-repo], [documentation][spatialdata-io-docs]). +- `spatialdata-plot`: Static plotting library for `spatialdata` ([repository][spatialdata-plot-repo], [documentation][spatialdata-io-docs]). +- `napari-spatialdata-repo`: napari plugin for interactive exploration and annotation of `spatialdata` ([repository][napari-spatialdata-repo], [documentation][napari-spatialdata-docs]). Please see our preprint {cite}`Marconato2023.05.05.539647` for citation and to learn more. @@ -74,6 +74,10 @@ references.md -[napari-spatialdata]: https://github.com/scverse/napari-spatialdata -[spatialdata-io]: https://github.com/scverse/spatialdata-io -[spatialdata-plot]: https://github.com/scverse/spatialdata-plot +[napari-spatialdata-repo]: https://github.com/scverse/napari-spatialdata +[spatialdata-io-repo]: https://github.com/scverse/spatialdata-io +[spatialdata-plot-repo]: https://github.com/scverse/spatialdata-plot +[napari-spatialdata-docs]: https://spatialdata.scverse.org/projects/napari/en/latest/notebooks/spatialdata.html +[spatialdata-io-docs]: https://spatialdata.scverse.org/projects/io/en/latest/ +[spatialdata-plot-docs]: https://spatialdata.scverse.org/projects/plot/en/latest/index.html + diff --git a/docs/installation.md b/docs/installation.md index d80c4927..9d6ec71a 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -26,11 +26,30 @@ pip install "spatialdata[extra]" ## Additional dependencies -To use the dataloader in `spatialdata`, torch needs to be installed. This can be done with: +To use the `PyTorch` dataloader in `spatialdata`, `torch` needs to be installed. This can be done with: ```bash pip install "spatialdata[torch]" ``` +## Installation on a M1/M2 (Apple Silicon) Mac +The framework supports the Apple Silicon architecture, but `napari-spatialdata` cannot be installed with `pip`, because `PyQt5` leads to an installation error. + +Thus `pip install "spatialdata[extra]"` will not work (as it installs `napari-spatialdata`). + +The solution is to pre-install `napari` via `conda` (which will install `PyQt5` correctly), and then install `napari-spatialdata` without the option `[extra]`. + +This is what is done in the following commands, which perform a correct installation on a M1/M2 Mac. + +```bash +mamba create -n my_env python==3.10 -y +conda activate my_env + +mamba install -c conda-forge napari -y +pip install spatialdata-io +pip install spatialdata-plot +pip install napari-spatialdata +pip install spatialdata +``` ## Development version @@ -46,9 +65,18 @@ Alternative you can clone the repository and do an editable install with: pip install -e . ``` -This is the reccommended way to install the package in case in which you want to contribute to the code. To update the package you can use `git pull`. +This is the reccommended way to install the package in case in which you want to contribute to the code. In this case, to subsequently update the package you can use `git pull`. + +### A note on editable install +If you perform an editable install of `spatialdata` and then install `spatialdata-plot`, `spatialdata-io` or `napari-spatialdata`, they may automatically override the installation of `spatialdata` with the version from PyPI. + +To check if this happened you can run + +``` +python -c "import spatialdata; print(spatialdata.__path__)" +``` -Important: if you perform an editable install of `spatialdata` and then install `spatialdata-plot`, `spatialdata-io` or `napari-spatialdata`, they may automatically override the installation of `spatialdata` with the version from PyPI. To check if this happened you can run `python -c "import spatialdata; print(spatialdata.__path__)"`: if you get a path that contains `site-packages`, then your editable installation has been overridden and you need to reinstall the package by rerunning `pip install -e .` in the cloned `spatialdata` repo. +if you get a path that contains `site-packages`, then your editable installation has been overridden and you need to reinstall the package by rerunning `pip install -e .` in the cloned `spatialdata` repo. From 76226476cb7320a91d36613cc221595088264786 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Thu, 13 Jul 2023 15:44:38 +0000 Subject: [PATCH 2/4] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- README.md | 2 +- docs/index.md | 7 +++---- docs/installation.md | 9 ++++++--- 3 files changed, 10 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 15b2d49b..de33449d 100644 --- a/README.md +++ b/README.md @@ -41,7 +41,7 @@ Note: if you are using a Mac with an M1/M2 chip, please follow the installation ## Contact - To get involved in the discussion, or if you need help to get started, you are welcome to join our [`scverse` Zulip chat](https://imagesc.zulipchat.com/#narrow/stream/329057-scverse/topic/segmentation) and our [scverse discourse forum](https://discourse.scverse.org/). -If you found a bug, please use the [issue tracker][issue-tracker]. + If you found a bug, please use the [issue tracker][issue-tracker]. ## Citation diff --git a/docs/index.md b/docs/index.md index 0b84221d..507a530b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -77,7 +77,6 @@ references.md [napari-spatialdata-repo]: https://github.com/scverse/napari-spatialdata [spatialdata-io-repo]: https://github.com/scverse/spatialdata-io [spatialdata-plot-repo]: https://github.com/scverse/spatialdata-plot -[napari-spatialdata-docs]: https://spatialdata.scverse.org/projects/napari/en/latest/notebooks/spatialdata.html -[spatialdata-io-docs]: https://spatialdata.scverse.org/projects/io/en/latest/ -[spatialdata-plot-docs]: https://spatialdata.scverse.org/projects/plot/en/latest/index.html - +[napari-spatialdata-docs]: https://spatialdata.scverse.org/projects/napari/en/latest/notebooks/spatialdata.html +[spatialdata-io-docs]: https://spatialdata.scverse.org/projects/io/en/latest/ +[spatialdata-plot-docs]: https://spatialdata.scverse.org/projects/plot/en/latest/index.html diff --git a/docs/installation.md b/docs/installation.md index 9d6ec71a..343ffaf1 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -31,7 +31,9 @@ To use the `PyTorch` dataloader in `spatialdata`, `torch` needs to be installed. ```bash pip install "spatialdata[torch]" ``` + ## Installation on a M1/M2 (Apple Silicon) Mac + The framework supports the Apple Silicon architecture, but `napari-spatialdata` cannot be installed with `pip`, because `PyQt5` leads to an installation error. Thus `pip install "spatialdata[extra]"` will not work (as it installs `napari-spatialdata`). @@ -42,7 +44,7 @@ This is what is done in the following commands, which perform a correct installa ```bash mamba create -n my_env python==3.10 -y -conda activate my_env +conda activate my_env mamba install -c conda-forge napari -y pip install spatialdata-io @@ -68,9 +70,10 @@ pip install -e . This is the reccommended way to install the package in case in which you want to contribute to the code. In this case, to subsequently update the package you can use `git pull`. ### A note on editable install -If you perform an editable install of `spatialdata` and then install `spatialdata-plot`, `spatialdata-io` or `napari-spatialdata`, they may automatically override the installation of `spatialdata` with the version from PyPI. -To check if this happened you can run +If you perform an editable install of `spatialdata` and then install `spatialdata-plot`, `spatialdata-io` or `napari-spatialdata`, they may automatically override the installation of `spatialdata` with the version from PyPI. + +To check if this happened you can run ``` python -c "import spatialdata; print(spatialdata.__path__)" From 00d77b1217e463b260c915fb8ef9673161d6e3df Mon Sep 17 00:00:00 2001 From: LucaMarconato <2664412+LucaMarconato@users.noreply.github.com> Date: Thu, 13 Jul 2023 18:01:35 +0200 Subject: [PATCH 3/4] oneliner for pip install in the docs --- docs/installation.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/docs/installation.md b/docs/installation.md index 343ffaf1..e5728aae 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -47,10 +47,7 @@ mamba create -n my_env python==3.10 -y conda activate my_env mamba install -c conda-forge napari -y -pip install spatialdata-io -pip install spatialdata-plot -pip install napari-spatialdata -pip install spatialdata +pip install spatialdata spatialdata-io spatialdata-plot napari-spatialdata ``` ## Development version From d42756286b67dc4c24e0363a4c61189e4074fa1d Mon Sep 17 00:00:00 2001 From: LucaMarconato <2664412+LucaMarconato@users.noreply.github.com> Date: Mon, 25 Sep 2023 09:18:50 +0200 Subject: [PATCH 4/4] mention forks in install instructions --- docs/installation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/installation.md b/docs/installation.md index e5728aae..480a7362 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -58,7 +58,7 @@ To install `spatialdata` from GitHub, run: pip install git+https://github.com/scverse/spatialdata ``` -Alternative you can clone the repository and do an editable install with: +Alternative you can clone the repository (or a fork of it if you are contributing) and do an editable install with: ```bash pip install -e .