mi_logreg_main: Estimate mutual information between discrete input and...

Description Usage Arguments Details Value References Examples

View source: R/mi_logreg_main.R

Description

The main wrapping function for basic usage of SLEMI package for estimation of mutual information. Firstly, data is pre-processed (all arguments are checked, observation with NAs are removed, variables are scaled and centered (if scale=TRUE)). Then basic estimation is carried out and (if testing=TRUE) diagnostic tests are computed. If output directory path is given (output_path is not NULL), graphs visualising the data and the analysis are saved there, together with a compressed output object (as .rds file) with full estimation results.

Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
mi_logreg_main(
  dataRaw,
  signal = "input",
  response = NULL,
  output_path = NULL,
  side_variables = NULL,
  pinput = NULL,
  formula_string = NULL,
  lr_maxit = 1000,
  MaxNWts = 5000,
  testing = FALSE,
  model_out = TRUE,
  scale = TRUE,
  TestingSeed = 1234,
  testing_cores = 1,
  boot_num = 10,
  boot_prob = 0.8,
  sidevar_num = 10,
  traintest_num = 10,
  partition_trainfrac = 0.6,
  plot_width = 6,
  plot_height = 4,
  data_out = FALSE
)

Arguments

dataRaw

must be a data.frame object

signal

is a character object with names of columns of dataRaw to be treated as channel's input.

response

is a character vector with names of columns of dataRaw to be treated as channel's output

output_path

is the directory in which output will be saved

side_variables

(optional) is a character vector that indicates side variables' columns of data, if NULL no side variables are included

pinput

is a numeric vector with prior probabilities of the input values. Uniform distribution is assumed as default (pinput=NULL).

formula_string

(optional) is a character object that includes a formula syntax to use in logistic regression model. If NULL, a standard additive model of response variables is assumed. Only for advanced users.

lr_maxit

is a maximum number of iteration of fitting algorithm of logistic regression. Default is 1000.

MaxNWts

is a maximum acceptable number of weights in logistic regression algorithm. Default is 5000.

testing

is the logical indicating if the testing procedures should be executed

model_out

is the logical indicating if the calculated logistic regression model should be included in output list

scale

is a logical indicating if the response variables should be scaled and centered before fitting logistic regression

TestingSeed

is the seed for random number generator used in testing procedures

testing_cores

- number of cores to be used in parallel computing (via doParallel package)

boot_num

is the number of bootstrap tests to be performed. Default is 10, but it is recommended to use at least 50 for reliable estimates.

boot_prob

is the proportion of initial size of data to be used in bootstrap

sidevar_num

is the number of re-shuffling tests of side variables to be performed. Default is 10, but it is recommended to use at least 50 for reliable estimates.

traintest_num

is the number of overfitting tests to be performed. Default is 10, but it is recommended to use at least 50 for reliable estimates.

partition_trainfrac

is the fraction of data to be used as a training dataset

plot_width

- basic dimensions (width) of plots, in inches

plot_height

- basic dimensions (height) of plots, in inches

data_out

is the logical indicating if the data should be included in output list

Details

In a typical experiment aimed to quantify information flow a given signaling system, input values x_1≤q x_2 …... ≤q x_m, ranging from 0 to saturation are considered. Then, for each input level, x_i, n_i observations are collected, which are represented as vectors

y^i_j \sim P(Y|X = x_i)

Within information theory the degree of information transmission is measured as the mutual information

MI(X,Y) = ∑_{i=1}^{m} P(x_i)\int_{R^k} P(y|X = x_i)log_2\frac{P(y|X = x_i)}{P(y)}dy,

where P(y) is the marginal distribution of the output. MI is expressed in bits and 2^{MI} can be interpreted as the number of inputs that the system can resolve on average.

In contrast to existing approaches, instead of estimating, possibly highly dimensional, conditional output distributions P(Y|X =x_i), we propose to estimate the discrete, conditional input distribution, P(x_i |Y = y), which is known to be a simpler problem. Estimation of the MI using estimates of P(x_i |Y = y), denoted here as \hat{P}(x_i|Y = y), is possible as the MI, can be alternatively written as

MI(X,Y) = ∑_{i=1}^{m} P(x_i)\int_{R^k} P(y|X = x_i)log_2\frac{P(x_i|Y = y)}{P(x_i)}dy

The expected value (as in above expression) with respect to distribution P(Y|X = x_i) can be approximated by the average with respect to data

MI(X,Y) \approx ∑_{i=1}^{m} P(x_i)\frac{1}{n_i} ∑_{j=1}^{n_i} P(y|X = x_i)log_2\frac{\hat{P}(x_i|Y = y^i_j)}{P(x_i)}dy

Here, we propose to use logistic regression as \hat{P}(x_i|Y = y^i_j). Specifically,

log\frac{P(x_i |Y = y)}{P(x_m|Y = y)} \approx α_i +β_iy

Additional parameters: lr_maxit and maxNWts are the same as in definition of multinom function from nnet package. An alternative model formula (using formula_string arguments) should be provided if data are not suitable for description by logistic regression (recommended only for advanced users). Preliminary scaling of data (argument scale) should be used similarly as in other data-driven approaches, e.g. if response variables are comparable, scaling (scale=FALSE) can be omitted, while if they represent different phenomenon (varying by units and/or magnitude) scaling is recommended.

Value

a list with several elements:

References

[1] Jetka T, Nienaltowski K, Winarski T, Blonski S, Komorowski M, Information-theoretic analysis of multivariate single-cell signaling responses using SLEMI, PLoS Comput Biol, 15(7): e1007132, 2019, https://doi.org/10.1371/journal.pcbi.1007132.

Examples

1
2
3
4
5
6
7
tempdata=data_example1
outputCLR1=mi_logreg_main(dataRaw=tempdata, signal="signal", response="response")

tempdata=data_example2
outputCLR2=mi_logreg_main(dataRaw=tempdata, signal="signal", response=c("X1","X2","X3")) 

#For further details see vignette

SLEMI documentation built on Feb. 22, 2021, 5:11 p.m.