Add vignettes. closes #311 closes #326 closes #322

Add all authors to DESCRIPTION

DESCRIPTION

@@ -15,7 +15,14 @@ Authors@R: c(
     comment = c(ORCID = '0000-0002-4716-6134')),
   person(c('Richard'), 'Schuster',
     email='[email protected]', role = c('aut'),
-    comment = c(ORCID = '0000-0003-3191-7869')))
+    comment = c(ORCID = '0000-0003-3191-7869')),
+  person(c('Joseph'), 'Bennett', role = c('aut')),
+  person(c('Jaimie'), 'Vincent', role = c('aut')),
+  person(c('Dan'), 'Wismer',
+    email='[email protected]', role = c('cre')),
+  person(c('Marc'), 'Edwards',
+    email='[email protected]', role = c('cre'))
+    )
 Imports:
     utils,
     stats,

vignettes/.gitignore

@@ -0,0 +1,2 @@
+*.html
+*.R

vignettes/articles/methods-in-ecology-and-evolution.csl

@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="utf-8"?>
+<style xmlns="http://purl.org/net/xbiblio/csl" version="1.0" default-locale="en-US">
+  <!-- British Ecological Society, generated from "bes" metadata at https://github.com/citation-style-language/journals -->
+  <info>
+    <title>Methods in Ecology and Evolution</title>
+    <id>http://www.zotero.org/styles/methods-in-ecology-and-evolution</id>
+    <link href="http://www.zotero.org/styles/methods-in-ecology-and-evolution" rel="self"/>
+    <link href="http://www.zotero.org/styles/apa" rel="independent-parent"/>
+    <link href="http://besjournals.onlinelibrary.wiley.com/hub/journal/10.1111/(ISSN)2041-210X/author-guidelines.html" rel="documentation"/>
+    <category citation-format="author-date"/>
+    <category field="biology"/>
+    <issn>2041-210X</issn>
+    <updated>2020-12-15T13:52:02+00:00</updated>
+    <rights license="http://creativecommons.org/licenses/by-sa/3.0/">This work is licensed under a Creative Commons Attribution-ShareAlike 3.0 License</rights>
+  </info>
+</style>

vignettes/articles/references.bib

