evalRequirement

Class: sdo.requirements.FunctionMatching
Package: sdo.requirements

Evaluate satisfaction of function matching requirement

Syntax

evaluation = evalRequirement(requirement,dependentVar)
evaluation = evalRequirement(requirement,dependentVar,indepVar1,...,indepVarN)


Description

evaluation = evalRequirement(requirement,dependentVar) evaluates whether the test data dependentVar matches the function that is specified in the Type property of the requirement object. The software computes the specified function using default independent variable vectors with value [0 1 2 ...]. There is an independent variable vector corresponding to each dimension of dependentVar, and the length of each independent variable vector is the same as the size of dependentVar in the corresponding dimension.

For example, consider a two-dimensional dependentVar of size 3-by-2. To compute a linear function of the form $$a_0+a_1{X}_1+a_2{X}_2$$, the software uses the independent variable vectors X1 = [0 1 2] and X2 = [0 1]. The software calculates the fit coefficients a0, a1, and a2 and then calculates the error between the test data and the linear function.

evaluation = evalRequirement(requirement,dependentVar,indepVar1,...,indepVarN) specifies the independent variable vectors to use for computing the function.

Input Arguments

requirement — Function matching requirement

sdo.requirements.FunctionMatching object

Function matching requirement, specified as an sdo.requirements.FunctionMatching object. You specify the function to be matched in requirement.Type.

dependentVar — Dependent variable test data to be evaluated

vector | matrix | multidimensional array

Dependent variable test data to be evaluated, specified as a vector, matrix, or multidimensional array.

indepVar1,...,indepVarN — Independent variable vectors

vectors

Independent variable vectors used for computing the function, specified as real, numeric, monotonic vectors. The independent variable vectors must satisfy the following characteristics:

• The number of independent variables N must equal the number of dimensions of the test data.

  For example, use two independent variables when the test data dependentVar is a matrix, and use three independent variables when the test data is a three-dimensional array.

• The first independent variable vector specifies coordinates going down test data rows, and the second independent variable vector specifies coordinates going across test data columns. The N^th independent variable vector specifies coordinates along the N^th dimension of dependentVar.

• The number of elements in each independent variable vector must match the size of test data in the corresponding dimension.

• The independent variable vectors must be monotonically increasing or decreasing.

In the requirement object, you can specify centering and scaling of the independent variables using the Centers and Scales properties. The independent variable vectors specified by you are divided by these Scales values after subtracting the Centers values. For more information, see the property descriptions on the sdo.requirements.FunctionMatching reference page.

You can also specify independent variable vectors using a cell array. The number of elements in the cell array must match the number of dimensions in the test data, dependentVar. For example, suppose that dependentVar is two-dimensional, you can use either of the following syntaxes:

evaluation = evalRequirement(requirement,dependentVar,independentVar1,independentVar2);
evaluation = evalRequirement(requirement,dependentVar,{independentVar1,independentVar2});

Output Arguments

evaluation — Evaluation of the function matching requirement

scalar | vector | matrix | multidimensional array

Evaluation of the function matching requirement, returned as a scalar, vector, matrix, or array, depending on the value of requirement.Method.

evalRequirement computes an error signal that is the difference between test data and the specified function of the independent variables. The error signal is then processed further to compute evaluation. The value of evaluation depends on the error processing method specified in requirement.Method.

requirement.Method	evaluation
'SSE'	evaluation is returned as a scalar value equal to the sum of squares of the errors. A positive value indicates that the requirement is violated, and 0 value indicates that the requirement is satisfied. The closer evaluation is to 0, the better the match between the function and test data.
'SAE'	evaluation is returned as a scalar value equal to the sum of absolute values of the errors. A positive value indicates that the requirement is violated, and 0 value indicates that the requirement is satisfied. The closer evaluation is to 0, the better the match between the function and test data.
'Residuals'	evaluation is returned as a vector, matrix, or array of the same size as the test data dependentVar. evaluation contains the difference between the test data and the specified function of the independent variables.

Examples

Evaluate Function Matching Requirement for One-Dimensional Variable

Create a requirement object to match one-dimensional variable data to a linear function.

Requirement = sdo.requirements.FunctionMatching;

Specify the Centers and Scales properties for a one-dimensional variable by using the set command. You specify these properties because their default values are for a two-dimensional variable.

set(Requirement,'Centers',0,'Scales',1);

Specify test data for the one-dimensional variable.

dependentVariable = 0.5+5.*(1:5);

Evaluate the requirement.

evaluation = evalRequirement(Requirement,dependentVariable)

evaluation = 5.6798e-30

The software computes the linear function using the default independent variable vector [0 1 2 3 4] because you did not specify any independent variable vectors. There is one independent variable because the number of independent variables must equal the number of dimensions of the test data. The size of the independent variable vector equals the size of the test data.

In this example, the processing method has the default value of 'SSE', so evaluation is returned as a scalar value equal to the sum of squares of the errors. evaluation is very close to zero, indicating that the dependentVariable test data almost matches a linear function. Note that machine precision can affect the value of evaluation at such small values.

Match Quadratic Function to Two-Dimensional Variable Data

Create a requirement object, and specify the function to be matched.

Requirement = sdo.requirements.FunctionMatching('Type','purequadratic');

The object specifies that the variables should match a quadratic function with no cross-terms.

Create 2-dimensional test data for the variable.

[X1,X2] = ndgrid((-1:1),(-4:2:4));
dependentVar = X1.^2 + X2.^2;

Specify independent variable vectors to compute the quadratic function.

The number of independent variable vectors must equal the dimensionality of the test data. In addition, the independent variable vectors must be monotonic and have the same size as the test data in the corresponding dimension.

indepVar1 = (-2:0);
indepVar2 = (-6:2:2);

Evaluate if the test data satisfies the requirement.

evaluation = evalRequirement(Requirement,dependentVar,indepVar1,indepVar2)

evaluation = 6.3950e-29

The evalRequirement command computes an error signal that is the difference between test data and the function of the independent variable vectors. The error signal is further processed to compute evaluation, based on the error processing method specified in Requirement.Method.

In this example, the processing method has the default value of 'SSE', so evaluation is returned as a scalar value equal to the sum of squares of the errors. evaluation is very close to zero, indicating that the dependentVariable test data almost matches a pure quadratic function.

Create test data with cross-terms.

dependentVariable2 = X1.^2 + X2.^2 + X1.*X2;

Evaluate the requirement for the new test data.

evaluation2 = evalRequirement(Requirement,dependentVariable2,indepVar1,indepVar2)

evaluation2 = 5.3333

The output evaluation2 is greater than evaluation and is substantially different from 0, indicating that dependentVariable2 does not fit a pure-quadratic function as well as dependentVariable fits the function.

Version History

Introduced in R2016b