diffuseV3: Diffuse heat in an AGG object by numerical equilibration.

In hyginn/ekplektoR: Network Analysis for Cell- and Systems Biology

Description

diffuseV3 Read an AGG object from an RDS compressed file. Diffuse a small portion q of excess heat across randomly chosen edges if the tail vertex of the directed edge has more "heat" than the head vertex. Repeat for N * |E| steps. Store the total amount of heat flowing across each edge as its "influence".

Usage

diffuseV3(fnAGG, fnEGG, param, silent = FALSE, writeLog = TRUE)

Arguments

fnAGG	Filename of an AGG object, saved as RDS.
fnEGG	Filename of an EGG object, to be saved as RDS.
param	list containing N, q, seed, and useRcpp parameters (see Details).
silent	logical. Whether output will be to console will be suppressed. Default FALSE.
writeLog	logical. Whether an event entry for the log file is to be written. Default TRUE.

Value

N/A. This function is invoked for its side effect of writing a heat-equilibrated EGG graph to the ouput filename in RDS format.

## @family ...

## @seealso ...

Algorithm

Heat diffusion by numerical equilibration simulates the physical heat diffusion process by equilibrating portions of heat difference between adjacent vertices in directed, weighted graphs. The algorithm scales with O(|E|) and requires insignificant extra memory. It is thus well suited for graphs for which the calculation of heat diffusion from Markov chain stationary states via matrix inversion is too costly, as well as for weighted graphs. By default the seed for the random equilibration is taken from Sys.time(), but an explicit random seed can be passed in the parameter list. Heat diffusion is calculated in base R if useRcpp is FALSE, and uses Rcpp code otherwise (not yet implemented).

Parameters

Typically the heat diffusion process is not run to equilibrium to emphasize the neighbourhood of the "hot" vertices in the graph. Large N and q values both speed up equilibration. Small q allow smooth equilibration without numerical artefacts. Thus q should be as small and N as large as computational resources allow. Setting a seed parameter allows to perform reproducible equilibrations for development purposes. If param is missing, the default is list(N = 100, q = 0.01, seed = as.numeric(Sys.time()), useRcpp = FALSE). If param is set, these default values will be used for any of the parameters that have not been specifed otherwise. ToDo: add benchmarks.

Heat diffusion step

The amount of heat h that is transported between the two incident vertices of the directed edge e: (t->h), with h_t heat on the tail vertex and h_h heat on the head vertex, is: h <- q * W_e *(h_t - (h_t + h_h)/2) if h_t > h_h, else 0. q [0;1] is the global fraction of heat that is transported and governs the speed with which the graph will equilibrate to a state without heat differences; W_e [0;1] is the "thermal conductivity" of the specific edge. Appropriately scaled influence scores on edges enhance flow across these edges and throttle flow across others. h is subtracted from h_t and added to h_h thus the heat on both nodes asymptotically approaches the average from both sides. At every step the amount of heat that has flowed is added to the "Influence" attribute of the edge.

Value

The resulting EGG graph is a igraph object, a directed, weighted graph with weights stored as a "Weight" edge attribute, the heat-flux as "Influence" edge-attributes, and the "heat" values as "Score" vertex attributes. Metadata is attached as attributes: "type": "EGG"; "version": "1.0"; and "UUID" a UUID.

Log file

The filenames and UUID of the source AGG and the resulting EGG are written to the global log-file if writeLog is TRUE. As well, the function call and detailed parameters are written to the log-file. Thus the parameters with which an EGG was equilibrated can be found in the log-file by searching for its UUID.

Examples

## Not run: 
   diffuseV3(IN, OUT)

## End(Not run)

hyginn/ekplektoR documentation built on May 17, 2019, 9:16 p.m.