Documentation Center

  • Trial Software
  • Product Updates

sdo.requirements.SignalTracking class

Package: sdo.requirements

Reference signal to track

Description

Specify a tracking requirement on a time-domain signal. You can then optimize the model response to track the reference using sdo.optimize.

You can specify an equality, upper or lower bound requirement.

Construction

track_req = sdo.requirements.SignalTracking creates an sdo.requirements.SignalTracking object and assigns default values to its properties.

track_req = sdo.requirements.SignalTracking(Name,Value) uses additional options specified by one or more Name,Value pair arguments. Name is a property name and Value is the corresponding value. Name must appear inside single quotes (''). You can specify several name-value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Input Arguments

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside single quotes (' '). You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

'AbsTol'

Absolute tolerance used to determine bounds as the signal approaches the reference signal. The bounds on the reference signal are given by:

yu = (1 + RelTol)yr + AbsTol

yl = (1 –RelTol)yrAbsTol

where yr is the value of the reference at a certain time, yu and yl are the upper and lower tolerance bounds corresponding to that time point.

Default: 0

'Description'

Requirement description. Must be a string.

Default: ''

'InterpolationTimes'

Time points to use when comparing reference and testpoint signals. Linear interpolation is used to compare the signals at the same timepoints.

Must be one of the following strings:

  • 'Reference only' — Compare the signals at the time points of the reference signal only

  • 'Testpoint only' — Compare the signals at the time points of the testpoint signal only

  • 'Reference and Testpoint' — Compare the signals at the time points of both the reference and testpoint signals

Default: 'Reference only'

'Method'

Algorithm for evaluating the requirement when the Type property is '=='.

When the requirement is evaluated using evalRequirement, the software computes the error between the reference and testpoint signals. This property specifies how the error signal e(t) = ys(t)–yr(t) should be processed.

Must be one of the following strings:

  • 'SSE'

  • 'SAE'

  • 'Residuals'

Default: 'SSE'

'Name'

Requirement name. Must be a string.

Default: ''

'Normalize'

Enable or disable normalization when evaluating the requirement. The maximum absolute value of the reference signal is used for normalization. Must be 'on' or 'off'.

Default: 'on'

'ReferenceSignal'

Reference signal to track. Must be a MATLAB® timeseries object with real finite data points.

Default: [1x1 timeseries]

'RelTol'

Relative tolerance used to determine bounds as the signal approaches the reference signal. The bounds on the reference signal are given by:

yu = (1 + RelTol)yr + AbsTol

yl = (1 — RelTol)yrAbsTol

Default: 0

'RobustCost'

Enable or disable robust treatment of outliers when evaluating the requirement. The software uses a Huber loss function to handle the outliers in the cost function and improves the fit quality. This option reduces the influence of outliers on the estimation without you manually modifying your data.

Must be one of the following:

  • 'on' — When you call the evalRequirement method, the software uses a Huber loss function to evaluate the cost for the tracking error outliers. The tracking error is calculated as e(t)=yref(t)-ytest(t). The software uses the error statistics to identify the outliers.

    The exact cost function used, F(x), depends on the requirement evaluation Method.

    Method NameCost Function for NonoutliersCost Function for Outliers
    'SSE'

    NOL is the set of nonoutlier samples.

    w is a linear weight. OL is the set of outlier samples.

    'SAE'

    NOL is the set of nonoutlier samples.

    w is a constant value. OL is the set of outlier samples.

    'Residuals'

    The software does not remove the outliers.

    N is the number of samples.

  • 'off'

Default: 'off'

'Type'

Tracking requirement type. Must be one of the following strings:

  • '==' — Tracking objective.

    '<=' — Upper bound

  • '>=' — Lower bound

Default: '=='

'Weights'

Weights to use when evaluating the tracking error between the reference and testpoint signals. Use weights to increase or decrease the significance of different time points.

Must be real finite positive vector with the same number of elements as the Time property of the MATLAB timeseries object in the ReferenceSignal property.

