inkhinge 1.2.3

The next-generation deep learning toolkit designed specifically for spectral analysis

inkhinge

inkhinge是一个专为光谱分析与生物信号数据处理设计的工具集，涵盖光谱数据处理、ABF生物信号文件转换、曲线拟合、图像分析、峰检测与机器学习分类六大核心能力。支持Omnic SPA光谱格式、ABF（生物信号）格式、多种图像格式的处理，提供从数据预处理（格式转换、背景校正）到高级建模（多维度拟合、峰检测、HAP-MoE深度学习分类）的完整流程支持。通过pip install inkhinge安装后，可便捷处理批量文件转换、高精度拟合、图像灰度分析、晶体结构插入等任务，适配科研场景中多类型数据的统一处理需求。

安装

pip install inkhinge

函数文档与使用方法

---

abf_to_csv

读取ABF文件（生物信号常用格式，如电生理、传感器数据）并转换为CSV格式，支持单文件转换与批量处理，自动生成时间轴并适配不同版本ABF文件。

参数:

• input_path (str): 输入路径（单个ABF文件或包含ABF文件的目录）。
• output_path (str, 可选): 输出路径（单文件转换时为CSV文件路径，批量转换时为目录路径），默认与输入同目录生成同名CSV。
• recursive (bool, 可选): 处理目录时是否递归子目录，默认False。

返回:

• 元组 (success_count, failure_count)：成功转换的文件数与失败的文件数。

核心功能:

• 自动判断输入类型（文件/目录），切换单文件/批量处理模式，无需手动调用不同函数。
• 内置process_single_file辅助函数，实现单文件全流程处理：包含输入文件存在性验证、ABF文件加载（兼容多版本pyabf）、加载后自动打印文件关键信息（版本、通道数、采样率、总数据点数）。
• 独立计算时间轴（基于采样率与总数据点，不依赖pyabf版本差异），支持最高100000 Hz采样率，生成后打印时间轴范围与数据点数，便于调试。
• 智能路径校正：输入文件不存在时会提示错误；输出路径若为目录，自动生成与ABF同名的CSV；输出目录不存在时自动创建，避免运行报错。
• 通道数据精细化处理：逐通道打印处理进度与数据长度，若通道数据与时间轴长度不匹配，自动截断过长数据或用NaN补全过短数据；兼容多版本pyabf的通道信息获取方式，保留通道名称与单位（如电压、电流）并作为CSV列名。
• 批量处理增强：递归模式下遍历所有子目录收集ABF文件，处理前统计文件总数，处理后输出“总文件数/成功数/失败数”的详细统计，单个文件转换失败不影响整体批量流程。

使用方法:

from inkhinge.core import abf_to_csv

# 示例1：单文件转换（ABF转CSV，指定输出路径）
success, failed = abf_to_csv(
    input_path="data/signal.abf",
    output_path="results/signal_output.csv"
)
print(f"单文件转换：成功{success}个，失败{failed}个")

# 示例2：批量转换目录中所有ABF（不递归子目录，输出到指定目录）
success, failed = abf_to_csv(
    input_path="data/abf_files/",
    output_path="results/abf_csvs/",
    recursive=False
)
print(f"批量转换：成功{success}个，失败{failed}个")

# 示例3：递归批量转换（处理子目录中所有ABF，默认输出到原目录）
success, failed = abf_to_csv(
    input_path="data/parent_dir/",
    recursive=True
)
print(f"递归批量转换：成功{success}个，失败{failed}个")

---

read_to_csv

读取Omnic SPA格式光谱文件并转换为CSV格式，支持背景校正、批量处理及多文件合并，自动计算Kubelka-Munk（KM）值。

参数:

• input_path (str): 输入路径（单个SPA文件或包含SPA文件的目录）。
• output_path (str, 可选): 输出路径（单个CSV文件或目录），默认与输入同目录并添加_converted后缀。
• background_path (str, 可选): 背景文件（如BG.spa）路径，用于背景校正（透射率/反射率数据适用）。
• overwrite (bool, 可选): 是否覆盖已有文件，默认False。
• recursive (bool, 可选): 处理目录时是否递归子目录，默认False。
• precision (int, 可选): 输出数据的小数位数（默认20位，确保定点表示，避免科学计数法）。
• merge_output (str, 可选): 合并后CSV的路径，默认None（不合并）。

