Tutorials

Tutorial¶

This tutorial will walk you through the process of getting started with the useage of different tools to operate with Systems biology models. It includes installation instructions, a quick start guide, and an overview of how to integrate and use the tool in your projects.

Install aiagents4pharma¶

To begin, you need to install the aiagents4pharma package, which includes the search_models tool for querying biological models.

Use the following command to install the package via pip:

In [103]:

# !pip install aiagents4pharma 
#This will install the aiagents4pharma library and all its dependencies.

# !pip install aiagents4pharma #This will install the aiagents4pharma library and all its dependencies.

Set up your API key¶

Before using the model tools, you need to authenticate using an API key. You can either store the API key in an environment variable or set it directly in your notebook/script.

Option 1 : Retrieve API Key from Environment Variable¶

In [104]:

import os
import openai 

# Retrieve API key from environment variable
openai.api_key = os.getenv("OPENAI_API_KEY")

import os import openai # Retrieve API key from environment variable openai.api_key = os.getenv("OPENAI_API_KEY")

Option 2: Store API Key Directly in the Script (Temporary)¶

In [ ]:

import os

os.environ["OPENAI_API_KEY"] = "your_api_key"
# Make sure to replace "your_api_key" with your actual API key.

import os os.environ["OPENAI_API_KEY"] = "your_api_key" # Make sure to replace "your_api_key" with your actual API key.

Once you have the package installed and the API key set up, you can start using the model tools to query biological models. Here's how you can get started quickly:

Invoke the search_models Tool¶

1. Import Required Packages

   This imports the SearchModelsTool class from the aiagents4pharma package.

In [106]:

# Import the `SearchModelsTool` class from search_models.py
from aiagents4pharma.talk2biomodels.tools.search_models import SearchModelsTool

# Import the `SearchModelsTool` class from search_models.py from aiagents4pharma.talk2biomodels.tools.search_models import SearchModelsTool

2. Initialize the Search Models Tool

   This creates an instance of the SearchModelsTool which you will use to search for biological models.

In [107]:

# Initialize the SearchModelsTool
search_tool = SearchModelsTool()

# Initialize the SearchModelsTool search_tool = SearchModelsTool()

3. Run the Search Models Tool

   In this example, we are searching for models related to Crohn's disease. You can replace the query with any disease or biological term you're interested in.

In [108]:

# Define the search query as follows
query = "crohn's disease"

# Run the tool with the query
search_results = search_tool.invoke(input={"query": query})

# Define the search query as follows query = "crohn's disease" # Run the tool with the query search_results = search_tool.invoke(input={"query": query})

4. Display the Results

   To view the results, simply print them

   The search results will be displayed in a table format containing the Model ID, Model Name, Format, and Submission Date.

In [109]:

print(search_results)

print(search_results)

