|
79 | 79 | #' \item \code{\link{ncbi_taxon_sample}} |
80 | 80 | #' } |
81 | 81 | #' |
| 82 | +#' @section Main classes: |
| 83 | +#' |
| 84 | +#' These are the classes users would typically interact with: |
| 85 | +#' |
| 86 | +#' * [taxon]: A class used to define a single taxon. Many other classes in the |
| 87 | +#' `taxa`` package include one or more objects of this class. |
| 88 | +#' * : Stores one or more [taxon] objects. This is just a thin wrapper |
| 89 | +#' for a list of [taxon] objects. |
| 90 | +#' * [hierarchy]: A class containing an ordered list of [taxon] objects that |
| 91 | +#' represent a hierarchical classification. |
| 92 | +#' * [hierarchies]: A list of taxonomic classifications. This is just a thin wrapper |
| 93 | +#' for a list of [hierarchy] objects. |
| 94 | +#' * [taxonomy]: A taxonomy composed of [taxon] objects organized in a tree |
| 95 | +#' structure. This differs from the [hierarchies] class in how the [taxon] |
| 96 | +#' objects are stored. Unlike a [hierarchies] object, each unique taxon is |
| 97 | +#' stored only once and the relationships between taxa are stored in an |
| 98 | +#' edgelist. |
| 99 | +#' * [taxmap]: A class designed to store a taxonomy and associated |
| 100 | +#' user-defined data. This class builds on the [taxonomy] class. User defined |
| 101 | +#' data can be stored in the list `obj$data`, where `obj` is a taxmap |
| 102 | +#' object. Any number of user-defined lists, vectors, or tables mapped |
| 103 | +#' to taxa can be manipulated in a cohesive way such that relationships |
| 104 | +#' between taxa and data are preserved. |
| 105 | +#' |
| 106 | +#' @section Minor classes: |
| 107 | +#' |
| 108 | +#' These classes are mostly components for the larger classes above and would |
| 109 | +#' not typically be used on their own. |
| 110 | +#' |
| 111 | +#' * [taxon_database]: Used to store information about taxonomy databases. |
| 112 | +#' * [taxon_id]: Used to store taxon IDs, either arbitrary or from a |
| 113 | +#' particular taxonomy database. |
| 114 | +#' * [taxon_name]: Used to store taxon names, either arbitrary or from a |
| 115 | +#' particular taxonomy database. |
| 116 | +#' * [taxon_rank]: Used to store taxon ranks (e.g. species, family), either |
| 117 | +#' arbitrary or from a particular taxonomy database. |
| 118 | +#' |
| 119 | +#' @section Major manipulation functions: |
| 120 | +#' |
| 121 | +#' These are some of the more important functions used to filter data in classes |
| 122 | +#' that store multiple taxa, like [hierarchies], [taxmap], and [taxonomy]. |
| 123 | +#' |
| 124 | +#' * [filter_taxa]: Filter taxa in a [taxonomy] or [taxmap] object with a |
| 125 | +#' series of conditions. Relationships between remaining taxa and user-defined |
| 126 | +#' data are preserved (There are many options controlling this). |
| 127 | +#' * [filter_obs]: Filter user-defined data [taxmap] object with a series of |
| 128 | +#' conditions. Relationships between remaining taxa and user-defined data are |
| 129 | +#' preserved (There are many options controlling this); |
| 130 | +#' * [sample_n_taxa]: Randomly sample taxa. Has same abilities as |
| 131 | +#' [filter_taxa]. |
| 132 | +#' * [sample_n_obs]: Randomly sample observations. Has same abilities as |
| 133 | +#' [filter_obs]. |
| 134 | +#' * [mutate_obs]: Add datasets or columns to datasets in the `data` list of |
| 135 | +#' [taxmap] objects. |
| 136 | +#' * [pick]: Pick out specific taxa, while others are dropped in [hierarchy] |
| 137 | +#' and [hierarchies] objects. |
| 138 | +#' * [pop]: Pop out taxa (drop them) in [hierarchy] and [hierarchies] objects. |
| 139 | +#' * [span]: Select a range of taxa, either by two names, or relational |
| 140 | +#' operators in [hierarchy] and [hierarchies] objects. |
| 141 | +#' |
| 142 | +#' @section Mapping functions: |
| 143 | +#' |
| 144 | +#' There are lots of functions for getting information for each taxon. |
| 145 | +#' |
| 146 | +#' * [subtaxa]: Return data for the subtaxa of each taxon in an [taxonomy] or |
| 147 | +#' [taxmap] object. |
| 148 | +#' * [supertaxa]: Return data for the supertaxa of each taxon in an [taxonomy] |
| 149 | +#' or [taxmap] object. |
| 150 | +#' * [roots]: Return data for the roots of each taxon in an [taxonomy] or |
| 151 | +#' [taxmap] object. |
| 152 | +#' * [leaves]: Return data for the leaves of each taxon in an [taxonomy] or |
| 153 | +#' [taxmap] object. |
| 154 | +#' * [obs]: Return user-specific data for each taxon and all of its subtaxa in |
| 155 | +#' an [taxonomy] or [taxmap] object. |
| 156 | +#' |
| 157 | +#' @section The kind of classes used: |
| 158 | +#' |
| 159 | +#' Note, this is mostly of interest to developers and advanced users. |
| 160 | +#' |
| 161 | +#' The classes in the `taxa` package are mostly |
| 162 | +#' [R6](https://adv-r.hadley.nz/r6.html) classes ([R6Class]). A few of the |
| 163 | +#' simpler ones ( and [hierarchies]) are |
| 164 | +#' [S3](https://adv-r.hadley.nz/s3.html) instead. R6 classes are different than |
| 165 | +#' most R objects because they are |
| 166 | +#' [mutable](https://en.wikipedia.org/wiki/Immutable_object) (e.g. A function |
| 167 | +#' can change its input without returning it). In this, they are more similar |
| 168 | +#' to class systems in |
| 169 | +#' [object-oriented](https://en.wikipedia.org/wiki/Object-oriented_programming) |
| 170 | +#' languages like python. As in other object-oriented class systems, functions |
| 171 | +#' are thought to "belong" to classes (i.e. the data), rather than functions |
| 172 | +#' existing independently of the data. For example, the function `print` in R |
| 173 | +#' exists apart from what it is printing, although it will change how it prints |
| 174 | +#' based on what the class of the data is that is passed to it. In fact, a user |
| 175 | +#' can make a custom print method for their own class by defining a function |
| 176 | +#' called `print.myclassname`. In contrast, the functions that operate on R6 |
| 177 | +#' functions are "packaged" with the data they operate on. For example, a print |
| 178 | +#' method of an object for an R6 class might be called like |
| 179 | +#' `my_data$print()` instead of `print(my_data)`. |
| 180 | +#' |
| 181 | +#' @section The two ways to call functions: |
| 182 | +#' |
| 183 | +#' Note, you will need to read the previous section to fully understand this one. |
| 184 | +#' |
| 185 | +#' Since the R6 function syntax (e.g. `my_data$print()`) might be confusing to |
| 186 | +#' many R users, all functions in `taxa` also have S3 versions. For example, |
| 187 | +#' the [filter_taxa()] function can be called on a [taxmap] object called |
| 188 | +#' `my_obj` like `my_obj$filter_taxa(...)` (the R6 syntax) or |
| 189 | +#' `filter_taxa(my_obj, ...)` (the S3 syntax). For some functions, these two |
| 190 | +#' way of calling the function can have different effect. For functions that do |
| 191 | +#' not returned a modified version of the input (e.g. [subtaxa()]), the two ways have identical behavior. |
| 192 | +#' However, functions like [filter_taxa()], that modify their inputs, actually |
| 193 | +#' change the object passed to them as the first argument as well as returning that |
| 194 | +#' object. For example, |
| 195 | +#' |
| 196 | +#' `my_obj <- filter_taxa(my_obj, ...)` |
| 197 | +#' |
| 198 | +#' and |
| 199 | +#' |
| 200 | +#' `my_obj$filter_taxa(...)` |
| 201 | +#' |
| 202 | +#' and |
| 203 | +#' |
| 204 | +#' `new_obj <- my_obj$filter_taxa(...)` |
| 205 | +#' |
| 206 | +#' all replace `my_obj` with the filtered result, but |
| 207 | +#' |
| 208 | +#' `new_obj <- filter_taxa(my_obj, ...)` |
| 209 | +#' |
| 210 | +#' will not modify `my_obj`. |
| 211 | +#' |
| 212 | +#' |
| 213 | +#' @section Non-standard evaluation: |
| 214 | +#' |
| 215 | +#' This is a rather advanced topic. |
| 216 | +#' |
| 217 | +#' Like packages such as `ggplot2` and [dplyr], the `taxa` package uses |
| 218 | +#' non-standard evaluation to allow code |
| 219 | +#' to be more readable and shorter. In effect, there are variables that only |
| 220 | +#' "exist" inside a function call and depend on what is passed to that function |
| 221 | +#' as the first parameter (usually a class object). For example, in the `dpylr` |
| 222 | +#' function [filter()], column names can be used as if they were independent |
| 223 | +#' variables. See `?dpylr::filter` for examples of this. The `taxa` package builds on this idea. |
| 224 | +#' |
| 225 | +#' For many functions that work on [taxonomy] or [taxmap] objects (e.g. [filter_taxa]), |
| 226 | +#' some functions that return per-taxon information (e.g. [taxon_names()]) can |
| 227 | +#' be referred to by just the name of the function. When one of these functions |
| 228 | +#' are referred to by name, the function is run on the relevant object and its |
| 229 | +#' value replaces the function name. For example, |
| 230 | +#' |
| 231 | +#' `new_obj <- filter_taxa(my_obj, taxon_names == "Bacteria")` |
| 232 | +#' |
| 233 | +#' is identical to: |
| 234 | +#' |
| 235 | +#' `new_obj <- filter_taxa(my_obj, taxon_names(my_obj) == "Bacteria")` |
| 236 | +#' |
| 237 | +#' which is identical to: |
| 238 | +#' |
| 239 | +#' `new_obj <- filter_taxa(my_obj, my_obj$taxon_names() == "Bacteria")` |
| 240 | +#' |
| 241 | +#' which is identical to: |
| 242 | +#' |
| 243 | +#' `my_names <- taxon_names(my_obj)` |
| 244 | +#' |
| 245 | +#' `new_obj <- filter_taxa(my_obj, my_names == "Bacteria")` |
| 246 | +#' |
| 247 | +#' For `taxmap` objects, you can also use names of user defined lists, vectors, |
| 248 | +#' and the names of columns in user-defined tables that are stored in the |
| 249 | +#' `obj$data` list. See [filter_taxa()] for examples. You can even add your own |
| 250 | +#' functions that are called by name by adding them to the `obj$funcs` list. |
| 251 | +#' For any object with functions that use non-standard evaluation, you can see |
| 252 | +#' what values can be used with [all_names()] like `all_names(obj)`. |
| 253 | +#' |
| 254 | +#' @section Dependencies and inspiration: |
| 255 | +#' |
| 256 | +#' Various elements of the `taxa` package were inspired by the [dplyr] and |
| 257 | +#' [taxize] packages. This package started as parts of the `metacoder` and |
| 258 | +#' `binomen` packages. There are also many dependencies that make `taxa` |
| 259 | +#' possible. |
| 260 | +#' |
| 261 | +#' @section Feedback and contributions: |
| 262 | +#' |
| 263 | +#' Find a problem? Have a suggestion? Have a question? Please submit an issue |
| 264 | +#' at our [GitHub repository](https://github.com/ropensci/taxa): |
| 265 | +#' |
| 266 | +#' [https://github.com/ropensci/taxa/issues](https://github.com/ropensci/taxa/issues) |
| 267 | +#' |
| 268 | +#' A GitHub account is free and easy to set up. We welcome feedback! If you |
| 269 | +#' don't want to use GitHub for some reason, feel free to email us. We do |
| 270 | +#' prefer posting to github since it allows others that might have the same |
| 271 | +#' issue to see our conversation. It also helps us keep track of what problems |
| 272 | +#' we need to address. |
| 273 | +#' |
| 274 | +#' Want to contribute code or make a change to the code? Great, thank you! |
| 275 | +#' Please [fork](https://help.github.com/articles/fork-a-repo/) our GitHub |
| 276 | +#' repository and submit a [pull request](https://help.github.com/articles/about-pull-requests/). |
| 277 | +#' |
82 | 278 | #' @author Zachary Foster and Niklaus Grunwald |
83 | 279 | #' @name metacoder |
84 | | -#' @docType package |
85 | 280 | #' @useDynLib metacoder |
86 | 281 | #' @importFrom Rcpp sourceCpp |
87 | 282 | NULL |
0 commit comments