Metadata-Version: 2.5
Name: pyepisuite
Version: 1.3.0
Summary: A comprehensive Python client for EPA's EPISuite API with DataFrame utilities for environmental chemistry research.
Project-URL: Homepage, https://github.com/USEtox/PyEPISuite
Project-URL: Documentation, https://usetox.github.io/PyEPISuite/
Project-URL: Repository, https://github.com/USEtox/PyEPISuite
Project-URL: Bug Tracker, https://github.com/USEtox/PyEPISuite/issues
Author-email: "Ali A. Eftekhari" <e.eftekhari@gmail.com>
License: MIT
License-File: LICENSE
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.12
Requires-Dist: dacite
Requires-Dist: openpyxl>=3.0.0
Requires-Dist: pandas>=1.5.0
Requires-Dist: requests
Requires-Dist: tqdm>=4.0.0
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: flake8>=6.0.0; extra == 'dev'
Requires-Dist: isort>=5.0.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.0.0; extra == 'docs'
Requires-Dist: mkdocs>=1.5.0; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.20.0; extra == 'docs'
Description-Content-Type: text/markdown

# PyEPISuite

[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Documentation](https://img.shields.io/badge/docs-mkdocs-green.svg)](https://usetox.github.io/PyEPISuite/)
[![CI Tests](https://github.com/usetox/PyEPISuite/workflows/Tests/badge.svg)](https://github.com/usetox/PyEPISuite/actions)
[![Code Quality](https://github.com/usetox/PyEPISuite/workflows/Tests/badge.svg)](https://github.com/usetox/PyEPISuite/actions)
[![codecov](https://codecov.io/gh/usetox/PyEPISuite/branch/main/graph/badge.svg)](https://codecov.io/gh/usetox/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)
```bash
pip install pyepisuite
```

### From Source
```bash
git clone https://github.com/USEtox/PyEPISuite.git
cd PyEPISuite
pip install -e .
```

## 📖 Quick Start

```python
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:

```bash
export PYEPISUITE_MODE=local
```

Windows PowerShell:

```powershell
$env:PYEPISUITE_MODE = "local"
```

Python:

```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:

```python
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:

```python
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](https://pyepisuite.readthedocs.io/getting-started/installation/)**
- **[Quick Start Tutorial](https://pyepisuite.readthedocs.io/getting-started/quickstart/)**
- **[Local Runtime Guide](https://pyepisuite.readthedocs.io/user-guide/local-mode/)**
- **[DataFrame Utilities Guide](https://pyepisuite.readthedocs.io/user-guide/dataframe-utils/)**
- **[Data Analysis Examples](https://pyepisuite.readthedocs.io/examples/data-analysis/)**
- **[API Reference](https://pyepisuite.readthedocs.io/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](CONTRIBUTING.md) for details.

### Quick Links
- [Contributing Guidelines](CONTRIBUTING.md)
- [Security Policy](SECURITY.md)
- [Code of Conduct](CODE_OF_CONDUCT.md)
- [Issue Templates](.github/ISSUE_TEMPLATE/)
- [Changelog](CHANGELOG.md)

### Development Setup
```bash
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
```bash
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](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](https://episuite.dev/EpiWebSuite/#/help/api) for the underlying web service.
