Commit 60e57c53 authored by Konrad Zych's avatar Konrad Zych

docs

parent 3eccdf17
Pipeline #4137 passed with stage
in 24 seconds
......@@ -112,7 +112,7 @@ get.features <- function(siamcat){
return(siamcat@phyloseq@otu_table)
}
#' Access phyloseq object in siamcat@phylose
#' Access phyloseq object in siamcat@phyloseq
#' @title get.phyloseq
#' @name get.phyloseq
#' @description Function to access phyloseq object in siamcat@phylose
......@@ -123,7 +123,7 @@ get.features <- function(siamcat){
#' data(siamcat_example)
#' phyloseq <- get.phyloseq(siamcat)
get.phyloseq <- function(siamcat){
return(siamcat@phyloseq@otu_table)
return(siamcat@phyloseq)
}
#' Access features in siamcat@phylose@otu_table
......
This diff is collapsed.
This source diff could not be displayed because it is too large. You can view the blob instead.
......@@ -85,7 +85,7 @@
</header>
<div class="page-header">
<h1>Articles <small>version&nbsp;0.4.0</small></h1>
<h1>Articles <small>version&nbsp;0.99.0</small></h1>
</div>
<div class="row">
......
No preview for this file type
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/add_meta_pred.r
\name{add.meta.pred}
\alias{add.meta.pred}
\title{Add metadata as predictors}
\usage{
add.meta.pred(siamcat, pred.names = NULL, std.meta = TRUE, verbose = 1)
}
\arguments{
\item{siamcat}{object of class \link{siamcat-class}}
\item{pred.names}{vector of names of the variables within the metadata to be
added to the feature matrix as predictors}
\item{std.meta}{boolean, should added metadata features be standardized?,
defaults to \code{TRUE}}
\item{verbose}{control output: \code{0} for no output at all, \code{1}
for only information about progress and success, \code{2} for normal
level of information and \code{3} for full debug information,
defaults to \code{1}}
}
\value{
an object of class \link{siamcat-class} with metadata added to the
features
}
\description{
This function adds metadata to the feature matrix to be
later used as predictors
}
\examples{
data(siamcat_example)
# Add the Age of the patients as potential predictor
siamcat_age_added <- add.meta.pred(siamcat_example, pred.names=c('age'))
# Add Age, BMI, and Gender as potential predictors
# Additionally, prevent standardization of the added features
siamcat_meta_added <- add.meta.pred(siamcat_example, pred.names=c('age',
'bmi', 'gender'), std.meta=FALSE)
}
\keyword{SIAMCAT}
\keyword{add.meta.pred}
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/create_data_split.r
\name{assign.fold}
\alias{assign.fold}
\title{Assign folds}
\usage{
assign.fold(label, num.folds, stratified, inseparable = NULL, meta = NULL,
verbose = 1)
}
\value{
vector with fold assignments
}
\description{
Create data split from label
}
\keyword{internal}
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/check_associations.r
\name{check.associations}
\alias{check.associations}
\title{Check and visualize associations between features and classes}
\usage{
check.associations(siamcat, fn.plot, color.scheme = "RdYlBu", alpha = 0.05,
mult.corr = "fdr", sort.by = "fc", detect.lim = 1e-06,
pr.cutoff = 10^-6, max.show = 50, plot.type = "quantile.box",
panels = c("fc", "auroc"), verbose = 1)
}
\arguments{
\item{siamcat}{object of class \link{siamcat-class}}
\item{fn.plot}{filename for the pdf-plot}
\item{color.scheme}{valid R color scheme or vector of valid R colors (must
be of the same length as the number of classes), defaults to \code{'RdYlBu'}}
\item{alpha}{float, significance level, defaults to \code{0.05}}
\item{mult.corr}{multiple hypothesis correction method, see \code{\link[stats]{p.adjust}},
defaults to \code{"fdr"}}
\item{sort.by}{string, sort features by p-value (\code{"p.val"}), by fold change
(\code{"fc"}) or by prevalence shift (\code{"pr.shift"}), defaults to
\code{"fc"}}
\item{detect.lim}{float, pseudocount to be added before log-transformation of
the data, defaults to \code{1e-06}}
\item{pr.cutoff}{float, cutoff for the prevalence computation, defaults to
\code{1e-06}}
\item{max.show}{integer, how many associated features should be shown,
defaults to \code{50}}
\item{plot.type}{string, specify how the abundance should be plotted, must be
one of these: \code{c("bean", "box", "quantile.box", "quantile.rect")},
defaults to \code{"quantile.box"}}
\item{panels}{vector, name of the panels to be plotted next to the log10-
transformed abundances, possible entries are \code{c("fc", "auroc",
"prevalence")}, defaults to \code{c("fc", "auroc")}}
\item{verbose}{control output: \code{0} for no output at all, \code{1}
for only information about progress and success, \code{2} for normal
level of information and \code{3} for full debug information, defaults to \code{1}}
}
\value{
Does not return anything, but produces an association plot
}
\description{
This function calculates for each feature a pseudo-fold change
(geometrical mean of the difference between quantiles) between the different
classes found in labels.
Significance of the differences is computed for each feature using a Wilcoxon
test followed by multiple hypothesis testing correction.
Additionally, the Area Under the Receiver Operating Characteristic Curve
(AU-ROC) and a prevalence shift are computed for the features found to be
associated with the two different classes at a user-specified
significance level \code{alpha}.
Finally, the function produces a plot of the top \code{max.show} associated
features, showing the distribution of the log10-transformed abundances for
both classes, and user-selected panels for the effect (AU-ROC, Prevalence
Shift, and Fold Change)
}
\examples{
# Example data
data(siamcat_example)
# since the whole pipeline has been run in the example data, exchange the
# normalized features with the original features
siamcat_example <- reset.features(siamcat_example)
# Simple example
check.associations(siamcat_example, './assoc_plot.pdf')
# Plot associations as bean plot
check.associations(siamcat_example, './assoc_plot_bean.pdf', plot.type='bean')
# Plot assocations as box plot
# Additionally, sort by p-value instead of by fold change
check.associations(siamcat_example, './assoc_plot_fc.pdf', plot.type='box', sort.by='p.val')
# Custom colors
check.associations(siamcat_example, './assoc_plot_blue_yellow.pdf', plot.type='box',
color.scheme=c('cornflowerblue', '#ffc125'))
}
\keyword{SIAMCAT}
\keyword{check.associations}
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/check_confounders.r
\name{check.confounders}
\alias{check.confounders}
\title{Check for potential confounders in the metadata}
\usage{
check.confounders(siamcat, fn.plot, verbose = 1)
}
\arguments{
\item{siamcat}{an object of class \link{siamcat-class}}
\item{fn.plot}{string, filename for the pdf-plot}
\item{verbose}{control output: \code{0} for no output at all, \code{1}
for only information about progress and success, \code{2} for normal
level of information and \code{3} for full debug information,
defaults to \code{1}}
}
\value{
Does not return anything, but produces a single plot for each
metadata category.
}
\description{
This function checks for associations between class labels and
potential confounders (e.g. age, sex, or BMI) that are present in the
metadata. Statistical testing is performed with Fisher's exact test
or Wilcoxon test, while associations are visualized either as barplot
or Q-Q plot, depending on the type of metadata.
}
\examples{
# Example data
data(siamcat_example)
# since the whole pipeline has been run in the example data, exchange the
# normalized features with the original features
siamcat_example <- reset.features(siamcat_example)
# Simple working example
check.confounders(siamcat_example, './conf_plot.pdf')
# Additional information with verbose
\dontrun{check.confounders(siamcat_example, './conf_plot.pdf', verbose=2)}
}
\keyword{SIAMCAT}
\keyword{check.confounders}
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/create_data_split.r
\name{create.data.split}
\alias{create.data.split}
\title{Split a dataset into training and a test sets.}
\usage{
create.data.split(siamcat, num.folds = 2, num.resample = 1,
stratify = TRUE, inseparable = NULL, verbose = 1)
}
\arguments{
\item{siamcat}{object of class \link{siamcat-class}}
\item{num.folds}{number of cross-validation folds (needs to be \code{>=2}),
defaults to \code{2}}
\item{num.resample}{resampling rounds (values \code{<= 1} deactivate
resampling), defaults to \code{1}}
\item{stratify}{boolean, should the splits be stratified so that an equal
proportion of classes are present in each fold?, defaults to \code{TRUE}}
\item{inseparable}{column name of metadata variable, defaults to \code{NULL}}
\item{verbose}{control output: \code{0} for no output at all, \code{1}
for only information about progress and success, \code{2} for normal
level of information and \code{3} for full debug information, defaults to \code{1}}
}
\value{
object of class \link{siamcat-class} with the \code{data_split}-slot filled
}
\description{
This function prepares the cross-validation by splitting the
data into \code{num.folds} training and test folds for
\code{num.resample} times.
}
\details{
This function splits the labels within a \link{siamcat-class} object and
prepares the internal cross-validation for the model training (see
\link{train.model}).
The function saves the training and test instances for the different
cross-validation folds within a list in the \code{data_split}-slot
of the \link{siamcat-class} object, which is a list with four entries: \itemize{
\item \code{num.folds} the number of cross-validation folds
\item \code{num.resample} the number of repetitions for the cross-validation
\item \code{training.folds} a list containing the indices for the training instances
\item \code{test.folds} a list containing the indices for the test instances
}
}
\examples{
data(siamcat_example)
# simple working example
siamcat_split <- create.data.split(siamcat_example, num.folds=10, num.resample=5, stratify=TRUE)
## # example with a variable which is to be inseparable
## siamcat_split <- create.data.split(siamcat_example, num.folds=10, num.resample=5, stratify=FALSE, inseparable='Gender')
}
\keyword{SIAMCAT}
\keyword{create.data.split}
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/siamcat_class.R
\docType{class}
\name{data_split-class}
\alias{data_split-class}
\title{The S4 class for storing data splits}
\description{
The S4 class for storing data splits
}
\section{Slots}{
\describe{
\item{\code{training.folds}}{a list - for each cv fold contains ids of
samples used for training}
\item{\code{test.folds}}{a list - for each cv fold contains ids of
samples used for testing}
\item{\code{num.resample}}{number of repetition rounds for cv}
\item{\code{num.folds}}{number of folds for cv}
}}
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/evaluate_predictions.r
\name{evaluate.predictions}
\alias{evaluate.predictions}
\title{Evaluate prediction results}
\usage{
evaluate.predictions(siamcat, verbose = 1)
}
\arguments{
\item{siamcat}{object of class \link{siamcat-class}}
\item{verbose}{control output: \code{0} for no output at all, \code{1}
for only information about progress and success, \code{2} for normal
level of information and \code{3} for full debug information, defaults to \code{1}}
}
\value{
object of class \link{siamcat-class} with the slot \code{eval_data} filled
}
\description{
This function takes the correct labels and predictions for all
samples and evaluates the results using the \itemize{
\item Area Under the Receiver Operating Characteristic (ROC) Curve (AU-ROC)
\item and the Precision-Recall Curve (PR)
}
as metric. Predictions can be supplied either for a single case or as
matrix after resampling of the dataset.
Prediction results are usually produced with the function \link{make.predictions}.
}
\details{
This functions calculates for the predictions in the \code{pred_matrix}
-slot of the \link{siamcat-class}-object several metrices. The Area Under the
Receiver Operating Characteristic (ROC) Curve (AU-ROC) and the Precision-
Recall Curve will be evaluated and the results will be saved in the
\code{eval_data}-slot of the supplied \link{siamcat-class}-object. The
\code{eval_data}-slot contains a list with several entries: \itemize{
\item \code{$roc.average} average ROC-curve across repeats or a
single ROC-curve on complete dataset;
\item \code{$auc.average} AUC value for the average ROC-curve;
\item \code{$ev.list} list of \code{length(num.folds)}, containing
for different decision thresholds the number of false positives,
false negatives, true negatives, and true positives;
\item \code{$pr.list} list of \code{length(num.folds)}, containing
the positive predictive value (precision) and true positive
rate (recall) values used to plot the PR curves.
} For the case of repeated cross-validation, the function will additonally return \itemize{
\item \code{$roc.all} list of roc objects (see \link[pROC]{roc}) for every repeat;
\item \code{$aucspr} vector of AUC values for the PR curves for every repeat;
\item \code{$auc.all} vector of AUC values for the ROC curves for every repeat.
}
}
\examples{
data(siamcat_example)
# simple working example
siamcat_evaluated <- evaluate.predictions(siamcat_example)
}
\keyword{SIAMCAT}
\keyword{evaluate.predictions}
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/filter.features.r
\name{filter.features}
\alias{filter.features}
\title{Perform unsupervised feature filtering.}
\usage{
filter.features(siamcat, filter.method = "abundance", cutoff = 0.001,
recomp.prop = FALSE, rm.unmapped = TRUE, verbose = 1)
}
\arguments{
\item{siamcat}{an object of class \link{siamcat-class}}
\item{filter.method}{method used for filtering the features, can be one of
these: \code{c("abundance", "cum.abundance", "prevalence")},
defaults to \code{"abundance"}}
\item{cutoff}{float, abundace or prevalence cutoff, default to \code{0.001}}
\item{recomp.prop}{boolean, should relative abundances be recomputed?,
defaults to \code{FALSE}}
\item{rm.unmapped}{boolean, should unmapped reads be discarded?, defaults to
\code{TRUE}}
\item{verbose}{control output: \code{0} for no output at all, \code{1}
for only information about progress and success, \code{2} for normal
level of information and \code{3} for full debug information, defaults to \code{1}}
}
\value{
siamcat an object of class \link{siamcat-class}
}
\description{
This function performs unsupervised feature filtering. Features
can be filtered based on abundance or prevalence. Additionally,
unmapped reads may be removed.
}
\details{
This function filters the features in a \link{siamcat-class} object in a
unsupervised manner.
The different filter methods work in the following way: \itemize{
\item \code{"abundace"} remove features whose abundance is never above
the threshold value in any of the samples
\item \code{"cum.abundance"} remove features with very low abundance
in all samples i.e. ones that are never among the most abundant
entities that collectively make up (1-cutoff) of the reads in any sample
\item \code{"prevalence"} remove features with low prevalence across samples
i.e. ones that are 0 (undetected) in more than (1-cutoff) proportion
of samples.
}
}
\examples{
# Example dataset
data(siamcat_example)
# since the whole pipeline has been run in the example data, the feature were
# filtered already.
siamcat_example <- reset.features(siamcat_example)
# Simple examples
siamcat_filtered <- filter.features(siamcat_example, filter.method='abundance', cutoff=1e-03)
}
\keyword{SIAMCAT}
\keyword{filter.features}
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/siamcat_class_methods.R
\name{filter.label}
\alias{filter.label}
\title{Filter samples from \code{siamcat@label}}
\usage{
filter.label(siamcat, ids, verbose = 1)
}
\arguments{
\item{siamcat}{an object of class \link{siamcat-class}}
\item{ids}{names of samples to be left in the \code{siamcat@label}}
\item{verbose}{control output: \code{0} for no output at all, \code{1} for more
information about progress and success, defaults to \code{1}}
}
\value{
siamcat an object of class \link{siamcat-class}
}
\description{
This functions filters \code{siamcat@label}.
}
\examples{
data(siamcat_example)
# simple working example
siamcat_filtered <- filter.label(siamcat_example, ids=c(1:10))
}
\keyword{filter.label}
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/siamcat_class_methods.R
\name{get.component.classes}
\alias{get.component.classes}
\title{Show the component objects classes and slot names.}
\usage{
get.component.classes(class)
}
\value{
list of component classes
}
\description{
Show the component objects classes and slot names.
}
\keyword{internal}
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/siamcat_class_methods.R
\name{get.eval_data}
\alias{get.eval_data}
\title{get.eval_data}
\usage{
get.eval_data(siamcat)
}
\arguments{
\item{siamcat}{an object of class \link{siamcat-class}t}
}
\value{
Evaluation data
}
\description{
Function to access evaluation data in siamcat@eval_data
}
\details{
Access evaluation data in siamcat@eval_data
}
\examples{
data(siamcat_example)
eval_data <- get.eval_data(siamcat)
}
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/siamcat_class_methods.R
\name{get.features}
\alias{get.features}
\title{get.features}
\usage{
get.features(siamcat)
}
\arguments{
\item{siamcat}{an object of class \link{siamcat-class}}
}
\value{
Features as \link[phyloseq]{otu_table} object
}
\description{
Function to access features in siamcat@phylose@otu_table
}
\details{
Access features in siamcat@phylose@otu_table
}
\examples{
data(siamcat_example)
feat <- get.features(siamcat)
}
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/siamcat_class_methods.R
\name{get.features.matrix}
\alias{get.features.matrix}
\title{get.features.matrix}
\usage{
get.features.matrix(siamcat)
}
\arguments{
\item{siamcat}{an object of class \link{siamcat-class}t}
}
\value{
Features as a matrix
}
\description{
Function to access features in siamcat@phylose@otu_table
}
\details{
Access features in siamcat@phylose@otu_table
}
\examples{
data(siamcat_example)
feat <- get.features.matrix(siamcat)
}
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/siamcat_class_methods.R
\name{get.label}
\alias{get.label}
\alias{get.label}
\alias{get.label.list}
\alias{get.label}
\alias{get.label.info}
\title{get.label}
\usage{
get.label(siamcat)
get.label.list(siamcat)
get.label.info(siamcat)
}
\arguments{
\item{siamcat}{an object of class \link{siamcat-class}}
\item{siamcat}{an object of class \link{siamcat-class}}
\item{siamcat}{an object of class \link{siamcat-class}}
}
\value{
an object of class \link{label-class}
Label object converted to a list
List of label informations
}
\description{
Function to access labels in siamcat@label
Function to access labels in siamcat@label
Function to access label info in siamcat@label@info
}
\details{
Access label object in siamcat@label
Access labels in siamcat@label
Access label info in siamcat@label@info
}
\examples{
data(siamcat_example)
label <- get.label(siamcat)
data(siamcat_example)
label <- get.label.list(siamcat)
data(siamcat_example)
label_info <- get.label.info(siamcat)
}
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/siamcat_class_methods.R
\name{get.label.label}
\alias{get.label.label}
\title{get.label.label}
\usage{
get.label.label(siamcat)
}
\arguments{
\item{siamcat}{an object of class \link{siamcat-class}}
}
\value{
Labels as a vector
}
\description{
Function to access labels in siamcat@label@label
}
\details{
Access labels in siamcat@label@label
}
\examples{
data(siamcat_example)
label <- get.label.label(siamcat)
}
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/siamcat_class_methods.R