readByIndex

Class: matlab.io.datastore.BackgroundDispatchable
Namespace: matlab.io.datastore

(Not recommended) Return observations specified by index from datastore

readByIndex is not recommended. For more information, see Compatibility Considerations.

Syntax

[data,info] = readByIndex(ds,ind)


Description

[data,info] = readByIndex(ds,ind) returns a subset of observations in a datastore, ds. The desired observations are specified by indices, ind.

Input Arguments

ds — Input datastore

Datastore object

Input datastore, specified as a Datastore object.

ind — Indices

vector of positive integers

Indices of observations, specified as a vector of positive integers.

Output Arguments

data — Observations from datastore

table

Observations from the datastore, returned as a table or an array according to the read method of the datastore. For example, when ds is a custom mini-batch datastore, then data is a table with the same format as returned by the read (MiniBatchable) method.

info — Information about read data

structure array

Information about read data, returned as a structure array. The structure array can contain the following fields.

Field Name	Description
Filename	Filename is a fully resolved path containing the path string, name of the file, and file extension.
FileSize	Total file size, in bytes. For MAT-files, FileSize is the total number of key-value pairs in the file.

Attributes

Abstract	true
Access	Public

To learn about attributes of methods, see Method Attributes.

Tips

• You must implement the readByIndex method by deriving a subclass from the matlab.io.datastore.BackgroundDispatchable class.

Version History

Introduced in R2018a

R2019a: readByIndex is not recommended

Before R2018a, to perform custom image preprocessing for training deep learning networks, you had to specify a custom read function using the readFcn property of imageDatastore. However, reading files using a custom read function was slow because imageDatastore did not prefetch files.

In R2018a, four classes including matlab.io.datastore.MiniBatchable and matlab.io.datastore.BackgroundDispatchable were introduced as a solution to perform custom image preprocessing with support for prefetching, shuffling, and parallel training. Implementing a custom mini-batch datastore using matlab.io.datastore.MiniBatchable has several challenges and limitations.

• In addition to specifying the preprocessing operations, you must also define properties and methods to support reading data in batches, reading data by index, and partitioning and shuffling data.

• You must specify a value for the NumObservations property, but this value may be ill-defined or difficult to define in real-world applications.

• Custom mini-batch datastores are not flexible enough to support common deep learning workflows, such as deployed workflows using GPU Coder™.

Starting in R2019a, datastores natively support prefetch, shuffling, and parallel training when reading batches of data. The transform function is the preferred way to perform custom data preprocessing, or transformations. The combine function is the preferred way to concatenate read data from multiple datastores, including transformed datastores. Concatenated data can serve as the network inputs and expected responses for training deep learning networks. The transform and combine functions have several advantages over matlab.io.datastore.MiniBatchable and matlab.io.datastore.BackgroundDispatchable.

• The functions enable data preprocessing and concatenation for all types of datastores, including imageDatastore.

• The transform function only requires you to define the data processing pipeline.

• When used on a deterministic datastore, the functions support tall data types and MapReduce.

• The functions support deployed workflows.

Note

The recommended solution to transform data with basic image preprocessing operations, including resizing, rotation, and reflection, is augmentedImageDatastore. For more information, see Preprocess Images for Deep Learning.

There are no plans to remove matlab.io.datastore.BackgroundDispatchable class or the readByIndex method at this time.