# sigrangebinmask

## Syntax

## Description

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.`msk`

= sigrangebinmask(___,`Name=Value`

)

`sigrangebinmask(___)`

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

## Examples

### Label Signal Values Within Target Range

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)

### Label Consecutive Samples Within Specified Range in Timetable

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)")
```

### Label High-Amplitude Regions in EMG Signal

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

## Input Arguments

`x`

— Input signal

vector | matrix | *N*-D array | timetable

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`

`bound`

— Target range

scalar | two-column matrix

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*i*th row contains nondecreasing indices corresponding to the lower and upper bounds of the*i*th 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`

`fs`

— Sample rate

positive scalar

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`

### 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].

`Relationship`

— Target range definition

`"above"`

| `"equal"`

| `"below"`

| `"inside"`

| `"outside"`

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`

`IntervalType`

— Interval type

`"closed"`

(default) | `"open"`

| `"openLeft"`

| `"openRight"`

Interval type, specified as one of these.

When

`bound`

is a scalar:`"open"`

— Target range includes the value specified by`bound`

.`"closed"`

— Target range excludes the value specified by`bound`

. If you do not specify this argument, the function uses`"closed"`

as the default value.

When

`bound`

is a two-column matrix:`"open"`

— All intervals include both the lower and upper bounds specified by`bound`

.`"closed"`

— All interval exclude both the lower and upper bounds specified by`bound`

. If you do not specify this argument, the function uses`"closed"`

as the default value.`"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`

`MinLength`

— Minimum length

positive scalar | `duration`

scalar

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`

— Dimension

positive integer scalar

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

`msk`

— Binary mask

logical array

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™.

### GPU Arrays

Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

This function fully supports GPU arrays. For more information, see Run MATLAB Functions on a GPU (Parallel Computing Toolbox).

## Version History

**Introduced in R2023a**

## Open Example

You have a modified version of this example. Do you want to open this example with your edits?

## MATLAB Command

You clicked a link that corresponds to this MATLAB command:

Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.

Select a Web Site

Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .

You can also select a web site from the following list:

## How to Get Best Site Performance

Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.

### Americas

- América Latina (Español)
- Canada (English)
- United States (English)

### Europe

- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)

- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)