Skip to content

Commit 1b6ec5b

Browse files
cboettigcboettig
committed
update documentation
1 parent cf96925 commit 1b6ec5b

23 files changed

+193
-97
lines changed

‎LICENSE

+2-34
Original file line numberDiff line numberDiff line change
@@ -1,35 +1,3 @@
1-
YEAR: 2013
1+
YEAR: 2013 - 2014
22
COPYRIGHT HOLDER: Carl Boettiger
3-
ORGANIZATION: rOpenSci
4-
5-
License: BSD_3_clause + file LICENSE
6-
7-
Copyright (c) 2013, rOpenSci
8-
9-
Redistribution and use in source and binary forms, with or without
10-
modification, are permitted provided that the following conditions are
11-
met:
12-
13-
Redistributions of source code must retain the above copyright
14-
notice, this list of conditions and the following disclaimer.
15-
16-
Redistributions in binary form must reproduce the above copyright
17-
notice, this list of conditions and the following disclaimer in
18-
the documentation and/or other materials provided with the
19-
distribution.
20-
21-
Neither the name of the <ORGANIZATION> nor the names of its
22-
contributors may be used to endorse or promote products derived
23-
from this software without specific prior written permission.
24-
25-
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
26-
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
27-
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
28-
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
29-
HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
30-
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
31-
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
32-
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
33-
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
34-
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
35-
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
3+
ORGANIZATION: rOpenSci

‎R/add_basic_meta.R

+1-1
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@
2121
#' citation can be a plain text object, but is preferably an R `citation` or `bibentry` object (which
2222
#' can include multiple citations. See examples
2323
#' @param ... additional arguments, currently no effect.
24-
#' @details \code{add_basic_meta()} is just a wrapper for \link{\code{add_meta}} to make it easy to
24+
#' @details \code{add_basic_meta()} is just a wrapper for \code{\link{add_meta}} to make it easy to
2525
#' provide generic metadata without explicitly providing the namespace. For instance,
2626
#' \code{add_basic_meta(title="My title", description="a description")} is identical to:
2727
#' \code{add_meta(list(meta("dc:title", "My title"), meta("dc:description", "a description")))}

‎R/add_characters.R

