inkhinge 0.1.10

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

inkhinge

inkhinge是一个专为光谱分析设计的工具集，专注于光谱数据的处理、转换与拟合分析，支持Omnic SPA格式文件的转换及Kubelka-Munk（KM）值的多维度曲线拟合，为光谱数据分析提供从数据预处理到高级建模的完整流程支持。通过pip install inkhinge安装后，可便捷处理光谱数据转换、背景校正、批量处理及多维度拟合等任务。

安装

pip install inkhinge

函数文档

read_to_csv

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

参数:

• 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）。

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²值、原始数据及拟合表达式等。

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σ²)))
（η为混合系数，a为振幅，x₀为峰位，σ为半宽）

curvefit_km_t_wavenumber

对时间-波数-KM值三维数据进行拟合，先通过时间序列拟合获取常数k，再对a(w)和c(w)进行多峰高斯-洛伦兹拟合，最终构建三维模型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, 可选): 拟合时需要用的峰的个数，默认为3。

返回:

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

核心功能:

• 自动修正波数非单调问题（排序确保1300→1320 cm⁻¹）。
• 分两步拟合：先求k（所有波数的b值均值），再固定k拟合a(w)和c(w)。
• 输出原始数据与拟合曲面的三维对比图，标注整体及分项R²值。

使用方法

1. SPA文件转换为CSV（含批量处理与合并）

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  # 保留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}个文件")

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

2. KM值随时间变化的曲线拟合

from inkhinge.core import curvefit_km_t

# 对CSV中第3行的KM值进行时间序列拟合
result = curvefit_km_t(
    file_path="merged_spectra.csv",
    target_row=3,  # 目标行号（从1开始）
    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}")

3. KM值与波数的高斯-洛伦兹混合拟合

from inkhinge.core import curvefit_km_wavenumber

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

4. 时间-波数-KM值的三维拟合

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, #默认为3
)
print(f"整体拟合优度R²：{result['r2_overall']:.4f}")
print(f"常数k值：{result['k']:.6f}")

功能特点

1. 高精度数据处理：

   • 光谱转换保留高小数精度（默认20位），避免科学计数法损失精度。
   • 拟合过程采用物理约束（如振幅非负、峰位在波数范围内），确保参数合理性。

2. 自动化与鲁棒性：

   • 自动识别光谱类型、处理波数排序问题、缺失值标记为nan。
   • 拟合失败时启用备用初始值策略，提高复杂数据的拟合成功率。

3. 全面的可视化支持：

   • 曲线拟合结果自动生成散点图（原始数据）与线图（拟合曲线）。
   • 三维拟合提供原始数据与拟合曲面的对比图，支持视角同步。

4. 灵活的批量处理：

   • 支持递归遍历子目录的SPA文件，合并后的数据结构适配深度学习输入格式。

贡献

如果你想为inkhinge工具集做出贡献，请遵循以下步骤：

1. Fork本仓库
2. 创建特性分支（git checkout -b feature/SpectralFeature）
3. 提交更改（git commit -m 'Add spectral preprocessing feature'）
4. 推送分支（git push origin feature/SpectralFeature）
5. 打开Pull Request

许可证

本项目采用MIT许可证 - 详情请见LICENSE文件。