返回:

• 单个文件转换：返回输出CSV路径。
• 批量转换：返回成功转换的文件数（未合并时）或文件路径列表（合并时）。

核心功能:

• 自动识别光谱类型（吸光度、透射率等）并标注单位。
• 对反射率数据自动计算Kubelka-Munk值。
• 支持背景校正（透射率数据减法校正，反射率数据除法校正）。
• 批量处理时按文件名排序，合并后列名自动编号（如Kubelka-Munk_0）。

使用方法:

from inkhinge.core import read_to_csv

# 单个SPA文件转换（带背景校正）
output_path = read_to_csv(
    input_path="sample.spa",
    output_path="output/sample.csv",
    background_path="background.BG.spa",  # 应用背景校正，无需时删除此行
    precision=15
)
print(f"转换完成，输出路径：{output_path}")

# 批量转换目录中所有SPA文件（含子目录，不合并）
success_count = read_to_csv(
    input_path="spectral_data/",
    output_path="converted_csv/",
    recursive=True,
    overwrite=True,
    precision=10
)
print(f"批量转换完成，成功转换{success_count}个文件")

# 转换并合并所有SPA文件为单个CSV
read_to_csv(
    input_path="spectral_data/",
    output_path="converted_csv/",
    merge_output="merged_spectra.csv"
)
print("转换与合并完成，结果已保存至merged_spectra.csv")

---

FindPeak_Single

自动检测单变量信号中的显著谷值特征（适用于电流、光谱等信号），计算特征参数（谷深、面积、半高宽、信噪比、对称性等）并支持可视化。

参数:

• csv_file_path (str): 输入CSV文件路径（包含时间列和信号列）。
• start_row (int, 可选): 起始行索引（从0开始），默认0。
• end_row (int, 可选): 结束行索引，默认None（读至文件末尾）。
• max_peak_count (int, 可选): 最多保留的事件数，默认500。
• x_col (str, 可选): 时间列名，默认自动识别含“time”的列。
• y_col (str, 可选): 信号列名，默认自动选择除时间外的第一列。
• plot_result (bool, 可选): 是否绘制全局检测结果图，默认True。
• output_image (str, 可选): 输出图像路径，默认"detected_valley_features.png"。
• output_csv (str, 可选): 输出事件特征CSV路径，默认"detected_valley_features.csv"。
• sampling_rate (float, 可选): 采样率（Hz），用于时间单位换算，默认1e6。
• enable_filtering (bool, 可选): 是否启用中值与Savgol滤波，默认True。
• savgol_polyorder (int, 可选): Savgol滤波器多项式阶数，默认3。
• enable_outlier_removal (bool, 可选): 是否移除离群值（基于sigma），默认True。
• create_connected_peaks (bool, 可选): 是否生成连接峰图像，默认True。

返回:

• 字典，包含：
  • features: 事件特征列表，每个特征包含谷深、面积、半高宽、信噪比、对称性、上升/下降时间等。
  • quality_metrics: 质量指标（平均信噪比、深度变异系数等）。
  • voltage: 从文件名解析的电压值（若有）。
  • connected_image_path: 连接峰图像路径（若生成）。

核心功能:

• 稳健基线估计：使用众数法（Mode）计算基线，并剔除异常值。
• 严格的筛选条件：持续时间3200点、对称性0.10.55、谷深 > 1.5×基线众数、向上峰无效排除（高于基线且超过1.2×|基线|）。
• 多维度特征计算：谷深、曲线面积、半高宽、信噪比、上升/下降斜率、对称性等。
• 可视化输出：全局检测图、连接峰事件图、原始/滤波对比细节图（Top6事件）。
• 数据合理性检查：避免异常数据导致图像生成失败。

使用方法:

from inkhinge.core import FindPeak_Single

