Merge pull request #79 from scverse/improve/docs

Improved documentation

Author: LucaMarconato

notebooks/examples/aggregation.ipynb

@@ -72,7 +72,7 @@
      "name": "stderr",
      "output_type": "stream",
      "text": [
-      "/Users/macbook/miniconda3/envs/ome/lib/python3.10/site-packages/anndata/_core/anndata.py:183: ImplicitModificationWarning: Transforming to str index.\n",
+      "/mnt/miniconda3/envs/ome/lib/python3.10/site-packages/anndata/_core/aligned_df.py:67: ImplicitModificationWarning: Transforming to str index.\n",
       "  warnings.warn(\"Transforming to str index.\", ImplicitModificationWarning)\n"
      ]
     },
@@ -88,19 +88,14 @@
        "├── Shapes\n",
        "│     ├── 'cell_boundaries': GeoDataFrame shape: (167780, 1) (2D shapes)\n",
        "│     ├── 'cell_circles': GeoDataFrame shape: (167780, 2) (2D shapes)\n",
-       "│     ├── 'nucleus_boundaries': GeoDataFrame shape: (167780, 1) (2D shapes)\n",
-       "│     └── 'xenium_landmarks': GeoDataFrame shape: (3, 2) (2D shapes)\n",
-       "└── Table\n",
-       "      └── AnnData object with n_obs × n_vars = 167780 × 313\n",
-       "    obs: 'cell_id', 'transcript_counts', 'control_probe_counts', 'control_codeword_counts', 'total_counts', 'cell_area', 'nucleus_area', 'region'\n",
-       "    var: 'gene_ids', 'feature_types', 'genome'\n",
-       "    uns: 'spatialdata_attrs'\n",
-       "    obsm: 'spatial': AnnData (167780, 313)\n",
+       "│     └── 'nucleus_boundaries': GeoDataFrame shape: (167780, 1) (2D shapes)\n",
+       "└── Tables\n",
+       "      └── 'table': AnnData (167780, 313)\n",
        "with coordinate systems:\n",
        "▸ 'aligned', with elements:\n",
        "        morphology_mip (Images)\n",
        "▸ 'global', with elements:\n",
-       "        morphology_focus (Images), morphology_mip (Images), transcripts (Points), cell_boundaries (Shapes), cell_circles (Shapes), nucleus_boundaries (Shapes), xenium_landmarks (Shapes)"
+       "        morphology_focus (Images), morphology_mip (Images), transcripts (Points), cell_boundaries (Shapes), cell_circles (Shapes), nucleus_boundaries (Shapes)"
       ]
      },
      "execution_count": 2,
@@ -133,27 +128,19 @@
        "│     ├── 'CytAssist_FFPE_Human_Breast_Cancer_full_image': MultiscaleSpatialImage[cyx] (3, 21571, 19505), (3, 10785, 9752), (3, 5392, 4876), (3, 2696, 2438), (3, 1348, 1219)\n",
        "│     ├── 'CytAssist_FFPE_Human_Breast_Cancer_hires_image': SpatialImage[cyx] (3, 2000, 1809)\n",
        "│     └── 'CytAssist_FFPE_Human_Breast_Cancer_lowres_image': SpatialImage[cyx] (3, 600, 543)\n",
-       "├── Points\n",
-       "│     ├── 'Points': DataFrame with shape: (3, 2) (2D points)\n",
-       "│     └── 'Points_1': DataFrame with shape: (1, 2) (2D points)\n",
        "├── Shapes\n",
-       "│     ├── 'CytAssist_FFPE_Human_Breast_Cancer': GeoDataFrame shape: (4992, 2) (2D shapes)\n",
-       "│     └── 'visium_landmarks': GeoDataFrame shape: (3, 2) (2D shapes)\n",
-       "└── Table\n",
-       "      └── AnnData object with n_obs × n_vars = 4992 × 18085\n",
-       "    obs: 'in_tissue', 'array_row', 'array_col', 'spot_id', 'region', 'dataset', 'clone'\n",
-       "    var: 'gene_ids', 'feature_types', 'genome'\n",
-       "    uns: 'spatial', 'spatialdata_attrs'\n",
-       "    obsm: 'spatial': AnnData (4992, 18085)\n",
+       "│     └── 'CytAssist_FFPE_Human_Breast_Cancer': GeoDataFrame shape: (4992, 2) (2D shapes)\n",
+       "└── Tables\n",
+       "      └── 'table': AnnData (4992, 18085)\n",
        "with coordinate systems:\n",
        "▸ 'aligned', with elements:\n",
