MolPropLab — Molecular Property Prediction Platform

An end-to-end full-stack machine learning application for predicting molecular properties from SMILES.

1. Core Features

Multi-property prediction: Predict 10 molecular properties at once (molecular weight, LogP, LogS, pKa, boiling point, melting point, refractive index, vapor pressure, density, flash point)
Python ML stack: RDKit preprocessing, molecular descriptors, ECFP (1024), PyTorch Geometric PotentialNet/GIN, LightGBM/RandomForest baselines
Uncertainty estimation: MC-Dropout (GNN) / small ensemble (baseline)
Interpretability: SHAP (baseline), gradient saliency (GNN) → atom-level importance JSON
Backend: Node.js + Express + TypeScript; invokes Python via child_process.spawn
Frontend: React + Vite + Tailwind + shadcn-style components + 3Dmol.js
Batch jobs: Simple in-memory queue & CSV/XLSX upload with model selection

Enter a SMILES string and get predictions for all properties, uncertainty estimates, and atom-importance heatmaps in one step.

2. Repository Structure

Top Level

ml/: ML core (data processing, train/eval, inference scripts, model weights and evaluation results).
server/: Backend API (Express + TypeScript) for prediction endpoints, batch job queue, and subprocess calls to ml/inference.py.
frontend/: Web UI (React + Vite + Tailwind) with single prediction, batch prediction, model browser, comparison charts, and 3D molecular visualization.
scripts/: Helper install scripts (mainly Linux/macOS) for one-command dependency setup.
requirements.txt: Python dependencies.
environment.yml: Conda environment (includes RDKit and some system deps) for one-shot environment creation.

`ml/` (Machine Learning)

ml/data/: Per-property datasets (CSV with smiles,target columns).
ml/saved_models/: Trained model weights and normalization params (train first):
- Baseline: baseline_<property>_v1.pkl
- GNN: gnn_<property>_v1.pth + gnn_<property>_v1_norm.json
ml/configs/: Training configuration.
ml/utils.py: Shared utilities (SMILES cleaning, ECFP/descriptor features, graph building, scaffold split, preprocessing, etc.).
ml/train_baseline.py / ml/train_gnn.py: Training scripts for baseline and GNN models.
ml/eval_baseline.py / ml/eval_gnn.py: Evaluation scripts (RMSE, MAE, R², MAPE, correlation, etc.).
ml/compare_models.py: Compare baseline vs GNN; outputs *_comparison.json and comparison_summary.json for the frontend.
ml/inference.py: Inference entry point (single SMILES or CSV/XLSX batch; JSON/CSV output).
ml/tests/: Python unit tests.

`server/` (Backend)

server/src/index.ts: Main server; /predict, /batch_predict, /models, etc.
server/tmp/: Temp directory for uploads and batch processing.
server/test/: Backend tests.

`frontend/` (Frontend)

frontend/src/App.tsx: Routes and page logic (single/batch prediction, model browser, comparison charts).
frontend/src/ui.tsx / frontend/src/index.css: UI components and global styles.

3. Requirements

Note: Environment used during development and experimentation.

System

OS: Windows 11
CPU: 64-bit, Intel(R) Core(TM) i7-14650HX, 16 cores
RAM: 16 GB
GPU: CUDA-capable NVIDIA GPU
- Model: NVIDIA GeForce RTX 4050 Laptop GPU
- CUDA: 12.7
- Driver: 566.24

Python

Version: 3.11.14
Package manager: Conda recommended for RDKit (pip on Windows is not recommended)
Key library versions: See requirements.txt

You can also create the Conda environment from environment.yml at the project root.

Node.js

Version: 20.19.5 recommended
- Download from nodejs.org
- Or use the archive: Node.js v20.19.5 and add the folder containing node.exe to your PATH

4. Installation

Example flow for Conda + Windows; macOS/Linux are similar with minor path differences.

Quick Install (recommended on Linux/macOS)

# 1. Create and activate Conda environment
conda create -n molproplab python=3.11 -y
conda activate molproplab

# 2. Run setup script (installs all dependencies)
bash scripts/setup.sh

The script will:

Check the Conda environment
Install RDKit
Install all Python dependencies
Install Node.js backend and frontend dependencies

Note: On Windows, use Git Bash or WSL for this script, or follow the manual steps below.

