Readme.Rmd

---
title: "Readme"
output: github_document
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE)
```

# otutableNMDS

This package aims to assist the easy implementation of Nonmetric Multidimensional Scaling (NMDS) plots into `ggplot`.

The package includes an example dataset from [Jauss et al. 2020](https://www.frontiersin.org/articles/10.3389/fmicb.2020.592189/), which is an OTU abundance table including sample metadata, and three functions:

- `get_NMDS_ordination`: The function takes the OTU table (with or without metadata) and performs the NMDS ordination. The resulting object is needed for the next step:
- `get_hull_data`: It returns a dataframe containing the coordinates for the convex hull data used for the drawing of polygons in the next function. The user can specify any sample type which the polygons should be drawn around
- `plot_NMDS`: This is a simple function pasting the hull data to `ggplot2` and drawing polygons around the specified samples or habitats

## Installation

You can easily install this package with `devtools` like this:

```{r Installation, eval=FALSE}
devtools::install_github('RJauss/otutableNMDS', ref = "HEAD")
```

## Usage 

Here is a simple example of how the package works. Let's first have a look at the example data:

```{r Example data}
library(otutableNMDS)
data("OTU_Table")

tibble::as_tibble(OTU_Table[1:10, 1:10])
```

My data has the sample metadata included in columns 1-5, after that comes the species abundance matrix. So we need to specify which columns and which sample(-types) to use in the `get_hull_data` function. But first we run the `get_NMDS_ordination` function which uses the `metaMDS` function from `vegan`:

```{r Get NMDS Ordination, message=FALSE, results='hide'}
NMDS.data <- get_NMDS_ordination(OTU_Table = OTU_Table, 
                                 SampleMetadata = c(1, 5), 
                                 logtransform = T, 
                                 relative = T, 
                                 k = 3)
# Note that you can specify further arguments which will be passes
# to metaMDS(), for example "distance = 'jaccard'" etc
```

```{r}
hull.data <- get_hull_data(NMDS_data = NMDS.data, 
                           SampleMetadata = OTU_Table[,1:5], 
                           NMDS = c("NMDS1", "NMDS2"), 
                           habitat = "Microhabitat", 
                           which = "all")

head(hull.data)
```

The function returns the dataframe with the coordinates neccessary for the polygons to draw around the microhabitats. 

## Plot NMDS

The dataframe will now be parsed into the third function, `plot_NMDS`:

```{r Plot NMDS, dpi=300}
g <- plot_NMDS(hull_data = hull.data, 
               NMDS_data = NMDS.data, 
               x = "NMDS1", y = "NMDS2", 
               habitat = "Microhabitat")

g
```

## Plot additional NMDS on top

Let's say we also want the hull data for the tree species, we can easily modify the code like this and plot a second ordination on top:

```{r Get Tree Species Hull Data}
hull.data.TreeSpecies <- get_hull_data(NMDS_data = NMDS.data, 
                                       SampleMetadata = OTU_Table[,1:5],
                                       NMDS = c("NMDS1", "NMDS2"), 
                                       habitat = "TreeSpecies", 
                                       which = "all")
```

Now call the `plot_NMDS` again and specify both hull.datas. The second one will be plotted on top with non-filled polygons:

```{r Plot NMDS two dataframes, dpi=300}
g <- plot_NMDS(hull_data = hull.data, 
               hull_data2 = hull.data.TreeSpecies, 
               NMDS_data = NMDS.data, 
               x = "NMDS1", y = "NMDS2", 
               habitat = "Microhabitat", 
               habitat2 = "TreeSpecies")

g
```

This is now a very basic ggplot NMDS which can be easily modified and appended with the ggplot syntax, e.g. "scale_fill_manual"