SourceSet (version 0.1.0)

sourceSet: Source Set

Description

Identify the sets of variables that are potential sources of differential behavior, (i.e., the primary genes) between two experimental conditions. The two experimental conditions are associated to a set of graphs, where each graph represents the topology of a biological pathway.

Usage

sourceSet(graphs, data, classes, seed = NULL, theta = 1, permute = TRUE,
  alpha = 0.05, shrink = FALSE, return.permutations = FALSE)

Arguments

graphs

a list of graphNEL objects representing the pathways to be analyzed.

data

a matrix of expression levels with column names for genes and row names for samples; gene names must be unique.

classes

a vector of length equal to the number of rows of data. It indicates the class (condition) of each statistical unit. Only two classes, labeled as 1 and 2, are allowed;

seed

integer value to get a reproducible random result. See Random.

theta

positive numeric value greater then 1, that defines the number of permutation. If permute=TRUE, (m/alpha x theta) permutations are used, where m is the number of unique conditional tests to be performed; otherwise, (1/alpha x theta) permutations are supplied.

permute

if TRUE permutation p-values are provided; if FALSE, asymptotic p-values are returned. NOTE: even if the argument permute is set to FALSE the function will permute the dataset; these permutations will be used to calculate the adjusted cut-off for the asymptotic p-values.

alpha

the p-value threshold. Denotes the level at which FWER is controlled for each input graph.

shrink

if TRUE, regularized estimation of the covariance matrices is performed; otherwise, maximum likelihood estimations is used.

return.permutations

if TRUE, the function returns the matrix of test statistic values for the supplied (first row) and the permutated datasets.

Value

The output of the function is an object of the sourceSetList class. It contains as many lists as the input graphs, and each of them provides the following variables:

  • primarySet: a character vector containing the names of the variables belonging to the estimated source set (primary dysregulation);

  • secondarySet: a character vector containing the names of the variables belonging to the estimated secondary set (secondary dysregulation);

  • orderingSet: a list of character vectors containing the names of the variables belonging to the estimated source set of each ordering; the union of these elements contains all genes affected by some form of perturbation;

  • Components: a data frame that contains information about unique tests, including their associated p-values;

  • Decompositions: a list of data frames, one for each identified ordering. Each data frame is a subset of size k (i.e., number of cliques), of the Components elements

  • Elements: cliques and separators of the underlying decomposable graph. See Graph

  • Thresholds: a list with information regarding the multiple testing correction:

    • alpha: the input (nominal) significance level;

    • value: the corrected threshold that ensures the control of FWER at level alpha;

    • type: the used procedure (minP or maxT);

    • iterations: the number of iterations for the step-down procedure;

    • nperms: the number of permutations.

  • Graph: decomposable graph used in the analysis. It may differ from the input graph. In fact, if the input graph is not decomposable, the function will internally moralize and triangulate it.

Details

The sourceSet approach models the data of the same pathway in two different experimental conditions as realizations of two Gaussian graphical models sharing the same decomposable graph G. Here, G = (V,E) is obtained from the pathway topology conversion, where V and E represent genes and biochemical reactions, respectively.

We give full freedom to the user in providing the underlying graph G, requiring only a specific input format (i.e., a graphNEL object). So, the user can provide a list of manually curated pathways or use developed software to translate the bases of knowledge. To date, the most complete software available for this task is graphite R package (Sales et al. 2017).

The source set algorithm infers the set of primary genes (i.e., the source set) following - for each graph - five steps:

  • decompose graph G in the set of the maximal cliques and the set of separators.

  • identify the cliques orderings, and the associated separators, that satisfy the running intersection property, using each cliques as root. See ripAllRootsClique.

  • a) calculate marginal test statistics for the cliques and the separators, for both the original and the permutated datasets; b) compute the conditional test statistics for the unique components, calculated as the difference between clique and separator marginal test statistics; c) control the FWER, using the test statistics matrix of the previous point.

  • make the union of the sets of variables belonging to cliques that are associated to a significant test, within each decomposition.

  • derive the source set, defined as the intersection of the set of variables obtained in step 4 across decompositions.

Although the interpretation of the source set for a single graph is intuitive, the interpretation of the collection of results associated to a set of pathways might be complex. For this reason, we propose a guideline for the meta-analysis providing descriptive statistics and predefined plots. See, infoSource, easyLookSource, sourceSankeyDiagram, sourceCytoscape and sourceUnionCytoscape.

References

Sales, G. et al. (2017). graphite: GRAPH Interaction from pathway Topological Environment, r package version 1.22.0 edition.

Westfall, P. and Young, S. (2017). Resampling-based multiple testing : examples and methods for p-value adjustment. Wiley.

Djordjilovic, Vera and Chiogna, Monica (2017) Searching for a Source of Difference: a Graphical Model Approach. [Working Paper] WORKING PAPER SERIES, 4/2017, PADOVA

Salviato et al. (2018). SourceSet: a graphical model approach to identify primary genes in perturbet biological pathways. Manuscript submitted for publication.

See Also

pathways, infoSource, easyLookSource, sourceSankeyDiagram, sourceCytoscape and sourceUnionCytoscape

Examples

Run this code
# NOT RUN {

#### Toy example: only one graph
if(require(mvtnorm)){
  # Generate two random samples of size 50 from two multivariate normal distributions
  n<-50
  # true parameters of class 1 and class 2
  param.class1<-simulation$condition1
  param.class2<-simulation$condition2$`10`$`2`

  # simulated dataset
  data.class1<-rmvnorm(n = n,mean =param.class1$mu ,sigma =param.class1$S)
  data.class2<-rmvnorm(n = n,mean =param.class2$mu ,sigma=param.class2$S)

  # Input arguments for the sourceSet function
  data<-rbind(data.class1,data.class2)
  classes<-c(rep(1,nrow(data.class1)),rep(2,nrow(data.class2)))
  graphs<-list("toy.graph"=simulation$graph)

  result<-sourceSet(graphs ,data ,classes ,seed = 123 ,permute =FALSE ,shrink =FALSE, alpha=0.05  )

  # source set: primary disregulation (toy.graph)
  result$toy.graph$primarySet
  # secondary disregulation (toy.graph)
  result$toy.graph$secondarySet
  # all affected variables
  unique(unlist(result$toy.graph$orderingSet))

  # summary statistics
  info<-infoSource(result)
  info$variable
  info$graph

  # visual summaries
  easyLookSource(result)
  sourceSankeyDiagram(result)
}

# launch cytoscape and run:
# }
# NOT RUN {
sourceCytoscape(result,name.graphs = "toy.graph",collection.name = "Example")
sourceUnionCytoscape(result ,collection.name = "Example")
# }
# NOT RUN {
### Real data:
# see vignette, section Getting deepening
vignette("SourceSet")
# }

Run the code above in your browser using DataCamp Workspace