模块 basalt.ml¶

102 个公开类型 · 14 个包内可见类型

经典机器学习：线性模型、近邻、SVM、树、梯度提升、聚类、降维、朴素贝叶斯、指标与切分。

类型概览

final class AgglomerativeClustering implements Estimator¶

自底向上合并的层次聚类，支持四种链接准则。

拟合从每个样本各自成簇开始，反复合并代价最小的一对活跃簇，直到剩余簇数等于 clusters。初始距离矩阵保存全部样本对的欧氏距离，占用 n×n 个 double，构造耗时为 O(n²p)；此后每轮合并都要扫描所有活跃簇对，共 n−clusters 轮，整体时间达到 O(n³)。因此该实现适合中小规模数据，样本数上万时距离矩阵本身就难以承受。

四种准则的差别在选择合并对时的代价：SINGLE 取两簇间最近样本的距离，倾向于串起长链，能发现非凸形状但易受噪声牵连；COMPLETE 取最远样本距离，产生紧致且直径相近的簇；AVERAGE 取簇间全部样本对距离的均值，介于两者之间，对噪声更稳健；WARD 用 (ni·nj/(ni+nj))·‖μi−μj‖² 衡量合并带来的方差增量，倾向等方差的球形簇。

合并后距离矩阵就地更新：SINGLE 取 min、COMPLETE 取 max、AVERAGE 与 WARD 都取按簇大小加权的平均 (sizeA·dAK + sizeB·dBK)/(sizeA+sizeB)。簇编号在合并结束后按活跃簇的下标升序重编为 0 起，与合并先后无关。

示例

Matrix features = Matrix.fromRows(new double[][] {
    {0.0, 0.0}, {0.2, 0.1}, {0.1, 0.3},
    {5.0, 5.0}, {5.2, 4.9}, {4.8, 5.1}
});
AgglomerativeClustering model = AgglomerativeClustering.builder()
        .clusters(2)
        .linkage(AgglomerativeClustering.Linkage.WARD)
        .build()
        .fit(features);
int[] labels = model.labels();
double[] assigned = model.predict(features);

注意

WARD 的选择代价与距离矩阵的更新公式并不相同：前者是方差增量，后者是加权平均距离

注意

只有 fit 而没有 fitPredict，训练标签通过 labels() 读取

注意

predict 在输入与拟合数据逐元素相同时直接返回训练标签，否则按到最终簇均值的平方欧氏距离归属，属于质心近似而非层次归属

注意

clusters 必须为正且不超过样本数，后者在 fit 时校验

参见：basalt.ml.Estimator, basalt.ml.KMeans, basalt.ml.DBSCAN

方法

builder() → Builderstatic¶

创建 AgglomerativeClustering 构建器。

返回

clusters 为 2、linkage 为 WARD 的新 Builder 实例

fit(Matrix features) → AgglomerativeClustering¶

以无监督方式执行层次聚类。

等价于 fit(features, null)，目标数组不参与任何计算。

参数

• features (Matrix) – 样本矩阵，行是样本、列是特征；元素必须有限

返回

this，便于链式调用

抛出

• NullPointerException – features 为 null

• IllegalArgumentException – features 含非有限值，或 clusters 大于样本数

fit(Matrix features, double[] ignoredTargets) → AgglomerativeClustering¶

在给定特征上执行自底向上的合并聚类。

先复制输入特征，建立 n×n 的欧氏距离矩阵，再循环挑选代价最小的活跃簇对并合并：合并后的均值按两簇样本数加权，被合并行的距离按链接准则更新，另一簇标为非活跃。簇数降到 clusters 时停止。

注意

重复调用 fit 会重建距离矩阵与标签，上一次结果被覆盖

注意

样本数等于 clusters 时不发生任何合并，每个样本自成一簇

参数

• features (Matrix) – 样本矩阵，行是样本、列是特征；元素必须有限

• ignoredTargets (double[]) – 占位参数；聚类为无监督任务，源码不读取，传 null 或任意数组均可

返回

this，便于链式调用

抛出

• NullPointerException – features 为 null

• IllegalArgumentException – features 含非有限值，或 clusters 大于样本数

predict(Matrix features) → double[]¶

把样本归入最近的最终簇均值。

输入与拟合数据行数相同且底层数组逐元素相等时，直接返回训练标签的副本；否则逐行计算到 clusters 个簇均值的平方欧氏距离并取最小者。距离比较用严格小于，平局时返回编号较小的簇。

参数

• features (Matrix) – 样本矩阵，列数须等于拟合时的特征数；元素必须有限

返回

长度为样本数的簇编号数组，取值 0 到 clusters−1

抛出

• NullPointerException – features 为 null

• IllegalStateException – 尚未拟合

• IllegalArgumentException – 特征列数与拟合时不一致，或含非有限值

labels() → int[]¶

返回训练样本的簇标签副本。

簇编号从 0 开始，按合并结束后活跃簇的下标升序编号，因此同一份输入的编号与 linkage 无关。返回 clone，修改它不影响模型状态。

返回

长度等于训练样本数的标签数组

抛出

• IllegalStateException – 尚未拟合

linkage() → Linkage¶

返回构造时指定的链接准则。

返回

Linkage 常量（WARD、COMPLETE、AVERAGE 或 SINGLE）；未拟合时同样返回配置值

enum BoostingAlgorithm¶

直方图树的生长策略：深度优先或叶优先

XGBOOST 按层递归生长：节点在深度小于 maxDepth 且增益为正时分裂，左右子树继续递归，树的叶数由深度与数据决定。LIGHTGBM 维护一个按增益降序排列的候选叶队列，每轮分裂全局增益最大的叶，直到叶数达到 maxLeaves。

示例

HistogramGradientBoosting depthWise = HistogramGradientBoosting.builder()
        .algorithm(BoostingAlgorithm.XGBOOST)
        .maxDepth(4)
        .build();

HistogramGradientBoosting leafWise = HistogramGradientBoosting.builder()
        .algorithm(BoostingAlgorithm.LIGHTGBM)
        .maxLeaves(15)
        .build();

注意

XGBOOST 策略不读取 maxLeaves

注意

LIGHTGBM 策略同时受 maxDepth 约束，每分裂一次叶数加一

参见：basalt.ml.HistogramGradientBoosting

枚举成员

XGBOOST()¶

深度优先（level-wise）逐层分裂节点

LIGHTGBM()¶

叶子优先（leaf-wise）按最大增益继续分裂

enum BoostingObjective¶

直方图提升支持的目标：平方误差与二分类逻辑

SQUARED_ERROR 取残差 raw - target 为梯度、hessian 恒为 1，叶权重等于负梯度除以 hessian 加 lambda。LOGISTIC 取概率减标签为梯度、p(1-p) 为 hessian（下限 1e-12），baseScore 为训练集正类均值的对数几率。

示例

HistogramGradientBoosting classifier = HistogramGradientBoosting.builder()
        .objective(BoostingObjective.LOGISTIC)
        .iterations(200)
        .build();

注意

LOGISTIC 的 fit 会逐行校验标签，出现 0 与 1 之外的值即抛 IllegalArgumentException

注意

predictProbability 只在 LOGISTIC 下可用，其他目标调用会抛 IllegalStateException

参见：basalt.ml.HistogramGradientBoosting

枚举成员

SQUARED_ERROR()¶

平方误差，用于回归

LOGISTIC()¶

二分类逻辑损失

final class DBSCAN implements Estimator¶

按 eps 邻域与 minPoints 判定核心点的密度聚类。

以 eps 为半径的邻域内样本数不少于 minPoints 的点为核心点，簇从核心点出发按广度优先扩展。边界点归入首个到达它的簇，无法从任何核心点到达的点保留噪声标签 -1。

邻域查询逐点线性扫描全部样本，整体需要 O(n²) 次距离计算，适用于中小规模数据。拟合时复制输入特征，后续 predict 与标签查询都基于这份副本。

示例

Matrix features = Matrix.fromRows(new double[][] {
    {0.0, 0.0}, {0.3, 0.1}, {0.1, 0.4},
    {5.0, 5.0}, {5.2, 4.8}, {4.9, 5.3},
    {9.0, 0.5}
});
DBSCAN dbscan = DBSCAN.builder()
        .eps(0.6)
        .minPoints(3)
        .metric(DistanceMetric.EUCLIDEAN)
        .build()
        .fit(features, null);
int[] labels = dbscan.labels();
int clusters = dbscan.clusterCount();
int noise = dbscan.noiseCount();

注意

minPoints 统计包含点自身，因为点与自身的距离为 0 且不大于 eps

注意

predict 在全部核心点中取 eps 内的最近邻并返回其标签，未命中时返回 -1；这是近似归属，不是密度可达判定

注意

DBSCAN 只实现 Estimator，没有 fit(Matrix) 单参数重载，也没有 write/read

参见：basalt.ml.DistanceMetric, basalt.ml.Estimator

方法

builder() → Builderstatic¶

创建 DBSCAN 构建器。

返回

参数取默认值的新 Builder 实例

fit(Matrix features, double[] ignoredTargets) → DBSCAN¶

在给定特征上执行密度聚类并返回自身。

先复制特征矩阵，再把全部标签初始化为 -1，然后按样本顺序扫描：邻域样本数达到 minPoints 的点成为新簇的种子，队列向外扩展直到没有新的核心点可达。

注意

重复调用 fit 会丢弃上一次的标签与核心点标记

参数

• features (Matrix) – 样本矩阵，行是样本、列是特征；元素必须有限

• ignoredTargets (double[]) – 占位参数；聚类为无监督任务，传 null 或任意数组都被忽略

返回

this，便于链式调用

抛出

• IllegalArgumentException – features 为 null 或包含非有限值

predict(Matrix features) → double[]¶

按最近核心点的标签预测样本所属簇。

对每个待预测样本，在全部核心点中寻找 eps 邻域内距离最近的一个，返回该核心点的簇标签；邻域内不存在核心点时返回 -1。边界点不参与查询，因此结果可能比训练标签更保守。

参数

• features (Matrix) – 样本矩阵，列数须与拟合时一致

返回

长度为样本数的标签数组，噪声或未命中为 -1

抛出

• IllegalStateException – 尚未拟合

• IllegalArgumentException – 特征列数与拟合时不一致

labels() → int[]¶

返回训练样本的簇标签副本。

簇编号从 0 开始，按种子点的发现顺序递增；噪声点保持 -1。返回的是副本，修改它不影响模型状态；未拟合时返回 null。

返回

长度等于训练样本数的标签数组；未拟合时为 null

clusterCount() → int¶

返回拟合得到的簇数量。

返回

簇数，不含噪声；未拟合时为 0

noiseCount() → int¶

统计标签为负的样本数量。

注意

直接遍历内部标签数组，未拟合时该数组为 null，调用会抛 NullPointerException

返回

标签小于 0 的样本个数

final class DataSplit¶

基于行下标的确定性 holdout、k 折与分层 k 折划分。

holdout 与两个 trainTestSplit 重载都先用 seed 构造 Random，对行下标数组做 Fisher-Yates 洗牌，再按洗牌后的顺序切片；两个 kFold 重载复用同一套下标洗牌，把洗牌顺序切成 folds 段连续区间。相同 seed 与相同输入必然产生相同切分，与标签分布无关。

返回的特征与标签都是新建副本，调用方修改切分结果不会影响原始数据。holdout 的测试行数取 round(rows·testFraction) 后夹到 [1, rows−1]；kFold 的每折测试块大小相差不超过 1。

stratifiedKFold 与 trainTestSplit 的 stratify 分支改为按目标值分组：每类内部独立洗牌，再用跨类连续的轮转把行分发到各折或切出测试行，使每侧都保留全部类别。某个类别的样本数少于折数时 stratifiedKFold 直接拒绝，因为无法保证每折都有该类样本。

示例

Matrix x = Matrix.fromRows(new double[][]{{0, 0}, {0, 1}, {1, 0}, {1, 1}, {2, 2}, {2, 1}});
double[] y = {0, 0, 1, 1, 1, 1};
DataSplit.Holdout split = DataSplit.holdout(x, y, 0.25, 42L);
LinearRegression model = LinearRegression.builder().build()
        .fit(split.trainFeatures(), split.trainTargets());
double[] predicted = model.predict(split.testFeatures());

注意

holdout 与 kFold 不做分层，类别偏斜时小测试块可能缺少某一类；需要类别均衡时改用 stratifiedKFold 或 stratify 分支

注意

洗牌只重排行，不改变列顺序与数值

注意

所有入口都会先做非空、行数一致与非有限值校验

注意

testFraction 取开区间 (0, 1)；分层分支的实际测试比例是各类比例的汇总，可能与入参略有偏差

参见：basalt.ml.DataSplit.Holdout, basalt.ml.DataSplit.Fold, basalt.ml.Estimators

方法

holdout(Matrix features, double[] targets, double testFraction, long seed) → Holdoutstatic¶

按比例切出一份测试集，其余作为训练集。

洗牌后取前 testSize 行为测试集，其余行为训练集，因此测试集在原始数据中并不连续。

注意

实际测试行数被夹到 [1, rows-1]，样本极少时也不会产生空的一侧

参数

• features (Matrix) – 样本矩阵，行数即样本数

• targets (double[]) – 目标数组，长度必须等于 features.rows()

• testFraction (double) – 测试集比例，必须落在开区间 (0, 1)

• seed (long) – 洗牌随机源种子，决定具体划分

返回

持有 trainFeatures、trainTargets、testFeatures、testTargets 四个副本的 Holdout

抛出

• NullPointerException – features 或 targets 为 null

• IllegalArgumentException – targets 长度与行数不符、数据含 NaN/无穷，或 testFraction 不在 (0, 1)

trainTestSplit(Matrix features, double[] targets, double testFraction, long seed) → Holdoutstatic¶

按比例切分训练集与测试集，默认洗牌且不分层。

等价于 trainTestSplit(features, targets, testFraction, true, false, seed)，也是 holdout 的实现。

参数

• features (Matrix) – 样本矩阵，行数即样本数

• targets (double[]) – 目标数组，长度必须等于 features 的行数

• testFraction (double) – 测试集比例，必须落在开区间 (0, 1)

• seed (long) – 洗牌随机源种子，决定具体划分

返回

持有 trainFeatures、trainTargets、testFeatures、testTargets 四个副本的 Holdout

抛出

• NullPointerException – features 或 targets 为 null

• IllegalArgumentException – targets 长度与行数不符、数据含非有限值、testFraction 不在 (0, 1)，或样本数小于 2

trainTestSplit(Matrix features, double[] targets, double testFraction, boolean shuffle, boolean stratify, long seed) → Holdoutstatic¶

可控洗牌与分层的 holdout 切分。

不分层时先按 shuffle 决定是否对行下标做 Fisher-Yates 重排，取重排后的前 round(rows·testFraction) 行（夹到 [1, rows−1]）作测试集，其余作训练集。

stratify 为真时改为按目标值分组：每组内部单独洗牌，按自身比例切出测试行且至少保留 1 行训练、1 行测试；只有单个样本的类整类留在训练集。因此实际测试比例是各类比例的汇总，可能与 testFraction 略有偏差。

注意

行数校验在分层判断之前，分层分支同样要求样本数不小于 2

注意

分层模式不重新混排类别，训练集与测试集内部按类别首次出现的顺序分块

注意

shuffle 为假时保持原始行序，此时测试集就是原始数据的头部若干行

参数

• features (Matrix) – 样本矩阵，行数即样本数

• targets (double[]) – 目标数组，长度必须等于 features 的行数；stratify 为真时按其中的取值分组

• testFraction (double) – 测试集比例，必须落在开区间 (0, 1)

• shuffle (boolean) – 为真时对行下标（分层时为每个类内的行号）做 Fisher-Yates 重排

• stratify (boolean) – 为真时按目标值分组抽样，使训练集与测试集都保留全部类别

• seed (long) – 洗牌随机源种子；不分层与分层两条分支各自新建 Random，含义相同

返回

四个字段均为新建副本的 Holdout

抛出

• NullPointerException – features 或 targets 为 null

• IllegalArgumentException – targets 长度与行数不符、数据含非有限值、testFraction 不在 (0, 1)，或样本数小于 2

kFold(Matrix features, double[] targets, int folds, long seed) → List<Fold>static¶

按折数切分为互不重叠的测试块。

第 i 折的测试区间为 [i*rows/folds, (i+1)*rows/folds)，训练集由其余折按洗牌顺序拼接而成，因此各折训练集大小同样只相差至多 1。

注意

列表顺序即折编号顺序，可直接顺序遍历做交叉验证

参数

• features (Matrix) – 样本矩阵

