minibatchqueue
R2026bCreate mini-batches for deep learning
Description
Use a minibatchqueue object to create, preprocess, and manage
mini-batches of data for deep learning.
A minibatchqueue object iterates over a datastore or in-memory data arrays
to provide data in a suitable format for training or prediction. The object prepares a queue of
mini-batches that are preprocessed on demand. Use a minibatchqueue object to
automatically convert your data to dlarray or gpuArray,
convert data to a different precision, pad sequence data, encode categorical data, or apply a
custom function to preprocess your data. You can prepare your data in parallel in the
background.
You can manage your data in a custom training loop by using a
minibatchqueue object. You can shuffle the data at the start of each
training epoch using the shuffle function
and collect data from the queue for each training iteration using the next function. You
can check if any data is left in the queue using the hasdata function,
and reset the queue
when it is empty.
Creation
Syntax
Description
mbq = minibatchqueue(ds)minibatchqueue object from the input datastore
ds. The mini-batches in mbq have the same number
of variables as the results of read on the input datastore.
mbq = minibatchqueue(ds,numOutputs)minibatchqueue object from the input datastore
ds and sets the number of variables in each mini-batch. Use this
syntax when you use MiniBatchFcn to specify a mini-batch
preprocessing function that has a different number of outputs than the number of variables
of the input datastore ds.
mbq = minibatchqueue(X1,...,XN)minibatchqueue object from one or
more in-memory data arrays X1,...,XN (since R2026b). When you use this
syntax, you must also specify the batch dimensions using the
BatchDimension name-value argument.
mbq = minibatchqueue(___,Name=Value)minibatchqueue(ds,MiniBatchSize=64,PartialMiniBatch="discard") sets
the size of the returned mini-batches to 64 and discards any mini-batches with fewer than
64 observations.
Input Arguments
Name-Value Arguments
Properties
Object Functions
Examples
Use a minibatchqueue object to automatically prepare
mini-batches of images and classification labels for training using the trainnet
function or in a custom training loop.
Create a datastore. Calling read on auimds
produces a table with two variables: input, containing the image
data, and response, containing the corresponding classification
labels.
auimds = augmentedImageDatastore([100 100],digitDatastore); A = read(auimds); head(A,2)
ans =
input response
_______________ ________
{100×100 uint8} 0
{100×100 uint8} 0
Create a minibatchqueue object from auimds. Set
the MiniBatchSize property to 256.
The minibatchqueue object has two output variables: the images and
classification labels from the input and response
variables of auimds, respectively. Set the
minibatchqueue object to return the images as a formatted
dlarray on the GPU. The images are single-channel black-and-white
images. Add a singleton channel dimension by applying the format
"SSBC" to the batch. Return the labels as a
non-dlarray on the CPU.
mbq = minibatchqueue(auimds,... MiniBatchSize=256, ... OutputAsDlarray=[1 0], ... MiniBatchFormat=["SSBC" ""], ... OutputEnvironment=["gpu" "cpu"])
To obtain mini-batches from mbq to use in a custom training loop,
use the next function.
[X,Y] = next(mbq);
Preprocess data using a minibatchqueue with a custom mini-batch preprocessing function. The custom function rescales the incoming image data between 0 and 1 and calculates the average image.
Unzip the data and create a datastore.
unzip("MerchData.zip"); imds = imageDatastore("MerchData", ... IncludeSubfolders=true, ... LabelSource="foldernames");
Create a minibatchqueue.
Set the number of outputs to
2to match the number of outputs of the function.Set the mini-batch size.
Preprocess the data using the custom function
preprocessMiniBatchdefined at the end of this example. The custom function concatenates the image data into a numeric array, rescales the image between 0 and 1, and calculates the average of the batch of images. The function returns the rescaled batch of images and the average image.Apply the preprocessing function in the background by setting the
PreprocessingEnvironmentproperty to"background". You can preprocess your data in the background if your preprocessing function is supported for a thread-based environment.Do not convert the mini-batch output variables to a
dlarray.
mbq = minibatchqueue(imds,2,... MiniBatchSize=16,... MiniBatchFcn=@preprocessMiniBatch,... PreprocessingEnvironment="background",... OutputAsDlarray=false)
mbq =
minibatchqueue with 2 outputs and properties:
Mini-batch creation:
MiniBatchSize: 16
PartialMiniBatch: 'return'
MiniBatchFcn: @preprocessMiniBatch
PreprocessingEnvironment: 'background'
Outputs:
OutputCast: {'single' 'single'}
OutputAsDlarray: [0 0]
MiniBatchFormat: {'' ''}
OutputEnvironment: {'auto' 'auto'}
Obtain a mini-batch and display the average of the images in the mini-batch. A thread worker in the backgroundPool applies the preprocessing function.
[X,averageImage] = next(mbq); imshow(averageImage)
function [X,averageImage] = preprocessMiniBatch(XCell) X = cat(4,XCell{:}); X = rescale(X,InputMin=0,InputMax=255); averageImage = mean(X,4); end
Train a network using minibatchqueue to manage the processing of mini-batches.
Load Training Data
Load the digits training data and store the data in a datastore. Create a datastore for the images and one for the labels using arrayDatastore. Then, combine the datastores to produce a single datastore to use with minibatchqueue.
[XTrain,YTrain] = digitTrain4DArrayData; dsX = arrayDatastore(XTrain,IterationDimension=4); dsY = arrayDatastore(YTrain); dsTrain = combine(dsX,dsY);
Determine the number of unique classes in the label data.
classes = categories(YTrain); numClasses = numel(classes);
Define Network
Create a dlnetwork object.
net = dlnetwork;
Specify the layers and the average image value using the Mean option in the image input layer.
layers = [
imageInputLayer([28 28 1],Mean=mean(XTrain,4))
convolution2dLayer(5,20)
reluLayer
convolution2dLayer(3,20,Padding=1)
reluLayer
convolution2dLayer(3,20,Padding=1)
reluLayer
fullyConnectedLayer(numClasses)
softmaxLayer];Add the layers and initialize the network.
net = addLayers(net,layers); net = initialize(net);
Define Model Loss Function
Create the helper function modelLoss, listed at the end of the example. The function takes as input a dlnetwork object net and a mini-batch of input data X with corresponding labels Y, and returns the loss and the gradients of the loss with respect to the learnable parameters in net.
Specify Training Options
Specify the options to use during training.
numEpochs = 10; miniBatchSize = 128;
Visualize the training progress in a plot.
plots = "training-progress";Create the minibatchqueue
Use minibatchqueue to process and manage the mini-batches of images. For each mini-batch:
Discard partial mini-batches.
Use the custom mini-batch preprocessing function
preprocessMiniBatch(defined at the end of this example) to one-hot encode the class labels.Format the image data with the dimension labels
'SSCB'(spatial, spatial, channel, batch). By default, theminibatchqueueobject converts the data todlarrayobjects with underlying data typesingle. Do not add a format to the class labels.Train on a GPU if one is available. By default, the
minibatchqueueobject converts each output to agpuArrayif a GPU is available. Using a GPU requires Parallel Computing Toolbox™ and a supported GPU device. For information on supported devices, see GPU Computing Requirements (Parallel Computing Toolbox).
mbq = minibatchqueue(dsTrain,... MiniBatchSize=miniBatchSize,... PartialMiniBatch="discard",... MiniBatchFcn=@preprocessMiniBatch,... MiniBatchFormat=["SSCB",""]);
Train Network
Train the model using a custom training loop. For each epoch, shuffle the data and loop over mini-batches while data is still available in the minibatchqueue. Update the network parameters using the adamupdate function. At the end of each epoch, display the training progress.
Initialize the average gradients and squared average gradients.
averageGrad = []; averageSqGrad = [];
Calculate the total number of iterations for the training progress monitor.
numObservationsTrain = numel(YTrain); numIterationsPerEpoch = floor(numObservationsTrain / miniBatchSize); numIterations = numEpochs * numIterationsPerEpoch;
Initialize the TrainingProgressMonitor object. Because the timer starts when you create the monitor object, make sure that you create the object close to the training loop.
if plots == "training-progress" monitor = trainingProgressMonitor(Metrics="Loss",Info="Epoch",XLabel="Iteration"); end
Train the network.
iteration = 0; epoch = 0; while epoch < numEpochs && ~monitor.Stop epoch = epoch + 1; % Shuffle data. shuffle(mbq); while hasdata(mbq) && ~monitor.Stop iteration = iteration + 1; % Read mini-batch of data. [X,Y] = next(mbq); % Evaluate the model loss and gradients using dlfeval and the % modelLoss helper function. [loss,grad] = dlfeval(@modelLoss,net,X,Y); % Update the network parameters using the Adam optimizer. [net,averageGrad,averageSqGrad] = adamupdate(net,grad,averageGrad,averageSqGrad,iteration); % Update the training progress monitor. if plots == "training-progress" recordMetrics(monitor,iteration,Loss=loss); updateInfo(monitor,Epoch=epoch + " of " + numEpochs); monitor.Progress = 100 * iteration/numIterations; end end end
Model Loss Function
The modelLoss helper function takes as input a dlnetwork object net and a mini-batch of input data X with corresponding labels Y, and returns the loss and the gradients of the loss with respect to the learnable parameters in net. To compute the gradients automatically, use the dlgradient function.
function [loss,gradients] = modelLoss(net,X,Y) YPred = forward(net,X); loss = crossentropy(YPred,Y); gradients = dlgradient(loss,net.Learnables); end
Mini-Batch Preprocessing Function
The preprocessMiniBatch function preprocesses the data using the following steps:
Extract the image data from the incoming cell array and concatenate the data into a numeric array. Concatenating the image data over the fourth dimension adds a third dimension to each image, to be used as a singleton channel dimension.
Extract the label data from the incoming cell array and concatenate along the second dimension into a categorical array.
One-hot encode the categorical labels into numeric arrays. Encoding into the first dimension produces an encoded array that matches the shape of the network output.
function [X,Y] = preprocessMiniBatch(XCell,YCell) % Extract image data from the cell array and concatenate over fourth % dimension to add a third singleton dimension, as the channel % dimension. X = cat(4,XCell{:}); % Extract label data from cell and concatenate. Y = cat(2,YCell{:}); % One-hot encode labels. Y = onehotencode(Y,1); end
