Human Learn

机器学习模型应该严格遵守规则，从字面意义上来说。

项目目标

在过去，编写基于规则的系统是很常见的。这些系统会执行如下操作：

而如今，使用机器学习来替代它们则更为流行。例如：

我们开始思考，在这一转变过程中，我们是否遗失了某些东西。诚然，机器学习的应用范围非常广泛，但它也可能做出错误的决策。因此，我们需要对炒作保持警惕。同时，我们也应意识到，许多分类问题同样可以由人类智能来解决。即便不能完全替代，至少也可以作为一个合理的基准。

本包包含与 scikit-learn 兼容的工具，旨在简化由人类设计的基于规则系统的构建与评估过程。此外，您还可以将其与机器学习模型结合使用。

安装

您可以使用 pip 来安装此工具。

python -m pip install human-learn

该项目依赖于现代版本的 scikit-learn 和 pandas。它还使用 bokeh 来实现交互式 Jupyter 组件，shapely 处理点在多边形内的算法，以及 clumper 来处理 JSON 数据结构。

文档

有关此工具的详细文档，请参阅 这里。

您还可以在 calmcode.io 上找到免费的视频课程。

功能

该库提供了一些可供您尝试的模型。

交互式绘图

此工具允许您在数据集上进行绘制。这些绘制内容随后可以转换为模型或预处理工具。

分类模型

FunctionClassifier

此模型允许您定义一个用于分类预测的函数。其设计方式使得您可以将函数的参数作为网格搜索中的可调参数进行评估。

InteractiveClassifier

此模型允许您在交互式图表中绘制决策边界以创建模型。您可以在笔记本中交互式地创建图表，并将其导出为与 scikit-learn 兼容的模型。

回归模型

FunctionRegressor

此模型允许您定义一个用于回归预测的函数。其设计方式使得您可以将函数的参数作为网格搜索中的可调参数进行评估。

异常值检测模型

FunctionOutlierDetector

此模型允许您定义一个用于识别异常值的函数。其设计方式使得您可以将函数的参数作为网格搜索中的可调参数进行评估。

InteractiveOutlierDetector

此模型允许您在交互式图表中绘制决策边界，以创建一个模型。如果某个数据点落在这些边界之外，我们就可以将其标记为异常值。此外，还有一个阈值参数，用于控制判定的严格程度。

预处理模型

PipeTransformer

此模型允许您定义一个用于预处理的函数。其设计方式使得您可以将函数的参数作为网格搜索中的可调参数进行评估。当与 pandas 的 .pipe 方法结合使用时，效果尤为显著。如果您还不熟悉这一强大的功能，不妨参考 这篇教程。

InteractivePreprocessor

此模型允许您绘制希望添加到数据集或机器学习流水线中的特征。您可以通过 tfm.fit(df).transform(df) 或 df.pipe(tfm) 来使用它。

数据集

泰坦尼克号

该库托管了著名的泰坦尼克号幸存者数据集，用于演示目的。此数据集的目标是预测哪些乘客可能在泰坦尼克号沉没事件中幸存下来。

鱼类市场

鱼类市场数据集也托管在该库中。此数据集的目标是预测鱼的重量，但通过预测鱼的种类，它也可以转化为一个分类问题。

贡献

我们欢迎对仓库提出建议，但在提交拉取请求之前，请先讨论您想要添加的功能。这样可以让大家知道有人正在开发该功能，并且可以在开发初期与维护者进行沟通。

如果您想快速在本地开始开发，可以运行以下命令来设置本地开发环境：

make develop

如果您想在本地运行所有测试和检查，可以执行：

make check

这将运行 flake8、black、pytest，并测试文档页面。

human-learn 快速上手指南

human-learn 是一个与 scikit-learn 兼容的 Python 库，旨在帮助开发者轻松构建和评估基于人类规则的系统。它允许你通过编写函数或在交互式图表中绘制决策边界来创建机器学习模型，既可作为独立模型使用，也可与传统 ML 模型结合进行基准测试。

环境准备

在开始之前，请确保你的开发环境满足以下要求：

