CNORode2017

This is a modified version of CNORode which is an add-on to CellNOptR. We refer to the vignette for learning usage of CNORode, and we will describe here below only added features. For more general information about the CellNOpt project visit: http://www.cellnopt.org/.

How to install

CNORode2017 requires CellNOptR and MEIGOR which are available in Bioconductor and can be installed typing:

if (!requireNamespace("BiocManager", quietly=TRUE))
    install.packages("BiocManager")
BiocManager::install("CellNOptR")
BiocManager::install("MEIGOR")

CNORode2017 can be installed typing:

library(devtools)
install_github("saezlab/CNORode2017")

Note that libraries should be loaded in this exact order:

library(CellNOptR)
library(MEIGOR)
library(CNORode2017)

This is because CNORode is a dependency of MEIGOR and has same function names as CNORode2017, so original CNORode functions will be prioritized when calling the optimisation function if MEIGOR (and thus CNORode) is loaded after CNORode2017.

Basic info on logic based ODE and CNORode

For an introduction on logic based ODE we recommend reading the original publication (Wittmann et al., BMC Syst Biol., 2009). Briefly, logic based ODE are ordinary differential equations (ODE) derived from logic rules using continuous update function (B_i), which allows to have a continuous description of the behaviour of the species of interest both in time and in state. Each species x_i is described by an ODE:

d(x_i)/dt=τ_i(B_i(f(x_i1), f(x_i2), ..., f(x_iN))-x_i)

where τ_i is the life-time of the species and x_i1, x_i2, ... x_iN are its N regulators. Each regulation is described by a transfer function f(x_ij) which can be, for example, a linear relationsip or a sigmoidal (Hill like) curve.

New features of CNORode2017

Differences with respect to the original CNORode package are described below. All new features can be used in the parEstimationLBode() function for parameters estimation and can be passed using the paramsSSm argument (can be used only when using essm method):

# sets optimisation parameters to default values
paramsSSm=defaultParametersSSm()
# passed to parameter estimation function as follows
opt_pars=parEstimationLBode(cnolist,model, method="essm", ode_parameters=ode_parameters, paramsSSm=paramsSSm)

Using default paramsSSm should get to the same results as the original CNORode.

1. New transfer function

A new transfer function f(x_ij) was introduces to have a more straightforward interpretability of the parameters in terms of functionality of the edges. For the previously implemented transfer functions we refer to (Wittmann et al., BMC Syst Biol., 2009) and (Terfve et al., BMC Syst Biol, 2012). The new transfer function is characterized by two parameters (k_ij and n_ij) and mantains the previously introduced sigmoidal shape, but allows to describe the case of "no regulation" when parameter k_ij=0. For fixed n_ij, increasing values of k_ij correspond to increasing strength of the regulation.

Previously implemented transfer functions are passed as numberes: 1 (linear), 2 (Hill) and 3 (Normalised Hill). The new transfer function has been assigned value 4 and can be passed as paramsSSm argument as follows:

# use new transfer function (see help for other transfer functions)
paramsSSm$transfer_function=4

Same when running the simulation:

simulatedData=plotLBodeFitness(cnolist, model, transfer_function=4, ode_parameters=opt_pars)

2. L1 regularisation

A penalty term proportional to the L1-norm of the parameters has been added to the objective function in order to induce sparsity in the network. The balance between prioritising good fit or sparse model is regulated by a tunable term λ which can be empirically selected testing the effect of different values on model fit and model sparsity. A regularisation factor λ can be assigned separately to parameters τ_i and k_ij as follows:

# for parameters tau
paramsSSm$lambda_tau=0.01
# for parameters k
paramsSSm$lambda_k=0.001

3. Steady state penalty

An additional penalty term can be considered in the objective function to penalise parameter sets for which the simulation does not reach steady state within the time range of the measured experimental data. This is especially recommended to match biological assumptions when only few time points are available in the experimental data and have been chosen considering that the biological system under investigation have reached a semi steady state. A different (typically higher) penalty can be given to the control (unperturbed) condition in order to favour that the system remains at basal condition when no perturbations are applied.

# steady state penalty
paramsSSm$SSpenalty_fac=10
# additional penalty for control condition (assumed to be first row of MIDAS)
paramsSSm$SScontrolPenalty_fac=1000

4. Bootstrap

This feature allows to perform the optimisation with random resampling (with replacement) of the experimental data. With default option for boot_seed, a random seed for the random sampling is selected each time the optimisation is run, but the seed can also be provided as user input.

# select bootstrapping option
paramsSSm$bootstrap=TRUE
# default random assignment of the seed for random sampling
paramsSSm$boot_seed=sample(1:10000,1)

When using the bootsrap, the user should repeat the optimisation multiple times (recommended at least 100) to derive a bootstrapped distribution of the estimated parameters. Here below a simple code that can be used for small networks, while for medium or large networks parallelisation (preferably on cluster) is strongly recommended.

# 100 bootstrap repetitions
opt_pars<-lapply(seq(1:100), function(x){
  paramsSSm$boot_seed=x
  parEstimationLBode(cnolist, model, method="essm", ode_parameters=ode_parameters, paramsSSm=paramsSSm)
})

Summary of new/modified arguments for paramsSSm

Name	Default	Suggested	Description
transfer_function	3	4	Defines which transfer function (f(x_ij)) to use. Default (transfer_function=3) is Normalised Hill. New transfer function is transfer_function=4.
lambda_tau	0	0.0001-0.1	Regularisation factor λ_τ to be used for parameters τ_i.
lambda_k	0	0.0001-0.1	Regularisation factor λ_k to be used for parameters k_ij.
SSpenalty_fac	0	10	Penalty factor for not reaching steady state within time range of experimental data
SScontrolPenalty_fac	0	1000	Penalty factor for not reaching steady state for control (unperturbed) condition. Control condition is assumed to be in the first row of the MIDAS or CNOlist.
bootstrap	FALSE		If bootstrap=TRUE experimental data used in the optimisation are randomly sampled with replacement. If this option is selected the optimisation should be repeated multiple times (≥ 100) to obtain a distribution of the estimated parameters.
boot_seed	sample(1:10000,1)		Seed to be used for random sampling if bootstrap=TRUE.

Example

A working example is available here and data and network (PKN) used are available in the same repository (https://github.com/saezlab/CPT_QSPtutorial).

Reference

The described additions to the CNORode package have been developed for the following paper:

F. Eduati, V. Doldàn-Martelli, B. Klinger, T. Cokelaer, A. Sieber, F. Kogera, M. Dorel, M. J Garnett, N. Blüthgen, J. Saez-Rodriguez. Drug resistance mechanisms in colorectal cancer dissected with cell type-specific dynamic logic models. Cancer Research, 2017. Published OnlineFirst 7 April. DOI: 10.1158/0008-5472.CAN-17-0078

Here the link to PKN and data used in the publication. Other analysis used for the publication are also available in the same repository.

saezlab / CNORode2017