update tutorials.

docs/source/Tutorials(Multi-sample)/Batch_QC.ipynb

@@ -27,13 +27,20 @@
    "id": "086b62ac",
    "metadata": {},
    "source": [
+    "This function can be run on GPU, if you want to use GPU, you need to create an environment according to the guide [Clustering_by_GPU](../Tutorials/Clustering_by_GPU.html).\n",
+    "\n",
+    "\n",
     "<div class=\"alert alert-info\">\n",
     "\n",
     "**Note**\n",
     "\n",
-    "**Torch** need to be installed beforehand:\n",
+    "**Torch** is the necessary dependency, we need to install it beforehand:\n",
+    "\n",
+    "        CPU: pip install torch==2.4.1+cpu --extra-index-url https://download.pytorch.org/whl\n",
+    "\n",
+    "        GPU(CUDA11): pip install torch==2.4.1+cu118 --extra-index-url https://download.pytorch.org/whl/\n",
     "\n",
-    "    pip install torch\n",
+    "        GPU(CUDA12): pip install torch==2.4.1+cu124 --extra-index-url https://download.pytorch.org/whl/\n",
     "\n",
     "</div>"
    ]

docs/source/Tutorials(Multi-sample)/MSData_Clustering.ipynb

@@ -330,7 +330,7 @@
     " - `scope` , similar to list, means which samples used for analysis.\n",
     " - `mode`, like a switch, shows that analysis is performed on single sample or multi samples, `integrate` and `isolated`. It is easy to distinguish processing modes.\n",
     "\n",
-    "There are two ways to set `scope` and `mode`, running `ms_data.tl.set_mode_and_scope` to set them globally or pass them as parameters into each analysis function, the latter will overwrite the former on every specific function."
+    "There are two ways to set `scope` and `mode`, running `ms_data.tl.set_scope_and_mode` to set them globally or pass them as parameters into each analysis function, the latter will overwrite the former on every specific function."
    ]
   },
   {

docs/source/Tutorials(Multi-sample)/ST_Gears.ipynb

@@ -15,15 +15,28 @@
     "    \n",
     "2. `stack_slices_pairwise_rigid` rigidly aligns sections using Procrustes Analysis.\n",
     "    \n",
-    "3. `stack_slices_pairwise_elas_field` eliminates distorsions through Gaussian Smoothed Elastic Fields. Validity is proved mathematically.\n",
-    "\n",
+    "3. `stack_slices_pairwise_elas_field` eliminates distorsions through Gaussian Smoothed Elastic Fields. Validity is proved mathematically."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "efe84931",
+   "metadata": {},
+   "source": [
     "This function can be run on GPU, if you want to use GPU, you need to create an environment according to the guide [Clustering_by_GPU](../Tutorials/Clustering_by_GPU.html).\n",
     "\n",
-    "Before anlysing, you also need to install a necessary package: **torch**\n",
     "\n",
-    "        CPU: pip install torch==1.10.0\n",
+    "<div class=\"alert alert-info\">\n",
+    "\n",
+    "**Note**\n",
+    "\n",
+    "**Torch** is the necessary dependency for using GPU, we need to install it beforehand:\n",
+    "\n",
+    "        GPU(CUDA11): pip install torch==2.4.1+cu118 --extra-index-url https://download.pytorch.org/whl/\n",
+    "\n",
+    "        GPU(CUDA12): pip install torch==2.4.1+cu124 --extra-index-url https://download.pytorch.org/whl/\n",
     "\n",
-    "        GPU: pip install torch==1.10.0+cu113 --extra-index-url https://download.pytorch.org/whl/"
+    "</div>"
    ]
   },
   {

docs/source/Tutorials(Multi-sample)/SpaSEG.ipynb

@@ -22,11 +22,13 @@
     "\n",
     "**Note**\n",
     "\n",
-    "Before anlysing, you also need to install a necessary package: **torch**\n",
+    "**Torch** is the necessary dependency, we need to install it beforehand:\n",
     "\n",
-    "        CPU: pip install torch==1.10.0\n",
+    "        CPU: pip install torch==2.4.1+cpu --extra-index-url https://download.pytorch.org/whl\n",
     "\n",
-    "        GPU: pip install torch==1.10.0+cu113 --extra-index-url https://download.pytorch.org/whl/\n",
+    "        GPU(CUDA11): pip install torch==2.4.1+cu118 --extra-index-url https://download.pytorch.org/whl/\n",
+    "\n",
+    "        GPU(CUDA12): pip install torch==2.4.1+cu124 --extra-index-url https://download.pytorch.org/whl/\n",
     "\n",
     "</div>"
    ]

docs/source/Tutorials/CellBin_Clustering.ipynb