• 操作系统：Linux, macOS 或 Windows
• Python 版本：支持主流 Python 3 版本（具体见 PyPI 徽章）
• 核心依赖：
  • scikit-learn
  • pandas
• 可选依赖（用于交互功能）：
  • bokeh：用于 Jupyter Notebook 中的交互式图表
  • shapely：用于点在多边形内的算法
  • clumper：用于处理 JSON 数据结构

提示：如果你在中国大陆地区，建议使用国内镜像源加速安装过程（如清华源或阿里源）。

安装步骤

你可以直接使用 pip 进行安装。

标准安装

python -m pip install human-learn

使用国内镜像加速安装（推荐）

python -m pip install human-learn -i https://pypi.tuna.tsinghua.edu.cn/simple

基本使用

human-learn 的核心优势在于可以将简单的 Python 函数或手绘规则转换为标准的 scikit-learn estimator。以下是两种最典型的使用场景。

1. 使用函数定义分类器 (FunctionClassifier)

你可以直接定义一个 Python 函数作为分类逻辑，并将其包装为模型。这使得规则逻辑可以像超参数一样在 GridSearch 中进行基准测试。

from human_learn import FunctionClassifier
import pandas as pd

# 1. 定义你的规则函数
# 注意：函数参数将自动成为模型的可调参数
def my_rule(X, threshold=0.5):
    # 假设 X 是一个包含 'feature_1' 的 DataFrame 或数组
    # 这里演示简单的逻辑判断
    return (X[:, 0] > threshold).astype(int)

# 2. 初始化为 scikit-learn 兼容的模型
clf = FunctionClassifier(my_rule)

# 3. 准备数据 (示例数据)
X = [[0.2], [0.6], [0.8], [0.1]]
y = [0, 1, 1, 0]

# 4. 训练 (对于规则模型，fit 通常只是存储状态，逻辑主要在 predict)
clf.fit(X, y)

# 5. 预测
predictions = clf.predict(X)
print(predictions)

# 6. 进阶：可以直接用于 GridSearchCV 来寻找最佳 threshold
from sklearn.model_selection import GridSearchCV

param_grid = {'threshold': [0.1, 0.3, 0.5, 0.7]}
grid_search = GridSearchCV(clf, param_grid, cv=3)
grid_search.fit(X, y)

print(f"最佳阈值：{grid_search.best_params_['threshold']}")

2. 交互式绘制决策边界 (InteractiveClassifier)

如果你在 Jupyter Notebook 环境中，可以使用交互式工具通过“画图”来训练模型。

from human_learn import InteractiveClassifier
from human_learn.datasets import load_fish

# 1. 加载示例数据集
df = load_fish()
# 选取两个特征用于二维绘图展示
X = df[['Length1', 'Length2']].values
y = df['Species'].values

# 2. 初始化交互式分类器
# 在 Jupyter 中运行此行会弹出一个可绘图的图表
clf = InteractiveClassifier()

# 3. 拟合数据并启动交互界面
# 在弹出的图表中用鼠标绘制区域来定义分类规则
clf.fit(X, y)

# 4. 绘制完成后，它就是一个标准的 scikit-learn 模型
# 可以进行预测或保存
score = clf.score(X, y)
print(f"模型准确率：{score}")

3. 数据预处理 (PipeTransformer)

除了建模，你还可以用函数定义预处理步骤，并无缝接入 pandas 管道。

from human_learn import PipeTransformer
import pandas as pd

# 定义一个预处理函数
def add_feature(df, multiplier=2):
    df = df.copy()
    df['new_feature'] = df['existing_col'] * multiplier
    return df

# 包装为 Transformer
tfm = PipeTransformer(add_feature)

# 使用方式 A: 标准 sklearn 风格
# tfm.fit(df).transform(df)

# 使用方式 B: pandas pipe 风格 (更简洁)
# df_processed = df.pipe(tfm, multiplier=3)

通过以上方式，human-learn 让你能够灵活地将人类直觉（规则/绘图）转化为可复现、可评估的机器学习组件。