# Documentation

### This is machine translation

Translated by
Mouseover text to see original. Click the button below to return to the English verison of the page.

# sbiosampleparameters

Generate parameters by sampling covariate model (requires Statistics and Machine Learning Toolbox software)

## Syntax

``phi = sbiosampleparameters(covexpr,fe,omega,ds)``
``phi = sbiosampleparameters(covexpr,fe,omega,n)``
``````[phi,covmodel] = sbiosampleparameters(_)``````

## Description

example

````phi = sbiosampleparameters(covexpr,fe,omega,ds)` generates a matrix `phi` containing sampled parameter values using the covariate model specified by the covariate expression `covexpr`, fixed effects `fe`, covariance matrix `omega`, and covariate data `ds`.```

example

````phi = sbiosampleparameters(covexpr,fe,omega,n)` uses a scalar `n` that specifies the number of rows in `phi` when the parameters are not dependent on any covariate.```

example

``````[phi,covmodel] = sbiosampleparameters(_)``` returns a matrix `phi` and a covariate model object `covmodel` using any of the input arguments from previous syntaxes.```

## Examples

collapse all

This example uses data collected on 59 preterm infants given phenobarbital during the first 16 days after birth. 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. Data was described in [1], a study funded by the NIH/NIBIB grant P41-EB01975.

`load pheno.mat ds`

Visualize the data.

```t = sbiotrellis(ds,'ID','TIME','CONC','marker','o','markerfacecolor',[.7 .7 .7],'markeredgecolor','r','linestyle','none'); t.plottitle = 'States versus Time'; t.updateFigureForPrinting(); ```

Create a one-compartment PK model with bolus dosing and linear clearance to model such data.

```pkmd = PKModelDesign; pkmd.addCompartment('Central','DosingType','Bolus','EliminationType','linear-clearance','HasResponseVariable',true,'HasLag',false); onecomp = pkmd.construct; ```

Suppose there is a correlation between the volume of the central compartment (`Central`) and the weight of infants. You can define this parameter-covariate relationship using a covariate model that can be described as

$\mathrm{log}\left({V}_{i}\right)={\theta }_{V}+{\theta }_{V}{WEIGHT}}\ast WEIGH{T}_{i}+{\eta }_{V,i}$,

where, for each ith infant, `V` is the volume, θs (thetas) are fixed effects, η (eta) represents random effects, and `WEIGHT` is the covariate.

```covM = CovariateModel; covM.Expression = {'Central = exp(theta1+theta2*WEIGHT+eta1)'};```

Define the fixed and random effects.

```thetas = [1.4 0.05]; eta1 = [0.2];```

Change the group label of `ds` to `'GROUP'` as required by the `sbiosampleparameters` function.

`ds.Properties.VarNames{1} = 'GROUP';`

Generate parameter values for the volumes of central compartments `Central` based on the covariate model for all infants in the data set.

`phi = sbiosampleparameters(covM.Expression,thetas,eta1,ds);`

You can then simulate the model using the sampled parameter values. For convenience, use the function-like interface provided by a `SimFunction object`.

First, construct a `SimFunction object` using the `createSimFunction` method, specifying the volume (`Central`) as the parameter, and the drug concentration in the compartment (`Drug_Central`) as the output of the `SimFunction` object, and the dosed species.

```f = createSimFunction(onecomp,covM.ParameterNames,'Drug_Central','Drug_Central'); ```

The data set `ds` contains dosing information for each infant, and the `groupedData` object provides a convenient way to extract such dosing information. Convert `ds` to a `groupedData object` and extract dosing information.

```grpData = groupedData(ds); doses = createDoses(grpData,'DOSE');```

Simulate the model using the sampled parameter values from `phi` and the extracted dosing information of each infant, and plot the results. The ith run uses the ith parameter value in `phi` and dosing information of the ith infant.

`sbiotrellis(f(phi,200, doses.getTable), [],'TIME','Drug_Central');`

## Input Arguments

collapse all

Covariate expressions, specified as a cell array of character vectors that defines the parameter-covariate relationships.

### Note

See `CovariateModel object` to learn more about covariate expressions.

Fixed effects, specified as a vector, dataset, or table containing values for fixed effect parameters defined in the covariate expressions `covexpr`. Fixed effect parameter names must start with `'theta'`.

When `fe` is specified as a vector, it must be in the increasing order of the suffixes in `'theta'` if they are numeric such as `'theta1'`, `'theta2'`, etc. If the suffixes are nonnumeric or mixed, `fe` must be specified in ascending ASCII dictionary order.

### Tip

Use the `sort` function to sort a cell array of character vectors to see the ASCII dictionary order.

`sort({'thetaone','theta2','thetax','theta4'})`
```ans = 'theta2' 'theta4' 'thetaone' 'thetax'```

Then specify parameter values in the same order.

`thetas = [0.1 1.3 0.3 4.1];`

where `'theta2'` has the value of 0.1, `'theta4'`, 1.3, etc.

Covariance matrix of random effects, specified as a matrix or dataset or table. Random effect parameter names must start with `'eta'`.

When `omega` is specified as a matrix, it must be in the increasing order of suffixes in `'eta'` such as `'eta1'`, `'eta2'`, etc. If the suffixes are nonnumeric or mixed, `omega` must be specified in ascending ASCII dictionary order. An example of a diagonal covariance matrix with three random effect parameters (`eta1`, `eta2`, and `eta3`) is

$\left[\begin{array}{l}Cov\left({\eta }_{1},{\eta }_{1}\right)\text{​}\text{​}\text{​}\text{​}\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}Cov\left(\eta {}_{1},{\eta }_{2}\right)\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}Cov\left({\eta }_{1},{\eta }_{3}\right)\\ Cov\left({\eta }_{2},{\eta }_{1}\right)\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}Cov\left({\eta }_{2},{\eta }_{2}\right)\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}Cov\left({\eta }_{2},{\eta }_{3}\right)\\ Cov\left({\eta }_{3},{\eta }_{1}\right)\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}Cov\left({\eta }_{3},{\eta }_{2}\right)\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}Cov\left({\eta }_{3},{\eta }_{3}\right)\end{array}\right]=\left[\begin{array}{l}eta1\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}0\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}0\\ 0\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}eta2\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}0\\ 0\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}0\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}eta3\end{array}\right]$

If `omega` is a dataset, `omega.Properties.VarNames` must match the names of the random effects.

If `omega` is a table, `omega.Properties.VariableNames` must match the names of the random effects.

Covariate data, specified as a dataset or table containing the covariate data for all groups.

`ds` must have a column named `'Group'` or `'GROUP'` specifying the group labels as well as a column each for all covariates used in the covariate model. The column names must match the names of the corresponding covariates used in the covariate expressions.

Number of rows in `phi`, specified as a scalar.

## Output Arguments

collapse all

Sampled parameter values, returned as a matrix of size S-by-P, where `S` is the number of groups specified in `ds` or specified by `n` and `P` is the number of parameters which is equal to the number of elements in `covexpr`.

Covariate model, returned as a ```CovariateModel object``` which represents the model defined by `covexpr`.

## References

[1] Grasela Jr, T.H., Donn, S.M. (1985) Neonatal population pharmacokinetics of phenobarbital derived from routine clinical data. Dev Pharmacol Ther. 8(6), 374–83.