Skip to content

PhosKinTime overview - light mode PhosKinTime overview - dark mode

PhosKinTime Documentation

Welcome to the official documentation for PhosKinTime, an ODE-based modeling toolkit for phosphorylation kinetics and transcriptional time-series analysis. This index page provides an overview of each package and submodule in the project.

DOI

Acknowledgments

This project originated as part of my master's thesis work at Theoretical Biophysics group ( now, Klipp-Linding Lab), Humboldt Universität zu Berlin.

I am especially grateful to Ivo Maintz for his generous technical support, enabling seamless experimentation with packages and server setups.

  • The package is built on the shoulders of giants, leveraging the power of NumPy, SciPy, Matplotlib, and Pandas for numerical computations and data handling.
  • The package also utilizes Numba for JIT compilation, enhancing performance for computationally intensive tasks.
  • The package is designed to be compatible with Python >=3.10,<3.14 and is tested on various platforms, including Windows, macOS, and Linux.

Overview

PhosKinTime integrates:

  • Parameter estimation
  • Mechanistic ODE models (distributive, successive, random)
  • Steady-state computation
  • Morris sensitivity analysis
  • Static and interactive visualization
  • Modular design for extensibility

PhosKinTime uses ordinary differential equations (ODEs) to model phosphorylation kinetics and supports multiple mechanistic hypotheses, including:

  • Distributive Model: Phosphorylation events occur independently.
  • Successive Model: Phosphorylation events occur sequentially.
  • Random Model: Phosphorylation events occur in a random manner.

Modeling backends (local vs global)

PhosKinTime provides two complementary modeling stacks:

1) Local phosphorylation ODE models (per protein / per site)
These implement the classic mechanistic hypotheses (distributive, successive, random) and are optimized against phosphoproteomics time series. They are intended for detailed fitting of individual proteins or phosphorylation sites.

2) Global coupled signaling–GRN model (networkmodel)
This is a network-scale ODE system that couples kinase-driven phosphorylation dynamics to TF-mediated transcriptional regulation. It is intended for system-level simulations (e.g., global knockouts, functional influence propagation) and calibration against multi-omics time series.

For the full mathematical specification of the coupled global system (all equations), see: Global model documentation

Package mapping: - kinopt: optimization + post-processing for local phosphorylation models - tfopt: TF→mRNA constrained optimization and reporting - networkmodel: coupled kinase-signaling + GRN simulation and optimization wrappers

Typical workflows: - Local phosphorylation fitting: prep → kinopt → model → sensitivity → plotting - TF regulation fitting: prep → tfopt → reports - Global network simulation: prep → networkmodel → simulate → measure → KO analysis - Global network optimization: prep → networkmodel → optimize → measure → KO analysis

Core Modules

config

  • Holds global constants, CLI parsing, and logging setup.

models

  • Implements ODE systems for different phosphorylation hypotheses.

paramest

  • Parameter estimation routines for ODE models (currently using paramest/normest.py).

steady

  • Computes steady-state initial conditions for each model.

sensitivity

  • Morris sensitivity analysis for parameter sensitivity.

plotting

  • Visualization tools for plotting results.

utils

  • Helper functions for data loading, saving, and plotting.

Optimization Frameworks

kinopt

The kinopt package provides advanced optimization and post-processing:

evol

Global evolutionary optimization using pymoo (DE, NSGA-II):

  • Problem formulation, data construction, exporter for Excel and plots

local

Local constrained optimization using SciPy solvers (SLSQP, TRUST-CONSTR) with Numba-accelerated objectives

optimality

Post-optimization analysis: feasibility checks, sensitivity reporting, LaTeX table generation, diagnostic plots

fitanalysis

Additional fit-evaluation utilities for residual and performance analysis

tfopt

Originally implemented by Julius Normann.

This version has been modified and optimized by Abhinav Mishra.

The tfopt package estimates transcriptional regulation using mRNA and TF time-series data through constrained optimization.

evol

Global evolutionary optimization using pymoo (NSGA-II, AGEMOEA, SMSEMOA):

  • Multi-objective loss (fit error, α and β constraint violations)
  • Parallel evaluation, Excel export, and HTML/plot reports

local

