Skip to content

Commit 50c1d6c

Browse files
authored
Merge pull request #35 from HiDiHlabs/docs_malta
Add scalebar update tutorial Xenium
2 parents e14860d + c8a74bc commit 50c1d6c

File tree

12 files changed

+253
-1065
lines changed

12 files changed

+253
-1065
lines changed

README.md

Lines changed: 77 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -4,37 +4,68 @@
44

55
A python tool to investigate vertical signal properties of imaging-based spatial transcriptomics data.
66

7-
## introduction
7+
## Introduction
88

99
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:
1010

1111
![3D slice visualization](docs/resources/cell_overlap_visualization.jpg)
1212

1313

1414

15-
Ovrl.py is a quality-control tool for spatial transcriptomics data that can help analysts find sources of vertical signal inconsistency in their data.
15+
**Ovrl.py** is a quality-control tool for spatial transcriptomics data that can help analysts find sources of vertical signal inconsistency in their data.
1616
It is works with imaging-based spatial transcriptomics data, such as 10x genomics' Xenium or vizgen's MERFISH platforms.
1717
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.
1818
Users can also use the built-in 3D visualisation tool to explore regions of signal inconsistency in their data on a molecular level.
1919

20-
## installation
20+
## Installation
2121

22-
The tool can be installed using the requirements.txt file in the root directory of the repository.
22+
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.
2323

24-
```bash
25-
pip install -e .
26-
```
2724

28-
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.
25+
> Ensure that Python (>= 3.6 and < 3.13) and pip are installed on your machine before proceeding.
2926
30-
```bash
31-
pip install jupyter pyarrow fastparquet
32-
```
27+
Steps for Installation
28+
-----------------------
29+
30+
1. **Clone the Repository**
31+
32+
First, ensure that you have cloned the repository to your local machine. If you haven't already done so, use the following commands:
33+
34+
````bash
35+
36+
git clone https://github.com/HiDiHlabs/ovrl.py.git
37+
cd ovrl.py
38+
39+
````
40+
41+
2. **Install Ovrlpy**
42+
43+
To install the ovrlpy package, execute the following command:
44+
45+
````bash
46+
47+
pip install .
48+
````
49+
This installs the package based on the current state of the source files.
50+
51+
3. **Set Up for Interactive Analysis (Optional)**
52+
53+
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:
3354

34-
## quickstart
55+
````bash
3556

57+
pip install jupyter
58+
59+
````
60+
61+
62+
## Quickstart
63+
-----------------------
3664
The simplest use case of ovrlpy is the creation of a signal integrity map from a spatial transcriptomics dataset.
37-
In a first step, we define a number of parameters for the analysis:
65+
66+
1. **Set Parameters & Load Data**
67+
68+
Define parameters and load your data.
3869

3970
```python
4071
import pandas as pd
@@ -50,52 +81,65 @@ coordinate_df = pd.read_csv('path/to/coordinate_file.csv')
5081
coordinate_df.head()
5182
```
5283

53-
you can then fit an ovrlpy model to the data and create a signal integrity map:
84+
2. **Fit the model**
5485

55-
```python
86+
Fit the ovrlpy model to create a signal integrity map.
5687

57-
# fit the ovrlpy model to the data
88+
```python
5889
5990
from ovrlpy import ovrlp
6091
61-
integrity, signal, visualizer = ovrlp.compute_coherence_map(df=coordinate_df,KDE_bandwidth=kde_bandwidth,n_expected_celltypes=n_expected_celltypes)
62-
92+
integrity, signal, visualizer = ovrlp.compute_coherence_map(
93+
df=coordinate_df,
94+
KDE_bandwidth=kde_bandwidth,
95+
n_expected_celltypes=n_expected_celltypes
96+
)
6397
```
6498

65-
returns a signal integrity map, a signal map and a visualizer object that can be used to visualize the data:
99+
3. **Visualize Model Fit**
66100

67101
```python
68102
visualizer.plot_fit()
69103
```
70104

71-
and visualize the signal integrity map:
105+
4. **Plot Signal Integrity Map**
106+
107+
Plot the signal integrity map with a threshold for signal coherence.
72108

73109
```python
74110
fig, ax = ovrlp.plot_signal_integrity(integrity,signal,signal_threshold=4.0)
75111
```
76112

77-
Ovrlpy can also identify individual overlap events in the data:
113+
5. **Detect & Visualize Overlaps (Doublets)**
78114

79115
```python
80116
import matplotlib.pyplot as plt
81-
doublet_df = ovrlp.detect_doublets(integrity,signal,signal_cutoff=4,coherence_sigma=1)
117+
doublet_df = ovrlp.detect_doublets(
118+
integrity,
119+
signal,
120+
signal_cutoff=4,
121+
coherence_sigma=1
122+
)
82123
83124
doublet_df.head()
84125
```
85126

86-
And use the visualizer to show a 3D visualization of the overlaps in the tissue:
127+
6. **3D Visualization of Overlap Event**
87128

88-
```python
89-
window_size=60 # size of the window around the doublet to show
90-
n_doublet_to_show = 0 # index of the doublet to show
91-
x,y = doublet_df.loc[doublet_case,['x','y']] # location of the doublet event
129+
This visualization shows a 3D representation of the spatial overlap event, giving more insight into the structure and coherence of the signals.
92130

