---
title: Methods for updating taxon names in APCalign
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{updating taxon names}
  %\VignetteEncoding{UTF-8}
  %\VignetteEngine{knitr::rmarkdown}
editor_options:
  chunk_output_type: console
---

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

options(rmarkdown.html_vignette.check_title = FALSE)

library(APCalign)
library(readr)
library(dplyr)
library(here)

#' Format table with kable and default styling for html
#'
#' @param ... arguments passed to `kableExtra::kable()`
#' @importFrom rlang .data
#' @export
util_kable_styling_html <- function(...) {
  txt <-
    kableExtra::kable(...) %>%
    kableExtra::kable_styling(...,
      bootstrap_options = c("striped", "hover", "condensed", "responsive"),
      full_width = FALSE,
      position = "left"
    )

  # hack to add margin to plot
  gsub('style="width: auto ', 'style="margin-left:30px; width: auto ', txt)
}

my_kable_styling <- util_kable_styling_html

match_taxa_documentation <-
  readr::read_csv(
    system.file(
      file.path("extdata", "match_taxa_documentation.csv"),
      package = "APCalign"),
    show_col_types = FALSE
  )

update_taxonomy_documentation <-
  readr::read_csv(
    system.file(
      file.path("extdata", "update_taxonomy_documentation.csv"),
      package = "APCalign"),
    show_col_types = FALSE, skip = 1
  )


APCalign_outputs_documentation <-
  readr::read_csv(
    system.file(
      file.path("extdata", "APCalign_outputs_documentation.csv"),
      package = "APCalign"),
    show_col_types = FALSE
  )
```

# Aligning taxon names with taxon concepts/names in APC and APNI

The following table indicates the rules for each of the 51 separate algorithms sequentially applied to attempt to align each submitted name to a taxon concept in APC or scientific names in APNI.

Note, if the table is truncated on your screen, use horizontal scroll to view the entire table.

```{r, results='show'}
match_taxa_documentation %>%
  my_kable_styling()
```


# Updating taxonomy

The following table indicates the separate functions used to:  

- update aligned names to accepted names in the APC
- add best-practice suggested names to all submitted names 
- add identifiers to taxon concepts (in the APC) or scientific names (in the APC or APNI)

Different functions are used depending on the taxon rank of the aligned name and the taxonomic dataset to which the name was aligned (APC vs APNI).

```{r, results='show'}
update_taxonomy_documentation %>%
  my_kable_styling() %>%
  kableExtra::add_header_above(c(" " = 1, "categories of aligned names processed" = 4, "columns filled in" = 3))
```

-* genus updated to APC accepted genus if possible; ** species or infraspecific taxon name


# Outputs of APCalign

The following columns are output by the core function `create_taxonomic_update_lookup` and the two component functions `align_taxa` and `update_taxonomy`.

```{r, results='show'}
APCalign_outputs_documentation %>%
  my_kable_styling()
```