Metadata-Version: 2.4
Name: chrom-qsar
Version: 0.1.1
Summary: A streamlined machine learning pipeline for QSAR and regression tasks with SHAP interpretability.
Author-email: Your Name <your.email@university.edu>
License: MIT
Keywords: machine-learning,qsar,shap,regression,optuna
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=1.3.0
Requires-Dist: numpy>=1.21.0
Requires-Dist: scikit-learn>=1.0.0
Requires-Dist: xgboost>=1.5.0
Requires-Dist: lightgbm>=3.3.0
Requires-Dist: optuna>=3.0.0
Requires-Dist: shap>=0.41.0
Requires-Dist: matplotlib>=3.4.0
Requires-Dist: seaborn>=0.11.0
Requires-Dist: joblib>=1.1.0
Requires-Dist: openpyxl>=3.0.0
Dynamic: license-file

# chrom_qsar 
## Requirements

在运行本库之前，请确保安装了 Python 3.8+，并安装以下依赖项:
```bash
pip install pandas numpy scikit-learn xgboost lightgbm optuna shap matplotlib seaborn joblib openpyxl
```

## Quick Start

### Step 1: 准备数据
确保您的 Excel 数据文件与运行脚本位于同一目录下。
默认数据格式要求：Excel 表格的 第1列 为目标变量 (Target/Y)，第2列 及之后的所有列为特征变量 (Features/X)。首行应为列名。
### Step 2: 训练与优化模型
创建 main.py 并运行，库将自动执行数据清洗、13种模型的 Optuna 调参、测试集评估、SHAP 分析并保存模型文件。

```python
# main.py
import chrom_qsar

if __name__ == '__main__':
    trainer = QSARModelTrainer(
        data_path='YOUR FILEPATH',
        out_dir='training_results',  
        n_trials=200                 # 100~500
    )
    
    summary_df = trainer.run()
    print("\n训练完成，最终模型排名:\n", summary_df)
```

### Step 3: 批量分析与深度可视化
如果您已经训练好了模型，或者想在新的测试集下重新分析，请使用 QSARModelAnalyzer。

```python
# main_analyze.py
import chrom_qsar

if __name__ == '__main__':
    analyzer = QSARModelAnalyzer(
        data_path='YOUR FILEPATH',
        model_dir='training_results',      
        out_dir='batch_analysis_results'   
    )
```

## Advanced Usage

- 若需引入新模型，只需在 chrom_qsar/models.py 的 `get_model_configs()` 字典中添加即可
- 如果您的 Excel 表格列顺序不同，请修改 `chrom_qsar/data.py` 中的 load_and_clean_data 函数：

## Notes

- 中文显示问题：库内已内置 `plt.rcParams['font.sans-serif'] = ['SimHei', 'Arial']`。若您的操作系统（如 macOS 或 Linux）未安装 SimHei 字体，图表中的中文可能会显示为方块。请将其替换为您系统已有的中文字体（如 PingFang SC 或 WenQuanYi Micro Hei）。
- SHAP 计算时间：对于 PermutationExplainer 或 KernelExplainer，当特征数量较多或样本量较大时，计算可能较慢。库内已默认设置 `max_evals` 限制以平衡速度与精度。
