hypernotes

hypernotes是一个轻量级的Python包，用于在您的机器学习实验中记笔记。它提供了一种简单的方法来存储超参数、它们对应的评估指标以及附加信息，并在稍后进行分析时再次检索它们。它使用纯Python编写，无需额外的依赖项。

目录

• 安装
• 基本用法
  • 创建笔记并添加到存储中
  • 加载笔记
  • 更新笔记
  • 删除笔记
  • 从另一个笔记创建笔记
• 附加功能
  • 在浏览器中查看存储内容
  • 存储附加对象
• 替代方案
• 开发

此包的变更日志

安装

pip install hypernotes

需要Python 3.6+

基本用法

hypernotes实现了笔记和存储类。一个笔记是Python字典的小型包装器。这意味着您可以像使用普通字典一样使用它，但除此之外，它还存储

• 您Python可执行文件的路径，
• 有关您Git仓库当前状态的信息（如果有），例如最后提交、当前分支等，
• 开始时间（初始化时）和结束时间（调用note.end()或添加到存储中），

并且它提供了

• 有用的默认字典结构
• 将所有初始字典键作为属性以支持更好的自动补全和可读性（例如 note.parameters、note.features）

打印笔记时，可以看到其内容。初始化后的笔记如下所示

Note(content={'text': '',
 'model': None,
 'parameters': {},
 'features': {'identifier': [],
              'binary': [],
              'categorical': [],
              'numerical': []},
 'target': None,
 'metrics': {},
 'info': {},
 'start_datetime': datetime.datetime(2019, 5, 21, 11, 3, 20),
 'end_datetime': None,
 'identifier': '3228fe02-d1c8-4251-8b35-bb8ae3d5f227',
 'python_path': 'C:/example_path/python.exe',
 'git': {'repo_name': 'C:/path_to_your_repo',
         'branch': 'master',
         'commit': '6bbdf31'}}

然后使用一个 Store 实例保存笔记，该实例使用 json 文件。因此，您只能将 json 序列化对象 + datetime.datetime 实例添加到 Note。

笔记可以通过其 identifier 属性唯一识别。

创建笔记并添加到存储中

from hypernotes import Note, Store

note = Note("Some descriptive text about your experiment")

# Add name of used algorithm
note.model = "randomforest"

# Add hyperparameters about model training, preprocessing, etc.
note.parameters["num_estimators"] = 100
note.parameters["impute_missings"] = True

# Add the names of the features and of the target variable
note.features["identifier"] = ["id"]
note.features["binary"] = ["bool1"]
note.features["categorical"] = ["cat1", "cat2"]
note.features["numerical"] = ["num1"]
note.target = "target"

# Some additional information
note.info["important_stuff"] = "something noteworthy"

# ... Rest of your code ...
# train_recall, train_precision test_recall, test_precision = train_and_evaluate_model(
#                                              parameters=note.params,
#                                              feature_names=note.features,
#                                              target_name=note.target)
# ...

# Add your calculated evaluation metrics
note.metrics["train"] = {"recall": train_recall, "precision": train_precision}
note.metrics["test"] = {"recall": test_recall, "precision": test_precision}

store = Store("hyperstore.json")
store.add(note)

加载笔记

Store 实例提供了一个 load 方法，可以用来检索整个存储库。默认情况下，它返回一个按时间排序的列表（最新笔记优先）。

notes = store.load()
most_recent_note = notes[0]

如果您已安装 pandas，您可以使用 return_dataframe 参数返回一个 pandas 数据框。

notes_df = store.load(return_dataframe=True)
notes_df.head()

返回的 pandas 数据框示例

更新笔记

如果您想更新笔记，可以直接在包含笔记的 json 文件中更新，或者按上述方式加载笔记，更改相关内容，并将其传递给 update 方法。

notes = store.load()
updated_notes = []
for note in notes[:2]:
    note.info["something_new"] = "..."
    updated_notes.append(note)

store.update(updated_notes)

删除笔记

如果您想删除笔记，可以直接在包含笔记的 json 文件中删除，或者按上述方式加载笔记，并将要删除的笔记传递给 remove 方法。

notes = store.load()
notes_to_remove = notes[:2]
store.remove(notes_to_remove)

从另一个笔记创建笔记

在评估多个模型参数（例如在网格搜索设置中）时，您可能发现为每个参数集创建一个新的笔记很有用。为此，您可以使用 from_note 方法从现有笔记创建一个新的笔记。这将复制所有现有内容，但也会设置新的开始时间和标识符。创建后，笔记是独立的，即修改一个不会影响另一个。

original_note = Note("Original")
new_note = Note.from_note(original_note)

附加功能

在浏览器中查看存储内容

要快速查看存储库，您可以使用命令行中的包。它将启动一个 http 服务器，并自动在您的网络浏览器中打开相关页面。该页面包含一个交互式表格，显示了存储库中所有笔记的最相关信息，例如指标和参数。该表格的样式类似于加载笔记部分中所示的表格。

$ python -m hypernotes hyperstore.json

这只需要一个现代网络浏览器以及互联网连接来加载一些 JavaScript 库和 CSS 文件。

要查看所有可用选项，请传递 --help 参数。

存储附加对象

如果您想存储实验的更大工件，例如训练好的模型，您可以创建一个单独的文件夹，并使用笔记的标识符作为名称的一部分。

experiment_folder = f"experiment_{note.identifier}"

然后您可以将任何其他对象存储到这个文件夹中，并将它们链接到使用 hypernotes 存储的超参数和指标将变得非常简单。

替代方案

如果您需要更好的多用户功能、更高级的可重现性功能、数据集版本控制等，请检查MLflow、Sacred 或 DVC 等工具。

开发

如果您发现错误或缺少功能，请随时在 GitHub 上打开一个问题或提交一个 pull request。

开发包所需的所有要求都可以使用以下方式安装：

pip install -r requirements_dev.txt

确保所有由tox运行的测试都通过。