• targets (double[]) – 目标数组，长度必须等于 features.rows()

• folds (int) – 折数，必须满足 2 <= folds <= features.rows()

• seed (long) – 洗牌随机源种子

返回

长度为 folds 的 Fold 列表，测试块并集覆盖全部行

抛出

• NullPointerException – features 或 targets 为 null

• IllegalArgumentException – folds 越界，或 targets 长度不符、数据含非有限值

kFold(Matrix features, double[] targets, int folds, boolean shuffle, long seed) → List<Fold>static¶

按折数切分，可选是否先洗牌。

shuffle 为假时直接按原始行顺序切片，各折测试块是连续的原始区间；为真时先对行下标做 Fisher-Yates 重排，再在重排顺序上切段。

注意

训练集由测试块之前与之后两段拼接而成，行序与原始顺序不同

参数

• features (Matrix) – 样本矩阵

• targets (double[]) – 目标数组，长度必须等于 features 的行数

• folds (int) – 折数，必须满足 2 <= folds <= 行数

• shuffle (boolean) – 为真时先重排行下标，为假时保持原始顺序

• seed (long) – 洗牌随机源种子；shuffle 为假时不起作用

返回

长度为 folds 的 Fold 列表，测试块并集覆盖全部行

抛出

• NullPointerException – features 或 targets 为 null

• IllegalArgumentException – folds 越界，或 targets 长度不符、数据含非有限值

stratifiedKFold(Matrix features, double[] targets, int folds, boolean shuffle, long seed) → List<Fold>static¶

按类别分层切分的 k 折。

先按目标值把行分组，每组内部可选洗牌，再用一个跨组连续累加的轮转计数器把样本依次放进 folds 个桶，因此同一类在各折的数量相差不超过 1。第 f 折以桶 f 为测试集，其余桶按桶序号拼接为训练集，每折都含有全部类别。

注意

轮转计数器跨类别连续累加，因此各类别的起始折不同

注意

只保证类内均衡，不保证各折总样本数完全相等

参数

• features (Matrix) – 样本矩阵

• targets (double[]) – 目标数组，长度必须等于 features 的行数；每个不同取值视为一个类别

• folds (int) – 折数，必须满足 2 <= folds <= 行数，且每个类别的样本数不少于 folds

• shuffle (boolean) – 为真时在每个类别内部做 Fisher-Yates 重排

• seed (long) – 洗牌随机源种子；shuffle 为假时不起作用

返回

长度为 folds 的 Fold 列表，各折测试桶互不重叠且并集覆盖全部行

抛出

• NullPointerException – features 或 targets 为 null

• IllegalArgumentException – folds 越界、某个类别的样本数少于 folds，或 targets 长度不符、数据含非有限值

final class DecisionTree implements Estimator, Persistable¶

预分箱特征上的 CART 树，分裂搜索走直方图

分裂搜索基于直方图：一次遍历节点样本即可填满每个特征的类别计数（分类）或和与平方和（回归），随后每个桶边界以 O(classes) 或 O(1) 评估增益。分类准则为 GINI 或 ENTROPY，回归固定使用 MSE 的和与平方和等价形式。

叶子值：分类取多数类标签（票数相同时取下标最小者），回归取样本均值。特征重要性按「分裂增益乘以节点样本数」逐特征累加，再归一化到总和 1。

拟合结果展平为 TreeModel，推理只在原始数组上迭代行走。RandomForest 复用一份全局 BinnedFeatures 并调用 fitBinned 传入自助采样行号，省去每棵树的重复分箱与矩阵复制。

示例

Matrix x = Matrix.fromRows(new double[][]{
        {0.0, 1.0},
        {1.0, 1.0},
        {1.0, 0.0},
        {2.0, 0.0}});
double[] y = {0.0, 0.0, 1.0, 1.0};

DecisionTree tree = DecisionTree.builder()
        .task(TreeTask.CLASSIFICATION)
        .criterion(ImpurityCriterion.GINI)
        .maxDepth(3)
        .minSamplesLeaf(1)
        .bins(32)
        .seed(7L)
        .build()
        .fit(x, y);

double[] predicted = tree.predict(x);
double[] importance = tree.featureImportances();

注意

分裂要求两侧样本数均不小于 minSamplesLeaf，父节点样本数不小于 minSamplesSplit 与 2*minSamplesLeaf

注意

最优增益不超过 1e-12*max(1, 父不纯度) 时停止分裂，节点转为叶

注意

maxDepth 为 0 时根节点直接成为叶

注意

fit 就地更新估计器状态并返回 this

参见：basalt.ml.RandomForest, basalt.ml.TreeModel, basalt.ml.ImpurityCriterion

方法

builder() → Builderstatic¶

创建构造器，参数全部取默认值

返回

新的 Builder 实例

fit(Matrix features, double[] targets) → DecisionTree¶

在原始特征矩阵上分箱并训练单棵树

先校验训练数据，再以 maxBins 构建 BinnedFeatures，最后用全部行号调用 fitBinned。分类标签按升序去重后编码为 0 起的整数，回归直接使用原始目标值。

注意

每次调用都会重建分箱与树，重复拟合覆盖上一次结果

参数

• features (Matrix) – 训练特征矩阵，行数为样本数，列数成为特征数

• targets (double[]) – 目标数组，长度必须等于行数；分类为类别标签，回归为连续值

返回

this，已完成拟合

抛出

• IllegalArgumentException – 目标数量与行数不一致、特征或目标含非有限值，或样本数小于 minSamplesLeaf

• NullPointerException – features 或 targets 为 null

predict(Matrix features) → double[]¶

输出每行的叶值，分类为类别标签

内部调用 TreeModel.addInto 一次遍历完成，不做逐行对象分配。分类返回叶节点保存的类别标签，回归返回叶节点均值。

参数

• features (Matrix) – 特征矩阵，列数须等于拟合时的特征数

返回

长度为行数的预测数组

抛出

• IllegalStateException – 估计器尚未拟合

• IllegalArgumentException – 列数与拟合时不一致，或含非有限值

featureImportances() → double[]¶

归一化的特征重要性，总和为 1

口径为「分裂增益乘以该节点样本数」，在整棵树范围内按特征累加；总和大于 0 时整体除以总和，否则保持全零。只有真正参与分裂的特征会累积到非零值。

注意

返回 clone，修改不影响估计器内部状态

返回

长度为特征数的副本；树未产生分裂时全为 0

抛出

• IllegalStateException – 估计器尚未拟合

task() → TreeTask¶

构造时指定的任务类型

返回

CLASSIFICATION 或 REGRESSION

classes() → double[]¶

分类任务的类别标签，按升序排列

注意

标签顺序来自 TreeMap 的自然序，与 predictProbability 的列顺序无关

返回

类别标签副本；回归任务返回 null

featureCount() → int¶

拟合时使用的特征数

返回

特征数；未拟合为 0

nodeCount() → int¶

树的节点总数

返回

节点数，含叶节点；未拟合为 0

depth() → int¶

根到叶的最大边数

返回

树深；未拟合或单叶树为 0

kind() → ModelKind¶

返回模型类型标识。

返回

ModelKind.DECISION_TREE

write(ModelWriter writer)¶

序列化入口，等价于 writeState。

Persistable 的实现方法，直接委托 writeState，落盘格式与直接调用 writeState 完全一致。

注意

读取端用静态 read 或 readState 均可，两者等价

参数

• writer (ModelWriter) – 目标写入器，由调用方负责容器头与关闭

抛出

• IllegalStateException – 估计器尚未拟合

read(ModelReader reader) → DecisionTreestatic¶

反序列化入口，等价于 readState。

静态工厂，直接委托 readState；读回后超参数取 Builder 默认值，只有任务、类别标签与树拓扑被还原。

注意

静态方法，调用形式为 DecisionTree.read(reader)

参数

• reader (ModelReader) – 已定位到本对象载荷起点的读取器

返回

新的 DecisionTree 实例，已具备预测能力

抛出

• ModelFormatException – 任务序号越界，或分类树缺少类别标签

writeState(ModelWriter writer)¶

写出特征数、任务、类别标签与树拓扑

写入顺序为特征数、任务序号、类别数（回归写 0）与类别标签，最后是树的节点数组。超参数不落盘，读取方需要自行重建配置；分类树缺少标签会导致读取失败。

注意

与 readState 成对使用，格式由 ModelCodec 的容器包裹

参数

• writer (ModelWriter) – 目标二进制写入器

抛出

• IllegalStateException – 估计器尚未拟合

readState(ModelReader reader) → DecisionTreestatic¶

从二进制流重建树

注意

重建后的超参数取 Builder 默认值，仅任务与准则被还原

注意

重建后的特征重要性全为 0，不参与持久化

参数

• reader (ModelReader) – 已定位到本对象载荷起点的读取器

返回

新的 DecisionTree 实例，已具备预测能力

抛出

• ModelFormatException – 任务序号越界，或分类树缺少类别标签

enum DistanceMetric¶

KNN 使用的距离函数枚举。

EUCLIDEAN 返回平方欧氏距离开方，MANHATTAN 返回逐元素绝对差之和；两者都调用 VectorMath 的 SIMD 内核，按扁平数组上的偏移窗口计算。

distance 直接接收两个 double[] 与起始偏移，因此可以在 Matrix.data() 上按行取窗口，不必为每一行构造临时数组。

示例

double[] a = {1.0, 2.0, 3.0};
double[] b = {1.0, 4.0, 3.0};
double euclidean = DistanceMetric.EUCLIDEAN.distance(a, 0, b, 0, 3);
double manhattan = DistanceMetric.MANHATTAN.distance(a, 0, b, 0, 3);

注意

偏移以元素为单位，不是字节

注意

不做越界检查，调用方需保证 offset + length 不超出数组长度

注意

两个常量都在枚举体内覆写 distance，没有默认实现

参见：basalt.ml.KNearestNeighbors, basalt.ml.KNeighborsRegressor

方法

distance(double[] a, int aOffset, double[] b, int bOffset, int length) → doubleabstract¶

计算两段等长向量在该度量下的距离。

注意

越界与 length 为负都不检查，由调用方保证

参数

• a (double[]) – 第一个向量的扁平存储

• aOffset (int) – a 中参与计算的起始元素下标

• b (double[]) – 第二个向量的扁平存储

• bOffset (int) – b 中参与计算的起始元素下标

• length (int) – 参与计算的元素个数，即特征维数

返回

按枚举常量定义的距离，非负；相同位置返回 0.0

enum EigenSolver¶

PCA 可选的对称特征分解求解器。

AUTO 依据数据形状挑选实现：特征数大于样本数时走 GRAM，否则走 JACOBI。JACOBI 直接分解 p × p 协方差矩阵，GRAM 分解 n × n Gram 矩阵再还原主方向。

显式指定的求解器不会因形状被改写；但 GRAM 需要为 n × n 矩阵分配内存，样本数超过 20000 时 fit 拒绝执行。

注意

AUTO 仅在特征数大于样本数且样本数不超过 20000 时选择 GRAM

注意

两条路径输出在符号与数值误差范围内一致，符号由最大绝对值分量为正的约定固定

参见：basalt.ml.PCA, basalt.ml.PCA.Builder

枚举成员

AUTO()¶

特征数多于样本数时选 GRAM，否则选 JACOBI

JACOBI()¶

对 p×p 协方差做 Jacobi 对角化，O(n·p²)

GRAM()¶

对 n×n Gram 矩阵做对角化，适合宽表，O(n²·p)

interface Estimator¶

经典估计器的统一契约。

fit 消费特征矩阵与目标数组，就地更新估计器状态并返回 this，便于链式调用；predict 返回与输入行数等长的预测数组，顺序与输入行一一对应。

接口不规定重复 fit 的语义、也不声明线程安全：实现类在 fit 期间可变，predict 只读，因此同一实例的并发 predict 依赖实现是否持有可变临时状态。无监督实现可忽略 targets。

示例

Matrix x = Matrix.fromRows(new double[][]{{0, 0}, {0, 1}, {1, 0}, {1, 1}});
double[] y = {0, 1, 1, 0};
Estimator model = KNearestNeighbors.builder().k(3).build().fit(x, y);
double[] prediction = model.predict(x);

注意

predict 前必须先 fit，实现类通过内部标记抛出 IllegalStateException

注意

不同实现的 predict 返回语义不同：分类器返回原始类别标签，回归器返回连续值

参见：basalt.ml.Estimators, basalt.ml.Metrics

final class Estimators¶

按枚举选择算法的一行式门面。

fit 按 Algorithm 分支构造对应估计器并立即训练，超参数一律取各 Builder 的默认值；需要调参时改用具体类的 builder()。有监督算法传入 null targets 会被拒绝，无监督算法则忽略 targets 并以 null 调用。

crossValidate 用 DataSplit.kFold 做种子固定为 42 的 k 折划分，逐折训练、预测、计分，返回各折算术平均。RMSE 在累加前取负号，使所有 Metric 都满足越大越好。

示例

Matrix x = Matrix.fromRows(new double[][]{{0, 0}, {0, 1}, {1, 0}, {1, 1}, {2, 2}, {2, 1}});
double[] y = {0.5, 1.0, 1.5, 2.0, 2.5, 2.2};
Estimator model = Basalt.fit(Basalt.Algorithm.RIDGE, x, y);
double[] prediction = Basalt.predict(model, x);
double score = Basalt.crossValidate(Basalt.Algorithm.RIDGE, x, y, 3, Estimators.Metric.R2);

注意

门面不缓存模型也不管理生命周期，返回的 Estimator 由调用方持有

注意

交叉验证的划分种子固定为 42，相同输入的结果可复现

注意

folds 的合法范围沿用 DataSplit.kFold 的约束（2 到样本数）

注意

门面本身无状态，全部方法为 static

参见：basalt.ml.Estimators.Algorithm, basalt.ml.Estimators.Metric, basalt.ml.Estimator, basalt.ml.DataSplit

方法

fit(Algorithm algorithm, Matrix features, double[] targets) → Estimatorstatic¶

按算法枚举训练一个默认配置的估计器。

分支覆盖 16 个算法常量，其中 RANDOM_FOREST_REGRESSOR 复用 RandomForest 并切换 task，两个梯度提升常量分别绑定 LOGISTIC 与 SQUARED_ERROR 目标。

注意

KNN 与 KNN_REGRESSOR 固定 k=5、欧氏距离

注意

KMEANS、PCA 调用只接收特征的 fit 重载；DBSCAN 以 null targets 调用 fit

参数

• algorithm (Algorithm) – 算法枚举，同时决定实现类与默认超参数

• features (Matrix) – 训练特征矩阵

• targets (double[]) – 训练目标；有监督算法不可为 null

返回

已拟合的估计器实例，静态类型为 Estimator

抛出

• NullPointerException – algorithm 为 null

• IllegalArgumentException – 有监督算法传入 null targets，或训练数据未通过估计器自身的校验

predict(Estimator model, Matrix features) → double[]static¶

委托给估计器自身的 predict。

注意

门面不追加任何校验，全部检查由估计器完成

参数

• model (Estimator) – 已拟合的估计器

• features (Matrix) – 待预测特征矩阵

返回

估计器返回的预测数组，不做转换

抛出

• NullPointerException – model 为 null

• IllegalStateException – model 尚未 fit

crossValidate(Algorithm algorithm, Matrix features, double[] targets, int folds, Metric metric) → doublestatic¶

k 折交叉验证并返回各折指标均值。

每折独立调用 fit 重新训练，模型之间不共享状态；指标在折内测试集上计算后累加，最后除以折数。

注意

划分种子固定为 42，重复调用结果一致

注意

ACCURACY 与 MACRO_F1 要求预测是类别码，R2 与 RMSE 要求连续值，错配不报错

参数

• algorithm (Algorithm) – 待评估算法，必须是有监督算法

• features (Matrix) – 全部样本特征

• targets (double[]) – 全部样本目标，长度等于特征行数

• folds (int) – 折数，2 <= folds <= 样本数

• metric (Metric) – 评估指标枚举

返回

各折指标的算术平均；RMSE 以负值参与平均，故越大越好

抛出

• IllegalArgumentException – 算法属于 UNSUPERVISED，或 folds 越界、数据校验失败

final class FeatureImportance¶

统一的特征重要性入口：树杂质、线性权重绝对值与置换重要性。

三种口径按模型分派。树的杂质重要性直接复用 DecisionTree、RandomForest、HistogramGradientBoosting 的 featureImportances，量纲是「分裂增益乘以节点样本数」，本身已归一化到总和 1；线性模型取权重绝对值后归一化，反映的是系数幅度，方向信息因此丢失，也不代表对预测的因果贡献。

