--- title: "From a published key to a field key" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{From a published key to a field key} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r, include = FALSE} knitr::opts_chunk$set(collapse = TRUE, comment = "#>") options(width = 100) ``` Most keys already exist: as text in a flora, a revision or a field guide. This vignette takes one from the printed page to a phone in five steps: read the text, check it, cut it down to the place you work in, see how quickly it reaches a result, and export it as a page that opens without signal. The steps that ask a web service (GBIF) are shown with the output of a run on 19 November 2026 and are not run when the vignette is built. Everything else runs as written. ```{r} library(dimoose) ``` ## 1. Read the text The example is a short key to the broadleaf trees of a river bottom, written for dimoose in the layout of a regional flora: numbered couplets with `a` and `b` leads, dot leaders, wrapped lines, authorities, common names and page references. ```{r} file <- system.file("extdata", "textkeys", "trees-bracketed.txt", package = "dimoose") writeLines(readLines(file)[1:11]) ``` `keyFromText()` takes a file, one string or a vector of lines: ```{r} trees <- keyFromText(file) trees trees$leads[1:6, c("Statement", "Choice", "Character", "Next", "Taxon", "CommonName")] ``` Each lead's destination is a couplet number or a taxon. The authority, the common name and the page are split off into columns of their own, so `Taxon` holds the bare name. It also reads leads marked `1.`/`1'.`, `A.`/`AA.`, a number and a dash, back-references such as `3(1).`, and indented keys. Indented keys whose leads have no number or letter at all are not handled. ## 2. Check it `keyFromText()` checks what it built and keeps a report with the key. Here the only entry is a note: a word hyphenated at a line end was joined. ```{r} trees$validate() # no structural problems attr(trees, "problems") ``` Scanned text is rougher. `parseTextKey()` gives the lead table and the report without building the key, which is the place to start with a scan. This one has a `l` where a `1` should be and a lead that lost its dot leaders: ```{r} scan <- system.file("extdata", "textkeys", "meadow-ocr.txt", package = "dimoose") parseTextKey(scan) ``` Repairs are reported, never silent, and `strict = TRUE` stops instead of repairing. A lead with no destination, a couplet with one lead or a missing couplet is a problem, reported with its line; no lead is dropped. These checks were written against keys made for the purpose; expect to correct a few lines by hand on a real scan. A printed key's names may be out of date. `checkNames()` looks them up in the GBIF backbone taxonomy: ```{r, eval = FALSE} checkNames(trees, kingdom = "Plantae")[, c("Taxon", "status", "accepted")] #> Taxon status accepted #> 1 Acer glabrum ok Acer glabrum #> 2 Acer negundo ok Acer negundo #> 3 Fraxinus pennsylvanica ok Fraxinus pennsylvanica #> 4 Salix ok Salix #> 5 Betula papyrifera ok Betula papyrifera #> 6 Betula occidentalis ok Betula occidentalis #> 7 Populus tremuloides ok Populus tremuloides #> 8 Populus angustifolia ok Populus angustifolia #> 9 Populus balsamifera subsp. trichocarpa synonym Populus trichocarpa ``` ## 3. Cut it down to a place A regional flora covers more than any one county. `regionalKey()` asks GBIF which of the key's taxa have been recorded in a place, drops the others, and closes up the couplets that no longer split anything. Here the place is Flathead County, Montana, by its GADM id, and a taxon needs five records to stay: ```{r, eval = FALSE} local <- regionalKey(trees, "USA.27.15_1", kingdom = "Plantae", minRecords = 5, renumber = TRUE) #> Kept 8 of 9 taxa recorded in GADM region USA.27.15_1 (GBIF) attr(local, "records")[, c("Taxon", "records", "kept")] #> Taxon records kept #> 1 Acer glabrum 272 TRUE #> 2 Acer negundo 11 TRUE #> 3 Fraxinus pennsylvanica 1 FALSE #> 4 Salix 348 TRUE #> 5 Betula papyrifera 70 TRUE #> 6 Betula occidentalis 13 TRUE #> 7 Populus tremuloides 93 TRUE #> 8 Populus angustifolia 7 TRUE #> 9 Populus balsamifera subsp. trichocarpa 56 TRUE ``` The table is the audit trail: every taxon, the number of records and whether it was kept. A place can also be a name (`"Flathead County, Montana"`), a two-letter country code or a polygon, and `source = "inat"` counts iNaturalist research-grade observations instead. With the default `minRecords = 1` all nine taxa of this key stay. Record counts say where people have looked as much as what grows there, so read the table before trusting the cut. `pruneKey()` makes the same cut from a list of names, with no web service. So that the rest of this vignette runs offline, it is used here to drop the one taxon GBIF dropped above: ```{r} local <- pruneKey(trees, drop = "Fraxinus pennsylvanica", renumber = TRUE) local local$validate() local$leads[1:4, c("Statement", "Character", "Next", "Taxon", "Note")] ``` Couplet 3 of the original told box elder from green ash. With green ash gone it no longer splits anything, so it was removed and its lead now ends at box elder directly. What it said about box elder is kept in the `Note` column, as a character to confirm the result with. `mergeKeys()` goes the other way and grafts a second key onto a result, for example a key to the willows onto *Salix*. ## 4. How quickly does it reach a result? ```{r} summary(local)[c("couplets", "taxa", "depth", "meanTaxonSteps", "bound", "efficiency")] ``` `meanTaxonSteps` is the number of couplets a reader answers, on average over the eight taxa. `bound` is what the best possible key to the same taxa would need: eight equally common taxa cannot be told apart in fewer than three two-way steps. `efficiency` is the bound over the steps taken. The taxa are not equally likely, though. Weighted by the record counts above (which `occurrenceWeights(local, region = "USA.27.15_1", kingdom = "Plantae")` fetches in one call), the key does better than its plain average, because the two commonest taxa key out in two steps: ```{r} w <- c("Acer glabrum" = 272, "Acer negundo" = 11, "Salix" = 348, "Betula papyrifera" = 70, "Betula occidentalis" = 13, "Populus tremuloides" = 93, "Populus angustifolia" = 7, "Populus balsamifera subsp. trichocarpa" = 56) summary(local, weights = w)[c("meanTaxonSteps", "expectedSteps", "bound", "efficiency")] q <- keyQuality(local, weights = w)$taxa q[order(-q$weight), c("Taxon", "steps", "weight")] ``` Real keys rarely reach an efficiency of 1, because the characters that would split the taxa evenly may not exist. Use it to compare keys to the same taxa, not as a mark out of one. ## 5. Take it into the field ```{r} site <- file.path(tempdir(), "site") dir.create(site, showWarnings = FALSE) page <- exportWizard(local, file.path(site, "flathead-trees.html"), offline = TRUE) list.files(site) ``` `flathead-trees.html` is the whole key in one file: it asks one couplet at a time, has an "I'm not sure" choice that follows both leads, a map of the key, and Back. `offline = TRUE` adds a web app manifest, a service worker and two icons. Put all five files in one folder of an `https` website, open the page once on the phone while it has a connection, and add it to the home screen; after that it opens without signal. A page opened straight from disk works too, but is not installed. The offline part has been tested with a simulated browser and not yet on a phone, so try it before you rely on it. To correct a lead or add photos, write the key out as the spreadsheet `keyFromSpreadsheet()` reads, edit it, and read it back (see `vignette("montana-hardwoods")`): ```{r} csv <- keyToSpreadsheet(local, file.path(site, "flathead-trees.csv")) back <- keyFromSpreadsheet(csv, desc = "Trees of Flathead County") back ``` The spreadsheet keeps the leads and their photos; the title and the extra columns (`Note`, `Authority`, `CommonName`, `Page`) are not written.