An "UNOFFICIAL" comprehensive Python client for the EPISuite API with advanced DataFrame utilities for environmental chemistry and toxicology research.
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.
- 🔗 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
pip install pyepisuitegit clone https://github.com/USEtox/PyEPISuite.git
cd PyEPISuite
pip install -e .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)}")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=localWindows 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
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')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
cas = "50-00-0"
experimental_hlc = henry_data.HLC(cas)
experimental_solubility = solubility_data.solubility(cas)
# Compare with predictions
predicted_hlc = epi_df[epi_df['cas'] == cas]['henrys_law_constant_estimated'].iloc[0]
print(f"Predicted: {predicted_hlc}, Experimental: {experimental_hlc}")PyEPISuite provides access to 40+ environmental and physical-chemical properties:
- Log Kow, Melting Point, Boiling Point
- Vapor Pressure, Water Solubility, Henry's Law Constant
- Log Koa, Log Koc
- Atmospheric Half-life, Biodegradation Rates
- Aerosol Adsorption, Bioconcentration Factor
- Water Volatilization, Fugacity Model Results
- Acute and chronic toxicity predictions
- Fish, Daphnid, and Algae endpoints
- Multiple QSAR model classes
- Installation Guide
- Quick Start Tutorial
- Local Runtime Guide
- DataFrame Utilities Guide
- Data Analysis Examples
- API Reference
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
We welcome contributions! Please see our Contributing Guide for details.
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 checkingpip install -e ".[docs]"
mkdocs serve # Local documentation serverIf 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
This project is licensed under the MIT License - see the LICENSE file for details.
- EPA for providing the EPISuite and EcoSAR APIs
- The pandas development team for the excellent DataFrame library
- All contributors and users of the package
- ✨ 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.