Match names that start or contain a specified text string
Usage
fuzzy_filter(
name,
by = c("scientificName", "vernacularName"),
provider = getOption("taxadb_default_provider", "itis"),
match = c("contains", "starts_with"),
version = latest_version(),
db = td_connect(),
ignore_case = TRUE,
collect = TRUE
)Arguments
- name
vector of names (scientific or common, see
by) to be matched against.- by
a column name in the taxa_tbl (following Darwin Core Schema terms). The filtering join is executed with this column as the joining variable.
- provider
from which provider should the hierarchy be returned? Default is 'itis', which can also be configured using
options(default_taxadb_provider=..."). See[td_create]for a list of recognized providers.- match
should we match by names starting with the term or containing the term anywhere in the name?
- version
Which version of the taxadb provider database should we use? defaults to latest. See tl_import for details.
- db
a connection to the taxadb database. See details.
- ignore_case
should we ignore case (capitalization) in matching names? Can be significantly slower to run.
- collect
logical, default
TRUE. Should we return an in-memory data.frame (default, usually the most convenient), or a reference to lazy-eval table on disk (useful for very large tables on which we may first perform subsequent filtering operations.)
Details
Note that fuzzy filter will be fast with an single or small number
of names, but will be slower if given a very large vector of
names to match, as unlike other filter_ commands,
fuzzy matching requires separate SQL calls for each name.
As fuzzy matches should all be confirmed manually in any event, e.g.
not every common name containing "monkey" belongs to a primate species.
This method utilizes the database operation %like% to filter tables without
loading into memory. Note that this does not support the use of regular
expressions at this time.
Examples
# \donttest{
## match any common name containing:
name <- c("woodpecker", "monkey")
fuzzy_filter(name, "vernacularName")
#> # A tibble: 254 × 15
#> taxonID scientificName taxonRank acceptedNameUsageID taxonomicStatus
#> <chr> <chr> <chr> <chr> <chr>
#> 1 ITIS:1025108 Simia lugens species ITIS:1025104 synonym
#> 2 ITIS:572943 Aotus azarai species ITIS:944172 synonym
#> 3 ITIS:572960 Lagothrix lagotri… species ITIS:944187 synonym
#> 4 ITIS:573068 Trachypithecus ve… species ITIS:944269 synonym
#> 5 ITIS:944307 Mycetes villosus species ITIS:572940 synonym
#> 6 ITIS:944311 Aotus gularis species ITIS:572952 synonym
#> 7 ITIS:944323 Ateles chuva species ITIS:572954 synonym
#> 8 ITIS:944325 Ateles fuliginosus species ITIS:572954 synonym
#> 9 ITIS:944329 Ateles subpentada… species ITIS:572953 synonym
#> 10 ITIS:944343 Callithryx chloro… species ITIS:612150 synonym
#> # ℹ 244 more rows
#> # ℹ 10 more variables: update_date <lgl>, kingdom <chr>, phylum <chr>,
#> # class <chr>, order <chr>, family <chr>, genus <chr>, specificEpithet <chr>,
#> # vernacularName <chr>, infraspecificEpithet <lgl>
## match scientific name
fuzzy_filter("Chera", "scientificName",
match = "starts_with")
#> # A tibble: 6 × 15
#> taxonID scientificName taxonRank acceptedNameUsageID taxonomicStatus
#> <chr> <chr> <chr> <chr> <chr>
#> 1 ITIS:1025106 Cheracebus torquat… species ITIS:1025106 accepted
#> 2 ITIS:1025107 Cheracebus lucifer species ITIS:1025107 accepted
#> 3 ITIS:1025110 Cheracebus purinus species ITIS:1025110 accepted
#> 4 ITIS:1025104 Cheracebus lugens species ITIS:1025104 accepted
#> 5 ITIS:1025111 Cheracebus regulus species ITIS:1025111 accepted
#> 6 ITIS:1025105 Cheracebus medemi species ITIS:1025105 accepted
#> # ℹ 10 more variables: update_date <lgl>, kingdom <chr>, phylum <chr>,
#> # class <chr>, order <chr>, family <chr>, genus <chr>, specificEpithet <chr>,
#> # vernacularName <chr>, infraspecificEpithet <lgl>
# }