result = FindPeak_Single(
    csv_file_path="data/signal.csv",
    start_row=0,
    max_peak_count=300,
    output_image="detection_result.png",
    output_csv="detected_peaks.csv"
)
print(f"检测到 {len(result['features'])} 个事件")
print(f"平均信噪比: {result['quality_metrics']['avg_snr']:.2f}")

---

PeakCsv_to_Json_Down

将峰检测生成的CSV文件（单个或多个）转换为JSON格式，用于HAP-MoE模型训练，并可选择将数据集分割为训练集和验证集。自动识别输入类型（文件/文件夹）。

参数:

• input_path (str): 输入路径（单个CSV文件或包含CSV文件的文件夹）。
• output_folder (str, 可选): 输出文件夹路径，默认使用输入文件所在目录或输入文件夹。
• output_filename (str, 可选): 输出的完整数据集JSON文件名，默认"processed_valleys_data.json"。
• use_filename_as_class (bool, 可选): 是否从文件名中提取类别标签，默认True。
• split_train_val (bool, 可选): 是否将数据集分割为训练集和验证集，默认True。
• train_ratio (float, 可选): 训练集比例（0-1），默认0.8。
• seed (int, 可选): 随机种子，确保结果可复现，默认42。
• stratify_by_class (bool, 可选): 分割时是否按类别分层抽样，保持类别分布，默认True。

返回:

• 字典，包含：
  • success (bool): 处理是否成功。
  • total_records (int): 生成的记录总数。
  • output_file (str): 完整数据集的JSON文件路径。
  • train_file (str, 可选): 训练集JSON文件路径（如果分割）。
  • val_file (str, 可选): 验证集JSON文件路径（如果分割）。
  • data (list): 完整的JSON数据列表。

核心功能:

• 自动识别输入类型：单个文件或文件夹，并相应处理。
• 鲁棒的文件解析：尝试多种编码（utf-8-sig, utf-8, gbk, latin-1）以处理不同来源的CSV文件。
• 特征清理与标准化：移除不可见字符，安全转换数值，标准化斜率（从/s到/μs）和时间（从秒到微秒）。
• 文件名类别合并：支持将同一物质的不同测量文件（如带有_0, _1后缀或时间片段）合并为同一类别。
• 构建与HAP-MoE兼容的JSON格式：包含instruction, input（特征字符串）, output（类别标签）。
• 可选分层分割：按类别比例将数据分割为训练集和验证集，并分别保存。
• 输出详细统计信息：包括各类别样本数、分割后分布等。

使用方法:

from inkhinge.core import PeakCsv_to_Json_Down

# 批量处理文件夹中的所有CSV文件，并自动分割训练/验证集
result = PeakCsv_to_Json_Down(
    input_path="data/mergedData/kongbai/kongbai_CSV",
    output_folder="data/mergedData/kongbai/kongbai_CSV",
    output_filename="processed_valleys_data.json",
    use_filename_as_class=True,
    split_train_val=True,
    train_ratio=0.8,
    seed=42,
    stratify_by_class=True
)
if result["success"]:
    print(f"完整数据集: {result['output_file']}")
    print(f"训练集: {result['train_file']}")
    print(f"验证集: {result['val_file']}")

# 处理单个CSV文件，并保存完整数据集（不分割）
result_single = PeakCsv_to_Json_Down(
    input_path="data/mergedData/kongbai/kongbai_CSV/kongbai 6.csv",
    output_folder="data/mergedData/kongbai/kongbai_CSV",
    output_filename="single_file_data.json",
    split_train_val=False
)

---

curvefit_km_t

对指定行的KM值随时间变化进行指数曲线拟合（模型：y = a·x^b·exp(-c·x)），输出拟合参数、R²值及可视化结果。

参数:

• file_path (str): 输入CSV文件路径（每行对应一个波数，每列对应一个时间点）。
• target_row (int, 可选): 目标行号（从1开始），默认1。
• txt_output_path (str, 可选): 拟合结果文本路径，默认curvefit_km_t.txt。
• png_output_path (str, 可选): 拟合图像路径，默认curvefit_km_t.png。
• show_plot (bool, 可选): 是否显示图像，默认True。