| #  | BioModel ID                                          | BioModel Name                                                                                                   | Format | Submission Date |
|----|------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------|--------|------------------|
| 1  | [BIOMD0000000534](https://www.ebi.ac.uk/biomodels/BIOMD0000000534) | Dwivedi2014 - Healthy Volunteer IL6 Model                                                                     | SBML   | 2014-08-04       |
| 2  | [BIOMD0000000535](https://www.ebi.ac.uk/biomodels/BIOMD0000000535) | Dwivedi2014 - Crohns IL6 Disease model - Anti-IL6 Antibody                                                   | SBML   | 2014-08-04       |
| 3  | [BIOMD0000000536](https://www.ebi.ac.uk/biomodels/BIOMD0000000536) | Dwivedi2014 - Crohns IL6 Disease model - sgp130 activity                                                     | SBML   | 2014-08-04       |
| 4  | [BIOMD0000000537](https://www.ebi.ac.uk/biomodels/BIOMD0000000537) | Dwivedi2014 - Crohns IL6 Disease model - Anti-IL6R Antibody                                                  | SBML   | 2014-08-04       |
| 5  | [MODEL1109130000](https://www.ebi.ac.uk/biomodels/MODEL1109130000) | Thiele2013 - Human metabolism global reconstruction (Recon 2)                                                 | SBML   | 2011-09-12       |
| 6  | [MODEL1311110000](https://www.ebi.ac.uk/biomodels/MODEL1311110000) | Smallbone2013 - Human metabolism global reconstruction (recon 2.1)                                            | SBML   | 2013-11-11       |
| 7  | [MODEL1311110001](https://www.ebi.ac.uk/biomodels/MODEL1311110001) | Smallbone2013 - Human metabolism global reconstruction (recon 2.1x)                                           | SBML   | 2013-11-11       |
| 8  | [MODEL1703310000](https://www.ebi.ac.uk/biomodels/MODEL1703310000) | MODEL1703310000_url.xml                                                                                       | SBML   | 2017-03-30       |
| 9  | [MODEL2001290001](https://www.ebi.ac.uk/biomodels/MODEL2001290001) | AhmedMobeen2021 - NF-kB Activation Model                                                                       | SBML   | 2020-01-29       |
| 10 | [MODEL2101150001](https://www.ebi.ac.uk/biomodels/MODEL2101150001) | Corral2021 - Interplay between SMAD2 and STAT5A regulating IL-17A/F expression in Th cells.                   | SBML   | 2021-01-15       |

Invoke the model_description tool¶

1. Import Required Modules

   The purpose of this step is to import the necessary classes to work with biological models. The ModelDescriptionTool is used to query and retrieve information about a biological model, and ModelData is a helper class to provide the model's details like its ID or file path. These imports are essential for interacting with the tool.

In [110]:

from aiagents4pharma.talk2biomodels.tools.model_description import ModelDescriptionTool,ModelData

from aiagents4pharma.talk2biomodels.tools.model_description import ModelDescriptionTool,ModelData

2. Initialize the Tool

   This step initializes the ModelDescriptionTool, which will allow you to interact with the BioModels database. It sets up the tool to process your questions and fetch the relevant answers from the specified model.

In [111]:

tool = ModelDescriptionTool()

tool = ModelDescriptionTool()

3. Define the Model Data

   The purpose of defining the model data is to specify the biological model you want to work with. By providing the modelid, you indicate which model from the BioModels database the tool should analyze. Alternatively, you can use the sbml_file_path to load a local SBML file, but here we focus on using a BioModels ID.

In [112]:

model_data = ModelData(
    modelid=537,  # Use a valid BioModels ID
    sbml_file_path=None
)

model_data = ModelData( modelid=537, # Use a valid BioModels ID sbml_file_path=None )

4. Prepare Input, Invoke the Tool, and Display the Result

   In this step, you define a question about the biological model and link it to the specified model data. The input is processed by the tool's invoke method, which retrieves the relevant information, and the response is displayed, providing a clear answer to your query

In [113]:

input_data = {
    "question": "What biological processes does this model simulate?",
    "sys_bio_model": model_data
}
response = tool.invoke(input=input_data)
print("Response:", response)

input_data = { "question": "What biological processes does this model simulate?", "sys_bio_model": model_data } response = tool.invoke(input=input_data) print("Response:", response)

None st_session_key
Response: This model simulates the interleukin-6 (IL-6)-mediated immune regulation in Crohn's disease. Specifically, it integrates intracellular signaling with organ-level dynamics of pharmacological markers underlying the disease. The model focuses on the differential activity of ligands on the signaling of IL-6, which in turn affects the Signal Transducer and Activator of Transcription 3 (STAT3) activity leading to the production of the biomarker C-Reactive Protein (CRP) expression.

As you can see, the query's answer is displayed in a clear and well-structured format.

Invoke the simulate_model tool¶

Simulation allows us to run virtual experiments on biological systems. Instead of conducting physical experiments in the lab, we can use computational models to predict how a system behaves under specific conditions.

Let's simulate a virtual patient with a CRP value of 100 and observe the results over time

1. Import Required Packages

In [114]:

from aiagents4pharma.talk2biomodels.tools.simulate_model import SimulateModelTool,TimeData,SpeciesData,TimeSpeciesNameConcentration
import streamlit as st

from aiagents4pharma.talk2biomodels.tools.simulate_model import SimulateModelTool,TimeData,SpeciesData,TimeSpeciesNameConcentration import streamlit as st

SimulateModelTool: The main tool for running model simulations.

TimeData, SpeciesData, TimeSpeciesNameConcentration: Helper classes to define time, species, and recurring data.

streamlit: A Python library for building web applications, used here to manage session data and visualize results.

2. Initialize the Tool

   Create an instance of the SimulateModelTool.

In [115]:

st.session_state["test_key"] = None

st.session_state["test_key"] = None

2024-12-10 15:44:56.926 Thread 'MainThread': missing ScriptRunContext! This warning can be ignored when running in bare mode.
2024-12-10 15:44:56.929 Thread 'MainThread': missing ScriptRunContext! This warning can be ignored when running in bare mode.

st.session_state: Stores data during the session. Here, we initialize it with a key (test_key) to save simulation results.

In [116]:

simulate_tool = SimulateModelTool(return_direct=True,st_session_key="test_key")

simulate_tool = SimulateModelTool(return_direct=True,st_session_key="test_key")

simulate_tool: Initializes the simulation tool and links it to the Streamlit session using st_session_key.

3. Define the Input Data

   Define the input data for the simulation in a structured format. You'll provide the model data, time data, species data, and recurring events (if any).

In [117]:

# Define time data
model_data=ModelData(
        modelid= 537,  # Use a valid BioModels ID
        sbml_file_path=None
)
time_data = TimeData(
    duration=10.0,  # Duration of the simulation
    interval=1000     # Interval between time steps
)

# Define species data
species_data = SpeciesData(
    species_name=["CRP{serum}"],
    species_concentration=[100.0]
)

# Define recurring data
new_data = [
    TimeSpeciesNameConcentration(time=5.0, species_name="CRP{serum}", species_concentration=100.0)
]

# Define time data model_data=ModelData( modelid= 537, # Use a valid BioModels ID sbml_file_path=None ) time_data = TimeData( duration=10.0, # Duration of the simulation interval=1000 # Interval between time steps ) # Define species data species_data = SpeciesData( species_name=["CRP{serum}"], species_concentration=[100.0] ) # Define recurring data new_data = [ TimeSpeciesNameConcentration(time=5.0, species_name="CRP{serum}", species_concentration=100.0) ]

In this simulation, we initially set the concentration of CRP[serum] to 100 at the timestamp 5.0.

4. Run the Simulation Using invoke

   Now, run the simulation using the invoke method. This method will use the structured input data to execute the simulation.

In [118]:

reponse = simulate_tool.invoke(input ={
    "model_data": {"modelid" : model_data.modelid},
    "time_data": {"duration" : time_data.duration,
                    "interval" : time_data.interval},
    "species_data" : {"species_name" : species_data.species_name,
                    "species_concentration" : species_data.species_concentration},
    "recurring_data"  : {"data": new_data}
    })

reponse = simulate_tool.invoke(input ={ "model_data": {"modelid" : model_data.modelid}, "time_data": {"duration" : time_data.duration, "interval" : time_data.interval}, "species_data" : {"species_name" : species_data.species_name, "species_concentration" : species_data.species_concentration}, "recurring_data" : {"data": new_data} })

2024-12-10 15:44:56.968 Thread 'MainThread': missing ScriptRunContext! This warning can be ignored when running in bare mode.
2024-12-10 15:44:56.971 Thread 'MainThread': missing ScriptRunContext! This warning can be ignored when running in bare mode.
2024-12-10 15:44:58.970 Thread 'MainThread': missing ScriptRunContext! This warning can be ignored when running in bare mode.
2024-12-10 15:44:58.970 Thread 'MainThread': missing ScriptRunContext! This warning can be ignored when running in bare mode.

5. Display the Results

   Finally, display the simulation results in the Jupyter notebook using print.

In [119]:

df =st.session_state["test_key"].simulation_results
# Retrieve and display simulation results from st.session_state

df =st.session_state["test_key"].simulation_results # Retrieve and display simulation results from st.session_state

2024-12-10 15:44:59.312 Thread 'MainThread': missing ScriptRunContext! This warning can be ignored when running in bare mode.

In [120]:

df_ = df[["Time","CRP[serum]"]]
# For example, the  rows of CRP concentration can be shown

df_ = df[["Time","CRP[serum]"]] # For example, the rows of CRP concentration can be shown

In [121]:

df[(df_["Time"]>=5)&(df_["Time"]<=5.05)][["Time","CRP[serum]"]]

df[(df_["Time"]>=5)&(df_["Time"]<=5.05)][["Time","CRP[serum]"]]

Out[121]:

	Time	CRP[serum]
500	5.00	200.458221
501	5.01	101.589706
502	5.02	103.145120
503	5.03	104.666835
504	5.04	106.155623
505	5.05	107.612282

When we examine the results within the time range between 5.0 and 5.05, we can observe a gradual increase in the concentration values.

This increase reflects how the concentration dynamically evolves after the timestamp 5.0 as the system resets or recalculates values for each subsequent timestep (e.g., 5.01, 5.02, etc.).

Invoke the ask_question tool¶

1. Import Required Packages

   Ensure that the required package (aiagents4pharma) is installed and imported correctly.

In [122]:

from aiagents4pharma.talk2biomodels.tools.ask_question import AskQuestionTool, AskQuestionInput

from aiagents4pharma.talk2biomodels.tools.ask_question import AskQuestionTool, AskQuestionInput

2. Initialize the Tool

   Create an instance of the AskQuestionTool.

In [123]:

ask_question_tool = AskQuestionTool(return_direct=True,st_session_key="test_key")

ask_question_tool = AskQuestionTool(return_direct=True,st_session_key="test_key")

3. Define the Input Question

   Define the input question in the required structure.

In [128]:

# Prepare the input for invoking the tool
input_data = {
    "question": "What is the concentration of CRP[serum] at time 5?",
    "sys_bio_model": "simulation_results"
}

# Prepare the input for invoking the tool input_data = { "question": "What is the concentration of CRP[serum] at time 5?", "sys_bio_model": "simulation_results" }

4. Use invoke

   Now, use the invoke method to get the answer to the question.

In [129]:

# Invoke the tool and get the response
response_ = ask_question_tool.invoke( input=input_data)

# Invoke the tool and get the response response_ = ask_question_tool.invoke( input=input_data)

2024-12-10 15:45:19.583 Thread 'MainThread': missing ScriptRunContext! This warning can be ignored when running in bare mode.
2024-12-10 15:45:19.586 Thread 'MainThread': missing ScriptRunContext! This warning can be ignored when running in bare mode.
2024-12-10 15:45:19.587 Thread 'MainThread': missing ScriptRunContext! This warning can be ignored when running in bare mode.
2024-12-10 15:45:19.588 Thread 'MainThread': missing ScriptRunContext! This warning can be ignored when running in bare mode.
2024-12-10 15:45:19.589 Thread 'MainThread': missing ScriptRunContext! This warning can be ignored when running in bare mode.
2024-12-10 15:45:19.590 Thread 'MainThread': missing ScriptRunContext! This warning can be ignored when running in bare mode.
2024-12-10 15:45:19.598 Thread 'MainThread': missing ScriptRunContext! This warning can be ignored when running in bare mode.
2024-12-10 15:45:19.600 Thread 'MainThread': missing ScriptRunContext! This warning can be ignored when running in bare mode.

5. Display the Answer

   Finally, display the answer in the Jupyter notebook.

In [130]:

# Print the response
print(response_)

# Print the response print(response_)

The concentration of CRP[serum] at time 5 is 200.458221.

In [133]:

df[(df_["Time"]>=5)&(df_["Time"]<=5.05)][["Time","CRP[serum]"]]

df[(df_["Time"]>=5)&(df_["Time"]<=5.05)][["Time","CRP[serum]"]]

Out[133]:

	Time	CRP[serum]
500	5.00	200.458221
501	5.01	101.589706
502	5.02	103.145120
503	5.03	104.666835
504	5.04	106.155623
505	5.05	107.612282

At the timestamp 5, the value obtained is 200.458221. Upon verification:

• The LLM's response matches this value accurately.
• The value is consistent with the corresponding entry in the dataframe (df) above.

This alignment confirms that the model is functioning correctly, as the tool's output is validated against the simulation results.