writeall

Write datastore to files

Since R2021a

Syntax

writeall(sds,outputLocation)

writeall(sds,outputLocation,Name,Value)

Description

writeall(sds,outputLocation) writes the data from the input datastore sds to output files at the location specified in outputLocation. The number of output files is the same as the number of files referenced by the datastore.

writeall(sds,outputLocation,Name,Value) writes data with additional options specified by one or more name-value arguments. For example, 'FilenameSuffix','norm' adds the descriptive text 'norm' at the end of all output files.

Examples

Write In-Memory Signal Datastore to Files

Create a signal datastore to iterate through the elements of an in-memory cell array of signal data. The array contains:

• A sinusoidally modulated linear chirp

• A concave quadratic chirp

• A voltage controlled oscillator

• A set of pulses of decreasing duration separated by regions of oscillating amplitude and fluctuating frequency with an increasing trend

The signals are sampled at 3000 Hz.

fs = 3000;
t = 0:1/fs:3-1/fs;
data = {chirp(t,300,t(end),800).*exp(2j*pi*10*cos(2*pi*2*t)); ...
        2*chirp(t,200,t(end),1000,'quadratic',[],'concave'); ...
        vco(sin(2*pi*t),[0.1 0.4]*fs,fs);
        besselj(0,600*(sin(2*pi*(t+1).^3/30).^5));};
sds = signalDatastore(data,'SampleRate',fs);

Create a folder called Files in the current folder. Write the contents of the datastore to files. List the contents of the folder. The writeall function uses the MemberNames property of signalDatastore to name the files and the signals in the files.

fname = 'Files';
mkdir(fname)

writeall(sds,fname)

dir(fname)

.            ..           Member1.mat  Member2.mat  Member3.mat  Member4.mat  

Create a datastore that points to the files in Files. Read the data one file at a time. Compute and display the short-time Fourier transform of each signal.

sdfs = signalDatastore(fname,'SampleRate',fs);
tiledlayout flow
while hasdata(sdfs)
    nexttile
    [sg,nf] = read(sdfs);
    stft(sg,nf.SampleRate)
end

Remove the Files directory you created earlier in the example.

rmdir(fname,'s')

Write Datastore Spectrograms to Files

Specify the path to four signals included with MATLAB®. The signals are recordings of a bird chirping, a train, a splat, and a female voice saying the word "MATLAB." The first three signals are sampled at 8192 Hz and the fourth at 7418 Hz. Create a signal datastore that points to the specified files.

fls = ["chirp" "train" "splat" "mtlb"];
folder = fullfile(matlabroot,"toolbox","matlab","audiovideo", ...
    append(fls,".mat"));

sds = signalDatastore(folder,SampleRateVariableName="Fs");

Write the spectrograms of the signals to text files in the current folder using the writeall and writeSpectrogram functions. writeall uses the MemberNames property of signalDatastore to name the files and the signals in the files. Create a datastore that points to the files in the current folder.

writeall(sds,".","WriteFcn",@writeSpectrogram)

sdfs = signalDatastore(".");

Read the data one file at a time. Display the spectrogram of each signal.

