Package ‘binomen’
April 26, 2017
Title 'Taxonomic' Specification and Parsing Methods
Description Includes functions for working with taxonomic data,
including functions for combining, separating, and filtering
taxonomic groups by any rank or name. Allows standard ('SE')
and non-standard evaluation ('NSE').
Version 0.1.2
License MIT + file LICENSE
URL https://github.com/ropensci/binomen
BugReports https://github.com/ropensci/binomen/issues
LazyLoad yes
LazyData yes
VignetteBuilder knitr
Imports methods, stats, jsonlite, lazyeval, dplyr
Suggests roxygen2 (>= 6.0.1), testthat, knitr, taxize, covr
RoxygenNote 6.0.1
NeedsCompilation no
Author Scott Chamberlain [aut, cre]
Maintainer Scott Chamberlain <[email protected]>
Repository CRAN
Date/Publication 2017-04-25 22:11:47 UTC
R topics documented:
binomen-package . . .
binomial . . . . . . . .
gethier . . . . . . . . .
grouping . . . . . . . .
make_taxon . . . . . .
make_taxon_fromclass
parts . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
1
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
2
3
3
4
6
7
7
2
binomen-package
pick . . . . .
pop . . . . .
rank_table . .
scatter . . . .
span . . . . .
strain . . . .
taxa . . . . .
taxon . . . .
taxonref . . .
taxonrefs . .
taxon_classes
taxon_df . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Index
binomen-package
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
9
10
11
11
12
13
14
14
15
16
16
17
18
Taxonomic class specification and parsing methods
Description
Taxonomic class specification and parsing methods
Author(s)
Scott Chamberlain <[email protected]>
Examples
library("binomen")
# operating on `taxon` objects
out <- make_taxon(genus="Poa", epithet="annua", authority="L.",
family='Poaceae', clazz='Poales', kingdom='Plantae', variety='annua')
# get single name
out %>% pick(family)
out %>% pick(genus)
out %>% pick(species)
out %>% pick(species) %>% name()
out %>% pick(species) %>% uri()
# get range of names
out %>% span(kingdom, genus)
# operating on taxonomic data.frames
df <- data.frame(class=c('Magnoliopsida','Magnoliopsida','Magnoliopsida',
'Magnoliopsida','Magnoliopsida','Magnoliopsida'),
order=c('Asterales','Asterales','Fagales','Poales','Poales','Poales'),
family=c('Asteraceae','Asteraceae','Fagaceae','Poaceae','Poaceae','Poaceae'),
genus=c('Helianthus','Helianthus','Quercus','Poa','Festuca','Holodiscus'),
stringsAsFactors = FALSE)
(df2 <- taxon_df(df))
binomial
3
## select single taxonomic class
df2 %>% pick(order)
df2 %>% pick(family, genus)
## filter to get a range of classes
df2 %>% span(order, genus)
df2 %>% span(family, genus)
binomial
A class to represent a taxonomic binomial
Description
A class to represent a taxonomic binomial
Usage
binomial(genus = NULL, epithet = NULL, canonical = NULL, species = NULL,
authority = NULL)
Arguments
genus
A genus name
epithet
A specific epithet name
canonical
Canonical name
species
Species, genus plus epithet
authority
Authority name
Examples
binomial("Poa")
binomial("Poa", "annua", authority="L.")
gethier
Get hierarchy as a data.frame
Description
Get hierarchy as a data.frame
Usage
gethier(x)
4
grouping
Arguments
x
An object of class taxon
Examples
bin <- binomial("Poa", "annua", authority="L.")
class <- grouping(kingdom=taxonref("kingdom", "Plantae"),
species=taxonref("family", "Poaceae"))
out <- taxon(bin, class)
# get hierarchy as data.frame
gethier(out)
grouping
A class to represent a taxonomic classification
Description
A class to represent a taxonomic classification
Usage
grouping(kingdom = NULL, subkingdom = NULL, infrakingdom = NULL,
division = NULL, phylum = NULL, subdivision = NULL,
infradavision = NULL, superclass = NULL, clazz = NULL,
subclass = NULL, infraclass = NULL, superorder = NULL, order = NULL,
suborder = NULL, infraorder = NULL, superfamily = NULL, family = NULL,
subfamily = NULL, tribe = NULL, subtribe = NULL, genus = NULL,
subgenus = NULL, section = NULL, subsection = NULL, species = NULL,
subspecies = NULL, variety = NULL, race = NULL, subvariety = NULL,
stirp = NULL, morph = NULL, form = NULL, aberration = NULL,
subform = NULL, unspecified = NULL)
Arguments
kingdom
A kingdom name
subkingdom
A subkingdom name
infrakingdom
A infrakingdom name
division
A division name
phylum
A phylum name
subdivision
A subdivision name
infradavision
A infradavision name
superclass
A superclass name
clazz
A clazz name
subclass
A subclass name
grouping
5
infraclass
A infraclass name
superorder
A superorder name
order
A order name
suborder
A suborder name
infraorder
A infraorder name
superfamily
A superfamily name
family
A family name
subfamily
A subfamily name
tribe
A tribe name
subtribe
A subtribe name
genus
A genus name
subgenus
A subgenus name
section
A section name
subsection
A subsection name
species
A species name
subspecies
A subspecies name
variety
A variety name
race
A race name
subvariety
A subvariety name
stirp
A stirp name
morph
A morph name
form
A form name
aberration
A aberration name
subform
A subform name
unspecified
A unspecified name
Examples
grouping(kingdom=taxonref("kingdom", "Animalia"),
species=taxonref("species", "Homo sapiens"))
6
make_taxon
make_taxon
Make taxon from class
Description
Make taxon from class
Usage
make_taxon(genus = "none", epithet = "none", authority = "none", ...)
Arguments
genus
Genus name, e.g., Homo (in Homo sapiens)
epithet
Specific epithet, e.g., sapiens (in Homo sapiens)
authority
Taxonomic authority
...
Further args.
Examples
(out <- make_taxon(genus="Poa"))
(out <- make_taxon(genus="Poa", epithet="annua", authority="L."))
(out <- make_taxon(genus="Poa", epithet="annua", authority="L.",
family='Poaceae', clazz='Poales', kingdom='Plantae', variety='annua'))
out$binomial
out$binomial$canonical
out$binomial$species
out$binomial$authority
out$grouping
out$grouping$family
out %>% pick(family) # get a single rank
out %>% span(kingdom, family) # get a range of ranks
gethier(out) # get hierarchy as data.frame
# Using dplyr
df <- data.frame(class=c('Magnoliopsida','Magnoliopsida','Magnoliopsida',
'Magnoliopsida','Magnoliopsida','Magnoliopsida'),
order=c('Asterales','Asterales','Fagales','Poales','Poales','Poales'),
family=c('Asteraceae','Asteraceae','Fagaceae','Poaceae','Poaceae','Poaceae'),
genus=c('Helianthus','Helianthus','Quercus','Poa','Festuca','Holodiscus'),
species=c('annuus','petrus','kellog','annua','arundinaceae','fava'),
stringsAsFactors = FALSE)
library(dplyr)
xx <- df %>% rowwise()
xx %>% do(i = strain(make_taxon(.$species, genus = .$genus), . < family)) %>% .[[1]]
xx %>% do(i = strain(make_taxon(.$species, genus = .$genus), . < genus)) %>% .[[1]]
xx %>% do(i = strain(make_taxon(.$species, genus = .$genus), . < species)) %>% .[[1]]
make_taxon_fromclass
7
make_taxon_fromclass
Make taxon from class
Description
Make taxon from class
Usage
make_taxon_fromclass(data, authority = "none")
Arguments
data
A data.frame
authority
Taxonomic authority
Examples
df <- data.frame(rank=c('family','tribe','subtribe','genus','subgenus','species'),
name=c('Helianthi','Helianthi','Helianthi','Poa','Festuci','Poa annua'),
id=c(1,2,3,4,5,6),
stringsAsFactors = FALSE)
apply(df, 1, make_taxon_fromclass)
parts
Pick out parts by name
Description
This suite of functions act on taxon or taxonref objects, and pick out object elements by the name
of the function.
Usage
name(x, unname = TRUE)
## S3 method for class 'taxon'
name(x, unname = TRUE)
## S3 method for class 'taxonref'
name(x, unname = TRUE)
uri(x, unname = TRUE)
## S3 method for class 'taxon'
uri(x, unname = TRUE)
8
parts
## S3 method for class 'taxonref'
uri(x, unname = TRUE)
rank(x, unname = TRUE)
## S3 method for class 'taxon'
rank(x, unname = TRUE)
## S3 method for class 'taxonref'
rank(x, unname = TRUE)
taxonid(x, unname = TRUE)
## S3 method for class 'taxon'
taxonid(x, unname = TRUE)
## S3 method for class 'taxonref'
taxonid(x, unname = TRUE)
Arguments
x
Input, object of class taxon or taxonref
unname
(logical) Unname output elements? Ignored when input is of class taxonref.
Default: TRUE
Value
For taxon inputs, gives back a taxonref object. For taxondf inputs, gives back taxondf.
Examples
# operating on `taxon` objects
out <- make_taxon(genus="Poa", epithet="annua", authority="L.",
family='Poaceae', clazz='Poales', kingdom='Plantae', variety='annua')
out
out
out
out
%>%
%>%
%>%
%>%
name()
uri()
rank()
taxonid()
## or don't unname the output
out %>% name(unname = FALSE)
# operating on `taxonref` objects
res <- taxonref("genus", "Poa", 56, "http://scottchamberlain.info/")
res %>% name()
res %>% uri()
res %>% rank()
res %>% taxonid()
pick
9
pick
Pick names
Description
Pick names
Usage
pick(.data, ...)
Arguments
.data
Input, object of class taxon
...
Further unnamed args, see examples
Value
For taxon inputs, gives back a taxonref object. For taxondf inputs, gives back taxondf.
Examples
# operating on `taxon` objects
out <- make_taxon(genus="Poa", epithet="annua", authority="L.",
family='Poaceae', clazz='Poales', kingdom='Plantae', variety='annua')
out %>% pick(family)
out %>% pick(genus)
out %>% pick(species, genus)
out %>% pick(species) %>% name()
out %>% pick(species) %>% uri()
# operating on taxonomic data.frames
df <- data.frame(class=c('Magnoliopsida','Magnoliopsida','Magnoliopsida',
'Magnoliopsida','Magnoliopsida','Magnoliopsida'),
order=c('Asterales','Asterales','Fagales','Poales','Poales','Poales'),
family=c('Asteraceae','Asteraceae','Fagaceae','Poaceae','Poaceae','Poaceae'),
genus=c('Helianthus','Helianthus','Quercus','Poa','Festuca','Holodiscus'),
stringsAsFactors = FALSE)
(df2 <- taxon_df(df))
## select single or many taxonomic classes
df2 %>% pick(order)
df2 %>% pick(family, genus)
# From taxa object
df2 %>% scatter %>% pick(family)
df2 %>% scatter %>% pick(family, species)
df2 %>% scatter %>% pick(family, species, genus)
10
pop
pop
Pop names out
Description
That is, drop them
Usage
pop(.data, ...)
Arguments
.data
Input, object of class taxon
...
Further unnamed args, see examples
Value
For taxon inputs gives back a taxon object. For taxa inputs gives back a taxa object. For taxondf
inputs, gives back a taxondf object.
Examples
# operating on `taxon` objects
out <- make_taxon(genus="Poa", epithet="annua", authority="L.",
family='Poaceae', clazz='Poales', kingdom='Plantae', variety='annua')
## single taxonomic group
out %>% pop(family)
out %>% pop(genus)
out %>% pop(species)
## many taxonomic groups
out %>% pop(family, genus, species)
# operating on taxonomic data.frames
df <- data.frame(class=c('Magnoliopsida','Magnoliopsida','Magnoliopsida',
'Magnoliopsida','Magnoliopsida','Magnoliopsida'),
order=c('Asterales','Asterales','Fagales','Poales','Poales','Poales'),
family=c('Asteraceae','Asteraceae','Fagaceae','Poaceae','Poaceae','Poaceae'),
genus=c('Helianthus','Helianthus','Quercus','Poa','Festuca','Holodiscus'),
stringsAsFactors = FALSE)
(df2 <- taxon_df(df))
## pop out a single taxonomic group
df2 %>% pop(order)
df2 %>% pop(family)
df2 %>% pop(genus)
## pop out many taxonomic groups
df2 %>% pop(order, family)
rank_table
11
df2 %>% pop(order, genus)
# From taxa object
df2 %>% scatter %>% pop(family)
df2 %>% scatter %>% pop(family, species)
df2 %>% scatter %>% pop(family, species, genus)
rank_table
Lookup-table for IDs of taxonomic ranks
Description
Lookup-table for IDs of taxonomic ranks
Value
data.frame with two columns and 34 rows. The two columns:
• rankid integer; smaller numbers are higher ranks.
• ranks character; rank name. Some rows have more than one name, in which the names are
considered of equal height.
scatter
Scatter each taxon in a taxondf to a taxon object
Description
Scatter each taxon in a taxondf to a taxon object
Usage
scatter(x, ...)
assemble(x, ...)
## S3 method for class 'taxa'
assemble(x, ...)
Arguments
x
A taxonomic data.frame
...
Further args, ignored for now
Details
Right now, assemble may not give back the identical data.frame that one would pass to scatter.
12
span
Value
Gives a taxa object, with each individual component a row from your data.frame, and of class
taxon
Examples
# operating on taxonomic data.frames
df <- data.frame(class=c('Magnoliopsida','Magnoliopsida','Magnoliopsida',
'Magnoliopsida','Magnoliopsida','Magnoliopsida'),
order=c('Asterales','Asterales','Fagales','Poales','Poales','Poales'),
family=c('Asteraceae','Asteraceae','Fagaceae','Poaceae','Poaceae','Poaceae'),
genus=c('Helianthus','Helianthus','Quercus','Poa','Festuca','Holodiscus'),
stringsAsFactors = FALSE)
(df2 <- taxon_df(df))
## scatter each taxon into a taxon class
df2 %>% scatter()
## re-assemble
df2
df2 %>% scatter()
df2 %>% scatter() %>% assemble
span
Parse taxon or taxondf objects by a range of names
Description
Parse taxon or taxondf objects by a range of names
Usage
span(.data, ...)
Arguments
.data
Input, object of class taxon
...
Pass in two unquoted taxonomic rank names, and only two. May make this more
flexible in the future.
Value
A single or list of taxon class objects
strain
13
Examples
# operating on `taxon` objects
out <- make_taxon(genus="Poa", epithet="annua", authority="L.",
family='Poaceae', clazz='Poales', kingdom='Plantae', variety='annua')
out %>% span(kingdom, genus)
# operating on taxonomic data.frames
df <- data.frame(class=c('Magnoliopsida','Magnoliopsida','Magnoliopsida',
'Magnoliopsida','Magnoliopsida','Magnoliopsida'),
order=c('Asterales','Asterales','Fagales','Poales','Poales','Poales'),
family=c('Asteraceae','Asteraceae','Fagaceae','Poaceae','Poaceae','Poaceae'),
genus=c('Helianthus','Helianthus','Quercus','Poa','Festuca','Holodiscus'),
stringsAsFactors = FALSE)
(df2 <- taxon_df(df))
## filter to get a range of classes
df2 %>% span(order, genus)
df2 %>% span(family, genus)
## from taxa object
df2 %>% scatter %>% span(family, species)
strain
Parse taxon or taxondf objects by a range of names
Description
Parse taxon or taxondf objects by a range of names
Usage
strain(.data, ...)
Arguments
.data
Input, object of class taxon
...
Logical predicates. Multiple conditions are combined with &. See Details.
Details
Example predicates:
• . > family = Get all taxa greater than family
• . < family = Get all taxa less than family
• . == family = Get all taxa equal to family
• . != family = Get all taxa not equal to family
• genus < order = Get all taxa between genus and order
• genus .. family = Get all taxa between genus and order
14
taxon
Value
A single or list of taxon class objects
Examples
# operating on `taxon` objects
out <- make_taxon(genus="Poa", epithet="annua", authority="L.",
family='Poaceae', clazz='Poales', kingdom='Plantae', variety='annua')
out %>% strain(. < family)
out %>% strain(. < genus)
out %>% strain(. > family)
out %>% strain(. < family)
taxa
A class to represent a list of taxa
Description
A class to represent a list of taxa
Usage
taxa(...)
Arguments
...
An object of class taxon
Examples
bin <- binomial("Poa", "annua", authority="L.")
class <- grouping(kingdom=taxonref("kingdom", "Plantae"),
species=taxonref("family", "Poaceae"))
taxa(taxon(bin, class), taxon(bin, class))
taxon
A class to represent a single taxon
Description
A class to represent a single taxon
Usage
taxon(binomial, grouping)
taxonref
15
Arguments
binomial
A binomial name
grouping
A grouping object
Examples
bin <- binomial("Poa", "annua", authority="L.")
class <- grouping(kingdom=taxonref("kingdom", "Plantae"),
species=taxonref("family", "Poaceae"))
taxon(bin, class)
# many names input
splist <- c('Litsea bindoniana', 'Rubus ghanakantae', 'Desmanthus palmeri',
'Leptinella longipes', 'Asarum sakawanum', 'Cistanche compacta',
'Ormosia nanningensis', 'Claoxylon physocarpum', 'Hedycarya arborea',
'Hypnum gracile')
lapply(splist, binomial)
taxonref
A class to represent a taxonomic reference
Description
A class to represent a taxonomic reference
Usage
taxonref(rank = "none", name = "none", id = "none", uri = "none")
Arguments
rank
(character) Taxonomic rank
name
(character) A name
id
(character,numeric) Identifier
uri
(character) Source of name
Examples
taxonref("genus", "Poa", 56, "http://scottchamberlain.info/")
# many names input
splist <- c('Litsea bindoniana', 'Rubus ghanakantae', 'Desmanthus palmeri',
'Leptinella longipes', 'Asarum sakawanum', 'Cistanche compacta',
'Ormosia nanningensis', 'Claoxylon physocarpum', 'Hedycarya arborea',
'Hypnum gracile')
lapply(splist, function(x) taxonref("species", name = x))
16
taxon_classes
taxonrefs
A class to represent a list of taxonomic references
Description
A class to represent a list of taxonomic references
Usage
taxonrefs(...)
Arguments
...
One or more taxonref objects
Examples
a <- taxonref("genus", "Poa", 56, "http://scottchamberlain.info/")
b <- taxonref("genus", "Quercus", 32343, "http://scottchamberlain.info/")
taxonrefs(a, b)
taxon_classes
Taxonomic class methods
Description
Taxonomic class methods
Details
The taxonomic classes:
• binomial - A binomial, via binomial
• taxonref - A single taxonref, via taxonref
• taxonrefs - A list of taxonrefs, via taxonrefs
• grouping - A grouping (classification) object, via grouping
• taxon - A taxon, via taxon
• taxa - List of taxon objects, via taxa
taxon_df
taxon_df
17
Taxon data.frame
Description
Taxon data.frame
Usage
taxon_df(x)
Arguments
x
A data.frame of taxa
Examples
# subset data.frame using taxonomy
df <- data.frame(family=c('Asteraceae','Asteraceae','Asteraceae','Poaceae','Poaceae','Poaceae'),
tribe=c('Helianthi','Helianthi','Helianthi','Poaeae','Festuci','Poaeae'),
genus=c('Helianthus','Helianthus','Madia','Poa','Festuca','Holodiscus'),
stringsAsFactors = FALSE)
df2 <- taxon_df(df)
df2 %>% pick(family)
df2 %>% pick(genus, tribe)
Index
∗Topic data
rank_table, 11
∗Topic package
binomen-package, 2
assemble (scatter), 11
binomen (binomen-package), 2
binomen-package, 2
binomial, 3, 16
gethier, 3
grouping, 4, 16
make_taxon, 6
make_taxon_fromclass, 7
name (parts), 7
parts, 7
pick, 9
pop, 10
rank (parts), 7
rank_table, 11
scatter, 11
span, 12
strain, 13
taxa, 14, 16
taxon, 14, 16
taxon_classes, 16
taxon_df, 17
taxonid (parts), 7
taxonref, 15, 16
taxonrefs, 16, 16
uri (parts), 7
18