置换重要性不依赖模型内部结构：以真实目标与未打乱预测算出的分数为基线，逐列打乱该特征后重新预测，用分数下降量衡量重要性。它对任意 Estimator 与 Pipeline 都成立，也能反映特征间的交互，代价是每列 nRepeats 次完整预测。

of 遇到 Pipeline 会递归到 p.estimator()，返回的是末端估计器所见特征空间的重要性，列数可能不等于原始输入列数。

示例

Matrix x = Matrix.fromRows(new double[][]{
        {0.0, 1.0}, {1.0, 1.0}, {1.0, 0.0}, {2.0, 0.0}});
double[] y = {0.0, 0.0, 1.0, 1.0};
DecisionTree tree = DecisionTree.builder()
        .task(TreeTask.CLASSIFICATION)
        .maxDepth(3)
        .build()
        .fit(x, y);

double[] impurity = FeatureImportance.of(tree);
FeatureImportance.PermutationResult permuted = FeatureImportance.permutationImportance(
        tree, x, y, Estimators.Metric.ACCURACY, 5, 42L);
double[] mean = permuted.importancesMean();
int[] order = permuted.rankedFeaturesDescending();

注意

of 只支持 DecisionTree、RandomForest、HistogramGradientBoosting、Ridge、Lasso、LinearRegression、LogisticRegression、LinearSVM，其余类型抛 IllegalArgumentException

注意

线性归一化把绝对值之和缩放到 1；系数全为零时保持全零而不做除法

注意

置换重要性返回分数下降量，正值表示该特征有用，负值表示打乱后反而更好（常见于噪声列）

注意

metric 已统一为越大越好（RMSE 在内部取负），因此误差指标下「置换后变差」同样得到正的重要性

注意

置换在特征矩阵副本上进行，不会修改调用方传入的矩阵

参见：basalt.ml.DecisionTree, basalt.ml.RandomForest, basalt.ml.HistogramGradientBoosting

方法

of(Estimator model) → double[]static¶

返回归一化到总和 1 的固有特征重要性。

按类型分派取原始值：树模型用其 featureImportances，线性模型用权重绝对值；随后整体除以总和，使结果之和为 1。Pipeline 会先递归到底层估计器。

注意

返回的数组可安全修改，树实现内部返回 clone

注意

对 Pipeline 只取末端估计器，忽略前置变换对列的影响

参数

• model (Estimator) – 已拟合的估计器；未拟合的树在取重要性时抛 IllegalStateException

返回

长度等于该估计器特征数的数组，非负且总和为 1；原始值全零时保持全零

抛出

• NullPointerException – model 为 null

• IllegalArgumentException – 该估计器类型不暴露固有重要性

permutationImportance(Estimator model, Matrix features, double[] targets, Estimators.Metric metric, int nRepeats, long seed) → PermutationResultstatic¶

逐列打乱特征，用评分下降量衡量重要性。

先对未打乱的预测算基线分数；再对每一列重复 nRepeats 次：用同一个 Random 做 Fisher-Yates 重排行下标，按重排结果把该列的值搬到新位置，复制成新矩阵后重新预测，单次下降量 = 基线 − 打乱后分数。最后按列求均值，并以总体标准差（除以 nRepeats）作为波动量。

注意

rawImportances 形状为 特征数 × nRepeats，第 c 行是第 c 列的各次下降量

注意

行下标数组在所有列与所有重复之间复用，洗牌状态不重置

注意

结果用 PermutationResult.rankedFeaturesDescending 可直接取降序特征下标

参数

• model (Estimator) – 已拟合的估计器；predict 会被调用 列数×nRepeats+1 次

• features (Matrix) – 评估用样本矩阵，行数为样本数、列数为特征数；元素必须有限

• targets (double[]) – 真实目标，长度必须等于 features 的行数

• metric (Estimators.Metric) – 评分口径，取 Estimators.Metric 的 ACCURACY、MACRO_F1、R2 或 RMSE；RMSE 在内部取负，使所有指标都越大越好

• nRepeats (int) – 每列重复打乱的次数，必须为正

• seed (long) – 洗牌随机源种子，决定重排序列

返回

持有 importancesMean、importancesStd 与 rawImportances 的 PermutationResult

抛出

• NullPointerException – model、features、targets 或 metric 为 null

• IllegalArgumentException – 目标数与行数不符、数据含非有限值，或 nRepeats 不为正

• IllegalStateException – model 尚未拟合

final class GaussianMixture implements Estimator, Persistable¶

EM 估计的高斯混合模型，协方差可选 FULL / TIED / DIAG。

协方差由 covarianceType 决定：FULL 为每个分量存一个 p×p 矩阵，TIED 让全部分量共享一个矩阵，DIAG 只存 p 个方差。FULL 与 TIED 在每轮 E 步前先做 Cholesky 分解，用前代把马氏距离换成 ‖L⁻¹(x−μ)‖²，对数行列式取 2·Σlog L_ii；分解失败时按 regCovar·10ⁿ 追加 jitter 重试，6 次仍非正定则抛 IllegalStateException。

拟合先用 KMeans 初始化：簇数等于 components、maxIterations 固定 30、使用同一 seed。均值取质心，权重取簇占比，协方差取簇内样本协方差（TIED 取全局共享）。随后每轮 E 步计算「log 权重 + 对数密度」并按行做 log-sum-exp 得到责任度，M 步更新权重、均值与协方差，相邻两轮平均对数似然差不超过 tolerance 即收敛。

AIC/BIC 的自由参数个数随协方差类型变化：DIAG 为 K·2p+K−1，FULL 为 K·(p+p(p+1)/2)+K−1，TIED 为 K·p+p(p+1)/2+K−1。相关特征上 FULL 的对数似然明显更高，但参数更多，需用 AIC/BIC 权衡。

注意

默认 covarianceType 为 FULL；改回 DIAG 可获得 O(K·p) 的存储与求值，代价是无法表达分量内的特征相关

注意

E 步对权重取 max(1e-15, w) 后再取对数，某个分量被压到 0 时不会出现负无穷

注意

lowerBound 是平均每样本对数似然而非总似然，量纲与 sklearn 的 lower_bound_ 一致

注意

write 落盘协方差类型与完整 p×p 矩阵；read 之后 maxIterations、tolerance、regCovar、seed 回落到 Builder 默认值

注意

DIAG 的非对角项恒为 0，但 covariance(k) 仍返回 p×p 稠密矩阵，便于统一处理

方法

builder() → Builderstatic¶

创建 GaussianMixture 构建器。

返回

components 为 2、maxIterations 为 100、tolerance 为 1e-4、regCovar 为 1e-6、seed 为 42 的新 Builder 实例

fit(Matrix features) → GaussianMixture¶

以无监督方式拟合混合模型。

等价于 fit(features, null)，目标数组不参与计算。

参数

• features (Matrix) – 样本矩阵，行是样本、列是特征；元素必须有限

返回

this，便于链式调用

抛出

• NullPointerException – features 为 null

• IllegalArgumentException – features 含非有限值，或 components 大于样本数

fit(Matrix features, double[] ignoredTargets) → GaussianMixture¶

用 EM 估计混合权重、均值与方差。

初始化阶段调用 KMeans 得到质心与初始簇划分，据此估算各分量的初始方差与权重；之后交替执行 E 步（算责任度、算 lowerBound）与 M 步（用责任度加权重估权重、均值、方差，并把 regCovar 加回方差）。

注意

每轮 E 步都覆盖 lowerBound，未收敛时它对应最后一次 E 步

注意

M 步用 max(nk, 1e-10) 作分母，空分量的权重被压到接近 0 而不会除零

参数

• features (Matrix) – 样本矩阵，行数为样本数，列数成为特征数；元素必须有限

• ignoredTargets (double[]) – 占位参数；混合模型为无监督任务，源码不读取，传 null 或任意数组均可

返回

this，已完成拟合

抛出

• NullPointerException – features 为 null

• IllegalArgumentException – features 含非有限值，或 components 大于样本数

scoreSamples(Matrix features) → double[]¶

返回每个样本的对数概率密度 log p(x)。

逐样本对 K 项的「log 权重 + 对角高斯对数密度」做 log-sum-exp：先减最大值，再取指数累加取对数，最后加回最大值，避免下溢。

参数

• features (Matrix) – 样本矩阵，列数须等于拟合时的特征数；元素必须有限

返回

长度为样本数的对数密度数组，元素通常为负

抛出

• NullPointerException – features 为 null

• IllegalStateException – 尚未拟合

• IllegalArgumentException – 特征列数与拟合时不一致，或含非有限值

predictProbability(Matrix features) → Matrix¶

返回样本属于各分量的后验概率。

对每行做减最大值的 softmax，得到 K 个非负且和为 1 的责任度，等价于 E 步的输出。

参数

• features (Matrix) – 样本矩阵，列数须等于拟合时的特征数；元素必须有限

返回

样本数 × components 的矩阵，第 k 列对应第 k 个分量

抛出

• NullPointerException – features 为 null

• IllegalStateException – 尚未拟合

• IllegalArgumentException – 特征列数与拟合时不一致，或含非有限值

predict(Matrix features) → double[]¶

返回后验概率最大的分量编号。

先算后验概率矩阵，再逐行取最大列。比较用严格大于，概率并列时返回编号较小的分量。

参数

• features (Matrix) – 样本矩阵，列数须等于拟合时的特征数；元素必须有限

返回

长度为样本数的分量编号数组，取值 0 到 components−1

抛出

• NullPointerException – features 为 null

• IllegalStateException – 尚未拟合

• IllegalArgumentException – 特征列数与拟合时不一致，或含非有限值

parameterCount() → int¶

按协方差类型计算的自由参数个数

返回

DIAG 为 K·2p+K−1，FULL 为 K·(p+p(p+1)/2)+K−1，TIED 为 K·p+p(p+1)/2+K−1

aic(Matrix features) → double¶

赤池信息量，用于在分量数之间取舍。

logLik 取 scoreSamples 之和，nParams = components·2·特征数 + (components−1)，返回 2·nParams − 2·logLik。参数越多惩罚越大，似然越高值越小。

注意

参数计数按对角协方差给出，每个分量计 p 个均值与 p 个方差

注意

样本数不影响 AIC，只影响 logLik 的累加项数

参数

• features (Matrix) – 用于评估的样本矩阵，列数须与拟合时一致，可与训练集不同

返回

AIC 值，无下界

抛出

• NullPointerException – features 为 null

• IllegalStateException – 尚未拟合

• IllegalArgumentException – 特征列数与拟合时不一致，或含非有限值

bic(Matrix features) → double¶

贝叶斯信息量，对参数的惩罚随样本数增长。

返回 nParams·ln(rows) − 2·logLik，nParams 与 aic 相同，rows 为传入矩阵的行数。样本数超过 e² 时 ln(rows) 大于 2，同一模型的 BIC 惩罚重于 AIC，因此 BIC 更倾向少分量。

注意

样本数取自传入矩阵而非训练集，用测试集评估时惩罚项随之变化

参数

• features (Matrix) – 用于评估的样本矩阵，列数须与拟合时一致，可与训练集不同

返回

BIC 值，无下界

抛出

• NullPointerException – features 为 null

• IllegalStateException – 尚未拟合

• IllegalArgumentException – 特征列数与拟合时不一致，或含非有限值

weights() → double[]¶

返回各分量的混合权重。

权重由 M 步的 nk/rows 得到，总和为 1；未经过 M 步时是初始化阶段的类频率。

返回

长度等于 components 的副本；未拟合时返回 null 而不抛异常

covarianceType() → CovarianceType¶

拟合时使用的协方差参数化

返回

FULL、TIED 或 DIAG

means() → Matrix¶

返回各分量的均值向量。

返回

components × 特征数 的矩阵，第 k 行是第 k 个分量的均值

抛出

• IllegalStateException – 尚未拟合

variances() → Matrix¶

返回各分量的对角方差。

矩阵元素已包含 regCovar，因此均不小于 regCovar，可直接用于高斯密度求值。

注意

只保存对角元素，非对角协方差不在模型中

返回

components × 特征数 的矩阵，第 k 行是第 k 个分量在各特征上的方差

抛出

• IllegalStateException – 尚未拟合

covariance(int component) → Matrix¶

返回某个分量的 p×p 协方差矩阵

参数

• component (int) – 分量下标，需满足 0 ≤ component < components

返回

形状 [featureCount, featureCount] 的稠密对称矩阵；DIAG 时非对角为 0

抛出

• IllegalArgumentException – component 越界

• IllegalStateException – 模型尚未拟合

converged() → boolean¶

报告 EM 是否在迭代上限内达到收敛判据。

返回

收敛为 true；未拟合或跑满 maxIterations 仍不满足为 false

iterations() → int¶

返回实际执行的 EM 轮数。

注意

收敛的那一轮也计入，即使该轮跳过了 M 步

返回

轮数，从 1 开始计；未拟合为 0，未收敛时等于 maxIterations

lowerBound() → double¶

返回最近一轮的平均每样本对数似然。

每轮 E 步把它更新为 totalLogProb/rows，因此它是收敛判据的比较对象，也是逐轮单调不减的见证量。

注意

收敛时对应最后一次 E 步，而非最后一次 M 步的参数

返回

lowerBound 值；未拟合时为 0.0

kind() → ModelKind¶

返回模型类型标识。

返回

ModelKind.GAUSSIAN_MIXTURE

write(ModelWriter writer)¶

把超参数与全部统计量写入序列化流。

写入顺序为 components、特征数、收敛标志、迭代轮数、lowerBound、权重、均值、方差。maxIterations、tolerance、regCovar、seed 不落盘。

注意

与静态 read 成对使用，读取端必须按同一顺序消费

参数

• writer (ModelWriter) – 目标写入器，由调用方负责容器头与关闭

抛出

• IllegalStateException – 尚未拟合

read(ModelReader reader) → GaussianMixturestatic¶

从序列化流重建 GaussianMixture。

注意

静态方法，调用形式为 GaussianMixture.read(reader)

注意

读回的 converged、iterations、lowerBound 来自流，不重新计算

参数

• reader (ModelReader) – 已完成容器头解析的读取器

返回

恢复统计量的新实例，超参数取 Builder 默认值

抛出

• ModelFormatException – components 或特征数不为正

final class GaussianNaiveBayes implements Estimator, Persistable¶

按类估计均值、方差与先验的高斯朴素贝叶斯分类器。

拟合时按目标值升序枚举类别，逐类计算各特征均值与总体方差（除以该类样本数），先验取类频率的对数。预测在对数域累加先验与各特征的独立高斯对数似然，避免概率连乘下溢。

方差平滑沿用 scikit-learn 的尺度无关约定：epsilon 等于 varianceSmoothing 乘以全体方差最大值，再加到每个方差上；该乘积不为正时直接使用 varianceSmoothing。

示例

Matrix features = Matrix.fromRows(new double[][] {
    {1.0, 2.0}, {1.2, 1.8}, {0.9, 2.1},
    {5.0, 8.0}, {5.4, 7.6}, {4.8, 8.2}
});
double[] targets = {0.0, 0.0, 0.0, 1.0, 1.0, 1.0};
GaussianNaiveBayes model = GaussianNaiveBayes.builder()
        .varianceSmoothing(1e-9)
        .build()
        .fit(features, targets);
double[] predicted = model.predict(features);
Matrix logPosterior = model.predictLogProbability(features);
Matrix posterior = model.predictProbability(features);

注意

类别取值按升序排列，概率并列时 predict 返回序号最小、即取值最小的类

注意

拟合样本数不少于 512 且原生内核可用时由原生实现计算均值、方差与先验

注意

varianceSmoothing 不写入序列化流，read 后取 Builder 默认值；已平滑的方差本身被保存，预测不受影响

参见：basalt.ml.Estimator, basalt.core.Persistable

方法

builder() → Builderstatic¶

创建 GaussianNaiveBayes 构建器。

返回

参数取默认值的新 Builder 实例

fit(Matrix features, double[] targets) → GaussianNaiveBayes¶

估计各类的均值、方差与先验。

类别集合来自目标数组的去重升序结果，随后两遍扫描：第一遍累计类内和与类计数得到均值、先验，第二遍累计离差平方得到总体方差，最后统一加上平滑项 epsilon。

参数

• features (Matrix) – 训练样本矩阵，行是样本、列是特征；元素必须有限

• targets (double[]) – 每行对应的类别标签，长度必须等于样本数；元素必须有限

返回

this，便于链式调用

抛出

• NullPointerException – features 或 targets 为 null

• IllegalArgumentException – targets 长度与样本数不一致，或存在非有限值

predictLogProbability(Matrix features) → Matrix¶

