Main Content

matlab.unittest.constraints.Tolerance Class

Namespace: matlab.unittest.constraints

Fundamental interface for tolerances

expand all in page

Description

The matlab.unittest.constraints.Tolerance class provides an interface for tolerances. Tolerances define a notion of approximate equality for given data types and can be applied to the IsEqualTo constraint as well as certain comparators using the Within name-value argument.

The class has three abstract methods. To create a custom tolerance class, derive your class from matlab.unittest.constraints.Tolerance and implement all the abstract methods.

Class Attributes

Abstract
true

For information on class attributes, see Class Attributes.

Methods

expand all

Examples

collapse all

Open Script

Determine if two DNA sequences have a Hamming distance within a specified tolerance. For two DNA sequences of the same length, the Hamming distance is the number of positions in which the nucleotides (letters) of one sequence differ from the other.

Create DNA Class

To represent DNA sequences, create the DNA class in a file named DNA.m in your current folder.

classdef DNA
    properties (SetAccess=immutable)
        Sequence char {mustHaveValidLetters}
    end

    methods
        function dna = DNA(sequence)
            dna.Sequence = sequence;
        end
    end
end

function mustHaveValidLetters(sequence)
validLetters = ...
    sequence == 'A' | ...
    sequence == 'C' | ...
    sequence == 'T' | ...
    sequence == 'G';

if ~all(validLetters,"all")
    error("Sequence contains one or more invalid letters.")
end
end

Create HammingDistance Class

In a file named HammingDistance.m in your current folder, create the HammingDistance class by subclassing matlab.unittest.constraints.Tolerance. Add a property Value so that you can specify the maximum allowable Hamming distance.

Classes that derive from the Tolerance class must implement the supports, satisfiedBy, and getDiagnosticFor methods:

  • supports method — Specify that the tolerance must support objects of the DNA class.

  • satisfiedBy method — Specify that for the actual and expected values to be within the tolerance, they must be the same size and their Hamming distance must be less than or equal to the tolerance value.

  • getDiagosticFor method — Create and return a StringDiagnostic object that contains diagnostic information about the comparison.

classdef HammingDistance < matlab.unittest.constraints.Tolerance
    properties
        Value
    end

    methods
        function tolerance = HammingDistance(value)
            tolerance.Value = value;
        end

        function tf = supports(~,expected)
            tf = isa(expected,"DNA");
        end

        function tf = satisfiedBy(tolerance,actual,expected)
            if ~isSameSize(actual.Sequence,expected.Sequence)
                tf = false;
                return
            end
            tf = hammingDistance(actual.Sequence,expected.Sequence) <= ...
                tolerance.Value;
        end

        function diagnostic = getDiagnosticFor(tolerance,actual,expected)
            import matlab.automation.diagnostics.StringDiagnostic
            if ~isSameSize(actual.Sequence,expected.Sequence)
                str = "The DNA sequences have different lengths.";
            else
                str = "The DNA sequences have a Hamming distance of " ...
                    + hammingDistance(actual.Sequence,expected.Sequence) ...
                    + "." + newline + "The allowable distance is " ...
                    + tolerance.Value + ".";
            end
            diagnostic = StringDiagnostic(str);
        end
    end
end

function tf = isSameSize(str1,str2)
tf = isequal(size(str1),size(str2));
end

function distance = hammingDistance(str1,str2)
distance = nnz(str1 ~= str2);
end

Compare DNA Sequences

To compare DNA sequences using a tolerance, first import the necessary classes and create a test case for interactive testing.

import matlab.unittest.TestCase
import matlab.unittest.constraints.IsEqualTo
testCase = TestCase.forInteractiveUse;

Create two DNA objects and compare them without specifying a tolerance. The test fails because the objects are not equal.

sampleA = DNA("ACCTGAGTA");
sampleB = DNA("ACCACAGTA");
testCase.verifyThat(sampleA,IsEqualTo(sampleB))

Verification failed.
    ---------------------
    Framework Diagnostic:
    ---------------------
    IsEqualTo failed.
    --> ObjectComparator failed.
        --> The objects are not equal using "isequaln".
        
        Actual Value:
          DNA with properties:
        
            Sequence: 'ACCTGAGTA'
        Expected Value:
          DNA with properties:
        
            Sequence: 'ACCACAGTA'
    ------------------
    Stack Information:
    ------------------
    In C:\work\CreateCustomToleranceExample.m (CreateCustomToleranceExample) at 45

Verify that the DNA sequences are equal within a Hamming distance of 1. The test fails and the testing framework displays additional diagnostic information produced by the getDiagnosticFor method.

testCase.verifyThat(sampleA,IsEqualTo(sampleB,"Within",HammingDistance(1)))

Verification failed.
    ---------------------
    Framework Diagnostic:
    ---------------------
    IsEqualTo failed.
    --> ObjectComparator failed.
        --> The objects are not equal using "isequaln".
        --> The DNA sequences have a Hamming distance of 2.
            The allowable distance is 1.
        
        Actual Value:
          DNA with properties:
        
            Sequence: 'ACCTGAGTA'
        Expected Value:
          DNA with properties:
        
            Sequence: 'ACCACAGTA'
    ------------------
    Stack Information:
    ------------------
    In C:\work\CreateCustomToleranceExample.m (CreateCustomToleranceExample) at 51

Verify that the DNA sequences are equal within a Hamming distance of 2. The test passes.

testCase.verifyThat(sampleA,IsEqualTo(sampleB,"Within",HammingDistance(2)))

Verification passed.

Version History

Introduced in R2013a

See Also

| |