README.Rmd

---
output: 
  github_document: default
  html_document:
    self_contained: no
---

```{r, echo = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-"
)
```

# phoenics: Pathways longitudinal and differential analysis in metabolomics

`phoenics` is a package that provide a method for differential analysis at a 
pathway level. It is based on metabolite quantifications and information on
pathway metabolite composition.

`phoenics` provides four user level functions: `test_pathway`,
`from_ASICS_to_PHOENICS`, `pathway_search` and `overlap_coefficient`, which are
briefly explained below.

## `from_ASICS_to_PHOENICS`
`from_ASICS_to_PHOENICS` prepare quantification data from `ASICS` outputs for
the function `test_pathway`.
```{r from_ASICS_to_PHOENICS, message=FALSE}
library(phoenics)
data("MTBLS422")

quantif <- from_ASICS_to_PHOENICS(quantif)
```

## `test_pathway`
`test_pathway` perform the differential analysis at pathway level.

The data.frame or matrix containing the pathway metabolite composition can be
given in the argument `pathways`.
```{r test_pathway, message=FALSE}
out_test <- test_pathway(quantif, design, pathways,
                         fixed = c("Age", "Treatment"), random = "Mouse", 
                         npc = 2, model = "blmer")
out_test
```

The results of `test_pathway` is of class `pathwayRes` and `PCApath`.

By default, a PCA is used to calculate pathway scores. A MFA can be used
instead, by adding the argument `analysis`.
```{r test_pathway_MFA, message=FALSE}
out_test_mfa <- test_pathway(quantif, design, pathways, 
                             fixed = c("Age", "Treatment"), random = "Mouse", 
                             npc = 2, model = "blmer", analysis = "MFA")
out_test_mfa
```

The results of `test_pathway` is of class `pathwayRes` and `MFApath`.

If no pathway information is given, `pathways` is automatically searched by the
function.
```{r test_pathway2, message=FALSE}
out_test2 <- test_pathway(quantif, design, pathways = "auto",
                          fixed = c("Age", "Treatment"), random = "Mouse",
                          npc = 2, model = "blmer", organism = "mmu")
out_test2
```

## `pathway_search`
`pathway_search` search pathways based on a vector of metabolite KEGG codes.
This function is automatically used in the function `test_pathway`, 
when `pathways = "auto"`.
```{r pathway_search}
pathways_auto <- pathway_search(metab = colnames(quantif), organism = "mmu")
head.matrix(pathways_auto)
```

## `overlap_coefficient`
`overlap_coefficient` calculate the overlap coefficient between two pathways.

The arguments `pathwayA` and `pathwayB` can be pathway names and their
metabolite compositions are given in the argument `pathways`.
```{r overlap_coefficient}
pathwayA <- "Galactose metabolism"
pathwayB <- "Vitamin digestion and absorption"
overlap_coefficient(pathwayA, pathwayB, pathways)
```

If `pathways` argument is not given, the argument `organism` is required to
search for pathway composition in KEGG database.
```{r overlap_coefficient2}
pathwayA <- "Galactose metabolism"
pathwayB <- "Vitamin digestion and absorption"
overlap_coefficient(pathwayA, pathwayB, organism = "mmu")
```

The arguments `pathwayA` and `pathwayB` can be pathway codes and their
metabolite compositions are given in the argument `pathways`.
```{r overlap_coefficient3}
pathwayA <- "mmu00052"
pathwayB <- "mmu00562"
overlap_coefficient(pathwayA, pathwayB, pathways)
```

The arguments `pathwayA` and `pathwayB` can be vectors of metabolites. In that
case, the the argument `pathways` is not required.
```{r overlap_coefficient4}
pathwayA <- c("C00029", "C00116", "C00137", "C00794", "C00984", "C01697")
pathwayB <- c("C00191", "C00092", "C00137")
overlap_coefficient(pathwayA, pathwayB)
```