Documentation

Training and Validation

To use an image datastore as a source of training data, use the imds argument of trainNetwork. To use all other types of datastore as a source of training data, use the ds argument of trainNetwork. To use a datastore for validation, use the 'ValidationData' name-value pair argument in trainingOptions.

To be a valid input for training or validation, the read function of a datastore must return data as either a cell array or a table (with the exception of ImageDatastore objects which can output numeric arrays and custom mini-batch datastores which must output tables).

For networks with a single input, the table or cell array returned by the datastore must have two columns. The first column of data represents inputs to the network and the second column of data represents responses. Each row of data represents a separate observation. For ImageDatastore only, trainNetwork and trainingOptions support data returned as integer arrays and single-column cell array of integer arrays.

To use a datastore for networks with multiple input layers, use the combine and transform functions to create a datastore that outputs a cell array with (numInputs + 1) columns, where numInputs is the number of network inputs. In this case, the first numInputs columns specify the predictors for each input and the last column specifies the responses. The order of inputs is given by the InputNames property of the layer graph layers.

The following table shows example outputs of calling the read function for datastore ds.

data = read(ds)

data =

  4×2 table

        Predictors        Response
    __________________    ________

    {224×224×3 double}       2    
    {224×224×3 double}       7    
    {224×224×3 double}       9    
    {224×224×3 double}       9  

data = read(ds)

data =

  4×2 cell array

    {224×224×3 double}    {[2]}
    {224×224×3 double}    {[7]}
    {224×224×3 double}    {[9]}
    {224×224×3 double}    {[9]}

data = read(ds)

data =

  4×3 cell array

    {224×224×3 double}    {128×128×3 double}    {[2]}
    {224×224×3 double}    {128×128×3 double}    {[2]}
    {224×224×3 double}    {128×128×3 double}    {[9]}
    {224×224×3 double}    {128×128×3 double}    {[9]}

The format of the predictors depend on the type of data.

For predictors returned in tables, the elements must contain a numeric scalar, a numeric row vector, or a 1-by-1 cell array containing a numeric array.

The trainNetwork function does not support networks with multiple sequence input layers.

The format of the responses depend on the type of task.

For responses returned in tables, the elements must be a categorical scalar, a numeric scalar, a numeric row vector, or a 1-by-1 cell array containing a numeric array.

Prediction

For inference using predict, classify, and activations, a datastore is only required to yield the columns corresponding to the predictors. The inference functions use the first NumInputs columns and ignores the subsequent layers, where NumInputs is the number of network input layers.

Transform Datastores

A transformed datastore applies a particular data transformation to an underlying datastore when reading data. To create a transformed datastore, use the transform function and specify the underlying datastore and the transformation.

The function handle provided to transform must accept input data in the same format as returned by the read function of the underlying datastore.

digitDatasetPath = fullfile(matlabroot,'toolbox','nnet', ...
    'nndemos','nndatasets','DigitDataset');
imds2 = imageDatastore(digitDatasetPath, ...
    'IncludeSubfolders',false, ...
    'LabelSource','foldernames');

miniBatchSize = 128;
imds.ReadSize = miniBatchSize;

dsTrain = transform(imds,@preprocessForTraining,'IncludeInfo',true)

dsTrain = 

  TransformedDatastore with properties:

    UnderlyingDatastore: [1×1 matlab.io.datastore.ImageDatastore]
             Transforms: {@preprocessForTraining}
            IncludeInfo: 1

layers = [
    imageInputLayer([28 28 1],'Normalization','none')
    convolution2dLayer(5,20)
    reluLayer
    maxPooling2dLayer(2,'Stride',2)
    fullyConnectedLayer(10);
    softmaxLayer
    classificationLayer];
 
options = trainingOptions('adam', ...
    'Plots','training-progress', ...
    'MiniBatchSize',miniBatchSize);
 
net = trainNetwork(dsTrain,layers,options);

function [dataOut,info] = preprocessForTraining(data,info)
 
numRows = size(data,1);
dataOut = cell(numRows,2);
 
for idx = 1:numRows
    
    % Randomized 90 degree rotation
    imgOut = rot90(data{idx,1},randi(4)-1);
    
    % Return the label from info struct as the 
    % second column in dataOut.
    dataOut(idx,:) = {imgOut,info.Label(idx)};
    
end

end

Combine Datastores

The combine function associates multiple datastores. Operating on the resulting CombinedDatastore, such as resetting the datastore, performs the same operation on all of the underlying datastores. Calling the read function of a combined datastore reads one batch of data from all of the N underlying datastores, which must return the same number of observations. Reading from a combined datastore returns the horizontally concatenated results in an N-column cell array that is suitable for training and validation. Shuffling a combined datastore results in an identical randomized ordering of files in the underlying datastores.

For example, if you are training an image-to-image regression network, then you can create the training data set by combining two image datastores. This sample code demonstrates combining two image datastores named imdsX and imdsY. The combined datastore imdsTrain returns data as a two-column cell array.

imdsX = imageDatastore(___);
imdsY = imageDatastore(___);
imdsTrain = combine(imdsX,imdsY)

imdsTrain = 

  CombinedDatastore with properties:

    UnderlyingDatastores: {1×2 cell}

If you have Image Processing Toolbox, then the randomPatchExtractionDatastore (Image Processing Toolbox) provides an alternate solution to associating image-based data in ImageDatastores, PixelLabelDatastores, and TransformedDatastores. A randomPatchExtractionDatastore has several advantages over associating data using the combine function. Specifically, a random patch extraction datastore: