Removes (or keeps) a subset of samples from an object of class
DEprot or DEprot.analyses and fully re-derives every
processing step that had been applied to the original object. Because
normalization (MBQN / HarmonizR), bottom-distribution randomization and,
most importantly, imputation (e.g. missForest) depend on the whole
set of samples/sub-groups, dropping samples and simply sub-setting the
pre-computed matrices would produce values that are inconsistent with what
those algorithms would return on the reduced data. This function therefore
goes back to the lowest count level that can be faithfully re-derived
(raw > normalized > randomized > imputed),
rebuilds a fresh object with the retained samples and re-runs, in order, the
same steps as in the original object, recovering the parameters directly from
the original object's slots and re-using the existing DEprot functions
(normalize.counts, harmonize.batches,
randomize.missing.values, impute.counts and, for
DEprot.analyses, diff.analyses / diff.analyses.limma /
diff.analyses.prolfqua).
# S3 method for class 'samples'
filter(
DEprot.object,
samples,
mode = "remove",
batch.column = NULL,
diff.method = "auto",
stat.test = NULL,
replicate.column = NULL,
min.samples.per.group = 2,
verbose = TRUE
)An object of class DEprot or DEprot.analyses.
Character vector with the identifiers of the samples to remove
or to keep. Identifiers must correspond to values of the column.id
column of the object metadata (i.e. the column names of the counts tables).
String, one among "remove" and "keep". If
"remove" (default) the samples listed in samples are dropped;
if "keep" only the samples listed in samples are retained.
String indicating the metadata column that stores the
batch identifiers, used only when the original object was batch-corrected
with harmonize.batches. This is normally recovered from the object,
so this argument acts as an override; if it is not stored (legacy objects)
and this argument is NULL (default) the function looks for a column
literally called "batch". Default: NULL.
String defining which differential-analyses engine should
be used to recompute the contrasts of a DEprot.analyses object. One
among "auto", "t.test", "limma" and "prolfqua".
With "auto" (default) the engine is read directly from the object
(the stat.test entry of differential.analyses.params records
whether limma, prolfqua or the t/Wilcoxon engine was used);
for legacy objects that do not store it, prolfqua is still detected
and the function otherwise falls back to diff.analyses (t/Wilcoxon).
Set this argument explicitly only to override the stored engine. Default:
"auto".
String passed to diff.analyses (t/Wilcoxon engine
only), one among "t.test" and "wilcoxon". Normally recovered
from the object, so this argument acts as an override. If NULL
(default) the stored test is used, falling back to "t.test". Default:
NULL.
String indicating the metadata column with the
replicate identifiers. It is recovered from the object for every engine, so
this argument only acts as an override (e.g. if the stored column was
renamed). Default: NULL.
Numeric value indicating the minimum number of
retained samples that each group of a contrast must still contain for the
contrast to be recomputed (DEprot.analyses only). Contrasts in which
at least one group falls below this threshold are skipped with a warning.
Default: 2.
Logical value indicating whether progress messages should be
printed. Imputation can be slow, hence a message is printed before each
step. Default: TRUE.
An object of the same class as the input (DEprot or
DEprot.analyses) containing only the retained samples, with all the
count tables, boxplots and (when applicable) differential results
recomputed from scratch.
Parameter recovery. The parameters of each step are collected from the corresponding slot of the original object:
Normalization (normalization.method slot): a
data.frame whose "package" row is either "MBQN"
or "HarmonizR". For MBQN, balancing.function and
NRI.RI.ratio.threshold are recovered. For HarmonizR, the
batch.column, algorithm, ComBat.mode,
block and cores are recovered.
Randomization (randomization.method slot): all the
parameters (group.column, percentage.missing,
tail.percentage, which.data and seed) are
recovered.
Imputation (imputation.method slot): method,
seed, data.used (the counts that were imputed) and the
method-specific parameters are recovered – including, for
missForest, the parallel.mode and
variable.wise.OOBerror, and for SVD/BPCA/PPCA
the number of principal components tested.
Differential analyses (differential.analyses.params and
contrasts slots): the contrasts, fold-change thresholds,
p-value/FDR threshold, adjustment method and counts used are recovered.
The engine is identified from the stored stat.test
("limma", "prolfqua" or the t/Wilcoxon test name); the
replicate.column is recovered for every engine, together with
the t/Wilcoxon paired.test, the limma rep.model /
fitting.method, and the prolfqua strategy /
moderate.variance.
The seeds saved during the original randomization/imputation are re-used so the re-computation is as reproducible as possible on the reduced data.
HarmonizR fallback. When the original object was harmonized, the
re-harmonization is attempted with the same algorithm/ComBat.mode.
If, after removing samples, a batch becomes too small for ComBat (or ComBat
fails for any reason), the function automatically falls back to the
"limma" algorithm.
if (FALSE) { # \dontrun{
# Remove two samples from an imputed DEprot object
dpo.filtered <- filter.samples(DEprot.object = dpo.imputed,
samples = c("sample_3", "sample_7"),
mode = "remove")
# Keep only a subset of samples from a DEprot.analyses object
dpa.filtered <- filter.samples(DEprot.object = dpo.analyses,
samples = c("ctrl_1", "ctrl_2", "treat_1", "treat_2"),
mode = "keep",
replicate.column = "replicate")
# Object that had been batch-corrected: provide the batch column
dpo.filtered <- filter.samples(DEprot.object = dpo.harmonized,
samples = "outlier_batchB",
mode = "remove",
batch.column = "batch")
} # }