返回各类的对数联合概率矩阵。

每个元素等于 log(先验) 加上各特征对数高斯密度之和，形如 -0.5 · (log(2πσ²) + (x - μ)² / σ²) 的累加。数值上比直接乘概率稳定。

参数

• features (Matrix) – 样本矩阵，列数须与拟合时一致

返回

样本数 × 类别数 的矩阵，列顺序与 classes() 一致

抛出

• IllegalStateException – 尚未拟合

• IllegalArgumentException – 特征列数与拟合时不一致

predictProbability(Matrix features) → Matrix¶

把对数联合概率归一化为后验概率。

逐行减去最大值后取指数并归一，等价于对对数概率做 softmax，可避免上溢。若整行对数概率都不是有限值，则退化为按先验归一；先验之和也不为正时返回均匀分布。

参数

• features (Matrix) – 样本矩阵，列数须与拟合时一致

返回

样本数 × 类别数 的矩阵，每行元素和为 1

抛出

• IllegalStateException – 尚未拟合

• IllegalArgumentException – 特征列数与拟合时不一致

predict(Matrix features) → double[]¶

返回后验概率最大的类别标签。

先计算后验概率矩阵，再逐行取最大列，映射回原始类别取值。比较使用严格大于，因此概率并列时返回序号最小、即取值最小的类。

参数

• features (Matrix) – 样本矩阵，列数须与拟合时一致

返回

长度为样本数的类别标签数组

抛出

• IllegalStateException – 尚未拟合

• IllegalArgumentException – 特征列数与拟合时不一致

classes() → double[]¶

返回按升序排列的类别取值。

返回

类别数组的副本；未拟合时为 null

means() → Matrix¶

返回各类别各特征的均值矩阵。

返回

类别数 × 特征数 的矩阵，第 i 行对应 classes()[i]

抛出

• IllegalStateException – 尚未拟合

variances() → Matrix¶

返回各类别各特征的方差矩阵。

数值为总体方差（分母是类内样本数）加平滑项 epsilon 之后的结果，因此全部为正，不会出现零方差导致除零。

返回

类别数 × 特征数 的矩阵，第 i 行对应 classes()[i]

抛出

• IllegalStateException – 尚未拟合

logPriors() → double[]¶

返回各类别先验概率的自然对数。

注意

取对数而非概率，便于与对数似然直接相加

返回

长度等于类别数的数组副本；未拟合时为 null

kind() → ModelKind¶

返回模型类型标识。

返回

ModelKind.GAUSSIAN_NAIVE_BAYES

write(ModelWriter writer)¶

把特征数、类别、均值、方差与对数先验写入序列化流。

注意

写入顺序为特征数、类别数、类别、均值、方差、对数先验，读取端必须按同一顺序消费

参数

• writer (ModelWriter) – 目标写入器，由调用方负责容器头与关闭

抛出

• IllegalStateException – 尚未拟合

read(ModelReader reader) → GaussianNaiveBayesstatic¶

从序列化流重建 GaussianNaiveBayes 模型。

参数

• reader (ModelReader) – 已完成容器头解析的读取器

返回

只恢复统计量的模型实例，varianceSmoothing 取 Builder 默认值

抛出

• ModelFormatException – 特征数或类别数不为正

final class GridSearchCV implements Estimator¶

网格穷举加交叉验证的调参器，选优后全量重训。

交叉验证来源是 DataSplit：stratified 为 false 时调用 DataSplit.kFold，为 true 时调用 DataSplit.stratifiedKFold，两者都以 shuffle=true 与构造时的 seed 打乱，折数为 cvFolds。

param 声明的每个键对应一组候选值，所有键做笛卡尔积并按声明顺序遍历。每个组合在每折上调用一次 estimatorFactory 新建估计器，在训练折拟合、测试折预测，再用 scoring 折算为标量：ACCURACY、MACRO_F1、R2 取原值，RMSE 取负值，因此分数一律越大越好。

组合之间用各折均值比较，严格大于才替换当前最优，并列时保留先出现的组合；均值标准差按总体公式 sqrt(Σ(s-mean)²/k) 计算。选优后以同一工厂再构造一个估计器并在全部数据上拟合，作为 bestEstimator。

示例

Matrix x = Matrix.fromRows(new double[][] {
        {0.0, 0.0}, {0.2, 0.1}, {0.1, 0.3}, {0.3, 0.2},
        {1.0, 1.0}, {1.2, 0.9}, {0.9, 1.1}, {1.1, 1.2}
});
double[] y = {0.0, 0.0, 0.0, 0.0, 1.0, 1.0, 1.0, 1.0};

GridSearchCV search = GridSearchCV.builder(
                params -> KNearestNeighbors.builder()
                        .k((Integer) params.get("k"))
                        .build())
        .param("k", 1, 3)
        .scoring(Estimators.Metric.ACCURACY)
        .cv(2)
        .stratified(true)
        .seed(42L)
        .build()
        .fit(x, y);

Estimator best = search.bestEstimator();
Map<String, Object> bestParams = search.bestParams();
double bestScore = search.bestScore();
double[] label = search.predict(x);

注意

默认 scoring=ACCURACY、cvFolds=5、stratified=false、seed=42；构建时 paramGrid 为空会抛 IllegalArgumentException

注意

RMSE 评分下 bestScore 与 cvResults 中的分数均为负值，比较时仍取最大者

注意

分层划分要求每个类别的样本数不少于折数，否则 DataSplit 抛 IllegalArgumentException

注意

工厂每折调用一次，估计器实例不跨折复用，工厂内部应无共享可变状态

注意

每次 fit 会清空 cvResults 并重置最优结果

参见：basalt.ml.KFold, basalt.ml.DataSplit, basalt.ml.Estimators, basalt.ml.Estimator

方法

builder(Function<Map<String, Object>, Estimator> estimatorFactory) → Builderstatic¶

以估计器工厂创建构造器。

参数

• estimatorFactory (Function<Map<String, Object>, Estimator>) – 参数组合到未拟合估计器的映射，每折调用一次且应返回新实例

返回

新的 Builder 实例，scoring=ACCURACY、cvFolds=5、stratified=false、seed=42

抛出

• NullPointerException – estimatorFactory 为 null

fit(Matrix features, double[] targets) → GridSearchCV¶

按折评分遍历网格并重训最优模型。

先按 stratified 选择划分方式，以 cvFolds 与 seed 生成折；再对 param 网格取笛卡尔积，逐个组合在每折上新建估计器、拟合训练折、预测测试折并折算分数，得到均值与总体标准差。

比较用严格大于，并列时保留先出现的组合；结束后用最优参数在全部数据上重新拟合一次作为 bestEstimator。

注意

折数大于样本数时同样由 DataSplit 抛 IllegalArgumentException

注意

同一组合的各折互不影响，分数按折序存入 foldScores

参数

• features (Matrix) – 训练特征矩阵，行数为样本数

• targets (double[]) – 目标数组，长度须等于行数

返回

this，已完成拟合并持有最优估计器

抛出

• NullPointerException – features 或 targets 为 null

• IllegalArgumentException – 目标数量与行数不一致、数据含非有限值，或分层划分时某类样本数少于折数

predict(Matrix features) → double[]¶

用最优估计器预测。

注意

列数校验由最优估计器自身的 predict 完成

参数

• features (Matrix) – 待预测特征矩阵，列数须与训练数据一致

返回

最优估计器的预测数组，标签或回归值取决于被调优的估计器

抛出

• IllegalStateException – 尚未拟合

bestEstimator() → Estimator¶

返回在全部数据上重训的估计器。

返回

已完成拟合的 Estimator 实例

抛出

• IllegalStateException – 尚未拟合

bestParams() → Map<String, Object>¶

返回最优参数组合。

返回

不可变的参数映射，键与 param 声明一致

抛出

• IllegalStateException – 尚未拟合

bestScore() → double¶

返回最优组合的交叉验证均分。

返回

各折分数的算术平均；scoring 为 RMSE 时为负值

抛出

• IllegalStateException – 尚未拟合

cvResults() → List<CandidateResult>¶

返回每个候选组合的逐折成绩。

注意

未拟合时返回空列表，不抛异常

注意

stdScore 为总体标准差，分母取折数而非折数减一

注意

fit 会清空并重建该列表

返回

不可变列表，元素为 CandidateResult（params、meanScore、stdScore、foldScores），顺序与网格遍历顺序一致

final class HistogramGradientBoosting implements Estimator, Persistable¶

二阶直方图梯度提升，支持深度优先与叶优先生长

分裂增益按正则化目标计算：0.5*(G_L^2/(H_L+lambda) + G_R^2/(H_R+lambda) - G^2/(H+lambda)) - gamma，叶权重为 -G/(H+lambda)。直方图用相减技巧：每次只累加较小子节点，较大子节点由 parent 减 small 得到，平衡树因此只做约一半遍历。

XGBOOST 策略按层递归，由 maxDepth 控制深度；LIGHTGBM 策略用优先队列每轮分裂全局增益最大的叶，由 maxLeaves 控制叶数。两种策略都受 minSamplesLeaf、minChildWeight 与 maxDepth 约束。

累计量较大时通过 JNI 交给 Rust AVX2 内核，原生调用失败则回退到分块并行的 Java 路径。featureFraction 按轮次抽取特征子集，validationFraction 切出验证集，配合 earlyStoppingRounds 把树列表回退到最优轮次。

示例

Matrix x = Matrix.fromRows(new double[][]{
        {0.0, 1.0}, {1.0, 1.0}, {1.0, 0.0}, {2.0, 0.0},
        {2.0, 1.0}, {3.0, 0.0}, {3.0, 1.0}, {4.0, 0.0}});
double[] y = {0.0, 0.0, 1.0, 1.0, 0.0, 1.0, 1.0, 0.0};

HistogramGradientBoosting model = HistogramGradientBoosting.builder()
        .algorithm(BoostingAlgorithm.LIGHTGBM)
        .objective(BoostingObjective.LOGISTIC)
        .iterations(200)
        .learningRate(0.1)
        .maxLeaves(15)
        .featureFraction(0.8)
        .validationFraction(0.25)
        .earlyStoppingRounds(20)
        .build()
        .fit(x, y);

double[] probability = model.predictProbability(x);
double[] label = model.predict(x);
double[] history = model.lossHistory();

注意

LOGISTIC 目标要求标签恰为 0 或 1，其余取值在 fit 入口被拒绝

注意

早停触发后树列表截断到 bestIteration+1，lossHistory 同步截断

注意

write 只保存算法、目标、学习率、baseScore 与树；读回时其余超参数取 Builder 默认值

参见：basalt.ml.BoostingAlgorithm, basalt.ml.BoostingObjective, basalt.ml.DecisionTree

方法

builder() → Builderstatic¶

创建构造器，参数全部取默认值

返回

新的 Builder 实例

fit(Matrix features, double[] targets) → HistogramGradientBoosting¶

分箱、切分验证集并逐轮提升

先按 validationFraction 用 seed 打乱行号，前若干行作验证集，其余作训练集；baseScore 取训练集标签均值，LOGISTIC 下取该均值的对数几率。每轮计算梯度与 hessian、生长一棵树、以 learningRate 累加到原始得分，并记录训练与验证损失。

注意

验证集大小取 round(rows*validationFraction)，下限 1，上限 rows-2

注意

featureFraction 小于 1 时，第 i 轮用 seed + i*7919 抽取 ceil(fraction*featureCount) 个特征

参数

• features (Matrix) – 训练特征矩阵，行数为样本数

• targets (double[]) – 目标数组，长度须等于行数；LOGISTIC 时取值须为 0 或 1

返回

this，已完成拟合

抛出

• IllegalArgumentException – 目标数量与行数不一致、含非有限值，或 LOGISTIC 标签不是 0 或 1

predictRaw(Matrix features) → double[]¶

输出原始得分，未过 sigmoid

结果以 baseScore 为初值，逐棵树以 learningRate 加权累加叶值。行数乘树数不小于 2000 万时转交原生集成预测内核，否则在 Java 侧逐树累加。

参数

• features (Matrix) – 特征矩阵，列数须等于拟合时的特征数

返回

长度为行数的原始得分数组

抛出

• IllegalStateException – 尚未拟合（树列表为空）

• IllegalArgumentException – 列数不匹配或含非有限值

predictProbability(Matrix features) → double[]¶

输出正类概率，等于 sigmoid(原始得分)

注意

sigmoid 按符号分支实现，负值不经过 exp 溢出

参数

• features (Matrix) – 特征矩阵，列数须等于拟合时的特征数

返回

长度为行数的概率数组，取值 (0, 1)

抛出

• IllegalStateException – 目标不是 LOGISTIC（该校验先于拟合状态校验）

predict(Matrix features) → double[]¶

输出预测值，LOGISTIC 下为 0/1 标签

回归直接返回原始得分；LOGISTIC 把 sigmoid(原始得分) 与 0.5 比较，大于等于 0.5 取 1.0，否则取 0.0。

参数

• features (Matrix) – 特征矩阵，列数须等于拟合时的特征数

返回

长度为行数的预测数组

抛出

• IllegalStateException – 尚未拟合

• IllegalArgumentException – 列数不匹配或含非有限值

lossHistory() → double[]¶

每轮训练集平均损失

平方误差目标记录 0.5*残差^2 的均值；LOGISTIC 记录 softplus(raw) - target*raw 的均值，数值上等价于二元交叉熵。

注意

早停后长度等于保留下来的树数

返回

长度为实际训练轮数的副本；未拟合为空数组

validationHistory() → double[]¶

每轮验证集平均损失

返回

长度为实际训练轮数的副本；未设置 validationFraction 或未拟合时为空数组

featureImportances() → double[]¶

归一化的特征重要性，总和为 1

口径与 DecisionTree 一致：每次分裂的增益乘以该节点样本数，按特征累加后整体归一化到总和 1。分裂发生在特征子集上时，未参与该轮的特征不增加。

注意

读回的模型不携带重要性，返回全 0

返回

长度为特征数的副本；未拟合为空数组

treeCount() → int¶

已训练的树数

返回

树数；未拟合为 0，早停后小于 iterations

bestIteration() → int¶

验证损失最优的轮次下标

返回

最优轮次；无验证集时为最后一轮，未拟合为 iterations-1

kind() → ModelKind¶

持久化类型标识

返回

ModelKind.HISTOGRAM_BOOSTING

write(ModelWriter writer)¶

按 Persistable 契约写出提升模型

写入算法序号、目标序号、learningRate、baseScore、特征数、树数与各棵树的节点数组。maxDepth、maxLeaves、lambda 等超参数不参与序列化。

参数

• writer (ModelWriter) – 目标二进制写入器

read(ModelReader reader) → HistogramGradientBoostingstatic¶

从二进制流重建提升模型

注意

读回后 lossHistory 与 validationHistory 为空数组，featureImportances 全为 0

注意

bestIteration 置为树数减 1，训练相关字段不恢复

参数

• reader (ModelReader) – 已定位到本对象载荷起点的读取器

返回

新的 HistogramGradientBoosting 实例，可直接预测

抛出

• ModelFormatException – 算法或目标序号越界，或特征数不大于 0、树数不在 [1, 100000]

enum ImpurityCriterion¶

决策树用于最大化信息增益的节点不纯度

GINI 计算 1 - Σp^2，ENTROPY 计算 -Σ p*log2(p)，两者绑定 TreeTask.CLASSIFICATION。MSE 绑定 TreeTask.REGRESSION，其 impurity 方法直接抛出 IllegalStateException，因为回归分裂改用和与平方和的代数等价形式，不经过类别计数。

每个常量在构造时绑定任务，task() 暴露该绑定。DecisionTree.Builder 在 build() 时校验 criterion.task() 与 task 一致，准则与任务不会在运行期错配。

示例

ImpurityCriterion criterion = ImpurityCriterion.ENTROPY;

DecisionTree tree = DecisionTree.builder()
        .criterion(criterion)
        .task(criterion.task())
        .maxDepth(4)
        .build();

注意

骨架中的 ENTROPY 与 MSE 条目是枚举常量，签名里出现的参数即构造时传入的任务标记

注意

MSE 只作任务标识，逐节点计算不经过 impurity

参见：basalt.ml.DecisionTree, basalt.ml.TreeTask

方法

task() → TreeTask¶

该准则绑定的任务类型

注意

Builder 用它校验准则与任务是否匹配

返回

构造时传入的 TreeTask

final class IsolationForest implements Estimator, Persistable¶

随机轴对齐切分的无监督孤立森林异常检测器。