Local constrained optimization using SciPy solvers (SLSQP):

  • Fast deterministic optimization under linear constraints
  • Numba-accelerated objectives, identical output and reports as evol

objfn

Shared objective logic and prediction functions for both backends

optcon

Data construction and constraint generation from TF–mRNA interaction files

utils

Input parsing, Excel + plot output, and HTML report generation

Command-Line Entry Point for the Phoskintime Pipeline

The phoskintime pipeline provides a command-line interface to execute various stages of the workflow,
including preprocessing, optimization, and modeling. Below are the usage instructions and examples for running
the pipeline.

Before running any commands, ensure you are in the working directory one level above the project root (where the project
directory is visible).

Run All Stages

Run the entire pipeline with the default (local) solver: 

python phoskintime all

Note: The all command runs prep → tfopt → kinopt → model only. It does not invoke the global network simulation (networkmodel). To run the global model, use the separate entry point: 

phoskintime-global
# or
python -m networkmodel.runner
The global model requires outputs from kinopt and tfopt as inputs. Run all (or the individual optimization stages) before invoking phoskintime-global.

Run Preprocessing Only

Execute only the preprocessing stage: 

python phoskintime prep

Run Transcription-Factor-mRNA Optimization (TFOPT)

Run TFOPT with the local solver: 

python phoskintime tfopt --mode local

Run TFOPT with the evolutionary solver: 

python phoskintime tfopt --mode evol

Run Kinase-Phosphorylation Optimization (KINOPT)

Run KINOPT with the local solver: 

python phoskintime kinopt --mode local

Run KINOPT with the evolutionary solver: 

python phoskintime kinopt --mode evol

Run the Model

Execute the modeling stage: 

python phoskintime model

Quick Start: Setting up environment

This guide provides clean setup instructions for running the phoskintime package on a new machine. Choose the scenario that best fits your environment and preferences.

Before proceeding, ensure you have the following prerequisites installed:

  • graphviz (for generating diagrams) 
# For Debian/Ubuntu
sudo apt-get install graphviz   

# For Fedora
sudo dnf install graphviz    

# For MacOS
brew install graphviz
  • python 3.10 or higher 
# Check python version 
python3 --version  

# If not installed, install python 3.10 or higher 

# For Debian/Ubuntu  
sudo apt-get install python3.10 

# For Fedora 
sudo dnf install python3.10 

# For MacOS
brew install python@3.10
  • git (for cloning the repository) 
# For Debian/Ubuntu 
sudo apt-get install git  

# For Fedora 
sudo dnf install git  

# For MacOS 
brew install git

Scenario 1: pip + virtualenv (Debian/Ubuntu/Fedora)

For Debian/Ubuntu

sudo apt update && sudo apt install -y python3 python3-pip python3-venv git

For Fedora

sudo dnf install -y python3 python3-pip python3-virtualenv git

Setup

git clone git@github.com:bibymaths/phoskintime.git
cd phoskintime

# Create and activate a virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install --upgrade pip
pip install -r requirements.txt

Scenario 2: Poetry + pyproject.toml

Install Poetry (all platforms)

curl -sSL https://install.python-poetry.org | python3 -
# Or: pip install poetry

Setup

git clone git@github.com:bibymaths/phoskintime.git
cd phoskintime

# Install dependencies
poetry install

# Optional: activate shell within poetry env
poetry shell

Scenario 3: Using uv (fast, isolated pip alternative)

Install uv

curl -LsSf https://astral.sh/uv/install.sh | sh

Setup

git clone git@github.com:bibymaths/phoskintime.git
cd phoskintime

# Create virtual environment and install deps fast
uv venv
source .venv/bin/activate
uv pip install -r requirements.txt

Scenario 4: Conda or Mamba (Anaconda/Miniconda users)

Setup

git clone git@github.com:bibymaths/phoskintime.git
cd phoskintime

# Create and activate conda environment
conda create -n phoskintime python=3.10 -y
conda activate phoskintime

# Install dependencies
pip install -r requirements.txt

Or if using pyproject.toml, add:

pip install poetry
poetry install

For making illustration diagrams, you need to install Graphviz. You can do this via conda or apt-get:

conda install graphviz

or

apt-get install graphviz

or download it from the Graphviz website. For macusers, you can use Homebrew:

brew install graphviz