模型拟合相关函数#
mas.model.PopModel#
- class mas.model.PopModel(mod, data=None)#
群体模型。对其可以进行模型拟合与模拟等操作。
此处的“群体模型”一般指代的是用于拟合群体数据的非线性混合效应模型(继承自 Module
的模型)。
参数:
mod (
AnyModule
):模型。data (
polars.DataFrame | pandas.DataFrame | EventTable
, optional):需要被模型拟合的数据集。默认值为None
。
data#
- property data#
获取将被模型拟合的数据集。
类型:
DataFrame
inits#
- property inits#
获取模型参数及其初值。
类型:
PopParams
fit()#
拟合模型。
参数:
estimation (
AnyEstimationSettings | Sequence[AnyEstimationSettings]
, optional):参数估计的算法及其相关设置。当前支持的算法包括FOCEi
(first-order conditional estimation with interaction)与FO
(first-order estimation)。若传入一个序列(Sequence
)则将根据传入顺序依次以对应的算法估计参数。默认值为FOCEi
。cov (
bool
, optional):是否计算协方差矩阵。默认值为True
。
返回值:
包含参数估计值的模型拟合结果。
返回类型:
FitResult
示例:
使用 FOCEi 算法拟合华法林 PK 模型:
from mas.model import *
from mas.datasets import warfarin
import polars as pl
class WarfarinPk(EvOneCmtLinear):
def __init__(self):
super().__init__()
self.tv_cl = theta(0.134, bounds=(0, None))
self.tv_v = theta(7.81, bounds=(0, None))
self.tv_ka = theta(0.571, bounds=(0, None))
self.tv_alag = theta(0.823, bounds=(0, None))
self.eta_cl = omega(0.049)
self.eta_v = omega(0.0802)
self.eta_ka = omega(0.047)
self.eta_alag = omega(0.156)
self.eps_prop = sigma(0.0104)
self.eps_add = sigma(0.554)
def pred(self):
cl = self.tv_cl * exp(self.eta_cl)
v = self.tv_v * exp(self.eta_v)
ka = self.tv_ka * exp(self.eta_ka)
alag = self.tv_alag * exp(self.eta_alag)
pred_res = self.pred_physio(cl=cl, v=v, ka=ka, alag1=alag, s2=v)
ipred = pred_res.F
y = ipred * (1 + self.eps_prop) + self.eps_add
return y
data = warfarin.filter(pl.col("DVID") != 2)
model = PopModel(data=data, mod=WarfarinPk)
fit_res = model.fit(FOCEi(print=10))
➡️ Since build cache already exists, skip compile
✈️ First Order Conditional Estimation
Using BFGS...
* maxiter = 9999
* xtol = 1e-06
* ftol = 1e-06
* lower_bounds =
* upper_bounds =
* log_level = 0
* print = 10
* print_type = 0
* verbose = 1
* p_small = 0.1
* rel_step_size = 0.001
#0 ofv: 347.7917575
x: 1.0000e-01 1.0000e-01 1.0000e-01 1.0000e-01 1.0000e-01 1.0000e-01 1.0000e-01 1.0000e-01 1.0000e-01 1.0000e-01
Gradients: -10.50922313 -8.337435215 -96.92524277 30.79964507 -27.5129099 17.54380989 -33.12124364 -11.51145138 43.18445972 122.184147
Funcalls: 8
#1 ofv: 252.9367071
x: 1.5161e-01 1.4094e-01 5.7596e-01 -5.1245e-02 2.3511e-01 1.3849e-02 2.6265e-01 1.5653e-01 -1.1206e-01 -5.0000e-01
Gradients: 58.50061103 19.48231624 -12.65455289 0.4384106675 -20.96792104 14.03048876 -33.11403771 -4.197922454 7.463903843 42.03740251
Funcalls: 17
#11 ofv: 219.1455277
x: 6.6128e-02 1.1409e-01 1.1174e+00 1.3436e-01 3.6191e-01 -1.8678e-01 1.6618e+00 -3.4404e-02 -4.8287e-02 -1.0445e+00
Gradients: -12.23382637 -8.006522096 1.121649154 2.078737048 -0.3172187198 -3.44933002 4.276000529 -2.390193903 -2.991842556 -5.93248133
Funcalls: 109
#21 ofv: 218.0048633
x: 8.5523e-02 1.2083e-01 9.4660e-01 8.7367e-02 3.6555e-01 -1.5218e-01 1.4398e+00 1.1198e-01 -6.5216e-02 -9.5924e-01
Gradients: -0.4235252143 -0.4252403098 -0.2043806704 -0.7252371926 -0.06346455363 -0.0730903328 -0.05603257135 -0.02540551396 0.01857995789 -0.1170551225
Funcalls: 223
converged = True
n_iter = 25
x_opt = 8.6104e-02 1.2128e-01 9.6344e-01 1.0153e-01 3.6619e-01 -1.5174e-01 1.4490e+00 9.8417e-02 -6.5853e-02 -9.5697e-01
f_opt = 217.9974593
fun_calls = 281
Computing Covariance...
Covariance computation succeed
vpc_res = fit_res.vpc()
vpc_res.plot()
[VPC] Preparing data...
[VPC] Running simulation...
[VPC] Done
Running Auto-bin...
Bin search ended, result is 10
Auto-bin completed, finally use 10 bins.
支持的算法设置#
设置 |
功能 |
---|---|
|
每 |
|
输出详尽等级。若为 |
|
最小化方法。 |
|
最大迭代次数。 |
|
相对参数收敛界值。 |
|
相对目标函数收敛界值。 |
|
协方差估算方法。 |
|
eta 参数最小化方法(仅适用于 FOCEi 算法)。 |
|
协方差最小化方法(仅适用于 FOCEi 算法)。 |
|
各最小化方法额外设置选项。 |
支持的各最小化方法额外设置选项#
lbfgs#
设置 |
功能 |
---|---|
|
用于方向计算(direction calculation)的迭代次数。 |
|
使用近似特征值(approximate eigenvalue scaling)。 |
|
用于近似目标函数的多项式的次数。 |
|
最小线搜索(line search)步长。 |
|
相对梯度收敛界值。 |
|
数值微分(numerical differentiation)方法。 若为 |
|
数值微分方法相对步长(relative step size)。 |
BObyQA 与 NEWUOA#
设置 |
功能 |
---|---|
|
初始信赖域(trust region)大小。 |
|
最终信赖域大小。 |
Nelder-Mead#
设置 |
功能 |
---|---|
|
反射(reflection)系数。 |
|
扩展(contraction)系数 |
|
收缩(expansion)参数。 |
|
回退(shrinkage)系数。 |
|
是否使用自适应(adaptive)参数。 |
simulate()#
- simulate(data=None, param=None, seed=1234) SimulationResult #
运行模型模拟。
参数:
data (
DataFrame | EventTable
, optional):用于模拟的数据集。若为None
则使用模型将要拟合的数据集(即在创建 PopModel 时指定的data
)。支持使用 EventTable。默认值为None
。params (
AnyPopParams
, optional):用于模拟的参数值。若为None
则使用模型中的参数初值。默认值为None
。seed (
int
, optional):随机种子。默认值为1234
。
返回值:
包含模拟数据集的模拟结果。
返回类型:
SimulationResult
示例:
模拟华法林的 PK 场景
sim_res = model.simulate(data)
sim_res.output
ID | TIME | AMT | DV | DVID | MDV | WT | AGE | SEX | DOSE | EVID | CMT | SS | _IPRED_ | _PRED_ | _Y_ | alag | cl | ipred | ka | v | y |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
i64 | f64 | f64 | f64 | i64 | i64 | f64 | i64 | i64 | f64 | i64 | i64 | i64 | f64 | f64 | f64 | f64 | f64 | f64 | f64 | f64 | f64 |
0 | 0.0 | 100.0 | null | 0 | 1 | 66.7 | 50 | 1 | 100.0 | 1 | 1 | null | 0.0 | 0.0 | -0.380376 | 1.025604 | 0.180516 | 0.0 | 0.764926 | 7.788145 | -0.380376 |
0 | 0.5 | null | 0.0 | 1 | 0 | 66.7 | 50 | 1 | 100.0 | 0 | 2 | null | 0.0 | 0.0 | -0.23897 | 1.025604 | 0.180516 | 0.0 | 0.764926 | 7.788145 | -0.23897 |
0 | 1.0 | null | 1.9 | 1 | 0 | 66.7 | 50 | 1 | 100.0 | 0 | 2 | null | 0.0 | 1.228928 | -0.439278 | 1.025604 | 0.180516 | 0.0 | 0.764926 | 7.788145 | -0.439278 |
0 | 2.0 | null | 3.3 | 1 | 0 | 66.7 | 50 | 1 | 100.0 | 0 | 2 | null | 6.661621 | 6.195857 | 6.363483 | 1.025604 | 0.180516 | 6.661621 | 0.764926 | 7.788145 | 6.363483 |
0 | 3.0 | null | 6.6 | 1 | 0 | 66.7 | 50 | 1 | 100.0 | 0 | 2 | null | 9.724606 | 8.908386 | 8.120754 | 1.025604 | 0.180516 | 9.724606 | 0.764926 | 7.788145 | 8.120754 |
… | … | … | … | … | … | … | … | … | … | … | … | … | … | … | … | … | … | … | … | … | … |
32 | 36.0 | null | 7.7 | 1 | 0 | 62.0 | 21 | 1 | 93.0 | 0 | 2 | null | 5.873412 | 6.713728 | 6.131435 | 0.695153 | 0.120611 | 5.873412 | 0.492931 | 10.994087 | 6.131435 |
32 | 48.0 | null | 6.9 | 1 | 0 | 62.0 | 21 | 1 | 93.0 | 0 | 2 | null | 5.148932 | 5.464455 | 5.668542 | 0.695153 | 0.120611 | 5.148932 | 0.492931 | 10.994087 | 5.668542 |
32 | 72.0 | null | 4.4 | 1 | 0 | 62.0 | 21 | 1 | 93.0 | 0 | 2 | null | 3.957041 | 3.620039 | 4.254351 | 0.695153 | 0.120611 | 3.957041 | 0.492931 | 10.994087 | 4.254351 |
32 | 96.0 | null | 3.5 | 1 | 0 | 62.0 | 21 | 1 | 93.0 | 0 | 2 | null | 3.041052 | 2.398168 | 2.127461 | 0.695153 | 0.120611 | 3.041052 | 0.492931 | 10.994087 | 2.127461 |
32 | 120.0 | null | 2.5 | 1 | 0 | 62.0 | 21 | 1 | 93.0 | 0 | 2 | null | 2.337099 | 1.588714 | 3.266617 | 0.695153 | 0.120611 | 2.337099 | 0.492931 | 10.994087 | 3.266617 |
to_nonmem()#
- to_nonmem(dir, control_filename=None, data_filename=None) None #
将模型翻译为 NONMEM 控制文件代码。
参数:
dir (
PathLike
):翻译结果输出路径control_filename (
str
, optional):输出的控制文件文件名。若为None
则采用模型类名.mod
的命名形式。默认值为None
。data_filename (
str
, optional):输出的数据集文件文件名。若为None
则采用模型类名.csv
的命名形式。默认值为None
。
mas.model.EstimationResult#
- class mas.model.EstimationResult#
模型参数估计结果。
ofv#
- property ofv#
当前参数估计结果对应的目标函数值。
类型:
float
estimates#
- property estimates#
模型参数估计结果。
类型:
PopParams
converged#
- property converged#
目标函数最小化过程中参数估计是否收敛。
类型:
bool
n_iter#
- property n_iter#
迭代次数。
类型:
int
est_time#
- property est_time#
参数估计耗时。
类型:
timedelta
mas.model.FitResult#
- class mas.model.FitResult#
模型拟合结果。
ofv#
- property ofv
所有最小化过程结束后参数估计结果对应的目标函数值。
类型:
float
estimates#
- property estimates
所有最小化过程结束后得到的参数估计值。
类型:
PopParams
converged#
- property converged
所有最小化过程结束后参数估计是否收敛。
类型:
bool
n_iter#
- property n_iter
所有最小化过程的总迭代次数。
类型:
int
inits#
- property inits
模型参数初值。
类型:
PopParams
est_sequence#
- property est_sequence
各最小化过程的参数估计结果。
类型:
list[EstimationResult]
iterations#
- property iterations
各次迭代的参数估计结果。
类型:
list[IterationResults]
compile_time#
- property compile_time
模型编译耗时。
类型:
timedelta
est_time#
- property est_time
参数估计耗时。
类型:
timedelta
cov_time#
- property cov_time
协方差估计耗时。
类型:
timedelta | None
elapsed_time#
- property elapsed_time
模型拟合所花费的总耗时。
类型:
timedelta
output#
- property output
包含观测值、群体预测值、个体预测值与个体参数值(以最后一次最小化过程的结果为准)的数据集。
类型:
DataFrame
covariance#
- property covariance
协方差估计结果。
类型:
CovResult
summary()#
- summary() None
打印模型拟合结果摘要。
compute()#
- compute(residuals=None) DataFrame
计算群体预测值(population predictions)、个体预测值(individual predictions)与残差(residuals)。
参数:
residuals (
list[Literal["CWRES", "WRES", "CWRESI", "WRESI", "CIWRES", "IWRES", "CIWRESI", "IWRESI"]]
, optional):需要计算的残差类型。如果为None
则跳过残差计算。默认值为None
。
返回值:
包含指定计算内容的 DataFrame
。
返回类型:
DataFrame
ebe()#
- ebe() DataFrame
计算 eta 参数的经验贝叶斯估计。
返回值:
包含各个个体经验贝叶斯估计值的 DataFrame
。
返回类型:
DataFrame
eta_shr()#
- eta_shr(method='sd', ebv=False) DataFrame
计算 eta 参数的收缩量。
eta 参数收缩量公式
若为标准差形式,计算公式如下:
若为方差形式,计算公式如下:
其中,eta(j) 为第 j 个 eta 参数的个体经验贝叶斯估计值。
参数:
method (
Literal["sd", "var"]
, optional):计算收缩量的方法。使用标准差形式("sd"
)或方差形式("var"
)。默认值为"sd"
。计算公式可见:eta 参数收缩量公式。ebv (
bool
, optional):是否计算平均经验贝叶斯方差。默认值为False
。
返回值:
eta 参数收缩量的数据框。
返回类型:
DataFrame
示例:
fit_res.eta_shr("sd")
eta_cl | eta_v | eta_ka | eta_alag |
---|---|---|---|
f64 | f64 | f64 | f64 |
1.0000e-10 | 0.039936 | 0.504504 | 0.592428 |
eps_shr()#
- eps_shr(method='sd') DataFrame
计算 eps 参数的收缩量。
eps 参数收缩量公式
若为标准差形式,计算公式如下:
若为方差形式,计算公式如下:
其中,IWRES 为个体加权残差(individual weighted residual)。
参数:
method (
Literal["sd", "var"]
, optional):计算收缩量的方法。使用标准差形式("sd"
)或方差形式("var"
)。默认值为"sd"
。计算公式可见:eps 参数收缩量公式。
返回值:
eps 参数收缩量的数据框。
返回类型:
DataFrame
plot_gof()#
- plot_gof(self, filter=None, idv_name=None, dv_name=None, wres='CWRES', iwres='CIWRES') Plot #
绘制模型拟合优度图(goodness of fit)。
参数:
filter (
Expr
, optional): 筛选条件,对于部分数据进行 gof 绘制。默认值为None
。idv_name (
str
, optional):因变量名。若为None
,则自动推断。默认值为None
。dv_name (
str
, optional):自变量名。若为None
,则自动推断。默认值为None
。wres (
Literal["CWRES", "CWRESI", "WRES", "WRESI"]
, optional):需要计算的加权残差类型(weighted residuals)。默认值为"CWRES"
。iwres (
Literal["CIWRES", "CIWRESI", "IWRES", "IWRESI"]
, optional):需要计算的个体加权残差类型(individual weighted residual)。默认值为"CIWRES"
。
示例:
fit_res.plot_gof()
plot_predictions()#
- plot_predictions(self, filter=None, idv_name=None, dv_name=None, wres='CWRES', iwres='CIWRES') Plot #
绘制个体拟合图(个体预测值/群体预测值 vs. 实测值)。
参数:
filter (
Expr
, optional): 筛选条件,对于部分数据进行个体拟合图绘制。默认值为None
。idv_name (
str
, optional):因变量名。若为None
,则自动推断。默认值为None
。dv_name (
str
, optional):自变量名。若为None
,则自动推断。默认值为None
。wres (
Literal["CWRES", "CWRESI", "WRES", "WRESI"]
, optional):需要计算的加权残差类型(weighted residuals)。默认值为"CWRES"
。iwres (
Literal["CIWRES", "CIWRESI", "IWRES", "IWRESI"]
, optional):需要计算的个体加权残差类型(individual weighted residual)。默认值为"CIWRES"
。
示例:
fit_res.plot_predictions(filter=pl.col("SEX") == 0)
plot_trace()#
- plot_trace(self) Plot #
绘制迭代历史图(目标函数值与各模型参数估计值在迭代间的变动情况)。
示例:
fit_res.plot_trace().with_x_grid(visible=True).with_y_grid(visible=True)
vpc()#
- vpc(n_sample=1000, seed=1234, ci_level=0.95, percentile_level=0.95, auto_bin=True, min_points_in_each_bin=10, linear_interpolation=True, *, dv_name=None, idv_name=None) VpcResult #
运行模型可视化预测检验(Visual Predictive Check)。
参数:
n_sample (
int
, optional):抽样次数。默认值为1000
。seed (
int
, optional):随机种子号。默认值为1234
。ci_level (
float
, optional):模拟数据百分位数的置信水平。默认值为0.95
。percentile_level (
float
, optional):模拟数据与实测值的百分位数水平。默认值为0.95
,即取 2.5% 与 97.5% 分位数。auto_bin (
bool | int | tuple[int, int]
, optional):分箱(binning)方法。默认值为True
。具体方法如下:若为
True
,则使用自动分箱方法。若为
False
,则视每一个观测时间点为一个分箱。若为
int
,则视分箱数目为int
,将基于此数目计算每个箱体的范围。若为
tuple[int, int]
,则视箱体的范围为tuple[int, int]
,将基于此范围计算最终的分箱数目。
min_points_in_each_bin (
int
, optional):每个分箱中需包含的最少观测点数目。默认值为10
。linear_interpolation (
bool
, optional):是否进行线性化。默认值为True
。idv_name (
str
, optional):因变量名。若为None
,则自动推断。默认值为None
。dv_name (
str
, optional):自变量名。若为None
,则自动推断。默认值为None
。
返回值:
包含 VPC 图、置信区间数据、模拟数据等相关内容的检验结果。
返回类型:
VpcResult
示例:
vpc_res = fit_res.vpc(linear_interpolation=False)
vpc_res.plot()
[VPC] Preparing data...
[VPC] Running simulation...
[VPC] Done
Running Auto-bin...
Bin search ended, result is 10
Auto-bin completed, finally use 10 bins.
bootstrap()#
- bootstrap(n_sample=1000, seed=1234, level=0.95) BootstrapResult #
运行自举法(bootstrap)。
参数:
n_sample (
int
, optional):抽样次数。默认值为1000
。seed (
int
, optional):随机种子号。默认值为1234
。level (
float
, optional):参数估计值的置信水平。默认值为0.95
。
返回值:
包含估算成功率与抽样数据等相关内容的检验结果。
返回类型:
BootstrapResult
scm()#
利用 SCM 法(stepwise covariate modeling)进行协变量筛选。
参数:
spec (
MarkedScmSpecDefFunctionType | ScmSpec
):SCM 配置。可详见 ScmSpec。
返回值:
SCM 运行结果汇总。
返回类型:
ScmResult