plotParameterStats

Show box plot, violin plot, and swarm scatter plots for parameter estimates

Since R2026a

collapse all in page

Syntax

plotParameterStats(fitResults,plotStyle1)
plotParameterStats(fitResults,plotStyle1,...,plotStyleN)

Description

plotParameterStats(fitResults,plotStyle1) generates a box plot, violin plot, or swarm scatter plot of the parameter estimates in fitResults.

example

plotParameterStats(fitResults,plotStyle1,...,plotStyleN) specifies to generate multiple plots, where 1≤ N ≤ 3. For example, plotParameterStats(fitResults,"box","violin","swarm") plots all three available plots.

example

Examples

collapse all

Open Live Script

This example uses data collected on 59 preterm infants given phenobarbital during the first 16 days after birth [1]. Each infant received an initial dose followed by one or more sustaining doses by intravenous bolus administration. A total of between 1 and 6 concentration measurements were obtained from each infant at times other than dose times, for a total of 155 measurements. Infant weights and APGAR scores (a measure of newborn health) were also recorded.

Load the data. 

load pheno.mat ds

Convert the dataset to a groupedData object, a container for holding tabular data that is divided into groups.

data = groupedData(ds);

Create a simple one-compartment PK model with bolus dosing and linear clearance to fit such data. Use the PKModelDesign object to construct the model.

pkmd = PKModelDesign;
addCompartment(pkmd,"Central",DosingType="Bolus",...
                    EliminationType="linear-clearance",...
                    HasResponseVariable=true,HasLag=false);
[onecomp,map] = pkmd.construct;

Describe the experimentally measured response by mapping the appropriate model component to the response variable.

map.Observed
ans = 1×1 cell array
    {'Drug_Central'}

Map the Drug_Central species to the CONC variable. 

responseMap = "Drug_Central = CONC";

The parameters to estimate in this model are the volume of the central compartment Central and the clearance rate Cl_Central. 

map.Estimated
ans = 2×1 cell
    {'Central'   }
    {'Cl_Central'}

Specify a log transform for the estimated parameters so that the transformed parameters follow a normal distribution. Use an estimatedInfo object to define such transforms and initial values (optional).

estimatedParams = estimatedInfo(["log(Central)","log(Cl_Central)"],InitialValue=[1 1]);

Each infant received a different schedule of dosing. The amount of drug is listed in the data variable DOSE. To specify these dosing during fitting, create dose objects from the data. These objects use the property TargetName to specify which species in the model receives the dose. In this example, the target species is Drug_Central, as listed by the PKModelMap property Dosed. 

map.Dosed
ans = 1×1 cell array
    {'Drug_Central'}

Create a sample dose with this target name and then use the createDoses method of groupedData object data to generate doses for each infant based on the dosing data DOSE. 

sampleDose = sbiodose("sample",TargetName="Drug_Central");
doses = createDoses(data,"DOSE","",sampleDose);

Fit the model. 

[nlmeResults,simI,simP] = sbiofitmixed(onecomp,data,responseMap,estimatedParams,doses,"nlmefit");

Display the variation of estimated parameters using box plots.

plotParameterStats(nlmeResults,"box")

Figure contains an axes object. The axes object contains an object of type boxchart.

Display the empirical distribution of each parameter estimate by showing a violin plot of each estimate.

plotParameterStats(nlmeResults,"violin")

Figure contains an axes object. The axes object contains 2 objects of type violinplot.

Display parameter estimate values as a swarm chart, which is a scatter plot with the points offset (jittered) in the x-dimension

plotParameterStats(nlmeResults,"swarm")

Figure contains an axes object. The axes object contains 2 objects of type scatter.

Display the box plots and swarm charts together.

plotParameterStats(nlmeResults,"box","swarm")

Figure contains an axes object. The axes object contains 3 objects of type boxchart, scatter.

Show the swarm charts and violin plots together.

plotParameterStats(nlmeResults,"swarm","violin")

Figure contains an axes object. The axes object contains 4 objects of type violinplot, scatter.

Show all three plots.

plotParameterStats(nlmeResults,"box","swarm","violin")

Figure contains an axes object. The axes object contains 5 objects of type boxchart, violinplot, scatter.

Input Arguments

collapse all

Parameter estimation results from least-squares (nonlinear regression) or nonlinear mixed-effects estimation, specified as OptimResults, NLINResults, or NLMEResults object.

Plot to show, specified as one of the following values:

  • "box" — Shows summary statistics, including the median, lower and upper quartiles, and any outliers. For details, see Box Chart (Box Plot).

  • "violin" — Shows empirical distributions of parameter estimates. For details, see Violin Plot.

  • "swarm" — Shows parameter estimate values as a swarm chart, which is a scatter plot with the points offset (jittered) in the x-dimension. For details, see swarmchart.

Note that for a hierarchical fit across C categories, the software shows N estimates, where each group has an estimated value based on which category it belongs to.

Data Types: char | string

References

[1] Grasela T.H. Jr, and Donn S.M. "Neonatal population pharmacokinetics of phenobarbital derived from routine clinical data." Developmental Pharmacology and Therapeutics 8, no. 6 (1985): 374–83. https://doi.org/10.1159/000457062.

Version History

Introduced in R2026a

See Also

|