TP TreeAge Pro中文帮助中心

使用调试函数控制输出

大多数情况下,您会使用树偏好设置来控制写入计算追踪控制台的调试信息。不过,您也可以将调试函数直接放入模型中来生成调试信息。

下表列出了可用于调试模型的专用命令。

重要提示: 所有这些命令的值都为零(“0”),可以添加到表达式中而不改变表达式的值。

函数语法 说明

DebugOn()

此前为 Debug("1")

开启计算追踪设置。发出此命令后,所有内部计算都会被写入计算追踪控制台。

DebugOff()

此前为 Debug("0")

关闭计算追踪设置。发出此命令后,内部计算不再写入计算追踪控制台。
DebugExport(filename)

将计算追踪控制台的当前内容导出到指定位置的指定名称的 .txt 文件。

以下是一个可用以替换 file 的示例:

filename = path + "name_of_file" + Str(\_trial) + ".txt"

其中

path = "X:\\Testing\\DocModels\\Output_files\\";

name_of_file = 保存导出内容时所用文件的新名称;

Str(\_trial) = 模型中当前 \_trial 的编号;以及

.txt = 设置文件类型。

DebugExport(index)

将计算追踪控制台的当前内容导出到与模型同名的文件,文件名后接 "_trace_" 再加上索引,文件扩展名为 .txt。

该 .txt 文件将位于原始模型所在的同一文件夹中。

DebugClear()

清除计算追踪控制台中的所有输出。

DebugWrite(text)

将文本参数发送到控制台,并在其前后各加一个空行。请注意,只有在通过树偏好设置(全部或选定元素)或通过 DebugOn() 函数开启调试时,文本才会被写入。

DebugWriteForce(text)

将文本参数发送到控制台,并在其前后各加一个空行。请注意,无论调试输出是开启还是关闭,文本都会被写入。

DebugTime()

将当前日期/时间(包括毫秒)写入控制台。请注意,只有在通过树偏好设置或 DebugOn() 函数开启调试时,文本才会被写入。

DebugTimeForce(text)

将当前日期/时间(包括毫秒)写入控制台。请注意,无论调试输出是开启还是关闭,文本都会被写入。

如果 Debug() 函数要求开启调试输出,那么可以通过在树偏好设置中开启“显示以下输出:全部(Show Output for All)”,或使用 DebugOn() 函数来实现。

Debug() 函数与一些专门用于在蒙特卡洛分析中选择单个试验的关键字结合使用时可能很有用。关于这些关键字的更多信息,请参见自定义模拟(Customizing Simulations)一节,特别是其中关于蒙特卡洛特殊变量(Monte Carlo special variables)的部分。模型调试与验证(Model Debugging and Validation)一章提供了使用若干调试工具来调试模型的示例。

以下是使用 Debug() 函数的几个示例。

示例:动态使用计算追踪

将计算追踪打开以查看特定计算以及模型出错的原因,通常很有用。对于计算量很大的模型,为所有试验(微观模拟)和抽样(敏感性分析)都打开计算追踪是不可行的。计算追踪可能需要很长时间才能到达模型出错的位置。

在这些情况下,可能不必查看所有试验的计算追踪控制台内部计算,但您可能想查看某个特定试验的数值。

要定位特定试验的计算

请查看特别功能示例模型 Debug MicrosimulationCancerModel.trex。

假设蒙特卡洛模拟中的试验 999 出现了错误。为了只查看试验 999 的内部计算,该模型中包含以下定义:

  • 创建一个特殊模拟变量,在试验 999 运行模型之前开启计算追踪:_monte_pre_trial_eval = if(_trial=999; DebugOn(); 0)。

  • 特殊变量/关键字 _monte_pre_trial_eval 是 TreeAge Pro 的内置关键字。它确保其所赋的表达式会在模型中每次试验求值之前先求值。在本例中,如果 _trial = 999,该表达式将使用 DebugOn() 开启调试功能;否则该表达式不做任何事。

  • 创建一个特殊模拟变量,在试验 999 完成模型计算之后关闭计算追踪:_monte_post_trial_eval = if(_trial=999; DebugOff(); 0)。

  • 特殊变量/关键字 _monte_post_trial_eval 是 TreeAge Pro 的内置关键字。它确保其所赋的表达式会在模型中每次试验求值之后求值。在本例中,如果 _trial = 999,该表达式将使用 DebugOff() 关闭调试功能;否则该表达式不做任何事。

