surfacia 3.0.1

A comprehensive Python package for molecular structure-activity relationship (QSAR/QSPR) studies with interactive SHAP visualization and AI-powered analysis

Surfacia - Surface Atomic Chemical Interaction Analyzer

Version: 3.0.0

Project Overview

Surfacia is a surface atomic chemical interaction analyzer based on quantum chemical calculations, designed for molecular property prediction and machine learning analysis. This tool integrates a complete workflow from SMILES strings to final property predictions.

Key Features

• SMILES Conversion: Convert SMILES strings to 3D molecular structures
• Geometry Optimization: Fast geometry optimization using XTB
• Quantum Chemical Calculations: Generate and run Gaussian calculations
• Property Analysis: Molecular property analysis using Multiwfn
• Feature Extraction: Extract atomic-level and functional group-level molecular descriptors
• Machine Learning: Integrated machine learning analysis tools
• Visualization: Interactive SHAP analysis and molecular visualization

Installation

System Requirements

• Python >= 3.7
• Linux/Windows/macOS

Installation Steps

# 1. Clone the repository
git clone https://github.com/yourusername/surfacia.git
cd surfacia

# 2. Create virtual environment (recommended)
python3 -m venv venv
source venv/bin/activate  # Linux/Mac
# or venv\Scripts\activate  # Windows

# 3. Install dependencies
pip install -r requirements.txt

# 4. Install surfacia package
pip install -e .  # Development mode

## Usage

### Command Line Interface

# View help
surfacia --help

# Complete workflow example:
surfacia smi2xyz -i molecules.csv
surfacia xtb-opt
surfacia xyz2gaussian
surfacia run-gaussian
surfacia multiwfn
surfacia extract-features -i FullOption2.csv -m 3
surfacia ml-analysis -i FinalFull.csv --test-samples 1,2,3
surfacia shap-viz -i Training_Set_Detailed.csv -x ./xyz_files/

Workflow Steps
SMILES to XYZ: Read SMILES from CSV file and generate 3D structures
Geometry Optimization: Optimize molecular geometry using XTB (optional)
Gaussian Calculations: Generate input files and run quantum chemical calculations
Multiwfn Analysis: Calculate molecular surface properties and descriptors
Feature Extraction: Extract atomic and functional group features
Machine Learning Analysis: Perform feature selection and model training
Result Visualization: Interactive analysis using SHAP

Input File Format
CSV files should contain the following columns:
smiles: SMILES strings
target: Target property values
Other experimental feature columns (optional)

## Required External Software
XTB Installation
Official Documentation: https://xtb-docs.readthedocs.io/en/latest/setup.html

Gaussian Installation
Detailed Installation Guide: http://sobereva.com/439

Multiwfn Installation
Official Website: http://sobereva.com/multiwfn/

Configuration
Environment Variables
Add these to your ~/.bashrc (Linux) 
## 许可证

MIT License

## 作者

Yuming Su ([e-mail])