caret downSample() in R: Balance Classes by Undersampling
The downSample() function in caret balances a classification dataset by randomly dropping rows from the majority classes until every class matches the smallest class count. It returns one combined data frame containing the predictors plus a renamed outcome column, and it handles binary or multiclass factor targets without extra arguments.
downSample(x = predictors, y = labels) # default, balances all classes downSample(x, y, yname = "Outcome") # rename the outcome column downSample(x, y, list = TRUE) # list with $x and $y separately downSample(train[, -1], train$Class) # typical training-only call downSample(iris[, 1:4], iris$Species) # no-op when already balanced table(downSample(x, y)$Class) # confirm equal class counts set.seed(1); downSample(x, y) # reproducible draws nrow(downSample(x, y)) # minority count times n classes
Need explanation? Read on for examples and pitfalls.
What downSample() does in one sentence
downSample() is caret's random undersampler for classification. You pass a predictor matrix and a factor outcome, and it removes rows at random from every non-minority class until each class count equals the smallest one, returning a single data frame with the predictors plus a Class column.
The function targets the same problem as oversampling, from the opposite direction. When 99% of training rows belong to one class, a model can score 99% accuracy by always predicting that class while catching zero minority cases. Undersampling trims the majority to the minority size so the loss function sees equal examples from each class. It is the natural first move when the majority is large enough that throwing rows away does not collapse the signal.
downSample() syntax and arguments
downSample() takes predictors and outcomes separately, not a formula. Four arguments cover everything the function exposes.
The signature is compact:
x: predictor data frame or matrix. Do not include the outcome column here.y: factor outcome vector. The class with the smallest count sets the target size for every other class.list: ifFALSE(the default), return a single data frame. Set toTRUEfor a named list with$xand$yseparately.yname: name for the outcome column whenlist = FALSE. Defaults to"Class".
The returned object has n_classes * minority_count rows, so an 800/40 binary problem collapses to 80 rows. For multiclass, every non-minority class is sampled down to the minority size, so a 500/200/50 split shrinks to 150 rows. Dropped rows are gone for that training run.
RandomUnderSampler().fit_resample(X, y) from imblearn.under_sampling. Both drop majority rows at random until classes balance; downSample() returns one combined data frame, imblearn returns X and y as separate arrays.downSample() examples by use case
Most undersampling workflows split first, then downsample only the training partition. The examples below build from a single call up to a pipeline with caret::train() and a held-out test set.
A single binary undersampling call on the toy data:
The majority fell from 800 rows to 40, matching the minority. The 760 dropped rows are removed from this frame, and the predictor space loses most of its majority-side coverage. That information loss is the cost of undersampling and the reason it pairs well with bagging.
The same call with list = TRUE keeps predictors and labels separate:
Use list = TRUE when downstream code expects X and y as separate arguments, for example glmnet() or xgboost::xgb.DMatrix().
A train/test split before undersampling, then balanced training:
The training set is balanced 28/28 while the test set keeps the natural imbalance. Evaluating on the imbalanced test set keeps metrics honest; balancing it hides the true deployment distribution.
Multiclass undersampling works the same way:
Every non-minority class is sampled down to the minority size. A 3-class problem with counts 300/150/50 collapses to 150 rows, an 80% reduction.
train() do it for you when tuning. Pass trainControl(sampling = "down") to caret's train() and the undersampling runs inside each resample, not on the full training set. This gives an honest performance estimate because the downsampling is recomputed per fold, and the discarded majority rows differ across folds, recovering some of the information that a one-shot downsample throws away.downSample() vs upSample() and other balancing tools
downSample() drops majority rows; upSample() duplicates minority rows; SMOTE creates synthetic minority points. Pick by dataset size, model variance, and how much majority signal you can afford to lose.
| Method | Sample size | Risk | Best for |
|---|---|---|---|
downSample(x, y) |
n_classes * minority_count |
throws away majority information | very large datasets, fast training, bagging |
upSample(x, y) |
n_classes * majority_count |
overfits to repeated minority rows | small datasets where dropping majority hurts |
themis::step_smote() |
synthetic interpolations | distorts feature manifold | continuous features, large enough minority to interpolate |
trainControl(sampling = "down") |
resamples inside CV | none above resample noise | hyperparameter tuning with caret |
weights in train() |
unchanged | weights only, no resampling | log-loss or weighted likelihood models |
Downsampling shines when the majority is large enough that the random sample still represents it well. With 100,000 majority and 1,000 minority rows, downsampling produces a 2,000-row frame that fits a model in seconds. Upsampling the same data inflates the frame to 200,000 rows and slows every fold, often without a measurable accuracy gain.
The natural partner for downsampling is bagging on multiple balanced subsets. Build several downsampled sets with different seeds and aggregate the predictions. Each model sees a different slice of the majority, and the ensemble recovers most of the information one downsample throws away. Random forest via caret::train(method = "rf") with trainControl(sampling = "down") is the simplest form of this pattern.
Common pitfalls
Three mistakes cause most undersampling bugs.
The first is undersampling before the train/test split. If you call downSample() on the full data and then split, the test set inherits the artificially balanced prior and the test metric stops describing real-world performance. Always split first, then downsample only the training partition.
The second is reporting accuracy on the balanced training data. Once downSample() runs, accuracy on the balanced sample is meaningless because the prior distribution has been rewritten. Score on the natural-prevalence test partition and report precision, recall, F1, and AUPRC instead.
The third is forgetting to set a seed. downSample() draws random row indexes, so two calls produce different training frames. Seed once before each call and the same balanced frame is rebuilt every run.
Try it yourself
Try it: Take the built-in iris dataset, duplicate the versicolor and virginica rows to create imbalance, then use downSample() to rebalance and confirm all three species drop back to 50 rows.
Click to reveal solution
Explanation: setosa is the minority with 50 rows so it sets the target size. versicolor and virginica get sampled down from 100 to 50 each, leaving a balanced 150-row frame.
Related caret functions
downSample() is one piece of caret's class-balancing toolkit.
upSample(x, y): random oversampling of the minority class to match the majority size.createDataPartition(y, p = 0.7): stratified train/test split, runs before any sampling.trainControl(sampling = "down"): runsdownSample()inside each resample duringtrain().train(method, weights = w): class-weighted fitting without resampling.confusionMatrix(predicted, actual): scores a classifier on the natural-prevalence test set.
See the caret documentation on subsampling for class imbalance for the authoritative reference.
FAQ
Why does downSample() rename my outcome column to Class?
The default yname = "Class" makes the returned frame work with caret's formula interface, where train(Class ~ ., data = balanced) finds the outcome by name. Pass yname = "Species" to keep the original name. The renaming is purely cosmetic; the factor values are identical to the input.
Should I downsample the validation set too?
No. Downsample only the training partition. The validation and test sets must reflect the real-world class prior so metrics generalise to production. Scoring on a balanced validation set inflates accuracy and obscures the precision-recall trade-off at deployment.
How does downSample() compare with upSample()?
downSample() drops majority rows so the training frame shrinks to n_classes * minority_count. upSample() duplicates minority rows so the frame grows to n_classes * majority_count. Choose downsampling when the majority is large and training time matters, and oversampling when the dataset is small and throwing rows away hurts more than duplicating them.
Can I combine downSample() with cross-validation?
Yes, by passing trainControl(sampling = "down") to train(). caret then downsamples inside each CV fold so the resample estimates are honest. Calling downSample() once before train() reuses the same shrunken set across every fold, which biases the cross-validation error.
Does downSample() work with regression targets?
No. downSample() requires a factor outcome and balances by class count. For numeric targets, stratify on a binned target with createDataPartition(), transform the response with log1p(), or fit a quantile loss.