# PKCompartment

Compartment used by `PKModelDesign`

to create SimBiology
model

## Description

The `PKCompartment`

object is used by the
`PKModelDesign`

object to construct a SimBiology^{®} model for pharmacokinetic modeling.

The `PKCompartment`

object is used by the
`PKModelDesign`

object to construct a SimBiology model for pharmacokinetic modeling. `PKCompartment`

holds the
following information:

Name of the compartment

Dosing type

Elimination type

Whether the drug concentration in this compartment is reported

The `PKCompartment`

class is a subclass of the
`hgsetget`

class which is a subclass of the `handle`

class. For more information on the inherited methods, see `hgsetget`

, and `handle`

.

## Creation

Use `addCompartment (PKModelDesign)`

to create and
add a compartment to a `PKModelDesign`

model object.

## Properties

`DosingType`

— Type of dosing of drug in compartment

empty character array (default) | `'Bolus'`

| `'Infusion'`

| `'ZeroOrder'`

| `'FirstOrder`

Type of dosing of a drug in a compartment, specified as one of the following:
`'Bolus'`

, `'Infusion'`

,
`'ZeroOrder'`

, or `'FirstOrder`

.

You can only dose one compartment in the model at any given time. For a description of the types of dosing supported, the model components created for each type of dosing, and the parameters to estimate, see Dosing Types.

**Data Types: **`char`

| `string`

`EliminationType`

— Type of elimination of drug from compartment

empty character array (default) | `'Linear'`

| `'Linear-Clearance'`

| `'Enzymatic'`

Type of elimination of a drug from a compartment, specified as one of the following:
`'Linear'`

, `'Linear-Clearance'`

, or
`'Enzymatic'`

.

For a description of the types of elimination supported, the model components created for each type of elimination, and the parameters to estimate, see Elimination Types.

**Data Types: **`char`

| `string`

`HasLag`

— Flag to indicate if dose has time lag

`false`

or 0 (default) | `true`

or 1

Flag to indicate if the dose targeting the compartment has a time lag, specified as
a numeric or logical 1 (`true`

) or 0 (`false`

).

**Data Types: **`double`

| `logical`

`HasResponseVariable`

— Flag to indicate if drug concentration in compartment is reported

`true`

or 1 (default) | `false`

or 0

Flag to indicate if the drug concentration in the compartment is reported, specified
as a numeric or logical 1 (`true`

) or 0
(`false`

).

**Note**

The `HasResponseVariable`

property can be `true`

for more than one `PKCompartment`

object in the model. If you perform
a parameter fit on a model, at least one `PKCompartment`

object in
the model must have a `HasResponseVariable`

property set to
`true`

.

**Data Types: **`double`

| `logical`

`Name`

— `PKCompartment`

object name

character vector | string

`PKCompartment`

object name, specified as a character vector or string.

For details on requirements and recommendations for naming SimBiology components, see Guidelines for Naming Model Components.

**Data Types: **`char`

| `string`

## Object Functions

## Examples

### Fit One-Compartment Model to Individual PK Profile

**Background**

This example shows how to fit an individual's PK profile data to one-compartment model and estimate pharmacokinetic parameters.

Suppose you have drug plasma concentration data from an individual and want to estimate the volume of the central compartment and the clearance. Assume the drug concentration versus the time profile follows the monoexponential decline $${C}_{t}={C}_{0}{e}^{-{k}_{e}t}$$, where $${C}_{t}$$ is the drug concentration at time t, $${C}_{0}$$ is the initial concentration, and $${k}_{e}$$ is the elimination rate constant that depends on the clearance and volume of the central compartment $${k}_{e}=Cl/V$$.

The synthetic data in this example was generated using the following model, parameters, and dose:

One-compartment model with bolus dosing and first-order elimination

Volume of the central compartment (

`Central`

) = 1.70 literClearance parameter (

`Cl_Central`

) = 0.55 liter/hourConstant error model

Bolus dose of 10 mg

**Load Data and Visualize**

The data is stored as a table with variables `Time`

and `Conc`

that represent the time course of the plasma concentration of an individual after an intravenous bolus administration measured at 13 different time points. The variable units for `Time`

and `Conc`

are hour and milligram/liter, respectively.

load('data15.mat') plot(data.Time,data.Conc,'b+') xlabel('Time (hour)'); ylabel('Drug Concentration (milligram/liter)');

**Convert to groupedData Format**

Convert the data set to a `groupedData`

object, which is the required data format for the fitting function `sbiofit`

for later use. A `groupedData`

