Main Content

createDoses

Create dose objects from groupedData object

collapse all in page

Syntax

doseArray = createDoses(grpData,amountVarNames)
doseArray = createDoses(grpData,amountVarNames,rateVarNames)
doseArray = createDoses(grpData,amountVarNames,rateVarNames,tempDoses)
doseArray = createDoses(grpData,amountVarNames,rateVarNames,tempDoses,groups)

Description

doseArray = createDoses(grpData,amountVarNames) creates an array of SimBiology® dose objects using dose times and amount data specified in grpData, with one row per group and one column per dose amount variable.

grpData.Properties.IndependentVariable specifies which variable contains dose times, and amountVarNames specifies which variables contain valid dose amounts.

example

doseArray = createDoses(grpData,amountVarNames,rateVarNames) uses dose rate variables specified by rateVarNames.

example

doseArray = createDoses(grpData,amountVarNames,rateVarNames,tempDoses) uses template doses specified by tempDoses as templates for dose objects in doseArray. In other words, this argument lets you copy some of the template dose properties, such as TargetName, DurationParameterName, and LagParameterName, to dose objects in doseArray.

example

doseArray = createDoses(grpData,amountVarNames,rateVarNames,tempDoses,groups) specifies which groups in grpData to create doses for.

example

Examples

collapse all

Open Live Script

Load the sample data set.

load pheno.mat ds

Create a groupedData object from the data set ds.

grpData = groupedData(ds);

Display the object properties.

grpData.Properties
ans = struct with fields:
                Description: ''
                   UserData: []
             DimensionNames: {'Observations'  'Variables'}
              VariableNames: {'ID'  'TIME'  'DOSE'  'WEIGHT'  'APGAR'  'CONC'}
              VariableTypes: ["double"    "double"    "double"    "double"    "double"    "double"]
       VariableDescriptions: {}
              VariableUnits: {}
         VariableContinuity: []
                   RowNames: {}
           CustomProperties: [1x1 matlab.tabular.CustomProperties]
          GroupVariableName: 'ID'
    IndependentVariableName: 'TIME'

GroupVariableName and IndpendentVariableName have been automatically assigned to 'ID' and 'Time', respectively.

Create an array of dose objects using the dosing information from the groupedData specified by the DOSE variable. Each row (dose object) represents a dosing schedule for each individual (group).

doseArray = createDoses(grpData,'DOSE');

Input Arguments

collapse all

Grouped data, specified as a groupedData object.

Set grpData.Properties.IndependentVariable to a valid variable in grpData that specifies the dose times. grpData.Properties.GroupVariableName optionally identifies a grouping variable. grpData.Properties.VariableUnits optionally specifies units for the corresponding variables. If the specified units are invalid, a warning is issued, and the units of corresponding doses in doseArray are set to empty character vectors ('').

Amount variable names, specified as a character vector, string, string vector, or cell array of character vectors that specifies variables in grpData that define dose amounts. Each character vector or string must specify a valid amount variable.

An amount variable is valid if it is a real, nonnegative column vector containing no infinite values.

Rate variable names, specified as a character vector, string, string vector, or cell array of character vectors that specify variables in grpData that define dose rates. If it is empty [] or {}, it indicates that there are no dose rates. If it is not empty, it must be a character vector, string, cell array of character vectors or string vector of names of the same length as amountVarNames. Individual names can be empty ('' or "") to indicate no dose rates for the corresponding doses or can be valid variable names in grpData specifying dose rates.

A rate variable is valid if it is a real, nonnegative column vector containing no infinite values. NaN rate values are allowed, but they are treated the same as the rate values of 0, that is, the doses are treated as bolus (instantaneous) doses.

Template doses, specified as a dose object (ScheduleDose object or RepeatDose object), vector of dose objects, or empty array [].

Use this argument to copy the following template dose properties to each dose in doseArray: TargetName, DurationParameterName, LagParameterName, Notes, Tag, and UserData.

If tempDoses is a single dose object, these properties from the object are copied to all doses in doseArray. If it is a vector, it must have the same length as amountVarNames, and these properties from each element (dose) are copied to the corresponding column of doses in doseArray.

The Name property of each dose in doseArray consists of the Name of the template dose followed by the group name in parentheses, such as 'DailyDose (Patient1)'.

If you do not specify units in grpData.Properties.VariableUnits, the following template dose units properties are copied to doses in doseArray: AmountUnits, RateUnits, and TimeUnits.

Group names, specified as a character vector, string vector, an empty array [], or a vector of data types that can be converted to a categorical vector. For a list of supported data types, see categorical.

By default, groups is set to [], meaning the function creates doses for each group in grpData, with doseArray containing one row per group in grpData, in the order of the first occurrence of each group in grpData.

If you specify any group, the function converts those groups and the grouping variable in grpData to categorical vectors and compares them. The ith row of doseArray corresponds to the ith group specified in groups.

Output Arguments

collapse all

SimBiology dose objects, returned as a 2-D matrix of dose objects containing dose time and amount data from grpData. If dose times for a particular dose in grpData are regularly spaced, then the corresponding dose object in doseArray is a RepeatDose object. Otherwise, the corresponding dose object is a ScheduleDose object.

Note

If there is a single dose time, then the dose object is represented as a ScheduleDose object.

Version History

Introduced in R2014a

See Also

| | |