Main Content

plotPermutationResults

Plot histogram of permutation results for a variable

    Description

    example

    plotPermutationResults(DDiagnostics) plots the histogram of metric values driftdetect computes during permutation testing for the variable with the lowest p-value.

    If you set the value of 'EstimatePValues' to false in the call to detectdrift, then plotPermutationResults does not generate a plot and returns a warning.

    example

    plotPermutationResults(DDiagnostics,Variable=variable) plots the histogram for the variable specified by variable.

    example

    plotPermutationResults(ax,___) plots into axes ax instead of gca.

    H = plotPermutationResults(___) plots the histogram and returns an array of Histogram objects, in H. Use this to inspect and adjust the properties of the histogram. For more information on the Histogram object properties, see Histogram Properties.

    example

    [H,CL] = plotPermutationResults(___) plots the histogram and returns two arrays of graphics objects, H and CL.

    H is an array of Histogram objects and CL is a ConstantLine object. Use CL to inspect and adjust the properties of the line. For more information on the ConstantLine object properties, see ConstantLine Properties.

    Examples

    collapse all

    Generate baseline and target data with three variables, where the distribution parameters of the second and third variables change for target data.

    rng('default') % For reproducibility
    baseline = [normrnd(0,1,100,1),wblrnd(1.1,1,100,1),betarnd(1,2,100,1)];
    target = [normrnd(0,1,100,1),wblrnd(1.2,2,100,1),betarnd(1.7,2.8,100,1)];

    Perform permutation testing for all variables to check for any drift between the baseline and target data.

    DDiagnostics = detectdrift(baseline,target)
    DDiagnostics = 
      DriftDiagnostics
    
                  VariableNames: ["x1"    "x2"    "x3"]
           CategoricalVariables: []
                    DriftStatus: ["Stable"    "Drift"    "Warning"]
                        PValues: [0.3850 0.0050 0.0910]
            ConfidenceIntervals: [2x3 double]
        MultipleTestDriftStatus: "Drift"
                 DriftThreshold: 0.0500
               WarningThreshold: 0.1000
    
    
      Properties, Methods
    
    

    Plot the permutation results for the default variable.

    plotPermutationResults(DDiagnostics)

    Figure contains an axes object. The axes object with title Permutation Results for x2 contains 3 objects of type histogram, constantline. These objects represent $<$ 0.34676, $\geq$ 0.34676.

    plotPermutationResults by default plots a histogram of the metric values computed in permutation testing for the variable with the lowest p-value, which, in this case, is x2. It marks the metric threshold value (the initial metric value detectdrift computes using the baseline and target data as they are provided) on the histogram, so you can see the amount that is greater than or equal to that value. plotPermutationResults also displays the p-value and the drift status for that variable, and the metric that you specify to use for permutation testing in the call to detectdrift. In this example, no metric is specified, so detectdrift uses the default metric (Wasserstein) for continuous variables.

    Generate baseline and target data with three variables, where the distribution parameters of the second and third variables change for target data.

    rng('default') % For reproducibility
    baseline = [normrnd(0,1,100,1),wblrnd(1.1,1,100,1),betarnd(1,2,100,1)];
    target = [normrnd(0,1,100,1),wblrnd(1.2,2,100,1),betarnd(1.7,2.8,100,1)];

    Perform permutation testing for all variables to check for any drift between the baseline and target data. Use the Energy metric for all variables.

    DDiagnostics = detectdrift(baseline,target,"ContinuousMetric","energy")
    DDiagnostics = 
      DriftDiagnostics
    
                  VariableNames: ["x1"    "x2"    "x3"]
           CategoricalVariables: []
                    DriftStatus: ["Stable"    "Drift"    "Warning"]
                        PValues: [0.3790 0.0110 0.0820]
            ConfidenceIntervals: [2x3 double]
        MultipleTestDriftStatus: "Drift"
                 DriftThreshold: 0.0500
               WarningThreshold: 0.1000
    
    
      Properties, Methods
    
    

    Display the 95% confidence bounds for the p-values.

    DDiagnostics.ConfidenceIntervals
    ans = 2×3
    
        0.3488    0.0055    0.0657
        0.4099    0.0196    0.1008
    
    

    Plot the permutation results for the third variable.

    plotPermutationResults(DDiagnostics,Variable=3)

    Figure contains an axes object. The axes object with title Permutation Results for x3 contains 3 objects of type histogram, constantline. These objects represent $<$ 0.10117, $\geq$ 0.10117.

    Generate baseline and target data with three variables, where the distribution parameters of the second and third variables change for target data.

    rng('default') % For reproducibility
    baseline = [normrnd(0,1,100,1),wblrnd(1.1,1,100,1),betarnd(1,2,100,1)];
    target = [normrnd(0,1,100,1),wblrnd(1.2,2,100,1),betarnd(1.7,2.8,100,1)];

    Perform permutation testing for all variables to check for any drift between the baseline and target data. Use the Energy metric for all variables.

    DDiagnostics = detectdrift(baseline,target,"ContinuousMetric","energy")
    DDiagnostics = 
      DriftDiagnostics
    
                  VariableNames: ["x1"    "x2"    "x3"]
           CategoricalVariables: []
                    DriftStatus: ["Stable"    "Drift"    "Warning"]
                        PValues: [0.3790 0.0110 0.0820]
            ConfidenceIntervals: [2x3 double]
        MultipleTestDriftStatus: "Drift"
                 DriftThreshold: 0.0500
               WarningThreshold: 0.1000
    
    
      Properties, Methods
    
    

    Plot the permutation results for variables x1 versus x2 in a tiled layout.

    tiledlayout(2,1);
    ax1 = nexttile;
    plotPermutationResults(DDiagnostics,ax1,Variable="x1")
    ax2 = nexttile;
    plotPermutationResults(DDiagnostics,ax2,Variable="x2")

    Figure contains 2 axes objects. Axes object 1 with title Permutation Results for x1 contains 3 objects of type histogram, constantline. These objects represent $<$ 0.15234, $\geq$ 0.15234. Axes object 2 with title Permutation Results for x2 contains 3 objects of type histogram, constantline. These objects represent $<$ 0.28619, $\geq$ 0.28619.

    Plot the permutation results for variables x1 versus x3 in a tiled layout.

    tiledlayout(2,1);
    ax1 = nexttile;
    plotPermutationResults(DDiagnostics,ax1,Variable="x1")
    ax3= nexttile;
    plotPermutationResults(DDiagnostics,ax3,Variable="x3")

    Figure contains 2 axes objects. Axes object 1 with title Permutation Results for x1 contains 3 objects of type histogram, constantline. These objects represent $<$ 0.15234, $\geq$ 0.15234. Axes object 2 with title Permutation Results for x3 contains 3 objects of type histogram, constantline. These objects represent $<$ 0.10117, $\geq$ 0.10117.

    Generate baseline and target data with three variables, where the distribution parameters of the second and third variables change for target data.

    rng('default') % For reproducibility
    baseline = [normrnd(0,1,100,1),wblrnd(1.1,1,100,1),betarnd(1,2,100,1)];
    target = [normrnd(0,1,100,1),wblrnd(1.2,2,100,1),betarnd(1.7,2.8,100,1)];

    Perform permutation testing for all variables to check for any drift between the baseline and target data. Use the Energy distance as the metric.

    DDiagnostics = detectdrift(baseline,target,"ContinuousMetric","energy")
    DDiagnostics = 
      DriftDiagnostics
    
                  VariableNames: ["x1"    "x2"    "x3"]
           CategoricalVariables: []
                    DriftStatus: ["Stable"    "Drift"    "Warning"]
                        PValues: [0.3790 0.0110 0.0820]
            ConfidenceIntervals: [2x3 double]
        MultipleTestDriftStatus: "Drift"
                 DriftThreshold: 0.0500
               WarningThreshold: 0.1000
    
    
      Properties, Methods
    
    

    Plot the permutation results for the third variable.

    [H,CL] = plotPermutationResults(DDiagnostics,Variable=3)

    Figure contains an axes object. The axes object with title Permutation Results for x3 contains 3 objects of type histogram, constantline. These objects represent $<$ 0.10117, $\geq$ 0.10117.

    H = 
      2x1 Histogram array:
    
      Histogram
      Histogram
    
    
    CL = 
      ConstantLine with properties:
    
        InterceptAxis: 'x'
                Value: 0.1012
                Color: [0.1500 0.1500 0.1500]
            LineStyle: ':'
            LineWidth: 3
                Label: ''
          DisplayName: ''
    
      Show all properties
    
    

    Change the histogram bar colors to blue and the threshold line color to red.

    H(1).FaceColor = "b";
    CL.Color = "r";

    Figure contains an axes object. The axes object with title Permutation Results for x3 contains 3 objects of type histogram, constantline. These objects represent $<$ 0.10117, $\geq$ 0.10117.

    You can also access other properties by double-clicking on H or CL in the Workspace and adjust them using the Property Inspector.

    Input Arguments

    collapse all

    Diagnostics of the permutation testing for drift detection, specified as a DriftDiagnostics object returned by detectdrift.

    Variable for which to plot the permutation results, specified as a string, a character vector, or an integer index.

    Example: Variable="x2"

    Example: Variable=2

    Data Types: single | double | char | string

    Axes for plotHistogram to plot into, specified as an Axes or UIAxes object. If you do not specify ax, then plotHistogram creates the plot using the current axes. For more information on creating an axes object, see axes and uiaxes.

    Output Arguments

    collapse all

    Histogram of metric values computed during permutation testing, returned as a 2-by-1 array of Histogram objects. Use H to inspect and adjust the properties of the histogram. For more information on the Histogram object properties, see Histogram Properties.

    Line showing the metric threshold value, returned as a ConstantLine object. Use CL to inspect and adjust the properties of the error bars.

    Version History

    Introduced in R2022a