Author: Marcelo Reginato

# Identification keys

#### Marcelo Reginato

In this tutorial we are going over basic steps to build two types of identification keys using monographaR: dichotomous keys (dichoKey and dichoKey.app) and an interactive key (interactiveKey).

## Preliminaries

### Loading the package

    library(monographaR)

### Working directory

    setwd("C:/My_working_directory")

### Input examples

Within monographaR there are examples of input formatted spreadsheets to use in both functions to build keys (dichoKey and interactiveKey). To load and visualize these models type:

    data("monographaR_examples")
    head(monographaR_examples$dichoKey)
    head(monographaR_examples$interactiveKey)

It is possible to export these models to open in other software (e.g., Excel). To export these models type:

    data("monographaR_examples")
    write.csv(monographaR_examples$dichoKey, file="dichoKey_model.csv", row.names=F)
    write.csv(monographaR_examples$interactiveKey, file="interactiveKey_model.csv", row.names=F)

## dichoKey

This function will generate a dichotomous key. It wraps around the function “rpart” from the package rpart (details here) to generate a more “taxonomic” styled key.

### Input

Importing the data

    read.csv("dichoKey_model.csv") -> dat

This is the format of the table:

X | Leaves | Leaf | Leaf.base | Inflorescences
--- | --- | --- | --- | ---
Pleiochiton amorimii | isophyllous | coriaceous | rounded/subcordate | with glandular trichomes
Pleiochiton blepharodes | isophyllous | chartaceous/membranous | obtuse/rounded | with glandular trichomes
Pleiochiton crassifolium | isophyllous | coriaceous | rounded/subcordate | with glandular trichomes
Pleiochiton ebracteatum | isophyllous | coriaceous | rounded/obtuse/subcordate | with glandular trichomes
Pleiochiton glaziovianum | isophyllous | coriaceous/chartaceous | rounded/subcordate | with glandular trichomes

If your dataset includes species with polymorphic characters (that is usually the case), first is necessary to format the data using the function “dataKey”. To use this function the user is required to provide what is the character used to indicate the polymorphics. In this example here I used a “/”. It is also possible to include characters with missing data, these should be as “NA”.

    ### First let's include the column name of the first column (where the species
    ### name is stored)
    colnames(dat)[1] <- "species"

    ### Now just run the function

    dataKey(dat, poly.sep = "/") -> dat.k

Percentage of spp. with polymorphic characters per character (initial): Leaves = 0 Leaf = 0.25 Leaf.base = 0.92 Inflorescences = 0.08 Flowers = 0.08 Inflorescence.position = 0.75 Bracteoles = 0 Bracteoles.shape = 0.67 Calyx.external.teeth = 0 Petal.shape = 0.75 Anther.colour = 0 Anther = 0 Anther.pore = 0 Seed.shape = 0.17 Ovary = 0.17 Percentage of spp. with polymorphic characters per character (final): Leaves = 0 Leaf = 0.25 Leaf.base = 0.92 Inflorescences = 0.08 Flowers = 0.08 Inflorescence.position = 0.75 Bracteoles = 0 Bracteoles.shape = 0.67 Calyx.external.teeth = 0 Petal.shape = 0.83 Anther.colour = 0 Anther = 0 Anther.pore = 0 Seed.shape = 0.58 Ovary = 0.25

    dat.k$dat -> dat.p

Notice that the function reports the percent of polymorphic characters (including the ones with missing data)

With the fully formatted matrix, now you can just run the function with the following command:

    dichoKey(dat.p) -> key

This is the output

    ## 1) Calyx external teeth twice as long as the hypanthium ........... Pleiochiton glaziovianum
    ## 1) Calyx external teeth up to 1.5 times as long as the hypanthium
    ##   2) Leaves isophyllous
    ##     3) Anther straight; anther pore ventral ........... Pleiochiton blepharodes
    ##     3) Anther curved; anther pore dorsal
    ##       4) Flowers in lax triads
    ##         5) Bracteoles shape lanceolate/ovate
    ##           7) Inflorescences with glandular trichomes
    ##             10) Leaf base rounded/subcordate/obtuse ........... Pleiochiton ebracteatum
    ##             10) Leaf base cordate ........... Pleiochiton micranthum
    ##           7) Inflorescences without glandular trichomes
    ##             11) Bracteoles shape lanceolate ........... Pleiochiton longipetiolatum
    ##             11) Bracteoles shape ovate ........... Pleiochiton magdalenense
    ##         5) Bracteoles shape oblong/cordate
    ##           8) Anther colour cream ........... Pleiochiton amorimii
    ##           8) Anther colour yellow
    ##             12) Leaf base cordate; ovary conical ........... Pleiochiton micranthum
    ##             12) Leaf base rounded/subcordate; ovary globose ........... Pleiochiton setulosum
    ##       4) Flowers in congested triads
    ##         6) Bracteoles covering the hypanthium ........... Pleiochiton crassifolium
    ##         6) Bracteoles not covering the hypanthium
    ##           9) Leaf chartaceous; inflorescences without glandular trichomes ........... Pleiochiton parvifolium
    ##           9) Leaf coriaceous; inflorescences with glandular trichomes ........... Pleiochiton roseum
    ##   2) Leaves anisophyllous ........... Pleiochiton parasiticum

    ### It is possible to check if there was any unresolved species

    ### which?

    key$unresolved

