Main Content

writeall

Write datastore to files

Since R2021a

    Description

    example

    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

    collapse all

    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')

    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

    collapse all

    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.

    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')

    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

    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

    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

    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

    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.

      FieldDescriptionType
      ReadInfoThe second output of the read method of the signalDatastorestruct
      SuggestedOutputNameA fully qualified, globally unique file name that meets the location and naming requirementsstring
      LocationThe specified outputLocation passed to writeallstring
    • 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