---
title: "Getting Started"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting Started}
  %\VignetteEncoding{UTF-8}
  %\VignetteEngine{knitr::rmarkdown}
editor_options: 
  chunk_output_type: console
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  warning = FALSE
)
```

Below contains a brief overview on how to get users started with `smatr` 

More detailed information about the package can be found here:
Warton, D. I., Duursma, R. A., Falster, D. S., & Taskinen, S. (2012). [smatr 3–an R package for estimation and inference about allometric lines](https://besjournals.onlinelibrary.wiley.com/doi/full/10.1111/j.2041-210X.2011.00153.x). Methods in Ecology and Evolution, 3(2), 257-259. 

First, install smatr`
```{r setup, eval = FALSE}
# Install via CRAN or github
install.packages("smatr")
devtools::install_github("dfalster/smatr3")
```

then load the library
```{r, message=FALSE}
# Load library
library(smatr)
```

Note we will illustrate some of the core functions of `smatr` using one of the two data sets included in the package
```{r}
data(leaflife)
data(leafmeas)

#For more details on each data set
?leaflife
?leafmeas
```

### One sample analyses ###

Users can fit a single major axis to their data using the `ma(y ~ x)` or `sma(y ~x)` functions for y against x. The `log` argument allows quick transformations to one or both axes before estimation occurs. For example: 

```{r}
# Extract only low-nutrient, low-rainfall data from leaflife dataset:
leaf.low <- subset(leaflife, soilp == 'low' & rain == 'low')

# Fit a single MA for log(leaf longevity) vs log(leaf mass per area):
ma(longev ~ lma, log='xy', data=leaflife)
```

### Testing for significance ###
Users can specify using the argument `slope.test` in the `ma()` or `sma()` function to test whether the estimated slope is significantly different from 1. Calling summary to `sma` or `ma` objects will return confidence intervals for the slope and/or elevation.

```{r}
# Test if the MA slope is not significantly different from 1 for longevity and leaf mass per area (LMA):
ma_obj <- ma(longev ~ lma, log='xy', slope.test=1, data=leaflife) 

summary(ma_obj)
plot(ma_obj)
```

### Multiple sample analyses ###

Often researchers wish to compare between slopes or intercepts of axes between different groups. Lets say we want to compare between high and low rainfall for low nutrient sites ONLY

```{r}
# First we subset the data that is relevant
leaf.low.soilp <- subset(leaflife, soilp == 'low')

# Then using * we can fit SMAs separately at each of high and low rainfall sites and test for whether sites with different rainfall share a common slope
rain_sma_obj <- sma(longev~lma*rain, log="xy", data=leaf.low.soilp)

# Lets plot longevity vs LMA separately for each group first:
plot(rain_sma_obj)
```

The same fit can be drawn with `ggplot2` by calling `ggplot()` on the fitted object. This plots the data and fitted (S)MA line(s), colours by group where present, and log-scales any axes that were log-transformed in the fit. Because it returns a standard `ggplot` object, you can add themes, labels and further layers as usual:

```{r, message=FALSE}
library(ggplot2)

# ggplot2 version of the grouped SMA fit
ggplot(rain_sma_obj)

# The result is a normal ggplot object, so extend it however you like:
ggplot(rain_sma_obj) +
  theme_minimal() +
  labs(title = "Leaf longevity vs LMA", colour = "Rainfall")
```

By default, the `sma()` function will first fit a common slope for all groups and then test whether there is a difference in elevation

```{r}
# Fit SMAs for each group and tests if several SMA lines share a common slope. 
rain_sma_obj <- sma(longev~lma*rain, log="xy", data=leaf.low.soilp)

summary(rain_sma_obj)
```

Again, using the `slope.test` will test whether the common slope is significantly different to 1.

```{r}
# Fit SMAs separately at each of high and low rainfall sites,
# and test if there is a common slope and whether it is equal to 1:
rain_slope_obj <- sma(longev~lma*rain, log="xy", slope.test=1, data=leaf.low.soilp)

summary(rain_slope_obj)
```

The `type` argument allows users to test for a change in elevation

```{r}
# Fit SMAs separately at each of high and low rainfall sites, and test whether sites differ in the elevation of their SMA
rain_elev_obj <- sma(longev~lma*rain, log="xy", type = "elevation", data=leaf.low.soilp)

summary(rain_elev_obj)
```

The `type` argument allows users to also test for shifts along a common axis

```{r}
# Fit SMAs with common slope across each of high and low rainfall sites, and test for no shift along common SMA:
rain_shift_obj <- sma(longev~lma+rain, log="xy", type="shift", data=leaf.low.soilp)
summary(rain_shift_obj)
```