PyEPISuite

An "UNOFFICIAL" comprehensive Python client for the EPISuite API with advanced DataFrame utilities for environmental chemistry and toxicology research.

Disclaimer

EPI Suite™ is a trademark of the U.S. Environmental Protection Agency. This project, i.e. PyEPISuite is an independent, unofficial interface and is not affiliated with or endorsed by the U.S. EPA. PyEPISuite is not created, endorsed, or sponsored by the U.S. EPA.

🚀 Key Features

• 🔗 Complete API Integration: Access EPA's EPISuite and EcoSAR models
• 📊 DataFrame Support: Convert results to pandas DataFrames for analysis
• 📈 Data Analysis Tools: Built-in statistical and visualization utilities
• 🧪 Experimental Data: Access curated experimental datasets for validation
• 📑 Excel Export: Multi-sheet export with customizable formatting
• 📚 Comprehensive Documentation: Detailed guides and examples

🛠️ Installation

Using pip (Recommended)

pip install pyepisuite

From Source

git clone https://github.com/USEtox/PyEPISuite.git
cd PyEPISuite
pip install -e .

📖 Quick Start

from pyepisuite import search_episuite_by_cas, submit_to_episuite
from pyepisuite.dataframe_utils import episuite_to_dataframe, ecosar_to_dataframe

# Search for chemicals
cas_list = ["50-00-0", "100-00-5", "100-02-7"]  
ids = search_episuite_by_cas(cas_list)

# Get predictions
epi_results, ecosar_results = submit_to_episuite(ids)

# Convert to DataFrames for analysis
epi_df = episuite_to_dataframe(epi_results)
ecosar_df = ecosar_to_dataframe(ecosar_results)

print(f"Retrieved data for {len(epi_df)} chemicals")
print(f"Properties available: {list(epi_df.columns)}")

🖥️ Local Runtime (Windows and Linux)

PyEPISuite now supports local-first operation with data/local/EpiSuiteCLI.jar.

• Default mode: auto (prefer local runtime when JAR is available)
• Force local: PYEPISUITE_MODE=local
• Force remote: PYEPISUITE_MODE=remote

Linux/macOS:

export PYEPISUITE_MODE=local

Windows PowerShell:

$env:PYEPISUITE_MODE = "local"

Python:

from pyepisuite import EpiSuiteAPIClient

client = EpiSuiteAPIClient()
hits = client.search("formaldehyde")
result = client.submit(cas="000050-00-0")

Detailed guide: docs/user-guide/local-mode.md

🧮 DataFrame Features

PyEPISuite provides powerful DataFrame utilities for data analysis:

from pyepisuite.dataframe_utils import (
    episuite_to_dataframe,
    ecosar_to_dataframe, 
    combine_episuite_ecosar_dataframes,
    export_to_excel,
    create_summary_statistics
)

# Convert API results to structured DataFrames
epi_df = episuite_to_dataframe(epi_results)          # 41 EPI Suite properties
ecosar_df = ecosar_to_dataframe(ecosar_results)      # 12 EcoSAR columns

# Combine datasets
combined_df = combine_episuite_ecosar_dataframes(epi_df, ecosar_df)

# Generate summary statistics
stats = create_summary_statistics(epi_df)

# Export to Excel with multiple sheets
export_to_excel({
    'EPI_Suite': epi_df,
    'EcoSAR': ecosar_df,
    'Statistics': stats
}, 'analysis_results.xlsx')

🧪 Experimental Data Integration

Access curated experimental datasets for model validation:

from pyepisuite.expdata import HenryData, SolubilityData

# Load experimental data
henry_data = HenryData()
solubility_data = SolubilityData()

# Get experimental values (the curated datasets use unpadded CAS)
cas = "50-00-0"
experimental_hlc = henry_data.HLC(cas)
experimental_solubility = solubility_data.solubility(cas)

# Compare with predictions. EPI Suite returns zero-padded CAS numbers
# ("000050-00-0"), so strip the padding before matching.
match = epi_df[epi_df['cas'].str.lstrip('0') == cas]
predicted_hlc = match['henrys_law_constant_estimated'].iloc[0]
print(f"Predicted: {predicted_hlc}, Experimental: {experimental_hlc['value']}")

📊 Available Properties

PyEPISuite provides access to 40+ environmental and physical-chemical properties:

Physical Properties

• Log Kow, Melting Point, Boiling Point
• Vapor Pressure, Water Solubility, Henry's Law Constant
• Log Koa, Log Koc

Environmental Fate

• Atmospheric Half-life, Biodegradation Rates
• Aerosol Adsorption, Bioconcentration Factor
• Water Volatilization, Fugacity Model Results

Ecotoxicity (via EcoSAR)

• Acute and chronic toxicity predictions
• Fish, Daphnid, and Algae endpoints
• Multiple QSAR model classes

📚 Documentation

• Installation Guide
• Quick Start Tutorial
• Local Runtime Guide
• DataFrame Utilities Guide
• Data Analysis Examples
• API Reference

🔬 Research Applications

PyEPISuite is ideal for:

• Environmental Risk Assessment: Screening chemicals for persistence, bioaccumulation, and toxicity
• QSAR Model Development: Large-scale property prediction and validation
• Regulatory Compliance: Generating data for chemical registration
• Academic Research: High-throughput environmental fate modeling
• Chemical Prioritization: Ranking chemicals by environmental concern

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Quick Links

• Contributing Guidelines
• Security Policy
• Code of Conduct
• Issue Templates
• Changelog

Development Setup

git clone https://github.com/your-username/PyEPISuite.git
cd PyEPISuite
pip install -e ".[dev]"
pytest  # Run tests
flake8 src tests  # Linting
mypy src  # Type checking

Documentation

pip install -e ".[docs]"
mkdocs serve  # Local documentation server

📝 Citation

If you use PyEPISuite in your research, please cite:

Eftekhari, A. A. (2024). PyEPISuite: A Python client for EPA's EPISuite API 
with DataFrame utilities. https://github.com/USEtox/PyEPISuite

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• EPA for providing the EPISuite and EcoSAR APIs
• The pandas development team for the excellent DataFrame library
• All contributors and users of the package

🆕 What's New in v0.1.0

• ✨ Complete DataFrame utilities for data manipulation
• 📊 Excel export functionality with multi-sheet support
• 🧮 Statistical analysis tools and summary functions
• 📚 Comprehensive documentation with MkDocs
• 🧪 Enhanced experimental data access
• 🔧 Improved API client with better error handling
• 📈 Advanced examples for data analysis workflows

API Reference: See EPISuite API Documentation for the underlying web service.