From a9e56048e982b4e24a22a1312443747b954dc769 Mon Sep 17 00:00:00 2001 From: Bishoy Wadie Date: Wed, 19 Mar 2025 10:42:53 +0100 Subject: [PATCH 1/2] Add User Guide --- docs/index.md | 7 ++ docs/user_guide.md | 228 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 235 insertions(+) create mode 100755 docs/user_guide.md diff --git a/docs/index.md b/docs/index.md index c92f7448d..0de4f62f9 100644 --- a/docs/index.md +++ b/docs/index.md @@ -40,6 +40,12 @@ If you like scverse® and want to support our mission, please consider making a Learn how to install ``spatialdata``. +.. card:: User Guide + :link: user_guide + :link-type: doc + + Navigate your way through ``spatialdata`` tutorials. + .. card:: Tutorials :link: tutorials/notebooks/notebooks :link-type: doc @@ -77,6 +83,7 @@ If you like scverse® and want to support our mission, please consider making a :maxdepth: 1 installation.md +user_guide.md api.md tutorials/notebooks/notebooks.md tutorials/notebooks/datasets/README.md diff --git a/docs/user_guide.md b/docs/user_guide.md new file mode 100755 index 000000000..8272aa65e --- /dev/null +++ b/docs/user_guide.md @@ -0,0 +1,228 @@ +# SpatialData User Guide +Lotte Pollaris, Bishoy Wadie, Friedrich Preusser +## Introduction +The SpatialData user guide gives an overview of the SpatialData data framework and its documentation. Based on questions you might have, this guide points you to the correct tutorials. + +If you want to read more about the framework, please have a look at our publication: [Marconato et al.](https://www.nature.com/articles/s41592-024-02212-x) + + +
+