Manual Installation

1. Create Conda environment

conda create -n molproplab python=3.11 -y
conda activate molproplab

2. Install RDKit

conda install -c conda-forge rdkit -y

Note: On Windows, avoid pip install rdkit; Conda is more reliable.

3. Install remaining Python dependencies

# From project root
pip install -r requirements.txt

Important:
NumPy 1.26.4 is used for stability on Windows
PyTorch: The default install is CPU-only. For GPU support:
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121
If PyTorch Geometric is hard to install, you can skip it; GNN will fall back to baseline automatically

4. Install Node.js dependencies

cd server
npm install

cd ../frontend
npm install

5. Running the Services

Keep the Python environment activated (conda activate molproplab).

Start the backend API

From the project root:

cd server
npm run dev

Backend default: http://localhost:3001

Note: The server picks the interpreter in server/src/index.ts via PYTHON / CONDA_PREFIX / python. For a different Conda env:

Set before start: set PYTHON=your\python\path && npm run dev (Windows) or export PYTHON=... (Unix)

Or set the PYTHON system environment variable

Start the frontend

In a separate terminal (no strict Python requirement):

cd frontend
npm run dev

Frontend default: http://localhost:5173

6. Usage

Web UI

Open http://localhost:5173 in a browser
Go to Single Prediction
Enter a SMILES, e.g.:
- CCO (ethanol)
- CC(=O)O (acetic acid)
- c1ccccc1 (benzene)
Choose model type (baseline or gnn)
Click Predict
You will see:
- A table of predictions for all properties, including:
  - Molecular weight (MW)
  - LogP (lipophilicity)
  - LogS (aqueous solubility)
  - pKa
  - Boiling point
  - Melting point
  - Refractive index
  - Vapor pressure
  - Density
  - Flash point
- Predicted value and uncertainty (σ) per property
- A 3D molecular view with atom-level heatmap (brighter = higher importance)

Batch prediction

Open Batch Prediction
Select model type (baseline or gnn)
Upload a CSV or XLSX with a smiles column (see ml/data/logp.csv)
The backend queues the job
Poll job status
Download results when done (columns: {property}_prediction and {property}_uncertainty)

7. Python CLI

Train models

cd ml

# Train baseline models for all properties
python train_baseline.py

# Train GNN models for all properties (requires PyTorch and PyTorch Geometric)
python train_gnn.py

Note: Training scripts train all 10 properties. For first use, run python train_baseline.py so predictions include all properties.

Evaluate models

# Evaluate baseline (RMSE, MAE, R2, MAPE, etc.)
python eval_baseline.py

# Evaluate GNN
python eval_gnn.py

Note: Evaluation uses scaffold_split, consistent with training, for reliable metrics.

Compare models

# Compare baseline vs GNN for one property
python compare_models.py --property logp

# Compare all properties
python compare_models.py

Outputs include RMSE, MAE, R², MAPE, correlation, and which model performs better per property.

Inference

# Single SMILES (all properties)
python inference.py --smiles "CCO" --model baseline --json
python inference.py --smiles "CCO" --model gnn --json

# Batch (CSV and XLSX)
python inference.py --csv data/logp.csv --output out.csv --model baseline
python inference.py --csv data/logp.csv --output out.csv --model gnn

Note: Single prediction returns all 10 properties. Batch output columns use {property}_prediction and {property}_uncertainty.

8. Troubleshooting

1. RDKit install fails

Problem: Cannot install or import RDKit

Fix:

Use a Conda environment
Run: conda install -c conda-forge rdkit
Avoid pip install rdkit on Windows

2. PyTorch DLL errors (Windows)

Problem: Errors like OSError: [WinError 127] Error loading "shm.dll" or [WinError 182]

Fix:

Install Visual C++ Redistributable
- https://aka.ms/vs/17/release/vc_redist.x64.exe

If it persists, reinstall PyTorch:

pip uninstall -y torch torchvision torchaudio
pip install torch==2.3.1 torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu
pip install "numpy<2"

The code sets TORCH_SHM_DISABLE=1 to reduce shared-memory issues

3. GNN falls back to baseline

Problem: You select GNN but the response model field is baseline

Causes:

PyTorch or PyTorch Geometric not installed correctly
DLL load failure on Windows

Diagnosis:

Check server logs
Inspect Python stderr from the subprocess

Fix:

See “PyTorch DLL errors” above
Install Visual C++ Redistributable
Ensure the Python environment is activated

4. Port conflicts

Problem: Port already in use

Fix:

Backend: change PORT in server/src/index.ts
Frontend: change server.port in frontend/vite.config.ts
Defaults:
- Backend: http://localhost:3001
- Frontend: http://localhost:5173

5. Python path

Problem: Server cannot find the Python interpreter

Fix:

Before start: set PYTHON=your\python\path && npm run dev (Windows)
Resolution order: PYTHON env var → CONDA_PREFIX/python.exe → system python

9. Models

Data preprocessing

Before training and evaluation:

Missing values: Rows with empty SMILES or target are removed
Outliers: IQR method removes values outside Q1 − 1.5×IQR to Q3 + 1.5×IQR (only when n > 10)
Normalization:
- Baseline: Z-score on input features (descriptors + ECFP)
- GNN: Standardize targets using training-set mean and std

Train/val/test split

Method: scaffold_split (scaffold-based; sample-count allocation)
- Molecules with the same scaffold stay in the same split to reduce leakage
- Large clusters may be split to approximate target ratios
- Default: 70% train, 15% val, 15% test
- Training: train on 70%, early stopping on 15% val
- Evaluation: metrics on 15% test

Multi-property prediction

The system predicts these 10 properties:

Molecular weight (MW) — g/mol
LogP — lipophilicity
LogS — aqueous solubility, log(mol/L)
pKa — acid dissociation constant
Boiling point — °C
Melting point — °C
Refractive index — dimensionless
Vapor pressure — Pa
Density — g/cm³
Flash point — °C

Each property has its own baseline and GNN model. At inference time, all property models run and results are returned together.

Baseline model

Algorithm: LightGBM (preferred) or RandomForest (fallback)
Features: Molecular descriptors + ECFP (1024 bits), Z-score normalized on training data
Uncertainty: Std dev across a 3-model ensemble
Interpretability: SHAP mapped to atom importance
Regularization: Dynamic hyperparameters by dataset size; subsample and colsample_bytree
Use when: Fast prediction, small/medium data, no GPU
Data: At least ~20 samples per property; 100+ recommended

GNN model

Algorithm: PotentialNet (default) or GIN (configurable)
Features: Graph neural network on molecular graphs; targets standardized on training data
Uncertainty: MC-Dropout (20 forward passes)
Interpretability: Gradient saliency → atom importance
Regularization: Dropout, early stopping on val RMSE, architecture scaled to dataset size
Use when: Larger datasets (500+ recommended), complex patterns, GPU helpful
Notes:
- Falls back to baseline if PyTorch/PyG unavailable
- Baseline often wins on small data (<200 samples)
- Hyperparameters (hidden size, epochs, etc.) adapt to dataset size

Evaluation metrics

RMSE — root mean squared error
MAE — mean absolute error (robust to outliers)
R² — coefficient of determination
MAPE — mean absolute percentage error (cross-property comparison)
Correlation — linear correlation between predictions and labels

All metrics are computed on the test set with scaffold_split, matching training.

10. Tests

Python

cd ml
python -m tests.test_inference

Node.js

cd server
npm test

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

MolPropLab — Molecular Property Prediction Platform

1. Core Features

2. Repository Structure

Top Level

ml/ (Machine Learning)

server/ (Backend)

frontend/ (Frontend)

3. Requirements

System

Python

Node.js

4. Installation

Quick Install (recommended on Linux/macOS)

Manual Installation

1. Create Conda environment

2. Install RDKit

3. Install remaining Python dependencies

4. Install Node.js dependencies

5. Running the Services

Start the backend API

Start the frontend

6. Usage

Web UI

Batch prediction

7. Python CLI

Train models

Evaluate models

Compare models

Inference

8. Troubleshooting

1. RDKit install fails

2. PyTorch DLL errors (Windows)

3. GNN falls back to baseline

4. Port conflicts

5. Python path

9. Models

Data preprocessing

Train/val/test split

Multi-property prediction

Baseline model

GNN model

Evaluation metrics

10. Tests

Python

Node.js

`ml/` (Machine Learning)

`server/` (Backend)

`frontend/` (Frontend)