taxa (version 0.1.0)

filter_taxa: Filter taxa with a list of conditions

Description

Filter taxa in a taxonomy() or taxmap() object with a series of conditions. Any variable name that appears in all_names() can be used as if it was a vector on its own. See dplyr::filter() for the inspiration for this function and more information. Calling the function using the obj$filter_taxa(...) style edits "obj" in place, unlike most R functions. However, calling the function using the filter_taxa(obj, ...) imitates R's traditional copy-on-modify semantics, so "obj" would not be changed; instead a changed version would be returned, like most R functions.

filter_taxa(obj, ..., subtaxa = FALSE, supertaxa = FALSE,
  drop_obs = FALSE, reassign_obs = TRUE, reassign_taxa = TRUE,
  invert = FALSE)
obj$filter_taxa(..., subtaxa = FALSE, supertaxa = FALSE,
  drop_obs = FALSE, reassign_obs = TRUE, reassign_taxa = TRUE,
  invert = FALSE)

Arguments

obj

An object of class taxonomy() or taxmap()

...

One or more filtering conditions. Any variable name that appears in all_names() can be used as if it was a vector on its own. Each filtering condition must resolve to one of three things:

  • character: One or more taxon IDs contained in obj$edge_list$to

  • integer: One or more row indexes of obj$edge_list

  • logical: A TRUE/FALSE vector of length equal to the number of rows in obj$edge_list

subtaxa

(logical or numeric of length 1) If TRUE, include subtaxa of taxa passing the filter. Positive numbers indicate the number of ranks below the target taxa to return. 0 is equivalent to FALSE. Negative numbers are equivalent to TRUE.

supertaxa

(logical or numeric of length 1) If TRUE, include supertaxa of taxa passing the filter. Positive numbers indicate the number of ranks above the target taxa to return. 0 is equivalent to FALSE. Negative numbers are equivalent to TRUE.

drop_obs

(logical) This option only applies to taxmap() objects. If FALSE, include observations even if the taxon they are assigned to is filtered out. Observations assigned to removed taxa will be assigned to NA. This option can be either simply TRUE/FALSE, meaning that all data sets will be treated the same, or a logical vector can be supplied with names corresponding one or more data sets in obj$data. For example, c(abundance = FALSE, stats = TRUE) would include observations whose taxon was filtered out in obj$data$abundance, but not in obj$data$stats. See the reassign_obs option below for further complications.

reassign_obs

(logical of length 1) This option only applies to taxmap() objects. If TRUE, observations assigned to removed taxa will be reassigned to the closest supertaxon that passed the filter. If there are no supertaxa of such an observation that passed the filter, they will be filtered out if drop_obs is FALSE. This option can be either simply TRUE/FALSE, meaning that all data sets will be treated the same, or a logical vector can be supplied with names corresponding one or more data sets in obj$data. For example, c(abundance = TRUE, stats = FALSE) would reassign observations in obj$data$abundance, but not in obj$data$stats.

reassign_taxa

(logical of length 1) If TRUE, subtaxa of removed taxa will be reassigned to the closest supertaxon that passed the filter. This is useful for removing intermediate levels of a taxonomy.

invert

(logical of length 1) If TRUE, do NOT include the selection. This is different than just replacing a == with a != because this option negates the selection after taking into account the subtaxa and supertaxa options. This is useful for removing a taxon and all its subtaxa for example.

Value

An object of type taxonomy() or taxmap()

See Also

Other taxmap manipulation functions: arrange_obs, arrange_taxa, filter_obs, mutate_obs, sample_frac_obs, sample_frac_taxa, sample_n_obs, sample_n_taxa, select_obs, transmute_obs

Examples

Run this code
# NOT RUN {
# Filter by index
filter_taxa(ex_taxmap, 1:3)

# Filter by taxon ID
filter_taxa(ex_taxmap, c("b", "c", "d"))

# Fiter by TRUE/FALSE
filter_taxa(ex_taxmap, taxon_names == "Plantae", subtaxa = TRUE)

# Filter by an observation characteristic
dangerous_taxa <- sapply(ex_taxmap$obs("info"),
                         function(i) any(ex_taxmap$data$info$dangerous[i]))
filter_taxa(ex_taxmap, dangerous_taxa)

# Include supertaxa
filter_taxa(ex_taxmap, 12, supertaxa = TRUE)
filter_taxa(ex_taxmap, 12, supertaxa = 2)

# Include subtaxa
filter_taxa(ex_taxmap, 1, subtaxa = TRUE)
filter_taxa(ex_taxmap, 1, subtaxa = 2)

# Dont remove rows in data corresponding to removed taxa
filter_taxa(ex_taxmap, 2, drop_obs = c(info = FALSE))

# Remove a taxon and it subtaxa
filter_taxa(ex_taxmap, 1, subtaxa = TRUE, invert = TRUE)

# }

Run the code above in your browser using DataCamp Workspace