```{r wrap-hook, echo = F}
library(knitr)
hook_output = knit_hooks$get("output")
knit_hooks$set(output = function(x, options) {
  # this hook is used only when the linewidth option is not NULL
  if (!is.null(n <- options$linewidth)) {
    x = knitr:::split_lines(x)
    # any lines wider than n should be wrapped
    if (any(nchar(x) > n)) x = strwrap(x, width = n)
    x = paste(x, collapse = "\n")
  }
  hook_output(x, options)
})

def.chunk.hook  <- knit_hooks$get("output")
knit_hooks$set(output = function(x, options) {
  x <- def.chunk.hook(x, options)
  ifelse(options$size != "normalsize", paste0("\n \\", options$size,"\n\n", x, "\n\n \\normalsize"), x)
})
```

## MadingleyR Installation

The MadingleyR package can be directly installed from R using the ```devtools``` or ```remotes``` R package. The following command installs the package using the remotes R package:

```{r, message=FALSE, linewidth=90, eval = FALSE}
# Load the remotes package
library("remotes") # or use library("devtools")

# Install the MadingleyR package
install_github("MadingleyR/MadingleyR", subdir="Package", build_vignettes = TRUE)
```

```{r, message=FALSE, linewidth=90, eval = TRUE}
# Load MadingleyR package 
library("MadingleyR")

# Get version MadingleyR and C++ source code
madingley_version( )
```

When calling the ```install_github()``` function, the argument ```force = TRUE``` can be used to make sure the package is updated to the latest version, in the case previous installation files exist in the machine. In addition to installing the MadingleyR dependencies (```rgdal```, ```sp```, ```data.table``` and ```raster```), the installation process also downloads the precompiled C++ executable, default spatio-temporal input layers and all other default input parameters and includes them in the installation folder.

\pagebreak

## Model initialisation

The function ```madingley_init()``` initialises a model run by generating a cohort and stock data set. Both data sets are returned as data frames in a list object (here named: ```mdata```) after the ```madingley_init()``` finishes. The cohort data set contains functional information for all cohorts (i.e. heterotrophs) needed to run a Madingley simulation (```mdata$cohorts```). The stock data set holds the functional information concerning the stocks (i.e. photo-autotrophs) (```mdata$stocks```). The generated data sets are based on the functional definitions defined in ```cohort_def``` (cohort definitions) and ```stock_def``` (stock definitions). ```spatial_window``` defines the boundaries of the spatial location, formatted as a vector containing four coordinates in the following order: 1) minimum longitude, 2) maximum longitude, 3) minimum latitude and 4) maximum latitude. The R code shown below illustrates the use of the ```madingley_init()``` function for an area that includes the Serengeti. 

```{r, linewidth=90, message=FALSE}
# Spatial model domain = c(min_long, max_long, min_lat, max_lat)
spatial_window = c(31, 35, -5, -1)

# plot the spatial window to check selection
plot_spatialwindow(spatial_window)
```
\pagebreak

```{r, linewidth=90}
# Prints possible input options to the R console
madingley_inputs( ) 
```

After checking which inputs are available, they can be loaded manually as shown below. However, if the default inputs suffice, it is possible to initialise the model without providing these inputs manually.

```{r, message=FALSE, results='hide'}
# Load MadingleyR default inputs
sptl_inp = madingley_inputs("spatial inputs")
chrt_def = madingley_inputs("cohort definition")
stck_def = madingley_inputs("stock definition")
mdl_prms = madingley_inputs("model parameters") # useful later for running the model
```

Next, we can view what is in the default input parameters of the MadingleyR package. These inputs can also be modified depending on the simulation experiment.

```{r, linewidth=130, size="footnotesize"}
# View the structure of the spatial input layers
str(sptl_inp,2)

# View the default stock definitions
print(stck_def)
```

\pagebreak

```{r, linewidth=130, size="footnotesize"}
# View the default cohort definitions
print(chrt_def)
```

