Skip to contents

Creates a data frame with column name given by by, and values given by the vector x, and then uses this table to do a filtering join, joining on the by column to return all rows matching the x values (scientificNames, taxonIDs, etc).

Source: R/filter_by.R
filter_by.Rd

Creates a data frame with column name given by by, and values given by the vector x, and then uses this table to do a filtering join, joining on the by column to return all rows matching the x values (scientificNames, taxonIDs, etc).

Usage

filter_by(
  x,
  by,
  provider = getOption("taxadb_default_provider", "itis"),
  schema = c("dwc", "common"),
  version = latest_version(),
  collect = TRUE,
  db = td_connect(),
  ignore_case = FALSE
)

Arguments

x

a vector of values to filter on

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.

schema

One of "dwc" (for Darwin Core data) or "common" (for the Common names table.)

version

Which version of the taxadb provider database should we use? defaults to latest. See tl_import for details.

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

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.

Value

a data.frame in the Darwin Core tabular format containing the matching taxonomic entities.

See also

Other filter_by: filter_common(), filter_id(), filter_name(), filter_rank()

Examples

# \donttest{
  # \dontshow{
   ## All examples use a temporary directory
   Sys.setenv(TAXADB_HOME=file.path(tempdir(), "taxadb"))
   options("taxadb_default_provider"="itis_test")
  # }

sp <- c("Trochalopteron henrici gucenense",
        "Trochalopteron elliotii")
filter_by(sp, "scientificName")
#> # A tibble: 0 × 15
#> # ℹ 15 variables: taxonID <chr>, scientificName <chr>, taxonRank <chr>,
#> #   acceptedNameUsageID <chr>, taxonomicStatus <chr>, update_date <lgl>,
#> #   kingdom <chr>, phylum <chr>, class <chr>, order <chr>, family <chr>,
#> #   genus <chr>, specificEpithet <chr>, vernacularName <chr>,
#> #   infraspecificEpithet <lgl>

filter_by(c("ITIS:1077358", "ITIS:175089"), "taxonID")
#> # A tibble: 0 × 15
#> # ℹ 15 variables: taxonID <chr>, scientificName <chr>, taxonRank <chr>,
#> #   acceptedNameUsageID <chr>, taxonomicStatus <chr>, update_date <lgl>,
#> #   kingdom <chr>, phylum <chr>, class <chr>, order <chr>, family <chr>,
#> #   genus <chr>, specificEpithet <chr>, vernacularName <chr>,
#> #   infraspecificEpithet <lgl>

filter_by("Aves", "class")
#> # A tibble: 0 × 15
#> # ℹ 15 variables: taxonID <chr>, scientificName <chr>, taxonRank <chr>,
#> #   acceptedNameUsageID <chr>, taxonomicStatus <chr>, update_date <lgl>,
#> #   kingdom <chr>, phylum <chr>, class <chr>, order <chr>, family <chr>,
#> #   genus <chr>, specificEpithet <chr>, vernacularName <chr>,
#> #   infraspecificEpithet <lgl>

# }