@@ -1880,7 +1880,9 @@
    "id": "28c7e577",
    "metadata": {},
    "source": [
-    "We can visulize the detail of cells base on clustering result. If set the parameter `base_image`, it will draw the ssDNA image as background and you can set transparency of foreground by the parameter `fg_alpha`."
+    "We can visulize the detail of cells base on clustering result. If set the parameter `base_image`, it will draw the ssDNA image as background and you can set transparency of foreground by the parameter `fg_alpha`.\n",
+    "\n",
+    "we can also export this plot as SVG or PDF, more detail in [API](../content/stereo.plots.PlotCollection.cells_plotting.rst)."
    ]
   },
   {

docs/source/Tutorials/SpaTrack.rst

@@ -12,7 +12,7 @@ taking into account both profile of gene expression and distance cost of cell tr
 spaTrack has the potential to capture fine local details of trajectory within a single tissue section of spatial transcriptomics (ST) data, 
 as well as reconstruct cell dynamics across multiple tissue sections in a time series. To capture potential dynamic drivers, 
 spaTrack models the fate of a cell as a function of expression profile along the time points driven by transcription factors, 
-which facilitates the identification of key molecular regulators that govern cellular trajectories.
+which facilitates the identification of key molecular regulators that govern cellular trajectories [`Shen <https://www.biorxiv.org/content/10.1101/2023.09.04.556175v2>`_].
 
 Highlighted features
 ---------------------

docs/source/Tutorials/Tissue_Segmentation.ipynb

@@ -40,22 +40,28 @@
     "\n",
     "Install necessary packages by running commands as below:\n",
     "\n",
-    "**For CPU:**\n",
+    "**CPU:**\n",
     "\n",
-    ">    **pip install tensorflow==2.7.0**  \n",
-    ">    **pip install torch==1.10.0**  \n",
-    ">    **pip install torchvision==0.11.1**  \n",
-    ">    **pip install albumentations==0.4.6**  \n",
-    ">    **pip protobuf~=3.20.0**\n",
+    "        pip install tensorflow==2.12.0\n",
+    "        pip install albumentations==1.3.1\n",
+    "        pip install torch==2.4.1+cpu --extra-index-url https://download.pytorch.org/whl\n",
+    "        pip install torchvision==0.19.1+cpu --extra-index-url https://download.pytorch.org/whl\n",
     "\n",
-    "**For GPU:**\n",
+    "**GPU(CUDA11):**\n",
     "\n",
-    ">    **pip install tensorflow==2.7.0**  \n",
-    ">    **pip install torch==1.10.0+cu113 --extra-index-url https://download.pytorch.org/whl/**  \n",
-    ">    **pip install torchvision==0.11.1+cu113 --extra-index-url https://download.pytorch.org/whl/**  \n",
-    ">    **pip install albumentations==0.4.6**  \n",
-    ">    **pip install onnxruntime-gpu**    \n",
-    ">    **pip protobuf~=3.20.0**\n",
+    "        pip install tensorflow==2.12.0\n",
+    "        pip install albumentations==1.3.1\n",
+    "        pip install torch==2.4.1+cu118 --extra-index-url https://download.pytorch.org/whl/\n",
+    "        pip install torchvision==0.19.1+cu118 --extra-index-url https://download.pytorch.org/whl/\n",
+    "        pip install onnxruntime-gpu\n",
+    "\n",
+    "**GPU(CUDA12):**\n",
+    "\n",
+    "        pip install tensorflow==2.12.0\n",
+    "        pip install albumentations==1.3.1\n",
+    "        pip install torch==2.4.1+cu124 --extra-index-url https://download.pytorch.org/whl/\n",
+    "        pip install torchvision==0.19.1+cu124 --extra-index-url https://download.pytorch.org/whl/\n",
+    "        pip install onnxruntime-gpu\n",
     "\n",
     "</div>"
    ]