返回:

• 字典，包含拟合参数（a, b, c）、R²值、原始数据及拟合表达式等。

使用方法:

from inkhinge.core import curvefit_km_t

# 对CSV中第3行的KM值进行时间序列拟合
result = curvefit_km_t(
    file_path="merged_spectra.csv",
    target_row=3,
    txt_output_path="time_fit_result.txt",
    png_output_path="time_fit_plot.png"
)
print(f"拟合函数表达式：{result['fit_expression']}")
print(f"拟合优度R²：{result['r_squared']:.4f}")

---

curvefit_km_wavenumber

对指定时间点的KM值与波数进行多峰高斯-洛伦兹混合函数拟合，适用于分析特定时间下的光谱峰特征（如峰位、半宽、振幅）。

参数:

• file_path (str): 输入CSV文件路径（每行对应一个波数，每列对应一个时间点）。
• time_column_index (int, 可选): 目标时间列索引（从0开始），默认1。
• txt_output_path (str, 可选): 拟合结果文本路径，默认curvefit_km_wavenumber.txt。
• png_output_path (str, 可选): 拟合图像路径，默认curvefit_km_wavenumber.png。

返回:

• 字典，包含拟合参数、R²值、拟合表达式及原始数据。

拟合模型:

单个峰的混合函数表达式：
η·(a/(1+((w-x₀)/σ)²)) + (1-η)·(a·exp(-(w-x₀)²/(2σ²)))

• η：混合系数（0≤η≤1，η=1时为纯洛伦兹峰，η=0时为纯高斯峰）
• a：峰振幅（信号强度）
• x₀：峰位（对应波数）
• σ：峰半宽（反映峰的尖锐程度）

使用方法:

from inkhinge.core import curvefit_km_wavenumber

# 对第2列（时间点）的KM值与波数进行拟合
result = curvefit_km_wavenumber(
    file_path="merged_spectra.csv",
    time_column_index=2,
    txt_output_path="wavenumber_fit_result.txt",
    png_output_path="wavenumber_fit_plot.png"
)
print(f"拟合优度R²：{result['r2']:.4f}")

---

curvefit_km_t_wavenumber

对时间-波数-KM值三维数据进行两步拟合，构建三维模型KM(t,w) = a(w)·t^k·exp(-c(w)·t)（k为全局常数），适用于动态光谱的时空特征分析。

参数:

• file_path (str): 输入CSV文件路径。
• wavenumber_min (float, 可选): 波数下限，默认1300 cm⁻¹。
• wavenumber_max (float, 可选): 波数上限，默认1320 cm⁻¹。
• output_txt_path (str, 可选): 结果文本路径，默认curvefit.txt。
• output_img_path (str, 可选): 三维拟合图像路径，默认curvefit.png。
• peak_num (int, 可选): 拟合a(w)和c(w)时的峰数量，默认3。

返回:

• 字典，包含常数k、a(w)和c(w)的拟合参数、整体R²值及数据范围等。

核心功能:

• 自动修正波数非单调问题（排序确保波数从低到高，如1300→1320 cm⁻¹）。
• 两步拟合逻辑：先通过所有波数的时间序列拟合求k（取b值均值），再固定k拟合a(w)和c(w)。
• 输出原始数据与拟合曲面的三维对比图，标注整体及分项R²值，直观展示拟合效果。

使用方法:

from inkhinge.core import curvefit_km_t_wavenumber

# 对1300-1320 cm⁻¹范围内的三维数据进行拟合
result = curvefit_km_t_wavenumber(
    file_path="merged_spectra.csv",
    wavenumber_min=1300,
    wavenumber_max=1320,
    output_txt_path="3d_fit_result.txt",
    output_img_path="3d_fit_plot.png",
    peak_num=3
)
print(f"整体拟合优度R²：{result['r2_overall']:.4f}")
print(f"全局常数k值：{result['k']:.6f}")

---

HAP_MoE

训练HAP-MoE（Hybrid Attention Pooling - Mixture of Experts）深度学习模型，用于谷值特征的多分类任务。该模型集成了注意力机制、多专家网络、自适应损失函数，并采用5折交叉验证集成。

