pad-analytics


Namepad-analytics JSON
Version 0.1.1 PyPI version JSON
download
home_pagehttps://github.com/PaperAnalyticalDeviceND/pad-analytics
SummaryPython tools for analyzing Paper Analytical Devices (PADs) to detect and quantify pharmaceutical compounds through colorimetric analysis
upload_time2025-07-08 13:18:12
maintainerNone
docs_urlNone
authorPaper Analytical Device Project Team
requires_python>=3.8
licenseMIT
keywords paper analytical device pad colorimetric analysis pharmaceutical quality drug detection machine learning diagnostics
VCS
bugtrack_url
requirements keras tensorflow pandas numpy scikit-learn matplotlib seaborn requests pillow opencv-python
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # 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(project_name="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(project_ids=12)
cards = pad.get_card_by_sample_id(65490)

# 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(project_name="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/1f/86/301bb54450df493a84eb021753fafe2523d6614cf1a14d1a4e46c25bdec0/pad_analytics-0.1.1.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(project_name=\"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(project_ids=12)\ncards = pad.get_card_by_sample_id(65490)\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(project_name=\"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.1.1",
    "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": "",
            "digests": {
                "blake2b_256": "89d34d2f31269ec4357f30bf3cdf750624fbe3424247a53c3975918ea7185bb1",
                "md5": "4d06f5a53c2e913edca722bdfd5b95c8",
                "sha256": "efd5d3e1acba5f574823ac91150a672fe4f57003dfdf84322d3a95f23327fa3b"
            },
            "downloads": -1,
            "filename": "pad_analytics-0.1.1-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "4d06f5a53c2e913edca722bdfd5b95c8",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.8",
            "size": 30800,
            "upload_time": "2025-07-08T13:18:11",
            "upload_time_iso_8601": "2025-07-08T13:18:11.545750Z",
            "url": "https://files.pythonhosted.org/packages/89/d3/4d2f31269ec4357f30bf3cdf750624fbe3424247a53c3975918ea7185bb1/pad_analytics-0.1.1-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "1f86301bb54450df493a84eb021753fafe2523d6614cf1a14d1a4e46c25bdec0",
                "md5": "7a52ce78c7ea694ea2e5a33a84906665",
                "sha256": "ccea9753299e6f5e17ae6dc1d9e3ebacc049f6f528a14ba078eb0403c2898600"
            },
            "downloads": -1,
            "filename": "pad_analytics-0.1.1.tar.gz",
            "has_sig": false,
            "md5_digest": "7a52ce78c7ea694ea2e5a33a84906665",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.8",
            "size": 5211447,
            "upload_time": "2025-07-08T13:18:12",
            "upload_time_iso_8601": "2025-07-08T13:18:12.960567Z",
            "url": "https://files.pythonhosted.org/packages/1f/86/301bb54450df493a84eb021753fafe2523d6614cf1a14d1a4e46c25bdec0/pad_analytics-0.1.1.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-07-08 13:18:12",
    "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"
}
        
Elapsed time: 2.14912s