object also lets you set independent variable and group variable names (if they exist). Set the units of the `Time`

and `Conc`

variables. The units are optional and only required for the UnitConversion feature, which automatically converts matching physical quantities to one consistent unit system.

gData = groupedData(data); gData.Properties.VariableUnits = {'hour','milligram/liter'}; gData.Properties

`ans = `*struct with fields:*
Description: ''
UserData: []
DimensionNames: {'Row' 'Variables'}
VariableNames: {'Time' 'Conc'}
VariableDescriptions: {}
VariableUnits: {'hour' 'milligram/liter'}
VariableContinuity: []
RowNames: {}
CustomProperties: [1×1 matlab.tabular.CustomProperties]
GroupVariableName: ''
IndependentVariableName: 'Time'

`groupedData`

automatically set the name of the `IndependentVariableName`

property to the `Time`

variable of the data.

**Construct a One-Compartment Model**

Use the built-in PK library to construct a one-compartment model with bolus dosing and first-order elimination where the elimination rate depends on the clearance and volume of the central compartment. Use the `configset`

object to turn on unit conversion.

pkmd = PKModelDesign; pkc1 = addCompartment(pkmd,'Central'); pkc1.DosingType = 'Bolus'; pkc1.EliminationType = 'linear-clearance'; pkc1.HasResponseVariable = true; model = construct(pkmd); configset = getconfigset(model); configset.CompileOptions.UnitConversion = true;

For details on creating compartmental PK models using the SimBiology® built-in library, see Create Pharmacokinetic Models.

**Define Dosing**

Define a single bolus dose of 10 milligram given at time = 0. For details on setting up different dosing schedules, see Doses in SimBiology Models.

dose = sbiodose('dose'); dose.TargetName = 'Drug_Central'; dose.StartTime = 0; dose.Amount = 10; dose.AmountUnits = 'milligram'; dose.TimeUnits = 'hour';

**Map Response Data to the Corresponding Model Component**

The data contains drug concentration data stored in the `Conc`

variable. This data corresponds to the `Drug_Central`

species in the model. Therefore, map the data to `Drug_Central`

as follows.

`responseMap = {'Drug_Central = Conc'};`

**Specify Parameters to Estimate**

The parameters to fit in this model are the volume of the central compartment (Central) and the clearance rate (Cl_Central). In this case, specify log-transformation for these biological parameters since they are constrained to be positive. The `estimatedInfo`

object lets you specify parameter transforms, initial values, and parameter bounds if needed.

paramsToEstimate = {'log(Central)','log(Cl_Central)'}; estimatedParams = estimatedInfo(paramsToEstimate,'InitialValue',[1 1],'Bounds',[1 5;0.5 2]);

**Estimate Parameters**

Now that you have defined one-compartment model, data to fit, mapped response data, parameters to estimate, and dosing, use `sbiofit`

to estimate parameters. The default estimation function that `sbiofit`

uses will change depending on which toolboxes are available. To see which function was used during fitting, check the `EstimationFunction`

property of the corresponding results object.

fitConst = sbiofit(model,gData,responseMap,estimatedParams,dose);

**Display Estimated Parameters and Plot Results**

Notice the parameter estimates were not far off from the true values (1.70 and 0.55) that were used to generate the data. You may also try different error models to see if they could further improve the parameter estimates.

fitConst.ParameterEstimates

`ans=`*2×4 table*
Name Estimate StandardError Bounds
______________ ________ _____________ __________
{'Central' } 1.6993 0.034821 1 5
{'Cl_Central'} 0.53358 0.01968 0.5 2

s.Labels.XLabel = 'Time (hour)'; s.Labels.YLabel = 'Concentration (milligram/liter)'; plot(fitConst,'AxesStyle',s);

**Use Different Error Models**

Try three other supported error models (proportional, combination of constant and proportional error models, and exponential).

fitProp = sbiofit(model,gData,responseMap,estimatedParams,dose,... 'ErrorModel','proportional'); fitExp = sbiofit(model,gData,responseMap,estimatedParams,dose,... 'ErrorModel','exponential'); fitComb = sbiofit(model,gData,responseMap,estimatedParams,dose,... 'ErrorModel','combined');

**Use Weights Instead of an Error Model**

You can specify weights as a numeric matrix, where the number of columns corresponds to the number of responses. Setting all weights to 1 is equivalent to the constant error model.

```
weightsNumeric = ones(size(gData.Conc));
fitWeightsNumeric = sbiofit(model,gData,responseMap,estimatedParams,dose,'Weights',weightsNumeric);
```