See [modelparams.pdf](https://madingleyr.github.io/MadingleyR/Documentation/modelparams.pdf) for the contents and explanation of ```mdl_prms```.

\pagebreak

For this example purposes we lowered the maximum number of cohorts allowed per spatial grid cell (keeping the number of interactions at a reasonable level). The Madingley model merges cohorts if they are highly similar and the maximum number of cohorts is exceeded. Lowering this value will increase model performance at expenses of resolution of cohort diversity. Setting ```max_cohort = 100``` saves time creating this vignette. By the default maximum number of cohorts allowed is 1000.

```{r, linewidth=90}
# Initialise model the model using the pre-loaded inputs
mdata = madingley_init(spatial_window = spatial_window,
                       cohort_def = chrt_def,
                       stock_def = stck_def,
                       spatial_inputs = sptl_inp,
                       max_cohort = 100)
```

The returned ```mdata``` object will contain all cohorts and stocks (```data.frame```). In addition, the spatial window will be attached, making sure any consecutive model run will use the same spatial window.

```{r, linewidth=90}
# View the contents of mdata
str(mdata,1)
```

\pagebreak

## Running the Madingley model

After generating cohorts and stocks, a simulation can be started using the ```madingley_run()``` function. The ```madingley_run()``` function requires the initialisation data set produced by the ```madingley_init()``` function. A typical Madingley simulation first requires a spin-up phase that allows ecosystem components to reach a stable state. This phase usually consists of a 100 to 1000-year model simulation without any model user induced changes (normally with ```max_cohort = 1000``` or ```max_cohort = 500```). The code below runs the Madingley model for 2 years (```years = 2```) using the previously generated ```mdata``` object. The standard model input variables (e.g. cohort definitions, stock definitions, spatial inputs and/or model parameters) can be changed for ```madingley_run()``` via the following input parameters: ```cohort_def```, ```stock_def```, ```spatial_inputs```, ```model_parameters```. Similar to the ```cohort_def```, ```stock_def``` and ```spatial_inputs``` (shown previously) we can see and alter the default model parameters. These parameters quantify the strength, rates and constants of the the ecological interactions in the model, [see modelparams.pdf](https://madingleyr.github.io/MadingleyR/Documentation/modelparams.pdf).

```{r}
# Run the Madingley model for 2 years
mdata2 = madingley_run(madingley_data = mdata, 
                       years = 2, 
                       cohort_def = chrt_def, 
                       stock_def = stck_def, 
                       spatial_inputs = sptl_inp, 
                       model_parameters = mdl_prms,
                       max_cohort = 100)

# View the contents of mdata2
str(mdata2,1)
```


By default the ```madingley_run()``` function prints the simulation process (simulation month). However, it can be useful in some cases to silence the printing of ```madingley_run()``` using ```silenced = TRUE```. Additionally, the ```parallel``` input argument allows the user to run the simulation in serial (on one processing core) or in parallel (using multiple cores). By default the simulation is executed in parallel to speed up the time required to run a simulation. See ```?madingley_run``` for all input arguments.


\pagebreak

## Creating plots

Specific plots can be created from the output generated by ```madingley_run()``` using the functions listed in the code blocks below. Alternatively, the ```madingley_plot()``` function with ```mdata2``` as input can be used to create all plots at once.

```{r, fig.height=7, fig.width=7, message=FALSE,error=FALSE,linewidth=90}
# Plot MadingleyR time lines
plot_timelines(mdata2)
```
\pagebreak

```{r, fig.height=7, fig.width=7, message=FALSE,error=FALSE,linewidth=90}
# Plot MadingleyR body mass density
plot_densities(mdata2)
```
\pagebreak

```{r, fig.height=7, fig.width=7, message=FALSE,error=FALSE,linewidth=90}
# Plot MadingleyR trophic pyramid
plot_trophicpyramid(mdata2)
```

\pagebreak

```{r, fig.height=6, fig.width=7, message=FALSE,error=FALSE,linewidth=90}
# Create MadingleyR log10-binned food-web plot
plot_foodweb(mdata2, max_flows = 5)
```

\pagebreak

```{r, fig.height=7, fig.width=9, message=FALSE,error=FALSE,linewidth=90}
# Plot MadingleyR spatial biomass
plot_spatialbiomass(mdata2, functional_filter = TRUE)
```




