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:573055 Pygathrix bieti species ITIS:944259 synonym
#> 2 ITIS:944191 Oreonax flavicauda species ITIS:572961 synonym
#> 3 ITIS:944216 Chlorocebus cynosu… species ITIS:944445 synonym
#> 4 ITIS:944298 Simia beelzebub species ITIS:572935 synonym
#> 5 ITIS:944300 Mycetes flavimanus species ITIS:572935 synonym
#> 6 ITIS:944303 Mycetes niger species ITIS:572939 synonym
#> 7 ITIS:944310 Nyctipithecus feli… species ITIS:572951 synonym
#> 8 ITIS:944315 Aotus senex species ITIS:572946 synonym
#> 9 ITIS:944321 Ateles braccatus species ITIS:572954 synonym
#> 10 ITIS:944349 Jacchus grandis 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:1025104 Cheracebus lugens species ITIS:1025104 accepted
#> 2 ITIS:1025111 Cheracebus regulus species ITIS:1025111 accepted
#> 3 ITIS:1025107 Cheracebus lucifer species ITIS:1025107 accepted
#> 4 ITIS:1025110 Cheracebus purinus species ITIS:1025110 accepted
#> 5 ITIS:1025106 Cheracebus torquat… species ITIS:1025106 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>
# }