Properties

AbsTol

Absolute tolerance used to determine bounds as the signal approaches the reference signal. The bounds on the reference signal are given by:

yu = (1 + RelTol)yr + AbsTol

yl = (1 –RelTol)yrAbsTol

where yr is the value of the reference at a certain time, yu and yl are the upper and lower tolerance bounds corresponding to that time point.

Default: 0

Description

Requirement description. Must be a string.

Default: ''

InterpolationTimes

Time points to use when comparing reference and testpoint signals. Linear interpolation is used to compare the signals at the same timepoints.

Must be one of the following strings:

  • 'Reference only' — Compare the signals at the time points of the reference signal only

  • 'Testpoint only' — Compare the signals at the time points of the testpoint signal only

  • 'Reference and Testpoint' — Compare the signals at the time points of both the reference and testpoint signals

Default: 'Reference only'

Method

Algorithm for evaluating the requirement when the Type property is '=='.

When the requirement is evaluated using evalRequirement, the software computes the error between the reference and testpoint signals. This property specifies how the error signal e(t) = ys(t)–yr(t) should be processed.

Must be one of the following strings:

  • 'SSE'

  • 'SAE'

  • 'Residuals'

Default: 'SSE'

Name

Requirement name. Must be a string.

Default: ''

Normalize

Enable or disable normalization when evaluating the requirement. The maximum absolute value of the reference signal is used for normalization. Must be 'on' or 'off'.

Default: 'on'

ReferenceSignal

Reference signal to track. Must be a MATLAB timeseries object with real finite data points.

Default: [1x1 timeseries]

RelTol

Relative tolerance used to determine bounds as the signal approaches the reference signal. The bounds on the reference signal are given by:

yu = (1 + RelTol)yr + AbsTol

yl = (1 — RelTol)yrAbsTol

Default: 0

RobustCost

Enable or disable robust treatment of outliers when evaluating the requirement. The software uses a Huber loss function to handle the outliers in the cost function and improves the fit quality. This option reduces the influence of outliers on the estimation without you manually modifying your data.

Must be one of the following:

  • 'on' — When you call the evalRequirement method, the software uses a Huber loss function to evaluate the cost for the tracking error outliers. The tracking error is calculated as e(t)=yref(t)-ytest(t). The software uses the error statistics to identify the outliers.

    The exact cost function used, F(x), depends on the requirement evaluation Method.

    Method NameCost Function for NonoutliersCost Function for Outliers
    'SSE'

    NOL is the set of nonoutlier samples.

    w is a linear weight. OL is the set of outlier samples.

    'SAE'

    NOL is the set of nonoutlier samples.

    w is a constant value. OL is the set of outlier samples.

    'Residuals'

    The software does not remove the outliers.

    N is the number of samples.

  • 'off'

Default: 'off'

Type

Tracking requirement type. Must be one of the following strings:

  • '==' — Tracking objective.

    '<=' — Upper bound

  • '>=' — Lower bound

Default: '=='

Weights

Weights to use when evaluating the tracking error between the reference and testpoint signals. Use weights to increase or decrease the significance of different time points.

Must be real finite positive vector with the same number of elements as the Time property of the MATLAB timeseries object in the ReferenceSignal property.

Methods

evalRequirementEvaluate tracking requirement

Copy Semantics

Handle. To learn how handle classes affect copy operations, see Copying Objects in the MATLAB documentation.

Examples

Construct a signal tracking object and specify a reference signal.

r = sdo.requirements.SignalTracking;
r.ReferenceSignal = timeseries(1-exp(-(0:10)'));

Alternatively, you can specify the reference signal during construction.

r = sdo.requirements.SignalTracking(...
        'ReferenceSignal',timeseries(1-exp(-(0:10)')));

Alternatives

Use getbounds to get the bounds specified in a Check Against Reference block.

See Also

| |

How To

Was this topic helpful?