模型数据相关 API#
在 Masmod 中，我们使用 polars.DataFrame 类的对象作为模型数据用于数据检视，模型拟合与模拟等场景。对于 polars.DataFrame 的入门以及使用技巧可参考 Python 数据科学入门。
在群体建模场景下，我们使用与 NONMEM 互相兼容的数据列映射，如 ID, TIME, DV 等。此外，我们也可以通过 EventTable() 工具来快速构建符合不同场景的模拟数据集用于模型模拟。
from mas.datasets import warfarin
import polars as pl
数据检视#
plot_profile()#
- plot_profile(data, scatter=True, line=True, idv_name=None, dv_name=None, **style) Plot#
绘制因变量与自变量的折线图。
参数：
data (
DataFrame)：数据集。scatter (
bool, optional)：是否在图形中绘制散点。默认值为True。line (
bool, optional)：是否在图形中绘制折线。默认值为True。idv_name (
str, optional)：因变量名。若为None，则自动推断。默认值为None。dv_name (
str, optional)：自变量名。若为None，则自动推断。默认值为None。**style: 样式相关设置
返回值：
绘制完成的因变量与自变量折线图。
返回类型：
Plot
from mas.model import plot_profile
plot_profile(warfarin.filter(pl.col("DVID") == 1)).with_facet_wrap("SEX")
plot_covariates()#
- plot_covariates(data, *, categorical=None, include=None, **style) GridPlot#
- plot_covariates(data, *, categorical=None, exclude=None, **style) GridPlot#
绘制协变量矩阵图。
参数：
data (
DataFrame)：数据集。categorical (
list[str], optional)：需要作为分类变量的列名。若为None，则自动推断。默认值为None。include (
list[str], optional)：需要纳入的协变量。若为None，则纳入所有列。默认值为None。exclude (
list[str], optional)：需要剔除的协变量。若为None，则无剔除列。默认值为None。**style: 样式相关设置
返回值：
绘制完成的协变量矩阵图。
返回类型：
GridPlot
from mas.model import plot_covariates
plot_covariates(warfarin, categorical=["SEX"], exclude=["DVID"]).with_layout(width=600, height=600)
plot_bivariate()#
- plot_bivariate(data, dvid_name='DVID', idv_name=None, dv_name=None, dvid_x=1, dvid_y=2, **style) Plot#
绘制两类因变量的关系折线图。
参数：
data (
DataFrame)：数据集。dvid_name (
str, optional)：作为DVID使用的列名，默认为"DVID"。idv_name (
str, optional)：因变量名。若为None，则自动推断。默认值为None。dv_name (
str, optional)：自变量名。若为None，则自动推断。默认值为None。dvid_x (
str | int | float, optional)：作为x使用的DVID值，默认为1。dvid_y (
str | int | float, optional)：作为y使用的DVID值，默认为2。**style: 样式相关设置
返回值：
绘制完成的两类因变量的关系折线图。
返回类型：
Plot
from mas.model import plot_bivariate
plot_bivariate(warfarin, dvid_x=1, dvid_y=2).with_title(text="两变量关系图")
NONMEM 数据录入#
read_nonmem_data()#
- read_nonmem_data(path, ignore='#', encoding='utf-8', columns=None) DataFrame#
读取本地 NONMEM 数据文件为 DataFrame
参数：
path (
PathLike)：NONMEM 数据文件的路径。ignore (
str, optional)：忽略以ignore开头的行。与 NONMEM 控制文件中$DATA的IGNORE功能一致。默认为"#"。encoding (
str, optional)：数据文件编码。默认值为"utf-8"columns (
list[str | NonmemDrop], optional)：数据集列名。与 NONMEM 控制文件中$INPUT功能一致。若为None，则将使用Unnamed_i作为列名，i为列的索引序号。默认值为None。
返回值：
读取自 NONMEM 数据集的 DataFrame 数据框。
返回类型：
DataFrame
EventTable#
EventTable 是一个非常实用的工具类，它能够帮助我们快速的构建出可以用于模型模拟或者拟合的标准格式的数据集。通过 EventTable 你可以对一个现有数据添加一系列新的观测点，也可以模拟不同给药场景。又或者我们可以通过 EventTable 从零开始创建一个全新的数据集。
- class EventTable(data=None, schema=None)#
构造 EventTable 对象
参数：
data (
FrameInitTypes, optional)：起始数据集。如果为None则从空数据开始构建。默认值为None。schema (
SchemaDefinition, optional)：数据集的列名以及列类型定义。如果为None则自动推断。默认值为None。
小技巧
data 和 schema 参数的使用方法可以另见：polars.DataFrame。
doses#
- property doses#
获取数据中的给药数据。
类型：
DataFrame
observations#
- property observations#
获取数据中的观测数据。
类型：
DataFrame
add_dosing()#
- add_dosing(self, time, amt, id=None, cmt=None, addl=None, ii=None, dur=None, rate=None, ss=None) Self#
向 EventTable 中添加给药记录。
参数：
time (
Numeric| Numeric)：给药时间。amt (
Numeric| Numeric)：给药剂量。id (
IdLike, optional)：需要增加给药记录的受试者编号。若为None，则为所有受试者增加给药记录。默认值为None。addl (
Int, optional)：额外给药次数。默认值为None。ii (
Numeric, optional)：给药间隔。默认值为None。cmt (
Int, optional)：给药房室编号。默认值为None。rate (
Numeric, optional)：给药速率。若为正数，将视为滴注速率；若为0，将视为推注给药；若为-1，则意为将对给药速率建模；若为-2，则意为将对给药持续时间建模。不能与dur同时设置。默认值为None。dur (
Numeric, optional)：给药持续时间。不能与rate同时设置。默认值为None。ss (
Numeric, optional)：稳态标记。默认值为None。
返回值：
更新后的 EventTable
返回类型：
EventTable
add_sampling()#
- add_dosing(self, time, id=None) Self#
向 EventTable 中添加观测记录。
参数：
time (
VectorLike | Numeric)：观测时间。id (
IdLike, optional)：需要增加观测记录的受试者编号。若为None，则为所有受试者增加观测记录。默认值为None。
返回值：
更新后的 EventTable
返回类型：
EventTable
with_covariates()#
- with_covariates(self, *, id=None, **kwargs) Self#
为 EventTable 添加协变量。
如果不提供 id，则协变量只能填写单一值，该值会应用到当前数据集中的每一行上。如果提供 id，则会根据 id 设置协变量。
参数：
id (
Int, optional)：需要添加协变量的受试者编号。若为None，则为所有受试者添加协变量。默认值为None。**kwargs: 协变量，如
WT=60
返回值：
更新后的 EventTable
返回类型：
EventTable
with_ids()#
- with_ids(self, *, ids, reset_id=False) Self#
为 EventTable 根据提供的 id 执行扩展。
参数：
ids (
Iterable[Int])：需要扩展的id。reset_id (
bool, optional): 如果当前EventTable存在id是否需要重置。默认值为False
返回值：
更新后的 EventTable
返回类型：
EventTable