Notebook 在复现数据科学研究成果中的丝滑使用

对于数据科学和 AI 科研人员而言，研究成果的复现至关重要。成果复现既是一种研究算法的方式，也有助于科研人员找到研究的新途径。

IDP 中提供自研 notebook 交互式编程环境，它非常适合做数据分析与代码展示，主要功能包括：智能开发、自适配环境、一键运行、一键连接数据源、各种其他平台工具集成、可视化工作流管理等等。

本文仅以展示可复现性研究成果为目标，来讲解如何利用 IDP 书写漂亮的 notebook。

研究成果复现的开发周期通常可分为三个阶段：组织和记录，代码的思想整理记录和为分享做准备。下面将对这三阶段进行依次展开。

一、组织和记录

“组织记录”，顾名思义就是记录完整的实验过程，其实验依赖应当完全参照论文内容的明确指示或者自我的实验设计细节。

广泛总结其他研究学者的经验，此阶段的 notebook 书写应当遵循以下几点：

1. 内容的故事性

IDP notebook 由代码、文本、SQL、数据可视化四部分组成，我们要利用好文本甚至多媒体在解释性方面的优秀表达，创建一个计算性的叙述，像为观众讲故事一样地介绍主题、排列步骤、解释结果，让这个故事变得更加引人入胜，在此时要对阅读故事的人群有一个预估，他是实验室的非技术同事、另一个实验室的分析师、某一期刊的读者还是公众？这决定了你要讲故事讲成什么样、语言描述的粒度大小。

图 1. IDP Notebook 组成

2. 更加注重过程而不是结果

IDP notebook 有很强的交互性，右边栏的变量管理器强大的功能进一步增强了这一点，这使得我们尝试和对比不同方法或参数更加快速和容易。但便捷的交互和参数管理功能，有时会使我们忽略了在执行这些交互式调研时将过程其记录下来（根源在于懒得新建一个 cell）。我们应当确保记录下所有的探索，甚至那些导致进入死胡同的探索！这些将帮助你记住做了什么和为什么做。不建议等到分析结束、得到了可靠结果后，才添加这样的解释性文字。正确做法是不要等，到那时你可能已经忘记了为什么选择某个特定参数值、从哪里复制了一段代码，或者中间结果的有趣之处是什么。如果你没有时间全面记录你此刻正在做什么或在想什么，那么留下简短的描述性笔记来提醒自己，在可以停下时抓紧把这些内容添加上。

图 2. IDP 工作区变量管理器

3. 将内容分区

IDP 的自研 notebook 是一个交互式的环境，所以它很容易编写和运行单行单元格，在实验过程中，可能会存在多个他人难以理解的短小代码单元格。这时，我们可以尝试添加一个有意义的分析步骤，用以划分单元块，还可以联动右边栏的大纲功能，实现随时跳转，准确定位。

细化来说，就是按单元格模块化代码，并在单元格上方用 markdown 标记。将每个单元格想象为一个段落、拥有一个函数或完成一个任务（例如，创建一个绘图）。避免长单元格（任何超过 100 行或一页的内容都太长了）。在代码注释中放入低级文档。使用描述性的 markdown header 将 notebook 分区，使其可以轻松导航和添加目录。将长 notebook 拆分为一系列 notebook，并保留一个 top-level index notebook，其中包含指向各个 notebook 的链接。

图 3. IDP 工作区大纲

二、代码的思想整理记录

到这一步实验已经基本完成，我们要让我们书写的 notebook 变得更加美观、合理，需要在以下几个方面整理笔记：

1. 遵循规则的重要性

面向对象的思想在代码工程中应用很多，此时也需要简单地遵循规则，以避免重复，在 notebook 中，复制一个单元格、调整几行、将生成的代码粘贴到新单元格或其他 notebook 中并再次运行是特别容易的，所以实验过程中难免留下一些重复代码，此时就应当将其用函数的形式包装起来，复杂一点的需要用到类，这取决于自己的判断。

需要注意的是，如果你要在其他项目或 notebook 中重用代码，请考虑将其转换为模块、包或库，并遵循良好的软件开发实践（如单元测试）。

2. 实验环境的配置

记录依赖项是一个非常重要的问题，这决定了你未来是否能重新生成分析，在计算机科学实验领域，建议一开始就使用诸如 conda 的 environment.yml 或 pip 的 requirements.txt 之类的工具明确地管理依赖项，以列出所有相关的依赖项（包括它们的软件版本）。始终在这些依赖项创建的环境中工作，以确保不添加未记录的依赖项。

在 notebook 中，你可以使用！pip install XXX.txt 一键安装依赖项，在工作区底部一键切换环境等等来完成实验配置，如果对 Linux 系统比较熟悉，也可以使用左边栏的终端功能，直接完成实验环境的配置。

3. 版本控制的妙用

IDP 工作区头部右侧的历史版本，可以实现版本控制，因为 notebook 的交互特性使其很容易意外地更改或删除重要内容。此外，由于 notebook 中包含代码，代码不可避免会有 bug，因此确定 bug 引入与修复的时间（及其可能影响的分析）是科学计算中的一项关键能力。

图 4. IDP 版本管理

4. 工作流的使用

实验研究稳定之后，可以考虑构建 pipeline，记录初步探索性研究的 notebook 很少能被广泛推广，但一旦确定了某种稳定的分析方法，设计良好的 notebook 就可以通过 pipeline 推广到其他任务中，从而使用不同的输入数据和参数很容易地重复分析。记住这一点，从一开始就设计你的 notebook，以允许将来重新调整用途。把关键变量声明（尤其是在进行新的分析时会改变的变量）放在 notebook 的顶部，而不是埋在中间的某个地方。直接在 notebook 中执行准备步骤，如数据清理，并尽可能避免手动干预。

通过构建 pipeline，也避免了他人在因为 ReadMe.txt 的阅读难度而影响复现结果。

图 5. IDP 可视化工作流管理

三、分享

分享是一项高瞻远瞩的主题，在书写 notebook 的时候考虑这一点似乎有些“鸡肋”，实际上分享、交流才是实验研究走得更远的基石，以下几点需要注意。

1. 可读性

分享的内容一定要具有可读性，特别是对于实验数据，需要详细又清晰的解释。理想情况下，你可以在 notebook 中共享整个数据集。我们认识到许多数据集太大或太敏感，无法以这种方式共享。在这些情况下，考虑将大型和复杂的数据集分解为多个层次，这样即使原始数据太大，无法与已发布的 notebook 一起共享，或者受到隐私或其他访问问题的限制，也不会影响到可复现性。