@@ -0,0 +1,26 @@
+@incollection{r1,
+  author = {Ball, I.R. and Possingham, Hugh and Watts, Matthew E.},
+  title = {{Marxan and relatives: Software for spatial conservation prioritisation}},
+  booktitle = {{Spatial Conservation Prioritisation: Quantitative Methods \& Computational Tools}},
+  editor = {Moilanen, A. and Wilson, Kerrie A. and Possingham, Hugh},
+  publisher = {Oxford University Press},
+  address = {Oxford, UK},
+  pages = {185-189},
+  year = {2009},
+}
+
+@book{r2,
+  title = {{Conservation Planning: Informed Decisions for a Healthier Planet}},
+  author = {Groves, C.R. and Game, E.T.},
+  year = {2016},
+  publisher = {Roberts and Company Publishers, Inc},
+  pages = {580},
+}
+
+@software{r3,
+  author = {Hanson, J.O. and Schuster, R. and Morrell, N. and Strimas-Mackay, M. and Watts, M.E. and Arcese, P. and Bennett, J. and Possingham, H.P.},
+  title = { Systematic Conservation Prioritization in R},
+  url = {https://prioritizr.net/},
+  version = {8.0.2.5},
+  year = {2023},
+}

vignettes/articles/wtw_data.Rmd

@@ -0,0 +1,134 @@
+---
+title: "Data"
+output:
+  html_document:
+    toc: true
+    fig_caption: true
+    toc_float: true
+    number_sections: true
+---
+
+# Introduction
+
+Input data for Where to Work needs to be summarized by planning unit during the 
+data-prep stage. We strongly recommend using the 4-file input format described in
+[wtw-data-prep](https://github.com/NCC-CNC/wtw-data-prep) with raster planning units,
+or shapefile planning units if planning units of different shapes and sizes are 
+required.
+
+As described in the Goals section of the [wtw-theory](theory.html#goals) article, Where to Work
+operates on the values assigned to each planning unit. Planning unit
+values for Themes, Weights, Includes and Excludes therefore need to be carefully
+prepared before feeding the planning units into Where to Work. 
+
+The correct way to summarize the input data depends on the
+planning unit type (i.e. equal area vs different areas), the units of the input data 
+(i.e. area/distance/count, other units, unitless), and the type of layer being 
+summarized (i.e. Theme, Weight or Include/Exclude).
+
+Planning unit values can generally be of two types: binary, where all the values
+are either zero or one; or continuous, where any value is possible. Generally we 
+recommend that all Includes and Excludes use binary values, and all Themes and 
+Weights use continuous values. This is explained further below.
+
+# Themes
+
+The important thing to remember for Themes is that each Theme will be assigned a
+Goal, and Where to Work will attempt to meet the Goal by summing the Themes values
+across all planning units in a solution. Values therefore need to be numeric, have 
+specific units (e.g. km, km2, tonnes of carbon ect.), and ideally we would like to 
+retain as much detail from the source data as possible when we summarize the data 
+into the planning units.
+
+#### Area/distance/count
+
+Most Themes will be layers representing area, distance or count data. Examples 
+are species ranges (area), lengths of rivers (distance), and points representing
+important sites (count). We recommend simply summing the area/distance/count of
+these data in each planning unit.
+
+```{r echo = FALSE, fig.cap = "*Fig 1. Species ranges representing areas of presence/absence are converted into plannnig unit values representing the area of each planning unit covered by the species range.*"}
+knitr::include_graphics("figures/species_range.png")
+```
+
+
+In the case of species range data, we could set a threshold (e.g. 50%) and assign 
+each planning unit to presence/absence based on the overlap with the 
+planning unit and the threshold (i.e. every planning unit would have a value of either
+zero, or the full planning unit area). This approach creates clean maps that look
+nicer in the Where to Work display. However, summing the area retains more information,
+especially in cases where some range polygons are smaller than the planning units.
+
+#### Other units
+
+Other layers could have non-area/distance/count units that will need to be considered
+on a layer-by-layer basis. A dataset detailing tonnes of Carbon per pixel for example
+could be summed to calculate the tonnes of Carbon per planning unit. Remember that 
+Where to Work will run using any input layer values, so the responsibility
+is on the user to make sure the values provided are suitable.
+```{r echo = FALSE, fig.cap = "*Fig 2. A raster layer representing tonnes of Carbon can be summed into the planning units and can retain the same units.*"}
+knitr::include_graphics("figures/carbon.png")
+```
+
+
+#### Unitless/non-numeric values
+
+If users want to inlcude Themes from input data that do not have units, or are 
+categorical, it is usually best to convert the source data into polygons and use
+the area approach described above. Here are some common examples:
+
+1. **Categorical land cover data** - extract each land cover type as a separate 
+Theme and calculate it's area in each planning unit.
+
+2. **Species probability maps** - these are not recommended because they are unitless.
+Additionally, while Where to Work would run using probability values, it can result
+in solutions that meet the Goal by collecting lots of planning units with low
+probability values which is this case represents low quality habitat. This is not
+really what we want, it would be better to meet the target with higher quality 
+habitat only. The best approach is to choose a threshold and convert the habitat 
+probability into a binary map of high quality habitat. This can then be treated 
+as an area layer and the planning unit values will represent the area of high 
+quality habitat.
+
+
+# Weights
+
+Ideally, data-prep for Weights should follow the same guidelines as Themes,
+however since Weights do not have Goals attached to them there is some additional
+flexibility. Unitless Weights can be used for example, as long as the values
+are numeric.
+
+If planning units are all the same size, it may be appropriate to calculate the mean
+Weight value per planning unit. However, where possible we still recommend summing
+values, especially if planning units are of different sizes. This is because Where
+to Work does not account for planning unit area when processing Weights. If a
+larger planning unit should have a relatively higher Weight than a smaller one,
+this should be accounted for during data prep (e.g. by summing rather than averaging).
+
+```{r echo = FALSE, fig.cap = "*Fig 3. Connectivity is a unitless Weight. Here we calculate the average connectivity value per planning unit, but if planning units were of different sizes we might consider summing.*"}
+knitr::include_graphics("figures/connectivity.png")
+```
+
+
+# Includes/Excludes
+
+The guidelines for Includes and Excludes are different because every planning unit
+needs to be either locked-in or locked-out of the solution. Values should therefore
+be binary where each planning unit has a value of zero or one. This means that for
+source data representing areas, users will need to decide thresholds to determine 
+if planning units are assigned as zero or one depending on the overlap of the 
+planning unit with the source layer. Using a 50% threshold for areas is generally
+recommended because it should average out to cover approximately the same area as 
+the input data. In some cases users might want to use a different approach. For 
+example an Include could be set to one if any of the planning unit intersects with 
+the source layer.
+
+```{r echo = FALSE, fig.cap = "*For n includes of existing protected areas, we use an area threshold of 50% so any planning unit with >= 50% coverage is assigned a 1, otherwise it's assigned a 0.*"}
+knitr::include_graphics("figures/includes.png")
+```
+
+# Data prep
+
+More information on data prep as well as scripts for preparing input data of various
+formats can be found in [the wtw-data-prep](https://github.com/NCC-CNC/wtw-data-prep) 
+github repo.