93-
# subsample the data around the doublet event
94-
subsample = visualizer.subsample_df(x,y,coordinate_df,window_size=window_size)
95-
# transform the subsample using the fitted color embedding model
131+
```python
132+
window_size = 60
133+
n_doublet_to_show = 0
134+
x, y = doublet_df.loc[n_doublet_to_show, ['x', 'y']]
135+
subsample = visualizer.subsample_df(x, y, coordinate_df, window_size=window_size)
96136
subsample_embedding, subsample_embedding_color = visualizer.transform(subsample)
97-
98-
# plot the subsample instance:
99-
visualizer.plot_instance(subsample,subsample[['x','y']].values,subsample_embedding_color,x,y,window_size=window_size)
137+
visualizer.plot_instance(
138+
subsample,
139+
subsample[['x', 'y']].values,
140+
subsample_embedding_color,
141+
x, y,
142+
window_size=window_size
143+
)
100144
101145
```

docs/source/index.rst

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
Ovrlpy
1+
Ovrlpy
22
==========================
33
**ovrlpy** is a python tool to investigate cell overlaps in imaging-based spatial transcriptomics data.
44

@@ -18,12 +18,12 @@ Users can also use the built-in 3D visualisation tool to explore regions of sign
1818
:align: center
1919
:width: 600px
2020

21-
Citation
21+
Citation
2222
---------
2323

24-
If you are using `ovrlpy` for your research please cite
24+
If you are using `ovrlpy` for your research please cite
25+
2526

26-
2727

2828

2929
.. toctree::

docs/source/installation.rst

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -20,9 +20,12 @@ Steps for Installation
2020
cd ovrl.py
2121
2222
23-
2. **Install the Package in Editable Mode**
23+
2. **Install the Package**
2424

2525
To install the ovrlpy package, execute the following command:
26+
.. note::
27+
28+
Ensure that Python (>= 3.6 and < 3.13) and pip are installed on your machine before proceeding.
2629

2730
.. code-block:: bash
2831
@@ -32,11 +35,11 @@ Steps for Installation
3235

3336
3. **Set Up for Interactive Analysis (Optional)**
3437

35-
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:
38+
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:
3639

3740
.. code-block:: bash
3841
39-
pip install jupyter pyarrow fastparquet
42+
pip install jupyter
4043
4144
4245
Summary of Commands
@@ -55,4 +58,3 @@ Here's a summary of the commands to run for installation:
5558
5659
# Step 3: Install Jupyter and other packages for interactive analysis
5760
pip install jupyter pyarrow fastparquet
58-

docs/source/tutorials/index.rst

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
1-
Tutorials
1+
Tutorials
22
==========================
33

44
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>`_,
5-
`Vizgen liver <https://info.vizgen.com/mouse-liver-data>`_, `Vizgen receptor <https://info.vizgen.com/mouse-brain-map>`_ ).
5+
`Vizgen liver <https://info.vizgen.com/mouse-liver-data>`_, `Vizgen receptor <https://info.vizgen.com/mouse-brain-map>`_ ).
66

77

88
Installation
@@ -23,13 +23,13 @@ Installation
2323

2424
.. code-block:: bash
2525
26-
pip install ovrlpy[tutorial]
26+
pip install ovrlpy[tutorial]
2727
2828
2929
This will install the required dependencies and tutorial-specific components of the package.
3030

3131
3. **Start with the Tutorials**
32-
To start the tutorial JupyterNotebooks are stored in
32+
To start the tutorial JupyterNotebooks are stored in
3333
.. code-block:: bash
3434
3535
ovrl.py/docs/source/tutorials/*.ipynb

docs/source/tutorials/vizgen_liver.ipynb

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -101,7 +101,6 @@
101101
}
102102
],
103103
"source": [
104-
"\n",
105104
"columns = [\"global_x\", \"global_y\", \"global_z\", \"gene\"]\n",
106105
"\n",
107106
"coordinate_df = pd.read_csv(\n",
@@ -247,7 +246,7 @@
247246
],
248247
"source": [
249248
"_ = plt.scatter(coordinate_df.loc[::100, \"x\"], coordinate_df.loc[::100, \"y\"], s=1)\n",
250-
"plt.gca().set_aspect('equal', adjustable='box')\n"
249+
"plt.gca().set_aspect(\"equal\", adjustable=\"box\")"
251250
]
252251
},
253252
{
@@ -447,7 +446,7 @@
447446
"_ = plt.scatter(\n",
448447
" doublet_df[\"x\"], doublet_df[\"y\"], c=doublet_df[\"integrity\"], s=1, cmap=\"viridis_r\"\n",
449448
")\n",
450-
"plt.gca().set_aspect('equal', adjustable='box')\n",
449+
"plt.gca().set_aspect(\"equal\", adjustable=\"box\")\n",
451450
"plt.colorbar(_)"
452451
]
453452
},

0 commit comments

Comments
 (0)