Merge pull request #35 from HiDiHlabs/docs_malta

Add scalebar update tutorial Xenium

Author: al3xmlt030

README.md

@@ -4,37 +4,68 @@
 
 A python tool to investigate vertical signal properties of imaging-based spatial transcriptomics data.
 
-## introduction
+## Introduction
 
 Much of spatial biology uses microscopic tissue slices to study the spatial distribution of cells and molecules. In the process, tissue slices are often interpreted as 2D representations of 3D biological structures - which can introduce artefacts and inconsistencies in the data whenever structures overlap in the thin vertical dimension of the slice:
 
 ![3D slice visualization](docs/resources/cell_overlap_visualization.jpg)
 
 
 
-Ovrl.py is a quality-control tool for spatial transcriptomics data that can help analysts find sources of vertical signal inconsistency in their data.
+**Ovrl.py** is a quality-control tool for spatial transcriptomics data that can help analysts find sources of vertical signal inconsistency in their data.
 It is works with imaging-based spatial transcriptomics data, such as 10x genomics' Xenium or vizgen's MERFISH platforms.
 The main feature of the tool is the production of 'signal integrity maps' that can help analysts identify sources of signal inconsistency in their data.
 Users can also use the built-in 3D visualisation tool to explore regions of signal inconsistency in their data on a molecular level.
 
-## installation
+## Installation
 
-The tool can be installed using the requirements.txt file in the root directory of the repository.
+To install the necessary tools and dependencies for this project, follow the steps outlined below. These instructions will guide you through setting up the environment for both standard use and interactive analysis with Jupyter notebooks.
 
-```bash
-pip install -e .
-```
 
-In order to use the ipython notebooks and perform interactive analysis, you will need to install the jupyter package also. For the tutorials, pyarrow and fastparquet are also required.
+> Ensure that Python (>= 3.6 and < 3.13) and pip are installed on your machine before proceeding.
 
-```bash
-pip install jupyter pyarrow fastparquet
-```
+Steps for Installation
+-----------------------
+
+1. **Clone the Repository**
+
+   First, ensure that you have cloned the repository to your local machine. If you haven't already done so, use the following commands:
+
+   ````bash
+
+      git clone https://github.com/HiDiHlabs/ovrl.py.git
+      cd ovrl.py
+
+    ````
+
+2. **Install Ovrlpy**
+
+   To install the ovrlpy package, execute the following command:
+
+   ````bash
+
+      pip install .
+    ````
+   This installs the package based on the current state of the source files.
+
+3. **Set Up for Interactive Analysis (Optional)**
+
+   If you plan to use Jupyter notebooks for interactive analysis or the project's tutorials, you'll need to install some additional packages: **Jupyter**. Install them using:
 
-## quickstart
+   ````bash
 
+      pip install jupyter
+
+    ````
+
+
+## Quickstart
+-----------------------
 The simplest use case of ovrlpy is the creation of a signal integrity map from a spatial transcriptomics dataset.
-In a first step, we define a number of parameters for the analysis:
+
+1. **Set Parameters & Load Data**
+
+Define parameters and load your data.
 
 ```python
 import pandas as pd
@@ -50,52 +81,65 @@ coordinate_df = pd.read_csv('path/to/coordinate_file.csv')
 coordinate_df.head()
 ```
 
-you can then fit an ovrlpy model to the data and create a signal integrity map:
+2. **Fit the model**
 
-```python
+Fit the ovrlpy model to create a signal integrity map.
 
-# fit the ovrlpy model to the data
+```python
 
 from ovrlpy import ovrlp
 
-integrity, signal, visualizer = ovrlp.compute_coherence_map(df=coordinate_df,KDE_bandwidth=kde_bandwidth,n_expected_celltypes=n_expected_celltypes)
-
+integrity, signal, visualizer = ovrlp.compute_coherence_map(
+    df=coordinate_df,
+    KDE_bandwidth=kde_bandwidth,
+    n_expected_celltypes=n_expected_celltypes
+)
 ```
 
-returns a signal integrity map, a signal map and a visualizer object that can be used to visualize the data:
+3. **Visualize Model Fit**
 
 ```python
 visualizer.plot_fit()
 ```
 
-and visualize the signal integrity map:
+4. **Plot Signal Integrity Map**
+
+Plot the signal integrity map with a threshold for signal coherence.
 
 ```python
 fig, ax = ovrlp.plot_signal_integrity(integrity,signal,signal_threshold=4.0)
 ```
 
-Ovrlpy can also identify individual overlap events in the data:
+5. **Detect & Visualize Overlaps (Doublets)**
 
 ```python
 import matplotlib.pyplot as plt
-doublet_df = ovrlp.detect_doublets(integrity,signal,signal_cutoff=4,coherence_sigma=1)
+doublet_df = ovrlp.detect_doublets(
+    integrity,
+    signal,
+    signal_cutoff=4,
+    coherence_sigma=1
+)
 
 doublet_df.head()
 ```
 
-And use the visualizer to show a 3D visualization of the overlaps in the tissue:
+6. **3D Visualization of Overlap Event**
 
-```python
-window_size=60          # size of the window around the doublet to show
-n_doublet_to_show = 0   # index of the doublet to show
-x,y = doublet_df.loc[doublet_case,['x','y']] # location of the doublet event
+This visualization shows a 3D representation of the spatial overlap event, giving more insight into the structure and coherence of the signals.
 
