# The nexml S4 Object

#### Carl Boettiger

#### Scott Chamberlain

#### Rutger Vos

#### Hilmar Lapp

## Understanding the `nexml` S4 object

The `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 `ouch` and `phylobase`. The `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[[1]]` or named arguments such as phy[[“edge”]]).

The `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

    slotNames(nex)

     [1] "version"            "generator"          "xsi:schemaLocation" "namespaces"         "otus"
     [6] "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@version

    [1] "0.9"

    nex@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"

Recognize that `nex@namespaces` 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 `nex@namespaces <- NULL`. Changing the namespace in this way is not advised.

Some slots can contain multiple elements of the same type, such as `trees`, `characters`, and `otus`. For instance, we see that

    class(nex@characters)

    [1] "ListOfcharacters"
    attr(,"package")
    [1] "RNeXML"

is an object of class `ListOfcharacters`, and is currently empty,

    length(nex@characters)

    [1] 0

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 `new` function,

    nex@characters <- new("ListOfcharacters", list(new("characters")))

and now we have a length-1 list of character matrices,

    length(nex@characters)

    [1] 1

and we access the first character matrix using the list notation, `[[1]]`. Here we check the class is a `characters` object.

    class(nex@characters[[1]])

    [1] "characters"
    attr(,"package")
    [1] "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 `otus` block:

    nex@otus[[1]]@otu[[1]]@label

          label
    "species 1"

We can add metadata to this particular OTU using this subsetting format

    nex@otus[[1]]@otu[[1]]@meta <-
      c(meta("skos:note",
              "This species was incorrectly identified"),
             nex@otus[[1]]@otu[[1]]@meta)

Here we use the `c` operator to append this element to any existing meta annotations to this otu.