Main Content

calibrate

Train i-vector system calibrator

Since R2022a

collapse all in page

    Syntax

    calibrate(ivs,data,labels)
    calibrate(ivs,data,labels,Name=Value)

    Description

    calibrate(ivs,data,labels) calibrates scores output from by i-vector system ivs. The calibration scheme is determined using the calibration data and associated labels. A properly calibrated system outputs scores that can be interpreted as confidence in a positive decision.

    example

    calibrate(ivs,data,labels,Name=Value) specifies additional options using name-value arguments. You can choose the hardware resource to extract i-vectors and whether to use prefetch queuing when reading from a datastore.

    Examples

    collapse all

    Open Live Script

    Download and unzip the air compressor data set [1]. This data set consists of recordings from air compressors in a healthy state or one of seven faulty states.

    loc = matlab.internal.examples.downloadSupportFile("audio", ...
    "AirCompressorDataset/AirCompressorDataset.zip");
unzip(loc,pwd)

    Create an audioDatastore object to manage the data and split it into training and validation sets.

    ads = audioDatastore(pwd,IncludeSubfolders=true,LabelSource="foldernames");

[adsTrain,adsTest] = splitEachLabel(ads,0.8,0.2);

    Read an audio file from the datastore and save the sample rate. Listen to the audio signal and plot the signal in the time domain.

    [x,fileInfo] = read(adsTrain);
fs = fileInfo.SampleRate;

sound(x,fs)

t = (0:size(x,1)-1)/fs;
plot(t,x)
xlabel("Time (s)")
title("State = " + string(fileInfo.Label))
axis tight

    Create an i-vector system with DetectSpeech set to false. Turn off the verbose behavior.

    faultRecognizer = ivectorSystem(SampleRate=fs,DetectSpeech=false, ...
    Verbose=false)
    faultRecognizer = 
  ivectorSystem with properties:

         InputType: 'audio'
        SampleRate: 16000
      DetectSpeech: 0
           Verbose: 0
    EnrolledLabels: [0×2 table]

    Train the i-vector extractor and the i-vector classifier using the training datastore.

    trainExtractor(faultRecognizer,adsTrain, ...
    UBMNumComponents=80, ...
    UBMNumIterations=3, ...
    ...
    TVSRank=40, ...
    TVSNumIterations=3)

trainClassifier(faultRecognizer,adsTrain,adsTrain.Labels, ...
    NumEigenvectors=7, ...
    ...
    PLDANumDimensions=32, ...
    PLDANumIterations=5)

    Calibrate the scores output by faultRecognizer so they can be interpreted as a measure of confidence in a positive decision. Turn the verbose behavior back on. Enroll all of the labels from the training set.

    calibrate(faultRecognizer,adsTrain,adsTrain.Labels)

faultRecognizer.Verbose = true;

enroll(faultRecognizer,adsTrain,adsTrain.Labels)
    Extracting i-vectors ...done.
Enrolling i-vectors ...........done.
Enrollment complete.

    Use the read-only property EnrolledLabels to view the enrolled labels and the corresponding i-vector templates.

    faultRecognizer.EnrolledLabels
    ans=8×2 table
                   ivector       NumSamples
                 ____________    __________

    Bearing      {7×1 double}       180    
    Flywheel     {7×1 double}       180    
    Healthy      {7×1 double}       180    
    LIV          {7×1 double}       180    
    LOV          {7×1 double}       180    
    NRV          {7×1 double}       180    
    Piston       {7×1 double}       180    
    Riderbelt    {7×1 double}       180

    Use the identify function with the PLDA scorer to predict the condition of machines in the test set. The identify function returns a table of possible labels sorted in descending order of confidence.

    [audioIn,audioInfo] = read(adsTest);
trueLabel = audioInfo.Label
    trueLabel = categorical
     Bearing 


    predictedLabels = identify(faultRecognizer,audioIn,"plda")
    predictedLabels=8×2 table
      Label        Score   
    _________    __________

    Bearing         0.99997
    Flywheel      2.265e-05
    Piston       8.6076e-08
    LIV          1.4237e-15
    NRV          4.5529e-16
    Riderbelt    3.7359e-16
    LOV          6.3025e-19
    Healthy      4.2094e-30

    By default, the identify function returns all possible candidate labels and their corresponding scores. Use NumCandidates to reduce the number of candidates returned.

    results = identify(faultRecognizer,audioIn,"plda",NumCandidates=3)
    results=3×2 table
     Label        Score   
    ________    __________

    Bearing        0.99997
    Flywheel     2.265e-05
    Piston      8.6076e-08

    References

    [1] Verma, Nishchal K., et al. “Intelligent Condition Based Monitoring Using Acoustic Signals for Air Compressors.” IEEE Transactions on Reliability, vol. 65, no. 1, Mar. 2016, pp. 291–309. DOI.org (Crossref), doi:10.1109/TR.2015.2459684.

    Input Arguments

    collapse all

    i-vector system, specified as an object of type ivectorSystem.

    Training data for an i-vector system, specified as a cell array or as an audioDatastore, signalDatastore, or TransformedDatastore object.

    • If InputType is set to "audio" when the i-vector system is created, specify data as one of these:

      • A cell array of single-channel audio signals, each specified as a column vector with underlying type single or double.

      • An audioDatastore object or a signalDatastore object that points to a data set of mono audio signals.

      • A TransformedDatastore with an underlying audioDatastore or signalDatastore that points to a data set of mono audio signals. The output from calls to read from the transform datastore must be mono audio signals with underlying data type single or double.

    • If InputType is set to "features" when the i-vector system is created, specify data as one of these:

      The feature matrices must consist of audio features with underlying type single or double where the number of features (columns) is locked the first time trainExtractor is called and the number of hops (rows) is variable-sized. The number of features input in any subsequent calls to any of the object functions must be equal to the number of features used when calling trainExtractor.

    Data Types: cell | audioDatastore | signalDatastore

    Classification labels used by the i-vector system, specified as one of the following:

    • A categorical array

    • A cell array of character vectors

    • A string array

    Note

    The number of audio signals in data must match the number of labels.

    Data Types: categorical | cell | string

    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.

    Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

    Example: calibrate(ivs,data,labels,DispatchInBackground=true)

    Hardware resource for execution, specified as one of these:

    • "auto" — Use the GPU if it is available. Otherwise, use the CPU.

    • "cpu" — Use the CPU.

    • "gpu" — Use the GPU. This option requires Parallel Computing Toolbox™.

    • "multi-gpu" — Use multiple GPUs on one machine, using a local parallel pool based on your default cluster profile. If there is no current parallel pool, the software starts a parallel pool with pool size equal to the number of available GPUs. This option requires Parallel Computing Toolbox.

    • "parallel" — Use a local or remote parallel pool based on your default cluster profile. If there is no current parallel pool, the software starts one using the default cluster profile. If the pool has access to GPUs, then only workers with a unique GPU perform training computation. If the pool does not have GPUs, then the training takes place on all available CPU workers. This option requires Parallel Computing Toolbox.

    Data Types: char | string

    Option to use prefetch queuing when reading from a datastore, specified as a logical value. This argument requires Parallel Computing Toolbox.

    Data Types: logical

    Version History

    Introduced in R2022a

    See Also

    | | | | | | | | | | | |