[Phylobase-commits] r910 - pkg/R
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Tue Apr 8 19:39:52 CEST 2014
Author: francois
Date: 2014-04-08 19:39:51 +0200 (Tue, 08 Apr 2014)
New Revision: 910
Modified:
pkg/R/labels-methods.R
Log:
updated doc for labels methods
Modified: pkg/R/labels-methods.R
===================================================================
--- pkg/R/labels-methods.R 2014-04-08 17:39:20 UTC (rev 909)
+++ pkg/R/labels-methods.R 2014-04-08 17:39:51 UTC (rev 910)
@@ -3,93 +3,103 @@
### Label accessors
#########################################################
-#' Labels for phylo4/phylo4d objects
-#'
-#' Methods for creating, accessing and updating labels in phylo4/phylo4d
-#' objects
-#'
-#'
-#' In phylo4/phylo4d objects, tips must have labels (that's why there is no
-#' method for hasTipLabels), internal nodes and edges can have labels.
-#'
-#' Labels must be provided as a vector of class \code{character}. The length of
-#' the vector must match the number of elements they label.
-#'
-#' The option \code{use.names} allows the user to match a label to a particular
-#' node. In this case, the vector must have names that match the node numbers.
-#'
-#' The function \code{labels} is mostly intended to be used internally.
-#'
-#' @name phylo4-labels
-#' @aliases labels<- labels,phylo4-method
-#' labels<-,phylo4,ANY,ANY,character-method
-#' labels<-,phylo4d,ANY,ANY,character-method hasDuplicatedLabels
-#' hasDuplicatedLabels-methods hasDuplicatedLabels,phylo4-method hasNodeLabels
-#' hasNodeLabels-methods hasNodeLabels,phylo4-method nodeLabels
-#' nodeLabels-methods nodeLabels,phylo4-method nodeLabels<-
-#' nodeLabels<-,phylo4,character-method nodeLabels<-,phylo4d,ANY-method
-#' tipLabels tipLabels-methods tipLabels,phylo4-method tipLabels<-
-#' tipLabels<-,phylo4,character-method tipLabels<-,phylo4d,character-method
-#' hasEdgeLabels hasEdgeLabels-methods hasEdgeLabels,phylo4-method edgeLabels
-#' edgeLabels<- edgeLabels-methods edgeLabels,phylo4-method
-#' edgeLabels<-,phylo4,character-method
-#' @docType methods
-#' @param x a phylo4 or phylo4d object.
-#' @param object a phylo4 or phylo4d object.
-#' @param type which type of labels: \code{all} (tips and internal nodes),
-#' \code{tip} (tips only), \code{internal} (internal nodes only).
-#' @param value a vector of class \code{character}, see Details for more
-#' information.
-#' @param use.names should the names of the vector used to create/update labels
-#' be used to match the labels? See Details for more information.
-#' @section Methods: \describe{ \item{labels}{\code{signature(object =
-#' "phylo4")}: tip and/or internal node labels, ordered by node ID}
-#'
-#' \item{hasDuplicatedLabels}{\code{signature(object = "phylo4")}: are any
-#' labels duplicated?}
-#'
-#' \item{tipLabels}{\code{signature(object = "phylo4")}: tip labels, ordered by
-#' node ID}
-#'
-#' \item{hasNodeLabels}{\code{signature(object = "phylo4")}: whether tree has
-#' (internal) node labels} \item{nodeLabels}{\code{signature(object =
-#' "phylo4")}: internal node labels, ordered by node ID}
-#'
-#' \item{hasEdgeLabels}{\code{signature(object = "phylo4")}: whether tree has
-#' (internal) edge labels} \item{edgeLabels}{\code{signature(object =
-#' "phylo4")}: internal edge labels, ordered according to the edge matrix} }
-#' @examples
-#'
-#'
-#' data(geospiza)
-#'
-#' ## Return labels from geospiza
-#' tipLabels(geospiza)
-#'
-#' ## Internal node labels in geospiza are empty
-#' nodeLabels(geospiza)
-#'
-#' ## Creating internal node labels
-#' ndLbl <- paste("n", 1:nNodes(geospiza), sep="")
-#' nodeLabels(geospiza) <- ndLbl
-#' nodeLabels(geospiza)
-#'
-#' ## naming the labels
-#' names(ndLbl) <- nodeId(geospiza, "internal")
-#'
-#' ## shuffling the labels
-#' (ndLbl <- sample(ndLbl))
-#'
-#' ## by default, the labels are attributed in the order
-#' ## they are given:
-#' nodeLabels(geospiza) <- ndLbl
-#' nodeLabels(geospiza)
-#'
-#' ## but use.names puts them in the correct order
-#' labels(geospiza, "internal", use.names=TRUE) <- ndLbl
-#' nodeLabels(geospiza)
-#'
-## return labels in increasing node order
+# @aliases labels<- labels,phylo4-method
+# labels<-,phylo4,ANY,ANY,character-method
+# labels<-,phylo4d,ANY,ANY,character-method hasDuplicatedLabels
+# hasDuplicatedLabels-methods hasDuplicatedLabels,phylo4-method hasNodeLabels
+# hasNodeLabels-methods hasNodeLabels,phylo4-method nodeLabels
+# nodeLabels-methods nodeLabels,phylo4-method nodeLabels<-
+# nodeLabels<-,phylo4,character-method nodeLabels<-,phylo4d,ANY-method
+# tipLabels tipLabels-methods tipLabels,phylo4-method tipLabels<-
+# tipLabels<-,phylo4,character-method tipLabels<-,phylo4d,character-method
+# hasEdgeLabels hasEdgeLabels-methods hasEdgeLabels,phylo4-method edgeLabels
+# edgeLabels<- edgeLabels-methods edgeLabels,phylo4-method
+# edgeLabels<-,phylo4,character-method
+
+##' Labels for phylo4/phylo4d objects
+##'
+##' Methods for creating, accessing and updating labels in
+##' phylo4/phylo4d objects
+##'
+##' In phylo4/phylo4d objects, tips must have labels (that's why there
+##' is no method for hasTipLabels), internal nodes and edges can have
+##' labels.
+##'
+##' Labels must be provided as a vector of class \code{character}. The
+##' length of the vector must match the number of elements they label.
+##'
+##' The option \code{use.names} allows the user to match a label to a
+##' particular node. In this case, the vector must have names that
+##' match the node numbers.
+##'
+##' The function \code{labels} is mostly intended to be used
+##' internally.
+##'
+##' @name phylo4-labels
+##' @aliases labels
+##' @docType methods
+##' @param x a phylo4 or phylo4d object.
+##' @param object a phylo4 or phylo4d object.
+##' @param type which type of labels: \code{all} (tips and internal nodes),
+##' \code{tip} (tips only), \code{internal} (internal nodes only).
+##' @param value a vector of class \code{character}, see Details for more
+##' information.
+##' @param use.names should the names of the vector used to create/update labels
+##' be used to match the labels? See Details for more information.
+##' @section Methods: \describe{ \item{labels}{\code{signature(object =
+##' "phylo4")}: tip and/or internal node labels, ordered by node ID}
+##'
+##' \item{hasDuplicatedLabels}{\code{signature(object = "phylo4")}: are any
+##' labels duplicated?}
+##'
+##' \item{tipLabels}{\code{signature(object = "phylo4")}: tip labels, ordered by
+##' node ID}
+##'
+##' \item{hasNodeLabels}{\code{signature(object = "phylo4")}: whether tree has
+##' (internal) node labels} \item{nodeLabels}{\code{signature(object =
+##' "phylo4")}: internal node labels, ordered by node ID}
+##'
+##' \item{hasEdgeLabels}{\code{signature(object = "phylo4")}: whether tree has
+##' (internal) edge labels} \item{edgeLabels}{\code{signature(object =
+##' "phylo4")}: internal edge labels, ordered according to the edge matrix} }
+##' @export
+##' @rdname labels-methods
+##' @include phylo4-class.R phylo4-methods.R phylo4-accessors.R nodeId-methods.R
+##' @author Ben Bolker, Peter Cowan, Steve Kembel, Francois Michonneau
+##' @return labels in ascending order.
+##' @examples
+##'
+##' data(geospiza)
+##'
+##' ## Return labels from geospiza
+##' tipLabels(geospiza)
+##'
+##' ## Internal node labels in geospiza are empty
+##' nodeLabels(geospiza)
+##'
+##' ## Creating internal node labels
+##' ndLbl <- paste("n", 1:nNodes(geospiza), sep="")
+##' nodeLabels(geospiza) <- ndLbl
+##' nodeLabels(geospiza)
+##'
+##' ## naming the labels
+##' names(ndLbl) <- nodeId(geospiza, "internal")
+##'
+##' ## shuffling the labels
+##' (ndLbl <- sample(ndLbl))
+##'
+##' ## by default, the labels are attributed in the order
+##' ## they are given:
+##' nodeLabels(geospiza) <- ndLbl
+##' nodeLabels(geospiza)
+##'
+##' ## but use.names puts them in the correct order
+##' labels(geospiza, "internal", use.names=TRUE) <- ndLbl
+##' nodeLabels(geospiza)
+setGeneric("labels")
+
+##' @rdname labels-methods
+##' @aliases labels,phylo4-method
setMethod("labels", signature(object="phylo4"),
function(object, type = c("all", "tip", "internal")) {
type <- match.arg(type)
@@ -104,6 +114,15 @@
return(lbl)
})
+##' @rdname labels-methods
+##' @aliases labels<-
+setGeneric("labels<-",
+ function(x, type, use.names, ..., value) {
+ standardGeneric("labels<-")
+ })
+
+##' @rdname labels-methods
+##' @aliases labels<-,phylo4,ANY,ANY,character-method
setReplaceMethod("labels",
signature(x="phylo4", type="ANY",
use.names="ANY", value="character"),
@@ -138,7 +157,17 @@
return(x)
})
-### Duplicated Labels
+##### -------- hasDuplicatedLabels
+
+##' @rdname labels-methods
+##' @aliases hasDuplicatedLabels
+setGeneric("hasDuplicatedLabels",
+ function(x, type) {
+ standardGeneric("hasDuplicatedLabels")
+ })
+
+##' @rdname labels-methods
+##' @aliases hasDuplicatedLabels,phylo4,ANY-method
setMethod("hasDuplicatedLabels", signature(x="phylo4", type="ANY"),
function(x, type=c("all", "tip", "internal")) {
## Default options
@@ -149,18 +178,45 @@
any(duplicated(na.omit(labels(x, type))))
})
+##### --------- hasNodeLabels
-### Node Labels
+##' @rdname labels-methods
+##' @aliases hasNodeLabels
+setGeneric("hasNodeLabels", function(x) {
+ standardGeneric("hasNodeLabels")
+})
+
+##' @rdname labels-methods
+##' @aliases hasNodeLabels,phylo4-method
setMethod("hasNodeLabels", signature(x="phylo4"),
function(x) {
!all(is.na(nodeLabels(x)))
})
+##### ---------- nodeLabels
+
+##' @rdname labels-methods
+##' @aliases nodeLabels
+setGeneric("nodeLabels", function(x) {
+ standardGeneric("nodeLabels")
+})
+
+##' @rdname labels-methods
+##' @aliases nodeLabels,phylo4-method
setMethod("nodeLabels", signature(x="phylo4"),
function(x) {
labels(x, type="internal")
})
+##' @rdname labels-methods
+##' @aliases nodeLabels<-
+setGeneric("nodeLabels<-",
+ function(x, ..., value) {
+ standardGeneric("nodeLabels<-")
+ })
+
+##' @rdname labels-methods
+##' @aliases nodeLabels<-,phylo4,character-method
setReplaceMethod("nodeLabels", signature(x="phylo4", value="character"),
function(x, ..., value) {
labels(x, type="internal", ...) <- value
@@ -168,27 +224,63 @@
x
})
-### Tip labels
+##### ---------- tipLabels
+
+##' @rdname labels-methods
+##' @aliases tipLabels
+setGeneric("tipLabels", function(x) {
+ standardGeneric("tipLabels")
+})
+
+##' @rdname labels-methods
+##' @aliases tipLabels,phylo4-method
setMethod("tipLabels", signature(x="phylo4"),
function(x) {
labels(x, type="tip")
})
+##' @rdname labels-methods
+##' @aliases tipLabels<-
+setGeneric("tipLabels<-",
+ function(x, ..., value) {
+ standardGeneric("tipLabels<-")
+})
+
+##' @rdname labels-methods
+##' @aliases tipLabels<-,phylo4,character-method
setReplaceMethod("tipLabels", signature(x="phylo4", value="character"),
function(x, ..., value) {
labels(x, type="tip", ...) <- value
if(is.character(checkval <- checkPhylo4(x))) stop(checkval)
- return(x)
+ return(x)
})
-### Edge labels
+##### ---------- hasEdgeLabels
+
+##' @rdname labels-methods
+##' @aliases hasEdgeLabels
+setGeneric("hasEdgeLabels", function(x) {
+ standardGeneric("hasEdgeLabels")
+})
+
+##' @rdname labels-methods
+##' @aliases hasEdgeLabels,phylo4-method
setMethod("hasEdgeLabels", signature(x="phylo4"),
function(x) {
!all(is.na(x at edge.label))
})
-# return edge labels in order by edgeIds (same order as edge matrix)
+##### ---------- edgeLabels
+
+##' @rdname labels-methods
+##' @aliases edgeLabels
+setGeneric("edgeLabels", function(x) {
+ standardGeneric("edgeLabels")
+})
+
+##' @rdname labels-methods
+##' @aliases edgeLabels,phylo4-method
setMethod("edgeLabels", signature(x="phylo4"),
function(x) {
## [JR: below, using match for ordering rather than direct character
@@ -199,6 +291,15 @@
return(lbl)
})
+##' @rdname labels-methods
+##' @aliases edgeLabels<-
+setGeneric("edgeLabels<-",
+ function(x, ..., value) {
+ standardGeneric("edgeLabels<-")
+ })
+
+##' @rdname labels-methods
+##' @aliases edgeLabels<-,phylo4,character-method
setReplaceMethod("edgeLabels", signature(x="phylo4", value="character"),
function(x, ..., value) {
lbl <- .createEdge(value, x at edge, type="labels")
More information about the Phylobase-commits
mailing list