character(0)

    ### how many?

    length(key$unresolved)

[1] 0

### Export

To export the key as plain text just type the following command:

    cat(key$key, file="Pleiochiton_key.txt")

### Adding costs

It is possible to provide “costs” for each character used to build the key. In order to do that, it is required to provide a vector (numeric) with the cost values of each character, where the higher is the cost the lower will be its priority to build the key. Any type of cost scheme would be accepted. In this example let’s penalize the characters with more polymorphic/missing data (increasing their costs in relation to the other characters).

    ## The percent of polymorphic spp. for each character was generated before
    ## (dataKey) and stored in theobject 'dat.k'

    dat.k$summary

                Leaves                   Leaf              Leaf.base
                  0.00                   0.25                   0.92
        Inflorescences                Flowers Inflorescence.position
                  0.08                   0.08                   0.75
            Bracteoles       Bracteoles.shape   Calyx.external.teeth
                  0.00                   0.67                   0.00
           Petal.shape          Anther.colour                 Anther
                  0.83                   0.00                   0.00
           Anther.pore             Seed.shape                  Ovary
                  0.00                   0.58                   0.25

    ((dat.k$summary) + 1) -> dat.c
    colnames(dat.p)

[1] “species” “Leaves” “Leaf”
[4] “Leaf.base” “Inflorescences” “Flowers”
[7] “Inflorescence.position” “Bracteoles” “Bracteoles.shape”
[10] “Calyx.external.teeth” “Petal.shape” “Anther.colour”
[13] “Anther” “Anther.pore” “Seed.shape”
[16] “Ovary”

    dat.c[2] <- max(dat.c)
    dat.c[11] <- max(dat.c)

    dichoKey(dat.p, dat.c, cp = 0) -> key.c
    length(key.c$unresolved)

[1] 0

    # Export

    cat(key.c$key, file = "Pleiochiton_key_costs.txt")

## dichoKey.app

This function is a shiny app that runs the function “dichoKey” in the background. It allows the user to easily subset the data (taxa and characters), as well as change the cost values of the characters. To open the App just type:

    dichoKey.app()

Then you can select a csv file (formmated similarly to “monographaR_examples$dichoKey”). Here is a demo video showing how to use the function:

## interactiveKey

This function will generate all the necessary files to build a “shiny app” that includes the interactive key. This “app” can be executed locally (see bellow) or online. To deploy online your app see details in shiny.

### Input

Importing the data

    read.csv("interactiveKey_model.csv") -> dat

This is the table format:

Group | Character | Pleiochiton.amorimii | Pleiochiton.blepharodes | Pleiochiton.crassifolium
--- | --- | --- | --- | ---
Leaves | texture | coriaceous | chartaceous/membranous | coriaceous
Leaves | size | isophyllous | isophyllous | isophyllous
Inflorescences | indumentum | with glandular trichomes | with glandular trichomes | with glandular trichomes
Inflorescences | position | terminal/lateral | lateral | terminal
Bracteoles | position | not covering the hypanthium | not covering the hypanthium | covering the hypanthium

If your dataset includes taxa with polymorphic characters (usually does), make sure you have a special character separating polymorphisms. In this example polymorphic characters are separed by a “/”.

### Labels

Before running the function to build the app, first we need to run an accessory function to generate standard “labels” for the three different types included in the function (families, genera, species). This is done with the function “interactiveKeyLabels”, which generates model labels in english and portuguese. In the next example, my characters are in english and this was supposed to be a key for species identification, thus the following code applies:

    interactiveKeyLabels(taxon = "species", language = "english") -> spp.eng.labs

    ### It would be possible to export the object 'spp.eng.labs' (e.g., with
    ### write.csv), change the labels accordingly and import it again to use in the
    ### next step

    ### Let's change the 'title' (default is 'My taxon')

    head(spp.eng.labs)
    spp.eng.labs[3] <- "Pleiochiton"
    head(spp.eng.labs)

### Generate the app

With the formatted matrix and labels, now it is possible to generate the required files for the interactive key shiny app to work. This is done with the following command:

    interactiveKey(dat = dat, txt.labels = spp.eng.labs, poly.sep = "/", taxa.in.italics = TRUE,
        theme = "lumen")

If everything went smoothly, this command will generate in your working directory the following files:

- about.Rmd
- app.R
- Dat_characters.csv
- Dat_matrix.csv
- Dat_matrix_missing.csv
- server.R
- ui.R

### Open the app

To open and test the app, in Rstudio go to “File” “Open file” e select the file “app.R”. When this file is opened, a new option (“Run App”) will become availble in the upper right corner. To start the app just click in that button and a new window with the app will pop up.

The app:

See other “theme” options in shinythemes.

### About

The file “about.Rmd” should be edited (include there whatever you feel deserves to be there). Editing can be done in a simple text editor or in Rstudio. To edit it in Rstudio, go to “File” “Open file” e select the file. After finishing editing, you can check how it will be compiled. Just click in “Knit”.

### Demo

Here is a demo video showing how to use the function:

### Example

Here is an example of an interactive key that was build with this function:

Chamaecrista