first steps for SpatialData section

jupyter-book/introduction/analysis_tools.ipynb

@@ -3315,6 +3315,67 @@
     "For more details on all available functions of muon, please read the muon API reference at https://muon.readthedocs.io/en/latest/api/index.html and the muon tutorials at https://muon-tutorials.readthedocs.io/en/latest/."
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Advanced: Using SpatialData to store multimodal and spacial data\n",
+    "\n",
+    "In the analogy of the scverse, SpacialData provides the data structure for loading, manipulating and storing spatial omics data. \n",
+    "SpatialData establishes a standardized, extensible multiplatform file format that supports lazy representation of larger-than-memory data, enabling efficient data transformations and alignment to common coordinate systems. This framework facilitates spatial annotations and cross-modal aggregation, making it an invaluable tool for integrative analysis.\n",
+    "The SpatialData framework is built on five core primitive elements—Images, Labels, Points, Shapes, and Tables—which collectively represent raw and derived data from a wide range of spatial omics technologies. These elements are serialized in a Zarr store, compliant with the Open Microscopy Environment–Next-Generation File Format (OME–NGFF), ensuring interoperability and efficient access across both traditional file systems and cloud-based storage.\n",
+    "The accompanying SpatialData Python library provides a unified programmatic interface for accessing, manipulating, and analyzing spatial datasets. It supports lazy loading of data, enabling the handling of datasets that exceed memory capacity, and offers versatile functionalities for defining coordinate transformations, querying datasets, and performing cross-modal aggregations. Additionally, SpatialData integrates seamlessly with the broader Python ecosystem, including tools like Scanpy, Squidpy, and scvi-tools, and supports interactive data exploration and annotation through the napari-spatialdata plugin.\n",
+    "\n",
+    "In the scverse ecosystem, SpatialData serves as the foundational data structure for managing spatial omics data. It introduces a standardized, extensible file format that supports lazy representation of larger-than-memory datasets, enabling efficient transformations and alignment to common coordinate systems. This framework streamlines spatial annotations and cross-modal aggregation, making it essential for integrative analysis.\n",
+    "\n",
+    "SpatialData organizes data into five core elements—Images, Labels, Points, Shapes, and Tables—representing raw and derived data from diverse spatial omics technologies. These elements are serialized in a Zarr store, compliant with the Open Microscopy Environment–Next-Generation File Format (OME–NGFF), ensuring interoperability and efficient access across file systems and cloud storage.\n",
+    "\n",
+    "The accompanying SpatialData Python library provides a unified interface for accessing, manipulating, and analyzing spatial datasets. It supports lazy loading for memory-efficient handling of large datasets and offers tools for coordinate transformations, dataset querying, and cross-modal aggregation. Seamlessly integrated with the Python ecosystem—including tools like Scanpy, Squidpy, and scvi-tools—it also enables interactive exploration and annotation via the napari-spatialdata plugin.\n",
+    "\n",
+    "\n",
+    "\n",
+    "We adapted the following section from \n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Installation\n",
+    "Again, either use PyPI or Conda to install SpacialData.\n",
+    "```bash\n",
+    "pip install spatialdata\n",
+    "conda install -c conda-forge spatialdata\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Key terms and data model\n",
+    "We can think of a `SpatialData` object as a container for various `Elements`. An `Element` is either a `SpatialElement` (`Images`, `Labels`, `Points`, `Shapes`) or a `Table`. Here is a brief description:\n",
+    "- `Images`: H&E, staining images\n",
+    "- `Labels`: pixel-level segmentation\n",
+    "- `Points`: transcripts locations with gene information, landmarks points\n",
+    "- `Shapes`: cell/nucleus boundaries, subcellular structures, anatomical annotations, regions of interest (ROIs)\n",
+    "- `Tables`: sparse/dense matrices annotating the the `SpatialElements` or storing arbitrary (non-spatial) metadata. They do not contain spatial coordinates.\n",
+    "\n",
+    "We can categorize the `SpatialElements` into two broad types:\n",
+    "- `Rasters`: Data made up of pixels: including `Images` and `Labels`\n",
+    "- `Vectors`: Data made up of points and lines. Polygons are also vectors, since they are a simply a list of connected points. `Points` and `Shapes` are elements of this type.\n",
+    "\n",
+    ":::{figure-md} spacialdata-fig\n",
+    "<img src=\"../_static/images/analysis_tools/SpacialData_elements.png\", alt=\"Overview of SpacialData's elements\", max-width = 800px>\n",
+    "\n",
+    "\n",
+    "The elements of a SpacialData object. Obtained from ...\n",
+    "muon overview. Image obtained from {cite}`Bredikhin2022`.\n",
+    ":::\n",
+    "\n",
+    "<img src=\"attachments/elements.png\" alt=\"SpatialData Elements\" style=\"max-width: 800px;\">"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},