Main Content

sigrangebinmask

Label signal samples with values within a specified range

Since R2023a

collapse all in page

    Syntax

    msk = sigrangebinmask(x,bound)
    msk = sigrangebinmask(x,bound,fs)
    msk = sigrangebinmask(x,bound,ts)
    msk = sigrangebinmask(___,Name=Value)
    sigrangebinmask(___)

    Description

    msk = sigrangebinmask(x,bound) returns a binary mask msk whose elements are true when the corresponding samples in signal x are within the target range specified by bound.

    example

    msk = sigrangebinmask(x,bound,fs) specifies a sample rate fs.

    example

    msk = sigrangebinmask(x,bound,ts) specifies a sample time ts.

    msk = sigrangebinmask(___,Name=Value) specifies additional options using name-value arguments. For example, you can specify a minimum region length to filter out false positives. Use this syntax with any of the input arguments in the previous syntaxes.

    example

    sigrangebinmask(___) with no output argument plots the signal regions within the specified range that meet the minimum length requirement.

    example

    Examples

    collapse all

    Open Live Script

    Consider a signal with 10 samples whose values range between 1 and 100.

    x = [0 12 7 65 90 27 99 44 50 90];

    Label signal samples greater than 45. Plot the result.

    bound = 45;
sigrangebinmask(x,bound)

    Figure contains an axes object. The axes object with title Signal Regions (MinLength = 0 Samples), xlabel Samples contains 6 objects of type patch, constantline, line. One or more of the lines displays its values using only markers

    Open Live Script

    Load a set of temperature readings in degrees Celsius taken every hour at Logan Airport in Boston for 31 days in January of 2011. Convert the data to a timetable.

    load bostemp
tt = array2timetable(tempC, ...
    TimeStep=hours(1),StartTime=datetime(2011,01,01));

    Label the intervals of at least eight consecutive hours in which the temperature readings were between –10 °C and –5 °C or between 5 °C and 10 °C. Plot the result.

    bound = [-10 -5; 5 10];
sigrangebinmask(tt,bound,MinLength=hours(8))
ylabel("Temperature (^\circC)")

    Figure contains an axes object. The axes object with title Signal Regions (MinLength = 8 hr), xlabel Time, ylabel Temperature ( toThePowerOf degree baseline C) contains 9 objects of type patch, constantline, line. One or more of the lines displays its values using only markers

    Open Live Script

    Load EMGdata into the Workspace. The file contains eight channels of surface electromyography (EMG) data [1] recorded from eight arm muscles of a volunteer performing different arm motions for three seconds each. For this example, use only the fifth channel of the EMG data. The sample rate is 3 kHz.

    The data is available at: www.sce.carleton.ca/faculty/chan/index.php?page=matlab.

    load EMGdata

fs = 3000;
x = data(:,5);

    Extract the absolute amplitude of the signal using the envelope function.

    xenv = envelope(abs(x),600,"peak");

    Label regions where the EMG amplitude is greater than 0.25 for at least 0.5 seconds.

    bound = 0.25;
ell = sigrangebinmask(xenv,bound,fs,MinLength=0.5);

    Load EMGindex into the Workspace. The file contains the motion labels and the start index (sample) of each motion in two variables: motion and start_index.

    When the signal amplitude is above 0.25 for at least 0.5 seconds, the motion label is expected to have a value of 1 or 3. Set all other label values to zero.

    load EMGindex

end_index = [start_index(2:end)-1; size(data,1)];
motionTarget = motion;
motionTarget(~(motion==1 | motion==3)) = 0;

    Create a signal mask using the motion intervals and corresponding labels. Call the plotsigroi function to visualize the labeled categories and compare the two mask results. 

    mskTarget = signalMask(table([start_index,end_index], ...
    string(motionTarget)));

