A photo key to Montana’s broadleaf trees

Make your own key in three steps

The key is an ordinary CSV file, so the quickest way to write a key of your own is to start from a copy of it:

1. Copy the template. It ships with dimoose, next to its photos:

   template <- system.file("extdata", "montana", package = "dimoose")
   dir.create("~/my-key")
   file.copy(template, "~/my-key", recursive = TRUE)   # makes ~/my-key/montana/

2. Edit it in Excel, Numbers or Google Sheets. One row per lead:

   Column	What goes in it
   Couplet	The couplet’s number.
   Choice	Optional: a, b, …; left blank, the leads are lettered in order.
   Question	Optional: what the couplet asks, such as “Leaf type?”.
   Description	What the lead says.
   Goes to	The next couplet, or blank when the lead names a species.
   Species	The result, written “Common name (Genus species)”.
   Photo	Optional: photo file names in the same folder, separated by ;.

   Put your photos in the same folder and save the sheet as CSV.

3. Build the key and look at it:

   library(dimoose)
   k <- keyFromSpreadsheet("~/my-key/montana/montana-key.csv", desc = "My key")
   k$validate()                       # lists any couplet that is never reached, etc.
   keyDiagram(k, "my-key.svg")        # a printable diagram
   exportWizard(k, "my-key.html")     # an interactive key for phones and browsers

If a row points to a couplet that is not in the sheet, or names a photo that is not in the folder, keyFromSpreadsheet() says which spreadsheet row to fix.

To check the species names too, add checkNames = TRUE. dimoose then looks each scientific name up in the GBIF backbone taxonomy (this needs an internet connection) and warns about names that are misspelled, are outdated synonyms, or are not known at all, again by row. The Montana names all pass; a sheet with two mistakes would give:

k <- keyFromSpreadsheet("~/my-key/montana/montana-key.csv", checkNames = TRUE)
#> Warning: Some species names do not match GBIF:
#> Row 5: Fraxinus pensylvanica is not in GBIF; did you mean Fraxinus pennsylvanica?
#> Row 9: Ulmus fulva is a synonym; GBIF accepts Ulmus rubra

checkNames(k) gives the same check as a table.

The Montana key

library(dimoose)
k <- montanaKey()
k
#> <dimoose key> Key to the native broadleaf trees of Montana
#>   10 couplets, 20 leads, 11 taxa, up to 7 steps deep

montanaKey() is keyFromSpreadsheet() applied to the template above. Its first rows:

csv <- system.file("extdata", "montana", "montana-key.csv", package = "dimoose")
head(read.csv(csv, check.names = FALSE), 4)
#>   Couplet Choice   Question
#> 1       1      a Leaf type?
#> 2       1      b Leaf type?
#> 3       2      a  Leaflets?
#> 4       2      b  Leaflets?
#>                                                                                  Description
#> 1                                           Leaves compound, divided into separate leaflets.
#> 2                                                             Leaves simple, a single blade.
#> 3 Leaves opposite, with 3 (rarely 5) leaflets that have a few coarse teeth or shallow lobes.
#> 4                                Leaves opposite, with 5 to 7 leaflets with toothed margins.
#>   Goes to                            Species                           Photo
#> 1       2                                    fraxinus_pennsylvanica_leaf.jpg
#> 2       3                                         populus_deltoides_leaf.jpg
#> 3      NA           Box elder (Acer negundo)           acer_negundo_leaf.jpg
#> 4      NA Green ash (Fraxinus pennsylvanica) fraxinus_pennsylvanica_leaf.jpg

Every species was checked as native to Montana in the Montana Field Guide and USDA PLANTS. Common hackberry is left out because the Montana Field Guide gives its origin in the state as undetermined, and American elm because it is planted rather than native. The characters in each couplet come from the Montana Field Guide’s descriptions and, for leaf stalks and buds, the Virginia Tech Dendrology fact sheets; ?montana lists the sources. The 14 photos are from Wikimedia Commons, most of them taken in Montana by Matt Lavin; their authors and licenses are in the package’s COPYRIGHTS file.

A diagram of the key

keyDiagram() draws any key top-down: each question in a blue box, its leads below it, and each species in a green box with its photo.

keyDiagram(k, "montana-key.svg")

An interactive key

exportWizard() writes the same key as a single web page that asks one question at a time and shows the photos with each answer. It works offline, so it can be copied to a phone and used in the field.

page <- tempfile(fileext = ".html")
exportWizard(k, page)

Open the file in a browser to try it.

Checking a photo against the key

If you have a photo and want a second opinion, a vision model trained on organisms can rank the key’s eleven species by how well they match it. BioCLIP 2 knows many species by their scientific name, so it needs no example photos (see ?visionModel; the first call downloads the model, about 1.7 GB):

model <- visionModel(name = "bioclip-2")
suggestSpecies(k, model, "my-tree.jpg", top = 3)

Only the key’s own species are ranked. For one answer per photo, use identifyPhotos(): when no species reaches the confidence you ask for (0.8 by default), it adds up the probabilities of the species in each genus, then family and order (looked up in GBIF), and answers with the most precise group that reaches it.

identifyPhotos(k, model, "my-tree.jpg", kingdom = "Plantae")

Treat the answer as a hint and confirm it by working through the key: the model can be wrong, especially on close relatives such as the cottonwoods.

Diagrams of other keys

keyDiagram() works on every dimoose key, whichever way it was made. Here is the key to the orders of Arachnida, transcribed from a textbook:

keyDiagram(arachnidaKey(), "arachnida.svg")