Metadata-Version: 2.4
Name: surfacia
Version: 3.0.3
Summary: A comprehensive Python package for molecular structure-activity relationship (QSAR/QSPR) studies with interactive SHAP visualization and AI-powered analysis
Author-email: YumingSu <823808458@qq.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/sym823808458/Surfacia
Project-URL: Bug Reports, https://github.com/sym823808458/Surfacia/issues
Project-URL: Source, https://github.com/sym823808458/Surfacia
Project-URL: Documentation, https://surfacia.readthedocs.io/
Keywords: chemistry,quantum-chemistry,molecular-descriptors,QSAR,QSPR,computational-chemistry,rdkit,gaussian,multiwfn,machine-learning,SHAP,molecular-visualization
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: openbabel-wheel>=3.1.1
Requires-Dist: scikit-learn>=1.0.0
Requires-Dist: xgboost<3.0.0,>=2.1.4
Requires-Dist: shap<0.49.0,>=0.48.0
Requires-Dist: matplotlib>=3.5.0
Requires-Dist: seaborn>=0.11.0
Requires-Dist: plotly>=5.0.0
Requires-Dist: zhipuai>=2.0.0
Requires-Dist: dash>=2.0.0
Requires-Dist: cclib>=1.7.2
Requires-Dist: click>=8.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: toml>=0.10.2
Requires-Dist: tqdm>=4.64.0
Requires-Dist: pathlib2>=2.3.7
Requires-Dist: joblib>=1.1.0
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov>=2.0; extra == "dev"
Requires-Dist: black>=21.0; extra == "dev"
Requires-Dist: flake8>=3.8; extra == "dev"
Requires-Dist: sphinx>=4.0; extra == "dev"
Requires-Dist: sphinx-rtd-theme>=1.0; extra == "dev"
Provides-Extra: viz
Requires-Dist: matplotlib>=3.5.0; extra == "viz"
Requires-Dist: seaborn>=0.11.0; extra == "viz"
Requires-Dist: plotly>=5.0.0; extra == "viz"
Requires-Dist: py3Dmol>=2.0.0; extra == "viz"
Requires-Dist: ipywidgets>=7.6.0; extra == "viz"
Requires-Dist: ipython>=7.0.0; extra == "viz"
Provides-Extra: notebook
Requires-Dist: jupyter>=1.0.0; extra == "notebook"
Requires-Dist: notebook>=6.4.0; extra == "notebook"
Requires-Dist: ipywidgets>=7.6.0; extra == "notebook"
Requires-Dist: ipython>=7.0.0; extra == "notebook"
Dynamic: license-file

# Surfacia

Surface Atomic Chemical Interaction Analyzer for descriptor extraction and interpretable machine learning in computational chemistry.

## At a Glance

- End-to-end workflow: `SMILES -> 3D -> xTB/Gaussian -> Multiwfn -> descriptors -> ML/SHAP`
- CLI-first design for local and remote Linux/HPC usage
- Supports full workflow mode and modular step-by-step execution
- Includes `SPES-C`, a SHAP-landscape candidate-prioritization layer for high-value test-set ranking

## Current Release

- Latest stable version: **3.0.3**
- Python requirement: **>= 3.9**
- License: **MIT**

PyPI: [https://pypi.org/project/surfacia/](https://pypi.org/project/surfacia/)

## Quick Install (Recommended for Most Users)

```bash
# optional but recommended
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

pip install --upgrade pip
pip install surfacia
```

Check installation:

```bash
surfacia --help
python -c "import surfacia; print(surfacia.__version__)"
```

## Important Compatibility Note (ML Stage)

To avoid ML parsing failures such as:

`could not convert string to float: '[-3.xxxE0]'`

use the validated dependency range:

- `xgboost>=2.1.4,<3.0.0`
- `shap>=0.48.0,<0.49.0`

Quick fix:

```bash
pip install --force-reinstall "xgboost==2.1.4" "shap==0.48.0"
```

## External Software Requirements

Surfacia orchestrates external quantum-chemistry tools. Ensure these commands are available in your `PATH`:

- `xtb`
- `g16` (and `formchk`)
- `Multiwfn` or `Multiwfn_noGUI`

## Minimal Usage

Run full workflow:

```bash
surfacia workflow -i molecules.csv --test-samples "1,3"
```

Run ML only (for existing descriptor table):

```bash
surfacia ml-analysis -i FinalFull_Mode3_20_168.csv \
  --max-features 1 --stepreg-runs 1 \
  --train-test-split 0.85 --epoch 32 --cores 8 \
  --test-samples "1,2,3"
```

Launch SHAP visualization with SPES overlay:

```bash
surfacia shap-viz \
  -i Training_Set_Detailed_Final_5feats_20260209_102423.csv \
  -x ./xyz_files \
  --test-csv Test_Set_Detailed_Final_5feats_20260209_102423.csv \
  --spes-csv SPES_Test_Set_Detailed_Final_5feats_20260209_102423.csv
```

## SPES Candidate Prioritization

SPES is not a replacement regression model. It is a post-prediction prioritization layer built on the selected Surfacia model and its SHAP landscape.

- The raw selected-model prediction remains the main interpretable regression output.
- `SPES-C` adds a conservative ranking score for high-value candidate discovery.
- In the interactive SHAP dashboard, users can switch the external overlay from the raw test set to the SPES test-set layer.
- When a test set is present, current ML analysis outputs now automatically write `SPES_Test_Set_Detailed_*.csv` and matching metadata JSON files.

## Source Install (Developers)

```bash
git clone https://github.com/sym823808458/Surfacia.git
cd Surfacia
pip install -e .
```

## Documentation

- Full docs: [https://surfacia.readthedocs.io/](https://surfacia.readthedocs.io/)
- Troubleshooting: [https://surfacia.readthedocs.io/en/latest/user_guide/troubleshooting.html](https://surfacia.readthedocs.io/en/latest/user_guide/troubleshooting.html)
- Mode3 top-20 remote debug example: [https://surfacia.readthedocs.io/en/latest/examples/mode3_top20_remote_debug.html](https://surfacia.readthedocs.io/en/latest/examples/mode3_top20_remote_debug.html)

## Citation

If Surfacia helps your research, please cite the project and related publication when available.

## Contact

- Author: Yuming Su
- Email: 823808458@qq.com
- Issues: [https://github.com/sym823808458/Surfacia/issues](https://github.com/sym823808458/Surfacia/issues)