参数:

• json_file_path (str, 可选): JSON数据文件路径，默认"processed_valleys_data.json"。
• test_size (float, 可选): 测试集比例，默认0.15。
• n_splits (int, 可选): 交叉验证折数，默认5。
• seed (int, 可选): 随机种子，默认42。
• max_lr (float, 可选): 最大学习率，默认0.002。
• output_dir (str, 可选): 输出目录（保存模型、图表、部署包），默认"hap_moe_results"。

返回:

• 字典，包含：
  • test_accuracy: 测试集准确率。
  • class_names: 原始类别名称列表。
  • simplified_names: 简化类别名称列表。
  • deployment_dir: 生成的部署包路径。

核心功能:

• 自动解析JSON数据（输入特征字符串、输出标签）。
• 特征工程：生成增强特征（如斜率比、面积深度比等），标准化，并使用随机森林筛选重要特征。
• 模型架构：4个专家网络、多头注意力、门控网络、残差连接、渐进式权重。
• 自适应损失：HAP_AdaptiveLoss（结合类别权重、focal loss、困难样本加权）。
• 5折交叉验证训练，每折保存最佳模型和pipeline。
• 集成预测：性能加权集成（指数权重）。
• 可视化：混淆矩阵、专家利用热图、SHAP特征重要性、选定特征相似度分析。
• 生成部署包：包含所有fold的模型、pipeline、配置文件和标签映射。

使用方法:

from inkhinge.core import HAP_MoE

result = HAP_MoE(
    json_file_path="processed_valleys_data.json",
    test_size=0.15,
    n_splits=5,
    seed=42,
    output_dir="my_hap_moe_run"
)
print(f"测试准确率: {result['test_accuracy']:.4f}")
print(f"部署包保存在: {result['deployment_dir']}")

---

load_HAP_MoE

加载预训练的HAP-MoE部署包，对新数据进行两阶段预测（分类+异常检测），识别“未知”类别样本，并生成详细报告与可视化。

参数:

• deployment_dir (str, 可选): 部署包目录路径，默认"hap_moe_deployment_package"。
• new_data_path (str, 可选): 新数据JSON文件路径，默认"processed_valleys_data_val.json"。
• anomaly_threshold (float, 可选): 异常检测阈值（0~1），越高越严格，默认0.8。
• output_dir (str, 可选): 输出目录（保存结果文件），默认当前目录。
• save_plots (bool, 可选): 是否保存可视化图像，默认True。
• return_results (bool, 可选): 是否返回结果字典，默认True。

返回:

• 字典，包含：
  • predictions: 预测类别数组（-1表示“未知”）。
  • probabilities: 类别概率矩阵。
  • confidence_scores: 最大概率（置信度）。
  • top_k_classes: 每个样本的Top-3类别名称列表。
  • top_k_confidences: Top-3置信度数组。
  • anomaly_scores: 异常分数数组。
  • report: 详细报告字典（含分类指标、分布统计等）。
  • output_files: 生成的文件路径（JSON结果、图像）。

核心功能:

• 自动加载部署包中的模型、pipeline、配置和标签映射。
• 解析新数据JSON中的特征字符串。
• 两阶段预测：
  • 第一阶段：常规集成分类，得到概率和置信度。
  • 第二阶段：基于置信度、概率熵、特征距离计算异常分数，标记低置信度/高异常样本为“unknown”。
• 生成详细报告：包含类别分布、置信度分布、异常分数分布、不确定样本示例、分类报告（含unknown类别）。
• 可视化：预测类别分布、置信度直方图、异常分数直方图、确定vs不确定饼图。
• 保存结果JSON和图像。

使用方法:

from inkhinge.core import load_HAP_MoE

results = load_HAP_MoE(
    deployment_dir="hap_moe_results/hap_moe_deployment_package",
    new_data_path="new_valley_data.json",
    anomaly_threshold=0.8,
    output_dir="prediction_output",
    save_plots=True
)
print(f"预测完成，不确定样本比例: {results['report']['summary']['uncertain_ratio']:.2%}")
print(f"结果JSON保存至: {results['output_files']['results_json']}")

