---
title: "Introduction to the microbiome R package"
author: "Leo Lahti, Sudarshan Shetty, et al."
bibliography: 
- bibliography.bib
date: "`r Sys.Date()`"
output:
  BiocStyle::html_document:
    toc: true
    fig_caption: yes    
  rmarkdown::md_document:
    toc: true
  rmarkdown::pdf_document:
    toc: true    
vignette: >
  %\VignetteIndexEntry{microbiome R package}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---


```{r, echo=FALSE, message=FALSE}
library(knitr)
# Can also write math expressions, e.g. 
# $Y = X\beta + \epsilon$, footnotes^[A footnote here.]
# > "He who gives up [code] safety for [code] speed deserves neither."
# ([via](https://twitter.com/hadleywickham/status/504368538874703872))
knitr::opts_chunk$set(fig.width=10, fig.height=10, message=FALSE, warning=FALSE)
```

# Introduction

The [microbiome R package](http://microbiome.github.io/microbiome)
facilitates exploration and analysis of microbiome profiling data, in
particular 16S taxonomic profiling.

This vignette provides a brief overview
with example data sets from published microbiome profiling studies.

A more comprehensive tutorial is available
[on-line](http://microbiome.github.io/tutorials).

Tools are provided for the manipulation, statistical analysis, and
visualization of taxonomic profiling data. In addition to targeted
case-control studies, the package facilitates scalable exploration of
population cohorts. Whereas sample collections are rapidly
accumulating for the human body and other environments, few
general-purpose tools for targeted microbiome analysis are available
in R.  This package supports the independent
[phyloseq](http://joey711.github.io/phyloseq) data format and expands
the available toolkit in order to facilitate the standardization of
the analyses and the development of best practices. See also
phylofactor for additional 16S rRNA amplicon analysis tools in R. The
aim is to complement the other available packages, but in some cases
alternative solutions have been necessary in order to streamline the
tools and to improve complementarity.

We welcome feedback, bug reports, and suggestions for new features
from the user community via the [issue
tracker](https://github.com/microbiome/microbiome/issues) and [pull
requests](http://microbiome.github.io/microbiome/Contributing.html). See
the [Github site](https://github.com/microbiome/microbiome) for source
code and other details. These R tools are released under the
[Two-clause FreeBSD
license](http://en.wikipedia.org/wiki/BSD\_licenses).

Kindly cite the work as follows: "Leo Lahti [et
al.](https://github.com/microbiome/microbiome/graphs/contributors)
(Bioconductor, 2017-2020). Tools for microbiome analysis in R. Microbiome
package version `r sessionInfo()$otherPkgs$microbiome$Version`. URL:
(http://microbiome.github.io/microbiome)


# Installation

Loading the package in R (after installation from Bioconductor):

```{r loading}
library(microbiome)  
```


# Further reading

The [on-line tutorial](http://microbiome.github.io/microbiome)
provides many additional tools and examples, with more thorough
descriptions. This package and tutorials are work in progress. We
welcome feedback, for instance via [issue
Tracker](https://github.com/microbiome/microbiome/issues), [pull
requests](https://github.com/microbiome/microbiome/), or via
[Gitter](https://gitter.im/microbiome).


# Acknowledgements

Thanks to all
[contributors](https://github.com/microbiome/microbiome/graphs/contributors).
Financial support has been provided by Academy of Finland (grants
256950 and 295741), [University of
Turku](http://www.utu.fi/en/Pages/home.aspx). 

This work relies heavily on the independent
[phyloseq](https://github.com/joey711/phyloseq) package and data
structures for R-based microbiome analysis developed by Paul McMurdie
and Susan Holmes.