FELLA 1.0.1
FELLA
is an R package that brings a new concept
for metabolomics data interpretation.
The starting point of this data enrichment is
a list of affected metabolites, which can stem from a
contrast between experimental groups.
This list, that may vary in size,
encompasses key role players from different
biological pathways that generate a biological perturbation.
The classical way to analyse this list is the over representation analysis. Each metabolic pathway has a statistic, the number of affected metabolites in it, that yields a p-value. After correcting for multiple testing, a list of prioritised pathways helps performing a quality check on the data and suggesting novel biological mechanisms related to the data. Subsequent generations of pathway analysis methods attempt to include quantitative and/or topological data in the statistics in order to improve power for subtle signals, but the interpretation of a prioritised pathway list remains a challenge.
Package FELLA
, on the other hand,
introduces a comprehensive output that encompasses
other biological entities that coherently relate
the top ranked pathways.
The priorisation of the pathways and other entiteis stems from a
diffusion process on a holistic graph representation
of the KEGG database.
FELLA
needs:
FELLA.DATA
S4 object.FELLA.USER
S4 object,
along with user analyses.This vignette makes use of sample data
that contains small subgraph of FELLA
’s KEGG graph
(mid 2017 KEGG release).
All the necessary contextual data is stored
in an S4 data structure with class FELLA.DATA
.
Several functions need access to the contextual data,
passed as an argument called data
,
being the enrichment itself among them.
library(FELLA)
data("FELLA.sample")
class(FELLA.sample)
## [1] "FELLA.DATA"
## attr(,"package")
## [1] "FELLA"
show(FELLA.sample)
## General data:
## - KEGG graph:
## * Nodes: 670
## * Edges: 1677
## * Density: 0.003741383
## * Categories:
## + pathway [2]
## + module [6]
## + enzyme [58]
## + reaction [279]
## + compound [325]
## * Size: 366.9 Kb
## - KEGG names are ready.
## -----------------------------
## Hypergeometric test:
## - Matrix is ready
## * Dim: 325 x 2
## * Size: 25 Kb
## -----------------------------
## Heat diffusion:
## - Matrix not loaded.
## - RowSums are ready.
## -----------------------------
## PageRank:
## - Matrix not loaded.
## - RowSums are ready.
Keep in mind that FELLA.DATA
objects need to
be constructed only once by using buildGraphFromKEGGREST
and buildDataFromGraph
, in that precise order.
This will store them in a local path and they
should be loaded through loadKEGGdata
.
The user is disadvised from manually modifying the database
internal files and the FELLA.DATA
object slots
not to corrupt the database.
The second block of necessary data is a list of affected metabolites, which shoud be specified as KEGG compound IDs. Provided is a list of hypothetical affected metabolites belonging to the graph, to which some decoys that do not map to the graph are added.
data("input.sample")
input.full <- c(input.sample, paste0("intruder", 1:10))
show(input.full)
## [1] "C00143" "C00546" "C04225" "C16328" "C00091"
## [6] "C15979" "C16333" "C05264" "C05258" "C00011"
## [11] "C00083" "C00044" "C05266" "C00479" "C05280"
## [16] "C01352" "C05268" "C16329" "C00334" "C05275"
## [21] "C14145" "C00081" "C04253" "C00027" "C00111"
## [26] "C00332" "C00003" "C00288" "C05467" "C00164"
## [31] "intruder1" "intruder2" "intruder3" "intruder4" "intruder5"
## [36] "intruder6" "intruder7" "intruder8" "intruder9" "intruder10"
Compounds are introduced through the defineCompounds
function and provide the first FELLA.USER
user data object containing the
mapped compounds and empty analyses slots.
The user should always build FELLA.USER
objects
through defineCompounds
instead of manipulating
the slots of the object manually - this might skip quality checks.
myAnalysis <- defineCompounds(
compounds = input.full,
data = FELLA.sample)
## No background compounds specified. Default background will be used.
## Warning in defineCompounds(compounds = input.full, data = FELLA.sample):
## Some compounds were introduced as affected but they do not belong to
## the background. These compounds will be excluded from the analysis. Use
## 'getExcluded' to see them.
Note that a warning message informs the user
that some compounds did not map to the KEGG compound collection.
Compounds that successfully mapped
can be obtained through getInput
,
getInput(myAnalysis)
## [1] "C00003" "C00011" "C00027" "C00044" "C00081" "C00083" "C00091" "C00111"
## [9] "C00143" "C00164" "C00288" "C00332" "C00334" "C00479" "C00546" "C01352"
## [17] "C04225" "C04253" "C05258" "C05264" "C05266" "C05268" "C05275" "C05280"
## [25] "C05467" "C14145" "C15979" "C16328" "C16329" "C16333"
while compounds that were excluded
because of mismatch can be accessed through getExcluded
:
getExcluded(myAnalysis)
## [1] "intruder1" "intruder2" "intruder3" "intruder4" "intruder5"
## [6] "intruder6" "intruder7" "intruder8" "intruder9" "intruder10"
Keep in mind that exact matching is sought, so be extremely careful with whitespaces, tabs or similar characters that might create mismatches. For example:
input.fail <- paste0(" ", input.full)
defineCompounds(
compounds = input.fail,
data = FELLA.sample)
## Error in defineCompounds(compounds = input.fail, data = FELLA.sample): None of the specified compounds appear in the available KEGG data.
Once the FELLA.DATA
and the FELLA.USER
with the affected metabolites are ready,
the data can be easily enriched.
There are three methods to enrich:
method = "hypergeom"
):
it performs the metabolite-sampling hypergeometric test
using the connections in FELLA
’s KEGG graph.
This is included for completeness and does not include
the contextual novelty of the diffusive methods.method = "diffusion"
):
it performs sub-network analysis on the KEGG graph
to extract a meaningful subgraph.
This subgraph can be plotted an interpretedmethod = "pagerank"
):
analogous to "diffusion"
but using the directed diffusion,
which matches the PageRank algorithm for web ranking.For methods "diffusion"
and "pagerank"
,
two statistical approximations are proposed:
approx = "normality"
):
scores are computed through z-scores
based on analytical expected value and covariance matrix
of the null model for diffusion.
This approximation is deterministic and fast.approx = "simulation"
):
scores are computed through Monte Carlo trials
of the random variables.
This approximation requires computing the random trials,
governed by the ntrials
argument.The function enrich
wraps the functions
defineCompounds
, runHypergeom
, runDiffusion
and runPagerank
in an easily usable manner, returning a FELLA.USER
object with complete analyses.
myAnalysis <- enrich(
compounds = input.full,
method = "diffusion",
approx = "normality",
data = FELLA.sample)
## No background compounds specified. Default background will be used.
## Warning in defineCompounds(compounds = compounds, compoundsBackground =
## compoundsBackground, : Some compounds were introduced as affected but they
## do not belong to the background. These compounds will be excluded from the
## analysis. Use 'getExcluded' to see them.
## Running diffusion...
## Computing p-scores through the specified distribution.
## Done.
The output is quite informative and aggregates
all the warnings.
Let’s compare an empty FELLA.USER
object
show(new("FELLA.USER"))
## Compounds in the input: empty
## Background compounds: all available compounds (default)
## -----------------------------
## Hypergeometric test: not performed
## -----------------------------
## Heat diffusion: not performed
## -----------------------------
## PageRank: not performed
to the output of a processed one:
show(myAnalysis)
## Compounds in the input: 30
## [1] "C00003" "C00011" "C00027" "C00044" "C00081" "C00083" "C00091" "C00111"
## [9] "C00143" "C00164" "C00288" "C00332" "C00334" "C00479" "C00546" "C01352"
## [17] "C04225" "C04253" "C05258" "C05264" "C05266" "C05268" "C05275" "C05280"
## [25] "C05467" "C14145" "C15979" "C16328" "C16329" "C16333"
## Background compounds: all available compounds (default)
## -----------------------------
## Hypergeometric test: not performed
## -----------------------------
## Heat diffusion: ready.
## P-scores under 0.05: 86
## -----------------------------
## PageRank: not performed
The wrapper function enrich
can run the three analysis
at once with the option method = listMethods()
, or only
the desired ones providing them as a character vector:
myAnalysis <- enrich(
compounds = input.full,
method = listMethods(),
approx = "normality",
data = FELLA.sample)
show(myAnalysis)
## Compounds in the input: 30
## [1] "C00003" "C00011" "C00027" "C00044" "C00081" "C00083" "C00091" "C00111"
## [9] "C00143" "C00164" "C00288" "C00332" "C00334" "C00479" "C00546" "C01352"
## [17] "C04225" "C04253" "C05258" "C05264" "C05266" "C05268" "C05275" "C05280"
## [25] "C05467" "C14145" "C15979" "C16328" "C16329" "C16333"
## Background compounds: all available compounds (default)
## -----------------------------
## Hypergeometric test: ready.
## Top 2 p-values:
## hsa00640 hsa00010
## 8.540386e-09 9.999888e-01
##
## -----------------------------
## Heat diffusion: ready.
## P-scores under 0.05: 86
## -----------------------------
## PageRank: ready.
## P-scores under 0.05: 70
The wrapped functions work in a similar way,
here is an example with runDiffusion
:
myAnalysis_bis <- runDiffusion(
object = myAnalysis,
approx = "normality",
data = FELLA.sample)
## Running diffusion...
## Computing p-scores through the specified distribution.
## Done.
show(myAnalysis_bis)
## Compounds in the input: 30
## [1] "C00003" "C00011" "C00027" "C00044" "C00081" "C00083" "C00091" "C00111"
## [9] "C00143" "C00164" "C00288" "C00332" "C00334" "C00479" "C00546" "C01352"
## [17] "C04225" "C04253" "C05258" "C05264" "C05266" "C05268" "C05275" "C05280"
## [25] "C05467" "C14145" "C15979" "C16328" "C16329" "C16333"
## Background compounds: all available compounds (default)
## -----------------------------
## Hypergeometric test: ready.
## Top 2 p-values:
## hsa00640 hsa00010
## 8.540386e-09 9.999888e-01
##
## -----------------------------
## Heat diffusion: ready.
## P-scores under 0.05: 86
## -----------------------------
## PageRank: ready.
## P-scores under 0.05: 70
The method plot
for data from the package FELLA
allows a friendly visualisation of the relevant
part of the KEGG graph.
In the case method = "hypergeom"
the plot encompasses
a bipartite graph that contains
top pathways and affected compounds.
In that case, threshold = 1
allows the visualisation
of both pathways; otherwise a plot with only one pathway
would be quite uninformative.
plot(
x = myAnalysis,
method = "hypergeom",
main = "My first enrichment using the hypergeometric test in FELLA",
threshold = 1,
data = FELLA.sample)
For method = "diffusion"
the graph contains
a richer representations involving
modules, enzymes and reactions
that link affected pathways and compounds.
plot(
x = myAnalysis,
method = "diffusion",
main = "My first enrichment using the diffusion analysis in FELLA",
threshold = 0.1,
data = FELLA.sample)