@@ -68,7 +74,7 @@
    "source": [
     "## Tissue segmentation from .TIFF image\n",
     "\n",
-    "We now support 4 staining types of **.TIFF** image: **ssDNA**, **DAPI**,  **HE** and **mIF** and have two models to process these four types images:\n",
+    "We now support 4 staining types of **.TIFF** image: **ssDNA**, **DAPI**,  **HE** and **mIF**, and have two models to process these four types images:\n",
     "\n",
     "        1. tissueseg_bcdu_H&E_20240201_tf.onnx: be used for staining type HE.\n",
     "\n",

docs/source/content/07_References.rst

@@ -81,3 +81,7 @@ References
 .. [Bai23]
    Yong Bai, Xiangyu Guo, Keyin Liu, Bingjie Zheng, Yingyue Wang, Qiuhong Luo, Jianhua Yin, Liang Wu, Yuxiang Li, Yong Zhang, Ao Chen, Xun Xu, Xin Jin,
    *Efficient reliability analysis of spatially resolved transcriptomics at varying resolutions using SpaSEG*, bioRxiv.
+
+.. [Shen23]
+    Xunan Shen, Ke Huang, Lulu Zuo, Zhongfei Ye, Zeyu Li, Qichao Yu, Xuanxuan Zou, Xiaoyu Wei, Ping Xu, Xin Jin, Xun Xu, Liang Wu, Hongmei Zhu, Pengfei Qin,
+    *Inferring cell trajectories of spatial transcriptomics via optimal transport analysis*, bioRxiv.

stereo/core/st_pipeline.py

@@ -794,6 +794,8 @@ def highly_variable_genes(
         n_bins
             number of bins for binning the mean gene expression. Normalization is done with respect to
             each bin. If just a single gene falls into a bin, the normalized dispersion is artificially set to 1.
+        layer
+            the key of layer to be used instead of the data.exp_matrix.
         res_key
             the key for getting the result from `self.result`.
 
@@ -868,6 +870,7 @@ def pca(self,
         :param hvg_res_key: the key of highly variable genes to get targeted result,`use_highly_genes=True` is a necessary prerequisite.
         :param random_state: change to use different initial states for the optimization, fixed value to fixed result.
         :param dtype: numpy data type string to which to convert the result.
+        :param layer: the key of layer to be used instead of the data.exp_matrix.
         :param res_key: the key for storage of PCA result.
 
         :return: Computation result of principal component analysis is stored in `self.result` where the result key is `'pca'`.
@@ -1253,7 +1256,7 @@ def find_marker_genes(self,
         :param case_groups: case group, default all clusters.
         :param control_groups: control group, default the rest of groups.
         :param corr_method: p-value correction method, only available for `t_test` and `wilcoxon_test`.
-        :param use_raw: whether to use raw express matrix for analysis, default True.
+        :param use_raw: whether to use raw express matrix for analysis, default True, it will be ignored if `layer` is not None.
         :param use_highly_genes: whether to use only the expression of hypervariable genes as input, default True.
         :param hvg_res_key: the key of highly variable genes to get corresponding result.
         :param res_key: the key for storing result of marker genes.
@@ -1263,6 +1266,7 @@ def find_marker_genes(self,
                 larger or equal to 1, less or equal to 50.
         :param ascending: default to False.
         :param n_jobs: the number of parallel jobs to run. default to 4.
+        :param layer: the key of layer to be used instead of the data.exp_matrix, `use_raw` is ignored if it is not None.
         :return: The result of marker genes is stored in `self.result` where the key is `'marker_genes'`.
         """
         from ..tools.find_markers import FindMarker

stereo/io/reader.py

@@ -70,11 +70,13 @@ def read_gem(
         if set it to True, the coordinate of each bin will be the center of the bin,
         otherwise, the coordinate of each bin will be the left-top corner of the bin.
     gene_name_index
-        In a v0.1 gem file, the column geneID is the gene name actually, but in a v0.2,
-        geneID just a ID for genes and there is an additional column called geneName where is the gene name,
-        When the version of gem file is v0.2, set `gene_name_index` to True to set column geneName as index, otherwise,
-        set column geneID, if a v0.1 gem file, `gene_name_index` will be ignored and column geneID is set as index.
-
+        In a **v0.1** gem file, the column **geneID** actually is the **gene name**, but in **v0.2**,
+        **geneID** is just the **ID** for genes and there is an additional column called **geneName** which is the **gene name**,
+        When being **v0.2**, setting `gene_name_index` to True means setting column **geneName** as index,
+        otherwise, setting column **geneID** as index and the column **geneName** is stored in `data.real_gene_names`,
+        if **v0.1**, `gene_name_index` will be ignored and the column **geneID** will be set as index,
+        regardless of **v0.1** or **v0.2**, the column set as index is stored in `data.gene_names`,
+        the index mentioned here is the index of `data.genes`.
     Returns
     -------------
     An object of StereoExpData.
@@ -1181,9 +1183,13 @@ def read_gef(
     region
         restrict data to the region condition, like [minX, maxX, minY, maxY].
     gene_name_index
-        `True` to set gene name as index if the version of gef file is 4 or greater,
-        otherwise to set gene id, if the version is 3 or less, `gene_name_index` would
-        be forced to `True` because there is no gene id in this case.
+        In a gef file whose version is 3 or lower, there is only a column called **geneName** which is the **gene name**,
+        but in the version higher than 3, additional column called **geneID** is added, which is the **ID** for genes,
+        When being higher version, setting `gene_name_index` to True means setting column **geneName** as index,
+        otherwise, setting column **geneID** as index and the column **geneName** is stored in `data.real_gene_names`,
+        if lower version, `gene_name_index` will be ignored and the column **geneID** will be set as index,
+        regardless of lower or higher version, the column set as index is stored in `data.gene_names`,
+        the index mentioned here is the index of `data.genes`.
     num_threads
         the number of threads to read the data, only available when `bin_type` is `'bins'`.
         -1 means to use all the cores of the machine.

stereo/plots/plot_collection.py

@@ -1402,7 +1402,7 @@ def cells_plotting(
         :param horizontal_offset_additional: the additional offset between each slice on horizontal direction while reorganizing coordinates.
         :param vertical_offset_additional: the additional offset between each slice on vertical direction while reorganizing coordinates.
 
-        :return the figure object if `show` is set to False, otherwise, show the figure directly.
+        :return: the figure object if `show` is set to False, otherwise, show the figure directly.
 
         .. note::