-       "        CytAssist_FFPE_Human_Breast_Cancer_full_image (Images), Points (Points), Points_1 (Points), CytAssist_FFPE_Human_Breast_Cancer (Shapes), visium_landmarks (Shapes)\n",
+       "        CytAssist_FFPE_Human_Breast_Cancer_full_image (Images), CytAssist_FFPE_Human_Breast_Cancer (Shapes)\n",
        "▸ 'downscaled_hires', with elements:\n",
        "        CytAssist_FFPE_Human_Breast_Cancer_hires_image (Images), CytAssist_FFPE_Human_Breast_Cancer (Shapes)\n",
        "▸ 'downscaled_lowres', with elements:\n",
        "        CytAssist_FFPE_Human_Breast_Cancer_lowres_image (Images), CytAssist_FFPE_Human_Breast_Cancer (Shapes)\n",
        "▸ 'global', with elements:\n",
-       "        CytAssist_FFPE_Human_Breast_Cancer_full_image (Images), CytAssist_FFPE_Human_Breast_Cancer (Shapes), visium_landmarks (Shapes)"
+       "        CytAssist_FFPE_Human_Breast_Cancer_full_image (Images), CytAssist_FFPE_Human_Breast_Cancer (Shapes)"
       ]
      },
      "execution_count": 3,
@@ -184,7 +171,10 @@
      "end_time": "2023-04-10T18:59:26.909684Z",
      "start_time": "2023-04-10T18:59:25.642148Z"
     },
-    "collapsed": false
+    "collapsed": false,
+    "jupyter": {
+     "outputs_hidden": false
+    }
    },
    "source": [
     "Interactive([visium_sdata, xenium_sdata], points=False, shapes=False)"
@@ -335,6 +325,9 @@
    "id": "e71718a2",
    "metadata": {
     "collapsed": false,
+    "jupyter": {
+     "outputs_hidden": false
+    },
     "tags": []
    },
    "outputs": [
@@ -498,25 +491,44 @@
    "id": "be9277db",
    "metadata": {},
    "source": [
-    "### Saving the alignment back to Zarr\n"
+    "### Saving the landmarks and the alignment back to Zarr\n"
    ]
   },
   {
    "cell_type": "markdown",
    "id": "2e98374c-85cd-45ad-ac62-b2bc075c9631",
    "metadata": {},
    "source": [
-    "We will now save the transformations to disk. Notice that this is a lightweight operation because we are just mofiying the objects metadata, not transforming the actual data. This is useful when dealing with large images and when one may need to reiterate multiple steps of landmark-based alignment in order to improve the spatial agreement of the alignment."
+    "We will now save the landmark points and the transformations of the other elements to disk. \n",
+    "\n",
+    "Notice that these are both lightweight operations because the two sets of landmark points are small, and when saving the transformation of the other elements we are modifying the objects metadata, not transforming the actual data. This is useful when dealing with large images and when one may need to reiterate multiple steps of landmark-based alignment in order to improve the spatial agreement of the alignment."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "a30ee131-40a4-44a2-b736-763532cf570e",
+   "metadata": {},
+   "source": [
+    "WARNING: unfortunately the modular saving of transformation and elements have been refactored out of the latest release and is still not finalized. This function will be re-enabled with high priority, please see the issue tracker here: https://github.com/scverse/spatialdata/issues/496."
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 8,
+   "execution_count": 10,
    "id": "474410bd-2d02-45c1-b073-eba1152ab615",
    "metadata": {
     "tags": []
    },
-   "outputs": [],
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "\u001b[34mINFO    \u001b[0m Not saving the transformation to element shapes/visium_landmarks as it is not found in Zarr storage       \n",
+      "\u001b[34mINFO    \u001b[0m Not saving the transformation to element shapes/xenium_landmarks as it is not found in Zarr storage       \n"
+     ]
+    }
+   ],
    "source": [
     "from spatialdata import save_transformations\n",
     "\n",
@@ -541,7 +553,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.12"
+   "version": "3.10.13"
   },
   "vscode": {
    "interpreter": {