The nexml S4 Object
nexml S4 object
RNeXML package provides many convenient functions to add and extract information from
nexml objects in the R environment without requiring the reader to understand the details of the NeXML data structure and making it less likely that a user will generate invalid NeXML syntax that could not be read by other parsers. The
nexml object we have been using in all of the examples is built on R’s S4 mechanism. Advanced users may sometimes prefer to interact with the data structure more directly using R’s S4 class mechanism and subsetting methods. Many R users are more familiar with the S3 class mechanism (such as in the
ape package phylo objects) rather than the S4 class mechanism used in phylogenetics packages such as
phylobase vignette provides an excellent introduction to these data structures. Users already familiar with subsetting lists and other S3 objects in R are likely familiar with the use of the
$ operator, such as
phy$edge. S4 objects simply use an
@ operator instead (but cannot be subset using numeric arguments such as
phy[] or named arguments such as phy[[“edge”]]).
nexml object is an S4 object, as are all of its components (slots). Its hierarchical structure corresponds exactly with the XML tree of a NeXML file, with the single exception that both XML attributes and children are represented as slots.
S4 objects have constructor functions to initialize them. We create a new
nexml object with the command:
nex <- new("nexml")
We can see a list of slots contained in this object with
 "version" "generator" "xsi:schemaLocation" "namespaces" "otus"  "trees" "characters" "meta" "about" "xsi:type"
Some of these slots have already been populated for us, for instance, the schema version and default namespaces:
nex xsi "http://www.nexml.org/2009" "http://www.w3.org/2001/XMLSchema-instance" xml cdao "http://www.w3.org/XML/1998/namespace" "http://purl.obolibrary.org/obo/" xsd dc "http://www.w3.org/2001/XMLSchema#" "http://purl.org/dc/elements/1.1/" dcterms prism "http://purl.org/dc/terms/" "http://prismstandard.org/namespaces/1.2/basic/" cc ncbi "http://creativecommons.org/ns#" "http://www.ncbi.nlm.nih.gov/taxonomy#" tc "http://rs.tdwg.org/ontology/voc/TaxonConcept#" "http://www.nexml.org/2009"
[email protected] serves the same role as
get_namespaces function, but provides direct access to the slot data. For instance, with this syntax we could also overwrite the existing namespaces with
[email protected] <- NULL. Changing the namespace in this way is not advised.
Some slots can contain multiple elements of the same type, such as
otus. For instance, we see that
 "ListOfcharacters" attr(,"package")  "RNeXML"
is an object of class
ListOfcharacters, and is currently empty,
In order to assign an object to a slot, it must match the class definition of the slot. We can create a new element of any given class with the
and now we have a length-1 list of character matrices,
and we access the first character matrix using the list notation,
[]. Here we check the class is a
 "characters" attr(,"package")  "RNeXML"
Direct subsetting has two primary use cases: (a) useful in looking up (and possibly editing) a specific value of an element, or (b) when adding metadata annotations to specific elements. Consider the example file
f <- system.file("examples", "trees.xml", package="RNeXML") nex <- nexml_read(f)
We can look up the species label of the first
otu in the first
label "species 1"
We can add metadata to this particular OTU using this subsetting format
nex@otus[]@otu[]@meta <- c(meta("skos:note", "This species was incorrectly identified"), nex@otus[]@otu[]@meta)
Here we use the
c operator to append this element to any existing meta annotations to this otu.