How can I install SpatialData?

 + +``` +pip install spatialdata +``` +This command installs barebone SpatialData. +For a more detailed description on the installation process including all bells and whistles, see [here](https://spatialdata.scverse.org/en/stable/installation.html). + +
+ +
+

I have a SpatialData object—how do I open it and see what's inside?

 + +``` +sdata = sd.read_zarr(“your-dataset.zarr") +``` + + +Please see [this section](https://spatialdata.scverse.org/en/stable/tutorials/notebooks/notebooks/examples/models1.html#reading-spatialdata-zarr-data) that gives more context about how to read in a new zarr file. For a more detailed tutorial that also explains how to explore the different element types within the SpatialData object, see [here](https://spatialdata.scverse.org/en/stable/tutorials/notebooks/notebooks/examples/intro.html). + + +
+ + +
+

How do I create a SpatialData object? +

 + + +
+

If you have an existing Squidpy object.

 + +Please have a look at [this tutorial](https://github.com/scverse/spatialdata-notebooks/blob/main/notebooks%2Fexamples%2Fsdata_from_scratch.ipynb). + +
+ +
+

If you want to start from raw files

 + +If you don’t have a SpatialData object or corresponding zarr file, you will have to create a SpatialData object to make use of the SpatialData framework. +You can create a SpatialData object directly from your raw files (e.g. CSVs, cell-gene matrix/cell-proteins matrix, images etc.) by using the [spatialdata-io](https://github.com/scverse/spatialdata-io) library that has reader functions for most spatial omics techniques. See [here](https://spatialdata.scverse.org/projects/io/en/latest/) for a list of currently supported technologies. + +For example, if you have data coming from a MERSCOPE®, just use: + +``` +sdata = spatialdata_io.merscope( + 'merscope_ex/' # path to the folder with MERSCOPE files + ) +``` + +Please also see [this section](https://spatialdata.scverse.org/en/stable/tutorials/notebooks/notebooks/examples/models1.html#reader-functions-from-spatialdata-io) for a more technical tutorial with more details on how to create a SpatialData object from raw data using io-readers. + +If there is no reader implemented for your data type, please refer to [this section](https://spatialdata.scverse.org/en/stable/tutorials/notebooks/notebooks/examples/models1.html#construct-a-spatialdata-object-from-scratch) to learn about building SpatialData objects from scratch. + +
+ +
+

If you want to play around with existing data.

 + +Please see [here](https://spatialdata.scverse.org/en/stable/tutorials/notebooks/datasets/README.html) for a repository of demo datasets (already available as .zarr) generated with different spatial omics technologies. + +
+
+ + +
+

How can I use SpatialData to analyze my data?

 + +SpatialData is **not** intended to analyze data itself, but to provide data infrastucture to efficiently manipulate spatial omics data. If you want to learn more about analyzing spatial omics data, please browse [these other tutorials](https://spatialdata.scverse.org/en/stable/tutorials/notebooks/notebooks.html#external-tutorials) for a demo of how various analysis packages work with SpatialData. + +If you want to see how SpatialData and Squidpy can interact, please have a look [here](https://spatialdata.scverse.org/en/latest/tutorials/notebooks/notebooks/examples/squidpy_integration.html). + + +
+ + +
+

How do I align my images?

 +Sometimes, you have multiple images containing information, but they have different pixels size/are rotated/are moved. For instance, you may have a multi-omics dataset with two images, each representing a different modality, but you need to align them within a single object while preserving their respective molecular signals. Here, we explain how you can spatially align(=register) these images. NOTE: SpatialData only allows for affine(=linear) transformations to map images onto each other. + + +Do you know how to align your images (i.e. Do you have a transformation matrix)? + +No → Check out our [Landmark annotation tutorial](https://spatialdata.scverse.org/en/stable/tutorials/notebooks/notebooks/examples/alignment_using_landmarks.html) + +Yes → Check out our [Transformation/coordinate system tutorial](https://spatialdata.scverse.org/en/stable/tutorials/notebooks/notebooks/examples/transformations.html) + +
+ +
+

How do I annotate my data?

 + + Annotation can have a lot of meanings. You might want to annotate specific regions in your tissue as tumor, add more details about your cell shapes, group together specific transcripts, include celltype annotations or cell sizes for your cells etc. +
+

How can I spatially annotate regions in my data?

+ +This is possible within the SpatialData framework, making use of napari, like explained [in this tutorial](https://spatialdata.scverse.org/en/stable/tutorials/notebooks/notebooks/examples/napari_rois.html). + + + +
+
+

I have annotated regions in an external tool, how do I add them to SpatialData?

 + +If the annotated regions are saved in a geojson, you can add them as follows: +``` +from spatialdata.models import ShapesModel +sdata['very_interesting_regions']=ShapesModel.parse('path_to_geojson') +``` +For more details, including information on how to add annotations for these regions, please have a look at [this tutorial](https://spatialdata.scverse.org/en/stable/tutorials/notebooks/notebooks/examples/tables.html). + + +
+ +
+ + +

I have cells in my dataset, how do I annotate them? (usage of AnnData)

 + +One of the most obvious things to do for spatial omics data is to annotate cells using the [AnnData](https://anndata.readthedocs.io/en/stable/) format (called tables in SpatialData). These tables can contain count/intensity data, all types of annotations, and make it possible to make use of [scanpy](https://scanpy.readthedocs.io/en/stable/) functionality (normalization/clustering/DE calculation). +If you want more technical details on how to create a table from scratch to annotate your shapes/labels/points, you can have a look [here](https://spatialdata.scverse.org/en/stable/tutorials/notebooks/notebooks/examples/models2.html#tables). A less technical tutorial is coming soon! + + + + +
+ + + +
+ +
+

How do I analyze a spatial subset of my data? +

+ +Eventually, you might want to know which cells are present in which region (e.g. 'Are immune cells infiltrating the tumor core?'). +Therefore, subsampling your data based on spatial coordinates can be helpful. Other examples would be for instance if you want to target your analysis to a specific subregion of the tissue (e.g. tumor core), if you have multiple tissues on one slide, if you want to start small, or if you want to only focus on regions with good tissue quality. + +
+

I want to annotate a specific region myself.

 + +Please see the previous section ('How do I annotate my data?') and then specifically the section about spatially annotating regions. This will guide you through the process of extracting coordinates, which will be used for spatially subsetting the data. Next, see below. +
+ +
+

I know the coordinates of the region I want to subsample.

 + +You will need to perform a spatial query, which filters the data based on spatial coordinates. Please see [this tutorial](https://spatialdata.scverse.org/en/stable/tutorials/notebooks/notebooks/examples/spatial_query.html). + +
+ + +
+ + +
+

How do I visualize my data?

 + +To make data visualization easier for each layer in your SpatialData object, we offer [spatialdata-plot](https://github.com/scverse/spatialdata-plot), a package that enhances SpatialData’s functionality for intuitive and detailed plotting. + +The standard format for plotting a specific layer follows this syntax: +``` +sdata.pl.render_("").pl.show() +``` + +You can also chain different plots. For example, if you want to plot regions of interest (ROIs) and/or cell outlines (i.e. shapes) on top of your image: + +``` +( + sdata + .pl.render_image( + "image_layer_name" + ) + .pl.render_shapes( + "shape_layer_name" + ) + .pl.show() +) +``` +For more details and examples on visualizing technology-specific datasets, explore our [technology-specific tutorials](https://spatialdata.scverse.org/en/stable/tutorials/notebooks/notebooks.html#technology-specific), which includes examples for various technologies (e.g., Visium-HD, Xenium, etc.). Keep in mind that the visualization methods demonstrated in these tutorials are broadly applicable and not limited to a specific technology. + +If you run into scalability issues with your plotting, or everything feels very slow, [this tutorial](https://spatialdata.scverse.org/en/latest/tutorials/notebooks/notebooks/examples/speed_up_illustration.html) might help you out! + +
+ +
+

How do I summarize/aggregate my data?

 + +You have annotated your object with regions or labels and want to determine which cells or transcripts are present in each area. For example, you may be interested in analyzing the composition of cell types within each region or generating a pseudobulk profile per region or label. Or maybe you just want to know your gene counts per cell. In SpatialData terminology, this corresponds to the **aggregate** function. + +The method of aggregation depends on the type of elements in your SpatialData object. Learn how to do it in our [Integrate/aggregate signals across spatial layers tutorial](https://spatialdata.scverse.org/en/stable/tutorials/notebooks/notebooks/examples/aggregation.html). + +
+
+ +

SpatialData looks amazing, I want to learn more. Give me all the technical details!

 + +Sure, no problem! There is much more to learn about SpatialData. + +You want to learn how to combine SpatialData and deep learning? We got you covered [here](https://spatialdata.scverse.org/en/stable/tutorials/notebooks/notebooks/examples/densenet.html). + +If you want to create a labels layer from your shapes (rasterize), a shapes layer from you labels (vectorize, or convert your spot-based data to a labels layer [this tutorial](https://spatialdata.scverse.org/en/stable/tutorials/notebooks/notebooks/examples/labels_shapes_interchangeability.html) might help you out). This is mainly useful to unlock specific functionalities, or speed up calculations. + +Deep diving into these tutorials is at your own risk: [Some technical notes](https://spatialdata.scverse.org/en/latest/tutorials/notebooks/notebooks/examples/transformations_advanced.html#other-technical-topics) and [on translations](https://spatialdata.scverse.org/en/latest/tutorials/notebooks/notebooks/examples/transformations_advanced.html#other-technical-topics). + + +
+ +
+ +

I am sold, how can I contribute to SpatialData? + +

 + + +[Here](https://spatialdata.scverse.org/en/stable/contributing.html) is a guide that explains how to contribute to SpatialData as a developer. + +
+ \ No newline at end of file From 5b7cc14c7e68e92d44b604086ed393cf6b55d40b Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Wed, 19 Mar 2025 09:51:24 +0000 Subject: [PATCH 2/2] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/user_guide.md | 83 +++++++++++++++++++++------------------------- 1 file changed, 37 insertions(+), 46 deletions(-) diff --git a/docs/user_guide.md b/docs/user_guide.md index 8272aa65e..22d140e04 100755 --- a/docs/user_guide.md +++ b/docs/user_guide.md @@ -1,10 +1,12 @@ # SpatialData User Guide + Lotte Pollaris, Bishoy Wadie, Friedrich Preusser + ## Introduction -The SpatialData user guide gives an overview of the SpatialData data framework and its documentation. Based on questions you might have, this guide points you to the correct tutorials. -If you want to read more about the framework, please have a look at our publication: [Marconato et al.](https://www.nature.com/articles/s41592-024-02212-x) +The SpatialData user guide gives an overview of the SpatialData data framework and its documentation. Based on questions you might have, this guide points you to the correct tutorials. +If you want to read more about the framework, please have a look at our publication: [Marconato et al.](https://www.nature.com/articles/s41592-024-02212-x)

How can I install SpatialData?

 @@ -12,8 +14,9 @@ If you want to read more about the framework, please have a look at our publicat ``` pip install spatialdata ``` -This command installs barebone SpatialData. -For a more detailed description on the installation process including all bells and whistles, see [here](https://spatialdata.scverse.org/en/stable/installation.html). + +This command installs barebone SpatialData. +For a more detailed description on the installation process including all bells and whistles, see [here](https://spatialdata.scverse.org/en/stable/installation.html).
@@ -24,18 +27,14 @@ For a more detailed description on the installation process including all bells sdata = sd.read_zarr(“your-dataset.zarr") ``` - Please see [this section](https://spatialdata.scverse.org/en/stable/tutorials/notebooks/notebooks/examples/models1.html#reading-spatialdata-zarr-data) that gives more context about how to read in a new zarr file. For a more detailed tutorial that also explains how to explore the different element types within the SpatialData object, see [here](https://spatialdata.scverse.org/en/stable/tutorials/notebooks/notebooks/examples/intro.html). - -

How do I create a SpatialData object?

-

If you have an existing Squidpy object.

 @@ -53,14 +52,14 @@ For example, if you have data coming from a MERSCOPE®, just use: ``` sdata = spatialdata_io.merscope( - 'merscope_ex/' # path to the folder with MERSCOPE files + 'merscope_ex/' # path to the folder with MERSCOPE files ) ``` Please also see [this section](https://spatialdata.scverse.org/en/stable/tutorials/notebooks/notebooks/examples/models1.html#reader-functions-from-spatialdata-io) for a more technical tutorial with more details on how to create a SpatialData object from raw data using io-readers. If there is no reader implemented for your data type, please refer to [this section](https://spatialdata.scverse.org/en/stable/tutorials/notebooks/notebooks/examples/models1.html#construct-a-spatialdata-object-from-scratch) to learn about building SpatialData objects from scratch. - +
@@ -70,28 +69,26 @@ Please see [here](https://spatialdata.scverse.org/en/stable/tutorials/notebooks/
- +

How can I use SpatialData to analyze my data?

 SpatialData is **not** intended to analyze data itself, but to provide data infrastucture to efficiently manipulate spatial omics data. If you want to learn more about analyzing spatial omics data, please browse [these other tutorials](https://spatialdata.scverse.org/en/stable/tutorials/notebooks/notebooks.html#external-tutorials) for a demo of how various analysis packages work with SpatialData. - -If you want to see how SpatialData and Squidpy can interact, please have a look [here](https://spatialdata.scverse.org/en/latest/tutorials/notebooks/notebooks/examples/squidpy_integration.html). +If you want to see how SpatialData and Squidpy can interact, please have a look [here](https://spatialdata.scverse.org/en/latest/tutorials/notebooks/notebooks/examples/squidpy_integration.html).
-

How do I align my images?

 Sometimes, you have multiple images containing information, but they have different pixels size/are rotated/are moved. For instance, you may have a multi-omics dataset with two images, each representing a different modality, but you need to align them within a single object while preserving their respective molecular signals. Here, we explain how you can spatially align(=register) these images. NOTE: SpatialData only allows for affine(=linear) transformations to map images onto each other. - + Do you know how to align your images (i.e. Do you have a transformation matrix)? - + No → Check out our [Landmark annotation tutorial](https://spatialdata.scverse.org/en/stable/tutorials/notebooks/notebooks/examples/alignment_using_landmarks.html) - + Yes → Check out our [Transformation/coordinate system tutorial](https://spatialdata.scverse.org/en/stable/tutorials/notebooks/notebooks/examples/transformations.html)
@@ -104,9 +101,8 @@ Yes → Check out our [Transformation/coordinate system tutorial](https://spatia

How can I spatially annotate regions in my data?

This is possible within the SpatialData framework, making use of napari, like explained [in this tutorial](https://spatialdata.scverse.org/en/stable/tutorials/notebooks/notebooks/examples/napari_rois.html). - - +

I have annotated regions in an external tool, how do I add them to SpatialData?

 @@ -116,9 +112,8 @@ If the annotated regions are saved in a geojson, you can add them as follows: from spatialdata.models import ShapesModel sdata['very_interesting_regions']=ShapesModel.parse('path_to_geojson') ``` -For more details, including information on how to add annotations for these regions, please have a look at [this tutorial](https://spatialdata.scverse.org/en/stable/tutorials/notebooks/notebooks/examples/tables.html). +For more details, including information on how to add annotations for these regions, please have a look at [this tutorial](https://spatialdata.scverse.org/en/stable/tutorials/notebooks/notebooks/examples/tables.html). -
@@ -127,11 +122,8 @@ For more details, including information on how to add annotations for these regi

I have cells in my dataset, how do I annotate them? (usage of AnnData)

 One of the most obvious things to do for spatial omics data is to annotate cells using the [AnnData](https://anndata.readthedocs.io/en/stable/) format (called tables in SpatialData). These tables can contain count/intensity data, all types of annotations, and make it possible to make use of [scanpy](https://scanpy.readthedocs.io/en/stable/) functionality (normalization/clustering/DE calculation). -If you want more technical details on how to create a table from scratch to annotate your shapes/labels/points, you can have a look [here](https://spatialdata.scverse.org/en/stable/tutorials/notebooks/notebooks/examples/models2.html#tables). A less technical tutorial is coming soon! - - +If you want more technical details on how to create a table from scratch to annotate your shapes/labels/points, you can have a look [here](https://spatialdata.scverse.org/en/stable/tutorials/notebooks/notebooks/examples/models2.html#tables). A less technical tutorial is coming soon! -
@@ -143,8 +135,8 @@ If you want more technical details on how to create a table from scratch to anno Eventually, you might want to know which cells are present in which region (e.g. 'Are immune cells infiltrating the tumor core?'). -Therefore, subsampling your data based on spatial coordinates can be helpful. Other examples would be for instance if you want to target your analysis to a specific subregion of the tissue (e.g. tumor core), if you have multiple tissues on one slide, if you want to start small, or if you want to only focus on regions with good tissue quality. - +Therefore, subsampling your data based on spatial coordinates can be helpful. Other examples would be for instance if you want to target your analysis to a specific subregion of the tissue (e.g. tumor core), if you have multiple tissues on one slide, if you want to start small, or if you want to only focus on regions with good tissue quality. +

I want to annotate a specific region myself.

 @@ -157,7 +149,7 @@ Please see the previous section ('How do I annotate my data?') and then specific You will need to perform a spatial query, which filters the data based on spatial coordinates. Please see [this tutorial](https://spatialdata.scverse.org/en/stable/tutorials/notebooks/notebooks/examples/spatial_query.html).
- + @@ -167,11 +159,12 @@ You will need to perform a spatial query, which filters the data based on spatia To make data visualization easier for each layer in your SpatialData object, we offer [spatialdata-plot](https://github.com/scverse/spatialdata-plot), a package that enhances SpatialData’s functionality for intuitive and detailed plotting. -The standard format for plotting a specific layer follows this syntax: +The standard format for plotting a specific layer follows this syntax: + ``` sdata.pl.render_("").pl.show() ``` - + You can also chain different plots. For example, if you want to plot regions of interest (ROIs) and/or cell outlines (i.e. shapes) on top of your image: ``` @@ -186,43 +179,41 @@ You can also chain different plots. For example, if you want to plot regions of .pl.show() ) ``` + For more details and examples on visualizing technology-specific datasets, explore our [technology-specific tutorials](https://spatialdata.scverse.org/en/stable/tutorials/notebooks/notebooks.html#technology-specific), which includes examples for various technologies (e.g., Visium-HD, Xenium, etc.). Keep in mind that the visualization methods demonstrated in these tutorials are broadly applicable and not limited to a specific technology. - -If you run into scalability issues with your plotting, or everything feels very slow, [this tutorial](https://spatialdata.scverse.org/en/latest/tutorials/notebooks/notebooks/examples/speed_up_illustration.html) might help you out! - + +If you run into scalability issues with your plotting, or everything feels very slow, [this tutorial](https://spatialdata.scverse.org/en/latest/tutorials/notebooks/notebooks/examples/speed_up_illustration.html) might help you out! +
-

How do I summarize/aggregate my data?

 +

How do I summarize/aggregate my data?

 You have annotated your object with regions or labels and want to determine which cells or transcripts are present in each area. For example, you may be interested in analyzing the composition of cell types within each region or generating a pseudobulk profile per region or label. Or maybe you just want to know your gene counts per cell. In SpatialData terminology, this corresponds to the **aggregate** function. The method of aggregation depends on the type of elements in your SpatialData object. Learn how to do it in our [Integrate/aggregate signals across spatial layers tutorial](https://spatialdata.scverse.org/en/stable/tutorials/notebooks/notebooks/examples/aggregation.html). - +

SpatialData looks amazing, I want to learn more. Give me all the technical details!

 -Sure, no problem! There is much more to learn about SpatialData. +Sure, no problem! There is much more to learn about SpatialData. You want to learn how to combine SpatialData and deep learning? We got you covered [here](https://spatialdata.scverse.org/en/stable/tutorials/notebooks/notebooks/examples/densenet.html). -If you want to create a labels layer from your shapes (rasterize), a shapes layer from you labels (vectorize, or convert your spot-based data to a labels layer [this tutorial](https://spatialdata.scverse.org/en/stable/tutorials/notebooks/notebooks/examples/labels_shapes_interchangeability.html) might help you out). This is mainly useful to unlock specific functionalities, or speed up calculations. +If you want to create a labels layer from your shapes (rasterize), a shapes layer from you labels (vectorize, or convert your spot-based data to a labels layer [this tutorial](https://spatialdata.scverse.org/en/stable/tutorials/notebooks/notebooks/examples/labels_shapes_interchangeability.html) might help you out). This is mainly useful to unlock specific functionalities, or speed up calculations. + +Deep diving into these tutorials is at your own risk: [Some technical notes](https://spatialdata.scverse.org/en/latest/tutorials/notebooks/notebooks/examples/transformations_advanced.html#other-technical-topics) and [on translations](https://spatialdata.scverse.org/en/latest/tutorials/notebooks/notebooks/examples/transformations_advanced.html#other-technical-topics). -Deep diving into these tutorials is at your own risk: [Some technical notes](https://spatialdata.scverse.org/en/latest/tutorials/notebooks/notebooks/examples/transformations_advanced.html#other-technical-topics) and [on translations](https://spatialdata.scverse.org/en/latest/tutorials/notebooks/notebooks/examples/transformations_advanced.html#other-technical-topics). - -
-

I am sold, how can I contribute to SpatialData? +

I am sold, how can I contribute to SpatialData? -

 +

 - -[Here](https://spatialdata.scverse.org/en/stable/contributing.html) is a guide that explains how to contribute to SpatialData as a developer. +[Here](https://spatialdata.scverse.org/en/stable/contributing.html) is a guide that explains how to contribute to SpatialData as a developer. -
- \ No newline at end of file +