+6
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,12 @@
88
#' format.
99
#' @param nexml a nexml object, if appending character table to an existing
1010
#' nexml object. If ommitted will initiate a new nexml object.
11+
#' @param append_to_existing_otus logical. If TRUE, will add any new taxa
12+
#' (taxa not matching any existing otus block) to the existing (first)
13+
#' otus block. Otherwise (default), a new otus block is created, even
14+
#' though it may contain duplicate taxa to those already present. While
15+
#' FALSE is the safe option, TRUE may be appropriate when building nexml
16+
#' files from scratch with both characters and trees.
1117
#' @include classes.R
1218
#' @export
1319
add_characters <- function(x,

‎R/concatenate_nexml.R

+9-4
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,13 @@
11

22
#' Concatenate nexml files
3-
#' @param a nexml object, e.g. from write.nexml() or read.nexml()
4-
#' @param ... additional nexml objects to be concatenated.
5-
#' must have unique ids on all elements
3+
#'
4+
#' Concatenate nexml files
5+
#' @param x,... nexml objects to be concatenated, e.g. from
6+
#' \code{\link{write.nexml}} or \code{\link{read.nexml}}.
7+
#' Must have unique ids on all elements
8+
#' @param recursive logical. If 'recursive = TRUE', the function recursively
9+
#' descends through lists (and pairlists) combining all their
10+
#' elements into a vector. (Not implemented).
611
#' @return a concatenated nexml file
712
#' @examples
813
#' f1 <- system.file("examples", "trees.xml", package="RNeXML")
@@ -12,7 +17,7 @@
1217
#' nex <- c(nex1, nex2)
1318
setMethod("c",
1419
signature("nexml"),
15-
function(x, ...){
20+
function(x, ..., recursive = FALSE){
1621
elements = list(x, ...)
1722
nexml <- new("nexml")
1823
## Check that ids are unique

‎R/get_characters.R

+1-2
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,8 @@
33

44
#' Extract the character matrix
55
#'
6-
#' @param nexml a nexml object
7-
#' @return the list of taxa
86
#' @param nexml nexml object (e.g. from read.nexml)
7+
#' @return the list of taxa
98
#' @export
109
get_characters_list <- function(nexml){
1110
# extract mapping between otus and taxon ids

‎R/get_metadata.R

+1-1
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
#'
66
#' get_metadata
77
#' @param nexml a nexml object
8-
#' @param the name of the level of element desired
8+
#' @param level the name of the level of element desired
99
#' @return the requested metadata
1010
#' @import XML
1111
#' @export

‎R/get_trees.R

+3-2
Original file line numberDiff line numberDiff line change
@@ -97,7 +97,7 @@ setAs("nexml", "phylo", function(from){
9797
#' nexml to phylo
9898
#'
9999
#' nexml to phylo coercion
100-
#' @param tree an nexml tree element (nexml@trees[[i]]@tree[[j]]
100+
#' @param tree an nexml tree element
101101
#' @param otus a character string of taxonomic labels, named by the otu ids.
102102
#' e.g. (from get_otu_maps for the otus set matching the relevant trees node.
103103
#' @return phylo object
@@ -132,7 +132,8 @@ toPhylo <- function(tree, otus){
132132

133133
## Identifies tip.label based on being named with OTUs while others are NULL
134134
## FIXME Should instead decide that these are tips based on the edge labels?
135-
nodes <- cbind(plyr::arrange(nodes, otu), id = 1:dim(nodes)[1])
135+
nodes <- cbind(plyr::arrange(nodes, otu), id = 1:dim(nodes)[1]) # Also warns because arrange isn't quoting the column name.
136+
136137
## NB: these ids are the ape:id numbers by which nodes are identified in ape::phylo
137138
## Arbitrary ids are not supported - ape expecs the numbers 1:n, starting with tips.
138139

‎R/meta.R

+15-2
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,8 @@
2121
#' numeric - xs:decimal,
2222
#' logical - xs:boolean
2323
#'
24+
#' @examples
25+
#' meta(content="example", property="dc:title")
2426
#' @export
2527
#' @seealso \code{\link{nexml_write}}
2628
meta <- function(property = character(0),
@@ -125,10 +127,21 @@ nexml_citation <- function(obj){
125127

126128

127129

128-
130+
#' Concatenate meta elements into a ListOfmeta
131+
#'
132+
#' Concatenate meta elements into a ListOfmeta
133+
#' @param x,... meta elements to be concatenated, e.g. see \code{\link{meta}}
134+
#' @param recursive logical, if 'recursive=TRUE', the function
135+
#' descends through lists and combines their elements into a vector.
136+
#' Currently not implemented. so "c(meta, c(meta))" will not work.
137+
#' @return a listOfmeta object containing multiple meta elements.
138+
#' @examples
139+
#' c(meta(content="example", property="dc:title"),
140+
#' meta(content="Carl", property="dc:creator"))
141+
#'
129142
setMethod("c",
130143
signature("meta"),
131-
function(x, ...){
144+
function(x, ..., recursive = FALSE){
132145
elements <- list(x, ...)
133146
new("ListOfmeta", elements)
134147
})

‎R/nexml_write.R

+3-1
Original file line numberDiff line numberDiff line change
@@ -3,10 +3,12 @@
33
#' @param x a nexml object, or any phylogeny object (e.g. phylo, phylo4)
44
#' that can be coerced into one. Can also be omitted, in which case a new
55
#' nexml object will be constructed with the additional parameters specified.
6+
#' @param file the name of the file to write out
67
#' @param trees phylogenetic trees to add to the nexml file (if not already given in x)
78
#' see \code{\link{add_trees}} for details.
89
#' @param characters additional characters
9-
#' @param file the name of the file to write out
10+
#' @param meta A meta element or list of meta elements, see \code{\link{add_meta}}
11+
#' @param ... additional arguments to add_meta, such as the namespaces. See \code{\link{add_meta}}.
1012
#' @return Writes out a nexml file
1113
#' @import ape
1214
#' @import XML

‎R/simmap.R

+1-1
Original file line numberDiff line numberDiff line change
@@ -62,7 +62,7 @@ simmap_edge_annotations <- function(maps, nexml, state_ids = NULL, char_id = "si
6262
mapping <- lapply(1:length(edge_map), function(j){
6363
## A node has an id, a length and a state
6464
meta(property = "simmap:stateChange",
65-
children = list(meta(propery = "simmap:order",
65+
children = list(meta(property = "simmap:order",
6666
content = j),
6767
meta(property = "simmap:length",
6868
content = edge_map[[j]]),

‎R/taxize_nexml.R

+10-8
Original file line numberDiff line numberDiff line change
@@ -12,15 +12,17 @@
1212
taxize_nexml <- function(nexml, type = c("NCBI"), ...){
1313
type <- match.arg(type)
1414
if(type == "NCBI"){
15-
for(i in 1:length(nexml@otus@otu)){
16-
id <- get_uid(nexml@otus@otu[[i]]@label)
17-
if(is.na(id))
18-
warning(paste("ID for otu", nexml@otus@otu[[i]]@label, "not found. Consider checking the spelling or alternate classification"))
19-
else
20-
nexml@otus@otu[[i]]@meta <- new("ListOfmeta", list(
21-
meta(href = paste0("http://ncbi.nlm.nih.gov/taxonomy/", id),
22-
rel = "tc:toTaxon")))
15+
for(j in 1:length(nexml@otus)){
16+
for(i in 1:length(nexml@otus[[j]]@otu)){
17+
id <- get_uid(nexml@otus[[j]]@otu[[i]]@label)
18+
if(is.na(id))
19+
warning(paste("ID for otu", nexml@otus[[j]]@otu[[i]]@label, "not found. Consider checking the spelling or alternate classification"))
20+
else
21+
nexml@otus[[j]]@otu[[i]]@meta <- new("ListOfmeta", list(
22+
meta(href = paste0("http://ncbi.nlm.nih.gov/taxonomy/", id),
23+
rel = "tc:toTaxon")))
2324

25+
}
2426
}
2527
}
2628
nexml

‎README.md

+53-12
Original file line numberDiff line numberDiff line change
@@ -46,10 +46,10 @@ Read in a `nexml` file into the `ape::phylo` format:
4646
f <- system.file("examples", "comp_analysis.xml", package="RNeXML")
4747
nexml <- nexml_read(f)
4848
tr <- get_trees(nexml) # or: as(nexml, "phylo")
49-
plot(tr[[1]])
49+
plot(tr)
5050
```
5151

52-
![plot of chunk unnamed-chunk-4](http://farm8.staticflickr.com/7296/12662932795_51f8b84960_o.png)
52+
![plot of chunk unnamed-chunk-4](http://farm3.staticflickr.com/2796/12974975053_189f56ab06_o.png)
5353

5454

5555
Write an `ape::phylo` tree into the `nexml` format:
@@ -256,19 +256,60 @@ We can then fire up `geiger` and fit, say, a Brownian motion model the continuou
256256

257257
```coffee
258258
library(geiger)
259-
fitContinuous(tree, traits[[1]])
260-
```
261-
262-
```
263-
## Error: names for 'data' must be supplied
259+
fitContinuous(tree, traits[1])
260+
```
261+
262+
```
263+
## GEIGER-fitted comparative model of continuous data
264+
## fitted 'BM' model parameters:
265+
## sigsq = 1.166011
266+
## z0 = 0.255591
267+
##
268+
## model summary:
269+
## log-likelihood = -20.501183
270+
## AIC = 45.002367
271+
## AICc = 46.716652
272+
## free parameters = 2
273+
##
274+
## Convergence diagnostics:
275+
## optimization iterations = 100
276+
## failed iterations = 0
277+
## frequency of best fit = 1.00
278+
##
279+
## object summary:
280+
## 'lik' -- likelihood function
281+
## 'bnd' -- bounds for likelihood search
282+
## 'res' -- optimization iteration summary
283+
## 'opt' -- maximum likelihood parameter estimates
264284
```
265285

266286
```coffee
267-
fitDiscrete(tree, traits[[2]])
268-
```
269-
270-
```
271-
## Error: names for 'data' must be supplied
287+
fitDiscrete(tree, traits[2])
288+
```
289+
290+
```
291+
## GEIGER-fitted comparative model of discrete data
292+
## fitted Q matrix:
293+
## 0 1
294+
## 0 -0.07308 0.07308
295+
## 1 0.07308 -0.07308
296+
##
297+
## model summary:
298+
## log-likelihood = -4.574133
299+
## AIC = 11.148266
300+
## AICc = 11.648266
301+
## free parameters = 1
302+
##
303+
## Convergence diagnostics:
304+
## optimization iterations = 100
305+
## failed iterations = 0
306+
## frequency of best fit = 1.00
307+
##
308+
## object summary:
309+
## 'lik' -- likelihood function
310+
## 'bnd' -- bounds for likelihood search
311+
## 'res' -- optimization iteration summary
312+
## 'opt' -- maximum likelihood parameter estimates
272313
```
273314

274315

‎inst/doc/pubs/README.Rmd

+3-3
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,7 @@ Read in a `nexml` file into the `ape::phylo` format:
4747
f <- system.file("examples", "comp_analysis.xml", package="RNeXML")
4848
nexml <- nexml_read(f)
4949
tr <- get_trees(nexml) # or: as(nexml, "phylo")
50-
plot(tr[[1]])
50+
plot(tr)
5151
```
5252

5353
Write an `ape::phylo` tree into the `nexml` format:
@@ -165,8 +165,8 @@ We can then fire up `geiger` and fit, say, a Brownian motion model the continuou
165165

166166
```{r}
167167
library(geiger)
168-
fitContinuous(tree, traits[[1]])
169-
fitDiscrete(tree, traits[[2]])
168+
fitContinuous(tree, traits[1])
169+
fitDiscrete(tree, traits[2])
170170
```
171171

172172

‎inst/doc/pubs/README.md

+53-12
Original file line numberDiff line numberDiff line change
@@ -46,10 +46,10 @@ Read in a `nexml` file into the `ape::phylo` format:
4646
f <- system.file("examples", "comp_analysis.xml", package="RNeXML")
4747
nexml <- nexml_read(f)
4848
tr <- get_trees(nexml) # or: as(nexml, "phylo")
49-
plot(tr[[1]])
49+
plot(tr)
5050
```
5151

52-
![plot of chunk unnamed-chunk-4](http://farm8.staticflickr.com/7296/12662932795_51f8b84960_o.png)
52+
![plot of chunk unnamed-chunk-4](http://farm3.staticflickr.com/2796/12974975053_189f56ab06_o.png)
5353

5454

5555
Write an `ape::phylo` tree into the `nexml` format:
@@ -256,19 +256,60 @@ We can then fire up `geiger` and fit, say, a Brownian motion model the continuou
256256

257257
```r
258258
library(geiger)
259-
fitContinuous(tree, traits[[1]])
260-
```
261-
262-
```
263-
## Error: names for 'data' must be supplied
259+
fitContinuous(tree, traits[1])
260+
```
261+
262+
```
263+
## GEIGER-fitted comparative model of continuous data
264+
## fitted 'BM' model parameters:
265+
## sigsq = 1.166011
266+
## z0 = 0.255591
267+
##
268+
## model summary:
269+
## log-likelihood = -20.501183
270+
## AIC = 45.002367
271+
## AICc = 46.716652
272+
## free parameters = 2
273+
##
274+
## Convergence diagnostics:
275+
## optimization iterations = 100
276+
## failed iterations = 0
277+
## frequency of best fit = 1.00
278+
##
279+
## object summary:
280+
## 'lik' -- likelihood function
281+
## 'bnd' -- bounds for likelihood search
282+
## 'res' -- optimization iteration summary
283+
## 'opt' -- maximum likelihood parameter estimates
264284
```
265285

266286
```r
267-
fitDiscrete(tree, traits[[2]])
268-
```
269-
270-
```
271-
## Error: names for 'data' must be supplied
287+
fitDiscrete(tree, traits[2])
288+
```
289+
290+
```
291+
## GEIGER-fitted comparative model of discrete data
292+
## fitted Q matrix:
293+
## 0 1
294+
## 0 -0.07308 0.07308
295+
## 1 0.07308 -0.07308
296+
##
297+
## model summary:
298+
## log-likelihood = -4.574133
299+
## AIC = 11.148266
300+
## AICc = 11.648266
301+
## free parameters = 1
302+
##
303+
## Convergence diagnostics:
304+
## optimization iterations = 100
305+
## failed iterations = 0
306+
## frequency of best fit = 1.00
307+
##
308+
## object summary:
309+
## 'lik' -- likelihood function
310+
## 'bnd' -- bounds for likelihood search
311+
## 'res' -- optimization iteration summary
312+
## 'opt' -- maximum likelihood parameter estimates
272313
```
273314

274315

0 commit comments

Comments
 (0)