每棵树在 min(行数, maxSamples) 个无放回抽样的样本上递归切分：随机挑一个取值不全相同的特征，在该列最小值与最大值之间均匀取切点，小于等于切点的样本进左子树；样本数不超过 1、深度达到 max(1, ceil(log2(effectiveMaxSamples)))、或所选特征无区分度时成为叶节点，叶节点保存 depth + c(n)。

路径长度归一化 s(x, n) = 2^(-E(h(x))/c(n))，E(h) 为样本在各棵树上路径长度的平均值，c(n) 为二叉搜索树平均路径修正项：n <= 1 取 0，n == 2 取 1，否则取 2*(ln(n-1) + EulerGamma) - 2*(n-1)/n。分数落在 (0, 1]，越接近 1 越异常，约 0.5 为平均路径长度。

contamination 只影响判决阈值：拟合末尾对训练集的 0.5 - s 升序排序，取下标 max(0, min(rows-1, floor(rows * contamination))) 处的值作为 threshold。decisionFunction 返回 0.5 - s - threshold，predict 对非负者给 +1.0、负者给 -1.0。

示例

Matrix features = Matrix.fromRows(new double[][] {
        {0.0, 0.1}, {0.2, 0.0}, {0.1, 0.2}, {0.15, 0.1},
        {9.0, 9.2}, {9.4, 8.8}, {10.0, 9.0}, {0.3, 0.25}
});

IsolationForest forest = IsolationForest.builder()
        .trees(100)
        .maxSamples(256)
        .contamination(0.25)
        .seed(42L)
        .build()
        .fit(features);

double[] score = forest.anomalyScore(features);
double[] decision = forest.decisionFunction(features);
double[] label = forest.predict(features);

注意

默认 trees=100、maxSamples=256、contamination=0.1、seed=42；trees 须为正，maxSamples 须 >= 2，contamination 须在 (0, 0.5) 开区间内

注意

随机性全部来自 seed：主随机源为每棵树派生一个子种子，同 seed 同数据得到相同的树与阈值

注意

write 保存全部超参数、featureCount、effectiveMaxSamples、threshold 与树结构，read 直接沿用读入的阈值，不重新打分

注意

样本数少于 maxSamples 时 effectiveMaxSamples 退化为行数，c(n) 与树高上限随之按行数计算

参见：basalt.ml.Estimator, basalt.core.Persistable, basalt.ml.Estimators

方法

builder() → Builderstatic¶

创建构造器，超参数取默认值。

返回

新的 Builder 实例，trees=100、maxSamples=256、contamination=0.1、seed=42

fit(Matrix features) → IsolationForest¶

仅凭特征拟合，等价于 fit(features, null)。

参数

• features (Matrix) – 训练特征矩阵，行数为样本数，列数为特征数

返回

this，已完成拟合并可打分

抛出

• NullPointerException – features 为 null

• IllegalArgumentException – 特征含非有限值

fit(Matrix features, double[] ignoredTargets) → IsolationForest¶

建树并对训练集打分确定阈值。

effectiveMaxSamples 取行数与 maxSamples 的较小值，树高上限为 max(1, ceil(log2(effectiveMaxSamples)))。每棵树用主随机源派生的子种子做无放回抽样，再随机选一个取值不全相同的特征、在列最小与最大之间均匀取切点递归下分。

全部树建成后对训练集计算 0.5 - s，升序排序并取 contamination 对应的分位值作为 threshold，供 decisionFunction 与 predict 使用。

注意

effectiveMaxSamples 极小时树高上限至少为 1

注意

每棵树的抽样与切点都由各自的子种子决定，treeCount 棵树互相独立

参数

• features (Matrix) – 训练特征矩阵，行数为样本数

• ignoredTargets (double[]) – 占位参数，内容被完全忽略，可为 null

返回

this，已完成拟合

抛出

• NullPointerException – features 为 null

• IllegalArgumentException – 特征含非有限值

anomalyScore(Matrix features) → double[]¶

计算归一化异常分数 2^(-E(h)/c(n))。

注意

E(h) 为样本在各棵树上的平均路径长度，归一化分母 c(n) 用 effectiveMaxSamples 计算

注意

c(n) 下限截到 1e-12，避免退化数据导致除零

参数

• features (Matrix) – 待打分特征矩阵，列数须等于拟合时的特征数

返回

长度等于行数的分数数组，取值 (0, 1]，越接近 1 越异常

抛出

• IllegalStateException – 尚未拟合（树列表为空）

• IllegalArgumentException – 列数不符或特征含非有限值

decisionFunction(Matrix features) → double[]¶

返回以阈值为零点的偏移分数。

注意

阈值由拟合时训练集的 contamination 分位确定，未拟合时无法得到有意义的零点

参数

• features (Matrix) – 待打分特征矩阵，列数须等于拟合时的特征数

返回

0.5 - s - threshold，正值表示正常点，负值表示异常点

抛出

• IllegalStateException – 尚未拟合

• IllegalArgumentException – 列数不符或特征含非有限值

predict(Matrix features) → double[]¶

输出 +1.0 正常、-1.0 异常。

注意

判定规则为 decisionFunction 结果不小于 0 时取 +1.0，否则取 -1.0

参数

• features (Matrix) – 待预测特征矩阵，列数须等于拟合时的特征数

返回

长度等于行数的标签数组，正常为 +1.0，异常为 -1.0

抛出

• IllegalStateException – 尚未拟合

• IllegalArgumentException – 列数不符或特征含非有限值

kind() → ModelKind¶

返回模型类型标识。

返回

ModelKind.ISOLATION_FOREST

write(ModelWriter writer)¶

写入超参数、阈值与全部树结构。

注意

依次写入 trees、maxSamples、contamination、seed、featureCount、effectiveMaxSamples、threshold 与树数

注意

阈值随模型一并保存，读回后不再重新计算

参数

• writer (ModelWriter) – 目标写入器，由调用方负责容器头与提交

抛出

• IllegalStateException – 尚未拟合（树列表为空）

read(ModelReader reader) → IsolationForeststatic¶

重建孤立森林模型。

参数

• reader (ModelReader) – 已完成容器头解析的读取器

返回

含已训练树与阈值的模型实例，可直接用于 predict

抛出

• ModelFormatException – 树数、特征数或实际读到的树数不为正

final class KBinsDiscretizer implements Transformer, Estimator¶

按分位数、等宽或一维 K-Means 把连续特征离散为箱。

拟合逐列计算 nBins+1 个边界：edges[0] 取该列最小值、edges[nBins] 取最大值，中间边界按策略生成。UNIFORM 取 min + b*(max-min)/nBins；QUANTILE 先排序该列，再在位置 (rows-1)*b/nBins 处对相邻样本做线性插值；KMEANS 在该列上运行一维 KMeans（clusters=nBins、maxIterations=50、seed=42），取排序后相邻质心的中点作为边界。列内取值全相同时，中间边界全部等于该常量。

变换用边界比较定位：从 b=1 起找第一个满足 value < edges[b] 的 b，返回 b-1；没有任何边界满足时落入最后一箱，因此区间是左闭右开，恰好等于边界值的样本归入右侧箱。ORDINAL 输出与输入同宽、元素为箱序号 0..nBins-1；ONEHOT_DENSE 输出宽度为 特征数 * nBins，每个原始特征占一段连续列，命中位置置 1。

逆变换用箱中点 0.5*(edges[b] + edges[b+1]) 还原：ORDINAL 先把箱序号四舍五入并夹到 [0, nBins-1]；ONEHOT_DENSE 对每段取最大值所在的列，并列时取靠前的箱。

示例

Matrix x = Matrix.fromRows(new double[][] {
        {0.0, 10.0}, {0.5, 12.0}, {1.0, 14.0},
        {2.0, 16.0}, {4.0, 18.0}, {8.0, 20.0}
});

KBinsDiscretizer discretizer = KBinsDiscretizer.builder()
        .nBins(3)
        .strategy(KBinsDiscretizer.Strategy.QUANTILE)
        .encode(KBinsDiscretizer.Encode.ORDINAL)
        .build()
        .fit(x);

Matrix binned = discretizer.transform(x);
Matrix restored = discretizer.inverseTransform(binned);
double[][] edges = discretizer.binEdges();

注意

默认 nBins=5、strategy=QUANTILE、encode=ORDINAL；nBins 须 >= 2

注意

变换前必须 fit，否则抛 IllegalStateException；输入列数须等于拟合时的特征数

注意

列内取值全相同的特征恒落在最后一箱，因为没有任何边界能严格大于该值

注意

KMEANS 策略的随机性固定为 seed=42，同一列多次拟合得到相同边界

注意

write 保存 nBins、策略、编码与逐列边界，read 后无需重新拟合即可 transform

参见：basalt.ml.Transformer, basalt.ml.KMeans, basalt.ml.OneHotEncoder

方法

builder() → Builderstatic¶

创建构造器，nBins=5、QUANTILE、ORDINAL。

返回

新的 Builder 实例

fit(Matrix features) → KBinsDiscretizer¶

仅凭特征拟合，等价于 fit(features, null)。

参数

• features (Matrix) – 训练特征矩阵，列数决定边界组数

返回

this，已算出逐列边界

抛出

• NullPointerException – features 为 null

• IllegalArgumentException – 特征含非有限值

fit(Matrix features, double[] ignoredTargets) → KBinsDiscretizer¶

逐列计算 nBins+1 个箱边界。

每列取最小与最大值作为首尾边界，中间边界按策略生成；列内取值全相同时中间边界退化为该常量。

注意

QUANTILE 的插值位置为 (rows-1)*b/nBins，等价于 numpy 默认的 linear 分位

注意

KMEANS 每列单独跑一次一维 KMeans，迭代上限 50、种子 42

参数

• features (Matrix) – 训练特征矩阵，列数决定边界组数

• ignoredTargets (double[]) – 占位参数，内容被完全忽略，可为 null

返回

this，已完成拟合

抛出

• NullPointerException – features 为 null

• IllegalArgumentException – 特征含非有限值

transform(Matrix features) → Matrix¶

把特征映射为箱序号或 One-Hot。

注意

判定为 value < edges[b]，等于边界值的样本进入右侧箱

注意

ONEHOT_DENSE 的列顺序为特征优先，每个特征的 nBins 列连续排列

参数

• features (Matrix) – 待转换矩阵，列数须等于拟合时的特征数

返回

ORDINAL 为 行数 × 特征数 的箱序号矩阵；ONEHOT_DENSE 为 行数 × (特征数 * nBins) 的 0/1 矩阵

抛出

• IllegalStateException – 尚未拟合

• IllegalArgumentException – 列数不符或特征含非有限值

inverseTransform(Matrix transformed) → Matrix¶

用箱中点还原近似原特征。

注意

ORDINAL 先把箱序号四舍五入再夹到 [0, nBins-1]，越界值被截断

注意

ONEHOT_DENSE 取每段最大值位置，并列时取靠前的箱；全零段落到第 0 箱

注意

还原值只保证落在对应箱内，不等于原始输入

参数

• transformed (Matrix) – 形状与 transform 输出一致的矩阵

返回

行数 × 特征数 的近似原特征矩阵，元素为对应箱的中点

抛出

• IllegalStateException – 尚未拟合

• IllegalArgumentException – 列数不符（ORDINAL 需特征数列，ONEHOT_DENSE 需特征数 * nBins 列）或含非有限值

predict(Matrix features) → double[]¶

返回展平后的离散结果。

注意

元素仍是箱序号或 0/1，便于把转换结果当作估计器输出消费

参数

• features (Matrix) – 待转换矩阵，列数须等于拟合时的特征数

返回

transform 结果按行优先展平的一维数组，长度为 行数 × 输出列数

抛出

• IllegalStateException – 尚未拟合

• IllegalArgumentException – 列数不符或特征含非有限值

binEdges() → double[][]¶

返回逐列的箱边界副本。

注意

返回深拷贝，修改不影响模型内部边界

返回

二维数组 [特征数][nBins+1]，首尾为列最小值与最大值

抛出

• IllegalStateException – 尚未拟合

kind() → ModelKind¶

返回模型类型标识。

返回

ModelKind.KBINS_DISCRETIZER

write(ModelWriter writer)¶

写入箱数、策略、编码与逐列边界。

注意

策略与编码以枚举 ordinal 落盘

注意

按特征顺序写入每组 nBins+1 个边界

参数

• writer (ModelWriter) – 目标写入器，由调用方负责容器头与提交

抛出

• IllegalStateException – 尚未拟合

read(ModelReader reader) → KBinsDiscretizerstatic¶

读回箱数、策略、编码与逐列边界。

参数

• reader (ModelReader) – 已完成容器头解析的读取器

返回

已可直接 transform 的实例

抛出

• ModelFormatException – 箱数小于 2、特征数不为正，或策略、编码序号越界

final class KFold¶

K 折交叉验证划分器，默认打乱且种子为 42。

划分是位置切分：先按 shuffle 与 seed 得到行序（不打乱时即 0..rows-1），第 f 折的测试区间为 [f*rows/folds, (f+1)*rows/folds)，其余行按行序首尾拼接成训练集。行数不能被折数整除时，多出的样本落在靠后的折上。

是否打乱由 shuffle 决定，构造器默认 true，与 sklearn 的默认 false 不同；seed 只在 shuffle 为 true 时起作用，相同 seed 与相同数据得到完全一致的划分。

每折以 DataSplit.Fold 返回四个字段：trainFeatures、trainTargets、testFeatures、testTargets，均为按索引复制出的新数组，可安全修改。

示例

Matrix x = Matrix.fromRows(new double[][] {
        {0.0, 1.0}, {1.0, 0.0}, {1.0, 1.0}, {2.0, 2.0},
        {2.0, 3.0}, {3.0, 2.0}, {3.0, 3.0}, {4.0, 4.0}
});
double[] y = {0.0, 0.0, 1.0, 1.0, 1.0, 0.0, 1.0, 0.0};

KFold kfold = new KFold(4);
List<DataSplit.Fold> folds = kfold.split(x, y);

DataSplit.Fold first = folds.get(0);
Matrix trainX = first.trainFeatures();
Matrix testX = first.testFeatures();
int count = kfold.folds();
boolean shuffled = kfold.shuffle();

注意

构造器只校验 folds >= 2，folds 超过样本数的检查延到 split 阶段

注意

类本身不持有数据，同一实例可对不同矩阵反复 split

注意

目标数组只随行搬运，划分过程不看标签取值，不做分层

参见：basalt.ml.DataSplit, basalt.ml.GridSearchCV, basalt.ml.StratifiedKFold

构造器

KFold(int folds)¶

按折数构造，默认打乱且种子为 42。

注意

等价于 KFold(folds, true, 42L)

参数

• folds (int) – 折数，须 >= 2

抛出

• IllegalArgumentException – folds 小于 2

KFold(int folds, boolean shuffle, long seed)¶

指定折数、是否打乱与随机种子。

参数

• folds (int) – 折数，须 >= 2

• shuffle (boolean) – 是否在划分前打乱行序；false 时按原始行号顺序切分

• seed (long) – 打乱所用随机源种子，shuffle 为 false 时无效

抛出

• IllegalArgumentException – folds 小于 2

方法

folds() → int¶

返回折数。

返回

构造时给定的折数

shuffle() → boolean¶

返回是否打乱。

返回

true 表示划分前按 seed 打乱行序

split(Matrix features, double[] targets) → List<DataSplit.Fold>¶

生成各折的训练与测试划分。

第 f 折测试区间取 [f*rows/folds, (f+1)*rows/folds)，训练集为其余区间的拼接，因此每折训练集大小等于 rows 减去该折测试集大小。

注意

返回的矩阵与数组都是新分配的副本，与原数据不共享存储

参数

• features (Matrix) – 特征矩阵，行数为样本数

• targets (double[]) – 目标数组，长度须等于行数，仅随行搬运

返回

长度为 folds 的列表，每项为 DataSplit.Fold，含 trainFeatures、trainTargets、testFeatures、testTargets

抛出

• NullPointerException – features 或 targets 为 null

• IllegalArgumentException – 折数大于样本数、目标数量与行数不一致，或数据含非有限值

final class KMeans implements Estimator, Persistable¶

K-Means++ 播种的 Lloyd 迭代聚类，支持多次重启。

分配步逐样本计算到 k 个质心的平方欧氏距离，按行区间并行执行；质心累加与求均值为串行循环，且复用预分配缓冲区。多次重启各自独立初始化，保留惯性最小的一次结果。

第 r 次重启使用 seed + 7919r 作为随机源种子。空簇修复从当前分配中挑选距离所属质心最远、且所属簇样本数大于 1 的样本，把它捐给空簇并以该样本位置作为新质心；找不到合格捐赠者时退化为全局最远样本。

