Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

fix docs #321

Merged
merged 4 commits into from
Sep 25, 2023
Merged

fix docs #321

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
33006d7
fix docs
LucaMarconato Jul 13, 2023
7622647
[pre-commit.ci] auto fixes from pre-commit.com hooks
pre-commit-ci[bot] Jul 13, 2023
00d77b1
oneliner for pip install in the docs
LucaMarconato Jul 13, 2023
d427562
mention forks in install instructions
LucaMarconato Sep 25, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 7 additions & 4 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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:
Expand All @@ -35,10 +36,12 @@ 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].
If you found a bug, please use the [issue tracker][issue-tracker].
- 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

Expand Down
15 changes: 9 additions & 6 deletions docs/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -74,6 +74,9 @@ references.md

<!-- Links -->

[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
34 changes: 31 additions & 3 deletions docs/installation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,12 +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 spatialdata-io spatialdata-plot napari-spatialdata
```

## Development version

To install `spatialdata` from GitHub, run:
Expand All @@ -46,9 +64,19 @@ 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`.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In that case, wouldn't we prefer people to create a fork first?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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`.
An editable installation is the best option if you want to contribute to the development of spatialdata.
Check out our [contributing guide](https://spatialdata.scverse.org/en/latest/contributing.html).

explaining forking goes beyond the scope of installation instructions.
But we can use the opportunity to funnel people to the development guide.

Copy link
Collaborator

@melonora melonora Sep 22, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes in any case for Numfocus we do require a contributors guide or another option would be to create a complete installation guide, similar to napari. All I am saying is that we do not necessarily want people to contribute by directly installing from main in this repo and then pushing their code. This was just there for the initial developers.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the comments. It's hidden but it's there: https://github.com/scverse/spatialdata/blob/main/docs/contributing.md.

I will modify installation.md to quickly mentione forks.


### 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.

<!-- Links -->

Expand Down