Main Content

sbioncaoptions

Specify options to calculate noncompartmental analysis (NCA) parameters

collapse all in page

Syntax

opt = sbioncaoptions

Description

opt = sbioncaoptions returns an NCA options object. Use dot notation to set the object properties for the options.

example

Examples

collapse all

This example uses:

Open Live Script

Load a synthetic data set that contains the drug concentration measurements of four individuals after an IV bolus dose.

load data1.mat

Set the dose amounts to NaN at time points when no dose was administered.

data1.Dose(data1.Dose(:) == 0) = NaN;

Display the data.

sbiotrellis(data1,'ID','Time','DrugConc','Marker','o','LineStyle','--');

Figure contains 4 axes objects. Axes object 1 with title ID 1 contains an object of type line. Axes object 2 with title ID 2 contains an object of type line. Axes object 3 with title ID 3 contains an object of type line. Axes object 4 with title ID 4 contains an object of type line. This object represents DrugConc.

Categorize the data columns using an NCA options object.

opt = sbioncaoptions;
opt.groupColumnName         = 'ID';
opt.concentrationColumnName = 'DrugConc';
opt.timeColumnName          = 'Time';
opt.IVDoseColumnName        = 'Dose';

Compute NCA parameters for each individual.

ncaparameters = sbionca(data1,opt);

Display the first few columns of the table. Each row of ncaparameters table represents an individual (or group), and each column lists the corresponding NCA parameter value.

ncaparameters(:,1:15)
ans=4×15 table
    ID    doseSchedule    administrationRoute    Lambda_Z      R2       adjusted_R2    Num_points    AUC_0_last    Tlast    C_max     C_max_Dose    T_max     MRT      T_half    AUC_infinity
    __    ____________    ___________________    ________    _______    ___________    __________    __________    _____    ______    __________    _____    ______    ______    ____________

    1      {'Single'}         {'IVBolus'}        0.57893     0.99991       0.9999          11          143.61       48      74.412      1.4882        0      1.5408    1.1973       143.61   
    2      {'Single'}         {'IVBolus'}        0.66798     0.99998      0.99998          11          299.37       48      191.96      1.9196        0      1.3352    1.0377       299.37   
    3      {'Single'}         {'IVBolus'}        0.62124     0.99999      0.99999          11           766.5       48      411.06      1.6442        0      1.4476    1.1157        766.5   
    4      {'Single'}         {'IVBolus'}        0.58011     0.99995      0.99995          11          1301.8       48      648.33      1.2967        0      1.5721    1.1949       1301.8

You can also specify a custom time range to compute T_max and C_max within that time range, say from time = 0 to 20. You can do so by setting the C_max_ranges property as a cell array of two-element row vector.

opt.C_max_ranges    = {[5.5 20]};
ncaparameters2       = sbionca(data1,opt);

The function reports the T_max and C_max values within the range by adding two new columns: T_max_5_5__20 and C_max_5_5__20. Note that in the names of these two columns, the last time point is preceded by two consecutive underscores (__).

ncaparameters2.T_max_5_5__20(:)
ans = 4×1

     6
     6
     6
     6


ncaparameters2.C_max_5_5__20(:)
ans = 4×1

    2.2719
    3.0213
   10.0233
   19.9006

Similarly, you can specify a custom time range to compute the partial AUC value for each group.

opt.PartialAreas    = {[0 20]};
ncaparameters3      = sbionca(data1,opt);
ncaparameters3.AUC_0__20(:)
ans = 4×1
103 ×

    0.1436
    0.2994
    0.7665
    1.3017

You can also specify multiple time ranges for C_max_ranges and PartialAreas.

opt.C_max_ranges    = {[0 20],[0 10],[0 15]};
opt.PartialAreas    = {[0 12],[0 30]};
ncaparameters4      = sbionca(data1,opt);

Output Arguments

collapse all

Options to calculate NCA parameters, returned as a SimBiology.nca.Options object. The properties of the object are classified into two groups, data classification options and parameter calculation options.

Data Classification Options

PropertyDescription
IVDoseColumnNameName of the data column that contains the IV dose amount.
EVDoseColumnNameName of the data column that contains the extravascular (EV) dose amount.
concentrationColumnNameName of the data column that contains the measured concentrations.
timeColumnNameName of the data column that contains the time points.
groupColumnName

Name of the data column that contains the grouping information. You can specify grouping using two levels of hierarchy. Specify the outer level of grouping in this column. Specify the inner level of grouping (subgroups) in idColumnName.

If you specify idColumnName, then you must also specify groupColumnName.

For example, consider data that contains three groups, where each group contains four patients. The group column labels the three groups, and the ID column labels each patient.

idColumnName

Name of the data column that contains the grouping information. You can specify grouping using two levels of hierarchy. Specify the inner level of grouping (subgroups) in this column. Specify the outer level of grouping in groupColumnName.

If you specify idColumnName, then you must also specify groupColumnName.

infusionRateColumnNameName of the data column that contains the infusion rates.

Parameter Calculation Options

PropertyDescription
AUCCalculationMode (since R2024a)

Method to calculate the AUC. There are two methods:

  • "Linear" — Linear trapezoidal method. This is the default.

  • "LinUpLogDown" — Linear-up log-down method. This method uses the linear trapezoidal integration whenever concentrations are increasing or constant and uses the trapezoidal integration of the log-transformed concentrations whenever they are decreasing. For details, see Linear-up Log-down Method.

LOQLower limit of quantization, a threshold below which the values of dependent variable are truncated to zero.
AdministrationRouteDrug administration route. Three types of administration are supported: IVBolus, IVInfusion, and ExtraVascular.
TAUDosing interval for multiple-dosing data.
SparseDataBoolean that indicates whether or not the values of dependent variable are averaged between subgroups to further populate a profile for a group. Time values for each measurement across subgroups (IDs) within a group must be identical.
Lambda_Z_Time_Min_Max

Two-element row vector that specifies a custom time range to compute the terminal rate constant (Lambda_z). The time range applies to all groups; you cannot specify a different time range for each group. For details, see Noncompartmental Analysis.

PartialAreas

Cell array of one or more two-element row vectors that specify one or more time ranges used to compute the partial AUC values. You can specify multiple rows for group-specific ranges, where the number of rows equal the number of groups. If there is only one row, the same time ranges are used for all groups.

C_max_ranges

Cell array of one or more two-element row vectors that specify one or more time ranges used to report the T_max,C_max pairs within the specified ranges. You can specify multiple rows for group-specific ranges, where the number of rows equal the number of groups. If there is only one row, the same time ranges are used for all groups.

More About

collapse all

Linear-up Log-down Method

This method uses the linear trapezoidal integration (LinUp) whenever concentrations are increasing or constant, and trapezoidal integration of the log-transformed concentrations (LogDown) whenever they are decreasing.

For the LinUpLogDown method, SimBiology uses the following equation to calculate the AUC for log-transformed concentrations:

AUC=​∫0ΔTC1e1ΔTlog(C2C1) tdt=ΔTlog(C2)−log(C1)(C2−C1)

where, C1 and C2 are concentrations at times t1 and t2, respectively. ΔT is t2 – t1.

For instance, the next figure illustrates where LinUp and LogDown are used for a given concentration-time course depending on whether concentrations are decreasing or increasing.

2D plot of a PK time course showing LinUp and LogDown areas

Version History

Introduced in R2017b

See Also

Topics