| Name | PETINA JSON |
| Version |
0.0.16
JSON |
| download |
| home_page | None |
| Summary | This library contains a collection of privacy preservation techniques. |
| upload_time | 2025-07-08 18:53:03 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | None |
| keywords |
federated learning
machine learning
privacy
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# PETINA: Privacy prEservaTIoN Algorithms
[](https://pypi.org/project/PETINA/)
[](https://pypi.org/project/PETINA/)
[](LICENSE)
[](https://pepy.tech/project/petina)
**PETINA** is a general-purpose Python library for Differential Privacy (DP), designed for flexibility, modularity, and extensibility across a wide range of ML and data processing pipelines. It supports both numerical and categorical data, with tools for supervised and unsupervised tasks.
## Features
PETINA includes state-of-the-art tools for:
### Differential Privacy Mechanisms
- Laplace, Gaussian, and Exponential Mechanisms
- Sparse Vector Technique (SVT)
- Percentile Mechanism
- Unary and Histogram Encoding
### Sketching Algorithms
- Count Sketch
- Fast Projection-Based Sketching
### Adaptive Privacy
- Adaptive Clipping
- Adaptive Pruning
### Utility Functions
- Convert between Python list, NumPy array, and PyTorch tensor
- Type casting and validation
- Compute privacy parameters (e.g., `p`, `q`, `gamma`, `sigma`) from ε
## Quick Start
Below is a real world example when adding noise to age of various person
```python
from PETINA import DP_Mechanisms, Encoding_Pertubation, Clipping, Pruning
import numpy as np
import random
# --- Real-world data: Users' ages from a survey ---
user_ages = [23, 35, 45, 27, 31, 50, 29, 42, 38, 33]
print("Original ages:", user_ages)
# --- DP parameters ---
sensitivity = 1 # Age changes by 1 at most for neighboring datasets
epsilon = 0.5 # Moderate privacy budget
delta = 1e-5
gamma = 0.001
# --- Add Laplace noise to ages ---
noisy_ages = DP_Mechanisms.applyDPLaplace(user_ages, sensitivity, epsilon)
print("\nNoisy ages with Laplace Mechanism:")
print(noisy_ages)
# --- Encode noisy ages using Unary Encoding ---
p = Encoding_Pertubation.get_p(epsilon)
q = Encoding_Pertubation.get_q(p, epsilon)
encoded_ages = Encoding_Pertubation.unaryEncoding(noisy_ages, p=p, q=q)
print("\nUnary encoded noisy ages:")
print(encoded_ages)
# --- Summary ---
print("\nSummary:")
print(f"Original ages: {user_ages}")
print(f"Noisy ages: {np.round(noisy_ages, 2)}")
#------OUTPUT------
# Original ages: [23, 35, 45, 27, 31, 50, 29, 42, 38, 33]
# Noisy ages with Laplace Mechanism:
# [21.46703958 34.93585449 47.36478841 25.68077936 30.11460444 49.3448666
# 28.8128474 36.54981691 37.6103979 33.32033856]
# Unary encoded noisy ages:
# [(33.320338556461415, np.float64(14.023220368761203)), (34.935854491045006, np.float64(5.97677963123879)), (36.54981690878978, np.float64(22.06966110628362)), (37.61039790139999, np.float64(-10.116101843806039)), (47.36478841495265, np.float64(-18.162542581328452)), (49.34486659855414, np.float64(14.023220368761203)), (21.467039579955127, np.float64(-18.162542581328452)), (25.6807793619914, np.float64(-2.069661106283625)), (28.812847396103876, np.float64(5.97677963123879)), (30.114604444236978, np.float64(-10.116101843806039))]
# Summary:
# Original ages: [23, 35, 45, 27, 31, 50, 29, 42, 38, 33]
# Noisy ages: [21.47 34.94 47.36 25.68 30.11 49.34 28.81 36.55 37.61 33.32]
```
We also provide hands-on [examples](./PETINA/examples/) in the examples folder.
- [Example 1](./PETINA/examples/tutorial1_basic.py): Basic PETINA Usage.
- [Example 2](./PETINA/examples/tutorial2_CountSketch_PureLDP.py): This example demonstrates how to perform frequency estimation on synthetic categorical data using various pure Local Differential Privacy (LDP) algorithms. It also compares PETINA's Count Mean Sketch (CMS) and CSVec-based sketching with baseline LDP methods and a centralized CMS variant.
- [Example 3](./PETINA/examples/tutorial3_Moment_Accounting.py): This script demonstrates differentially private training in PyTorch using PETINA with budget tracking, clipping, and noise injection.
- [Example 4](./PETINA/examples/tutorial4_csVec_implementation_PETINA.py): This script demonstrates how to apply PETINA's Count Sketch mechanism to lists, NumPy arrays, and PyTorch tensors for efficient data approximation.
- [Example 5](./PETINA/examples/tutorial5_PETINA_MA_Implement.py): This script runs a federated learning simulation with optional Laplace, Gaussian, or Count Sketch-based privacy mechanisms, integrated with PETINA's budget accountant to track and gracefully handle differential privacy budget consumption.
## Installation
- Install from PyPI
```bash
pip install PETINA
```
- Install from Source
```bash
git clone https://github.com/ORNL/PETINA.git
cd PETINA
pip install -e .
```
## Citing PETINA
If you use PETINA in your research, please cite the official DOE OSTI release:
> [https://www.osti.gov/doecode/biblio/149859](https://www.osti.gov/doecode/biblio/149859)
```bash
@misc{ doecode_149859,
title = {ORNL/PETINA},
author = {Kotevska, Ole and Nguyen, Duc},
abstractNote = {This is a library that has implementation of privacy preservation algorithms.},
}
```
## Contributors
- Oliver Kotevska – KOTEVSKAO@ORNL.GOV – Maintainer
- Trong Nguyen – NT9@ORNL.GOV – Developer
We welcome community contributions to PETINA.
For major changes, please open an issue first. For small fixes or enhancements, submit a pull request. Include/update tests where applicable.
Contact: KOTEVSKAO@ORNL.GOV
## License
This project is licensed under the MIT License.
## Acknowledgements
This material is based upon work supported by the U.S. Department of Energy, Office of Science, Office of Advanced Scientific Computing Research under Contract No. DE-AC05-00OR22725. This manuscript has been authored by UT-Battelle, LLC under Contract No. DE-AC05-00OR22725 with the U.S. Department of Energy. The United States Government retains and the publisher, by accepting the article for publication, acknowledges that the United States Government retains a non-exclusive, paid-up, irrevocable, world-wide license to publish or reproduce the published form of this manuscript, or allow others to do so, for United States Government purposes. The Department of Energy will provide public access to these results of federally sponsored research in accordance with the DOE Public Access Plan (http://energy.gov/downloads/doe-public-access-plan).
Raw data
{
"_id": null,
"home_page": null,
"name": "PETINA",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Olivera Kotevska <KOTEVSKAO@ORNL.GOV>",
"keywords": "federated learning, machine learning, privacy",
"author": null,
"author_email": "Olivera Kotevska <KOTEVSKAO@ORNL.GOV>",
"download_url": "https://files.pythonhosted.org/packages/e9/d6/3cbb040d6450f5302eb34c195b342cd1efba0fd99bf263f26031f2b54b4d/petina-0.0.16.tar.gz",
"platform": null,
"description": "\n\n# PETINA: Privacy prEservaTIoN Algorithms\n\n[](https://pypi.org/project/PETINA/)\n[](https://pypi.org/project/PETINA/)\n[](LICENSE)\n[](https://pepy.tech/project/petina)\n\n**PETINA** is a general-purpose Python library for Differential Privacy (DP), designed for flexibility, modularity, and extensibility across a wide range of ML and data processing pipelines. It supports both numerical and categorical data, with tools for supervised and unsupervised tasks.\n\n## Features\n\nPETINA includes state-of-the-art tools for:\n\n### Differential Privacy Mechanisms\n- Laplace, Gaussian, and Exponential Mechanisms\n- Sparse Vector Technique (SVT)\n- Percentile Mechanism\n- Unary and Histogram Encoding\n\n### Sketching Algorithms\n- Count Sketch\n- Fast Projection-Based Sketching\n\n### Adaptive Privacy\n- Adaptive Clipping\n- Adaptive Pruning\n\n### Utility Functions\n- Convert between Python list, NumPy array, and PyTorch tensor\n- Type casting and validation\n- Compute privacy parameters (e.g., `p`, `q`, `gamma`, `sigma`) from \u03b5\n\n## Quick Start\n\nBelow is a real world example when adding noise to age of various person\n```python\nfrom PETINA import DP_Mechanisms, Encoding_Pertubation, Clipping, Pruning\nimport numpy as np\nimport random\n\n# --- Real-world data: Users' ages from a survey ---\nuser_ages = [23, 35, 45, 27, 31, 50, 29, 42, 38, 33]\nprint(\"Original ages:\", user_ages)\n\n# --- DP parameters ---\nsensitivity = 1 # Age changes by 1 at most for neighboring datasets\nepsilon = 0.5 # Moderate privacy budget\ndelta = 1e-5\ngamma = 0.001\n\n# --- Add Laplace noise to ages ---\nnoisy_ages = DP_Mechanisms.applyDPLaplace(user_ages, sensitivity, epsilon)\nprint(\"\\nNoisy ages with Laplace Mechanism:\")\nprint(noisy_ages)\n\n# --- Encode noisy ages using Unary Encoding ---\np = Encoding_Pertubation.get_p(epsilon)\nq = Encoding_Pertubation.get_q(p, epsilon)\nencoded_ages = Encoding_Pertubation.unaryEncoding(noisy_ages, p=p, q=q)\nprint(\"\\nUnary encoded noisy ages:\")\nprint(encoded_ages)\n\n# --- Summary ---\nprint(\"\\nSummary:\")\nprint(f\"Original ages: {user_ages}\")\nprint(f\"Noisy ages: {np.round(noisy_ages, 2)}\")\n#------OUTPUT------\n# Original ages: [23, 35, 45, 27, 31, 50, 29, 42, 38, 33]\n\n# Noisy ages with Laplace Mechanism:\n# [21.46703958 34.93585449 47.36478841 25.68077936 30.11460444 49.3448666\n# 28.8128474 36.54981691 37.6103979 33.32033856]\n\n# Unary encoded noisy ages:\n# [(33.320338556461415, np.float64(14.023220368761203)), (34.935854491045006, np.float64(5.97677963123879)), (36.54981690878978, np.float64(22.06966110628362)), (37.61039790139999, np.float64(-10.116101843806039)), (47.36478841495265, np.float64(-18.162542581328452)), (49.34486659855414, np.float64(14.023220368761203)), (21.467039579955127, np.float64(-18.162542581328452)), (25.6807793619914, np.float64(-2.069661106283625)), (28.812847396103876, np.float64(5.97677963123879)), (30.114604444236978, np.float64(-10.116101843806039))]\n\n# Summary:\n# Original ages: [23, 35, 45, 27, 31, 50, 29, 42, 38, 33]\n# Noisy ages: [21.47 34.94 47.36 25.68 30.11 49.34 28.81 36.55 37.61 33.32]\n```\nWe also provide hands-on [examples](./PETINA/examples/) in the examples folder.\n\n- [Example 1](./PETINA/examples/tutorial1_basic.py): Basic PETINA Usage.\n- [Example 2](./PETINA/examples/tutorial2_CountSketch_PureLDP.py): This example demonstrates how to perform frequency estimation on synthetic categorical data using various pure Local Differential Privacy (LDP) algorithms. It also compares PETINA's Count Mean Sketch (CMS) and CSVec-based sketching with baseline LDP methods and a centralized CMS variant.\n- [Example 3](./PETINA/examples/tutorial3_Moment_Accounting.py): This script demonstrates differentially private training in PyTorch using PETINA with budget tracking, clipping, and noise injection.\n- [Example 4](./PETINA/examples/tutorial4_csVec_implementation_PETINA.py): This script demonstrates how to apply PETINA's Count Sketch mechanism to lists, NumPy arrays, and PyTorch tensors for efficient data approximation.\n- [Example 5](./PETINA/examples/tutorial5_PETINA_MA_Implement.py): This script runs a federated learning simulation with optional Laplace, Gaussian, or Count Sketch-based privacy mechanisms, integrated with PETINA's budget accountant to track and gracefully handle differential privacy budget consumption.\n## Installation\n- Install from PyPI\n```bash\npip install PETINA\n```\n- Install from Source\n```bash\ngit clone https://github.com/ORNL/PETINA.git\ncd PETINA\npip install -e .\n```\n## Citing PETINA\nIf you use PETINA in your research, please cite the official DOE OSTI release: \n> [https://www.osti.gov/doecode/biblio/149859](https://www.osti.gov/doecode/biblio/149859)\n```bash\n@misc{ doecode_149859,\n title = {ORNL/PETINA},\n author = {Kotevska, Ole and Nguyen, Duc},\n abstractNote = {This is a library that has implementation of privacy preservation algorithms.},\n}\n```\n## Contributors\n- Oliver Kotevska \u2013 KOTEVSKAO@ORNL.GOV \u2013 Maintainer\n- Trong Nguyen \u2013 NT9@ORNL.GOV \u2013 Developer\n\n\nWe welcome community contributions to PETINA.\n\nFor major changes, please open an issue first. For small fixes or enhancements, submit a pull request. Include/update tests where applicable.\n\nContact: KOTEVSKAO@ORNL.GOV\n\n## License\nThis project is licensed under the MIT License.\n\n## Acknowledgements\nThis material is based upon work supported by the U.S. Department of Energy, Office of Science, Office of Advanced Scientific Computing Research under Contract No. DE-AC05-00OR22725. This manuscript has been authored by UT-Battelle, LLC under Contract No. DE-AC05-00OR22725 with the U.S. Department of Energy. The United States Government retains and the publisher, by accepting the article for publication, acknowledges that the United States Government retains a non-exclusive, paid-up, irrevocable, world-wide license to publish or reproduce the published form of this manuscript, or allow others to do so, for United States Government purposes. The Department of Energy will provide public access to these results of federally sponsored research in accordance with the DOE Public Access Plan (http://energy.gov/downloads/doe-public-access-plan).\n\n",
"bugtrack_url": null,
"license": null,
"summary": "This library contains a collection of privacy preservation techniques.",
"version": "0.0.16",
"project_urls": {
"Homepage": "https://github.com/ORNL/PETINA",
"Repository": "https://github.com/ORNL/PETINA.git"
},
"split_keywords": [
"federated learning",
" machine learning",
" privacy"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "b69cd6ccab411341103583c9937aa8dce7bac531523a808f4a64d8acc32455b8",
"md5": "f6c03065415d1e8014dfa2dcad53c5d2",
"sha256": "abc8998d867ec791ba6e42607ec13a67d7473690afbb5777c2d025e8c4191786"
},
"downloads": -1,
"filename": "petina-0.0.16-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f6c03065415d1e8014dfa2dcad53c5d2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 64298,
"upload_time": "2025-07-08T18:53:00",
"upload_time_iso_8601": "2025-07-08T18:53:00.948758Z",
"url": "https://files.pythonhosted.org/packages/b6/9c/d6ccab411341103583c9937aa8dce7bac531523a808f4a64d8acc32455b8/petina-0.0.16-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e9d63cbb040d6450f5302eb34c195b342cd1efba0fd99bf263f26031f2b54b4d",
"md5": "fa4c76b7da97f47068fa40659b003837",
"sha256": "e0fb7a8fe2ae390758143300241795ed5efb7b24a67935521911e8a2cf73b3eb"
},
"downloads": -1,
"filename": "petina-0.0.16.tar.gz",
"has_sig": false,
"md5_digest": "fa4c76b7da97f47068fa40659b003837",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 49252,
"upload_time": "2025-07-08T18:53:03",
"upload_time_iso_8601": "2025-07-08T18:53:03.432260Z",
"url": "https://files.pythonhosted.org/packages/e9/d6/3cbb040d6450f5302eb34c195b342cd1efba0fd99bf263f26031f2b54b4d/petina-0.0.16.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-08 18:53:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ORNL",
"github_project": "PETINA",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "petina"
}
