该指标时间线 (TMT) ⌚

That Metric Timeline (TMT) 是一个针对机器/深度学习从业者/研究人员的 Python 库。该图书馆旨在：

• 帮助用户跟踪实验、他们的指标、他们的结果和用于产生它们的代码；
• 为用户提供易于使用且基于KISS的库；
• 做最少的事情（即没有花哨的网络界面、绘图等），但（希望）做对；
• 向社区提供一个开源的实验跟踪库，在“免费啤酒”和“言论自由”中都是免费的。

在从事研究项目时，我看到很多次实验的数量在眨眼间飙升......然后当我们在“休息一段时间”后回到我们的项目时，我们可能已经忘记了在哪里结果是，产生它们的代码是什么等等。
这个库有望成为所有这些的解决方案:)

阅读ReadTheDocs上的完整文档。

安装

该库在 PyPI 上可用，并且可以安装

pip install ThatMetricTimeline

成功安装后，tmt_tui您的路径中将提供一个二进制文件。这是图书馆终端用户界面 (TUI)。稍后再详述。

用法

tmt可以跟踪您的实验。每个实验都将作为一个条目保存在 json 数据库中，结果和代码快照备份[^1] 保存在不同的文件夹中。默认情况下，tmt将：

• 在您当前的工作目录中创建一个.tmt目录；
• 创建一个.tmt/tmt_db.json将用作数据库的文件；
• 创建一个.tmt/snapshots目录，将保存代码快照备份。.tmt/snapshots/last还将创建一个符号链接，并将始终指向最后拍摄的快照。有关更多详细信息，请参阅快照部分。

如果您想更改所有这些内容的保存位置，请查看自定义配置部分。此存储库的文件夹中
提供了代码示例。examples将来会添加更多示例。

[^1]：代码备份被视为“快照”。这意味着第一次它将是您所有文件的标准副本（您可以提供一个.gitignore文件以忽略文件）。以下备份将仅复制新的和更改的文件，而其他所有内容都作为硬链接复制（因此不占用磁盘空间）。

跟踪实验

虽然未来可能会出现更多可选功能，但库的目标是简单，对用户和库开发人员都是如此。
暴露出来的主要功能tmt其实就是tmt_recorder装饰器。这是我们用来实际存储和跟踪实验的东西。

装饰器接受一个name参数（以及一些可选参数）。实验将被保存并稍后使用此名称进行搜索。
装饰函数可能会返回一个字典，其中包含用户希望保存以供以后检索的指标。如果您不想保存任何指标，该函数必须返回None一个空对象（例如{}）。

from tmt import tmt_recorder

@tmt_recorder(name="some_experiment")
def train_and_predict(x_tr, y_tr, x_te, y_te):
    lr = LogisticRegression()
    lr.fit(x_tr, y_tr)
    preds = lr.predict(x_te)
    return {'f1': f1_score(y_te, preds), 'accuracy': accuracy_score(y_te, preds)}

tmt暴露的另一个关键功能是tmt_save. 用户应随时调用此函数来保存任何类型的可拾取对象。
如果我们想保存上面示例中的预测，我们会这样做：

from tmt import tmt_recorder, tmt_save

@tmt_recorder(name="some_experiment_with_data")
def train_and_predict(...):
    ...
    preds = lr.predict(x_te)
    tmt_save(preds, name='lr_predictions')
    return {'f1': f1_score(y_te, preds), 'accuracy': accuracy_score(y_te, preds)}

如您所见，我们也为保存的对象命名。这应该更容易识别这个腌制对象所指的内容。

途易

搜索和查看实验

tmt提供了一个终端用户界面 (TUI)，当您pip install使用库时，它应该安装在您的路径中。您可以通过键入以下内容访问 TUI：

tmt_tui

如果您使用的是自定义配置（请参阅自定义配置），请按如下方式指定：

tmt_tui -c /path/to/your/config.json

您将看到以下老式界面（谁不喜欢 90 年代？）：

您可以使用箭头（或 tab 和 shift+tab）键四处移动。然后，您可以在此界面中按名称搜索（支持正则表达式！）：

选择实验后，您可以看到有关它的一些详细信息：

按日期搜索实验功能尚未实现，将在未来版本中提供。但是，您可以使用TmtManager（请参阅下一节）。

在代码中加载和使用跟踪的实验

tmt提供了一个简约的TmtManager帮助类，它可以帮助您在代码中加载实验、加载腌制结果、查看指标等。
一旦您有了 ID（或实验的唯一名称），您就可以：

from tmt import TmtManager

# Let's say we know there is an experiment with id "example"


