pyepisuite 1.0.1__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- pyepisuite-1.0.1/CHANGELOG.md +51 -0
- pyepisuite-1.0.1/LICENSE +21 -0
- pyepisuite-1.0.1/MANIFEST.in +7 -0
- pyepisuite-1.0.1/PKG-INFO +244 -0
- pyepisuite-1.0.1/README.md +203 -0
- pyepisuite-1.0.1/data/README.md +45 -0
- pyepisuite-1.0.1/data/bcfbaf/BCFWIN_DD_Source_Oct2008.xls +0 -0
- pyepisuite-1.0.1/data/bcfbaf/BCF_Ionic_Training_Data.xls +0 -0
- pyepisuite-1.0.1/data/bcfbaf/BCF_NonIonic_Regression_DataSet.xls +0 -0
- pyepisuite-1.0.1/data/bcfbaf/BCF_Validation_DataSet.xls +0 -0
- pyepisuite-1.0.1/data/bcfbaf/km training_testing sets.xls +0 -0
- pyepisuite-1.0.1/data/henrywin/Henry_PhysProp_Data.csv +1830 -0
- pyepisuite-1.0.1/data/henrywin/Henry_PhysProp_Data.xls +0 -0
- pyepisuite-1.0.1/data/henrywin/data_cleanup.ipynb +56 -0
- pyepisuite-1.0.1/data/kowwin/SrcKowData2.xls +0 -0
- pyepisuite-1.0.1/data/kowwin/SrcKowData2.xlsx +0 -0
- pyepisuite-1.0.1/data/kowwin/kow.csv +13346 -0
- pyepisuite-1.0.1/data/kowwin/kow_clean_up.ipynb +394 -0
- pyepisuite-1.0.1/data/kowwin/kow_zwitterionic.csv +124 -0
- pyepisuite-1.0.1/data/kowwin/params.csv +5 -0
- pyepisuite-1.0.1/data/mpbpvp/Boiling_Point_PhysChem.csv +6114 -0
- pyepisuite-1.0.1/data/mpbpvp/Boiling_Pt_TestSet.xls +0 -0
- pyepisuite-1.0.1/data/mpbpvp/Melting_Point_PhysChem.csv +11476 -0
- pyepisuite-1.0.1/data/mpbpvp/Melting_Pt_TestSet.xls +0 -0
- pyepisuite-1.0.1/data/mpbpvp/VaporPressure_TestSet.xls +0 -0
- pyepisuite-1.0.1/data/mpbpvp/Vapor_Pressure_PhysChem.csv +3038 -0
- pyepisuite-1.0.1/data/mpbpvp/data_cleanup.ipynb +320 -0
- pyepisuite-1.0.1/data/sample/result.json +1923 -0
- pyepisuite-1.0.1/data/sample/result_ecosar.json +180 -0
- pyepisuite-1.0.1/data/usetox3/AA_Model_substance_data_Default.xlsx +0 -0
- pyepisuite-1.0.1/data/usetox3/README.md +2 -0
- pyepisuite-1.0.1/data/waternt/README.md +1 -0
- pyepisuite-1.0.1/data/waternt/WaterFrag_EPA_Report.doc +0 -0
- pyepisuite-1.0.1/data/waternt/WaterFragmentDataFiles.xls +0 -0
- pyepisuite-1.0.1/data/wskowwin/README.md +1 -0
- pyepisuite-1.0.1/data/wskowwin/WskowwinDatasetDocument.doc +0 -0
- pyepisuite-1.0.1/data/wskowwin/WskowwinValidationDocument.doc +0 -0
- pyepisuite-1.0.1/data/wskowwin/compound_classification.csv +45 -0
- pyepisuite-1.0.1/data/wskowwin/data_cleanup.ipynb +390 -0
- pyepisuite-1.0.1/data/wskowwin/solubility_data.csv +1451 -0
- pyepisuite-1.0.1/data/wskowwin/solubility_data_clean.csv +1451 -0
- pyepisuite-1.0.1/pyproject.toml +66 -0
- pyepisuite-1.0.1/requirements.txt +8 -0
- pyepisuite-1.0.1/setup.cfg +8 -0
- pyepisuite-1.0.1/src/pyepisuite/__init__.py +31 -0
- pyepisuite-1.0.1/src/pyepisuite/api_client.py +81 -0
- pyepisuite-1.0.1/src/pyepisuite/dataframe_utils.py +431 -0
- pyepisuite-1.0.1/src/pyepisuite/expdata.py +157 -0
- pyepisuite-1.0.1/src/pyepisuite/models.py +980 -0
- pyepisuite-1.0.1/src/pyepisuite/usetox_input.py +627 -0
- pyepisuite-1.0.1/src/pyepisuite/utils.py +372 -0
- pyepisuite-1.0.1/src/pyepisuite.egg-info/PKG-INFO +244 -0
- pyepisuite-1.0.1/src/pyepisuite.egg-info/SOURCES.txt +97 -0
- pyepisuite-1.0.1/src/pyepisuite.egg-info/dependency_links.txt +1 -0
- pyepisuite-1.0.1/src/pyepisuite.egg-info/requires.txt +17 -0
- pyepisuite-1.0.1/src/pyepisuite.egg-info/top_level.txt +1 -0
- pyepisuite-1.0.1/tests/test_api_client.py +17 -0
- pyepisuite-1.0.1/tests/test_cache.py +246 -0
- pyepisuite-1.0.1/tests/test_dataframe_utils.py +361 -0
- pyepisuite-1.0.1/tests/test_expdata.py +198 -0
- pyepisuite-1.0.1/tests/test_usetox_input.py +222 -0
- pyepisuite-1.0.1/tests/test_utils.py +114 -0
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to this project will be documented in this file.
|
|
4
|
+
|
|
5
|
+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
|
|
6
|
+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
|
+
|
|
8
|
+
## [1.0.0] - 2025-08-29
|
|
9
|
+
|
|
10
|
+
### Added
|
|
11
|
+
- **Comprehensive DataFrame utilities** for converting EPI Suite and EcoSAR results to pandas DataFrames
|
|
12
|
+
- **45+ properties** extracted from EPI Suite results including:
|
|
13
|
+
- Chemical identification and classification
|
|
14
|
+
- Physical-chemical properties (Log Kow, melting/boiling points, solubility, etc.)
|
|
15
|
+
- Environmental fate (atmospheric half-life, biodegradation, bioconcentration)
|
|
16
|
+
- Detailed atmospheric chemistry (hydroxyl radical and ozone reaction rates)
|
|
17
|
+
- Bioconcentration with trophic level data
|
|
18
|
+
- Water volatilization parameters
|
|
19
|
+
- Dermal permeability coefficients
|
|
20
|
+
- Fugacity model persistence and compartment half-lives
|
|
21
|
+
- Sewage treatment removal efficiencies
|
|
22
|
+
- Hydrolysis rate constants
|
|
23
|
+
- **Excel export functionality** with multiple sheets and formatting
|
|
24
|
+
- **Summary statistics generation** for results analysis
|
|
25
|
+
- **Comprehensive MkDocs documentation** with API references and examples
|
|
26
|
+
- **GitHub Actions workflows** for automated testing and documentation deployment
|
|
27
|
+
- **Dependabot configuration** for automated dependency updates
|
|
28
|
+
- **Contributing guidelines**, security policy, and issue templates
|
|
29
|
+
- **Experimental data integration** for model validation
|
|
30
|
+
|
|
31
|
+
### Enhanced
|
|
32
|
+
- Updated package structure with improved organization
|
|
33
|
+
- Enhanced test coverage with comprehensive test cases
|
|
34
|
+
- Improved error handling and data validation
|
|
35
|
+
- Updated README with detailed usage examples and badges
|
|
36
|
+
|
|
37
|
+
### Infrastructure
|
|
38
|
+
- Complete CI/CD pipeline with GitHub Actions
|
|
39
|
+
- Documentation deployment to GitHub Pages
|
|
40
|
+
- Automated testing across multiple Python versions and operating systems
|
|
41
|
+
- Code quality checks with linting and type checking
|
|
42
|
+
|
|
43
|
+
## [0.1.0] - Initial Development
|
|
44
|
+
|
|
45
|
+
### Added
|
|
46
|
+
- Basic EPI Suite API client functionality
|
|
47
|
+
- Models for EPI Suite data structures
|
|
48
|
+
- Utility functions for common operations
|
|
49
|
+
- Experimental data handling capabilities
|
|
50
|
+
- Initial test suite
|
|
51
|
+
- Basic documentation
|
pyepisuite-1.0.1/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2024 USEtox
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,244 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: pyepisuite
|
|
3
|
+
Version: 1.0.1
|
|
4
|
+
Summary: A comprehensive Python client for EPA's EPISuite API with DataFrame utilities for environmental chemistry research.
|
|
5
|
+
Author-email: "Ali A. Eftekhari" <e.eftekhari@gmail.com>
|
|
6
|
+
License: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/USEtox/PyEPISuite
|
|
8
|
+
Project-URL: Documentation, https://usetox.github.io/PyEPISuite/
|
|
9
|
+
Project-URL: Repository, https://github.com/USEtox/PyEPISuite
|
|
10
|
+
Project-URL: Bug Tracker, https://github.com/USEtox/PyEPISuite/issues
|
|
11
|
+
Classifier: Development Status :: 5 - Production/Stable
|
|
12
|
+
Classifier: Intended Audience :: Science/Research
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: Topic :: Scientific/Engineering :: Chemistry
|
|
15
|
+
Classifier: Topic :: Scientific/Engineering :: Information Analysis
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
20
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
21
|
+
Classifier: Operating System :: OS Independent
|
|
22
|
+
Requires-Python: >=3.10
|
|
23
|
+
Description-Content-Type: text/markdown
|
|
24
|
+
License-File: LICENSE
|
|
25
|
+
Requires-Dist: requests
|
|
26
|
+
Requires-Dist: dacite
|
|
27
|
+
Requires-Dist: pandas>=1.5.0
|
|
28
|
+
Requires-Dist: openpyxl>=3.0.0
|
|
29
|
+
Provides-Extra: docs
|
|
30
|
+
Requires-Dist: mkdocs>=1.5.0; extra == "docs"
|
|
31
|
+
Requires-Dist: mkdocs-material>=9.0.0; extra == "docs"
|
|
32
|
+
Requires-Dist: mkdocstrings[python]>=0.20.0; extra == "docs"
|
|
33
|
+
Provides-Extra: dev
|
|
34
|
+
Requires-Dist: pytest>=7.0.0; extra == "dev"
|
|
35
|
+
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
|
|
36
|
+
Requires-Dist: black>=23.0.0; extra == "dev"
|
|
37
|
+
Requires-Dist: isort>=5.0.0; extra == "dev"
|
|
38
|
+
Requires-Dist: mypy>=1.0.0; extra == "dev"
|
|
39
|
+
Requires-Dist: flake8>=6.0.0; extra == "dev"
|
|
40
|
+
Dynamic: license-file
|
|
41
|
+
|
|
42
|
+
# PyEPISuite
|
|
43
|
+
|
|
44
|
+
[](https://www.python.org/downloads/)
|
|
45
|
+
[](https://opensource.org/licenses/MIT)
|
|
46
|
+
[](https://usetox.github.io/PyEPISuite/)
|
|
47
|
+
[](https://github.com/usetox/PyEPISuite/actions)
|
|
48
|
+
[](https://github.com/usetox/PyEPISuite/actions)
|
|
49
|
+
[](https://codecov.io/gh/usetox/PyEPISuite)
|
|
50
|
+
|
|
51
|
+
A comprehensive Python client for the EPISuite API with advanced DataFrame utilities for environmental chemistry and toxicology research.
|
|
52
|
+
|
|
53
|
+
## ๐ Key Features
|
|
54
|
+
|
|
55
|
+
- **๐ Complete API Integration**: Access EPA's EPISuite and EcoSAR models
|
|
56
|
+
- **๐ DataFrame Support**: Convert results to pandas DataFrames for analysis
|
|
57
|
+
- **๐ Data Analysis Tools**: Built-in statistical and visualization utilities
|
|
58
|
+
- **๐งช Experimental Data**: Access curated experimental datasets for validation
|
|
59
|
+
- **๐ Excel Export**: Multi-sheet export with customizable formatting
|
|
60
|
+
- **๐ Comprehensive Documentation**: Detailed guides and examples
|
|
61
|
+
|
|
62
|
+
## ๐ ๏ธ Installation
|
|
63
|
+
|
|
64
|
+
### Using pip (Recommended)
|
|
65
|
+
```bash
|
|
66
|
+
pip install pyepisuite
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
### From Source
|
|
70
|
+
```bash
|
|
71
|
+
git clone https://github.com/USEtox/PyEPISuite.git
|
|
72
|
+
cd PyEPISuite
|
|
73
|
+
pip install -e .
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
## ๐ Quick Start
|
|
77
|
+
|
|
78
|
+
```python
|
|
79
|
+
from pyepisuite import search_episuite_by_cas, submit_to_episuite
|
|
80
|
+
from pyepisuite.dataframe_utils import episuite_to_dataframe, ecosar_to_dataframe
|
|
81
|
+
|
|
82
|
+
# Search for chemicals
|
|
83
|
+
cas_list = ["50-00-0", "100-00-5", "100-02-7"]
|
|
84
|
+
ids = search_episuite_by_cas(cas_list)
|
|
85
|
+
|
|
86
|
+
# Get predictions
|
|
87
|
+
epi_results, ecosar_results = submit_to_episuite(ids)
|
|
88
|
+
|
|
89
|
+
# Convert to DataFrames for analysis
|
|
90
|
+
epi_df = episuite_to_dataframe(epi_results)
|
|
91
|
+
ecosar_df = ecosar_to_dataframe(ecosar_results)
|
|
92
|
+
|
|
93
|
+
print(f"Retrieved data for {len(epi_df)} chemicals")
|
|
94
|
+
print(f"Properties available: {list(epi_df.columns)}")
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
## ๐งฎ DataFrame Features
|
|
98
|
+
|
|
99
|
+
PyEPISuite provides powerful DataFrame utilities for data analysis:
|
|
100
|
+
|
|
101
|
+
```python
|
|
102
|
+
from pyepisuite.dataframe_utils import (
|
|
103
|
+
episuite_to_dataframe,
|
|
104
|
+
ecosar_to_dataframe,
|
|
105
|
+
combine_episuite_ecosar_dataframes,
|
|
106
|
+
export_to_excel,
|
|
107
|
+
create_summary_statistics
|
|
108
|
+
)
|
|
109
|
+
|
|
110
|
+
# Convert API results to structured DataFrames
|
|
111
|
+
epi_df = episuite_to_dataframe(epi_results) # 41 EPI Suite properties
|
|
112
|
+
ecosar_df = ecosar_to_dataframe(ecosar_results) # 12 EcoSAR columns
|
|
113
|
+
|
|
114
|
+
# Combine datasets
|
|
115
|
+
combined_df = combine_episuite_ecosar_dataframes(epi_df, ecosar_df)
|
|
116
|
+
|
|
117
|
+
# Generate summary statistics
|
|
118
|
+
stats = create_summary_statistics(epi_df)
|
|
119
|
+
|
|
120
|
+
# Export to Excel with multiple sheets
|
|
121
|
+
export_to_excel({
|
|
122
|
+
'EPI_Suite': epi_df,
|
|
123
|
+
'EcoSAR': ecosar_df,
|
|
124
|
+
'Statistics': stats
|
|
125
|
+
}, 'analysis_results.xlsx')
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
## ๐งช Experimental Data Integration
|
|
129
|
+
|
|
130
|
+
Access curated experimental datasets for model validation:
|
|
131
|
+
|
|
132
|
+
```python
|
|
133
|
+
from pyepisuite.expdata import HenryData, SolubilityData
|
|
134
|
+
|
|
135
|
+
# Load experimental data
|
|
136
|
+
henry_data = HenryData()
|
|
137
|
+
solubility_data = SolubilityData()
|
|
138
|
+
|
|
139
|
+
# Get experimental values
|
|
140
|
+
cas = "50-00-0"
|
|
141
|
+
experimental_hlc = henry_data.HLC(cas)
|
|
142
|
+
experimental_solubility = solubility_data.solubility(cas)
|
|
143
|
+
|
|
144
|
+
# Compare with predictions
|
|
145
|
+
predicted_hlc = epi_df[epi_df['cas'] == cas]['henrys_law_constant_estimated'].iloc[0]
|
|
146
|
+
print(f"Predicted: {predicted_hlc}, Experimental: {experimental_hlc}")
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
## ๐ Available Properties
|
|
150
|
+
|
|
151
|
+
PyEPISuite provides access to 40+ environmental and physical-chemical properties:
|
|
152
|
+
|
|
153
|
+
### Physical Properties
|
|
154
|
+
- Log Kow, Melting Point, Boiling Point
|
|
155
|
+
- Vapor Pressure, Water Solubility, Henry's Law Constant
|
|
156
|
+
- Log Koa, Log Koc
|
|
157
|
+
|
|
158
|
+
### Environmental Fate
|
|
159
|
+
- Atmospheric Half-life, Biodegradation Rates
|
|
160
|
+
- Aerosol Adsorption, Bioconcentration Factor
|
|
161
|
+
- Water Volatilization, Fugacity Model Results
|
|
162
|
+
|
|
163
|
+
### Ecotoxicity (via EcoSAR)
|
|
164
|
+
- Acute and chronic toxicity predictions
|
|
165
|
+
- Fish, Daphnid, and Algae endpoints
|
|
166
|
+
- Multiple QSAR model classes
|
|
167
|
+
|
|
168
|
+
## ๐ Documentation
|
|
169
|
+
|
|
170
|
+
- **[Installation Guide](https://pyepisuite.readthedocs.io/getting-started/installation/)**
|
|
171
|
+
- **[Quick Start Tutorial](https://pyepisuite.readthedocs.io/getting-started/quickstart/)**
|
|
172
|
+
- **[DataFrame Utilities Guide](https://pyepisuite.readthedocs.io/user-guide/dataframe-utils/)**
|
|
173
|
+
- **[Data Analysis Examples](https://pyepisuite.readthedocs.io/examples/data-analysis/)**
|
|
174
|
+
- **[API Reference](https://pyepisuite.readthedocs.io/api-reference/)**
|
|
175
|
+
|
|
176
|
+
## ๐ฌ Research Applications
|
|
177
|
+
|
|
178
|
+
PyEPISuite is ideal for:
|
|
179
|
+
|
|
180
|
+
- **Environmental Risk Assessment**: Screening chemicals for persistence, bioaccumulation, and toxicity
|
|
181
|
+
- **QSAR Model Development**: Large-scale property prediction and validation
|
|
182
|
+
- **Regulatory Compliance**: Generating data for chemical registration
|
|
183
|
+
- **Academic Research**: High-throughput environmental fate modeling
|
|
184
|
+
- **Chemical Prioritization**: Ranking chemicals by environmental concern
|
|
185
|
+
|
|
186
|
+
## ๐ค Contributing
|
|
187
|
+
|
|
188
|
+
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
|
|
189
|
+
|
|
190
|
+
### Quick Links
|
|
191
|
+
- [Contributing Guidelines](CONTRIBUTING.md)
|
|
192
|
+
- [Security Policy](SECURITY.md)
|
|
193
|
+
- [Code of Conduct](CODE_OF_CONDUCT.md)
|
|
194
|
+
- [Issue Templates](.github/ISSUE_TEMPLATE/)
|
|
195
|
+
- [Changelog](CHANGELOG.md)
|
|
196
|
+
|
|
197
|
+
### Development Setup
|
|
198
|
+
```bash
|
|
199
|
+
git clone https://github.com/your-username/PyEPISuite.git
|
|
200
|
+
cd PyEPISuite
|
|
201
|
+
pip install -e ".[dev]"
|
|
202
|
+
pytest # Run tests
|
|
203
|
+
flake8 src tests # Linting
|
|
204
|
+
mypy src # Type checking
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
### Documentation
|
|
208
|
+
```bash
|
|
209
|
+
pip install -e ".[docs]"
|
|
210
|
+
mkdocs serve # Local documentation server
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
## ๐ Citation
|
|
214
|
+
|
|
215
|
+
If you use PyEPISuite in your research, please cite:
|
|
216
|
+
|
|
217
|
+
```
|
|
218
|
+
Eftekhari, A. A. (2024). PyEPISuite: A Python client for EPA's EPISuite API
|
|
219
|
+
with DataFrame utilities. https://github.com/USEtox/PyEPISuite
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
## ๐ License
|
|
223
|
+
|
|
224
|
+
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
|
|
225
|
+
|
|
226
|
+
## ๐ Acknowledgments
|
|
227
|
+
|
|
228
|
+
- EPA for providing the EPISuite and EcoSAR APIs
|
|
229
|
+
- The pandas development team for the excellent DataFrame library
|
|
230
|
+
- All contributors and users of the package
|
|
231
|
+
|
|
232
|
+
## ๐ What's New in v0.1.0
|
|
233
|
+
|
|
234
|
+
- โจ **Complete DataFrame utilities** for data manipulation
|
|
235
|
+
- ๐ **Excel export functionality** with multi-sheet support
|
|
236
|
+
- ๐งฎ **Statistical analysis tools** and summary functions
|
|
237
|
+
- ๐ **Comprehensive documentation** with MkDocs
|
|
238
|
+
- ๐งช **Enhanced experimental data** access
|
|
239
|
+
- ๐ง **Improved API client** with better error handling
|
|
240
|
+
- ๐ **Advanced examples** for data analysis workflows
|
|
241
|
+
|
|
242
|
+
---
|
|
243
|
+
|
|
244
|
+
**API Reference**: See [EPISuite API Documentation](https://episuite.dev/EpiWebSuite/#/help/api) for the underlying web service.
|
|
@@ -0,0 +1,203 @@
|
|
|
1
|
+
# PyEPISuite
|
|
2
|
+
|
|
3
|
+
[](https://www.python.org/downloads/)
|
|
4
|
+
[](https://opensource.org/licenses/MIT)
|
|
5
|
+
[](https://usetox.github.io/PyEPISuite/)
|
|
6
|
+
[](https://github.com/usetox/PyEPISuite/actions)
|
|
7
|
+
[](https://github.com/usetox/PyEPISuite/actions)
|
|
8
|
+
[](https://codecov.io/gh/usetox/PyEPISuite)
|
|
9
|
+
|
|
10
|
+
A comprehensive Python client for the EPISuite API with advanced DataFrame utilities for environmental chemistry and toxicology research.
|
|
11
|
+
|
|
12
|
+
## ๐ Key Features
|
|
13
|
+
|
|
14
|
+
- **๐ Complete API Integration**: Access EPA's EPISuite and EcoSAR models
|
|
15
|
+
- **๐ DataFrame Support**: Convert results to pandas DataFrames for analysis
|
|
16
|
+
- **๐ Data Analysis Tools**: Built-in statistical and visualization utilities
|
|
17
|
+
- **๐งช Experimental Data**: Access curated experimental datasets for validation
|
|
18
|
+
- **๐ Excel Export**: Multi-sheet export with customizable formatting
|
|
19
|
+
- **๐ Comprehensive Documentation**: Detailed guides and examples
|
|
20
|
+
|
|
21
|
+
## ๐ ๏ธ Installation
|
|
22
|
+
|
|
23
|
+
### Using pip (Recommended)
|
|
24
|
+
```bash
|
|
25
|
+
pip install pyepisuite
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
### From Source
|
|
29
|
+
```bash
|
|
30
|
+
git clone https://github.com/USEtox/PyEPISuite.git
|
|
31
|
+
cd PyEPISuite
|
|
32
|
+
pip install -e .
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
## ๐ Quick Start
|
|
36
|
+
|
|
37
|
+
```python
|
|
38
|
+
from pyepisuite import search_episuite_by_cas, submit_to_episuite
|
|
39
|
+
from pyepisuite.dataframe_utils import episuite_to_dataframe, ecosar_to_dataframe
|
|
40
|
+
|
|
41
|
+
# Search for chemicals
|
|
42
|
+
cas_list = ["50-00-0", "100-00-5", "100-02-7"]
|
|
43
|
+
ids = search_episuite_by_cas(cas_list)
|
|
44
|
+
|
|
45
|
+
# Get predictions
|
|
46
|
+
epi_results, ecosar_results = submit_to_episuite(ids)
|
|
47
|
+
|
|
48
|
+
# Convert to DataFrames for analysis
|
|
49
|
+
epi_df = episuite_to_dataframe(epi_results)
|
|
50
|
+
ecosar_df = ecosar_to_dataframe(ecosar_results)
|
|
51
|
+
|
|
52
|
+
print(f"Retrieved data for {len(epi_df)} chemicals")
|
|
53
|
+
print(f"Properties available: {list(epi_df.columns)}")
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
## ๐งฎ DataFrame Features
|
|
57
|
+
|
|
58
|
+
PyEPISuite provides powerful DataFrame utilities for data analysis:
|
|
59
|
+
|
|
60
|
+
```python
|
|
61
|
+
from pyepisuite.dataframe_utils import (
|
|
62
|
+
episuite_to_dataframe,
|
|
63
|
+
ecosar_to_dataframe,
|
|
64
|
+
combine_episuite_ecosar_dataframes,
|
|
65
|
+
export_to_excel,
|
|
66
|
+
create_summary_statistics
|
|
67
|
+
)
|
|
68
|
+
|
|
69
|
+
# Convert API results to structured DataFrames
|
|
70
|
+
epi_df = episuite_to_dataframe(epi_results) # 41 EPI Suite properties
|
|
71
|
+
ecosar_df = ecosar_to_dataframe(ecosar_results) # 12 EcoSAR columns
|
|
72
|
+
|
|
73
|
+
# Combine datasets
|
|
74
|
+
combined_df = combine_episuite_ecosar_dataframes(epi_df, ecosar_df)
|
|
75
|
+
|
|
76
|
+
# Generate summary statistics
|
|
77
|
+
stats = create_summary_statistics(epi_df)
|
|
78
|
+
|
|
79
|
+
# Export to Excel with multiple sheets
|
|
80
|
+
export_to_excel({
|
|
81
|
+
'EPI_Suite': epi_df,
|
|
82
|
+
'EcoSAR': ecosar_df,
|
|
83
|
+
'Statistics': stats
|
|
84
|
+
}, 'analysis_results.xlsx')
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
## ๐งช Experimental Data Integration
|
|
88
|
+
|
|
89
|
+
Access curated experimental datasets for model validation:
|
|
90
|
+
|
|
91
|
+
```python
|
|
92
|
+
from pyepisuite.expdata import HenryData, SolubilityData
|
|
93
|
+
|
|
94
|
+
# Load experimental data
|
|
95
|
+
henry_data = HenryData()
|
|
96
|
+
solubility_data = SolubilityData()
|
|
97
|
+
|
|
98
|
+
# Get experimental values
|
|
99
|
+
cas = "50-00-0"
|
|
100
|
+
experimental_hlc = henry_data.HLC(cas)
|
|
101
|
+
experimental_solubility = solubility_data.solubility(cas)
|
|
102
|
+
|
|
103
|
+
# Compare with predictions
|
|
104
|
+
predicted_hlc = epi_df[epi_df['cas'] == cas]['henrys_law_constant_estimated'].iloc[0]
|
|
105
|
+
print(f"Predicted: {predicted_hlc}, Experimental: {experimental_hlc}")
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
## ๐ Available Properties
|
|
109
|
+
|
|
110
|
+
PyEPISuite provides access to 40+ environmental and physical-chemical properties:
|
|
111
|
+
|
|
112
|
+
### Physical Properties
|
|
113
|
+
- Log Kow, Melting Point, Boiling Point
|
|
114
|
+
- Vapor Pressure, Water Solubility, Henry's Law Constant
|
|
115
|
+
- Log Koa, Log Koc
|
|
116
|
+
|
|
117
|
+
### Environmental Fate
|
|
118
|
+
- Atmospheric Half-life, Biodegradation Rates
|
|
119
|
+
- Aerosol Adsorption, Bioconcentration Factor
|
|
120
|
+
- Water Volatilization, Fugacity Model Results
|
|
121
|
+
|
|
122
|
+
### Ecotoxicity (via EcoSAR)
|
|
123
|
+
- Acute and chronic toxicity predictions
|
|
124
|
+
- Fish, Daphnid, and Algae endpoints
|
|
125
|
+
- Multiple QSAR model classes
|
|
126
|
+
|
|
127
|
+
## ๐ Documentation
|
|
128
|
+
|
|
129
|
+
- **[Installation Guide](https://pyepisuite.readthedocs.io/getting-started/installation/)**
|
|
130
|
+
- **[Quick Start Tutorial](https://pyepisuite.readthedocs.io/getting-started/quickstart/)**
|
|
131
|
+
- **[DataFrame Utilities Guide](https://pyepisuite.readthedocs.io/user-guide/dataframe-utils/)**
|
|
132
|
+
- **[Data Analysis Examples](https://pyepisuite.readthedocs.io/examples/data-analysis/)**
|
|
133
|
+
- **[API Reference](https://pyepisuite.readthedocs.io/api-reference/)**
|
|
134
|
+
|
|
135
|
+
## ๐ฌ Research Applications
|
|
136
|
+
|
|
137
|
+
PyEPISuite is ideal for:
|
|
138
|
+
|
|
139
|
+
- **Environmental Risk Assessment**: Screening chemicals for persistence, bioaccumulation, and toxicity
|
|
140
|
+
- **QSAR Model Development**: Large-scale property prediction and validation
|
|
141
|
+
- **Regulatory Compliance**: Generating data for chemical registration
|
|
142
|
+
- **Academic Research**: High-throughput environmental fate modeling
|
|
143
|
+
- **Chemical Prioritization**: Ranking chemicals by environmental concern
|
|
144
|
+
|
|
145
|
+
## ๐ค Contributing
|
|
146
|
+
|
|
147
|
+
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
|
|
148
|
+
|
|
149
|
+
### Quick Links
|
|
150
|
+
- [Contributing Guidelines](CONTRIBUTING.md)
|
|
151
|
+
- [Security Policy](SECURITY.md)
|
|
152
|
+
- [Code of Conduct](CODE_OF_CONDUCT.md)
|
|
153
|
+
- [Issue Templates](.github/ISSUE_TEMPLATE/)
|
|
154
|
+
- [Changelog](CHANGELOG.md)
|
|
155
|
+
|
|
156
|
+
### Development Setup
|
|
157
|
+
```bash
|
|
158
|
+
git clone https://github.com/your-username/PyEPISuite.git
|
|
159
|
+
cd PyEPISuite
|
|
160
|
+
pip install -e ".[dev]"
|
|
161
|
+
pytest # Run tests
|
|
162
|
+
flake8 src tests # Linting
|
|
163
|
+
mypy src # Type checking
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
### Documentation
|
|
167
|
+
```bash
|
|
168
|
+
pip install -e ".[docs]"
|
|
169
|
+
mkdocs serve # Local documentation server
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
## ๐ Citation
|
|
173
|
+
|
|
174
|
+
If you use PyEPISuite in your research, please cite:
|
|
175
|
+
|
|
176
|
+
```
|
|
177
|
+
Eftekhari, A. A. (2024). PyEPISuite: A Python client for EPA's EPISuite API
|
|
178
|
+
with DataFrame utilities. https://github.com/USEtox/PyEPISuite
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
## ๐ License
|
|
182
|
+
|
|
183
|
+
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
|
|
184
|
+
|
|
185
|
+
## ๐ Acknowledgments
|
|
186
|
+
|
|
187
|
+
- EPA for providing the EPISuite and EcoSAR APIs
|
|
188
|
+
- The pandas development team for the excellent DataFrame library
|
|
189
|
+
- All contributors and users of the package
|
|
190
|
+
|
|
191
|
+
## ๐ What's New in v0.1.0
|
|
192
|
+
|
|
193
|
+
- โจ **Complete DataFrame utilities** for data manipulation
|
|
194
|
+
- ๐ **Excel export functionality** with multi-sheet support
|
|
195
|
+
- ๐งฎ **Statistical analysis tools** and summary functions
|
|
196
|
+
- ๐ **Comprehensive documentation** with MkDocs
|
|
197
|
+
- ๐งช **Enhanced experimental data** access
|
|
198
|
+
- ๐ง **Improved API client** with better error handling
|
|
199
|
+
- ๐ **Advanced examples** for data analysis workflows
|
|
200
|
+
|
|
201
|
+
---
|
|
202
|
+
|
|
203
|
+
**API Reference**: See [EPISuite API Documentation](https://episuite.dev/EpiWebSuite/#/help/api) for the underlying web service.
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
# Experimental data
|
|
2
|
+
The experimental data used to train EPI Suite models are available [here](https://episuite.dev/EpiWebSuite/#/help/associated-databases). We provide an interface to access the data directly within the package. Here's a quote from the EPI Suite website:
|
|
3
|
+
> The EPIUnified database holds the combined values from: PhysProp and the available EPI Suiteโข model Training and Validation sets.
|
|
4
|
+
The data sets available are:
|
|
5
|
+
**WSKOWWIN**: WSKOWWIN Program Methodology & Validation Documents (includes Training & Validation datasets)
|
|
6
|
+
**WaterFragmentDataFiles**: WATERNT (Water Solubility Fragment) Program Methodology & Validation Documents (includes Training & Validation datasets) BioHCwin - estimates biodegradation of hydrocarbons
|
|
7
|
+
**MP-BP-VP-TestSets**: MPBPWIN (Melting Pt, Boiling Pt, Vapor Pressure) Program Test Sets
|
|
8
|
+
**Data_for_BCFBAF**: BCFBAF Excel spreadsheets of BCF and kM data used in training & validation (includes the Jon Arnot Source BCF DB with multiple BCF values)
|
|
9
|
+
**HENRYWIN_Data_EPI**: HENRYWIN Data files used in training & validation (includes Meylan and Howard (1991) Data document)
|
|
10
|
+
|
|
11
|
+
# Headers
|
|
12
|
+
CAS - Chemical Abstract Service Registry number (the few numbers below 000050-00-0 are not real CAS numbers, but used to designate compounds with no CAS number or an unknown CAS number; these designated numbers can be retrieved from the SRC SMILECAS database).
|
|
13
|
+
|
|
14
|
+
CLASS - An arbitrary classification of compounds by structure. Many compounds overlap individual classes. In general, compounds that are drugs or pesticides are assigned to those classes. Anilines were given precedence over phenols which were given precedence over nitrobenzenes, etc. The class numbers are as follows:
|
|
15
|
+
1. Alkanes 24. Haloalcohols, aliphatic
|
|
16
|
+
2. Haloalkanes 25. Nitriles
|
|
17
|
+
3. Alkenes 26. Misc Nitrogens
|
|
18
|
+
4. Haloalkenes 27. Pyridines
|
|
19
|
+
5. Alkynes 30. Drugs
|
|
20
|
+
6. Ethers, aliphatic 31. Dyes
|
|
21
|
+
7. Nitroso 32. Steroids
|
|
22
|
+
8. Pesticides 34. Amino acids
|
|
23
|
+
9. Biphenyls 35. Misc Aromatics
|
|
24
|
+
10. PAHs 37. Thioureas
|
|
25
|
+
11. Alkyl Benzenes 38. Multiply aliphatic -OH
|
|
26
|
+
12. Halobenzenes 40. Misc. Sulfur
|
|
27
|
+
13. Misc. Benzenes 41. Phosphorus
|
|
28
|
+
14. Amines, aliphatic 42. Naphthalenes
|
|
29
|
+
15. Anilines 43. Cholic acids
|
|
30
|
+
16. Phenols 44. Dioxins & Benzofurans
|
|
31
|
+
17. Acids, aliphatic 45. Nitrobenzenes
|
|
32
|
+
18. Acids, aromatic 47. Amides
|
|
33
|
+
19. Alcohols, aliphatic 48. Ureas
|
|
34
|
+
20. Aldehydes 49. Nitro, aliphatic
|
|
35
|
+
21. Esters 50. Aromatic sulfonamides
|
|
36
|
+
22. Ketones 51. Glycolamide esters
|
|
37
|
+
23. Epoxides
|
|
38
|
+
|
|
39
|
+
LOGP - measured log Kow value
|
|
40
|
+
LOGMOLAR - logarithm of the measured water solubility in molar units
|
|
41
|
+
ESTIMATE - water solubility estimate (in molar units) using equation 20
|
|
42
|
+
ERROR - the difference between LOGMOLAR and ESTIMATE
|
|
43
|
+
WSOL - the measured water solubility in units of mg/L
|
|
44
|
+
MP - the melting point in oC; "Liq" refers to liquids (MP < 25oC)
|
|
45
|
+
MOLWT - the molecular weight of the compound
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|