tiledlayout flow
while hasdata(sdfs)
    nexttile
    
    [d,info] = read(sdfs);
    waterfall(d(2:end,1),d(1,2:end),d(2:end,2:end)')
    
    wtf = gca;
    wtf.XDir = "reverse";
    view(30,45)
    xlabel("{\it f} (Hz)")
    ylabel("{\it t} (s)")
    
    [~,k] = fileparts(info.FileName);
    title(k)
end

The writeSpectrogram function computes the spectrogram of the input signal using pspectrum and writes it to a MAT-file in the current folder. The function specifies 80% of overlap between adjoining segments, a time resolution of 0.15 second, and a spectral leakage of 0.8.

function writeSpectrogram(data,info,~)

    [s,f,t] = pspectrum(data,info.ReadInfo.SampleRate,"spectrogram", ...
        TimeResolution=0.15,OverlapPercent=80,Leakage=0.8);
    d = [NaN t'; f s];
    
    [~,q] = fileparts(info.SuggestedOutputName);
    save(q,"d")

end

Input Arguments

sds — Signal datastore

signalDatastore object

Signal datastore, specified as a signalDatastore object. By default, when sds contains in-memory data, the writeall function writes the input data to MAT-files.

Example: signalDatastore({randn(100,1)},'SampleRate',100) specifies a signal datastore containing one member, a random signal, sampled at 100 Hz.

outputLocation — Folder location to write data

character vector | string scalar

Folder location to write data, specified as a character vector or string scalar. outputLocation can specify a full or relative path.

Example: outputLocation = '../../dir/data'

Example: outputLocation = "C:\Users\MyName\Desktop"

Data Types: char | string

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: writeall(sds,outputLocation,'FolderLayout','flatten')

FolderLayout — Layout of files in output folder

'duplicate' (default) | 'flatten'

Layout of files in the output folder, specified as either 'duplicate' or 'flatten'.

• 'duplicate' — Replicate the folder structure of the data that the signal datastore points to. Specify the 'FolderLayout' as 'duplicate' to maintain correspondence between the input and output datasets.

• 'flatten' — Write all the files from the input to the specified output folder without any subfolders.

'FolderLayout' does not apply when sds contains in-memory data.

Data Types: char | string

FilenamePrefix — Prefix to file name

character vector | string scalar

Prefix to file name, specified as a character vector or string scalar.

The writeall function adds the specified prefix to the output file names. For example, this code adds today’s date to the beginning of all output file names from the datastore.

prefixText = string(datetime('today'))
writeall(imds,'C:\myFolder','FilenamePrefix',prefixText);

Data Types: char | string

FilenameSuffix — Suffix to file name

character vector | string scalar

Suffix to file name, specified as a character vector or string scalar.

The writeall function adds the specified suffix to the output file names. For example, this code adds the descriptive text 'jpeg_70per' at the end of all output file names from the datastore.

writeall(imds,'C:\myFolder','FilenameSuffix','jpeg_70per');

Data Types: char | string

UseParallel — Indicator to write in parallel

false or 0 (default) | true or 1

Indicator to write in parallel, specified as either false or true.

By default writeall writes in serial. If you set UseParallel to true, then writeall divides the writing operations into separate groups and runs the groups in parallel if:

• Parallel Computing Toolbox™ is installed.

• An open parallel pool exists or automatic pool creation is enabled in the Parallel Preferences.

Otherwise, writeall writes in serial regardless of the value for UseParallel.

Note

Parallel writing is not supported for CombinedDatastore objects or datastores resulting from the transform applied to a CombinedDatastore.

Data Types: logical

WriteFcn — Custom writing function

function handle

Custom writing function, specified as a function handle. The specified function is responsible for creating the output files. You can use the 'WriteFcn' name-value argument to transform data or write data to a file format different from the default, even if writeall does not directly support the output format.

Function Signature

The custom writing function must accept at least three input arguments, data, writeInfo, and suggestedOutputType.

function myWriteFcn(data,writeInfo,suggestedOutputType)

The function can also accept additional inputs, such as name-value arguments, after the first three required inputs.

• data contains the output of the read method operating on the datastore.

• writeInfo is an object of type matlab.io.datastore.WriteInfo with fields listed in the table.

  Field	Description	Type
  ReadInfo	The second output of the read method of the signalDatastore	struct
  SuggestedOutputName	A fully qualified, globally unique file name that meets the location and naming requirements	string
  Location	The specified outputLocation passed to writeall	string

• suggestedOutputType is the suggested output file type.

Example Function

A simple write function that computes the spectrogram of the input signal using pspectrum and writes it to a text file in the current folder using the MATLAB^® function writematrix. The function specifies 80% of overlap between adjoining segments, a time resolution of 0.15 second, and a spectral leakage of 0.8.

function writeSpectrogram(data,info,~)

    [s,f,t] = pspectrum(data,info.ReadInfo.SampleRate,'spectrogram', ...
        'TimeResolution',0.15,'OverlapPercent',80,'Leakage',0.8);
    d = [NaN t'; f s];
    
    [~,q] = fileparts(info.SuggestedOutputName);
    writematrix(d,append(q,".txt"))

end

To use writeSpectrogram as the writing function for the signalDatastore object sds, use this command.

writeall(sds,'.','WriteFcn',@writeSpectrogram)

Data Types: function_handle

Version History

Introduced in R2021a