-# subsample the data around the doublet event
-subsample = visualizer.subsample_df(x,y,coordinate_df,window_size=window_size)
-# transform the subsample using the fitted color embedding model
+```python
+window_size = 60
+n_doublet_to_show = 0
+x, y = doublet_df.loc[n_doublet_to_show, ['x', 'y']]
+subsample = visualizer.subsample_df(x, y, coordinate_df, window_size=window_size)
 subsample_embedding, subsample_embedding_color = visualizer.transform(subsample)
-
-# plot the subsample instance:
-visualizer.plot_instance(subsample,subsample[['x','y']].values,subsample_embedding_color,x,y,window_size=window_size)
+visualizer.plot_instance(
+    subsample,
+    subsample[['x', 'y']].values,
+    subsample_embedding_color,
+    x, y,
+    window_size=window_size
+)
 
 ```

docs/source/index.rst

@@ -1,4 +1,4 @@
-Ovrlpy 
+Ovrlpy
 ==========================
 **ovrlpy** is a python tool to investigate cell overlaps in imaging-based spatial transcriptomics data.
 
@@ -18,12 +18,12 @@ Users can also use the built-in 3D visualisation tool to explore regions of sign
    :align: center
    :width: 600px
 
-Citation 
+Citation
 ---------
 
-If you are using `ovrlpy` for your research please cite 
+If you are using `ovrlpy` for your research please cite
+
 
- 
 
 
 .. toctree::

docs/source/installation.rst

@@ -20,9 +20,12 @@ Steps for Installation
       cd ovrl.py
 
 
-2. **Install the Package in Editable Mode**
+2. **Install the Package**
 
    To install the ovrlpy package, execute the following command:
+   .. note::
+
+   Ensure that Python (>= 3.6 and < 3.13) and pip are installed on your machine before proceeding.
 
    .. code-block:: bash
 
@@ -32,11 +35,11 @@ Steps for Installation
 
 3. **Set Up for Interactive Analysis (Optional)**
 
-   If you plan to use Jupyter notebooks for interactive analysis or the project's tutorials, you'll need to install some additional packages: **Jupyter**, **pyarrow**, and **fastparquet**. Install them using:
+   If you plan to use Jupyter notebooks for interactive analysis or the project's tutorials, you'll need to install some additional packages: **Jupyter**. Install them using:
 
    .. code-block:: bash
 
-      pip install jupyter pyarrow fastparquet
+      pip install jupyter
 
 
 Summary of Commands
@@ -55,4 +58,3 @@ Here's a summary of the commands to run for installation:
 
    # Step 3: Install Jupyter and other packages for interactive analysis
    pip install jupyter pyarrow fastparquet
-

docs/source/tutorials/index.rst

@@ -1,8 +1,8 @@
-Tutorials 
+Tutorials
 ==========================
 
 We will demonstrate an example usage of ovrlpy on 3 different datasets (`Xenium Brain <https://www.10xgenomics.com/products/xenium-in-situ/mouse-brain-dataset-explorer>`_,
-`Vizgen liver <https://info.vizgen.com/mouse-liver-data>`_, `Vizgen receptor <https://info.vizgen.com/mouse-brain-map>`_  ). 
+`Vizgen liver <https://info.vizgen.com/mouse-liver-data>`_, `Vizgen receptor <https://info.vizgen.com/mouse-brain-map>`_  ).
 
 
 Installation
@@ -23,13 +23,13 @@ Installation
 
    .. code-block:: bash
 
-      pip install ovrlpy[tutorial] 
+      pip install ovrlpy[tutorial]
 
 
    This will install the required dependencies and tutorial-specific components of the package.
 
 3. **Start with the Tutorials**
-   To start the tutorial JupyterNotebooks are stored in 
+   To start the tutorial JupyterNotebooks are stored in
    .. code-block:: bash
 
       ovrl.py/docs/source/tutorials/*.ipynb

docs/source/tutorials/vizgen_liver.ipynb

@@ -101,7 +101,6 @@
     }
    ],
    "source": [
-    "\n",
     "columns = [\"global_x\", \"global_y\", \"global_z\", \"gene\"]\n",
     "\n",
     "coordinate_df = pd.read_csv(\n",
@@ -247,7 +246,7 @@
    ],
    "source": [
     "_ = plt.scatter(coordinate_df.loc[::100, \"x\"], coordinate_df.loc[::100, \"y\"], s=1)\n",
-    "plt.gca().set_aspect('equal', adjustable='box')\n"
+    "plt.gca().set_aspect(\"equal\", adjustable=\"box\")"
    ]
   },
   {
@@ -447,7 +446,7 @@
     "_ = plt.scatter(\n",
     "    doublet_df[\"x\"], doublet_df[\"y\"], c=doublet_df[\"integrity\"], s=1, cmap=\"viridis_r\"\n",
     ")\n",
-    "plt.gca().set_aspect('equal', adjustable='box')\n",
+    "plt.gca().set_aspect(\"equal\", adjustable=\"box\")\n",
     "plt.colorbar(_)"
    ]
   },