# probkit
Toolkit for modifying probabilities and shaping curves.
## Features
- **Tunable sigmoid curves** - Transform distributions with controllable steepness/flatness
- **Probability modification** - Scale probabilities using ratios with proper mathematical behavior
- **Pure functional design** - Deterministic functions for precise control
- **Random sampling** - Convenient random versions for generating samples from curves
- **Zero dependencies** - Only uses Python standard library
- **Robust validation** - Input validation and comprehensive error handling
- **Well tested** - Thoroughly unit tested with edge case coverage
## Quick Start
### Deterministic Functions
```python
from probkit import ntsig, biased_curve, modified_probability
# Sigmoid-like curve through (0,0), (0.5,0.5), (1,1)
y = ntsig(k=0.5, x=0.3) # k controls steepness
# Custom curve between any two points
y = biased_curve(k=0.2, a=10, b=100, x=0.7) # From (0,10) to (1,100)
# Modify probability with a ratio
new_prob = modified_probability(0.3, 1.5) # Scale 30% by 1.5x
new_prob = modified_probability(0.3, 3, 2) # Scale 30% by ratio 3/2
```
### Random Sampling
```python
from probkit.sampling import rng, seed
# Optionally set seed for reproducible results
seed(42)
# Sample from curves with random x values
sample = rng.ntsig(k=0.5)
sample = rng.biased_curve(k=0.2, a=10, b=100)
# Generate multiple samples
samples = [rng.ntsig(0.3) for _ in range(1000)]
# Generate random values using the singleton RNG
random_val = rng.random() # Random float in [0,1)
choices = rng.choices(['a', 'b', 'c'], k=5) # All random.Random methods available
# Independent RNG instances for parallel work
fork1 = rng.fork() # Clone current state
spawn1 = rng.spawn(123) # Fresh RNG with seed 123
# Context managers that don't affect main RNG
with rng.forked() as r:
values = [r.ntsig(0.5) for _ in range(10)]
with rng.spawned(456) as r:
reproducible_values = [r.nthsig(0.3) for _ in range(10)]
```
## API Reference
### Curve Functions
- **`ntsig(k, x)`** - Normalized tunable sigmoid. Negative k is flat (logit-like), positive k is steep (sigmoid-like)
- **`nthsig(k, x)`** - Normalized tunable half-sigmoid. Negative k is convex, positive k is concave
- **`biased_curve(k, a, b, x)`** - Custom curve between points (0,a) and (1,b) with bias k
### Probability Functions
- **`modified_probability(k, a, b=None)`** - Scale probability by ratio `a` (or `a/b` if b provided) with proper saturation
### Random Sampling
- **`probkit.sampling.rng`** - Singleton RNG with all `random.Random` methods plus probkit helpers
- **`probkit.sampling.seed(value)`** - Set seed for the singleton RNG
- **`rng.ntsig(k)`** - Sample from ntsig with random x
- **`rng.nthsig(k)`** - Sample from nthsig with random x
- **`rng.biased_curve(k, a, b)`** - Sample from biased_curve with random x
- **`rng.fork()`** - Clone current RNG state into independent instance
- **`rng.spawn(seed)`** - Create fresh RNG instance with specified seed
- **`rng.forked()`** - Context manager yielding forked RNG (doesn't affect main state)
- **`rng.spawned(seed)`** - Context manager yielding spawned RNG (doesn't affect main state)
### Utilities
- **`clamp(val, min_val, max_val)`** - Constrain value to range
- **`transform_range(x, old_range, new_range)`** - Linear transformation between ranges
- **`effective_ratio(a, b)`** - Safe division with edge case handling
## Use Cases
- **Game development** - Procedural generation, difficulty curves, loot tables
- **Simulations** - Monte Carlo methods, statistical modeling
- **Data science** - Distribution transformation, probability weighting
- **Machine learning** - Custom activation functions, data preprocessing
## Install
Clone this repo or copy the `probkit` folder into your project. No external dependencies required.
```bash
# Example: install with pip from local folder
pip install .
```
## Testing
Run all tests with:
```bash
python -m unittest discover tests -v
```
## Deployment (notes for Taylor)
PyPI is set up to receive releases from the `main` branch or when tagged with `v*`. This is accomplished using PyPI OIDC and GitHub Actions.
Pushing to main will create a new dev release with automatic version bump.
Creating a `v*` tag will create a production release using that version number.
```bash
git tag v0.1.0 && git push --tags
```
## Contributing
Pull requests and suggestions welcome! Open an issue or PR on GitHub.
## License
MIT License. See LICENSE file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "probkit",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "probability, curves, sigmoid, mathematics, simulation, statistics",
"author": null,
"author_email": "Taylor Vance <mirrors.cities0w@icloud.com>",
"download_url": "https://files.pythonhosted.org/packages/a2/82/e20611d4e834debe64583d1102097c3e7e1a940881e900c9d6e406907495/probkit-0.2.1.tar.gz",
"platform": null,
"description": "# probkit\n\nToolkit for modifying probabilities and shaping curves.\n\n## Features\n- **Tunable sigmoid curves** - Transform distributions with controllable steepness/flatness\n- **Probability modification** - Scale probabilities using ratios with proper mathematical behavior\n- **Pure functional design** - Deterministic functions for precise control\n- **Random sampling** - Convenient random versions for generating samples from curves\n- **Zero dependencies** - Only uses Python standard library\n- **Robust validation** - Input validation and comprehensive error handling\n- **Well tested** - Thoroughly unit tested with edge case coverage\n\n## Quick Start\n\n### Deterministic Functions\n```python\nfrom probkit import ntsig, biased_curve, modified_probability\n\n# Sigmoid-like curve through (0,0), (0.5,0.5), (1,1)\ny = ntsig(k=0.5, x=0.3) # k controls steepness\n\n# Custom curve between any two points\ny = biased_curve(k=0.2, a=10, b=100, x=0.7) # From (0,10) to (1,100)\n\n# Modify probability with a ratio\nnew_prob = modified_probability(0.3, 1.5) # Scale 30% by 1.5x\nnew_prob = modified_probability(0.3, 3, 2) # Scale 30% by ratio 3/2\n```\n\n### Random Sampling\n```python\nfrom probkit.sampling import rng, seed\n\n# Optionally set seed for reproducible results\nseed(42)\n\n# Sample from curves with random x values\nsample = rng.ntsig(k=0.5)\nsample = rng.biased_curve(k=0.2, a=10, b=100)\n\n# Generate multiple samples\nsamples = [rng.ntsig(0.3) for _ in range(1000)]\n\n# Generate random values using the singleton RNG\nrandom_val = rng.random() # Random float in [0,1)\nchoices = rng.choices(['a', 'b', 'c'], k=5) # All random.Random methods available\n\n# Independent RNG instances for parallel work\nfork1 = rng.fork() # Clone current state\nspawn1 = rng.spawn(123) # Fresh RNG with seed 123\n\n# Context managers that don't affect main RNG\nwith rng.forked() as r:\n values = [r.ntsig(0.5) for _ in range(10)]\nwith rng.spawned(456) as r:\n reproducible_values = [r.nthsig(0.3) for _ in range(10)]\n```\n\n## API Reference\n\n### Curve Functions\n- **`ntsig(k, x)`** - Normalized tunable sigmoid. Negative k is flat (logit-like), positive k is steep (sigmoid-like)\n- **`nthsig(k, x)`** - Normalized tunable half-sigmoid. Negative k is convex, positive k is concave\n- **`biased_curve(k, a, b, x)`** - Custom curve between points (0,a) and (1,b) with bias k\n\n### Probability Functions \n- **`modified_probability(k, a, b=None)`** - Scale probability by ratio `a` (or `a/b` if b provided) with proper saturation\n\n### Random Sampling\n- **`probkit.sampling.rng`** - Singleton RNG with all `random.Random` methods plus probkit helpers\n- **`probkit.sampling.seed(value)`** - Set seed for the singleton RNG\n- **`rng.ntsig(k)`** - Sample from ntsig with random x\n- **`rng.nthsig(k)`** - Sample from nthsig with random x \n- **`rng.biased_curve(k, a, b)`** - Sample from biased_curve with random x\n- **`rng.fork()`** - Clone current RNG state into independent instance\n- **`rng.spawn(seed)`** - Create fresh RNG instance with specified seed\n- **`rng.forked()`** - Context manager yielding forked RNG (doesn't affect main state)\n- **`rng.spawned(seed)`** - Context manager yielding spawned RNG (doesn't affect main state)\n\n### Utilities\n- **`clamp(val, min_val, max_val)`** - Constrain value to range\n- **`transform_range(x, old_range, new_range)`** - Linear transformation between ranges\n- **`effective_ratio(a, b)`** - Safe division with edge case handling\n\n## Use Cases\n- **Game development** - Procedural generation, difficulty curves, loot tables\n- **Simulations** - Monte Carlo methods, statistical modeling \n- **Data science** - Distribution transformation, probability weighting\n- **Machine learning** - Custom activation functions, data preprocessing\n\n## Install\nClone this repo or copy the `probkit` folder into your project. No external dependencies required.\n\n```bash\n# Example: install with pip from local folder\npip install .\n```\n\n## Testing\nRun all tests with:\n```bash\npython -m unittest discover tests -v\n```\n\n## Deployment (notes for Taylor)\nPyPI is set up to receive releases from the `main` branch or when tagged with `v*`. This is accomplished using PyPI OIDC and GitHub Actions.\nPushing to main will create a new dev release with automatic version bump.\nCreating a `v*` tag will create a production release using that version number.\n```bash\ngit tag v0.1.0 && git push --tags\n```\n\n## Contributing\nPull requests and suggestions welcome! Open an issue or PR on GitHub.\n\n## License\nMIT License. See LICENSE file for details.\n",
"bugtrack_url": null,
"license": null,
"summary": "Toolkit for modifying probabilities and shaping curves.",
"version": "0.2.1",
"project_urls": {
"Homepage": "https://github.com/taylorvance/probkit",
"Issues": "https://github.com/taylorvance/probkit/issues",
"Repository": "https://github.com/taylorvance/probkit"
},
"split_keywords": [
"probability",
" curves",
" sigmoid",
" mathematics",
" simulation",
" statistics"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "5ac3431da232b107850bfe0d7fcf48115d5ca2ec8ca69233ce1ea680dc1910a4",
"md5": "2d5f0cd76191bf2b9565861580e2bc59",
"sha256": "18af718af9c199193ed1ce990a4c11060a8dc34a6af80d07d5ab544946c5df40"
},
"downloads": -1,
"filename": "probkit-0.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2d5f0cd76191bf2b9565861580e2bc59",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 7827,
"upload_time": "2025-08-22T16:25:59",
"upload_time_iso_8601": "2025-08-22T16:25:59.850475Z",
"url": "https://files.pythonhosted.org/packages/5a/c3/431da232b107850bfe0d7fcf48115d5ca2ec8ca69233ce1ea680dc1910a4/probkit-0.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "a282e20611d4e834debe64583d1102097c3e7e1a940881e900c9d6e406907495",
"md5": "b992ba05f88ea5696c74793ce55d214c",
"sha256": "5ddd88e92bee312c6f0630099bf2010bebfc8c6946e6fcad41b3de853c7ce621"
},
"downloads": -1,
"filename": "probkit-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "b992ba05f88ea5696c74793ce55d214c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 12088,
"upload_time": "2025-08-22T16:26:01",
"upload_time_iso_8601": "2025-08-22T16:26:01.255214Z",
"url": "https://files.pythonhosted.org/packages/a2/82/e20611d4e834debe64583d1102097c3e7e1a940881e900c9d6e406907495/probkit-0.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-22 16:26:01",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "taylorvance",
"github_project": "probkit",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "probkit"
}
JSON