用 2,000 次试验运行该模型的微观模拟,计算追踪控制台中只会显示一份输出,即 _trial = 999 的计算。

其他类似 _monte_pre_trial_eval 的有用关键字也可用于自定义模型。它们可在自定义模拟(Customizing simulations)一节中找到。

示例:定位分布抽样错误

一种常见的分析错误(Analysis Error)与分布有关。分布在被独立抽样时可能定义得当。然而,多个分布抽样的组合可能会导致分析过程中出现概率错误。下图显示了一条典型的错误消息,它是在对特别功能示例模型 Debug WriteForce MarkovCancer.trex 运行概率敏感性分析时产生的。

打开示例模型 Debug WriteForce MarkovCancer.trex,查看其中的两个分布。

Dist_p_Local_Death 和 Dist_p_Local_Mets 都是 Beta 分布,参数相同,均值为 0.4,标准差为 0.1。

两个分布都按期望值抽样,因此当我们运行概率敏感性分析时,模型的每一次重新计算都会重新从分布中抽样。

在树偏好设置中,我们选择开启随机种子(seeding)和线程(threading)。开启随机种子是为了反复重现相同的结果。如果您要在一个随机数种子变化时结果就不断变动的模型中定位问题,这是一项很有用的技巧。我们选择以单线程(“1”)运行模型,这意味着计算必须按顺序进行。有关这些选项的更多信息,请参见树偏好设置一节。

选中决策节点,然后选择分析(Analysis)> 概率敏感性分析(Probabilistic Sensitivity Analysis)来运行模型。运行 100 次抽样。错误消息应与上图类似。

为了调试此模型,我们创建了一个变量,可将其添加到模型中的任何变量上,以查看特定输出。该变量为:

outputDebug = DebugWriteForce("Sample= " + str(_sample) + ", Prob LocToMets=" + str(Dist_p_Local_Mets) + ", Prob LocToDead=" + str(Dist_p_Local_Death))

来看一下变量 outputDebug 的前几个元素:

  • DebugWriteForce( text here ):这是指示模型将“text here”位置的内容写入控制台的命令。即使树偏好设置中关闭了调试,该命令也会生效。

  • "Sample = " + str(_sample):这是包含在函数 DebugWriteForce 可执行部分内的一些文本。它包含三个元素:

    • 引号:写在 " " 之内的任何内容都会被写入控制台。此处为 "Sample = "。

    • “ + ”号:用于连接表达式。此处会先输出 "Sample = ",随后是 str(_sample) 的解析结果。

    • str(_sample):函数 str() 会将括号中的内容转换为用于屏幕显示的文本。本例将关键字 _sample(获取当前抽样编号)转换为字符串。在概率敏感性分析(PSA)中,我们预期每个 PSA 抽样都会有一个新的抽样编号。

构成该变量的其他元素也类似。不同之处在于,写入屏幕的不是抽样编号,而是分别写入 Dist_p_Local_Mets 和 Dist_p_Local_Death 的值。

变量 outputDebug 可以添加到模型中的任意位置。由于所有调试函数的值都是 0,把这个变量加进模型中的其他变量不会影响计算出的数值。在示例模型中,我们把这个变量加到了 Local Cancer > Progress to Metastases 分支下的概率表达式上。下图显示的是错误(Error)出现前一刻“计算控制台追踪(Calculation Console Trace)”中的输出。

现在就可以在模型中定位这个错误了。Local Cancer 节点上所有概率之和必须等于 1。通过在 Stay Here 分支下加入“#”,模型会先计算另外两个分支上的概率,然后再计算 Stay Here 分支上的概率。上面的输出表明,当 PSA 运行到第 4 个抽样样本时,由 Beta 分布生成的取值分别为 pLocalToMets = 0.365、pLocalToDeath = 0.663。仅这两个值之和就已经大于 1,因此模型无法确定 Stay Here 分支下的概率。这两个分布本身虽然都有效,但示例模型需要重新考虑它们组合后的概率。

此外,关于为 DebugWrite 与 DebugWriteForce 函数创建字符串表达式的语法,请参阅字符串处理(String Processing)一节。