subset

Create subset of datastore or FileSet

Syntax

subds = subset(ds,indices)

Description

subds = subset(ds,indices) returns a subset containing reads corresponding to indices. The subset subds is of the same type as the input.

• if the input ds is a datastore, then the output outds is a datastore of the same type.

• if the input ds is a FileSet, DsFileSet, or BlockedFileSet object, then the output subds is also, respectively, a FileSet, DsFileSet, or BlockedFileSet object.

Examples

Create Subset of ImageDatastore

Make an image datastore object and then create a subset of that image datastore.

Create an image datastore imds for all the image files in a sample folder. Then, display the Files property of imds.

folders = fullfile(matlabroot,'toolbox','matlab',{'demos','imagesci'});
exts = {'.jpg','.png','.tif'};
imds = imageDatastore(folders,'LabelSource','foldernames','FileExtensions',exts);
imds.Files

ans =

  8×1 cell array

    {'...\matlab\toolbox\matlab\demos\cloudCombined.jpg'}
    {'...\matlab\toolbox\matlab\demos\example.tif'      }
    {'...\matlab\toolbox\matlab\demos\landOcean.jpg'    }
    {'...\matlab\toolbox\matlab\demos\ngc6543a.jpg'     }
    {'...\matlab\toolbox\matlab\demos\street1.jpg'      }
    {'...\matlab\toolbox\matlab\demos\street2.jpg'      }
    {'...\matlab\toolbox\matlab\imagesci\corn.tif'      }
    {'...\matlab\toolbox\matlab\imagesci\peppers.png'   }

Create a subset datastore subimds that contains the first four files of imds and examine the Files property of subimds.

indices = 1:4; 
subimds = subset(imds,indices); 
subimds.Files

ans =

  4×1 cell array

    {'...\matlab\toolbox\matlab\demos\cloudCombined.jpg'}
    {'...\matlab\toolbox\matlab\demos\example.tif'      }
    {'...\matlab\toolbox\matlab\demos\landOcean.jpg'    }
    {'...\matlab\toolbox\matlab\demos\ngc6543a.jpg'     }

Create Subset Datastore with Randomly Selected Files

Make an image datastore, and then create subset datastore containing only a specified percentage of files, randomly selected from the original datastore.

Create imageDatastore for all the image files in a sample folder and display the Files property. This datastore contains 8 files.

folders = fullfile(matlabroot,'toolbox','matlab',{'demos','imagesci'});
exts = {'.jpg','.png','.tif'};
imds = imageDatastore(folders,'LabelSource','foldernames','FileExtensions',exts);
imds.Files

ans =

  8×1 cell array

    {'...\matlab\toolbox\matlab\demos\cloudCombined.jpg'}
    {'...\matlab\toolbox\matlab\demos\example.tif'      }
    {'...\matlab\toolbox\matlab\demos\landOcean.jpg'    }
    {'...\matlab\toolbox\matlab\demos\ngc6543a.jpg'     }
    {'...\matlab\toolbox\matlab\demos\street1.jpg'      }
    {'...\matlab\toolbox\matlab\demos\street2.jpg'      }
    {'...\matlab\toolbox\matlab\imagesci\corn.tif'      }
    {'...\matlab\toolbox\matlab\imagesci\peppers.png'   }

Create a set of indices that represents randomly selected subset containing 60% of the files.

nFiles = length(imds.Files);
RandIndices = randperm(nFiles);
nSixtyPercent = round(0.6*nFiles);
indices = RandIndices(1:nSixtyPercent)

indices =

     8     6     4     5     1

Create a subset datastore submids using indices and examine its Files property.

subimds = subset(imds,indices); 
subimds.Files

ans =

  5×1 cell array

    {'...\matlab\toolbox\matlab\imagesci\peppers.png'   }
    {'...\matlab\toolbox\matlab\demos\street2.jpg'      }
    {'...\matlab\toolbox\matlab\demos\ngc6543a.jpg'     }
    {'...\matlab\toolbox\matlab\demos\street1.jpg'      }
    {'...\matlab\toolbox\matlab\demos\cloudCombined.jpg'}

Compare Data Granularities

Compare a coarse-grained partition with a fine-grained subset.

Read all the frames in the video file xylophone.mp4 and construct an ArrayDatastore object to iterate over it. The resulting object has 141 frames.

v = VideoReader("xylophone.mp4");
allFrames = read(v);
arrds = arrayDatastore(allFrames,IterationDimension=4,OutputType="cell",ReadSize=4);

To extract a specific set of adjacent frames, create four coarse-grained partitions of arrds. Extract the second partition, which has 35 frames.

partds = partition(arrds,4,2);
imshow(imtile(partds.readall()))

Extract six nonadjacent frames from arrds at specified indices using a fine-grained subset.

subds = subset(arrds,[67 79 82 69 89 33]);
imshow(imtile(subds.readall()))

Input Arguments

ds — Input datastore or file-set

matlab.io.Datastore object | FileSet object | DsFileSet object | BlockedFileSet object

Input datastore or file-set, specified as a datastore, FileSet, DsFileSet, or BlockedFileSet object.

indices — Indices of files to include in subset

vector of indices | logical vector

Indices of files to include in subset, specified as a vector of indices or a logical vector.

• The vector of indices must contain the indices of files to include in the subset subds.

• The logical vector must be of the same length as the number of files in the input ds. The subset method creates a subset subds containing files corresponding to the elements in the logical vector that have a value of true.

Elements of indices must be unique.

Data Types: double | logical

Extended Capabilities

Thread-Based Environment

Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

Usage notes and limitations:

• In a thread-based environment, you can use subset only with the following datastores:

  • ImageDatastore objects

  • CombinedDatastore, SequentialDatastore, or TransformedDatastore objects you create from ImageDatastore objects by using combine or transform

  You can use subset with other datastores if you have Parallel Computing Toolbox™. To do so, run the function using a process-backed parallel pool instead of using backgroundPool or ThreadPool (use either ProcessPool or ClusterPool).

For more information, see Run MATLAB Functions in Thread-Based Environment.

Version History

Introduced in R2019a