Commit 052d6edc by Eric Coissac

Commit the man pages and make aggregate public again

parent 51f152cc
.Rproj.user
.Rhistory
.RData
loopbenchmark.R
......@@ -101,9 +101,10 @@ aggregate.metabarcoding.data=function(x, by, FUN,...,
m = matrix(as.character(x[[n]]))
dim(m)=df
}
else
else {
m = x[[n]]
isfact=FALSE
}
aggr.args = list(m,by=by,FUN=f,simplify=FALSE)
lagr = do.call(aggregate,aggr.args)
lagr = as.factor.or.matrix(lagr[,-(1:ncat),drop=FALSE])
......@@ -182,15 +183,15 @@ aggregate.metabarcoding.data=function(x, by, FUN,...,
for (n in ln) {
f = layers[[n]]
if (is.factor(x[[n]])){
isfact=is.factor(x[[n]])
if (isfact){
isfact = TRUE
lf = levels(x[[n]])
df = dim(x[[n]])
m = matrix(as.character(x[[n]]))
dim(m)=df
}
else
else
m = x[[n]]
aggr.args = list(t(m),by=by,FUN=f,simplify=FALSE)
......
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ROBITools.R
\docType{package}
\name{ROBITools-package}
\alias{ROBITools-package}
\alias{ROBITools}
\title{A package to manipulate DNA metabarcoding data.}
\description{
A package to manipulate DNA metabarcoding data.
}
\details{
This package was written as a following of the OBITools.
\tabular{ll}{
Package: \tab ROBITools\cr
Type: \tab Package\cr
Version: \tab 0.1\cr
Date: \tab 2013-06-27\cr
License: \tab CeCILL 2.0\cr
LazyLoad: \tab yes\cr
}
}
\references{
http://metabarcoding.org/obitools
}
\author{
Frederic Boyer
Aurelie Bonin
Lucie Zinger
Eric Coissac
}
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/s3objects.R
\name{addS3Class}
\alias{addS3Class}
\title{Adds a class into the class hierarchie attribute.}
\usage{
addS3Class(object, classname)
}
\arguments{
\item{object}{the object to modify}
\item{classname}{the name of the new class}
}
\value{
the object given as parametter casted to the new
class
}
\description{
\code{addS3Class} adds a new class name to the vector
of class associated to the object. This the way to
assign an object to an S3 class. \code{addS3Class} add
the new class name in front of the class vector
}
\note{
for efficiency purpose no check is done on the input
parametters
}
\examples{
x = c(1,3,2,5)
x = addS3Class(x,"my.vector")
class(x)
}
\seealso{
\code{\link{rmS3Class}}
}
\author{
Eric Coissac
}
\keyword{function}
\keyword{system}
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/metabarcoding_threshold.R
\docType{methods}
\name{const.threshold.mask,metabarcoding.data-method}
\alias{const.threshold.mask,metabarcoding.data-method}
\alias{const.threshold.mask-methods,metabarcoding.data}
\title{Computes a constant thresold mask for filtering read aboundancies.}
\usage{
\S4method{const.threshold.mask}{metabarcoding.data}(data, MARGIN,
threshold = 0.01, operator = "<")
}
\arguments{
\item{data}{The \code{\linkS4class{metabarcoding.data}} instance
on normalisation have to be computed.}
\item{MARGIN}{Indicates if the sums have to be computed across
samples or motus.
Allowed values are :
\itemize{
\item{'sample' or 1} for computing sum across samples
\item{'motu' or 2} for computing sum across motus
}}
\item{threshold}{a numeric value between 0 and 1 indicating which part of
the signal must be conserved. Default value is setup to
0.01 (1% of the normalized signal).}
\item{operator}{is a logical comparison operator.}
}
\value{
A logical matrix usable for selecting cell in the read aboundancy matrix.
}
\description{
The method \code{const.threshold.mask} of the class \code{\linkS4class{metabarcoding.data}}
computes a logical matrix of the same size than the read matrix of the data parameter.
Each cell of this matrix contains a \code{TRUE} or a \code{FALSE} value according to the
relationship existing between the read abondancy and the global theshold.
}
\details{
(computed value) = (normalized read aboundancy) operator (threshold value)
for a cell in the result matrix, \code{(normalized read aboundancy)} is extracted from the read layer
after normalization.
\code{operator} is a comparaison operator and \code{(threshold value)} is estimated with the
\code{\link{theshold}} method.
}
\seealso{
\code{\linkS4class{metabarcoding.data}}, \code{\link{threshold.mask}}, \code{\link{normalize}}
}
\author{
Aurelie Bonin
}
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/contaslayer.R
\name{contaslayer}
\alias{contaslayer}
\title{Detects contaminants in metabarcoding data}
\usage{
contaslayer(x, controls, clust = NULL)
}
\arguments{
\item{x}{a \code{\link{metabarcoding.data}} object}
\item{controls}{a vector of samples names where conta are suspected to be detected
(typically negative control names).}
\item{clust}{a vector for grouping sequences. Default set to \code{NULL}.}
}
\value{
a vector containing the names of sequences identified as contaminants
}
\description{
Detects sequences/motus in a \code{\link{metabarcoding.data}} object
for which frequencies over the entire dataset are maximum in negative controls and
hence, most likely to be contaminants.
}
\examples{
data(termes)
termes.ok = termes[,colSums(termes$reads)>0]
neg = rownames(termes.ok)[grep("r",rownames(termes.ok))]
#finds contaminants based on neg samples
contaslayer(termes.ok, neg)
# extanding contamininant detection with grouping factor,
# typically obiclean/sumatra cluster or taxonomy membership
contaslayer(termes.ok, neg, termes.ok$motus$scientific_name)
}
\seealso{
\code{\link{threshold}} for further trimming
}
\author{
Lucie Zinger
}
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/s3objects.R
\name{createS3Class}
\alias{createS3Class}
\title{create basic functions to manipulate a new S3 class}
\usage{
createS3Class(classname)
}
\arguments{
\item{classname}{a \code{character string} indicating the name
of the new class.}
}
\description{
createS3Class function create in the \code{package:ROBITools}
environment an \code{is.xxx} function and an \code{as.xxx} function
allowing to test if an abject belong the class \code{xxx} and to add
the class \code{xxx} to the class list of an object. \code{xxx} is a
generic class name that is specified through the \code{classname}
argument of the function.
}
\note{
Take care that the new functions are created in the
\code{package:ROBITools} environment.
}
\examples{
# Create a new S3 class named mynewclass
createS3Class('mynewclass')
#create a new vector object
x=c(1,4,6)
# test if it belongs the new class, that is false
is.mynewclass(x)
# Associate x to the new class
as.mynewclass(x)
# test again if x belongs the new class, that is now true
is.mynewclass(x)
}
\seealso{
\code{\link{rmS3Class}}
}
\author{
Eric Coissac
}
\keyword{function}
\keyword{system}
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/taxoDBtree.R
\name{dbtree}
\alias{dbtree}
\title{Construct a taxonomic tree from a list of taxa}
\usage{
dbtree(x)
}
\arguments{
\item{x}{a table containing the taxonomic path of the references. Typically an output from get.classic.taxonomy}
}
\value{
g a directed graph displaying the taxonomy hierarchy of the input data. Stored in a \code{\link{igraph}} object
where the taxonomic ranks of the vertices are added to the vertices attributes
}
\description{
Construct a graph from a table containing the taxonomic path of sequences
}
\examples{
data(termes)
taxo=default.taxonomy()
termes.taxo.table = get.classic.taxonomy(termes, taxo, "taxid")
head(termes.taxo.table)
graph.tax.termes = dbtree(termes.taxo.table[,1:7])
library(igraph)
#plot the tree
coord = layout.reingold.tilford(graph.tax.termes, root=1, circular=F)
v.cex = as.factor(V(graph.tax.termes)$rank)
levels(v.cex) = match(levels(v.cex), colnames(termes.taxo.table))
plot(graph.tax.termes, vertex.size=1, vertex.label.cex=2*(as.numeric(as.vector(v.cex))^-1), edge.arrow.size=0, layout=coord)
#Vizualization with sequence counts
tax.count = log10(colSums(termes$reads)[match(as.vector(V(graph.tax.termes)$name), termes$motus$scientific_name)])
tax.count[is.na(tax.count)|tax.count<0] = 0.01
V(graph.tax.termes)$count = unname(tax.count)
plot(graph.tax.termes, vertex.size=V(graph.tax.termes)$count, vertex.label.cex=2*(as.numeric(as.vector(v.cex))^-1), edge.arrow.size=0, layout=coord)
}
\seealso{
\code{\link{get.classic.taxonomy}}
}
\author{
Lucie Zinger
}
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/mstat.R
\name{dist.center.group}
\alias{dist.center.group}
\title{Builds the list of sample groups included in a circle around a central sample}
\usage{
dist.center.group(dtable, radius, center = TRUE)
}
\arguments{
\item{dtable}{a distance table between samples as
computed by \code{\link{dist.grid}}}
\item{radius}{the radius of the circle}
\item{center}{a \code{logical} value indicating if the center of
the group must be included in the group}
}
\value{
a list of vectors containing the labels of the group members
}
\description{
Builds the list of sample groups included in a circle around a central sample
}
\examples{
data(termes)
termes.ok = termes[,colSums(termes$reads)>0]
pos = expand.grid(1:3 * 10,1:7 * 10)
labels = rownames(termes.ok)
d = dist.grid(pos[,1],pos[2],labels)
groups = dist.center.group(d,20)
}
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/mstat.R
\name{dist.clique.group}
\alias{dist.clique.group}
\title{Builds the list of sample groups including samples closest than a define distance}
\usage{
dist.clique.group(dtable, dmax, center = True)
}
\arguments{
\item{dtable}{a distance table between samples as
computed by \code{\link{dist.grid}}}
\item{dmax}{the maximum distance between two samples}
}
\value{
a list of vectors containing the labels of the group members
}
\description{
A graph is build by applying the threshold \code{dmax} to the distance matrix
A group is a clique max in this graph. Consequently all member pairs of a group
are distant by less or equal to \code{dmax}.
}
\examples{
data(termes)
termes.ok = termes[,colSums(termes$reads)>0]
pos = expand.grid(1:3 * 10,1:7 * 10)
labels = rownames(termes.ok)
d = dist.grid(pos[,1],pos[2],labels)
groups = dist.clique.group(d,20)
}
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/mstat.R
\name{dist.grid}
\alias{dist.grid}
\title{Computes the pairwise distance matrix as a data.frame where}
\usage{
dist.grid(x, y, labels = NULL)
}
\arguments{
\item{x}{a vector for the X coordinates}
\item{y}{a vector for the Y coordinates}
\item{labels}{a vector with the sample names}
}
\value{
a data.frame instance of three columns
- a : The label of the first sample
- b : The label of the second sample
- dist : The euclidian distance beween sample a and b
}
\description{
Computes the pairwise distance matrix as a data.frame where
}
\examples{
data(termes)
termes.ok = termes[,colSums(termes$reads)>0]
pos = expand.grid(1:3 * 10,1:7 * 10)
labels = rownames(termes.ok)
d = dist.grid(pos[,1],pos[2],labels)
}
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/mstat.R
\name{dm.univariate}
\alias{dm.univariate}
\title{Simulate null distribion of the M statistics by Monte-Carlo}
\usage{
dm.univariate(w, groups, resampling = 100)
}
\arguments{
\item{w}{the weigth matrix indicating the presence probability of each motu
in each samples. Each line corresponds to a sample and each column
to a MOTU. \code{rownames} of the \code{w} matrix must be the sample
names.}
\item{groups}{the list of considered groups as computed by the \code{\link{dist.center.group}}
function}
\item{resampling}{the number of simulation to establish the null distribution}
}
\value{
a matrix of M score under the null hypothesis of random distribution of MOTUs
with a MOTUs per line and a culumn per simulation
}
\description{
Computes the null empirical distribution of the M statistics
by shuffling MOTUs among location.
}
\examples{
data(termes)
termes.ok = termes[,colSums(termes$reads)>0]
pos = expand.grid(1:3 * 10,1:7 * 10)
labels = rownames(termes.ok)
d = dist.grid(pos[,1],pos[2],labels)
groups = dist.center.group(d,20)
w = m.weight(termes.ok)
dnull = dm.univariate(w,groups)
}
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/layers.metabarcoding.R
\docType{methods}
\name{[[,metabarcoding.data-method}
\alias{[[,metabarcoding.data-method}
\alias{double-open-brace-methods,metabarcoding.data}
\title{Returns the a layer associated to a \code{\link{metabarcoding.data}}}
\usage{
\method{[[}{unmutable}(x,i)
}
\arguments{
\item{x}{a \code{\link{metabarcoding.data}} instance}
}
\value{
matrix or a factor.
}
\description{
[[ operator Extracts a layer
attached to a \code{\link{metabarcoding.data}} instance.
}
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/obiclean.R
\docType{methods}
\name{extracts.obiclean,metabarcoding.data-method}
\alias{extracts.obiclean,metabarcoding.data-method}
\alias{extracts.obiclean-methods,metabarcoding.data}
\title{Extracts the obiclean results}
\usage{
\S4method{extracts.obiclean}{metabarcoding.data}(obj)
}
\arguments{
\item{obj}{the \code{\linkS4class{metabarcoding.data}} to analyze}
}
\value{
the modified \code{\linkS4class{metabarcoding.data}} instance
}
\description{
The method \code{extracts.obiclean} of the class \code{\linkS4class{metabarcoding.data}}
extracts \code{obiclean} results from the MOTUs descriptions include in the
\code{\linkS4class{metabarcoding.data}} instance.
When an \code{obitab} file is imported using the \code{\link{import.metabarcoding.data}}
if \code{obiclean} results are present in the file they are stored in the
\code{motu} data.frame. By calling this methods, MOTU descriptors describing
the \code{obiclean} status are moved to a set of layers.
}
\examples{
# load termite data set from the ROBITools sample data
data(termes)
# shows the initial list of layer names
layer.names(t)
# extracts the obiclean status
termes = extracts.obiclean(termes)
# shows the name of the newly created layers
layer.names(t)
}
\seealso{
\code{\linkS4class{metabarcoding.data}}, \code{\link{threshold.mask}}, \code{\link{normalize}}
}
\author{
Eric Coissac
}
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/distrib.extrapol.R
\name{extrapol.freq}
\alias{extrapol.freq}
\title{Read frequencies krigging}
\usage{
extrapol.freq(x, min.coord, max.coord, grid.grain = 100, coords, otus.table,
cutoff = 0.001, return.metabarcoding.data = FALSE)
}
\arguments{
\item{x}{a vector or matrix from a row-normalized read table
\code{\link{metabarcoding.data}} object}
\item{min.coord}{a vector of length = 2 indicating the minimum values of x and y
coordinates to be used for the predicted grid}
\item{max.coord}{a vector of length = 2 indicating the maximum values of x and y
coordinates to be used for the predicted grid}
\item{grid.grain}{an integer indicating the resolution (i.e. nb of subpoints) in x and y
coordinates required for the predicted grid}
\item{coords}{a dataframe containing the x and y coordinates of the abundances
from x to be extrapolated.}
\item{otus.table}{a motus data.frame containing motus informations of x}
\item{cutoff}{a cutoff below which abundances are set to 0.
This threshold also determines the value to be added to 0 values for log10
transformation}
\item{return.metabarcoding.data}{if \code{TRUE}, returns a \code{\link{metabarcoding.data}} object. Default is \code{FALSE}}
}
\value{
either a dataframe or a S3 object with a structure similar to \code{\link{metabarcoding.data}} object.
The number of samples corresponds to the predicted points.
The two last columns (if \code{return.metabarcoding.data==F}) or sample data.frame contains x y coordinates of the predicted grid
The all but last two columns (if \code{return.metabarcoding.data==F}) or read matrix contains the predicted log10 transformed relative abundances
instead of reads counts
If \code{return.metabarcoding.data==F} the motus data.frame contains the motus informations from x
}
\description{
Extrapolates read frequencies from a \code{\link{metabarcoding.data}} object in space for a finer resolution
}
\examples{
data(termes)
#Create dummy spatial coordinates
attr(termes, "samples")[c("x", "y")] = expand.grid(1:7,1:3)
#compute frequencies
attr(termes, "layers")[["reads.freq"]] = normalize(termes, MARGIN=1)$reads
# Getting extrapolations
termes.pred = extrapol.freq(attr(termes, "layers")[["reads.freq"]], min.coord=c(1,1), max.coord=c(7,3),
grid.grain=100,termes$samples[,c("x", "y")], termes$motus, cutoff=1e-3)
head(termes.pred$reads)
}
\seealso{
\code{\link{map.extrapol.freq}} as well as \code{sp} and \code{gstat} packages
}
\author{
Lucie Zinger
}
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/taxonomy_classic_table.R
\name{get.classic.taxonomy}
\alias{get.classic.taxonomy}
\title{Get classical taxonomy format}
\usage{
get.classic.taxonomy(x, taxonomy, coltaxid)
}
\arguments{
\item{x}{a \code{\link{metabarcoding.data}} object}
\item{taxonomy}{a instance of \code{\linkS4class{taxonomy.obitools}}}
\item{coltaxid}{a the name of the column containing taxids to be used for creating classical taxonomic description}
}
\value{
returns a data.frame with the classical taxonomic description ("kingdom", "phylum", "class", "order", "family", "genus", "species"), as well as
sequence taxonomic assignment rank and scientific name for each sequences stored in the \code{\link{metabarcoding.data}} object
}
\description{
Creates a table with the classical taxonomic description (from phylum to species)
}
\examples{
data(termes)
taxo=default.taxonomy()
termes.taxo.table = get.classic.taxonomy(termes, taxo, "taxid")
head(termes.taxo.table)
attr(termes, "motus") = data.frame(termes$motus, termes.taxo.table)
}
\seealso{
\code{\linkS4class{taxonomy.obitools}}, and methods \code{\link{species}},\code{\link{genus}}, \code{\link{family}},\code{\link{kingdom}},
\code{\link{superkingdom}},\code{\link{taxonatrank}}, \code{\link{taxonmicank}}
}
\author{
Lucie Zinger
}
\keyword{taxonomy}
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/import.metabarcoding.R
\name{import.metabarcoding.data}
\alias{import.metabarcoding.data}
\title{Read a data file produced by the \code{obitab} command}
\usage{
import.metabarcoding.data(file, sep = "\\t", sample = "sample",
sample.sep = "\\\\.", attribute = ":")
}
\arguments{
\item{file}{a string containing the file name of the obitab file.}
\item{sep}{Column separator in the obitab file.
The default separator is the tabulation.}
\item{sample}{A regular expression allowing to identify columns
from the file describing abundances of sequences per sample}
\item{sample.sep}{Separator between combined sample name.}
\item{attribute}{Separator used to split between sample 'tag' and sample name.}
}
\value{
a \code{\link{metabarcoding.data}} instance
}
\description{
Read a data file issued from the conversion of a \strong{fasta}
file to a tabular file by the \code{obitab} command of the
\strong{OBITools} package
}
\examples{
require(ROBITools)
\dontshow{# switch the working directory to the data package directory}
\dontshow{setwd(system.file("extdata", package="ROBITools"))}
# read the termes.tab file
termes=import.metabarcoding.data('termes.tab')
# print the number of samples and motus described in the file
dim(termes)
}
\seealso{
\code{\link{metabarcoding.data}}
}
\author{
Eric Coissac
}
\keyword{DNA}
\keyword{metabarcoding}
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/import.ngsfilter.R
\name{import.ngsfilter.data}
\alias{import.ngsfilter.data}
\title{Read ngsfilter text file}
\usage{
import.ngsfilter.data(file, platewell = NULL)
}
\arguments{
\item{file}{a string containing the file name for the \code{ngsfilter} command.}
\item{platewell}{a string corresponding to the tag used for storing the sample location
in the PCR plate. Should be of the form "nbPlate_Well" (e.g. "01_A02").
Default is \code{NULL}}
}
\value{
\code{\link{import.ngsfilter.data}} returns a \code{\link{data.frame}} instance
}
\description{
Reads the text file used for assigning reads to samples with the
\code{ngsfilter} command of the \strong{OBITools} package.
}
\examples{
\dontshow{# switch the working directory to the data package directory}
\dontshow{setwd(system.file("extdata", package="ROBITools"))}
data(termes)
# reading the termes_ngsfilt.txt file
termes.ngs=import.ngsfilter.data('termes_ngsfilt.txt', platewell="position")
# including ngsfilter data into termes data
attr(termes, "samples") = termes.ngs[rownames(termes),]
colnames(termes$samples)
}
\seealso{
\code{\link{import.metabarcoding.data}} and \code{\link{read.obitab}} for other methods of data importation
}
\author{
Lucie Zinger
}
\keyword{DNA}
\keyword{metabarcoding}
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/02_class_metabarcoding.data.R
\docType{methods}
\name{initialize,metabarcoding.data-method}
\alias{initialize,metabarcoding.data-method}
\alias{initialize-methods,metabarcoding.data}
\title{metabarcoding.data constructor}
\usage{
\S4method{initialize}{metabarcoding.data}(.Object, reads, samples, motus,
taxonomy = NULL, taxid = NULL, sample.margin = NA, layers = list())
}
\description{
metabarcoding.data constructor
}
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/layers.metabarcoding.R
\docType{methods}
\name{layer.names,metabarcoding.data-method}
\alias{layer.names,metabarcoding.data-method}
\alias{layer.names-methods,metabarcoding.data}
\title{Returns the names of all the layers}
\usage{
\S4method{layer.names}{metabarcoding.data}(obj)
}
\arguments{
\item{obj}{a \code{\link{metabarcoding.data}} instance}