Lace

将“科学”融入“数据科学”

一个快速、可扩展的概率交叉分类引擎。

Lace 是一个用 Rust 编写的概率交叉分类引擎，具有可选的 Python 接口。与传统的机器学习方法不同，Lace 学习数据集上的联合概率分布，使用户能够...

• 预测或计算任何数量特征的似然度，条件是任何数量的其他特征
• 从数据的方差、模型中的认知不确定性和缺失特征中识别、量化和归因不确定性
• 确定哪些变量是预测其他变量的
• 确定哪些记录/行在整体或特定上下文中与其他记录/行相似
• 模拟和操作合成数据
• 与缺失数据原生工作，并对缺失性进行推理（缺失非随机）
• 与连续和分类数据原生工作，无需转换
• 识别数据中的异常、错误和不一致性
• 编辑、填充和追加数据，无需重新训练

更多功能，全部在一个地方，无需任何显式模型构建。

设计

Lace使用交叉分类学习表格数据的概率模型。操作的通用步骤是

• 创建一个描述您的数据的prelude::Codebook。一个可以自动生成，但最好在使用前检查它。
• 使用您的数据和代码簿创建一个prelude::Engine。
• 训练prelude::Engine并监控模型似然度以实现收敛。
• 通过prelude::Engine的prelude::OracleT实现提出问题以探索您的数据。

示例

（有关完整教程，请参阅Lace Book）

以下示例使用预训练的animals示例数据集。每一行代表一个动物，每一列代表该动物的特征。如果单元格值为1，则表示特征存在；如果值为0，则表示特征不存在。

首先，我们创建一个预言者和导入一些enum，允许我们用普通的英语调用一些行和列索引。

use lace::prelude::*;
use lace::examples::Example;

let oracle = Example::Animals.oracle().unwrap();
// You can also load trained-metadata using the command:
// let engine = Engine::load("my-metadata.lace")?;

让我们了解一下游泳和速度快或是否有鳍之间的统计依赖性。我们预计会游泳的东西比速度快更能表明它是否会游泳，因此我们预计游泳和鳍之间的依赖性会更高。

let depprob_fast = oracle.depprob(
    "swims",
    "fast",
).unwrap();

let depprob_flippers = oracle.depprob(
    "swims",
    "flippers",
).unwrap();

assert!(depprob_flippers > depprob_fast);

我们对互信息的预期相同。互信息需要用户更多的输入。如果我们需要估计互信息，我们需要知道互信息的类型以及需要抽取多少样本。

let mi_fast = oracle.mi(
    "swims",
    "fast",
    1000,
    MiType::Iqr,
).unwrap();

let mi_flippers = oracle.mi(
    "swims",
    "flippers",
    1000,
    MiType::Iqr,
).unwrap();

assert!(mi_flippers > mi_fast);

我们同样可以询问行（在这种情况下，动物）之间的相似性。

let wrt: Option<&[usize]> = None;
let rowsim_wolf = oracle.rowsim(
    "wolf",
    "chihuahua",
    wrt,
    RowSimilarityVariant::ViewWeighted,
).unwrap();

let rowsim_rat = oracle.rowsim(
    "rat",
    "chihuahua",
    wrt,
    RowSimilarityVariant::ViewWeighted,
).unwrap();

assert!(rowsim_rat > rowsim_wolf);

我们还可以向相似性添加上下文。

let context = vec!["swims"];
let rowsim_otter = oracle.rowsim(
    "beaver",
    "otter",
    Some(&context),
    RowSimilarityVariant::ViewWeighted,
).unwrap();

let rowsim_dolphin = oracle.rowsim(
    "beaver",
    "dolphin",
    Some(&context),
    RowSimilarityVariant::ViewWeighted,
).unwrap();

入门

要作为库使用Lace，只需将其添加到您的Cargo.toml

[dependencies]
lace = "*"

安装CLI

cargo install --locked lace

从源安装

$ cargo install --path .

构建API文档

$ cargo doc --all --no-deps

运行测试

$ cargo test --all

请注意，当构建脚本运行时，示例文件会被移动到您的数据目录。一旦您为示例之一请求了一个Oracle，如果它不存在，lace将构建元数据。如果您需要重新生成元数据——比如说元数据规范已更改——您可以使用以下CLI命令进行操作

$ lace regen-examples

标准CLI工作流程

CLI使一些事情比在Rust或Python中更容易。从命令行生成代码簿和运行模型更为简单。

代码簿

代码簿告诉Lace如何对您的数据进行建模——每种特征可以包含什么类型的数据；如果是分类的，它们可以取什么值；它们的先验（和超先验）分布应该是什么；等等。由于代码簿与您数据的大小成比例，最好从一个使用合理默认值的模板代码簿开始，如果需要，再对其进行编辑（通常不需要）。

从CSV文件生成模板代码簿

$ lace codebook --csv mydata.csv codebook.yaml

在您最喜欢的编辑器中打开代码簿以调整代码簿。您可以在用户指南中找到编辑代码簿的提示和完整的代码簿参考。

运行推理

您可以使用Rust或CLI运行推理（拟合模型）。

使用Rust

use rand::SeedableRng;
use rand_xoshiro::Xoshiro256Plus;
use polars::prelude::CsvReader;
use lace::prelude::*;

// Load a dataframe
let df = CsvReader::from_path("mydata.csv")
    .unwrap()
    .has_header(true)
    .finish()
    .unwrap();

// Create a codebook
let codebook = Codebook::from_df(&df).unwrap();

// Build the engine
let mut engine = Engine::new(
    16,
    codebook,
    DataSource::Polars(df),
    0,
    Xoshiro256Plus::from_entropy(),
).unwrap();

// Run the fit procedure. You can also use `Engine::update` if
// you would like more control over the algorithms run or if you
// would like to collect different diagnostics.
engine.run(1000).unwrap();

// Save the model
engine.save("mydata.lace", SerializedType::Bincode).unwrap();

您还可以使用命令行界面。使用默认的代码簿和设置运行csv文件的推理，并保存到mydata.lace

$ lace run --csv mydata.csv --codebook codebook.yaml mydata.lace

如果您没有指定代码簿，则会后台生成默认代码簿。

您可以通过两种方式指定要使用的转换和算法。您可以使用命令行参数

$ lace run \
    --csv mydata \
    --row-alg slice \
    --col-alg gibbs \
    --transitions=row_assignment,view_alphas,column_assignment,state_alpha \
    mydata.lace

或者您也可以提供运行配置

# runconfig.yaml
n_iters: 4
timeout: 60
save_path: ~
transitions:
  - row_assignment: slice
  - view_alphas
  - column_assignment: gibbs
  - state_alpha
  - feature_priors

上面我们运行了32个状态1000次迭代或10分钟（600秒）。

$ lace run \
    --csv mydata \
    --run-config runconfig.yaml \
    mydata.lace

请注意，如果提供了运行配置，则无法使用运行配置中覆盖的任何命令行参数。

我们可以使用-s指定状态（样本）的数量，使用-n指定要运行的迭代次数，并使用--timeout指定状态应运行的最大秒数。

$ lace run --csv mydata.csv -s 32 -n 1000 --timeout 600 mydata.lace

我们可以通过传递要运行的引擎来扩展运行（添加更多迭代）。

$ lace run --engine mydata.lace -n 1000 mydata-extended.lace

许可证

Lace受服务器端公共许可证（SSPL）的许可。

如果您希望用于封闭源代码的许可证，请联系lace@promised.ai