---

GrayValueCalculation类

提供图像灰度值精准计算功能，支持单张/批量图片处理，可通过RGB范围筛选特定区域（如目标物体、背景排除），适用于图像光谱特征与像素级分析。

静态方法process_single_image

处理单张图片，筛选符合RGB范围的区域，计算有效区域的平均灰度值并输出结果文件。

参数:

• image_path (str): 图片文件路径。
• red_range (tuple): 红色通道范围，格式(最小值, 最大值)（0-255）。
• green_range (tuple): 绿色通道范围，格式(最小值, 最大值)（0-255）。
• blue_range (tuple): 蓝色通道范围，格式(最小值, 最大值)（0-255）。
• max_valid_width (int): 有效区域的最大宽度（像素）。
• max_valid_height (int): 有效区域的最大高度（像素）。
• region_size (int): 基础分析区域大小（如9表示9×9像素块）。
• output_dir (str, 可选): 结果文件保存目录，默认"results"。

返回:

• 字典：包含image_path（图片路径）、overall_average（所有有效区域的平均灰度值）、result_file（结果文件路径）；处理失败返回None。

静态方法process_images

批量处理图片（自动识别文件/目录），生成每张图片的灰度值结果与汇总报告。

参数:

• input_path (str): 单个图片文件路径或包含图片的目录路径。
• red_range (tuple)、green_range (tuple)、blue_range (tuple): 同process_single_image。
• max_valid_width (int)、max_valid_height (int)、region_size (int): 同process_single_image。
• output_dir (str, 可选): 结果文件保存目录，默认"results"。

返回:

• 列表：包含每张图片的处理结果字典；输入路径无效或处理失败返回空列表。

支持图片格式:

.png, .jpg, .jpeg, .tif, .tiff

使用方法:

from inkhinge.core import GrayValueCalculation

# 处理单张TIF图片
single_result = GrayValueCalculation.process_single_image(
    image_path="tifdemo/an.tif",
    red_range=(0, 15),
    green_range=(0, 15),
    blue_range=(0, 15),
    max_valid_width=10,
    max_valid_height=10,
    region_size=9,
    output_dir="analysis_results"
)
print(f"单张图片平均灰度值：{single_result['overall_average']:.2f}")

# 批量处理目录中的所有图片
batch_results = GrayValueCalculation.process_images(
    input_path="image_directory/",
    red_range=(0, 15),
    green_range=(0, 15),
    blue_range=(0, 15),
    max_valid_width=10,
    max_valid_height=10,
    region_size=9,
    output_dir="batch_analysis_results"
)
print(f"批量处理完成，成功处理{len(batch_results)}张图片")

---

TifToPng类

轻量型TIF到PNG格式转换工具，支持单文件精准转换与目录批量转换，自动处理文件命名与目录创建，确保图像兼容性。

静态方法convert_single

将单个TIF文件转换为PNG格式，支持自定义输出路径。

参数:

• input_path (str): TIF文件路径。
• output_path (str, 可选): 输出PNG文件路径，默认在原目录生成同名PNG。

返回:

• 布尔值：True表示转换成功，False表示失败。

静态方法batch

批量转换目录中所有TIF文件为PNG格式，支持自定义输出目录。

参数:

• input_dir (str): 包含TIF文件的目录路径。
• output_dir (str, 可选): 输出PNG文件的目录路径，默认使用输入目录。

使用方法:

from inkhinge.core import TifToPng

# 单文件转换（默认输出到原目录）
TifToPng.convert_single("input.tif")

# 单文件转换（指定输出路径）
TifToPng.convert_single("tifdemo/an.tif", "tifdemo/an.png")

# 批量转换（默认输出到输入目录）
TifToPng.batch("input_dir")

# 批量转换（指定输出目录）
TifToPng.batch("input_dir", "output_dir")

---

insert_crystals

将晶体结构（分子、离子或原子）插入主体结构，考虑周期性边界条件与原子碰撞规避，适用于材料模拟与晶体工程场景。

参数:

