prop-profiler 0.2.1

A molecular property profiler for drug discovery applications

Prop Profiler

A molecular property profiler for drug discovery applications. This package provides machine learning models to predict various molecular properties including water solubility (ESOL, mg/L), logD, most basic pKa and other essential chemical properties, along with drug-likeliness scores (e.g. CNS-MPO, Stoplight, QED scores).

Features

• Water Solubility (ESOL, mg/L): Predicts aqueous solubility using molecular descriptors
• logD Prediction: Estimates distribution coefficient at physiological pH
• pKa Prediction: Predicts most basic site using MolGpKa (requires [pka] extra)
• CNS-MPO Scoring: Calculates Central Nervous System Multiparameter Optimization scores Paper (requires [pka] extra)
• Stoplight Scoring: Provides color-coded molecular property assessments (Stoplight)
• Command Line Interface: Easy-to-use CLI for batch processing

Installation

From PyPI (Recommended)

# Basic installation (without pKa/CNS-MPO prediction)
pip install prop-profiler

# Full installation with pKa prediction capabilities
pip install prop-profiler[pka]

# For development
pip install prop-profiler[pka,dev]

From Source

# Clone the repository
git clone https://github.com/eneskelestemur/prop_profiler.git
cd prop_profiler

# Install in development mode
pip install -e .

# Or with all features
pip install -e .[pka,dev]

Conda Environment (Alternative)

If you prefer conda environments:

# Create conda environment with all dependencies
conda env create -f environment.yml
conda activate prop-profiler
pip install -e .

Verify Installation

# Test the command line interface
prop-profiler --help

# Test the Python API
python -c "from prop_profiler import profile_molecules; print('Installation successful!')"

Quick Start

Command Line Usage

# Show help message and available options
prop-profiler --help

# Profile molecules from a SMILES file
prop-profiler -i molecules.smi -o results.csv

# Profile molecules from an SDF file
prop-profiler -i molecules.sdf -o results.csv

# Skip CNS-MPO scoring for faster processing
prop-profiler -i molecules.smi -o results.csv --skip-cns-mpo

# Use GPU for pKa prediction
prop-profiler -i molecules.smi -o results.csv --device cuda

Python API Usage

from prop_profiler import configure_logging, profile_molecules

configure_logging()

# Create some example smiles/molecules
smiles = ['CCO', 'CC(=O)O', 'c1ccccc1']

# Profile the molecules (basic features only)
results = profile_molecules(smiles, skip_cns_mpo=True, verbose=True)
print(results)

# Profile with CNS-MPO and pKa (requires [pka] extra)
# results = profile_molecules(smiles, verbose=True)

Extending with Predictors and Training

from prop_profiler import (
    Trainer,
    Predictor,
    EsolPredictor,
    LogDPredictor,
    PkaPredictor,
    CnsMpoPredictor,
    StoplightPredictor,
)

Input Formats

• SMILES files (.smi): One SMILES string per line
• SDF files (.sdf): Standard structure-data format
• CSV files (.csv): Must contain a column with SMILES strings

Output

The profiler returns a pandas DataFrame with the following columns:

• smiles: Input SMILES string
• mw: Molecular weight
• logp: Octanol-water partition coefficient
• hba: Hydrogen bond acceptors
• hbd: Hydrogen bond donors
• tpsa: Topological polar surface area
• num_rotatable_bonds: Number of rotatable bonds
• fsp3: Fraction of sp3 hybridized carbons
• qed: Quantitative Estimate of Drug-likeness
• esol_mg/L: Water solubility prediction (in mg/L)
• stoplight_score: Stoplight score (0-2) based on Stoplight paper
• stoplight_color: Color-coded assessment (Green/Yellow/Red)

When CNS-MPO scoring is enabled (requires [pka] extra):

• most_basic_pka: Most basic pKa value
• logd: LogD prediction at pH 7.4
• cns_mpo_score: CNS-MPO score (0-6)

Requirements

Core Dependencies

• Python >= 3.11
• NumPy, Pandas for data handling
• RDKit for cheminformatics
• scikit-learn for machine learning
• matplotlib for plotting
• tqdm for progress bars

Optional Dependencies (for pKa/CNS-MPO)

• PyTorch >= 2.0.0
• PyTorch Geometric >= 2.0.0

Install with: pip install prop-profiler[pka]

Logging

Use configure_logging once at application startup to control logging verbosity:

from prop_profiler import configure_logging
configure_logging()

Model Paths

Model file locations can be overridden with environment variables:

• PROP_PROFILER_ESOL_MODEL
• PROP_PROFILER_LOGD_MODEL
• PROP_PROFILER_ACID_MODEL
• PROP_PROFILER_BASE_MODEL
• PROP_PROFILER_MODEL_DIR (shared directory for all model files)

Per-model variables take precedence over PROP_PROFILER_MODEL_DIR.

The ESOL, LogD, and pKa model weights ship with the package under prop_profiler/model_weights. Install [pka] to enable pKa/CNS-MPO inference, but no extra model download is required.

Typing

Type checking is supported with mypy. Recommended usage:

mypy prop_profiler

License

MIT License - see LICENSE file for details.

Third-Party Components

This package includes a modified version of MolGpKa for pKa prediction:

• MolGpKa: Graph-convolutional neural network for pKa prediction
• Original Repository: https://github.com/Xundrug/MolGpKa
• License: MIT License
• Modifications: Optimized for integration and performance

Citation

If you use this package in your research, please cite:

@software{prop_profiler,
  author = {Enes Kelestemur},
  title = {Prop Profiler: A molecular property profiler for drug discovery},
  url = {https://github.com/eneskelestemur/prop_profiler},
  year = {2025}
}

If you use the pKa prediction functionality (Included in CNS-MPO calculation), please also cite the original MolGpKa work:

@article{pan2021molgpka,
  title={MolGpka: A Web Server for Small Molecule pKa Prediction Using a Graph-Convolutional Neural Network},
  author={Pan, Xiaolin and Wang, Hao and Li, Cuiyu and Zhang, John Z. H. and Ji, Changge},
  journal={Journal of Chemical Information and Modeling},
  volume={61},
  number={7},
  pages={3159--3165},
  year={2021},
  publisher={American Chemical Society},
  doi={10.1021/acs.jcim.1c00075}
}

If you use the CNS-MPO scoring functionality, please cite MolGpKa (above) along with the CNS-MPO paper:

@article{wager2016cns,
  title={Central Nervous System Multiparameter Optimization Desirability: Application in Drug Discovery},
  author={Wager, Travis T and Hou, Xinjun and Verhoest, Patrick R and Villalobos, Anabella},
  journal={ACS Chemical Neuroscience},
  volume={7},
  number={6},
  pages={767--775},
  year={2016},
  publisher={American Chemical Society},
  doi={10.1021/acschemneuro.6b00029}
}

If you use the Stoplight scoring functionality, please cite the original Stoplight paper:

@article{wellnitz2024stoplight,
  title={STOPLIGHT: A Hit Scoring Calculator},
  author={Wellnitz, James and Martin, Holli-Joi and Hossain, Mohammad Anwar and others},
  journal={Journal of Chemical Information and Modeling},
  volume={64},
  number={11},
  pages={4387--4391},
  year={2024},
  publisher={American Chemical Society},
  doi={10.1021/acs.jcim.4c00412}
}

Data Sources

The package uses the following datasets for training and evaluation:

• ESOL Dataset: Aqueous solubility dataset for training ESOL models (website)
• LogD Dataset: Distribution coefficient dataset for logD prediction (website)

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For questions and issues, please open an issue on the GitHub repository.