---
title: "Getting started with the AICcPermanova package"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting started with the AICcPermanova package}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

```{r setup}
library(AICcPermanova)
```

# Introduction

The AICcPermanova package provides an R implementation of model selection for Permanovas from the vegan package. This package enables users to generate all possible models for a given set of variables, calculate AICc values for those models, and perform model selection based on a given threshold.

# Installation

To install this package, you can use the remotes package to install its development version:

```{r, eval= F}
remotes::install_github("Sustainscapes/AICcPerm")
```

Alternatively, you can install the stable version from CRAN:

```{r, eval = F}
install.packages("AICcPermanova")
```

## Generating all possible models

To generate all possible models, you can use the `make_models` function. For example:

```{r examplemakemodels, results='hide', message=FALSE}
library(AICcPermanova)
AllModels <- make_models(vars = c("pH", "Sand", "Clay"), ncores = 1)
```

This function will create a table of all possible models for the specified variables, which you can see in the following table:

```{r Table1, echo = F}
knitr::kable(AllModels)
```

Where you can see all possible models for those 3 variables.

## Calculating AICc

To calculate AICc, you can use the AICc_permanova2 function. Here's an example of how to use it:

```{r}
library(vegan)
data(dune)
data(dune.env)

# Run PERMANOVA using adonis2

Model <- adonis2(dune ~ Management * A1, data = dune.env)

# Calculate AICc
Table_permanova <- AICc_permanova2(Model)
```

The results of this calculation are displayed in the following table:

```{r permanovatable}
knitr::kable(Table_permanova)
```

In this example, we used the adonis2 function to run a PERMANOVA analysis on the dune dataset with the Management and A1 variables. We then calculated AICc using the AICc_permanova2 function

## Full example

In this section, we'll provide a complete example of the AICcPerm package workflow. First, we need to load datasets from the vegan package:

```{r}
library(vegan)
data(dune)
data(dune.env)
```

Next, we'll generate all possible first-order models for this dataset:

```{r, results='hide'}
AllModels <- make_models(vars = c("A1", "Moisture", "Management", "Use", "Manure"), ncores = 1)
```

This results in `r nrow(AllModels)` possible models, which are shown in the following table:
```{r, echo=FALSE}
knitr::kable(AllModels)
```

### Avoiding multicollinearity

After generating all the models, it's important to check for multicollinearity. We can use the `filter_vif` function to filter out models that have a high degree of collinearity (defined as having a maximum value of VIF of 5 or more):

```{r}
NonColinear <- filter_vif(all_forms = AllModels, env_data = dune.env, ncores = 1)
```

This reduces the number of models to `r nrow(NonColinear)`

### Fittng the models

After filtering out collinear models, we can fit all the remaining non-collinear models by using the `fit_models` function:

```{r}
Fitted <- fit_models(
  all_forms = NonColinear,
  com_data = dune,
  env_data = dune.env,
  ncores = 1,
  method = "bray"
)
```

This results in a table of fitted models ordered by AICc, which is displayed below:

```{r, echo=FALSE}
knitr::kable(Fitted)
```

If there is a block variable to be used (such as Use in the dune.env object), you can specify it using the strata argument:

```{r fitwihtstrata}
Fitted2 <- fit_models(
  all_forms = NonColinear,
  com_data = dune,
  env_data = dune.env,
  ncores = 1,
  method = "bray",
  strata = "Use"
)
```

This results in a table of fitted models that takes into account the block variable, which is displayed below:

```{r, echo=FALSE}
knitr::kable(Fitted2)
```

## Model Selection

To select models, we use the select_models function, which chooses models with a maximum VIF of less than 5 and a delta AICc less than a specified threshold, delta_aicc. By default, delta_aicc is set to 2.

We can use the Fitted2 object generated in the previous section to select models:

```{r selected}
Selected <- select_models(Fitted2)
```

The resulting table displays the selected models:

```{r tableselected, echo = FALSE}
knitr::kable(Selected)
```

Note that the models in the table satisfy the criteria for maximum VIF and delta AICc as specified in the `select_models` function.


### Summary weighted by AICc

finally you can do a summarized r squared weighted by AICc using the 
`akaike_adjusted_rsq` function as seen bellow:

```{r}
Summary <- akaike_adjusted_rsq(Selected)
```

which results in the following table:

```{r, echo = FALSE}
knitr::kable(Summary)
```

# Conclusion

The AICcPerm package provides an easy-to-use implementation of model selection based on AICc, which is a useful tool for selecting the best model from a set of candidate models. By calculating AICc values for each model, we can compare them and select the model with the lowest AICc value. This method takes into account both model complexity and goodness-of-fit, making it a valuable approach for selecting models that balance these two factors.

Furthermore, the AICcPermanova package offers additional tools for model selection, such as model averaging and model comparison based on likelihood ratio tests. These can be used to further refine model selection and improve the accuracy of model predictions.

Overall, the AICcPermanova package is a powerful tool for model selection in a variety of contexts, including ecology, biology, and other fields that use statistical modeling to analyze complex data. By selecting the best model from a set of candidate models, researchers can make more accurate predictions and draw more reliable conclusions from their data.