docs

cc907196 · Rui Ribeiro · 5795d4d4 · cc907196 · cc907196 · cc907196
Commit cc907196 authored 2 years ago by Rui Ribeiro
--- a/SSBtoolkit-Tutorial1.ipynb
+++ b/SSBtoolkit-Tutorial1.ipynb
@@ -486,6 +486,14 @@
    "    <img src=\"https://res.cloudinary.com/djz27k5hg/image/upload/v1642677502/logos/COFUNDED_EU_j2ktlp.jpg\" width=\"300\" align='left' style=\"margin-left:50px\">\n",
    "</div>  "
   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "690b7ff2",
+   "metadata": {},
+   "outputs": [],
+   "source": []
  }
 ],
 "metadata": {

 %% Cell type:markdown id:ebbbd7d9 tags:

 <div style="padding-bottom:50px">
 <img src="https://res.cloudinary.com/djz27k5hg/image/upload/v1637335206/logos/Logo_des_Forschungszentrums_J_C3_BClich_seit_2018_hcliq4.svg"  width=250 align='left' style="margin-top:30px"/>
 <img src="https://res.cloudinary.com/djz27k5hg/image/upload/v1637657234/logos/HBP_horizontal_logo_qtcyzn.png" width="300" align='left' style="margin-left:50px">
 </div>

 <br><br><br><br>

 # Simulation of dose-response curves of agonists using affinity values

 In this tutorial we will simulate a mathematical model of a signaling pathway to obtain dose-response curves, from wich  *potency (EC<sub>50</sub>)* values of agonists can be infered.



 This tutorial and the rest in this sequence can be done in Google colab. If you'd like to open this notebook in colab, you can use the following link.

 <div style='padding:15px'>
 <a href="https://colab.research.google.com/github/rribeiro-sci/SSBtoolkit/blob/main/SSBtoolkit-Tutorial1.ipynb" target="_blank">
 <img alt="Colab" src="https://res.cloudinary.com/djz27k5hg/image/upload/v1637335713/badges/colab-badge_hh0uyl.svg" height="25" style="margin:20px">
 </a>

 </div>

 ## Setup

 To run the SSBtoolkit within Google Colab, you'll need to run the following installation commands. You can of course run this tutorial locally if you prefer.


 <span style="color:black"> ⚠️ WARNING: this notebook is prepared to run on linux machines. If you intend to run it <b>locally</b> on a different OS (MacOS or Windows) you have to set the BioNetGen environment path manually. Running directly on Google colab is OS independent.</span>

 %% Cell type:markdown id:f0984b4a tags:

 ## Install Dependencies

 %% Cell type:markdown id:bc7afa75 tags:

 ### Install on SSB toolkit on Google Colab

 %% Cell type:code id:d7c956eb tags:

 ``` python
 #@title Install dependencies
 %%bash

 # download SSB source code and install dependencies
 if [ ! -d "SSBtoolkit/" ]; then
  git clone https://github.com/rribeiro-sci/SSBtoolkit.git --quiet
  pip install -r SSBtoolkit/requirements.txt
 fi
 ```

 %% Cell type:code id:73b58794 tags:

 ``` python
 cd SSBtoolkit
 ```

 %% Cell type:markdown id:0d2bec33 tags:

 ### Import Dependencies

 %% Cell type:code id:e344d8de tags:

 ``` python
 #Import Python dependencies
 import os, sys, json, math, site
 import numpy as np
 import pandas as pd
 import seaborn as sns
 import matplotlib.pyplot as plt

 from sklearn.linear_model import LinearRegression

 from src.lib.ssbtoolkit import convert, get, simulation
 ```

 %% Cell type:code id:c123810d tags:

 ``` python
 #Setting BioNetGen environment path
 distpath = site.getsitepackages()[0]
 BioNetGen=os.path.join(distpath, 'bionetgen/bng-linux:')
 mypath=%env PATH
 newpath=BioNetGen+mypath
 %env PATH=$newpath
 ```

 %% Cell type:code id:66d54bde tags:

 ``` python
 #Test bioservices
 from bioservices import UniProt
 u = UniProt(verbose=False)
 ```

 %% Cell type:markdown id:ec421692 tags:

 ## Load experimental data

 %% Cell type:markdown id:184abec2 tags:

 Once the SSBtoolkit environment is set up we are ready to start to simulate.

 We will begin by loading the affinity data of some selective agonists of the Adenosine 2A receptor. The experimental affinity data was taken from *([Varani, K. et al., 2015](https://doi.org/10.1021/acs.jmedchem.5b00215))*. This data can be found in `examples/data.csv`.

 %% Cell type:code id:be92204e tags:

 ``` python
 data = pd.read_csv('example/A2AR_binding_data.csv')
 data
 ```

 %% Cell type:markdown id:b75c81c0 tags:

 Commonly, the experimental affinity values come in different "flavors".

 The SSB framework just accepts affinity values as pK<sub>d</sub>. Since the affinity values in our data set is repported as K<sub>i</sub> and EC<sub>50</sub> and we need to convert them to pK<sub>i</sub> and pEC<sub>50</sub> repectively.

 %% Cell type:code id:b26bfc66 tags:

 ``` python
 data['pKi'] = data.Ki.apply(lambda x: -np.log10(x*1E-6))
 data['pEC50']=data.EC50.apply(lambda x: -np.log10(x*1E-6))
 data
 ```

 %% Cell type:markdown id:05c44c9d tags:

 ## Selection of the signaling pathway

 The core of the SSB framework is, naturally, the mathematical models of the GPCRs' signaling pathways.

 Since G-protein sub-families are classified by their $\alpha$ subunits, this classfication as been served to identify their signaling pathways:
 * G<sub>s</sub>
 * G<sub>i/o</sub>
 * G<sub>q/11</sub>
 * G<sub>12/13</sub>

 📖 See [The SSB toolkit](https://github.com/rribeiro-sci/SSBtoolkit/blob/main/docs/ssb_toolkit.md) documentation for more details.

 We can define manualy the G$\alpha$ pathway we want to work with, or simply query our internal database of human GPCR pathways using the UNIPROT id of our receptor using the SSBtoolkit built-in function `get.gprotein()`. The UNIPROT id for the human Adenosine A2 receptot is [P29274](https://www.uniprot.org/uniprot/P29274).

 %% Cell type:code id:a6d7dcb1 tags:

 ``` python
 uniprotID = 'P29274'
 gprotein = get.gprotein(uniprotID)
 gprotein
 ```

 %% Cell type:markdown id:9393b0cb tags:

 <span style="color:black">⚠️ WARNING: our toolkit was specifically design for human GPCRs. The quering for pathways for GPCRs other than Human may be included in the future. However, if you want to study a non-human GPCR you can still use the SSB toolkit by setting manually the G$\alpha$ pathway.</span>

 %% Cell type:markdown id:b555bc6f tags:

 ##  Preparation, Simulation and Analysis

 To obtain a dose-response curve from the simulation of signaling pathways, individual simulations of the pathway according to a series of ligand concentrations must be performed (as it would be done in the wet-lab).

 To define an array of ligand concentrations we will use a geometric progression. The reason why we use a geometric progression is due to the impact of the dilution fraction on the accuracy of K<sub>d</sub> and EC<sub>50</sub>/IC<sub>50</sub> values experimentally estimated. This factor, that defines the spacing between the adjacent concentration values, has an impact on the concentration values that are on the linear portion of the curve. Therefore, using a geometric progression we can mimic the experimental conditions where each concentration equals to the power of 2 of the previous lowest concentration *([Sebaugh, J.L., 2011](https://doi.org/10.1002/pst.426))*

 <span style="color:black"> ⚠️ WARNING: the SSB toolkit uses μM as default concentration units.</span>

 %% Cell type:code id:252c3fe8 tags:

 ``` python
 # setting the range of ligand concentrations
 lig_conc_min = 1E-4 # μM
 lig_conc_max = 1E4  # μM
 lig_conc_range = np.geomspace(lig_conc_min, lig_conc_max, 20) # 20 concentration values
 ```

 %% Cell type:code id:a4cf0857 tags:

 ``` python
 lig_conc_range
 ```

 %% Cell type:markdown id:0dbc3673 tags:

 SSB simulations are also sensible to the concentration of the protein, wich must be, again, in <b><i>μM</i></b>. However, the  concentration values reported in functional assays comes, commonly, in <b><i>μg</i></b> of protein.

 The experimental data we are using was obtained from a functional assay using 50 <b><i>μg</i></b> of protein. We can use the SSBtoolkit built-in function `convert.microgr2nanomolar()` to convert  <b><i>μg</i></b> of protein in <b><i>μM</i></b>.

 %% Cell type:code id:ca0b4a08 tags:

 ``` python
 # the following function takes as input the UniProtID and the concentration in μg.
 prot_conc = convert.microgr2nanomolar(uniprotID, 50)
 print(prot_conc, 'μM')
 ```

 %% Cell type:markdown id:8f795fe7 tags:

 Finnaly, we need to define the length and number of time steps (resolution) of the simulation.

 %% Cell type:code id:4cdacd1a tags:

 ``` python
 time = 10000  # time of simulation in seconds
 nsteps = 1000   # number of time steps
 ```

 %% Cell type:markdown id:ba2bc317 tags:

 ## Integration of ODEs

 After having defined all the simulation parameters we are ready to proceed with the simulations. A simulation of a methamatical model of a signaling pathway consists of the integration of a set of ordinary differential equations (ODEs) as function of time. Since each ODE represents a molecular event of the signaling pathway, when integrated over time, such equations can describe how the concentration of species inside the model changes over time. The key point of this tutorial is the use of the drug-receptor affinity value (K<sub>d</sub>) to fire up the model. With the K<sub>d</sub> values one can calculate the fraction of receptors that are occupied by the ligand in the equilibrium and, according to the *occupancy theory*, the fraction of occupied receptors represents the concentration of activated receptors in the equilibrium *([Kenakin T., 2004 ](https://doi.org/10.1016/j.tips.2004.02.012))*. 📖 Read the [Docs](https://github.com/rribeiro-sci/SSBtoolkit/blob/main/docs/ssb_toolkit.md) for more details.


 In this tutorial we want to simulate dose-response curves of agonists towards Adenosine A2 receptor, so, we will use the SSBtoolkit built-in class `simulation.activation()`.


 <span style='color:black'>ℹ️ If you want study antagonists follow the tutorial [Simulation of dose-responses curves of antagonists](https://github.com/rribeiro-sci/SSBtoolkit/blob/main/SSBtoolkit_Tutorial2.ipynb).</span>

 %% Cell type:code id:5b3bf63d tags:

 ``` python
 # we will start by creating a simulation instance.
 sim = simulation.activation()
 ```

 %% Cell type:code id:c1ae3b1f tags:

 ``` python
 # configuration of simulation parameters
 sim.SetSimulationParameters(ligands=data.id.to_list()[:2],
                            affinities=data.pKi.to_list()[:2],
                            pathway=gprotein,
                            receptor_conc=prot_conc,
                            lig_conc_range=lig_conc_range,
                            ttotal=time,
                            nsteps=nsteps,
                            binding_kinetics=False)
 ```

 %% Cell type:code id:5f8df280 tags:

 ``` python
 #Start the simulation
 sim.Run()
 ```

 %% Cell type:markdown id:697afeef tags:

 In the end, the concentration values of the species of the signaling pathway over the simulation time will be saved inside the instance.

 The response of a signaling pathway is, naturally, represented by the increase or decrease of one of the species described by the model. So, to predict the dose-response curve we need, firstly, to extract the maximum concentration value orbserved for one specie from each individual simulation (from the series of simulations for each ligand concentration). Then, such values will be fitted to a logistic regression.

 To achieve this, we will use the analysis function:

 %% Cell type:code id:8b21a9a2 tags:

 ``` python
 sim.Analysis()
 ```

 %% Cell type:markdown id:37fb6a47 tags:

 We can now to plot the dose-response curves:

 %% Cell type:code id:6aeba621 tags:

 ``` python
 sim.Curve()
 ```

 %% Cell type:markdown id:5291e364 tags:

 Finnaly, from the dose-response curves we can interpolate the EC<sub>50</sub> values.

 %% Cell type:code id:dcc07180 tags:

 ``` python
 sim.Potency()
 ```

 %% Cell type:markdown id:561e9437 tags:

 💡 The potency predicted values can be exported as a python dictionary using the function `sim.PotencyToDict()` or saved in a csv file: `sim.PotencyToCSV()`.

 %% Cell type:markdown id:e9076090 tags:

 ## Save results on Google Drive

 %% Cell type:code id:00a87ac7 tags:

 ``` python
 from google.colab import drive
 drive.mount('/gdrive')
 ```

 %% Cell type:code id:6cea1600 tags:

 ``` python
 sim.PotencyToCSV(path='/gdrive/MyDrive/XX') ## change XX accordingly.
 ```

 %% Cell type:markdown id:ee42b0a5 tags:

 ## Congratulations!

 Congratulations on completing this tutorial notebook! If you enjoyed working through the tutorial, and want to continue working with SSBtoolkit, we encourage you to finish the rest of the tutorials in this series.

 ## Cite Us

 If you use or adapt this tutorial for your own research projects please cite us.

 ```
 @article{XXX,
    title={XXX},
    author={XXX},
    publisher={XXX},
    note={\url{XXX}},
    year={XXX}
 }
 ```



 ## Acknowledgments

 EU Human Brain Project (SGA1 and SGA2): This open source software was developed in part in the Human Brain Project funded from the European Union's Horizon 2020 Framework Programme for Research and Innovation under Specific Grant Agreements No 720270 and No. 78907 (Human Brain Project SGA1 and SGA2).

 <div style="padding-bottom:50px">
 <img src="https://res.cloudinary.com/djz27k5hg/image/upload/v1637657234/logos/HBP_horizontal_logo_qtcyzn.png" width="300" align='left' style="margin-left:50px">
    <img src="https://res.cloudinary.com/djz27k5hg/image/upload/v1642677502/logos/COFUNDED_EU_j2ktlp.jpg" width="300" align='left' style="margin-left:50px">
 </div>
+
+%% Cell type:code id:690b7ff2 tags:
+
+``` python
+```

--- a/docs/_static/custom.css
+++ b/docs/_static/custom.css
+.wy-side-nav-search, .wy-nav-top {
+    background: #EFEFEF;
+
+}
+/* Text inside search */
+.wy-side-nav-search input[type=text] {
+    color: #000000;
+}
+
+
+/* Home button */
+.wy-side-nav-search > a {
+    color: #555753;
+    font-size: 25px;
+}
\ No newline at end of file
--- a/docs/apidocs.rst
+++ b/docs/apidocs.rst
 API Documentation
 =================
-
 .. automodule:: ssbtoolkit
   :members:
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -53,4 +53,6 @@ pygments_style = 'sphinx'
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-#html_static_path = ['_static']
+html_static_path = ['_static']
+
+#html_css_files = ["custom.css"]
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -46,6 +46,53 @@ protocols.
   apidocs
   faq

+\
+
+\ 
+
+Availability and License
+========================
+The source code is freely available at https://github.com/rribeiro-sci/SSBtoolkit under
+the Apache 2.0 license. Tutorial notebooks containing minimal working examples can be found at https://github.com/rribeiro-sci/SSBtoolkit.
+
+\
+
+\ 
+
+Developed by
+============
+.. image:: _static/FZJ_logo.svg
+  :width: 200
+
+\
+
+\ 
+
+Funded by
+=========
+.. image:: https://res.cloudinary.com/djz27k5hg/image/upload/v1637657234/logos/HBP_horizontal_logo_qtcyzn.png
+  :width: 200
+  :alt: Alternative text
+  
+Citation |DOI for Citing pyGOMoDo|
+==================================
+
+pyGOMoDo is research software. If you make use of pyGOMoDo in scientific
+publications, please cite it. The BibTeX reference is
+
+::
+
+    @article{,
+        title = {},
+        author = {},
+        journal = {},
+        volume = {},
+        number = {},
+        pages = {},
+        year = {},
+        doi = {}
+    }
+

 Indices and tables
 ==================