# MetaChat
## Brief introduction
MetaChat is a Python package to screen metabolic cell communication (MCC) from spatial multi-omics data of transcriptomics and metabolomics.
It contains many intuitive visualization and downstream analysis tools, provides a great practical toolbox for biomedical researchers.
### Metabolic cell communication
Metabolic cell-cell communication (MCC) occurs when sensor proteins in the receiver cells detect metabolites in their environment, activating intracellular signaling events. There are three major potential sensors of metabolites: surface receptors, nuclear receptors, and transporters. Metabolites secreted from cells are either transported over short-range distances (a few cells) via diffusion through extracellular space, or over long-range distances via the bloodstream and the cerebrospinal fluid (CSF).
<img width="500" alt="image" src="https://github.com/SonghaoLuo/MetaChat/assets/138028157/f08f21de-eeae-4626-8fbe-c26a307ec225">
### MetaChatDB
MetaChatDB is a literature-supported database for metabolite-sensor interactions for both human and mouse. All the metabolite-sensor interactions are reported based on peer-reviewed publications. Specifically, we manually build MetaChatDB by integrating three high-quality databases (PDB, HMDB, UniProt) that are being continually updated.
<img width="500" alt="image" src="https://github.com/SonghaoLuo/MetaChat/assets/138028157/20e168c2-2409-47c4-881f-3b80d38326f3">
## Installation
### System requirements
Recommended operating systems: macOS or Linux. MetaChat was developed and tested on Linux and macOS.
### Python requirements
MetaChat was developed using python 3.9.
### Installation using `pip`
We suggest setting up MetaChat in a separate `mamba` or `conda` environment to prevent conflicts with other software dependencies. Create a new Python environment specifically for MetaChat and install the required libraries within it.
```bash
mamba create -n metachat_env python=3.9 r-base=4.3.2
mamba activate metachat_env
pip install metachat
```
## Documentation, and Tutorials
For more realistic and simulation examples, please see MetaChat documentation that is available through the link https://metachat.readthedocs.io/en/latest/.
## Quick start
Let's get a quick start on using metachat to infer MCC by using simulation data generated from a PDE dynamic model.
### Import packages
```python
import os
import numpy as np
import pandas as pd
import scanpy as sc
import squidpy as sq
import matplotlib.pyplot as plt
import metachat as mc
```
### Setting work dictionary
To run the examples, you'll need to download the some pre-existing files in `docs/tutorials/simulated_data` folder and change your working directory to the `simulated_data` folder.
```python
os.chdir("your_path/simulated_data")
```
### Multi-omics data from simulation
```python
adata = sc.read("data/example1/adata_example1.h5ad")
```
This dataset consists of a metabolite `M1` and a sensor `S1`. Their spatial distributions are shown below:
```python
fig, ax = plt.subplots(1, 2, figsize = (8,4))
sq.pl.spatial_scatter(adata = adata, color = "M1", size = 80, cmap = "Blues", shape = None, ax = ax[0])
ax[0].invert_yaxis()
ax[0].set_box_aspect(1)
sq.pl.spatial_scatter(adata = adata, color = "S1", size = 80, cmap = "Reds", shape = None, ax = ax[1])
ax[1].invert_yaxis()
ax[1].set_box_aspect(1)
plt.show()
```
<img src="https://github.com/SonghaoLuo/MetaChat/assets/138028157/7176aabd-7e3e-4439-9f9c-9b0346fd5da8" alt="Spatial Distributions" width="600"/>
### Long-range channels (LRC)
Import the pre-defined long range channel and add it to the `adata` object.
```python
LRC_channel = np.load('data/example1/LRC_channel.npy')
adata.obs['LRC_type1_filtered'] = LRC_channel.flatten()
adata.obs['LRC_type1_filtered'] = adata.obs['LRC_type1_filtered'].astype('category')
```
It's spatial distribution are shown in orange color:
```python
fig, ax = plt.subplots(figsize = (3,3))
sq.pl.spatial_scatter(adata = adata, color = "LRC_type1_filtered", size = 80, shape = None, ax = ax)
ax.invert_yaxis()
ax.set_box_aspect(1)
plt.show()
```
<img src="https://github.com/SonghaoLuo/MetaChat/assets/138028157/c7cc5dbd-1725-4726-a973-8555cf4f6ad0" alt="Spatial Distributions" width="300"/>
### Metabolite-sensor database construction
We need to artificially create a simple database which must include three columns: 'Metabolite', 'Sensor', 'Long.Range.Channel', representing the metabolite name, the sensor name, and the type of long range channel that metabolites may be entered, respectively.
In this example, we assume that the metabolite `M1` can communicate with proximal cells by short-range diffusion and with distal cells by long-range channel transport (`type1`).
```python
M_S_pair = [['M1', 'S1', 'type1']]
df_metasen = pd.DataFrame(M_S_pair)
df_metasen.columns = ['Metabolite', 'Sensor', 'Long.Range.Channel']
```
### Compute the cost matrix based on the long-range channels
To utilize flow-optimal transport, we need to compute the cost matrix depends mainly on two parameters:maximum communication distance (`dis_thr`) and long-range communication strength (`LRC_strength`).
```python
mc.pp.compute_costDistance(adata = adata,
LRC_type = ["type1"],
dis_thr = 10,
k_neighb = 5,
LRC_strength = 4,
plot = True,
spot_size = 1)
```
### Run the inference function
```python
mc.tl.metabolic_communication(adata = adata,
database_name = 'msdb_example1',
df_metasen = df_metasen,
LRC_type = ["type1"],
dis_thr = 15,
fot_weights = (1.0,0.0,0.0,0.0),
fot_eps_p = 0.25,
fot_rho = 1.0,
cost_type = 'euc')
```
### Compare MetaChat results with the PDE model
Comparative results showed that the distribution of M1-S1 inferred by MetaChat had a high correlation with that simulated by the PDE model.
```python
MCC_PDE = np.load('data/example1/pde_result.npy')
MCC_infer = adata.obsm['MetaChat-msdb_example1-sum-receiver']['r-M1-S1'].values.reshape(50,50)
```
```python
fig, ax = plt.subplots(1,2, figsize = (7,14))
ax[0].imshow(MCC_PDE[2].T, cmap='viridis', origin='lower')
ax[0].set_xlabel('x')
ax[0].set_ylabel('y')
ax[0].set_title('M1-S1 distribution from PDE')
ax[0].set_box_aspect(1)
ax[1].imshow(MCC_infer.T, cmap='viridis', origin='lower')
ax[1].set_xlabel('x')
ax[1].set_ylabel('y')
ax[1].set_title('M1-S1 distribution with LRC')
ax[1].set_box_aspect(1)
plt.tight_layout()
```
<img src="https://github.com/SonghaoLuo/MetaChat/assets/138028157/9aec37b3-a266-4d86-b486-5b6409c06293" alt="Spatial Distributions" width="600"/>
## Reference
Luo, S., Almet, A.A., Nie, Q.. Spatial metabolic communication flow of single cells.
Raw data
{
"_id": null,
"home_page": null,
"name": "metachat",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "metabolic cell communicaiton, spatial transcriptomics, spatial metabolomics, optimal transport",
"author": null,
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/08/07/90a7c56fedf6c783e96964ebfe4add6d118c5e619c922a731b366b4732d5/metachat-0.0.3.tar.gz",
"platform": null,
"description": "# MetaChat\n## Brief introduction\nMetaChat is a Python package to screen metabolic cell communication (MCC) from spatial multi-omics data of transcriptomics and metabolomics. \nIt contains many intuitive visualization and downstream analysis tools, provides a great practical toolbox for biomedical researchers.\n\n### Metabolic cell communication\nMetabolic cell-cell communication (MCC) occurs when sensor proteins in the receiver cells detect metabolites in their environment, activating intracellular signaling events. There are three major potential sensors of metabolites: surface receptors, nuclear receptors, and transporters. Metabolites secreted from cells are either transported over short-range distances (a few cells) via diffusion through extracellular space, or over long-range distances via the bloodstream and the cerebrospinal fluid (CSF).\n\n<img width=\"500\" alt=\"image\" src=\"https://github.com/SonghaoLuo/MetaChat/assets/138028157/f08f21de-eeae-4626-8fbe-c26a307ec225\">\n\n### MetaChatDB\nMetaChatDB is a literature-supported database for metabolite-sensor interactions for both human and mouse. All the metabolite-sensor interactions are reported based on peer-reviewed publications. Specifically, we manually build MetaChatDB by integrating three high-quality databases (PDB, HMDB, UniProt) that are being continually updated.\n\n<img width=\"500\" alt=\"image\" src=\"https://github.com/SonghaoLuo/MetaChat/assets/138028157/20e168c2-2409-47c4-881f-3b80d38326f3\">\n\n## Installation\n### System requirements\nRecommended operating systems: macOS or Linux. MetaChat was developed and tested on Linux and macOS.\n### Python requirements\nMetaChat was developed using python 3.9.\n### Installation using `pip`\nWe suggest setting up MetaChat in a separate `mamba` or `conda` environment to prevent conflicts with other software dependencies. Create a new Python environment specifically for MetaChat and install the required libraries within it.\n\n```bash\nmamba create -n metachat_env python=3.9 r-base=4.3.2\nmamba activate metachat_env\npip install metachat\n```\n\n## Documentation, and Tutorials\n\nFor more realistic and simulation examples, please see MetaChat documentation that is available through the link https://metachat.readthedocs.io/en/latest/.\n\n## Quick start\nLet's get a quick start on using metachat to infer MCC by using simulation data generated from a PDE dynamic model.\n\n### Import packages\n```python\nimport os\nimport numpy as np\nimport pandas as pd\nimport scanpy as sc\nimport squidpy as sq\nimport matplotlib.pyplot as plt\nimport metachat as mc\n```\n\n### Setting work dictionary\nTo run the examples, you'll need to download the some pre-existing files in `docs/tutorials/simulated_data` folder and change your working directory to the `simulated_data` folder.\n\n```python\nos.chdir(\"your_path/simulated_data\")\n```\n\n### Multi-omics data from simulation\n```python\nadata = sc.read(\"data/example1/adata_example1.h5ad\")\n```\nThis dataset consists of a metabolite `M1` and a sensor `S1`. Their spatial distributions are shown below:\n```python\nfig, ax = plt.subplots(1, 2, figsize = (8,4))\nsq.pl.spatial_scatter(adata = adata, color = \"M1\", size = 80, cmap = \"Blues\", shape = None, ax = ax[0])\nax[0].invert_yaxis()\nax[0].set_box_aspect(1)\nsq.pl.spatial_scatter(adata = adata, color = \"S1\", size = 80, cmap = \"Reds\", shape = None, ax = ax[1])\nax[1].invert_yaxis()\nax[1].set_box_aspect(1)\nplt.show()\n```\n<img src=\"https://github.com/SonghaoLuo/MetaChat/assets/138028157/7176aabd-7e3e-4439-9f9c-9b0346fd5da8\" alt=\"Spatial Distributions\" width=\"600\"/>\n\n### Long-range channels (LRC)\nImport the pre-defined long range channel and add it to the `adata` object.\n```python\nLRC_channel = np.load('data/example1/LRC_channel.npy')\nadata.obs['LRC_type1_filtered'] = LRC_channel.flatten()\nadata.obs['LRC_type1_filtered'] = adata.obs['LRC_type1_filtered'].astype('category')\n```\nIt's spatial distribution are shown in orange color:\n```python\nfig, ax = plt.subplots(figsize = (3,3))\nsq.pl.spatial_scatter(adata = adata, color = \"LRC_type1_filtered\", size = 80, shape = None, ax = ax)\nax.invert_yaxis()\nax.set_box_aspect(1)\nplt.show()\n```\n<img src=\"https://github.com/SonghaoLuo/MetaChat/assets/138028157/c7cc5dbd-1725-4726-a973-8555cf4f6ad0\" alt=\"Spatial Distributions\" width=\"300\"/>\n\n### Metabolite-sensor database construction\nWe need to artificially create a simple database which must include three columns: 'Metabolite', 'Sensor', 'Long.Range.Channel', representing the metabolite name, the sensor name, and the type of long range channel that metabolites may be entered, respectively. \nIn this example, we assume that the metabolite `M1` can communicate with proximal cells by short-range diffusion and with distal cells by long-range channel transport (`type1`).\n```python\nM_S_pair = [['M1', 'S1', 'type1']]\ndf_metasen = pd.DataFrame(M_S_pair)\ndf_metasen.columns = ['Metabolite', 'Sensor', 'Long.Range.Channel']\n```\n\n### Compute the cost matrix based on the long-range channels\nTo utilize flow-optimal transport, we need to compute the cost matrix depends mainly on two parameters:maximum communication distance (`dis_thr`) and long-range communication strength (`LRC_strength`).\n```python\nmc.pp.compute_costDistance(adata = adata,\n LRC_type = [\"type1\"],\n dis_thr = 10,\n k_neighb = 5,\n LRC_strength = 4,\n plot = True,\n spot_size = 1)\n```\n\n### Run the inference function\n```python\nmc.tl.metabolic_communication(adata = adata,\n database_name = 'msdb_example1',\n df_metasen = df_metasen,\n LRC_type = [\"type1\"],\n dis_thr = 15,\n fot_weights = (1.0,0.0,0.0,0.0),\n fot_eps_p = 0.25,\n fot_rho = 1.0,\n cost_type = 'euc')\n```\n\n### Compare MetaChat results with the PDE model\nComparative results showed that the distribution of M1-S1 inferred by MetaChat had a high correlation with that simulated by the PDE model.\n```python\nMCC_PDE = np.load('data/example1/pde_result.npy')\nMCC_infer = adata.obsm['MetaChat-msdb_example1-sum-receiver']['r-M1-S1'].values.reshape(50,50)\n```\n```python\nfig, ax = plt.subplots(1,2, figsize = (7,14))\nax[0].imshow(MCC_PDE[2].T, cmap='viridis', origin='lower')\nax[0].set_xlabel('x')\nax[0].set_ylabel('y')\nax[0].set_title('M1-S1 distribution from PDE')\nax[0].set_box_aspect(1)\nax[1].imshow(MCC_infer.T, cmap='viridis', origin='lower')\nax[1].set_xlabel('x')\nax[1].set_ylabel('y')\nax[1].set_title('M1-S1 distribution with LRC')\nax[1].set_box_aspect(1)\nplt.tight_layout()\n```\n<img src=\"https://github.com/SonghaoLuo/MetaChat/assets/138028157/9aec37b3-a266-4d86-b486-5b6409c06293\" alt=\"Spatial Distributions\" width=\"600\"/> \n\n## Reference\nLuo, S., Almet, A.A., Nie, Q.. Spatial metabolic communication flow of single cells.\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "Spatial metabolic communication flow of single cells.",
"version": "0.0.3",
"project_urls": null,
"split_keywords": [
"metabolic cell communicaiton",
" spatial transcriptomics",
" spatial metabolomics",
" optimal transport"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "55f31addf4da43f06e6dba46fb088aaa65e1966af6eecd5c14037a6fd1887e7d",
"md5": "0f499e9e88caa7beb7e241bd1fba879f",
"sha256": "11916ad444fa3f60d47690597e89edcf5ae1c959a10ccfa0243e816b5cea865a"
},
"downloads": -1,
"filename": "metachat-0.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0f499e9e88caa7beb7e241bd1fba879f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 418864,
"upload_time": "2024-07-08T03:56:53",
"upload_time_iso_8601": "2024-07-08T03:56:53.806146Z",
"url": "https://files.pythonhosted.org/packages/55/f3/1addf4da43f06e6dba46fb088aaa65e1966af6eecd5c14037a6fd1887e7d/metachat-0.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "080790a7c56fedf6c783e96964ebfe4add6d118c5e619c922a731b366b4732d5",
"md5": "818ae2d4a073e0cdc7fe5df0a91d603d",
"sha256": "09bd085f6cc2bbf95609585f97be7f3cb7e00361f1cf2340012e33817ace9eaf"
},
"downloads": -1,
"filename": "metachat-0.0.3.tar.gz",
"has_sig": false,
"md5_digest": "818ae2d4a073e0cdc7fe5df0a91d603d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 407624,
"upload_time": "2024-07-08T03:56:56",
"upload_time_iso_8601": "2024-07-08T03:56:56.059538Z",
"url": "https://files.pythonhosted.org/packages/08/07/90a7c56fedf6c783e96964ebfe4add6d118c5e619c922a731b366b4732d5/metachat-0.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-08 03:56:56",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "metachat"
}
JSON