Alternatively, you can use a function handle that accepts a vector of predicted response values and returns a vector of weights. In this example, use a function handle that is equivalent to the proportional error model.

```
weightsFunction = @(y) 1./y.^2;
fitWeightsFunction = sbiofit(model,gData,responseMap,estimatedParams,dose,'Weights',weightsFunction);
```

**Compare Information Criteria for Model Selection**

Compare the loglikelihood, AIC, and BIC values of each model to see which error model best fits the data. A larger likelihood value indicates the corresponding model fits the model better. For AIC and BIC, the smaller values are better.

allResults = [fitConst,fitWeightsNumeric,fitWeightsFunction,fitProp,fitExp,fitComb]; errorModelNames = {'constant error model','equal weights','proportional weights', ... 'proportional error model','exponential error model',... 'combined error model'}; LogLikelihood = [allResults.LogLikelihood]'; AIC = [allResults.AIC]'; BIC = [allResults.BIC]'; t = table(LogLikelihood,AIC,BIC); t.Properties.RowNames = errorModelNames; t

`t=`*6×3 table*
LogLikelihood AIC BIC
_____________ _______ _______
constant error model 3.9866 -3.9732 -2.8433
equal weights 3.9866 -3.9732 -2.8433
proportional weights -3.8472 11.694 12.824
proportional error model -3.8257 11.651 12.781
exponential error model 1.1984 1.6032 2.7331
combined error model 3.9163 -3.8326 -2.7027

Based on the information criteria, the constant error model (or equal weights) fits the data best since it has the largest loglikelihood value and the smallest AIC and BIC.

**Display Estimated Parameter Values**

Show the estimated parameter values of each model.

Estimated_Central = zeros(6,1); Estimated_Cl_Central = zeros(6,1); t2 = table(Estimated_Central,Estimated_Cl_Central); t2.Properties.RowNames = errorModelNames; for i = 1:height(t2) t2{i,1} = allResults(i).ParameterEstimates.Estimate(1); t2{i,2} = allResults(i).ParameterEstimates.Estimate(2); end t2

`t2=`*6×2 table*
Estimated_Central Estimated_Cl_Central
_________________ ____________________
constant error model 1.6993 0.53358
equal weights 1.6993 0.53358
proportional weights 1.9045 0.51734
proportional error model 1.8777 0.51147
exponential error model 1.7872 0.51701
combined error model 1.7008 0.53271

**Conclusion**

This example showed how to estimate PK parameters, namely the volume of the central compartment and clearance parameter of an individual, by fitting the PK profile data to one-compartment model. You compared the information criteria of each model and estimated parameter values of different error models to see which model best explained the data. Final fitted results suggested both the constant and combined error models provided the closest estimates to the parameter values used to generate the data. However, the constant error model is a better model as indicated by the loglikelihood, AIC, and BIC information criteria.

## Version History

**Introduced in R2009a**

### R2024a: Having duplicate model component names is no longer allowed

When you load a model that contains duplicate names, SimBiology automatically updates those names. SimBiology disambiguates the duplicate names by adding a suffix

`"_`

, where*N*"*N*is the first positive integer that results in a unique name. If there is an existing suffix,*N*will be incremented from that suffix. For example, if there are two model components named*x_3*, the function updates one of the names to*x_4*. If the existing suffix has leading zeros, the function omits the zeros in the new name. For instance, if*x_003*is a duplicate name, it gets renamed to*x_4*. However, the function assumes that names with leading zeros and without leading zeros are different. For instance,*x_005*and*x_5*are considered to be different names.SimBiology issues an error if multiple model components (model, compartment, species, parameter, reaction, rule, event, observable, dose, and variant) have the same name. Within a single model, these components are required to have unique names even when they are of different types with the following two exceptions:

Species in different compartments can have the same name.

Parameters can have the same name if they are scoped to different parents. Specifically, you can use the same name for a model-scoped parameter and reaction-scoped parameters, where each reaction-scoped parameter belongs to a different reaction.

For details on how to reference model component names in expressions, see Guidelines for Referencing Names in Expressions.

### R2022b: Having duplicate model component names issues a warning

SimBiology issues a warning if multiple model components have the same name.

### R2022a: Having duplicate model component names will not be allowed in a future release

SimBiology will not allow you to have duplicate names for model components within a model.

## MATLAB Command

You clicked a link that corresponds to this MATLAB command:

Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.

Select a Web Site

Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .

You can also select a web site from the following list:

## How to Get Best Site Performance

Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.

### Americas

- América Latina (Español)
- Canada (English)
- United States (English)

### Europe

- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)

- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)