示例

Matrix features = Matrix.fromRows(new double[][] {
    {0.0, 0.0}, {0.4, 0.2}, {0.1, 0.5},
    {9.6, 9.8}, {10.0, 10.2}, {9.4, 9.9}
});
KMeans kmeans = KMeans.builder()
        .clusters(2)
        .restarts(4)
        .maxIterations(200)
        .seed(7L)
        .build()
        .fit(features);
double[] assignment = kmeans.predict(features);
double[] distance = kmeans.transform(features);
Matrix centers = kmeans.centroids();
double inertia = kmeans.inertia();

注意

tolerance 作用于质心位移：全部质心各分量位移的平方和不超过 tolerance² 时停止迭代

注意

inertia 在迭代结束后按最终质心重新计算，等于各样本到最近质心平方距离之和，可能与最后一轮分配时的值略有差异

注意

样本数不少于 1024、特征数不少于 8 且原生内核可用时，整个拟合交给原生实现

注意

特征数不少于 128 时，单轮分配步也可能切换到原生内核

参见：basalt.ml.Estimator, basalt.core.Persistable

方法

builder() → Builderstatic¶

创建 KMeans 构建器。

返回

参数取默认值的新 Builder 实例

fit(Matrix features) → KMeans¶

只用特征拟合，目标数组缺省为 null。

参数

• features (Matrix) – 训练样本矩阵，行是样本、列是特征

返回

this，便于链式调用

fit(Matrix features, double[] ignoredTargets) → KMeans¶

执行 K-Means++ 初始化与 Lloyd 迭代。

首个质心从样本中均匀随机抽取，后续质心按到最近已有质心的平方距离加权抽取；若全部距离之和为 0，则改用簇序号对样本数取模。每次重启跑满收敛条件或 maxIterations，取惯性最小者。

注意

每次重启都新建 Random，因此同一 seed 与 restarts 组合可复现结果

参数

• features (Matrix) – 训练样本矩阵，行是样本、列是特征；元素必须有限

• ignoredTargets (double[]) – 占位参数；聚类忽略监督目标，可为 null

返回

this，便于链式调用

抛出

• IllegalArgumentException – features 为 null 或含非有限值，或簇数大于样本数

predict(Matrix features) → double[]¶

把每个样本分配给最近的质心。

参数

• features (Matrix) – 样本矩阵，列数须与拟合时一致

返回

长度为样本数的簇索引，以 double 表示

抛出

• IllegalStateException – 尚未拟合

• IllegalArgumentException – 特征列数与拟合时不一致

transform(Matrix features) → double[]¶

返回各样本到其所属质心的平方距离。

先按最近质心确定归属，再取该质心与样本的平方欧氏距离。返回一维数组，每个样本一个标量，而不是距离矩阵；需要欧氏距离时自行开方。

参数

• features (Matrix) – 样本矩阵，列数须与拟合时一致

返回

长度为样本数的平方距离数组

抛出

• IllegalStateException – 尚未拟合

• IllegalArgumentException – 特征列数与拟合时不一致

centroids() → Matrix¶

返回最终质心矩阵。

返回

簇数 × 特征数 的矩阵，每行一个质心

抛出

• IllegalStateException – 尚未拟合

inertia() → double¶

返回最优重启的惯性值。

返回

样本到最近质心平方距离之和；未拟合时为 0

iterations() → int¶

返回最优重启实际执行的迭代轮数。

返回

1 到 maxIterations 之间的轮数；未拟合时为 0

restarts() → int¶

返回已完成的随机重启次数。

返回

拟合后等于配置的 restarts；未拟合或由 read 重建的模型为 0

kind() → ModelKind¶

返回模型类型标识。

返回

ModelKind.KMEANS

write(ModelWriter writer)¶

写入簇数、特征数、惯性、迭代轮数与质心。

注意

tolerance、seed、restarts 与 threads 不写入流，read 后回到 Builder 默认值

参数

• writer (ModelWriter) – 目标写入器，由调用方负责容器头与关闭

抛出

• IllegalStateException – 尚未拟合

read(ModelReader reader) → KMeansstatic¶

从序列化流重建 KMeans 模型。

参数

• reader (ModelReader) – 已完成容器头解析的读取器

返回

只恢复质心与统计量的模型实例，可直接用于 predict

抛出

• ModelFormatException – 簇数或特征数不为正

final class KNearestNeighbors implements Estimator¶

统一权重的 KNN 分类器。

fit 只保存训练集的副本（特征 copy、标签 clone），不做归一化或索引结构；predict 对每个查询样本线性扫描全部训练行，用距离度量维护容量为 k 的最大堆，堆中即 k 个最近邻，再按标签多数投票。

投票是统一权重，距离不参与加权；票数相同时选择数值更小的标签，因此结果与 HashMap 迭代顺序无关，完全可复现。单次查询的时间为 O(n·d)，额外内存为 O(k) 加上训练集副本。

示例

Matrix x = Matrix.fromRows(new double[][]{{0, 0}, {0, 1}, {1, 0}, {1, 1}});
double[] y = {0, 1, 1, 0};
KNearestNeighbors knn = KNearestNeighbors.builder()
        .k(3)
        .metric(DistanceMetric.MANHATTAN)
        .build()
        .fit(x, y);
double[] labels = knn.predict(x);

注意

k 在 build() 时校验为正，fit 时再校验不超过训练样本数

注意

特征未标准化，量纲差异会主导欧氏距离

注意

训练集在 fit 时复制，之后修改原 Matrix 不影响模型

参见：basalt.ml.KNeighborsRegressor, basalt.ml.DistanceMetric, basalt.ml.KNearestNeighbors.Builder

方法

builder() → Builderstatic¶

创建构建器，默认 k=5、欧氏距离。

注意

每次调用都返回独立实例，可安全地分别配置

返回

新的 Builder，字段取默认值

fit(Matrix features, double[] targets) → KNearestNeighbors¶

保存训练集副本，不做任何预计算。

注意

重复 fit 会用新数据覆盖旧训练集

参数

• features (Matrix) – 训练特征矩阵，列数即特征维数

• targets (double[]) – 训练标签数组，取值可以是任意 double

返回

this

抛出

• NullPointerException – features 或 targets 为 null

• IllegalArgumentException – k 大于训练样本数，或行数与标签长度不符、数据含非有限值

predict(Matrix features) → double[]¶

对每个样本取 k 近邻多数投票。

注意

平票时返回数值更小的标签，保证确定性

参数

• features (Matrix) – 待预测特征矩阵，列数须等于训练特征数

返回

每行一个训练集中出现过的标签值

抛出

• IllegalStateException – 尚未 fit

• IllegalArgumentException – 列数不匹配或含非有限值

final class KNeighborsRegressor implements Estimator¶

统一权重的 KNN 回归器。

与分类版共享同一套流程：fit 只复制训练集，predict 逐样本线性扫描并用容量为 k 的最大堆保留最近邻。区别在聚合方式——对 k 个邻居的目标值取算术平均，不做距离加权。

单次查询的时间为 O(n·d)，额外内存为 O(k) 加上训练集副本。目标值未做任何变换，因此预测结果始终落在训练目标的最小值与最大值之间，不会外推。

示例

Matrix x = Matrix.fromRows(new double[][]{{0, 0}, {0, 1}, {1, 0}, {1, 1}});
double[] y = {0.0, 1.0, 1.0, 2.0};
KNeighborsRegressor regressor = KNeighborsRegressor.builder().k(2).build().fit(x, y);
double[] predictions = regressor.predict(x);

注意

k 在 fit 时校验不超过训练样本数

注意

距离加权、叶节点裁剪等加速结构均未实现

参见：basalt.ml.KNearestNeighbors, basalt.ml.DistanceMetric

方法

builder() → Builderstatic¶

创建构建器，默认 k=5、欧氏距离。

返回

新的 Builder，字段取默认值

fit(Matrix features, double[] targets) → KNeighborsRegressor¶

保存训练集副本，不做预计算。

参数

• features (Matrix) – 训练特征矩阵

• targets (double[]) – 训练目标数组，长度等于行数

返回

this

抛出

• NullPointerException – features 或 targets 为 null

• IllegalArgumentException – k 大于训练样本数，或形状不符、数据含非有限值

predict(Matrix features) → double[]¶

对 k 个最近邻的目标值取平均。

参数

• features (Matrix) – 待预测特征矩阵，列数须等于训练特征数

返回

每行一个连续预测值，为 k 个邻居目标的算术平均

抛出

• IllegalStateException – 尚未 fit

• IllegalArgumentException – 列数不匹配或含非有限值

final class Kernel¶

四种半正定核函数：LINEAR、RBF、POLY 与 SIGMOID。

四种核的定义为 LINEAR K(x, y) = x · y；RBF K(x, y) = exp(-gamma * ||x - y||^2)；POLY K(x, y) = (gamma * (x · y) + coef0)^degree；SIGMOID K(x, y) = tanh(gamma * (x · y) + coef0)。SIGMOID 不保证半正定，仅在参数合适时可用作核。

gamma 控制内积或距离的缩放：RBF 中越大核越窄、单个样本影响半径越小；POLY 与 SIGMOID 中缩放内积后再叠加 coef0。degree 只对 POLY 生效，coef0 对 POLY 与 SIGMOID 生效，LINEAR 不使用这三个参数。

评估有两条路径：evaluate 直接在原数组上按偏移与长度计算单点核值，避免为每个样本对分配临时向量；gram 逐行逐列调用 evaluate 组装批量的 Gram 矩阵。

示例

Matrix a = Matrix.fromRows(new double[][] {{1.0, 2.0}, {2.0, 1.0}});
Matrix b = Matrix.fromRows(new double[][] {{0.0, 1.0}, {3.0, 3.0}});

Kernel kernel = Kernel.rbf(0.5);
double value = kernel.evaluate(a.data(), 0, b.data(), 0, 2);
Matrix gram = kernel.gram(a, b);

Kernel poly = Kernel.poly(3, 0.25, 1.0);
double degree = poly.degree();
double coef0 = poly.coef0();

注意

构造器允许 gamma 取 0，此时 evaluate 内部改用 1/max(1, length) 作为缩放，等价于按维数缩放；rbf/poly/sigmoid 工厂则要求 gamma 严格为正

注意

linear() 固定 gamma=1.0、degree=3、coef0=0.0；sigmoid 工厂固定 degree=3，只有 poly 工厂会改写 degree

注意

gram 不做分块与原生加速，时间复杂度为 rows(a) * rows(b) * 特征数

注意

write 按类型序号、gamma、degree、coef0 的顺序落盘，read 依赖 Type 枚举的声明顺序

参见：basalt.ml.SVC, basalt.ml.KernelRidge, basalt.ml.KernelPCA

构造器

Kernel(Type type, double gamma, int degree, double coef0)¶

按显式类型与参数构造核函数。

注意

构造器不按类型裁剪参数，未参与计算的字段照原样保存

参数

• type (Type) – 核类型，取 Type 枚举值，不接受 null

• gamma (double) – 缩放系数，须有限且非负；取 0 时评估按 1/max(1, length) 替代

• degree (int) – POLY 的多项式次数，须 >= 1

• coef0 (double) – POLY 与 SIGMOID 的常数项，须有限

返回

持有给定参数的核函数实例

抛出

• NullPointerException – type 为 null

• IllegalArgumentException – gamma 非有限或为负、degree 小于 1、coef0 非有限

方法

linear() → Kernelstatic¶

构造线性核 K(x, y) = x · y。

注意

三个参数都不参与 LINEAR 的计算，仅随实例保存并参与序列化

返回

gamma=1.0、degree=3、coef0=0.0 的 LINEAR 核

rbf(double gamma) → Kernelstatic¶

构造高斯核 exp(-gamma * ||x - y||²)。

参数

• gamma (double) – 尺度系数，须为正且有限；越大核越窄、影响半径越小

返回

degree=3、coef0=0.0 的 RBF 核

抛出

• IllegalArgumentException – gamma 小于等于 0 或非有限

poly(int degree, double gamma, double coef0) → Kernelstatic¶

构造多项式核 (gamma * x·y + coef0)^degree。

参数

• degree (int) – 多项式次数，须 >= 1

• gamma (double) – 内积缩放系数，须为正且有限

• coef0 (double) – 加在内积上的常数项，须有限

返回

POLY 核实例

抛出

• IllegalArgumentException – gamma 非正或非有限，或 degree 小于 1、coef0 非有限

sigmoid(double gamma, double coef0) → Kernelstatic¶

构造 sigmoid 核 tanh(gamma * x·y + coef0)。

参数

• gamma (double) – 内积缩放系数，须为正且有限

• coef0 (double) – 双曲正切内的偏移量，须有限

返回

degree=3 的 SIGMOID 核实例

抛出

• IllegalArgumentException – gamma 非正或非有限，或 coef0 非有限

type() → Type¶

返回核类型。

返回

Type 枚举值 LINEAR、RBF、POLY 或 SIGMOID

gamma() → double¶

返回 gamma 系数。

返回

RBF、POLY、SIGMOID 的尺度系数；LINEAR 固定为 1.0

degree() → int¶

返回多项式次数。

返回

POLY 的次数；其余类型固定为 3

coef0() → double¶

返回常数项 coef0。

返回

POLY 与 SIGMOID 的常数项；LINEAR 与 RBF 为 0.0

evaluate(double[] x, int xOffset, double[] y, int yOffset, int length) → double¶

按偏移与长度计算两点核值。

注意

gamma 为 0 时内部改用 1/max(1, length)，即按维数缩放

注意

不检查偏移与长度的越界，由调用方保证区间合法

参数

• x (double[]) – 左向量所在的数组

• xOffset (int) – 左向量在 x 中的起始下标

• y (double[]) – 右向量所在的数组

• yOffset (int) – 右向量在 y 中的起始下标

• length (int) – 参与计算的维数

返回

核函数值：LINEAR 为内积，RBF 落在 (0, 1]，POLY 与 SIGMOID 可为任意实数

gram(Matrix a, Matrix b) → Matrix¶

计算两批样本之间的 Gram 矩阵。

注意

逐元素调用 evaluate，串行双重循环，无分块或原生加速

参数

• a (Matrix) – 左样本矩阵，行数为样本数，列数为特征数

• b (Matrix) – 右样本矩阵，列数须与 a 相同

返回

rows(a) × rows(b) 的矩阵，第 i 行第 j 列为 K(a 的第 i 行, b 的第 j 行)

抛出

• IllegalArgumentException – 两个矩阵的列数不同

write(ModelWriter writer)¶

写入类型序号、gamma、degree 与 coef0。

注意

依次写入一个 int 序号、一个 double、一个 int 与一个 double，共四个字段

注意

类型以 Type.ordinal() 落盘，read 依赖同一枚举顺序

参数

• writer (ModelWriter) – 目标写入器，由调用方负责容器头与提交

read(ModelReader reader) → Kernelstatic¶

从序列化流重建核函数。

参数

• reader (ModelReader) – 已完成容器头解析的读取器

返回

参数与写入时一致的 Kernel 实例

抛出

• ModelFormatException – 类型序号不在 Type 枚举范围内

final class KernelDensity implements Estimator, Persistable¶

高斯与 TOPHAT 核的核密度估计，输出对数密度。

拟合不做任何参数估计，只把训练样本复制一份作为核中心集合，因此打分代价为查询点数、训练样本数与特征数三者之积。

GAUSSIAN 核下 log p(x) = -log(n) - d*log(bandwidth) - 0.5*d*log(2π) + log Σ exp(-||x - x_i||² / (2 * bandwidth²))，求和用减去最大项的方式做 log-sum-exp 以避免下溢；TOPHAT 核下以带宽为半径的球内命中数 hits 决定密度，log p(x) = log(hits / n) - [0.5*d*log(π) - logΓ(d/2 + 1) + d*log(bandwidth)]，无命中时返回负无穷。

bandwidth 是唯一平滑参数：越大分布越平滑、峰值越低，方差约等于 bandwidth² 加上训练样本自身方差。sample 从训练行中均匀抽取一个中心再叠加噪声，GAUSSIAN 加各向同性正态噪声，TOPHAT 加逐维均匀噪声。

示例

Matrix train = Matrix.fromRows(new double[][] {
        {0.0}, {0.4}, {1.0}, {1.2}, {2.0}, {3.5}
});
Matrix query = Matrix.fromRows(new double[][] {{0.5}, {1.5}, {3.0}});

KernelDensity kde = KernelDensity.builder()
        .bandwidth(0.5)
        .kernel(KernelDensity.KernelType.GAUSSIAN)
        .build()
        .fit(train);

