Import Data into Signal Labeler

Supported Signal Types

The Signal Labeler app works with real-valued vectors, matrices, MATLAB^® timetables, and labeledSignalSet objects. The app also supports MAT-files and CSV files.

Note

Signal Labeler does not support complex-valued signals, signals with Inf or NaN values, multidimensional arrays, or sparse matrices.

Example: Numeric Arrays
```
num = cos(pi./[4;2]*(0:159))'+randn(160,2);
```
specifies a two-channel signal consisting of sinusoids embedded in white noise. The signal does not contain time information unless you specify it. In Signal Labeler, you can import the signal in samples, or you can add time information when you import it.
Example: MATLAB Timetables
```
tt1 = timetable(num,'SampleRate',100);
tt2 = timetable(seconds((0:159)'/100),num);
```
both specify that the noisy two-channel sinusoid is sampled at 100 Hz. For more information, see the timetable documentation.
Example: labeledSignalSet Objects
```
lss = labeledSignalSet(num);
```
specifies that the noisy sinusoid is in samples.
Example: labeledSignalSet Objects with Time Information
```
lst1 = labeledSignalSet(num,'SampleRate',100);
lst2 = labeledSignalSet(timetable(seconds((0:159)'/100),num));
```
both specify that the noisy sinusoid is sampled at 100 Hz.
Example: Multisignal Members
```
msn = labeledSignalSet({randn(10,3),randn(17,9)});
```
has two members. The first member contains three 10-sample signals. The second member contains nine 17-sample signals.
```
mst = labeledSignalSet({{timetable(seconds(1:10)',randn(10,3))}, ...
    {timetable(seconds(1:7)',randn(7,2)), ...
    timetable(randn(30,1),'SampleRate',100)}});
```
has two members. The first member contains three signals sampled at 1 Hz for 10 seconds. The second member contains two signals sampled at 1 Hz for 7 seconds and one 30-sample signal sampled at 100 Hz.

Example: signalDatastore Object Pointing to Files

Specify the path to a set of sample sound signals included as MAT-files with MATLAB®. Each file contains a signal variable and a sample rate. List the names of the files.

folder = fullfile(matlabroot,"toolbox","matlab","audiovideo");
lst = dir(append(folder,"/*.mat"));
nms = {lst(:).name}'

nms = 7x1 cell
    {'chirp.mat'   }
    {'gong.mat'    }
    {'handel.mat'  }
    {'laughter.mat'}
    {'mtlb.mat'    }
    {'splat.mat'   }
    {'train.mat'   }

Create a signal datastore that points to the specified folder. Set the sample rate variable name to Fs, which is common to all files. Generate a subset of the datastore that excludes the file mtlb.mat, which differs from the other files in that the signal variable is not called y.

sds = signalDatastore(folder,"SampleRateVariableName","Fs");
sdss = subset(sds,~strcmp(nms,"mtlb.mat"));

Use the subset datastore as the source for a labeledSignalSet object.

lss = labeledSignalSet(sdss)

lss = 
  labeledSignalSet with properties:

             Source: [1x1 signalDatastore]
         NumMembers: 6
    TimeInformation: "inherent"
             Labels: [6x0 table]
        Description: ""

 Use labelDefinitionsHierarchy to see a list of labels and sublabels.
 Use setLabelValue to add data to the set.

Specify Time Information

The signals you import into Signal Labeler can be labeled in samples or in time. This specification stays fixed to ensure consistent labeling. You cannot mix signals in samples and signals with time information in the same session.

When specifying the time information for a set of signals that do not have it, select a time specification option in the import dialog box.

