Identification keys

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)

Input

Importing the data

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

This is the format of the table:

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")

Input

Importing the data

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

This is the table format:

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