double[] logDensity = kde.scoreSamples(query);
Matrix drawn = kde.sample(100, 7L);
double bandwidth = kde.bandwidth();

注意

默认 bandwidth=1.0、kernel=GAUSSIAN；bandwidth 须为正且有限

注意

scoreSamples 与 predict 返回对数密度而非概率密度，需要密度时自行取 exp

注意

write 只保存 bandwidth、核类型、特征数与训练样本，模型无其他可训练状态

注意

TOPHAT 在稀疏数据上常出现查询点邻域内无训练样本的情况，此时整行为负无穷

参见：basalt.ml.Estimator, basalt.core.Persistable, basalt.ml.Kernel

方法

builder() → Builderstatic¶

创建构造器，bandwidth=1.0、核为 GAUSSIAN。

返回

新的 Builder 实例

fit(Matrix features) → KernelDensity¶

仅凭样本拟合，等价于 fit(features, null)。

参数

• features (Matrix) – 训练样本矩阵，行数为样本数，列数为特征数

返回

this，已保存训练样本

抛出

• NullPointerException – features 为 null

• IllegalArgumentException – 特征含非有限值

fit(Matrix features, double[] ignoredTargets) → KernelDensity¶

保存训练样本副本与特征数。

KDE 无需估计参数，拟合只把特征矩阵复制一份作为核中心集合，所有距离在打分时按需计算。

注意

保存的是副本，拟合后再修改原矩阵不影响模型

参数

• features (Matrix) – 训练样本矩阵，行数为样本数

• ignoredTargets (double[]) – 占位参数，内容被完全忽略，可为 null

返回

this，已完成拟合

抛出

• NullPointerException – features 为 null

• IllegalArgumentException – 特征含非有限值

scoreSamples(Matrix features) → double[]¶

输出每个查询点的对数密度 log p(x)。

GAUSSIAN 下对每个查询点累加 -||x - x_i||²/(2*bandwidth²)，再以 log-sum-exp 汇总并加上归一化常数；TOPHAT 下统计平方距离不超过 bandwidth² 的训练样本数，按球体积归一化。

注意

复杂度为查询行数 × 训练行数 × 特征数，无树结构或原生加速

注意

GAUSSIAN 的归一化常数包含 -log(n) 与 -d*log(bandwidth)

参数

• features (Matrix) – 查询点矩阵，列数须等于拟合时的特征数

返回

长度等于行数的对数密度数组；TOPHAT 下无命中时为负无穷

抛出

• IllegalStateException – 尚未拟合

• IllegalArgumentException – 列数不符或特征含非有限值

sample(int nSamples, long seed) → Matrix¶

从拟合的密度中抽取随机样本。

注意

每个样本先均匀抽取一个训练行作为中心，再叠加噪声

注意

GAUSSIAN 的噪声为标准差等于 bandwidth 的各向同性正态噪声；TOPHAT 为每维 [-bandwidth, bandwidth] 上的均匀噪声

参数

• nSamples (int) – 抽样个数，须为正

• seed (long) – 随机源种子，仅影响本次抽样的结果

返回

nSamples × 特征数 的矩阵

抛出

• IllegalStateException – 尚未拟合

• IllegalArgumentException – nSamples 小于等于 0

predict(Matrix features) → double[]¶

与 scoreSamples 等价，返回对数密度。

注意

沿用 scoreSamples 的实现，输出是打分而非分类标签

参数

• features (Matrix) – 查询点矩阵，列数须等于拟合时的特征数

返回

长度等于行数的对数密度数组

抛出

• IllegalStateException – 尚未拟合

• IllegalArgumentException – 列数不符或特征含非有限值

bandwidth() → double¶

返回带宽。

返回

构造时给定的 bandwidth，正有限值

kind() → ModelKind¶

返回模型类型标识。

返回

ModelKind.KERNEL_DENSITY

write(ModelWriter writer)¶

写入带宽、核类型与训练样本。

注意

核类型以 KernelType.ordinal() 落盘

注意

训练样本按行优先展平后整体写入，读回时按特征数还原形状

参数

• writer (ModelWriter) – 目标写入器，由调用方负责容器头与提交

抛出

• IllegalStateException – 尚未拟合

read(ModelReader reader) → KernelDensitystatic¶

读回带宽、核类型与训练样本。

参数

• reader (ModelReader) – 已完成容器头解析的读取器

返回

已可打分的模型实例

抛出

• ModelFormatException – 核类型序号越界、特征数或样本数不为正

final class KernelPCA implements Estimator, Transformer, Persistable¶

核主成分分析：在核空间中心化后做特征分解的降维估计器。

fit 先用核函数在训练集上求 n × n Gram 矩阵，按行均值、列均值与全均值做双重中心化 K - 1K/n - K1/n + 1K1/n²，再用循环 Jacobi 对称特征分解求特征值与特征向量；特征值截断为非负、按降序取前 components 个，特征向量按 1/sqrt(λ) 缩放后存为 alphas，λ 不超过 1e-12 的分量缩放因子取 0。

transform 对新样本计算它与全部训练样本的核值，用拟合阶段缓存的 kFitRows 与 kFitAll 做同样的中心化，再与 alphas 逐分量做内积得到投影坐标。predict 只是把投影矩阵按行优先展开成扁平数组。

示例

Matrix features = Matrix.fromRows(new double[][] {
    {1.0, 2.0}, {2.0, 1.0}, {3.0, 4.0}, {4.0, 3.0}, {5.0, 6.0}
});
KernelPCA kpca = KernelPCA.builder()
        .components(2)
        .rbf(0.5)
        .build()
        .fit(features);
Matrix projected = kpca.transform(features);
double[] eigenvalues = kpca.eigenvalues();

注意

核函数默认 rbf(gamma=1.0)，可用 kernel(Kernel)、rbf(gamma) 或 poly(degree, gamma, coef0) 替换

注意

components 不能超过样本数，否则 fit 抛 IllegalArgumentException

注意

Jacobi 迭代上限 60 轮、收敛阈值 1e-12，Builder 未暴露这两个参数的设值方法

注意

主方向符号按特征向量绝对值最大的分量为正固定，同一输入重复拟合可复现

注意

训练集与核行均值随模型一起序列化，预测时的内存占用与训练集规模成正比

参见：basalt.ml.Kernel, basalt.ml.PCA, basalt.ml.KernelPCA.Builder

方法

builder() → Builderstatic¶

创建构建器，默认 2 个分量、rbf(1.0) 核。

返回

新的 Builder，字段取默认值

fit(Matrix features) → KernelPCA¶

只用特征拟合，目标数组缺省为 null。

注意

等价于 fit(features, null)，目标参数被忽略

参数

• features (Matrix) – 训练样本矩阵，行是样本、列是特征；元素必须有限

返回

this，便于链式调用

抛出

• NullPointerException – features 为 null

• IllegalArgumentException – features 含非有限值，或 components 大于样本数

fit(Matrix features, double[] ignoredTargets) → KernelPCA¶

计算中心化核矩阵并提取前若干核主成分。

核矩阵在训练集自身上求值后做双重中心化；Jacobi 分解得到的特征值截断为非负、降序排序，前 components 个特征向量按 1/sqrt(λ) 缩放为 alphas。

注意

时间与内存都是 O(n²)，n 为训练样本数

注意

特征值不大于 1e-12 的分量缩放因子取 0，该分量投影恒为 0

参数

• features (Matrix) – 训练样本矩阵，行是样本、列是特征；元素必须有限

• ignoredTargets (double[]) – 占位参数；核 PCA 忽略监督目标，可为 null

返回

this，便于链式调用

抛出

• NullPointerException – features 为 null

• IllegalArgumentException – features 含非有限值，或 components 大于样本数

transform(Matrix features) → Matrix¶

把样本投影到核主成分坐标。

注意

每个样本都要与全部训练样本求核值，代价为 O(m·n) 次核求值

参数

• features (Matrix) – 样本矩阵，列数须等于训练特征数

返回

样本数 × components 的投影矩阵

抛出

• NullPointerException – features 为 null

• IllegalStateException – 尚未 fit

• IllegalArgumentException – 列数不匹配或含非有限值

predict(Matrix features) → double[]¶

返回投影结果的扁平数组。

等价于 transform(features).toArray()，按行优先展开，便于接入只需要 double[] 的下游流程。

参数

• features (Matrix) – 样本矩阵，列数须等于训练特征数

返回

长度为 样本数 × components 的数组

抛出

• NullPointerException – features 为 null

• IllegalStateException – 尚未 fit

• IllegalArgumentException – 列数不匹配或含非有限值

eigenvalues() → double[]¶

返回各核主成分的特征值。

注意

数值是中心化核矩阵的特征值，量纲与原始特征方差不同

返回

长度等于 components 的数组副本，非负且按降序排列

抛出

• IllegalStateException – 尚未 fit

kind() → ModelKind¶

返回模型类型标识。

返回

ModelKind.KERNEL_PCA

write(ModelWriter writer)¶

写入核函数、分量数、训练集与中心化统计量。

注意

写入顺序为核函数、分量数、特征数、训练样本数、全均值、训练数据、核行均值、特征值、alphas

注意

maxIterations 与 tolerance 不写入流，read 后回到 Builder 默认值

参数

• writer (ModelWriter) – 目标写入器，由调用方负责容器头与关闭

抛出

• IllegalStateException – 尚未 fit

read(ModelReader reader) → KernelPCAstatic¶

从序列化流重建 KernelPCA 模型。

注意

核函数按流中记录的类型与参数还原，不会退回默认的 rbf(1.0)

参数

• reader (ModelReader) – 已完成容器头解析的读取器

返回

可直接用于 transform 与 predict 的模型实例

抛出

• ModelFormatException – 分量数、特征数或训练样本数不为正

final class KernelRidge implements Estimator, Persistable¶

核岭回归：在核空间解 (K + alpha·I)α = y 的回归估计器。

fit 用核函数在训练集上求 n × n Gram 矩阵，对角线加 alpha 后用 Cholesky 分解解线性方程组，得到对偶系数 α；预测值是目标样本与全部训练样本核值的加权和，模型没有独立截距项。

Cholesky 分解对对角元取 max(sum, 1e-12) 作为抖动，半正定退化时不产生 NaN。alpha 越大解越平滑，对偶系数的绝对值整体变小。

示例

Matrix x = Matrix.fromRows(new double[][]{{0, 0}, {1, 0}, {0, 1}, {1, 1}});
double[] y = {0.0, 1.0, 1.0, 2.0};
KernelRidge model = KernelRidge.builder()
        .rbf(1.0)
        .alpha(0.1)
        .build()
        .fit(x, y);
double[] predictions = model.predict(x);
double[] dual = model.dualCoef();

注意

核函数默认 rbf(gamma=1.0)，可用 kernel(Kernel)、rbf(gamma) 或 poly(degree, gamma, coef0) 替换

注意

alpha 必须严格为正且有限，在 build() 时校验

注意

训练集与对偶系数一起序列化，预测代价与训练样本数成正比

注意

没有截距项：目标未中心化时预测会带系统性偏移

参见：basalt.ml.Kernel, basalt.ml.Ridge, basalt.ml.KernelRidge.Builder

方法

builder() → Builderstatic¶

创建构建器，默认 rbf(1.0) 核、alpha=1.0。

返回

新的 Builder，字段取默认值

fit(Matrix features, double[] targets) → KernelRidge¶

组装正则化核矩阵并用 Cholesky 求解对偶系数。

注意

Gram 矩阵为 n × n，时间 O(n²·d)、内存 O(n²)

注意

alpha 只加在 Gram 对角线上，等价于对偶问题的 L2 惩罚

参数

• features (Matrix) – 训练特征矩阵，n 行 d 列

• targets (double[]) – 训练目标数组，长度等于 n

返回

this，便于链式调用

抛出

• NullPointerException – features 或 targets 为 null

• IllegalArgumentException – 行数与目标长度不符，或数据含 NaN/无穷

predict(Matrix features) → double[]¶

用对偶系数与核值加权求和。

注意

每行需要 n 次核求值，n 为训练样本数

参数

• features (Matrix) – 待预测特征矩阵，列数须等于训练特征数

返回

每行一个连续预测值

抛出

• NullPointerException – features 为 null

• IllegalStateException – 尚未 fit

• IllegalArgumentException – 列数不匹配或含非有限值

dualCoef() → double[]¶

返回对偶系数副本。

注意

系数与训练样本一一对应，顺序即 fit 时特征矩阵的行序

返回

长度为训练样本数的对偶系数数组副本

抛出

• IllegalStateException – 尚未 fit

kernel() → Kernel¶

返回配置的核函数。

注意

核函数在构造时确定，fit 不会替换它

返回

拟合所用的 Kernel 实例；未 fit 时也可读取

kind() → ModelKind¶

返回模型类型标识。

返回

ModelKind.KERNEL_RIDGE

write(ModelWriter writer)¶

写入核函数、alpha、训练集与对偶系数。

注意

写入顺序为核函数、alpha、特征数、训练样本数、训练数据、对偶系数

参数

• writer (ModelWriter) – 目标写入器，由调用方负责容器头与关闭

抛出

• IllegalStateException – 尚未 fit

read(ModelReader reader) → KernelRidgestatic¶

从序列化流重建 KernelRidge 模型。

注意

alpha 从流中还原并重新经过 Builder 校验

参数

• reader (ModelReader) – 已完成容器头解析的读取器

返回

可直接用于 predict 的模型实例

抛出

• ModelFormatException – 特征数或训练样本数不为正

final class LabelEncoder implements Transformer¶

把类别标签双向映射为 0..k-1 整数码的编码器。

fit(double[]) 用 TreeSet 收集升序唯一值作为类别表；fit(String[]) 按字符串自然序收集，同时建立标签到下标的哈希表，并把 classes 置为 0..k-1，使数值接口与字符串接口共享同一套下标语义。

transform 对未见过的标签不做兜底：数值路径用二分查找，字符串路径查表，命中失败一律抛 IllegalArgumentException；inverseTransform 把整数码还原为类别值，浮点输入要求与最近整数相差不超过 1e-9。

示例

LabelEncoder encoder = new LabelEncoder();
double[] codes = encoder.fitTransform(new double[]{3.0, 1.0, 3.0, 2.0});
double[] original = encoder.inverseTransform(codes);
double[] classes = encoder.classes();

LabelEncoder names = new LabelEncoder();
int[] ids = names.fitTransform(new String[]{"cat", "dog", "cat"});
String[] restored = names.inverseTransformStrings(ids);

注意

fit(double[]) 与 fit(String[]) 互斥，后一次 fit 会清空另一种模式的类别表

注意

在字符串上拟合后 classes() 返回 0..k-1 的整数码，反查字符串需用 stringClasses() 或 inverseTransformStrings

注意

空输入与 null 元素在 fit 阶段即被拒绝，未知标签只在 transform 阶段报错

注意

write 把字符串按 UTF-8 逐条写入，长度前缀为字节数而非字符数

参见：basalt.ml.OneHotEncoder, basalt.ml.Transformer

构造器

LabelEncoder()¶

创建尚未拟合的空编码器。

注意

fit 之前调用任何 transform 或 inverseTransform 都抛 IllegalStateException

方法

fit(double[] targets) → LabelEncoder¶

收集升序唯一值作为类别表。

注意

类别表按数值升序排列，编码值即该顺序中的下标

注意

会清空此前 fit(String[]) 建立的字符串表

参数

• targets (double[]) – 标签数组，不能为空，元素必须有限

返回

this，便于链式调用

抛出

• NullPointerException – targets 为 null

• IllegalArgumentException – targets 为空或含 NaN/无穷

fit(String[] labels) → LabelEncoder¶

按字符串自然序建立类别表。

注意

排序使用 String 的自然序，区分大小写，不做归一化

注意

同时把 classes 置为 0..k-1，因此数值接口在字符串拟合后仍可用

参数

• labels (String[]) – 标签数组，不能为空，元素不能为 null

返回

this，便于链式调用

抛出

• NullPointerException – labels 为 null，或其中某个元素为 null

• IllegalArgumentException – labels 为空

transformToInt(double[] targets) → int[]¶

把标签转成整数下标。

注意

内部用 Arrays.binarySearch，依赖类别表升序

参数

• targets (double[]) – 待编码标签

返回

与输入等长的整数码数组，取值 0..k-1

抛出

• NullPointerException – targets 为 null

• IllegalStateException – 尚未 fit

• IllegalArgumentException – 出现训练时未见过的标签

transform(double[] targets) → double[]¶

把标签转成 double 形式的整数码。

注意

等价于 transformToInt 的逐元素 double 化

参数

• targets (double[]) – 待编码标签

返回

