From 8059f872c70182318efa2a7a1562a547380e39c6 Mon Sep 17 00:00:00 2001 From: Gregory Jefferis Date: Tue, 8 May 2018 09:33:55 +0100 Subject: [PATCH] Export graph.nodes and improve docs for root points * closes #373 * but note that #374 is documented but not fixed --- NAMESPACE | 1 + R/graph-nodes.R | 55 +++++++++++++++++++++++++++++++++++----------- man/graph.nodes.Rd | 24 ++++++++++++++++---- man/rootpoints.Rd | 34 +++++++++++++++++++++------- 4 files changed, 89 insertions(+), 25 deletions(-) diff --git a/NAMESPACE b/NAMESPACE index 4052991f..3e0ace9d 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -210,6 +210,7 @@ export(find.soma) export(flip) export(getformatreader) export(getformatwriter) +export(graph.nodes) export(ijkpos) export(im3d) export(imexpand.grid) diff --git a/R/graph-nodes.R b/R/graph-nodes.R index e347d9c1..9d2db73a 100644 --- a/R/graph-nodes.R +++ b/R/graph-nodes.R @@ -1,13 +1,28 @@ #' Return root, end, or branchpoints of an igraph object -#' -#' @details Note that the graph must be directed in order to return a root point -#' @param x An igraph object +#' +#' @details This function underlies \code{\link{rootpoints.igraph}} methods and +#' friends. It is conceived of as slightly lower level and end users would +#' normally use the \code{rootpoints} methods. +#' +#' \code{graph.nodes} should work for any \code{\link{igraph}} object +#' (including \code{\link{ngraph}} objects, which inherit from \code{igraph}). +#' However the graph must be directed in order to return a root point +#' @param x An igraph (or \code{\link{ngraph}}) object #' @param type one of root, end (which includes root) or branch -#' @param original.ids Use named attribute to return original vertex ids (when +#' @param original.ids Use named attribute to return original vertex ids (when #' available). Set to FALSE when this is not desired. -#' @param exclude.isolated Do not count isolated vertices as root points +#' @param exclude.isolated Do not count isolated vertices as root points #' (default) #' @importFrom igraph V degree get.vertex.attribute +#' @export +#' @seealso \code{\link{rootpoints}}, \code{\link{ngraph}} +#' @examples +#' ng=as.ngraph(Cell07PNs[[1]]) +# resetof igraph::vertex_attr(ng, 'name') <-sample(500, nvertices(ng)) +#' # arbitrary vertex identifiers +#' graph.nodes(ng, type = 'end') +#' # raw vertex indices +#' graph.nodes(ng,type = 'end', original.ids = FALSE) graph.nodes<-function(x, type=c('root','end','branch'), original.ids='name', exclude.isolated=TRUE){ type=match.arg(type) @@ -33,13 +48,25 @@ graph.nodes<-function(x, type=c('root','end','branch'), original.ids='name', vertex_names } -#' Return the root or branch points of a neuron or graph +#' Return the root, branch, or end points of a neuron or graph #' -#' A neuron may have multiple subtrees and therefore multiple roots -#' @param x Neuron or other object which might have roots -#' @param ... Further arguments passed to methods -#' @return Integer point number of root/branch point +#' @description \code{rootpoints} returns the root point(s) (one per tree, often +#' the soma). +#' @details A neuron may have multiple subtrees and therefore multiple roots. At +#' present there is discrepancy between the \code{*.neuron} and +#' \code{*.igraph} methods. For \code{neuron}s we return the node indices, for +#' \code{igraph}/\code{ngraph} objects the node identifiers (aka +#' names/PointNo) +#' @param x Neuron or other object (e.g. \code{igraph}) which might have roots +#' @param ... Further arguments passed to methods (for \code{\link{ngraph}} or +#' \code{igraph} objects eventually \code{\link{graph.nodes}})). +#' @return FIXME Raw indices (in range 1:N) of vertices when \code{x} is a +#' neuron, integer point identifier (aka PointNo) othwerise. #' @export +#' @seealso \code{\link{graph.nodes}}, \code{\link{ngraph}} +#' @examples +#' rootpoints(Cell07PNs[[1]]) +#' endpoints(Cell07PNs[[1]]) rootpoints<-function (x, ...) UseMethod("rootpoints") @@ -66,7 +93,7 @@ rootpoints.neuron<-function(x, subtrees=1, ...){ #' @export rootpoints.igraph<-function(x, ...) graph.nodes(x, type='root', ...) -#' Return the branchpoints of a neuron or graph +#' @description \code{branchpoints} returns the branch points. #' @export #' @rdname rootpoints #' @aliases branchpoints @@ -79,8 +106,8 @@ branchpoints<-function (x, ...) branchpoints.default<-function(x, ...) branchpoints(as.ngraph(x), ...) #' @rdname rootpoints -#' @details \code{branchpoints.neuron} returns a list if more than one subtree is -#' specified +#' @details \code{branchpoints.neuron} returns a list if more than one subtree +#' is specified #' @export #' @method branchpoints neuron branchpoints.neuron<-function(x, subtrees=1, ...){ @@ -96,6 +123,8 @@ branchpoints.neuron<-function(x, subtrees=1, ...){ #' @export branchpoints.igraph<-function(x, ...) graph.nodes(x, type='branch', ...) +#' @description \code{endpoints} returns the end points (aka leaf nodes); the +#' root point will be returned if it also a leaf node. #' @rdname rootpoints #' @export endpoints<-function (x, ...) UseMethod("endpoints") diff --git a/man/graph.nodes.Rd b/man/graph.nodes.Rd index ef242caf..bc0b7ba6 100644 --- a/man/graph.nodes.Rd +++ b/man/graph.nodes.Rd @@ -8,19 +8,35 @@ graph.nodes(x, type = c("root", "end", "branch"), original.ids = "name", exclude.isolated = TRUE) } \arguments{ -\item{x}{An igraph object} +\item{x}{An igraph (or \code{\link{ngraph}}) object} \item{type}{one of root, end (which includes root) or branch} -\item{original.ids}{Use named attribute to return original vertex ids (when +\item{original.ids}{Use named attribute to return original vertex ids (when available). Set to FALSE when this is not desired.} -\item{exclude.isolated}{Do not count isolated vertices as root points +\item{exclude.isolated}{Do not count isolated vertices as root points (default)} } \description{ Return root, end, or branchpoints of an igraph object } \details{ -Note that the graph must be directed in order to return a root point +This function underlies \code{\link{rootpoints.igraph}} methods and + friends. It is conceived of as slightly lower level and end users would + normally use the \code{rootpoints} methods. + + \code{graph.nodes} should work for any \code{\link{igraph}} object + (including \code{\link{ngraph}} objects, which inherit from \code{igraph}). + However the graph must be directed in order to return a root point +} +\examples{ +ng=as.ngraph(Cell07PNs[[1]]) +# arbitrary vertex identifiers +graph.nodes(ng, type = 'end') +# raw vertex indices +graph.nodes(ng,type = 'end', original.ids = FALSE) +} +\seealso{ +\code{\link{rootpoints}}, \code{\link{ngraph}} } diff --git a/man/rootpoints.Rd b/man/rootpoints.Rd index 693d0d02..fac2d4f1 100644 --- a/man/rootpoints.Rd +++ b/man/rootpoints.Rd @@ -13,7 +13,7 @@ \alias{endpoints.neuron} \alias{endpoints.igraph} \alias{endpoints.default} -\title{Return the root or branch points of a neuron or graph} +\title{Return the root, branch, or end points of a neuron or graph} \usage{ rootpoints(x, ...) @@ -40,27 +40,45 @@ endpoints(x, ...) \method{endpoints}{default}(x, ...) } \arguments{ -\item{x}{Neuron or other object which might have roots} +\item{x}{Neuron or other object (e.g. \code{igraph}) which might have roots} -\item{...}{Further arguments passed to methods} +\item{...}{Further arguments passed to methods (for \code{\link{ngraph}} or +\code{igraph} objects eventually \code{\link{graph.nodes}})).} \item{subtrees}{Integer index of the fully connected subtree in \code{x$SubTrees}. Only applicable when a \code{neuron} consists of multiple unconnected subtrees.} } \value{ -Integer point number of root/branch point +FIXME Raw indices (in range 1:N) of vertices when \code{x} is a + neuron, integer point identifier (aka PointNo) othwerise. } \description{ -A neuron may have multiple subtrees and therefore multiple roots +\code{rootpoints} returns the root point(s) (one per tree, often + the soma). -Return the branchpoints of a neuron or graph +\code{branchpoints} returns the branch points. + +\code{endpoints} returns the end points (aka leaf nodes); the + root point will be returned if it also a leaf node. } \details{ -\code{branchpoints.neuron} returns a list if more than one subtree is - specified +A neuron may have multiple subtrees and therefore multiple roots. At + present there is discrepancy between the \code{*.neuron} and + \code{*.igraph} methods. For \code{neuron}s we return the node indices, for + \code{igraph}/\code{ngraph} objects the node identifiers (aka + names/PointNo) + +\code{branchpoints.neuron} returns a list if more than one subtree + is specified +} +\examples{ +rootpoints(Cell07PNs[[1]]) +endpoints(Cell07PNs[[1]]) } \seealso{ +\code{\link{graph.nodes}}, \code{\link{ngraph}} + Other neuron: \code{\link{neuron}}, \code{\link{ngraph}}, \code{\link{plot.dotprops}}, \code{\link{potential_synapses}}, \code{\link{prune}},