-
Notifications
You must be signed in to change notification settings - Fork 20
/
citrus.full.R
181 lines (171 loc) · 9.98 KB
/
citrus.full.R
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
#' Perform a full Citrus analysis
#'
#' This function takes FCS data, identifies cell subsets using clustering,
#' characterizes the behavior of each identified cluster on a per-sample basis,
#' and identifies cluster properties associated with an endpoint.
#'
#' @param fileList A data frame containing the names of FCS files to be analyzed. Each column should contain FCS files measured in the same condition. Each row should contain FCS files measured from the same individual under different conditions. See examples below.
#' @param labels A vector containing the experimental endpoint values for each row of FCS files in the fileList.
#' @param clusteringColumns A vector containing the names or indices of parameters to be used for clustering.
#' @param dataDirectory The full path to the directory containing FCS files.
#' @param outputDirectory The full path to directory analysis output should be placed in. If not \code{NULL}, clustering is saved.
#' @param family Type of association model to be calculated. Valid values are currently \code{classification} and \code{continuous}.
#' @param modelTypes Vector of model types to be used to detect associations with experimental endpoint. Valid values are \code{glmnet}, \code{pamr}, and \code{sam}.
#' @param nFolds Number of independent clustering folds to be used for model fitting. Should only be >1 if using \code{glmnet} or \code{pamr} models. Default value is 1 and all samples are clustered together.
#' @param conditionComparaMatrix matrix of condition data to compare. See details.
#' @param ... Other arguments to be passed to \code{citrus.readFCSSet}, \code{citrus.calculateFeatures}, \code{citrus.endpointRegress}.
#' Useful additional arguments listed in details.
#'
#' @details Citrus is able to analyze FCS data from single conditions or relative to a given baseline
#' (i.e. stimulated values relative to an unstimulated baseline). Tell Citrus to compare conditions using
#' the conditionComparisonMatrix argument. The conditionComparisonMatrix is an \eqn{n x n} matrix of logical values
#' indicating which conditions should be compared where \eqn{n} is the number of experimental conditions specified in
#' the fileList. Rows and columns names of the conditionComparsion matrix should be the names of experimental conditions
#' in the fileList. A matrix entry of \code{TRUE} indicates that Citrus should calculate the value features in column name
#' relative to feature values in the row name. \code{TRUE} entries on the diagonal means conditions are analyzed by themselves.
#' See Examples.
#'
#' Other useful arguments to pass to citrus.full include:
#' \itemize{
#'
#' \item \code{fileSampleSize}: The number of cells to select from each sample. See \code{\link{citrus.readFCSSet}}.
#'
#' \item \code{transformColumns}: Vector of parameter names or indicies whose values should transformed. See \code{\link{citrus.readFCSSet}}.
#'
#' \item \code{transformCofactor}: Cofactor for arcsin-hyperbolic transform. See \code{\link{citrus.readFCSSet}}.
#'
#' \item \code{featureType}: The descriptive feature type to be calculated for each cluster. See \code{\link{citrus.calculateFeatures}}.
#'
#' \item \code{minimumClusterSizePercent}: The minimum cluster size as a percentage of total sampled cells. See \code{\link{citrus.calculateFeatures}}.
#' }
#'
#' @return A citrus.full.result object with the following properties:
#' \item{citrus.combinedFCSSet}{A \code{citrus.combinedFCSSet} object containing data read from files.}
#' \item{citrus.foldClustering}{A \code{citrus.foldClustering} object that contains clustering results.}
#' \item{conditionFoldFeatures}{A list of \code{citrus.foldFeatureSet} objects used for regression, one list element for each set of analyzed conditions.}
#' \item{conditionRegressionResults}{A list of \code{citrus.regressionResult} objects, one entry for each set of analyzed condition.}
#' \item{family}{The family of the regression model.}
#' \item{labels}{Endpoint labels of the analyzed samples.}
#' \item{conditions}{List of analyzed conditions.}
#' \item{modelTypes}{Vector of regression models used to test for endpoint associations.}
#'
#' @author Robert Bruggner
#' @export
#'
#' @seealso \code{citrus.readFCSSet}, \code{citrus.cluster},\code{citrus.calculateFeatures}, and \code{citrus.endpointRegress}
#'
#' @examples
#' # Example with a single experimental condition (unstimulated data)
#' # Where the data lives
#' dataDirectory = file.path(system.file(package = "citrus"),"extdata","example1")
#'
#' # Create list of files to be analyzed
#' fileList = data.frame("unstim"=list.files(dataDirectory,pattern=".fcs"))
#'
#' # List disease group of each sample
#' labels = factor(rep(c("Healthy","Diseased"),each=10))
#'
#' # List of columns to be used for clustering
#' clusteringColumns = c("Red","Blue")
#'
#' # Run citrusAnalysis
#' results = citrus.full(fileList,labels,clusteringColumns,dataDirectory)
#'
#' # Should be used to plot results
#' # plot(results, outputDirectory="/path/to/outputDirectory")
#'
#' ############################################
#'
#' # Example using multiple experimental conditions, including a
#' # comparison of stimulated to unstimulated damples
#'
#' # Where the data lives
#' dataDirectory = file.path(system.file(package = "citrus"),"extdata","example2")
#'
#' # Create list of files to be analyzed
#' fileList = data.frame(unstim=list.files(dataDirectory,pattern="unstim"),stim1=list.files(dataDirectory,pattern="stim1"))
#'
#' # Disease group of each sample
#' labels = factor(rep(c("Healthy","Diseased"),each=10))
#'
#' # Vector of parameters to be used for clustering
#' clusteringColumns = c("LineageMarker1","LineageMarker2")
#'
#' # Vector of parameters to calculate medians for
#' functionalColumns = c("FunctionalMarker1","FunctionalMarker2")
#'
#' # Form condition comparison matrix to tell Citrus which conditions to analyze compare
#' conditionComparaMatrix = matrix(T,nrow=2,ncol=2,dimnames=list(colnames(fileList),colnames(fileList)))
#' conditionComparaMatrix[2]=F
#'
#' # Run citrusAnalysis
#' results = citrus.full(fileList,labels,clusteringColumns,dataDirectory,
#' conditionComparaMatrix=conditionComparaMatrix,
#' featureType="medians",
#' medianColumns=functionalColumns)
#'
#' # Result should be plotted
#' # plot(results,outputDirectory="/path/to/outputDirectory")
citrus.full = function(fileList,
labels,
clusteringColumns,
dataDirectory,
outputDirectory=NULL,
family="classification",
modelTypes=c("glmnet"),
nFolds=1,
conditionComparaMatrix=NULL,
...){
# No point in running cv if SAM only model
if (all(modelTypes=="sam")){
nFolds=1
}
if (!is.null(conditionComparaMatrix)){
allConditions = citrus.convertConditionMatrix(conditionComparaMatrix)
} else {
allConditions = as.list(colnames(fileList))
}
names(allConditions) = sapply(allConditions,function(x){paste(rev(x),collapse="_vs_")})
# Read in data
citrus.combinedFCSSet = citrus.readFCSSet(dataDirectory=dataDirectory,fileList=fileList,...)
# Cluster each fold
citrus.foldClustering = citrus.clusterAndMapFolds(citrus.combinedFCSSet,clusteringColumns,labels=labels,nFolds=nFolds)
if (!is.null(outputDirectory)){
save(list=c("citrus.combinedFCSSet","citrus.foldClustering"),file=file.path(outputDirectory,"citrusClustering.rData"),compress=F)
}
conditionFeatures = list()
conditionRegressionResults = list()
# Analyze each condition or set of conditions separately
for (conditions in allConditions){
cat(paste0("Analyzing condition(s): ",paste0(conditions,collapse=" vs. "),"\n"))
#conditionFileIds = citrus.combinedFCSSet$fileIds[,conditions]
# Calculate fold features
#citrus.foldFeatureSet = citrus.calculateFoldFeatureSet(citrus.foldClustering=citrus.foldClustering,citrus.combinedFCSSet=citrus.combinedFCSSet,featureType=featureType,minimumClusterSizePercent=minimumClusterSizePercent,medianColumns=medianColumns,mc.cores=4)
#citrus.foldFeatureSet = citrus.calculateFoldFeatureSet(citrus.foldClustering=citrus.foldClustering,citrus.combinedFCSSet=citrus.combinedFCSSet,conditions=conditions,featureType="medians",medianColumns=medianColumns)
cat("\tBuilding Fold Features\n")
citrus.foldFeatureSet = citrus.calculateFoldFeatureSet(citrus.foldClustering=citrus.foldClustering,citrus.combinedFCSSet=citrus.combinedFCSSet,conditions=conditions,...)
conditionFeatures[[paste(rev(conditions),collapse="_vs_")]] = citrus.foldFeatureSet
# Endpoint regress for each model type
#citrus.regressionResults = mclapply(modelTypes,citrus.endpointRegress,citrus.foldFeatureSet=citrus.foldFeatureSet,labels=labels,family=family)
#citrus.regressionResults = citrus.endpointRegress("sam",citrus.foldFeatureSet=citrus.foldFeatureSet,labels=labels,family=family)
cat("\tAnalyzing vs. endpoint\n")
citrus.regressionResults = mclapply(modelTypes,citrus.endpointRegress,citrus.foldFeatureSet=citrus.foldFeatureSet,labels=labels,family=family,...)
names(citrus.regressionResults) = modelTypes
conditionRegressionResults[[paste(rev(conditions),collapse="_vs_")]] = citrus.regressionResults
cat("\n")
}
# Return Results
results = list(citrus.combinedFCSSet=citrus.combinedFCSSet,citrus.foldClustering=citrus.foldClustering,conditionFoldFeatures=conditionFeatures,conditionRegressionResults=conditionRegressionResults,family=family,labels=labels,conditions=allConditions,modelTypes=modelTypes)
class(results) = "citrus.full.result"
return(results)
}
#' @export
#' @name citrus.full
print.citrus.full.result = function(citrus.full.result,...){
cat("Citrus full result\n")
cat(paste("Family:",citrus.full.result$family,"\n"))
cat("Models: ")
cat(paste0(paste(unlist(citrus.full.result$modelTypes),collapse=", "),"\n"))
cat("Conditions: ")
cat(paste0(paste(unlist(citrus.full.result$conditions),collapse=", "),"\n"))
}