figure
nexttile
plotsigroi(mskTarget,x,true)
nexttile
sigrangebinmask(xenv,bound,MinLength=0.5*fs)

    Figure contains 2 axes objects. Axes object 1 with xlabel Samples contains 17 objects of type line, patch. Axes object 2 with title Signal Regions (MinLength = 1500 Samples), xlabel Samples contains 6 objects of type patch, constantline, line. One or more of the lines displays its values using only markers

    Input Arguments

    collapse all

    Input signal, specified as a vector, matrix, N-D array, or MATLAB® timetable containing numeric data. When x is a matrix or timetable, the function operates on each column separately. When x is an N-D array, the function operates along the first array dimension of size greater than 1.

    If x is a timetable, it must:

    • Contain increasing, uniformly sampled, and finite time values.

    • Have a single variable containing a vector or a matrix, or have multiple variables each containing a vector.

    Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

    Target range, specified as a scalar or a two-column matrix.

    • When bound is a scalar, the function labels signal values in x that are greater than or equal to bound.

    • When bound is a two-column matrix, each row defines a closed interval where the ith row contains nondecreasing indices corresponding to the lower and upper bounds of the ith interval. The function labels signal values in x that are within any of the defined intervals.

    Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

    Sample rate, specified as a positive scalar and expressed in hertz. This argument does not apply when input x is a timetable.

    Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

    Sample time, specified as a duration scalar. This argument does not apply when input x is a timetable.

    Example: seconds(2)

    Data Types: duration

    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.

    Example: sigrangebinmask(x,[–1 1],Relationship="outside",MinLength=20) labels the regions of x where there are at least 20 consecutive sample points whose values are outside the range [–1, 1].

    Target range definition based on input bound, specified as one of these.

    • When bound is a scalar:

      • "above" — Define the range as greater than or equal to bound. If you do not specify this argument, the function uses "above" as the default value.

      • "equal" — Define the range as equal to bound.

      • "below" — Define the range as less than or equal to bound.

    • When bound is a two-column matrix:

      • "inside" — Define the range as within any of the intervals [bound(n,1), bound(n,2)], where n = 1, 2, …, size(bound,1). If you do not specify this argument, the function uses "inside" as the default value.

      • "outside" — Define the range as outside of all the intervals [bound(n,1), bound(n,2), where n = 1 ,2, …, size(bound,1).

    Data Types: char | string

    Interval type, specified as one of these.

    • When bound is a scalar:

      • "closed" — Target range includes the value specified by bound. If you do not specify this argument, the function uses "closed" as the default value.

      • "open" — Target range excludes the value specified by bound.

    • When bound is a two-column matrix:

      • "closed" — All intervals include both the lower and upper bounds specified by bound. If you do not specify this argument, the function uses "closed" as the default value.

      • "open" — All intervals exclude both the lower and upper bounds specified by bound.

      • "openLeft" — All intervals include only the upper bounds specified by bound.

      • "openRight" — All intervals include only the lower bounds specified by bound.

    This argument does not apply when Relationship is set to "equal".

    Data Types: char | string

    Minimum length for signal regions within the target range or intervals, specified as a positive scalar or duration scalar. When you specify fs or ts, or when x is a timetable, MinLength represents the time in seconds. In all other cases, MinLength must be a positive scalar and represents the number of samples.

    Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | duration

    Dimension of x to operate along, specified as a positive integer scalar.

    • If you do not specify this argument, the function operates along the first array dimension of size greater than 1.

    • If input x is a timetable, this argument does not apply and the function operates along the columns of x.

    Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

    Output Arguments

    collapse all

    Binary mask, returned as a logical array with true values indicating signal samples that are within the target range. The size of msk is equal to the size of x.

    References

    [1] Chan, Adrian D.C., and Geoffrey C. Green. "Myoelectric Control Development Toolbox." Paper presented at 30th Conference of the Canadian Medical & Biological Engineering Society, Toronto, Canada, 2007.

    Extended Capabilities

    C/C++ Code Generation
    Generate C and C++ code using MATLAB® Coder™.

    Version History

    Introduced in R2023a

    See Also

    Objects

    Functions