| Type: | Package |
| Title: | Semantically Rich I/O for the 'NeXML' Format |
| Version: | 2.4.11 |
| Description: | Provides access to phyloinformatic data in 'NeXML' format. The package should add new functionality to R such as the possibility to manipulate 'NeXML' objects in more various and refined way and compatibility with 'ape' objects. |
| URL: | https://docs.ropensci.org/RNeXML/,https://github.com/ropensci/RNeXML |
| BugReports: | https://github.com/ropensci/RNeXML/issues |
| License: | BSD_3_clause + file LICENSE |
| VignetteBuilder: | knitr |
| Suggests: | spelling, rdflib, geiger (≥ 2.0), phytools (≥ 0.3.93),knitr (≥ 1.5), rfigshare (≥ 0.3.0), knitcitations (≥ 1.0.1),testthat (≥ 0.10.0), rmarkdown (≥ 0.3.3), xslt, covr,taxalight, progress |
| Depends: | R (≥ 3.0.0), ape (≥ 3.1), methods (≥ 3.0.0) |
| Imports: | XML (≥ 3.95), plyr (≥ 1.8), reshape2 (≥ 1.2.2), httr (≥0.3), uuid (≥ 0.1-1), dplyr (≥ 0.7.0), tidyr (≥ 0.3.1),stringr (≥ 1.0), stringi, xml2, rlang |
| Collate: | 'S4-utils.R' 'classes.R' 'add_basic_meta.R' 'add_characters.R''add_meta.R' 'add_namespaces.R' 'nexmlTree.R' 'add_trees.R''character_classes.R' 'concatenate_nexml.R' 'constructors.R''deprecated.R' 'get_basic_metadata.R' 'get_characters.R''get_level.R' 'get_metadata.R' 'get_namespaces.R' 'get_rdf.R''get_taxa.R' 'get_taxa_meta.R' 'get_trees.R''internal_get_node_maps.R' 'internal_isEmpty.R''internal_name_by_id.R' 'internal_nexml_id.R' 'meta.R''nexml_add.R' 'nexml_get.R' 'nexml_methods.R' 'nexml_publish.R''nexml_read.R' 'nexml_validate.R' 'nexml_write.R''prefixed-uris.R' 'simmap.R' 'taxize_nexml.R' 'tbl_df.R''utils.R' |
| RoxygenNote: | 7.2.3 |
| X-schema.org-applicationCategory: | Data Publication |
| X-schema.org-keywords: | metadata, nexml, phylogenetics, linked-data |
| X-schema.org-isPartOf: | https://ropensci.org |
| Language: | en-US |
| Encoding: | UTF-8 |
| NeedsCompilation: | no |
| Packaged: | 2023-02-01 16:56:11 UTC; cboettig |
| Author: | Carl Boettiger [cre, aut], Scott Chamberlain [aut], Hilmar Lapp [aut], Kseniia Shumelchyk [aut], Rutger Vos [aut] |
| Maintainer: | Carl Boettiger <cboettig@gmail.com> |
| Repository: | CRAN |
| Date/Publication: | 2023-02-01 17:50:07 UTC |
Calls the given generic with the given arguments
Description
Calls the given generic with the given arguments, using the methodwhose signature matches the arguments.
Usage
.callGeneric(f, ..., .package = NULL)Arguments
f | the generic, as a character string or a |
... | the arguments (named and/or unnamed) with which to call thematching method |
.package | the package name for finding the generic (if |
Details
Usesmethods::selectMethod() to find the matching method. In theory,this is at best wholly redundant with what standard S4 generics alreadydo by themselves. However, the generics dispatch for S4 seems (at leastcurrently) broken at least if the first argument in the signature isa class that name-clashes with a class defined in another package. Inthat case, whether the standard dispatch works correctly or not can dependonsearch() order, and can change within a sessiondepending on the order in which packages are loaded.
Value
the value returned by the method
Saves the next method in the method meta data
Description
Promotes the given method definition to an instance ofMethodWithNext, thereby recording the nextmethod in thenextMethod slot.
Usage
.methodWithNext(method, nextMethod, .cache = FALSE)Arguments
method | the |
nextMethod | the |
.cache | whether to cache the promoted method definition object(using |
Value
an instance ofMethodWithNext,which has the next method in thenextMethod slot
Note
MethodWithNext objects are normally returned bymethods::addNextMethod(), but a constructor function for the classseems missing (or is undocumented?). This provides one.
Create a label for a method signature
Description
Creates a label for a signature mirroring the result of.sigLabel()in themethods package, which unfortunately does not export the function.This is needed, for example, for theexcluded slot in theMethodWithNext class.
Usage
.sigLabel(signature)Arguments
signature | the signature for which to create a label, as a vectoror list of strings, or as an instance of |
Value
a character string
Class of objects that have metadata as lists of meta elements
Description
Class of objects that have metadata as lists of meta elements
Slots
metalist of
metaobjectsaboutfor RDF extraction, the identifier for the resource that thisobject is about
new with namespaced class name
Description
Convenience function formethods::new() that ensures that the providedclass name is namespaced with a package name.
Usage
New(Class, ...)Arguments
Class | the name of the S4 class to be instantiated |
... | additional parameters for |
Details
If the provided class name is not already namespaced (seemethods::packageSlot()), it will be namespaced with this package. Thismechanism is used bynew() to disambiguate if the class name clasheswith a class defined in another package.
Note
This may not completely eliminate messages on standard error aboutclasses with the same name having been found in different packages. Ifthey appear, they will most likely have come from the call to themethods::initialize() generic thatnew() issues at the end.
Add basic metadata
Description
adds Dublin Core metadata elements to (top-level) nexml
Usage
add_basic_meta( title = NULL, description = NULL, creator = Sys.getenv("USER"), pubdate = NULL, rights = "CC0", publisher = NULL, citation = NULL, nexml = new("nexml"))Arguments
title | A title for the dataset |
description | a description of the dataset |
creator | name of the data creator. Can be a string or R person object |
pubdate | publication date. Default is current date. |
rights | the intellectual property rights associated with the data.The default is Creative Commons Zero (CC0) public domain declaration,compatible with all other licenses and appropriate for depositioninto the Dryad or figshare repositories. CC0 is also recommended by the Panton Principles.Alternatively, any other plain text string can be added and will be provided as the contentattribute to the dc:rights property. |
publisher | the publisher of the dataset. Usually where a user may go to find the canonicalcopy of the dataset: could be a repository, journal, or academic institution. |
citation | a citation associated with the data. Usually an academic journalarticle that indicates how the data should be cited in an academic context. Multiple citationscan be included here.citation can be a plain text object, but is preferably an R |
nexml | a nexml object to which metadata should be added. A newnexml object will be created if none exists. |
Details
add_basic_meta() is just a wrapper foradd_meta to make it easy toprovide generic metadata without explicitly providing the namespace. For instance,add_basic_meta(title="My title", description="a description") is identical to:add_meta(list(meta("dc:title", "My title"), meta("dc:description", "a description")))Most function arguments are mapped directly to the Dublin Core termsof the same name, with the exception ofrights, which by default mapsto the Creative Commons namespace when using CC0 license.
Value
an updated nexml object
See Also
add_treesadd_charactersadd_meta
Examples
nex <- add_basic_meta(title = "My test title", description = "A description of my test", creator = "Carl Boettiger <cboettig@gmail.com>", publisher = "unpublished data", pubdate = "2012-04-01") ## Adding citation to an R package: nexml <- add_basic_meta(citation=citation("ape"))## Not run: ## Use knitcitations package to add a citation by DOI: library(knitcitations) nexml <- add_basic_meta(citation = bib_metadata("10.2307/2408428")) ## End(Not run)Add character data to a nexml object
Description
Add character data to a nexml object
Usage
add_characters(x, nexml = new("nexml"), append_to_existing_otus = FALSE)Arguments
x | character data, in which character traits labels are column namesand taxon labels are row names. x can be in matrix or data.frameformat. |
nexml | a nexml object, if appending character table to an existingnexml object. If omitted will initiate a new nexml object. |
append_to_existing_otus | logical. If TRUE, will add any new taxa(taxa not matching any existing otus block) to the existing (first)otus block. Otherwise (default), a new otus block is created, eventhough it may contain duplicate taxa to those already present. WhileFALSE is the safe option, TRUE may be appropriate when building nexmlfiles from scratch with both characters and trees. |
Add metadata to a nexml file
Description
Add metadata to a nexml file
Usage
add_meta( meta, nexml = new("nexml"), level = c("nexml", "otus", "trees", "characters"), namespaces = NULL, i = 1, at_id = NULL)Arguments
meta | a meta S4 object, e.g. ouput of the function |
nexml | (S4) object |
level | the level at which the metadata annotation should be added. |
namespaces | named character string for any additional namespaces that should be defined. |
i | for otus, trees, characters: if there are multiple such blocks, which one should be annotated? Default is first/only block. |
at_id | the id of the element to be annotated. Optional, advanced use only. |
Value
the updated nexml object
See Also
metaadd_treesadd_charactersadd_basic_meta
Examples
## Create a new nexml object with a single metadata element: modified <- meta(property = "prism:modificationDate", content = "2013-10-04")nex <- add_meta(modified) # Note: 'prism' is defined in nexml_namespaces by default. ## Write multiple metadata elements, including a new namespace: website <- meta(href = "http://carlboettiger.info", rel = "foaf:homepage") # meta can be link-style metadatanex <- add_meta(list(modified, website), namespaces = c(foaf = "http://xmlns.com/foaf/0.1/"))## Append more metadata, and specify a level: history <- meta(property = "skos:historyNote", content = "Mapped from the bird.orders data in the ape package using RNeXML")data(bird.orders)nex <- add_trees(bird.orders) # need to have created a trees block firstnex <- add_meta(history, nexml = nex, level = "trees", namespaces = c(skos = "http://www.w3.org/2004/02/skos/core#"))Add namespaces
Description
Add namespaces and their prefixes as a named vector of URIs, with thenames being the prefixes. Namespaces have most relevance for meta objects'rel andproperty, and for embedded XML literals.
Usage
add_namespaces(namespaces, nexml = new("nexml"))Arguments
namespaces | a named character vector of namespaces |
nexml | a nexml object. will create a new one if none is given. |
Details
The implementation attempts to avoid duplication, currently using theprefix. I.e., namespaces with prefixes already defined will not get added.Namespaces needed by the NeXML format, and for commonly used metadataterms, are already included by default, seeget_namespaces().
Value
a nexml object with updated namespaces
Note
Often a user won't call this directly, but instead provide thenamespace(s) throughadd_meta().
See Also
meta()add_meta()get_namespaces()
Examples
## Write multiple metadata elements, including a new namespace: website <- meta(href = "http://carlboettiger.info", rel = "foaf:homepage") # meta can be link-style metadatamodified <- meta(property = "prism:modificationDate", content = "2013-10-04")nex <- add_meta(list(modified, website), namespaces = c(foaf = "http://xmlns.com/foaf/0.1/")) # prism prefix already included by default## Add namespace "by hand" before adding meta:nex <- add_namespaces(c(skos = "http://www.w3.org/2004/02/skos/core#"), nexml = nex)history <- meta(property = "skos:historyNote", content = "Mapped from the bird.orders data in the ape package using RNeXML")nex <- add_meta(history, nexml = nex)add_trees
Description
add_trees
Usage
add_trees(phy, nexml = new("nexml"), append_to_existing_otus = FALSE)Arguments
phy | a phylo object, multiPhylo object, or list ofmultiPhylo to be added to the nexml |
nexml | a nexml object to which we should append this phylo.By default, a new nexml object will be created. |
append_to_existing_otus | logical, indicating if we shouldmake a new OTU block (default) or append to the existing one. |
Value
a nexml object containing the phy in nexml format.
Concatenate meta elements into a ListOfmeta
Description
Concatenate meta elements into a ListOfmeta
Concatenate ListOfmeta elements into a flat ListOfmeta
Usage
## S4 method for signature 'meta'c(x, ..., recursive = TRUE)## S4 method for signature 'ListOfmeta'c(x, ..., recursive = TRUE)Arguments
x,... |
|
recursive | logical, if 'recursive=TRUE', the function recursivelydescends through lists and combines their elements into a flat vector.This method does not support |
Value
a ListOfmeta object containing a flat list of meta elements.
Examples
c(meta(content="example", property="dc:title"), meta(content="Carl", property="dc:creator"))metalist <- c(meta(content="example", property="dc:title"), meta(content="Carl", property="dc:creator"))out <- c(metalist, metalist) out <- c(metalist, meta(content="a", property="b"))Concatenate nexml files
Description
Concatenate nexml files
Usage
## S4 method for signature 'nexml'c(x, ..., recursive = FALSE)Arguments
x,... | nexml objects to be concatenated, e.g. from |
recursive | logical. If 'recursive = TRUE', the function recursivelydescends through lists (and pairlists) combining all theirelements into a vector. (Not implemented). |
Value
a concatenated nexml file
Examples
## Not run: f1 <- system.file("examples", "trees.xml", package="RNeXML")f2 <- system.file("examples", "comp_analysis.xml", package="RNeXML")nex1 <- read.nexml(f1)nex2 <- read.nexml(f2)nex <- c(nex1, nex2)## End(Not run)Treats zero-length character vectors as empty strings
Description
If the argument is a zero-length character vector (character(0)), returnsan empty string (which is a character vector of length 1). Otherwise passesthrough the argument.
Usage
charzero_as_empty(x)Arguments
x | the object to be tested for zero-length character vector |
Value
an empty string ifx is a character vector of length zero, andxotherwise
Front-end to dplyr::coalesce to deal with NULL vectors
Description
Replaces any NULL argument with a vector ofNA, and casts every vectorto the same type as the last vector. After that, callsdplyr::coalesce().
Usage
coalesce_(...)Arguments
... | the vectors to coalesce on NA |
Value
a vector of the same type and length as the last argument
See Also
Expand namespace-prefixed string
Description
Substitutes the namespace prefix in the input vector of strings withthe corresponding namespaces.
Usage
expand_prefix(x, namespaces = NULL)Arguments
x | a character vector of potentially namespace-prefixed strings |
namespaces | a named vector of namespaces, with namespace prefixesbeing the names. A "base" namespace with an empty name can be included.If not provided, or if empty, the input vector is returned as is. |
Details
Namespace prefixes are expected to be separated by one or more semicolons.Prefixes that cannot be matched to the vector of namespaces will be leftas is. For strings that do not have a namespace prefix, the vector ofnamespaces can contain a base namespace, identified as not having a name,with which these strings will be expanded.
Value
a character vector, of the same length as the input vector
Examples
uris <- c("cc:license", "dc:title")ns <- c(dc = "http://purl.org/dc/elements/1.1/", dcterms = "http://purl.org/dc/terms/", dct = "http://purl.org/dc/terms/", cc = "http://creativecommons.org/ns#")# expansion is vectorizedexpand_prefix(uris, ns)# strings with non-matching or no prefix are left as isuris <- c(uris, "my:title", "title")expand_prefix(uris, ns)# NAs in the input list become NA in the outputuris <- c(uris, NA)expand_prefix(uris, ns)# can include a "base" (unnamed) namespace for expanding unprefixed stringsns <- c(ns, "//local/")xuris <- expand_prefix(uris, ns)xurisxuris[uris == "title"] == paste0("//local/", uris[uris == "title"])# different prefixes may expand to the same resultexpand_prefix("dcterms:modified", ns) == expand_prefix("dct:modified", ns)# or they may result in different expansionsexpand_prefix("dc:title", ns) != expand_prefix("dcterms:title", ns)Finds the method that callNextMethod() should chain to
Description
Attempts to find the "next" method in the inheritance chain. This would(ideally) be the method thatmethods::callNextMethod() would chain to,as a result of the methodmethods::addNextMethod() would find (and returnin thenextMethod slot of theMethodWithNextobject). Hence, in theory one shouldn't ever need this, but unfortunatelyaddNextMethod() is broken (and errors out) if one of the classes in thesignature name-clashes with an S4 class defined in another package that isloaded.
Usage
findNextMethod(method, f = NULL, envir = topenv())Arguments
method |
|
f |
|
envir | the environment in which to find the method |
Details
The next method will be determined by the S4 inheritance chain. However,this function will walk only the inheritance chain of those arguments inthe signature that are defined in the package of the generic method fromwhich this function was invoked (directly or indirectly). If there areno such parameters in the signature, or if there is more than one,finding the next method is handed off tomethods::addNextMethod().
Value
aMethodDefinition object that is the next method in thechain by inheritance
Note
In theory a class name clash between packages shouldn't be a problembecause class names can be namespaced, and theMethodDefinitionobject passed toaddNextMethod() has all the necessary namespaceinformation. Hopefully, at some point this gets fixed in R, and then wedon't need this anymore.
Flatten a multiphylo object
Description
Flatten a multiphylo object
Usage
flatten_multiphylo(object)Arguments
object | a list of multiphylo objects |
Details
NeXML has the concept of multiple<trees> nodes, each with multiple child<tree> nodes.This maps naturally to a list of multiphylo objects. Sometimesthis hierarchy conveys important structural information, so it is not discarded by default.Occasionally it is useful to flatten the structure though, hence this function. Note that thisdiscards the original structure, and the nexml file must be parsed again to recover it.
Get flattened list of meta annotations
Description
Collects recursively (in the case of nested meta annotations) all metaobject annotations for the given object, and returns the result as a flatlist.
Usage
get_all_meta(annotated)Arguments
annotated | the object from which to extract meta object annotations |
Details
Does not check that the input object can actually have meta annotations.An invalid slot error will be generated if it can't.
Value
a flat list ofmeta objects
Get character data.frame from nexml
Description
Get character data.frame from nexml
Usage
get_characters( nex, rownames_as_col = FALSE, otu_id = FALSE, otus_id = FALSE, include_state_types = FALSE)Arguments
nex | a nexml object |
rownames_as_col | option to return character matrix rownames (with taxon ids) as it's own column in thedata.frame. Default is FALSE for compatibility with geiger and similar packages. |
otu_id | logical, default FALSE. return a column with theotu id (for joining with otu metadata, etc) |
otus_id | logical, default FALSE. return a column with theotus block id (for joining with otu metadata, etc) |
include_state_types | logical, default FALSE. whether to also return amatrix of state types (with values standard, polymorphic, and uncertain) |
Details
RNeXML will attempt to return the matrix using the NeXML taxon (otu) labels to name the rowsand the NeXML char labels to name the traits (columns). If these are unavailable or not unique, the NeXMLid values for the otus or traits will be used instead.
Value
the character matrix as a data.frame, or ifinclude_state_types isTRUE a list of two elements,characters as the character matrix, andstate_types as a matrix of state types. Both matrices will be in the sameordering of rows and columns.
Examples
## Not run: # A simple example with a discrete and a continous traitf <- system.file("examples", "comp_analysis.xml", package="RNeXML")nex <- read.nexml(f)get_characters(nex)# A more complex example -- currently ignores sequence-type charactersf <- system.file("examples", "characters.xml", package="RNeXML")nex <- read.nexml(f)get_characters(nex)# if polymorphic or uncertain states need special treatment, request state# types to be returned as well:f <- system.file("examples", "ontotrace-result.xml", package="RNeXML")nex <- read.nexml(f)res <- get_characters(nex, include_state_types = TRUE)row.has.p <- apply(res$state_types, 1, function(x) any(x == "polymorphic", na.rm = TRUE))col.has.p <- apply(res$state_types, 2, function(x) any(x == "polymorphic", na.rm = TRUE))res$characters[row.has.p, col.has.p, drop=FALSE] # polymorphic rows and colsres$characters[!row.has.p, drop=FALSE] # drop taxa with polymorphic states# replace polymorphic state symbols in matrix with '?'m1 <- mapply(function(s, s.t) ifelse(s.t == "standard", s, "?"), res$characters, res$state_types)row.names(m1) <- row.names(res$characters)m1## End(Not run)Extract the character matrix
Description
Extract the character matrix
Usage
get_characters_list(nexml, rownames_as_col = FALSE)Arguments
nexml | nexml object (e.g. from read.nexml) |
rownames_as_col | option to return character matrix rownames(with taxon ids) as it's own column in the data.frame. Default is FALSEfor compatibility with geiger and similar packages. |
Value
the list of taxa
Examples
comp_analysis <- system.file("examples", "comp_analysis.xml", package="RNeXML")nex <- nexml_read(comp_analysis)get_characters_list(nex)Get citation from metadata
Description
Extracts the citation annotation from the metadata annotation of thenexmlobject, and returns its value.
Usage
get_citation(nexml)Arguments
nexml | a nexml object |
Details
Currently the implementation looks fordcterms:bibliographicCitationannotations. (Note that these may be given with any prefix in the metadataso long as they expand to the same full property URIs.)
Value
the citation if the metadata provides one that is non-empty, andNA otherwise. If multiple non-empty annotations are found, only the firstone is returned.
See Also
get_flat_trees
Description
extract a single multiPhylo object containing all trees in the nexml
Usage
get_flat_trees(nexml)Arguments
nexml | a representation of the nexml object from which the data is to be retrieved |
Details
Note that this method collapses any hierarchical structure that may have been present as multipletrees nodes in the original nexml (though such a feature is rarely used). To preserve that structure, useget_trees instead.
Value
a multiPhylo object (list of ape::phylo objects). See details.
See Also
Examples
comp_analysis <- system.file("examples", "comp_analysis.xml", package="RNeXML")nex <- nexml_read(comp_analysis)get_flat_trees(nex)get_level
Description
get a data.frame of attribute values of a given node
Usage
get_level(nex, level)Arguments
nex | a nexml object |
level | a character vector indicating the class of node, see details |
Details
level should be a character vector giving the path to the specified nodegroup. For instance,otus,characters, andtrees are top-level blocks (e.g.child nodes of the root nexml block), and can be specified directly. To get metadatafor all "char" elements from all characters blocks, you must specify thatchar nodesare child nodes tocharacter nodes: e.g.get_level(nex, "characters/char"),or similarly for states:get_level(nex, characters/states).
The return object is a data frame whose columns are the attribute names of the elementsspecified. The column names match the attribute names except for "id" attribute, for which the columnis renamed using the node itself. (Thus<otus> would be rendered in a data.frame with columncalled "otus" instead of "id"). Additional columns areadded for each parent element in the path; e.g.get_level(nex, "otus/otu") would include a columnnamed "otus" with the id of each otus block. Even though the method always returns the data framefor all matching nodes in all blocks, these ids let you see which otu values came from whichotus block. This is identical to the function callget_taxa().Similarly,get_level(nex, "otus/otu/meta") would return additional columns 'otus' andalso a column, 'otu', with the otu parent ids of each metadata block. (This is identical to afunction call toget_metadata). This makes it easier to join data.frames as well, see examples
Value
Returns the attributes of specified class of nodes as a data.frame
Get license from metadata
Description
Extracts the license annotation from the metadata annotation of thenexmlobject, and returns its value.
Usage
get_license(nexml)Arguments
nexml | a nexml object |
Details
Currently the implementation looks forcc:license anddc:rightsannotations. (Note that these may be given with any prefix in the metadataso long as they expand to the same full property URIs.)
Value
the license if the metadata asserts one that is non-empty, andNA otherwise.If multiple non-empty annotations are found, only the firstone is returned.
See Also
Extracts meta objects matching properties
Description
Extracts the metadata annotations for the given property or properties,and returns the result as a list ofmeta objects.
Usage
get_meta(nexml, annotated = NULL, props)Arguments
nexml | a nexml object |
annotated | the nexml component object from which to obtain metadataannotations, or a list of such objects. Defaults to the nexml object itself. |
props | a character vector of property names for which to extractmetadata annotations |
Details
For matching property identifiers (i.e., URIs), prefixes in the input listas well as in theannotated object will be expanded using the namespacesof thenexml object. Names in the returned list are mapped to the(possibly prefixed) form in the input list. The resulting list is flat,and hence does not retain the nesting hierarchy in the object's annotation.
Value
a named list of the matching meta objects
get_metadata
Description
get_metadata
Usage
get_metadata(nexml, level = "nexml", simplify = TRUE)Arguments
nexml | a nexml object |
level | the name of the level of element desired, see details |
simplify | logical, see Details |
Details
'level' should be either the name of a child element of a NeXML document(e.g. "otu", "characters"), or a path to the desired element, e.g. 'trees/tree'will return the metadata for all phylogenies in all trees blocks.
If a metadata element has other metadata elements nested within it, thenested metadata are returned as well. A column "Meta" will contain theIDs consolidated from the type-specific LiteralMeta and ResourceMetacolumns, and IDs are generated for meta elements that have nested elementsbut do not have an ID ("blank nodes"). A column "meta" contains theIDs of the parent meta elements for nested ones. This means that theresulting table can be self-joined on those columns.
Ifsimplify isFALSE, the type-specific "LiteralMeta" and "ResourceMeta"columns will be retained even if a consolidated "Meta" column is present.Otherwise, only the consolidated column will be included in the result.Also, ifsimplify isTRUE the values for "property" (LiteralMeta) and"rel" (ResourceMeta) will be consolidated to "property", and "rel" will beremoved from the result.
Value
the requested metadata as a data.frame. Additional columnsindicate the parent element of the return value.
Examples
## Not run: comp_analysis <- system.file("examples", "primates.xml", package="RNeXML")nex <- nexml_read(comp_analysis)get_metadata(nex)get_metadata(nex, "otus/otu")## End(Not run)Get the value(s) for metadata
Description
Extracts the values from the metadata annotations for the given propertyor properties, and returns the result.
Usage
get_metadata_values(nexml, annotated = NULL, props)Arguments
nexml | a nexml object |
annotated | the nexml component object from which to obtain metadataannotations, defaults to the nexml object itself |
props | a character vector of property names for which to extractmetadata annotations |
Details
For matching property identifiers (i.e., URIs), prefixes in the input listas well as in theannotated object will be expanded using the namespacesof thenexml object. Names in the returned vector are mapped to the(possibly prefixed) form in the input list.
Value
a named character vector, giving the values and names being theproperty names
get namespaces
Description
get namespaces
Usage
get_namespaces(nexml)Arguments
nexml | a nexml object |
Value
a named character vector providing the URLs defining eachof the namespaces used in the nexml file. Names correspond tothe prefix abbreviations of the namespaces.
Examples
comp_analysis <- system.file("examples", "comp_analysis.xml", package="RNeXML")nex <- nexml_read(comp_analysis)get_namespaces(nex)Extract rdf-xml from a NeXML file
Description
Extract rdf-xml from a NeXML file
Usage
get_rdf(file)Arguments
file | the name of a nexml file, or otherwise a nexml object. |
Value
an RDF-XML object (XMLInternalDocument). This can be manipulated withtools from the XML R package, or converted into a triplestore for use withSPARQL queries from the rdflib R package.
get_taxa
Description
Retrieve names of all species/otus otus (operational taxonomic units) included in the nexml
Usage
get_taxa(nexml)Arguments
nexml | a nexml object |
Value
the list of taxa
See Also
Examples
comp_analysis <- system.file("examples", "comp_analysis.xml", package="RNeXML")nex <- nexml_read(comp_analysis)get_taxa(nex)get_taxa_list
Description
Retrieve names of all species/otus otus (operational taxonomic units) included in the nexml
Usage
get_taxa_list(nexml)Arguments
nexml | a nexml object |
Value
the list of taxa
See Also
get_taxa_meta
Description
Retrieve metadata of all species/otus otus (operational taxonomic units) included in the nexml
Usage
get_taxa_meta(nexml, what = "href")Arguments
nexml | a nexml object |
what | One of href, rel, id, or xsi:type |
Value
the list of metadata for each taxon
See Also
Examples
## Not run: data(bird.orders)birds <- add_trees(bird.orders)birds <- taxize_nexml(birds, "NCBI")RNeXML:::get_taxa_meta(birds)RNeXML:::get_taxa_meta(birds, 'rel')RNeXML:::get_taxa_meta(birds, 'id')RNeXML:::get_taxa_meta(birds, 'xsi:type') ## End(Not run)get_taxa_meta_list
Description
Retrieve metadata of all species/otus otus (operational taxonomic units) included in the nexml
Usage
get_taxa_meta_list(nexml, what = "href")Arguments
nexml | a nexml object |
what | One of href, rel, id, or xsi:type |
Value
the list of metadata for each taxon
See Also
Examples
## Not run: data(bird.orders)birds <- add_trees(bird.orders)birds <- taxize_nexml(birds, "NCBI")RNeXML:::get_taxa_meta_list(birds)RNeXML:::get_taxa_meta_list(birds, 'rel')RNeXML:::get_taxa_meta_list(birds, 'id')RNeXML:::get_taxa_meta_list(birds, 'xsi:type')## End(Not run)extract a phylogenetic tree from the nexml
Description
extract a phylogenetic tree from the nexml
Usage
get_trees(nexml)Arguments
nexml | a representation of the nexml object fromwhich the data is to be retrieved |
Value
an ape::phylo tree, if only one tree is represented.Otherwise returns a list of lists of multiphylo trees.To consistently receive the list of lists format (preservingthe hierarchical nature of the nexml), useget_trees_list instead.
See Also
get_treesget_flat_treesget_item
Examples
comp_analysis <- system.file("examples", "comp_analysis.xml", package="RNeXML")nex <- nexml_read(comp_analysis)get_trees(nex)extract all phylogenetic trees in ape format
Description
extract all phylogenetic trees in ape format
Usage
get_trees_list(nexml)Arguments
nexml | a representation of the nexml object fromwhich the data is to be retrieved |
Value
returns a list of lists of multiphylo trees, even if all treesare in the sametrees node (and hence the outer list will be of length
or if there is only a single tree (and hence the inner list will alsobe of length 1. This ensures a consistent return type regardless ofthe number of trees present in the nexml file, and also preserves anygrouping of trees.
See Also
get_treesget_flat_treesget_item
Examples
comp_analysis <- system.file("examples", "comp_analysis.xml", package="RNeXML")nex <- nexml_read(comp_analysis)get_trees_list(nex)Compact list then lapply
Description
Compacts the list (i.e., removes NULL objects), then callslapply()on the result with the remaining parameters.
Usage
lcapply(X, ...)Arguments
X | the list object |
... | remaining arguments to |
Constructor function for metadata nodes
Description
Constructor function for metadata nodes
Usage
meta( property = NULL, content = NULL, rel = NULL, href = NULL, datatype = NULL, id = NULL, type = NULL, children = list())Arguments
property | specify the ontological definition together with it's namespace, e.g. dc:title |
content | content of the metadata field |
rel | Ontological definition of the reference provided in href |
href | A link to some reference |
datatype | optional RDFa field |
id | optional id element (otherwise id will be automatically generated). |
type | optional xsi:type. If not given, will use either "LiteralMeta" or "ResourceMeta" asdetermined by the presence of either a property or a href value. |
children | Optional element containing any valid XML block (XMLInternalElementNode class, see the XML package for details). |
Details
User must either provide property+content or rel+href. Mixing these will result in potential garbage.The datatype attribute will be detected automatically from the class of the content argument. Maps from R classto schema datatypes are as follows:character - xs:string,Date - xs:date,integer - xs:integer,numeric - xs:decimal,logical - xs:boolean
See Also
Examples
meta(content="example", property="dc:title")Class representing a NeXML document
Description
Thenexml class represents a NeXML document, and is the top of theclass hierarchy defined in this package, corresponding to the root nodeof the corresponding XML document.
Details
Normally objects of this type are created by the package as a result ofreading a NeXML file, or of converting from another type, such asape::phylo. Also, interacting directly with the slots of the class isnormally not necessary. Instead, use theget_XXX() andadd_XXX()functions in the API.
Slots
treeslist, corresponding to the list of
<trees/>elements inNeXML. Elements will be of classtrees.characterslist, corresponding to the list of
<characters/>elements in NeXML. Elements will be of classcharacters.otuslist, corresponding to the list of
<otus/>elements in NeXML.Elements will be of classotus.aboutinherited, seeAnnotated
metainherited, seeAnnotated
xsi:typefor internal use
versionNeXML schema version, do not change
generatorname of software generating the XML
xsi:schemaLocationfor internal use, do not change
namespacesnamed character vector giving the XML namespaces
See Also
Examples
nex <- nexml() # a nexml object with no further contentnex <- new("nexml") # accomplishes the same thingnex@generatorlength(nex@trees)data(bird.orders)nex <- as(bird.orders, "nexml")summary(nex)length(nex@trees)Constructor for the respective class
Description
Creates an instance of the class corresponding to the respective NeXMLelement, and initializes its slots with the provided parameters, if any.
Usage
nexml.tree(...)nexml.trees(...)nexml.node(...)nexml.edge(...)nexml.otu(...)nexml.otus(...)nexml.char(...)nexml.characters(...)nexml.format(...)nexml.state(...)nexml.uncertain_state(...)nexml.states(...)nexml.uncertain_states(...)nexml.polymorphic_states(...)nexml.member(...)nexml.matrix(...)nexml.row(...)nexml.seq(...)nexml.cell(...)Arguments
... | optionally, parameters passed on to |
Details
Usually, users won't need to invoke this directly.
See Also
nexml.meta() for documentation ofnexml.meta()
add elements to a new or existing nexml object
Description
add elements to a new or existing nexml object
Usage
nexml_add( x, nexml = new("nexml"), type = c("trees", "characters", "meta", "namespaces"), ...)Arguments
x | the object to be added |
nexml | an existing nexml object onto which the object should be appended |
type | the type of object being provided. |
... | additional optional arguments to the add functions |
Value
a nexml object with the additional data
See Also
add_treesadd_charactersadd_metaadd_namespaces
publish nexml to figshare
Description
publish nexml to figshare
Usage
nexml_figshare( nexml, file = "nexml.xml", categories = "Evolutionary Biology", tags = list("phylogeny", "NeXML"), visibility = c("public", "private", "draft"), id = NULL, ...)Arguments
nexml | a nexml object (or file path to a nexml file) |
file | The filename desired for the object, if nexml is not already a file.if the first argument is already a path, this value is ignored. |
categories | The figshare categories, must match available set. see |
tags | Any keyword tags you want to add to the data. |
visibility | whether the results should be published (public), or kept private,or kept as a draft for further editing before publication. (New versions can be updated,but any former versions that was once made public will always be archived and cannot be removed). |
id | an existing figshare id (e.g. from fs_create), to which this file can be appended. |
... | additional arguments |
Value
the figshare id of the object
Examples
## Not run: data(bird.orders)birds <- add_trees(bird.orders)doi <- nexml_figshare(birds, visibility = "public", repository="figshare")## End(Not run)Get the desired element from the nexml object
Description
Get the desired element from the nexml object
Usage
nexml_get( nexml, element = c("trees", "trees_list", "flat_trees", "metadata", "otu", "taxa", "characters", "characters_list", "namespaces"), ...)Arguments
nexml | a nexml object (from read_nexml) |
element | the kind of object desired, see details. |
... | additional arguments, if applicable to certain elements |
Details
"tree" an ape::phylo tree, if only one tree is represented. Otherwise returns a list of lists of multiphylo trees. To consistently receive the list of lists format (preserving the hierarchical nature of the nexml), use
treesinstead."trees" returns a list of lists of multiphylo trees, even if all trees are in the same
treesnode (and hence the outer list will be of length 1) or if there is only a single tree (and hence the inner list will also be of length 1. This ensures a consistent return type regardless of the number of trees present in the nexml file, and also preserves any hierarchy/grouping of trees."flat_trees" a multiPhylo object (list of ape::phylo objects) Note that this method collapses any hierarchical structure that may have been present as multiple
treesnodes in the original nexml (though such a feature is rarely used). To preserve that structure, usetreesinstead."metadata"Get metadata from the specified level (default is top/nexml level)
"otu" returns a named character vector containing all available metadata. names indicate
property(orrelin the case of links/resourceMeta), while values indicate thecontent(orhreffor links)."taxa" alias for otu
For a slightly cleaner interface, each of these elements is also defined as an S4 methodfor a nexml object. So in place ofget_item(nexml, "tree"), one could useget_tree(nexml),and so forth for each element type.
Value
return type depends on the element requested. See details.
See Also
Examples
comp_analysis <- system.file("examples", "comp_analysis.xml", package="RNeXML")nex <- nexml_read(comp_analysis)nexml_get(nex, "trees")nexml_get(nex, "characters_list")publish nexml files to the web and receive a DOI
Description
publish nexml files to the web and receive a DOI
Usage
nexml_publish(nexml, ..., repository = "figshare")Arguments
nexml | a nexml object (or file path) |
... | additional arguments, depending on repository. See examples. |
repository | destination repository |
Value
a digital object identifier to the published data
Examples
## Not run: data(bird.orders)birds <- add_trees(bird.orders)doi <- nexml_publish(birds, visibility = "public", repository="figshare")## End(Not run)Read NeXML files into various R formats
Description
Read NeXML files into various R formats
Usage
nexml_read(x, ...)## S3 method for class 'character'nexml_read(x, ...)## S3 method for class 'XMLInternalDocument'nexml_read(x, ...)## S3 method for class 'XMLInternalNode'nexml_read(x, ...)Arguments
x | Path to the file to be read in. An |
... | Further arguments passed on to |
Examples
# filef <- system.file("examples", "trees.xml", package="RNeXML")nexml_read(f)## Not run: # may take > 5 s# urlurl <- "https://raw.githubusercontent.com/ropensci/RNeXML/master/inst/examples/trees.xml"nexml_read(url)# character string of XMLstr <- paste0(readLines(f), collapse = "")nexml_read(str)# XMLInternalDocumentlibrary("httr")library("XML")x <- xmlParse(content(GET(url)))nexml_read(x)# XMLInternalNodenexml_read(xmlRoot(x))## End(Not run)validate nexml using the online validator tool
Description
validate nexml using the online validator tool
Usage
nexml_validate( file, schema = system.file("xsd/nexml.xsd", package = "RNeXML"), local = TRUE)Arguments
file | path to the nexml file to validate |
schema | URL of schema (for fallback method only, set by default). |
local | logical, if TRUE we skip the online validator and rely only on pure XML-schema validation. This may fail to detect invalid use of some semantic elements. |
Details
Requires an internet connection if local=FALSE. see http://www.nexml.org/nexml/phylows/validator for more information in debugging invalid files
Value
TRUE if the file is valid, FALSE or error message otherwise
Examples
## Not run: data(bird.orders)birds <- nexml_write(bird.orders, "birds_orders.xml")nexml_validate("birds_orders.xml")unlink("birds_orders.xml") # delete file to clean up## End(Not run)Write nexml files
Description
Write nexml files
Usage
nexml_write( x = nexml(), file = NULL, trees = NULL, characters = NULL, meta = NULL, ...)Arguments
x | a nexml object, or any phylogeny object (e.g. phylo, phylo4)that can be coerced into one. Can also be omitted, in which case a newnexml object will be constructed with the additional parameters specified. |
file | the name of the file to write out |
trees | phylogenetic trees to add to the nexml file (if not already given in x)see |
characters | additional characters |
meta | A meta element or list of meta elements, see |
... | additional arguments to add__basic_meta, such as the title. See |
Value
Writes out a nexml file
See Also
add_treesadd_charactersadd_metanexml_read
Examples
## Write an ape tree to nexml, analgous to write.nexus: library(ape); data(bird.orders) ex <- tempfile(fileext=".xml") write.nexml(bird.orders, file=ex)reset id counter
Description
reset the id counter
Usage
reset_id_counter()Convert phylo with attached simmap to nexml object
Description
Convert phylo with attached simmap to nexml object
Convert nexml object with simmap to phylo
Usage
simmap_to_nexml(phy, state_ids = NULL)nexml_to_simmap(nexml)Arguments
phy | a phylo object containing simmap |
state_ids | a named character vector giving the statenames corresponding to the ids used to refer to each statein nexml. If null ids will be generated and states taken fromthe phy$states names. |
nexml | a nexml object |
Value
a nexml representation of the simmap
a simmap object (phylo object with a$maps elementfor use in phytools functions).
Functions
nexml_to_simmap(): Convert nexml object with simmap to phylo
Examples
simmap_ex <- read.nexml(system.file("examples","simmap_ex.xml", package="RNeXML"))phy <- nexml_to_simmap(simmap_ex)nex <- simmap_to_nexml(phy)Access or set slot of S4 object
Description
Seemethods::slot(). This version allows using "property" consistentlyfor both LiteralMeta and ResourceMeta (which internally uses "rel" becauseRDFa does), which is easier to program. It also allows using "meta"as an alias for "children" for ResourceMeta, to be consistent with thecorresponding slot for instances ofAnnotated.
Usage
## S4 method for signature 'ResourceMeta'slot(object, name)## S4 replacement method for signature 'ResourceMeta'slot(object, name) <- valueArguments
object | the object |
name | name of the slot |
value | the new value |
See Also
Summary method for nexml objects
Description
Generates a list of various counts of the major elements that comprise anexml object, such as number of different kinds of blocks,characters, states, OTUs (taxa), etc.
Usage
## S4 method for signature 'nexml'summary(object)Arguments
object | thenexml object |
Details
Theshow method uses this summary for pretty-printing asummary of the NeXML object, but it can be used on its own as well, inparticular for quick inspection of key properties of a NeXML file.
Value
A list with the following elements:
nblocksthe number of trees, otus, and characters blocksncharactersthe number of characters in each characters blocknstatessummary statistics of the number of character states per state setdefined for each characters blocknnonstdstatedefsthe number of polymorphic and uncertain states definedfor each character blocknmatrixrowsthe number of rows in the matrix for each character blockntreesthe number of trees contained in each trees blocknotusthe number of OTUs defined in each OTUs blocknmetaa list of the number of the number of metadata annotations atseveral levels, specifically:nexmlat the top (nexml) levelotuat the OTU level, for each OTUs blockcharat the character level, for each characters blockstateat the character state level, for each characters block
Examples
nex <- nexml_read(system.file("examples", "comp_analysis.xml", package = "RNeXML"))s <- summary(nex)# number of major blocks:s$nblocks# each characters block defines 1 character:s$ncharacters# summary stats of states per character (for morphological matrices there is# typically one state set per character)s$nstates # note that first block is of continuous type, so no stats there# pretty-printed summary:nex # this is the same as show(nex)taxize nexml
Description
Check taxonomic names against the specified service andadd appropriate semantic metadata to the nexml OTU unitcontaining the corresponding identifier.
Usage
taxize_nexml( nexml, type = c("ncbi", "itis", "col", "tpl", "gbif", "wd"), warnings = TRUE, ...)Arguments
nexml | a nexml object |
type | the name of the identifier to use |
warnings | should we show warning messages if no match can be found? |
... | additional arguments to |
Examples
## Not run: data(bird.orders)birds <- add_trees(bird.orders)birds <- taxize_nexml(birds, "NCBI")## End(Not run)nexml to phylo
Description
nexml to phylo coercion
Usage
toPhylo(tree, otus)Arguments
tree | an nexml tree element |
otus | a character string of taxonomic labels, named by the otu ids.e.g. (from get_otu_maps for the otus set matching the relevant trees node. |
Value
phylo object. If a "reconstructions" annotation is found on theedges, return simmap maps slot as well.