update readme

README.md

@@ -14,7 +14,7 @@ tags:
 <p align="center">
   📃 <a href=" https://doi.org/10.1101/2024.07.25.605062" target="_blank">Pre-print</a> • 👾 <a href="https://discord.gg/pSjWbmjX" target="_blank">Discord bot</a> • 🧬 <a href="https://insilico.com/repository/precious3gpt" target="_blank">Validation digest</a> <br>
 </p>
-<div align=center><img src="P3GPT_architecture.png" width="70%" height="70%" /></div>
+<div align=center><img src="P3GPT_architecture.png" width="80%" height="80%" /></div>
 
 - **Developer**: [Insilico Medicine](https://insilico.com/precious)
 - **License**: cc-by-nc-4.0
@@ -22,8 +22,25 @@ tags:
 - **Domain**: Biomedical
 - **Base architecture**: [MPT](https://huggingface.co/mosaicml/mpt-7b)
 
-### Run model using endpoint step by step
 
+<h1 align="center"> Model summary </h1>
+
+- Precious3GPT (P3GPT) is a unique language model that has been trained on 1.2MM omics data points, knowledge graphs, and biomedical texts (PubMed) to be used in drug discovery and aging research;
+
+- P3GPT simulates biological processes on an omics level to return the transcriptomic, epigenetic, or proteomic signatures of a wide variety of perturbators;
+
+- Various modes of execution allow users to replicate the workflows of chemical screenings, case-control observational studies, and other popular research settings;
+
+- The context of P3GPT-simulated experiments can be defined with >60k biomedical entities, including 3 species, 569 tissues and cell lines, 635 health conditions, and 22k small molecules;
+
+- You may work with P3GPT either by downloading model weights for a local deployment or by interacting with the Discord bot on the official Inisilico Medicine's server.
+
+
+<h1 align="center"> Model usage guide </h1>
+
+### Run model with an endpoint
+<details>
+  <summary style="font-weight:600">Details</summary>
 
 **Step 1 - connect to endpoint**
 ```python
@@ -61,12 +78,12 @@ request_config = {"inputs": config_data, "mode": "meta2diff", "parameters": {
 
 ```
 
-**How Precisou3GPT will see given request**
+**Actual request processed by Precisou3GPT**
 ```text
 [BOS]<age_group2diff2age_group><disease2diff2disease><compound2diff2compound><tissue>lung </tissue><age_individ></age_individ><cell></cell><efo>EFO_0000768 </efo><datatype>expression </datatype><drug>curcumin </drug><dose></dose><time></time><case>70.0-80.0 80.0-90.0 </case><control></control><dataset_type></dataset_type><gender>m </gender><species>human </species>
 ```
 
-**Step 3 - send request to endpoint**
+**Step 3 - send the request to endpoint**
 ```python
 output = query(request_config)
 ```
@@ -85,8 +102,11 @@ output = query(request_config)
 
 }
 ```
+
 Note: If the ```mode``` was supposed to generate compounds, the output would contain ```compounds: List```.
 
+</details>
+
 ---
 
 ### Run model locally
@@ -128,38 +148,47 @@ output = precious3gpt_handler(request_config)
 ---
 ## Precious3GPT request configuration
 
-### Generation Modes (`mode` in config)
 
-Choose the appropriate mode based on your requirements:
+### Instruction (`inputs.instruction` in `config`)
 
-1. **meta2diff**: Generate signature (up- and down- gene lists) given meta-data such as tissue, compound, gender, etc.
-2. **diff2compound**: Predict compounds based on signature.
-3. **meta2diff2compound**: Generate signatures given meta-data and then predict compounds based on generated signatures.
+Instructions define the experimental setting P3GPT will be simulating using the information provided in the prompt. 
+
+1. `disease2diff2disease` - generate an omics signature characterizing a disease / determine the disease based on a given signature;
+2. `compound2diff2compound` - generate an omics signature of a compound-induced perturbation / determine the compound given its omics signature;
+3. `age_group2diff2age_group` - generate differential omics for age groups / determine age groups provided differential gene lists
 
----
 
+### Generation Modes (`mode` in config)
 
-### Instruction (`inputs.instruction` in config)
+Generation modes are not part of the prompt processed to P3GPT but may affect the way P3GPT's response is presented or processed:
 
-1. disease2diff2disease - generate signature for disease / predict disease based on given signature
-2. compound2diff2compound - generate signature for compound / predict compound based on given signature
-3. age_group2diff2age_group - generate signature for age group / predict age group based on signature
+1. `meta2diff`: The ```compound2diff2compound``` instruction can be executed either way. This mode tells P3GPT to return differentially expressed genes and not compounds;
+2. `diff2compound`: The reverse of the ```meta2diff``` mode. Make sure to fill in 'up' and 'down' in the prompt first!
+3. `meta2diff2compound`: Runs ```meta2diff``` first and applies ```diff2compound``` to its output with one call.
+
+See ```Precious3GPT_example.ipynb``` tutorial notebook to learn more about building P3GPT requests.
+
+---
 
 
 ### Other meta-data (`inputs.` in config)
 
-Full list of available values for each meta-data item you can find in ```p3_entities_with_type.csv```
+P3GPT can only simulate the experiments featuring the biomedical entities and metadata values present in ```p3_entities_with_type.csv```
+
+If you aim to study a tissue, a compound, or something else using P3GPT, make sure to check that the names of the entities you are using match those in this file. 
 
 
 
 ## Examples
 
-In the following examples all possible configuration fields are specified. You can leave some meta-data fields in the ```inputs``` section empty string(```""```) or empty list(```[]```). 
+In the following examples, all possible configuration fields are specified. You can leave some meta-data fields in the ```inputs``` section empty string(```""```) or empty list(```[]```). 
 
-_**Example 1**_
+_**Example 1: generate a disease signature**_
+<details>
+  <summary style="font-weight:600">Details</summary>
 
-If you want to generate a signature given specific meta-data you can use the following configuration. Note, ```up``` and ```down``` fields are empty lists as you want to generate them. 
-Here we ask the model to generate a signature for a human within the age group of 70-90 years, male, in tissue - Lungs with disease EFO_0000768.
+If you want to generate a signature given specific metadata you can use the following configuration. Note, ```up``` and ```down``` fields are empty lists as you want to generate them. 
+Here, we ask the model to generate a signature for a male human within in the 70-90 years age group, in the "lung" tissue, with "EFO_0000768" (Idiopathic pulmonary fibrosis).
 
 ```json
 {
@@ -178,7 +207,7 @@ Here we ask the model to generate a signature for a human within the age group o
 }
 ```
 
-Here is output:
+See the corresponding P3GPT output:
 ```json
 {
   "output": {
@@ -191,13 +220,15 @@ Here is output:
   "random_seed": 137
 }
 ```
+</details>
 
-
-_**Example 2**_
-
-Now let's generate a signature for a healthy human within the age group of 70-90 years, male, in tissue - whole blood.
-Note, here we use ```disease2diff2disease``` instruction, but we expect to generate signatures for a healthy human, that's why we'd set ```efo``` to empty string "".
-Alternatively, for this example we can add one more instruction to example 2 - "instruction": ["disease2diff2disease", "age_group2diff2age_group"] 
+_**Example 2: generate an aging signature**_
+<details>
+  <summary style="font-weight:600">Details</summary>
+  
+Now, let's generate a signature for the whole blood of a healthy male human in the 70-90 years age group.
+Note that we use the ```disease2diff2disease``` instruction, but we expect to generate the signatures for a healthy human, that's why we set ```efo``` to an empty string "".
+Alternatively, we can add one more instruction to example 2 — "instruction": ["disease2diff2disease", "age_group2diff2age_group"] 
 
 ```json
 {
@@ -222,7 +253,7 @@ Alternatively, for this example we can add one more instruction to example 2 - "
 
 ```
 
-Here is output:
+P3GPT's output:
 ```json
 {
   "output": {
@@ -235,8 +266,27 @@ Here is output:
   "random_seed": 137
 }
 ```
-
+</details>
 ---
 
 ## Multi-Modality
-Applies by default in tasks where you pass a signature. For each gene in up- and down- lists the model gets embeddings from Knowledge Graph and Text NNs. Then embeddings are averaged in order to obtain one embedding for each modality for each gene list (4 averaged embeddings in total).
+By default, all tasks with a signature in the input prompt are executed with multimodal features. For each gene in the up-/down- lists, P3GPT pulls the embeddings from the Knowledge Graph and Text neural modelity mappers. Then, the embeddings are averaged to obtain one embedding for each modality and each gene list (4 averaged embeddings in total).
+
+## Cite this model
+Please, cite the following bioRxiv pre-print if you use P3GPT in your research papers or other published materials:
+
+```
+@article {Galkin2024.07.25.605062,
+	author = {Galkin, Fedor and Naumov, Vladimir and Pushkov, Stefan and Sidorenko, Denis and Urban, Anatoly and Zagirova, Diana and Alawi, Khadija M and Aliper, Alex and Gumerov, Ruslan and Kalashnikov, Aleksand and Mukba, Sabina and Pogorelskaya, Aleksandra and Ren, Feng and Shneyderman, Anastasia and Tang, Qiuqiong and Xiao, Deyong and Tyshkovskiy, Alexander and Ying, Kejun and Gladyshev, Vadim N. and Zhavoronkov, Alex},
+	title = {Precious3GPT: Multimodal Multi-Species Multi-Omics Multi-Tissue Transformer for Aging Research and Drug Discovery},
+	elocation-id = {2024.07.25.605062},
+	year = {2024},
+	doi = {10.1101/2024.07.25.605062},
+	publisher = {Cold Spring Harbor Laboratory},
+	abstract = {We present a multimodal multi-species multi-omics multi-tissue transformer for aging research and drug discovery capable of performing multiple tasks such as age prediction across species, target discovery, tissue, sex, and disease sample classification, drug sensitivity prediction, replication of omics response and prediction of biological and phenotypic response to compound treatment. This model combines textual, tabular, and knowledge graph-derived representations of biological experiments to provide insights into molecular-level biological processes. We demonstrate that P3GPT has developed an intuition for the interactions between compounds, pathologies, and gene regulation in the context of multiple species and tissues. In these areas, it outperforms existing LLMs and we highlight its utility in diverse case studies. P3GPT is a general model that may be used as a target identification tool, aging clock, digital laboratory, and scientific assistant. The model is intended as a community resource available open source as well as via a Discord server.Competing Interest StatementThe authors are affiliated with Insilico Medicine, a commercial company developing and using generative artificial intelligence and other next-generation AI technologies and robotics for drug discovery, drug development, and aging research. Utilizing its generative AI platform and a range of deep aging clocks, Insilico Medicine has developed a portfolio of multiple therapeutic programs targeting fibrotic diseases, cancer, immunological diseases, and a range of age-related diseases.},
+	URL = {https://www.biorxiv.org/content/early/2024/07/25/2024.07.25.605062},
+	eprint = {https://www.biorxiv.org/content/early/2024/07/25/2024.07.25.605062.full.pdf},
+	journal = {bioRxiv}
+}
+
+```