• host_path (str): 主体结构文件路径（如CIF格式）。
• insert_path (str): 待插入结构文件路径（如CIF格式）。
• center (tuple): 插入区域中心坐标 (x, y, z)（单位与主体结构一致）。
• radius (float): 插入区域半径（控制插入范围）。
• num (int): 待插入的结构数量。
• tolerance (float, 可选): 碰撞容忍度（0.0-1.0，值越小碰撞限制越严格），默认0.9。
• max_attempts (int, 可选): 最大插入尝试次数（避免无限循环），默认1000。
• output_path (str, 可选): 输出结构文件路径，默认None（不保存）。
• view_crystals (bool, 可选): 是否可视化插入后的结构，默认True。

返回:

• ASE的Atoms对象：插入后的完整晶体结构。

核心功能:

• 自动识别插入结构类型（分子、离子、原子），采用对应插入策略。
• 基于周期性边界条件计算原子间最小距离，避免插入结构与主体结构过度重叠。
• 支持自定义原子半径字典，适配不同元素的碰撞判断需求。
• 在指定球形区域内随机生成插入位置，确保插入范围可控。

使用方法:

from inkhinge.core import insert_crystals

# 插入5个NaCl结构到MIL-101主体中
insert_crystals(
    host_path="6_mil-101_pbesol-ot_optcell.cif",
    insert_path="NaCl_insert.cif",
    center=[10.0, 10.0, 10.0],
    radius=5.0,
    num=5,
    tolerance=0.9,
    max_attempts=1000,
    output_path="result.cif"
)

---

功能特点

1. 多类型数据兼容：

   • 覆盖光谱（SPA）、生物信号（ABF）、图像（TIF/PNG/JPG）、晶体结构（CIF）四大类科研数据。
   • 适配ABF2及以下版本、Omnic SPA全版本，支持100000 Hz高采样率生物信号处理。

2. 高精度与鲁棒性：

   • 光谱转换保留20位小数精度，避免科学计数法损失数据；ABF转换自动处理通道长度不匹配（截断/补NaN）。
   • 拟合过程加入物理约束（如振幅非负、峰位在波数范围内），失败时启用备用初始值，提升复杂数据拟合成功率。
   • 所有文件操作均包含路径校验与目录自动创建，避免“目录不存在”“路径为文件”等常见错误。

3. 自动化与便捷性：

   • 单函数支持“文件/目录”双输入（如abf_to_csv自动切换单文件/批量模式），减少函数调用复杂度。
   • 批量处理支持递归子目录，合并数据结构适配深度学习输入格式（如光谱CSV列对应时间点）。
   • 图像分析与格式转换无需手动筛选文件，自动识别支持格式并生成结果报告。

4. 可视化与可解释性：

   • 曲线拟合自动生成“原始数据散点+拟合曲线”图，三维拟合输出曲面对比图，支持实时预览。
   • 拟合结果包含参数、R²值、表达式，晶体插入支持可视化验证，所有结果可导出为文本文件追溯。
   • 峰检测提供全局检测图、连接峰事件图、原始/滤波对比细节图，便于人工核查。
   • 机器学习模型输出混淆矩阵、专家利用热图、SHAP特征重要性、特征相似度矩阵，增强模型透明度。
   • 两阶段预测提供置信度分布、异常分数分布、不确定样本示例，辅助决策。

5. 深度学习集成：

   • 内置HAP-MoE先进分类模型，支持多分类、不平衡数据、困难样本挖掘。
   • 自动生成部署包，便于模型迁移与二次开发。
   • 两阶段预测有效识别未知类别，提升实际应用可靠性。

贡献

若您希望为inkhinge工具集贡献功能或修复问题，请遵循以下步骤：

1. Fork本项目仓库
2. 创建特性分支（如git checkout -b feature/ABFv3Support）
3. 提交代码更改（如git commit -m 'Add ABF3 format support'）
4. 推送分支至远程仓库（如git push origin feature/ABFv3Support）
5. 打开Pull Request并描述功能细节

许可证

本项目采用MIT许可证，允许自由使用、修改与二次分发，详情请见LICENSE文件。