# An Entry is a row in the database, i.e. an experiment that was tracked.
manager = TmtManager()
manager.set_entry_by_id('example') 

# load the results and unpickle them
for name, path in manager.results_paths():
    with open(path, 'rb') as f:
        # do stuff with your results. If it's a pickle it's 
        # more convenient to use the code block below this one
        res = pickle.load(f)

# load the unpickled results
for name, res in manager.load_results():
    # do something with your results.
    # if res is a numpy array...
    print(res.mean())


for name, val in manager.get_metrics():
    print(f"{name}: {val}")

如果需要，可以从成员访问“低级”数据库管理器manager.db。

# If you need to do other stuff, like searching for 
# experiments between two datetimes and so on
# you can access the `db` member like
manager.db.get_entries_greater_than_date(date_or_timestamp)

# You can also search names with a regex
manager.db.get_entries_by_name_regex(r'experiment\d+')

快照

每次使用 跟踪实验时tmt_recorder，都会保存一个代码快照备份（默认情况下在 中.tmt/snapshots）。这意味着：

• 当您第一次在项目中使用该库时，会制作一个简单的项目副本（默认情况下，这是您启动实验的当前工作目录 ( cwd )）；
• 随后的备份将仅复制新的和不同的文件，同时硬链接所有其他文件。这限制了磁盘上占用的空间；
• 默认情况下，该库将.gitignore在您的cwd中查找文件并忽略（即，不复制）其中列出的所有文件（PathSpec库用于 gitignore 解析；
• 指向最后拍摄的快照的符号链接在.tmt/snapshots/last.

您可以使用自定义配置文件更改默认路径。

自定义配置

tmt可以按原样使用，不需要任何配置文件。默认情况下，库需要或保存的所有内容都存储在.tmt当前工作目录 ( cwd ) 中的隐藏目录中。如果您的cwd经常因不同的实验而更改，或者您想指定备份哪个文件夹等等，您可能需要创建并指定一个自定义配置文件。

为此，请创建一个config.json文件：如果您可以使用该cwd/.tmt目录，请将此文件放在cwd/.tmt/config.json. 这样，您就不必将此配置文件的路径指定到库相关函数。
配置文件具有以下结构

{
    // tmt_dir specifies the path where code snapshots and 
    // results will be saved. You may use an absolute 
    // path as well
    "tmt_dir": ".example",

    // this is the folder we will take a snapshot of 
    // for every experiment  
    "snapshot_source": ".", 

    // snapshot_target is where code snapshots will be 
    // saved. It will be joined with tmt_dir. So in this 
    // case the target will be .examples/snapshot_example
    "snapshot_target": "snapshot_example",

    // this path will be a symlink to the last snapshot
    // taken. Same rules as for snapshot_target apply
    "last_snapshot_link": "snapshot_example/last",

    // this might actually be any file with a .gitignore 
    // syntax. These files will be ignored and not backupped
    "gitignore_path": "path/to/.gitignore",

    // the two paths below are for the db and the results
    // directory, respectively. Same rules apply as for 
    // snapshot_target, so path will be .example/tmt_db.json
    "json_db_path": "tmt_db.json",
    "results_path": "results"
}

如前所述，如果您将此文件保存在 中.tmt/config.json，则无需执行其他操作，并且tmt会将其拾取并用于其配置。
相反，如果您将其保存在其他地方，例如/config/path/config.json，您将不得不在代码中指定此路径。记录实验时：

@tmt_recorder('custom_config', config_path='/config/path/config.json')
def with_custom_config():
    x, y = make_classification()
    lr = LogisticRegression()
    lr.fit(x, y)
    preds = lr.predict(x)
    return {'f1': f1_score(y, preds), 'accuracy': accuracy_score(y, preds)}

在管理实验时：

manager = TmtManager(config='/config/path/config.json')
# do your stuff

最后的评论

开发这个项目主要是因为我想要一个简单的库来跟踪我在博士论文中运行的机器学习实验（而且，因为我玩得很开心：D）。
我很清楚目前还有其他选项，例如Weights& Biases和ModelChimp，但我想要一些尽可能简单明了的东西。
该项目的目标应该是保持KISS方法，使其他研究人员更容易修补库代码或进行调整。
出于这个原因，没有提供太多的自动化，例如，导航快照留给用户：当您想快速检查许多实验的代码时，这可能会很痛苦，我确实计划添加更好和更多自动化的方式来做到这一点。
也就是说，大多数其他库功能将保持原样。

如果您有任何建议、反馈或问题，请随时在 Github 上打开问题或拉取请求。
干杯!