Time Specification Option	Description
`Samples`	This option enables you to explore and label signals without the need to specify a sample rate or a sample time. It is equivalent to plotting the signal in MATLAB without x-axis information.
`Sample Rate`	Use this option when you know the rate at which the signal has been sampled. The sample rate can be expressed in Hz, kHz, MHz, or GHz. To specify the sample rate, you can use a numeric value, the name of a scalar variable in the MATLAB Workspace, or any valid MATLAB expression. Set the sample rate so that the members are plotted in units of time.
`Sample Rate Variable From File`	Use this option when the sample rate is saved as a variable in the file being imported.
`Sample Time`	Use this option when you know the time interval between samples. The sample time can be expressed in seconds, years, days, hours, minutes, milliseconds, microseconds, or nanoseconds. To specify the sample time, you can use a numeric value, the name of a scalar variable in the MATLAB Workspace, or any valid MATLAB expression. Set the sample time so that the members are plotted in units of time.
`Sample Time Variable From File`	Use this option when the sample time is saved as a variable in the file being imported.
`Time Values`	Use this option when you know the time value corresponding to each sample. Specify the time values using a valid MATLAB expression or the name of a variable in the MATLAB Workspace. The time values can be stored in a numeric or `duration` vector with real time values expressed in seconds. The values must be unique and cannot be `NaN`, but need not be uniformly spaced. The time array must have the same length as the members. In all cases, the app derives a sample rate from the time values and displays it in the Time column of the Labeled Signal Set Browser. An asterisk preceding the sample rate indicates that the members are nonuniformly sampled.
`Time Values Variable From File`	Use this option when the time values are saved as a variable in the file being imported.

Once a signal or set of signals has been imported into Signal Labeler, the chosen time specification stays fixed throughout the labeling session.

Import Signals from the MATLAB Workspace

To import signals to Signal Labeler from the MATLAB Workspace, on the Labeler tab, click Import ▼ and select From workspace in the Members list. In the dialog box, select the signals you want to import.

Import Members from Workspace dialog box

If you initially imported a numeric array and specified it in samples, or if you initially imported a labeledSignalSet object in samples, you can subsequently choose only signals in samples. If you choose a numeric array, Signal Labeler imports it and treats it in samples.
If you initially imported a numeric array and specified its time information, or if you initially imported a MATLAB timetable or a labeledSignalSet object with time information, you can subsequently choose only signals with time information. If you choose a numeric array, you must set its time information when importing it.

Note

You cannot modify the time information of a labeledSignalSet object from within Signal Labeler. If the labeled signal set has no time information, the app treats its members as being in samples. If the labeled signal set has time information, the app incorporates this information when it imports the signals. For more information, see the labeledSignalSet documentation.

To be imported successfully, labeled signal sets must obey these additional rules:

If the selection includes two or more labeled signal sets, the labeled signal sets must have unique signal label definitions. If two or more sets share a label definition, the definition must have the same type and data type for all sets. For more information, see Create or Import Signal Label Definitions.
If the selection includes two or more labeled signal sets, the labeled signal sets must have unique member names. You cannot change member names from within Signal Labeler. To change the name of a member of a labeled signal set, use setMemberNames at the command line.
If you select two or more labeledSignalSet objects for labeling, Signal Labeler merges them and creates a single labeled signal set containing all the members and label values of the input sets. This action is equivalent to using merge at the command line.

Import Signals from Files

To import signals to Signal Labeler from files, on the Labeler tab, click Import ▼ and select From files in the Members list. In the dialog box, browse to select the signals you want to import.

Note

Signal Labeler supports MAT-files and CSV files only. All values in a CSV file other than headers must be numeric.
Importing labeledSignalSet objects from files is not supported. To import a labeledSignalSet object, load it into the MATLAB Workspace and import it from there.

Import Members from File dialog box

All members to import must have the same extension and the same variables.
Signal Labeler does not support working simultaneously with in-memory data and data from files.
- If you initially imported in-memory members from the MATLAB Workspace, the From files option is disabled from the Import menu of the Labeler tab.
- If you initially imported data from files, the only workspace variables you can then import from the MATLAB Workspace are labeledSignalSet objects whose input data sources are signalDatastore objects pointing to files. For an example, see Supported Signal Types.

By default, Signal Labeler reads the first signal variable of each file. To determine the name of the first variable in a file, signalDatastore follows these steps:

For MAT-files:

s = load(fileName);
varNames = fieldnames(s);
firstVar = s.(varNames{1});

For CSV files:

opts = detectImportOptions(fileName,'PreserveVariableNames',true);
varNames = opts.VariableNames;
firstVar = string(varNames{1});

To specify the signal variables that you want to read, click Specify and enter a comma-separated list of signal variable names.

Tip

If a CSV file does not have variable names specified in a header line, then the variables are called Var1 for the first column, Var2 for the second column, and so on.

Documentation