与输入等长的编码数组，元素为整数值的 double

抛出

• NullPointerException – targets 为 null

• IllegalStateException – 尚未 fit

• IllegalArgumentException – 出现训练时未见过的标签

fitTransform(double[] targets) → double[]¶

先 fit 再 transform。

注意

同一数组既作训练又作输入，因此不会出现未知标签

参数

• targets (double[]) – 既用于拟合又用于编码的标签数组

返回

与输入等长的编码数组

抛出

• NullPointerException – targets 为 null

• IllegalArgumentException – targets 为空或含 NaN/无穷

inverseTransform(double[] encoded) → double[]¶

把浮点编码还原为类别值。

注意

先用 Math.round 取整再校验，容差 1e-9

参数

• encoded (double[]) – 编码数组，元素须接近 [0, k-1] 内的整数

返回

与输入等长的类别值数组

抛出

• NullPointerException – encoded 为 null

• IllegalStateException – 尚未 fit

• IllegalArgumentException – 下标越界，或元素与最近整数相差超过 1e-9

inverseTransform(int[] encoded) → double[]¶

把整数编码还原为类别值。

参数

• encoded (int[]) – 整数码数组，元素须在 [0, k-1] 内

返回

与输入等长的类别值数组

抛出

• NullPointerException – encoded 为 null

• IllegalStateException – 尚未 fit

• IllegalArgumentException – 下标越界

transform(String[] labels) → int[]¶

把字符串标签转成整数下标。

注意

只查表，不做大小写或空白归一化

参数

• labels (String[]) – 待编码字符串标签

返回

与输入等长的整数码数组

抛出

• NullPointerException – labels 为 null

• IllegalStateException – 未在字符串标签上 fit

• IllegalArgumentException – 出现未见过的字符串标签

fitTransform(String[] labels) → int[]¶

先 fit 再编码字符串标签。

参数

• labels (String[]) – 既用于拟合又用于编码的字符串标签

返回

与输入等长的整数码数组

抛出

• NullPointerException – labels 为 null，或其中某个元素为 null

• IllegalArgumentException – labels 为空

inverseTransformStrings(int[] encoded) → String[]¶

把整数编码还原为字符串标签。

参数

• encoded (int[]) – 整数码数组，元素须在 [0, k-1] 内

返回

与输入等长的字符串数组

抛出

• NullPointerException – encoded 为 null

• IllegalStateException – 未在字符串标签上 fit

• IllegalArgumentException – 下标越界

fit(Matrix features, double[] ignoredTargets) → LabelEncoder¶

以单列矩阵为输入的适配方法。

注意

把矩阵数据按行展开后交给 fit(double[])，因此只接受单列输入

参数

• features (Matrix) – 单列矩阵，每行一个标签

• ignoredTargets (double[]) – 占位参数，被忽略，可为 null

返回

this，便于链式调用

抛出

• NullPointerException – features 为 null

• IllegalArgumentException – features 的列数不等于 1，或数据含非有限值

transform(Matrix features) → Matrix¶

编码单列矩阵。

注意

内部走 transform(double[])，编码值以 double 写出

参数

• features (Matrix) – 单列矩阵，每行一个标签

返回

行数不变、单列的编码矩阵

抛出

• NullPointerException – features 为 null

• IllegalStateException – 尚未 fit

• IllegalArgumentException – 列数不等于 1，或出现未见过的标签

inverseTransform(Matrix transformed) → Matrix¶

解码单列矩阵。

注意

内部走 inverseTransform(double[])，同样要求编码接近整数

参数

• transformed (Matrix) – 单列的编码矩阵

返回

行数不变、单列的类别值矩阵

抛出

• NullPointerException – transformed 为 null

• IllegalStateException – 尚未 fit

• IllegalArgumentException – 列数不等于 1，或编码值越界

classes() → double[]¶

返回数值类别表副本。

返回

升序类别值副本；在字符串上拟合时为 0..k-1

抛出

• IllegalStateException – 尚未 fit

stringClasses() → String[]¶

返回字符串类别表副本。

注意

不抛异常，未拟合或数值模式下一律返回 null

返回

按自然序排列的字符串类别副本；未在字符串上 fit 时为 null

kind() → ModelKind¶

返回模型类型标识。

返回

ModelKind.LABEL_ENCODER

write(ModelWriter writer)¶

写入数值类别表与可选的字符串表。

注意

先写类别数与类别值，再写字符串条数（0 表示无字符串表）

注意

每条字符串先写 UTF-8 字节数再写字节，读取端按同一格式消费

参数

• writer (ModelWriter) – 目标写入器，由调用方负责容器头与关闭

抛出

• IllegalStateException – 尚未 fit

read(ModelReader reader) → LabelEncoderstatic¶

从序列化流重建 LabelEncoder。

注意

字符串条数大于 0 时同时重建标签到下标的哈希表

参数

• reader (ModelReader) – 已完成容器头解析的读取器

返回

可直接用于 transform 与 inverseTransform 的编码器

抛出

• ModelFormatException – 类别数不为正

final class Lasso implements Estimator, Persistable¶

坐标下降求解的 L1 正则最小二乘。

fit 先令截距等于目标均值、残差为零均值化后的目标，再循环坐标下降：对每个特征计算 rho = Σ x_i·(r_i + w_j·x_i)，用软阈值把 rho 向零收缩 alpha，再除以该特征的平方和得到新系数，并把变化量即时回写到残差。

每轮扫描结束后把残差均值并入截距，使残差保持零均值。alpha 作用在按行求和的尺度上（rho 与 norms 都未除以样本数），与按均方误差定义的 alpha 相差 n 倍，取值需相应放大。

示例

Matrix x = Matrix.fromRows(new double[][]{{1, 0}, {0, 1}, {1, 1}, {2, 2}});
double[] y = {1.0, 2.0, 3.0, 5.0};
Lasso lasso = Lasso.builder()
        .alpha(0.1)
        .maxIterations(500)
        .build()
        .fit(x, y);
double[] coefficients = lasso.weights();
double bias = lasso.intercept();

注意

alpha 允许为 0，此时退化为无正则的坐标下降最小二乘

注意

收敛判据是本轮坐标更新的最大绝对变化小于 tolerance；达到 maxIterations 时静默停止，不抛异常

注意

各特征的平方和只在 fit 开始时计算一次

注意

特征未中心化或标准化，列尺度直接决定收缩强度

参见：basalt.ml.Ridge, basalt.ml.LinearRegression, basalt.ml.Lasso.Builder

方法

builder() → Builderstatic¶

创建构建器，默认 alpha=0.1、1000 轮、1e-8。

返回

新的 Builder，字段取默认值

fit(Matrix features, double[] targets) → Lasso¶

用循环坐标下降拟合 L1 正则模型。

注意

系数初值全为零，相同输入的迭代轨迹完全确定

注意

平方和为零的常数列会被跳过，系数保持 0

参数

• features (Matrix) – 训练特征矩阵，n 行 d 列

• targets (double[]) – 训练目标数组，长度等于 n

返回

this

抛出

• NullPointerException – features 或 targets 为 null

• IllegalArgumentException – 行数与目标长度不符，或数据含 NaN/无穷

predict(Matrix features) → double[]¶

计算截距与系数的线性组合。

参数

• features (Matrix) – 待预测特征矩阵，列数须等于训练特征数

返回

每行一个连续预测值

抛出

• IllegalStateException – 尚未 fit

• IllegalArgumentException – 列数不匹配或含非有限值

weights() → double[]¶

返回回归系数副本。

返回

长度为特征数的系数数组副本，稀疏结果中不重要的特征为 0.0

抛出

• NullPointerException – 尚未 fit，内部数组为 null

intercept() → double¶

返回截距项。

注意

截距不受 L1 惩罚，每轮扫描后按残差均值修正

返回

标量截距；未 fit 时为 0.0

kind() → ModelKind¶

返回模型类型标识。

返回

ModelKind.LASSO

write(ModelWriter writer)¶

写入 alpha、迭代参数、截距与系数。

注意

写入顺序为 alpha、maxIterations、tolerance、特征数、截距、系数

参数

• writer (ModelWriter) – 目标写入器，由调用方负责容器头与关闭

抛出

• IllegalStateException – 尚未 fit

read(ModelReader reader) → Lassostatic¶

从序列化流重建 Lasso 模型。

注意

alpha、maxIterations、tolerance 从流中还原并重新经过 Builder 校验

参数

• reader (ModelReader) – 已完成容器头解析的读取器

返回

可直接用于 predict 的模型实例

抛出

• ModelFormatException – 特征数不为正

final class LimeExplainer¶

用局部加权线性代理模型解释单个预测的 LIME 解释器。

构造时统计训练数据每列的标准差（分母取样本数，标准差不超过 1e-12 的列按 1.0 处理），作为扰动的尺度。explainInstance 以目标样本为中心按 0.5 倍标准差做高斯采样：第 0 条样本固定为目标本身、权重为 1，其余样本按 w = exp(-d²/kernelWidth²) 加权，其中 d² 是采样偏移按列标准差归一化后再乘 0.5 的平方和。

代理模型是对增广设计矩阵 [1, x] 的加权岭回归，用 Cholesky 求解，特征对角加 1e-4、截距加 1e-9 的抖动。拟合优度用加权 R² 表示，即 1 减去加权残差平方和与加权总平方和之比；总平方和不超过 1e-15 时直接记为 1.0，结果下限截断为 0。

示例

Matrix train = Matrix.fromRows(new double[][]{{0, 0}, {1, 0}, {0, 1}, {1, 1}});
double[] y = {0, 0, 1, 1};
LogisticRegression model = LogisticRegression.builder().build().fit(train, y);
LimeExplainer lime = new LimeExplainer(model, train, 200, 0.75, 7L);
LimeExplainer.LocalExplanation explanation = lime.explainInstance(new double[]{1.0, 0.2});
double[] weights = explanation.featureWeights();
double fidelity = explanation.r2Fidelity();
int[] ranked = explanation.topFeatures();

注意

kernelWidth 不大于 0 时自动取 0.75·sqrt(特征数)，单参数构造器即走该路径

注意

numSamples 必须不小于 20，默认 500

注意

每次调用都用 seed 重新初始化随机源，同一实例的多次解释结果完全一致

注意

topFeatures 按 |系数 × 该列标准差| 降序给出全部特征的下标，不做截断

注意

模型统一经 ShapExplainer 的求值入口调用：逻辑回归与随机森林取正类概率，直方图梯度提升取原始分数

参见：basalt.ml.ShapExplainer, basalt.ml.Estimator, basalt.ml.Pipeline

构造器

LimeExplainer(Estimator model, Matrix trainingData)¶

用默认采样数 500、自动核宽、种子 42 构造。

注意

等价于 new LimeExplainer(model, trainingData, 500, 0.0, 42L)

参数

• model (Estimator) – 被解释的估计器或 Pipeline，不能为 null

• trainingData (Matrix) – 训练数据，用于估计每列标准差

抛出

• NullPointerException – model 或 trainingData 为 null

• IllegalArgumentException – trainingData 含 NaN 或无穷

LimeExplainer(Estimator model, Matrix trainingData, int numSamples, double kernelWidth, long seed)¶

指定采样数、核宽与随机种子构造。

注意

标准差按总体口径计算，分母为样本数而非样本数减一

注意

标准差不超过 1e-12 的列按 1.0 处理，避免扰动退化为常数

参数

• model (Estimator) – 被解释的估计器或 Pipeline，不能为 null

• trainingData (Matrix) – 训练数据，用于估计每列标准差

• numSamples (int) – 局部采样数，必须不小于 20

• kernelWidth (double) – 距离核的宽度；不大于 0 时取 0.75·sqrt(特征数)

• seed (long) – 随机种子，决定扰动样本的生成

抛出

• NullPointerException – model 或 trainingData 为 null

• IllegalArgumentException – trainingData 含 NaN 或无穷，或 numSamples 小于 20

方法

explainInstance(double[] instance) → LocalExplanation¶

为目标样本生成局部解释。

注意

localPrediction 由代理模型在目标样本上求值，与 modelPrediction 的差异反映代理拟合质量

注意

全部扰动样本的预测通过一次批量调用完成，不逐行调用

参数

• instance (double[]) – 目标样本，长度须等于训练特征数

返回

含截距、各特征权重、局部与真实预测、加权 R² 与特征排序的 LocalExplanation

抛出

• NullPointerException – instance 为 null

• IllegalArgumentException – instance 长度与训练特征数不符

final class LinearRegression implements Estimator, Persistable¶

全批量梯度下降的普通最小二乘。

fit 从全零权重与零截距出发，每个 epoch 用全部样本累加 MSE 梯度（缩放因子 2/n），加上 2·l2·w 后按 learningRate 做一次整批更新；fitIntercept 为 true 时截距同步更新，且不受 l2 惩罚。

lossHistory 记录每个 epoch 更新前算出的均方误差，可用于判断是否收敛。算法对特征尺度敏感：未标准化时应降低 learningRate，否则梯度下降可能震荡或发散。

示例

Matrix x = Matrix.fromRows(new double[][]{{0, 1}, {1, 1}, {2, 1}, {3, 1}});
double[] y = {1.0, 3.0, 5.0, 7.0};
LinearRegression model = LinearRegression.builder()
        .learningRate(0.05)
        .epochs(2000)
        .fitIntercept(true)
        .build()
        .fit(x, y);
double[] predictions = model.predict(x);
double one = model.predictOne(new double[]{4.0, 1.0}, 0);

注意

权重初值恒为零，同一输入的拟合结果完全确定

注意

l2 以 2·l2·w 加入梯度，只作用于权重

注意

不对特征做中心化或标准化，也不做特征筛选

参见：basalt.ml.Ridge, basalt.ml.LogisticRegression, basalt.ml.LinearRegression.Builder

方法

builder() → Builderstatic¶

创建构建器，默认 lr=0.05、2000 轮、无正则。

返回

新的 Builder，字段取默认值

fit(Matrix features, double[] targets) → LinearRegression¶

用全批量梯度下降最小化均方误差。

注意

epochs 轮内不做提前停止，lossHistory 长度恒为 epochs

参数

• features (Matrix) – 训练特征矩阵，n 行 d 列

• targets (double[]) – 训练目标数组，长度等于 n

返回

this

抛出

• NullPointerException – features 或 targets 为 null

• IllegalArgumentException – 行数与目标长度不符，或数据含 NaN/无穷

predict(Matrix features) → double[]¶

批量计算线性预测值。

参数

• features (Matrix) – 待预测特征矩阵，列数须等于训练特征数

返回

长度等于行数的连续预测值

抛出

• IllegalStateException – 尚未 fit

• IllegalArgumentException – 列数不匹配或含非有限值

predictOne(double[] features, int offset) → double¶

对扁平数组中的单个样本预测。

适合在已经展开的批量缓冲区上按偏移逐行调用，避免为单行构造 Matrix。

注意

只检查长度，不检查取值是否有限

参数

• features (double[]) – 扁平特征数组

• offset (int) – 该样本第一个特征在数组中的下标

返回

单样本的预测值

抛出

• IllegalStateException – 尚未 fit

• IndexOutOfBoundsException – offset 为负，或 offset 加特征数超过数组长度

weights() → double[]¶

返回权重副本。

注意

返回副本，修改它不影响模型

返回

长度为特征数的权重副本；未 fit 时返回空数组

intercept() → double¶

返回截距项。

注意

fitIntercept 为 false 时该值恒为 0.0

返回

标量截距；未 fit 时为 0.0

lossHistory() → double[]¶

返回每个 epoch 的均方误差。

注意

返回副本；未 fit 时为空数组

注意

曲线单调下降说明学习率合适，震荡说明步长偏大

返回

长度为 epochs 的数组，元素是当轮更新前的 MSE

kind() → ModelKind¶

返回模型类型标识。

返回

ModelKind.LINEAR_REGRESSION

write(ModelWriter writer)¶

写入超参数、截距与权重。

注意

写入顺序为 learningRate、epochs、l2、fitIntercept 字节、特征数、截距、权重

注意

lossHistory 不写入流，read 后为空数组

参数

• writer (ModelWriter) – 目标写入器，由调用方负责容器头与关闭

抛出

• IllegalStateException – 尚未 fit

read(ModelReader reader) → LinearRegressionstatic¶

从序列化流重建 LinearRegression 模型。

注意

超参数从流中还原并重新经过 Builder 校验

注意

lossHistory 为空数组，训练曲线不可恢复

参数

• reader (ModelReader) – 已完成容器头解析的读取器

返回

已标记为拟合状态、可直接 predict 的实例

抛出

• ModelFormatException – 特征数不为正