# PAD ML Workflow
A Python package for researchers to explore and analyze Paper Analytical Device (PAD) data, build machine learning models, and develop new analytical methods for pharmaceutical quality testing.
## About PADs
[Paper Analytical Devices (PADs)](https://padproject.nd.edu) are low-cost diagnostic tools designed to verify pharmaceutical authenticity in low-resource settings. When a dissolved drug sample is applied to a PAD card, it produces colorimetric patterns that can be analyzed to determine drug quality and composition.
This package provides programmatic access to PAD image data collected through the [PADReader mobile app](https://padproject.nd.edu) and enables researchers to:
- Explore historical PAD test data
- Apply and evaluate machine learning models
- Develop new analytical methods
- Build custom ML pipelines for PAD analysis
## Installation
```bash
pip install pad-analytics
```
Or install directly from GitHub:
```bash
pip install git+https://github.com/PaperAnalyticalDeviceND/pad-analytics.git
```
For development:
```bash
git clone https://github.com/PaperAnalyticalDeviceND/pad-analytics.git
cd pad-analytics
pip install -e .
```
### Debug Mode
By default, the package suppresses technical warnings for a cleaner user experience. To enable debug output:
```bash
PAD_DEBUG=1 python your_script.py
# or
export PAD_DEBUG=1
python -c "import pad_analytics as pad; pad.predict(19208, 18)"
```
**Note:** You may see `libpng error: Read Error` messages during prediction - these are harmless warnings from corrupted image data on the server side and do not affect the prediction results.
## Quick Start
```python
import pad_analytics as pad
# Explore available projects
projects = pad.get_projects()
print(f"Found {len(projects)} projects")
# Get PAD test cards from a specific project
cards = pad.get_project_cards("ChemoPADNNtraining2024")
# Analyze a specific PAD card
card_data = pad.get_card(card_id=19208)
print(f"Drug tested: {card_data['sample_name'].values[0]}")
print(f"Concentration: {card_data['quantity'].values[0]} %")
# Apply a pre-trained model
actual, prediction = pad.predict(card_id=19208, model_id=18)
```
## Key Features
### 1. Data Exploration
Access the complete PAD database through the [OAS-compliant API](https://pad.crc.nd.edu/openapi.json):
```python
# List all projects
projects = pad.get_projects()
# Get cards by various criteria
cards = pad.get_project_cards(12) # project id
card = pad.get_card(sample_id=65490) # sample id
# View available ML models
models = pad.get_models()
```
### 2. Model Application
Apply pre-trained models to PAD images:
```python
# Neural Network models (for classification)
actual, (drug_name, confidence, energy) = pad.predict(card_id=19208, model_id=16)
# PLS models (for concentration quantification)
actual_conc, predicted_conc = pad.predict(card_id=19208, model_id=18)
```
### 3. Visualization
Interactive widgets for Jupyter notebooks:
```python
# Display PAD card with metadata
pad.show_card(card_id=19208)
# Show prediction results
pad.show_prediction(card_id=19208, model_id=18)
# Display multiple cards grouped by drug type
cards_df = pad.get_project_cards("ChemoPADNNtraining2024")
pad.show_grouped_cards(cards_df, group_column='sample_name')
```
## Example Notebook
See [`notebooks/using_padml_package.ipynb`](notebooks/using_padml_package.ipynb) for a comprehensive example of:
- Exploring PAD projects and data
- Applying different model types
- Visualizing results
- Evaluating model performance
- Building custom analysis pipelines
## Research Applications
This package supports various research activities:
### For Chemistry Researchers
- Analyze PAD performance across different drug formulations
- Evaluate colorimetric response patterns
- Optimize PAD card designs
- Validate new analytical methods
### For Computer Science Researchers
- Develop new ML models for PAD analysis
- Compare algorithm performance (NN vs PLS vs custom)
- Implement novel image processing techniques
- Create ensemble methods for improved accuracy
## The PAD Workflow
1. **Sample Preparation**: Dissolve pharmaceutical sample
2. **Application**: Apply sample to PAD card
3. **Reaction**: Chemical indicators produce color patterns
4. **Imaging**: Capture with PADReader mobile app
5. **Analysis**: ML algorithms interpret patterns
6. **Results**: Determine drug identity and quality
This package focuses on steps 5-6, providing tools to analyze the collected images and develop better analytical methods.
## API Documentation
### Core Functions
| Function | Description | Returns |
|----------|-------------|---------|
| `get_projects()` | List all PAD projects | DataFrame of projects |
| `get_card(card_id)` | Get specific card data | Card metadata + image URL |
| `predict(card_id, model_id)` | Apply model to card | (actual, prediction) |
| `get_models()` | List available models | DataFrame of models |
| `show_card(card_id)` | Display card in notebook | Interactive widget |
### Model Types
**Neural Networks (TensorFlow Lite)**
- Purpose: Drug identification and multi-class classification
- Output: `(predicted_class, probability, energy_score)`
**PLS (Partial Least Squares)**
- Purpose: Concentration quantification
- Output: `predicted_concentration` (float)
## Requirements
- Python >= 3.8
- TensorFlow >= 2.13.0
- OpenCV-Python >= 4.5.0
- NumPy, Pandas, scikit-learn
- ipywidgets (for notebook visualizations)
## Contributing
We welcome contributions from both chemistry and computer science researchers! Please see our [Contributing Guide](CONTRIBUTING.md).
## Citation
If you use this package in your research, please cite:
```bibtex
@software{pad_analytics,
title = {PAD Analytics: Python Tools for Paper Analytical Device Research},
author = {Paper Analytical Device Project Team},
institution = {University of Notre Dame},
year = {2024},
url = {https://github.com/PaperAnalyticalDeviceND/pad-analytics}
}
```
## License
MIT License - see [LICENSE](LICENSE)
## Links
- [PAD Project Homepage](https://padproject.nd.edu)
- [PADReader Mobile App](https://padproject.nd.edu)
- [API Documentation](https://pad.crc.nd.edu/docs)
- [OpenAPI Specification](https://pad.crc.nd.edu/openapi.json)
- [GitHub Repository](https://github.com/PaperAnalyticalDeviceND/pad-analytics)
## Support
For questions about:
- PAD technology and chemistry: Visit [padproject.nd.edu](https://padproject.nd.edu)
- Package usage and ML models: Open an [issue on GitHub](https://github.com/PaperAnalyticalDeviceND/pad-analytics/issues)
- API access: Check the [API documentation](https://pad.crc.nd.edu/docs)
## Security Notice
**Note about Keras dependency**: This package uses Keras 2.14.0 which has a known security vulnerability (CVE-2024-55459) related to the `keras.utils.get_file()` function. However, **pad-analytics is not affected** because we do not use this function in our codebase.
If you are extending this package and need to download files programmatically:
- **DO NOT** use `keras.utils.get_file()` with untrusted URLs
- If you must use it, add security measures to validate any downloaded files
- Only download files from trusted sources
We plan to upgrade to Keras 3.8.0+ in a future release to eliminate this dependency concern. See [Issue #2](https://github.com/PaperAnalyticalDeviceND/pad-analytics/issues/2) for more details.
Raw data
{
"_id": null,
"home_page": "https://github.com/PaperAnalyticalDeviceND/pad-analytics",
"name": "pad-analytics",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "paper analytical device, PAD, colorimetric analysis, pharmaceutical quality, drug detection, machine learning, diagnostics",
"author": "Paper Analytical Device Project Team",
"author_email": "Priscila Saboia Moreira <pmoreira@nd.edu>",
"download_url": "https://files.pythonhosted.org/packages/d1/b5/a5b781c1551d7c79c19f9117bfcfe1c268787358e2b329ab67e916ac8509/pad_analytics-0.2.2.tar.gz",
"platform": null,
"description": "# PAD ML Workflow\n\nA Python package for researchers to explore and analyze Paper Analytical Device (PAD) data, build machine learning models, and develop new analytical methods for pharmaceutical quality testing.\n\n\n## About PADs\n\n[Paper Analytical Devices (PADs)](https://padproject.nd.edu) are low-cost diagnostic tools designed to verify pharmaceutical authenticity in low-resource settings. When a dissolved drug sample is applied to a PAD card, it produces colorimetric patterns that can be analyzed to determine drug quality and composition.\n\nThis package provides programmatic access to PAD image data collected through the [PADReader mobile app](https://padproject.nd.edu) and enables researchers to:\n- Explore historical PAD test data\n- Apply and evaluate machine learning models\n- Develop new analytical methods\n- Build custom ML pipelines for PAD analysis\n\n## Installation\n\n```bash\npip install pad-analytics\n```\n\nOr install directly from GitHub:\n```bash\npip install git+https://github.com/PaperAnalyticalDeviceND/pad-analytics.git\n```\n\nFor development:\n```bash\ngit clone https://github.com/PaperAnalyticalDeviceND/pad-analytics.git\ncd pad-analytics\npip install -e .\n```\n\n### Debug Mode\nBy default, the package suppresses technical warnings for a cleaner user experience. To enable debug output:\n\n```bash\nPAD_DEBUG=1 python your_script.py\n# or\nexport PAD_DEBUG=1\npython -c \"import pad_analytics as pad; pad.predict(19208, 18)\"\n```\n\n**Note:** You may see `libpng error: Read Error` messages during prediction - these are harmless warnings from corrupted image data on the server side and do not affect the prediction results.\n\n## Quick Start\n\n```python\nimport pad_analytics as pad\n\n# Explore available projects\nprojects = pad.get_projects()\nprint(f\"Found {len(projects)} projects\")\n\n# Get PAD test cards from a specific project\ncards = pad.get_project_cards(\"ChemoPADNNtraining2024\")\n\n# Analyze a specific PAD card\ncard_data = pad.get_card(card_id=19208)\nprint(f\"Drug tested: {card_data['sample_name'].values[0]}\")\nprint(f\"Concentration: {card_data['quantity'].values[0]} %\")\n\n# Apply a pre-trained model\nactual, prediction = pad.predict(card_id=19208, model_id=18)\n```\n\n## Key Features\n\n### 1. Data Exploration\nAccess the complete PAD database through the [OAS-compliant API](https://pad.crc.nd.edu/openapi.json):\n\n```python\n# List all projects\nprojects = pad.get_projects()\n\n# Get cards by various criteria\ncards = pad.get_project_cards(12) # project id\ncard = pad.get_card(sample_id=65490) # sample id\n\n# View available ML models\nmodels = pad.get_models()\n```\n\n### 2. Model Application\nApply pre-trained models to PAD images:\n\n```python\n# Neural Network models (for classification)\nactual, (drug_name, confidence, energy) = pad.predict(card_id=19208, model_id=16)\n\n# PLS models (for concentration quantification)\nactual_conc, predicted_conc = pad.predict(card_id=19208, model_id=18)\n\n```\n\n### 3. Visualization\nInteractive widgets for Jupyter notebooks:\n\n```python\n# Display PAD card with metadata\npad.show_card(card_id=19208)\n\n# Show prediction results\npad.show_prediction(card_id=19208, model_id=18)\n\n# Display multiple cards grouped by drug type\ncards_df = pad.get_project_cards(\"ChemoPADNNtraining2024\")\npad.show_grouped_cards(cards_df, group_column='sample_name')\n```\n\n\n## Example Notebook\n\nSee [`notebooks/using_padml_package.ipynb`](notebooks/using_padml_package.ipynb) for a comprehensive example of:\n- Exploring PAD projects and data\n- Applying different model types\n- Visualizing results\n- Evaluating model performance\n- Building custom analysis pipelines\n\n## Research Applications\n\nThis package supports various research activities:\n\n### For Chemistry Researchers\n- Analyze PAD performance across different drug formulations\n- Evaluate colorimetric response patterns\n- Optimize PAD card designs\n- Validate new analytical methods\n\n### For Computer Science Researchers \n- Develop new ML models for PAD analysis\n- Compare algorithm performance (NN vs PLS vs custom)\n- Implement novel image processing techniques\n- Create ensemble methods for improved accuracy\n\n## The PAD Workflow\n\n1. **Sample Preparation**: Dissolve pharmaceutical sample\n2. **Application**: Apply sample to PAD card\n3. **Reaction**: Chemical indicators produce color patterns\n4. **Imaging**: Capture with PADReader mobile app\n5. **Analysis**: ML algorithms interpret patterns\n6. **Results**: Determine drug identity and quality\n\nThis package focuses on steps 5-6, providing tools to analyze the collected images and develop better analytical methods.\n\n## API Documentation\n\n### Core Functions\n\n| Function | Description | Returns |\n|----------|-------------|---------|\n| `get_projects()` | List all PAD projects | DataFrame of projects |\n| `get_card(card_id)` | Get specific card data | Card metadata + image URL |\n| `predict(card_id, model_id)` | Apply model to card | (actual, prediction) |\n| `get_models()` | List available models | DataFrame of models |\n| `show_card(card_id)` | Display card in notebook | Interactive widget |\n\n### Model Types\n\n**Neural Networks (TensorFlow Lite)**\n- Purpose: Drug identification and multi-class classification\n- Output: `(predicted_class, probability, energy_score)`\n\n**PLS (Partial Least Squares)**\n- Purpose: Concentration quantification\n- Output: `predicted_concentration` (float)\n\n## Requirements\n\n- Python >= 3.8\n- TensorFlow >= 2.13.0\n- OpenCV-Python >= 4.5.0\n- NumPy, Pandas, scikit-learn\n- ipywidgets (for notebook visualizations)\n\n## Contributing\n\nWe welcome contributions from both chemistry and computer science researchers! Please see our [Contributing Guide](CONTRIBUTING.md).\n\n## Citation\n\nIf you use this package in your research, please cite:\n\n```bibtex\n@software{pad_analytics,\n title = {PAD Analytics: Python Tools for Paper Analytical Device Research},\n author = {Paper Analytical Device Project Team},\n institution = {University of Notre Dame},\n year = {2024},\n url = {https://github.com/PaperAnalyticalDeviceND/pad-analytics}\n}\n```\n\n## License\n\nMIT License - see [LICENSE](LICENSE)\n\n## Links\n\n- [PAD Project Homepage](https://padproject.nd.edu)\n- [PADReader Mobile App](https://padproject.nd.edu)\n- [API Documentation](https://pad.crc.nd.edu/docs)\n- [OpenAPI Specification](https://pad.crc.nd.edu/openapi.json)\n- [GitHub Repository](https://github.com/PaperAnalyticalDeviceND/pad-analytics)\n\n## Support\n\nFor questions about:\n- PAD technology and chemistry: Visit [padproject.nd.edu](https://padproject.nd.edu)\n- Package usage and ML models: Open an [issue on GitHub](https://github.com/PaperAnalyticalDeviceND/pad-analytics/issues)\n- API access: Check the [API documentation](https://pad.crc.nd.edu/docs)\n\n## Security Notice\n\n**Note about Keras dependency**: This package uses Keras 2.14.0 which has a known security vulnerability (CVE-2024-55459) related to the `keras.utils.get_file()` function. However, **pad-analytics is not affected** because we do not use this function in our codebase.\n\nIf you are extending this package and need to download files programmatically:\n- **DO NOT** use `keras.utils.get_file()` with untrusted URLs\n- If you must use it, add security measures to validate any downloaded files\n- Only download files from trusted sources\n\nWe plan to upgrade to Keras 3.8.0+ in a future release to eliminate this dependency concern. See [Issue #2](https://github.com/PaperAnalyticalDeviceND/pad-analytics/issues/2) for more details.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python tools for analyzing Paper Analytical Devices (PADs) to detect and quantify pharmaceutical compounds through colorimetric analysis",
"version": "0.2.2",
"project_urls": {
"Documentation": "https://pad.crc.nd.edu/docs",
"Homepage": "https://padproject.nd.edu",
"Issues": "https://github.com/PaperAnalyticalDeviceND/pad-analytics/issues",
"Repository": "https://github.com/PaperAnalyticalDeviceND/pad-analytics",
"Source Code": "https://github.com/PaperAnalyticalDeviceND/pad-analytics"
},
"split_keywords": [
"paper analytical device",
" pad",
" colorimetric analysis",
" pharmaceutical quality",
" drug detection",
" machine learning",
" diagnostics"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c90f8fc0c2cce2491999f10bccdc40073981757656d1527c66b0bb42c826e720",
"md5": "72e30d6fb7743b168f4ecca112d3fe4d",
"sha256": "9b5f0795baf84e3e59bdbe00e12e5dcc568001251add2eaf1421ff826f987b9b"
},
"downloads": -1,
"filename": "pad_analytics-0.2.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "72e30d6fb7743b168f4ecca112d3fe4d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 50343,
"upload_time": "2025-07-16T09:54:14",
"upload_time_iso_8601": "2025-07-16T09:54:14.858007Z",
"url": "https://files.pythonhosted.org/packages/c9/0f/8fc0c2cce2491999f10bccdc40073981757656d1527c66b0bb42c826e720/pad_analytics-0.2.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "d1b5a5b781c1551d7c79c19f9117bfcfe1c268787358e2b329ab67e916ac8509",
"md5": "fff298d821163fee4e56e5045d98bb94",
"sha256": "360563e601be3ad7a8466cc13fe2aafae67ce5910c1651e4256a8a2312c3fc1d"
},
"downloads": -1,
"filename": "pad_analytics-0.2.2.tar.gz",
"has_sig": false,
"md5_digest": "fff298d821163fee4e56e5045d98bb94",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 5273672,
"upload_time": "2025-07-16T09:54:16",
"upload_time_iso_8601": "2025-07-16T09:54:16.024349Z",
"url": "https://files.pythonhosted.org/packages/d1/b5/a5b781c1551d7c79c19f9117bfcfe1c268787358e2b329ab67e916ac8509/pad_analytics-0.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-16 09:54:16",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "PaperAnalyticalDeviceND",
"github_project": "pad-analytics",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "keras",
"specs": [
[
"==",
"2.14.0"
]
]
},
{
"name": "tensorflow",
"specs": [
[
"==",
"2.14.1"
]
]
},
{
"name": "pandas",
"specs": [
[
"==",
"2.2.2"
]
]
},
{
"name": "numpy",
"specs": [
[
"==",
"1.26.4"
]
]
},
{
"name": "scikit-learn",
"specs": [
[
"==",
"1.5.2"
]
]
},
{
"name": "matplotlib",
"specs": [
[
"==",
"3.8.4"
]
]
},
{
"name": "seaborn",
"specs": [
[
"==",
"0.13.2"
]
]
},
{
"name": "requests",
"specs": [
[
"==",
"2.32.2"
]
]
},
{
"name": "pillow",
"specs": [
[
"==",
"10.3.0"
]
]
},
{
"name": "opencv-python",
"specs": [
[
"==",
"4.10.0.84"
]
]
}
],
"lcname": "pad-analytics"
}
JSON
