minibatchqueue
Create mini-batches for deep learning
Description
Use minibatchqueue to create, preprocess, and manage
mini-batches of data for training using custom training loops.
A minibatchqueue iterates over a datastore to provide data in a suitable
format for training using custom training loops. Use a minibatchqueue to
automatically convert your data to dlarray or gpuArray,
convert data to a different precision, or apply a custom function to preprocess your data. You
can prepare your data in parallel in the background.
During training, you can manage your data using the minibatchqueue. 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 there is any data left in the queue using the hasdata function,
and reset the queue
when it is empty.
Creation
Description
mbq = minibatchqueue(ds)minibatchqueue 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 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.
Input Arguments
Properties
Object Functions
Examples
Prepare Mini-Batches for Custom Training Loop
Use a minibatchqueue to automatically prepare
mini-batches of images and classification labels for training 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 from auimds. Set the
MiniBatchSize property to 256.
The minibatchqueue has two output variables: the images and
classification labels from the input and response
variables of auimds, respectively. Set the
minibatchqueue 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'})
Use the next function to obtain mini-batches from
mbq.
[X,Y] = next(mbq);
Create Mini-Batches Using Custom Preprocessing Function
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 that preprocesses data using the custom function preprocessMiniBatch defined 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. Set the number of outputs to 2, to match the number of outputs of the function.
mbq = minibatchqueue(imds,2,... 'MiniBatchSize',16,... 'MiniBatchFcn',@preprocessMiniBatch,... 'OutputAsDlarray',0)
mbq =
minibatchqueue with 2 outputs and properties:
Mini-batch creation:
MiniBatchSize: 16
PartialMiniBatch: 'return'
MiniBatchFcn: @preprocessMiniBatch
DispatchInBackground: 0
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.
[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
Use minibatchqueue in a Custom Training Loop
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
Define the network and specify the average image value using the 'Mean' option in the image input layer.
layers = [
imageInputLayer([28 28 1], 'Name','input','Mean',mean(XTrain,4))
convolution2dLayer(5,20,'Name','conv1')
reluLayer('Name', 'relu1')
convolution2dLayer(3,20,'Padding',1,'Name','conv2')
reluLayer('Name','relu2')
convolution2dLayer(3,20,'Padding',1,'Name','conv3')
reluLayer('Name','relu3')
fullyConnectedLayer(numClasses,'Name','fc')
softmaxLayer('Name','softmax')];
lgraph = layerGraph(layers);
Create a dlnetwork object from the layer graph.
dlnet = dlnetwork(lgraph);
Define Model Gradients Function
Create the helper function modelGradients, listed at the end of the example. The function takes a dlnetwork object dlnet and a mini-batch of input data dlX with corresponding labels Y, and returns the loss and the gradients of the loss with respect to the learnable parameters in dlnet.
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 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 CUDA® enabled NVIDIA® GPU with compute capability 3.0 or higher.
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 training progress plot.
if plots == "training-progress" figure lineLossTrain = animatedline('Color',[0.85 0.325 0.098]); ylim([0 inf]) xlabel("Iteration") ylabel("Loss") grid on end
Initialize the average gradients and squared average gradients.
averageGrad = []; averageSqGrad = [];
Train the network.
iteration = 0; start = tic; for epoch = 1:numEpochs % Shuffle data. shuffle (mbq); while hasdata(mbq) iteration = iteration + 1; % Read mini-batch of data [dlX,Y] = next(mbq); % Evaluate the model gradients and loss using dlfeval and the % modelGradients helper function. [grad,loss] = dlfeval(@modelGradients,dlnet,dlX,Y); % Update the network parameters using the Adam optimizer. [dlnet,averageGrad,averageSqGrad] = adamupdate(dlnet,grad,averageGrad,averageSqGrad,iteration); % Display the training progress. if plots == "training-progress" D = duration(0,0,toc(start),'Format','hh:mm:ss'); addpoints(lineLossTrain,iteration,double(gather(extractdata(loss)))) title("Epoch: " + epoch + ", Elapsed: " + string(D)) drawnow end end end
Model Gradients Function
The modelGradients helper function takes a dlnetwork object dlnet and a mini-batch of input data dlX with corresponding labels Y, and returns the loss and the gradients of the loss with respect to the learnable parameters in dlnet. To compute the gradients automatically, use the dlgradient function.
function [gradients,loss] = modelGradients(dlnet,dlX,Y) dlYPred = forward(dlnet,dlX); loss = crossentropy(dlYPred,Y); gradients = dlgradient(loss,dlnet.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 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 cell and concatenate over 4th dimension to adds a % singleton dimension 3 for 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