pso-segmentation 0.1.0__tar.gz

pso_segmentation-0.1.0/.github/ci.yml

@@ -0,0 +1,37 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+      - master
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install package and dev dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Lint
+        run: |
+          ruff check .
+          ruff format --check .
+
+      - name: Type check
+        run: mypy src/
+
+      - name: Test
+        run: pytest

pso_segmentation-0.1.0/.gitignore

@@ -0,0 +1,141 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+docs/build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+Pipfile.lock
+
+# PEP 582
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Project specific
+.readthedocs.yml
+
+# Specs and documentation drafts
+specs/
+
+#old notebooks
+notebooks/old/

pso_segmentation-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,143 @@
+# Contributing to pso-segmentation
+
+Thank you for your interest in contributing! We welcome contributions from the community.
+
+## Code of Conduct
+
+This project adheres to a code of conduct. By participating, you are expected to uphold this code.
+
+## Getting Started
+
+### Prerequisites
+
+- Python 3.12 or higher
+- Git
+
+### Development Setup
+
+1. Fork the repository
+2. Clone your fork:
+   ```bash
+   git clone <repository-url>
+   cd pso-segmentation
+   ```
+3. Create a virtual environment:
+   ```bash
+   python -m venv venv
+   source venv/bin/activate  # On Windows: venv\Scripts\activate
+   ```
+4. Install in development mode with all dependencies:
+   ```bash
+   pip install -e ".[all]"
+   ```
+
+## Making Changes
+
+### Code Style
+
+We use strict code quality standards:
+
+- **Formatting**: `ruff format` (enforced)
+- **Linting**: `ruff check` (enforced)
+- **Type Checking**: `mypy --strict` (enforced)
+
+Before committing, run:
+
+```bash
+ruff format .
+ruff check .
+mypy src/
+pytest
+```
+
+### Testing
+
+All new features must include tests. Run tests with:
+
+```bash
+pytest
+pytest --cov=src/pso_segmentation  # With coverage
+```
+
+Aim for coverage > 80% on core modules.
+
+### Commits
+
+Use clear, descriptive commit messages:
+
+```
+Add feature: Brief description
+
+Longer explanation if needed.
+- Point 1
+- Point 2
+```
+
+Avoid:
+- ❌ `fix bug`
+- ❌ `update code`
+- ✅ `Fix convergence issue in PSO when pop_size < 2`
+
+## Pull Request Process
+
+1. Create a feature branch: `git checkout -b feature/my-feature`
+2. Make your changes
+3. Run all checks: `ruff format . && ruff check . && mypy src/ && pytest`
+4. Commit with clear messages
+5. Push to your fork
+6. Create a Pull Request with:
+   - Clear title and description
+   - Reference to any related issues
+   - Summary of changes
+
+## Documentation
+
+- Update docstrings for public APIs (Google style)
+- Add/update Sphinx docs for new features
+- Include examples in docstrings
+
+Example:
+
+```python
+def segment_scores(scores: np.ndarray, labels: np.ndarray, objective_func: Callable) -> np.ndarray:
+    """
+    Optimize segmentation of continuous scores.
+    
+    Parameters
+    ----------
+    scores : np.ndarray
+        Continuous scores to segment (shape: (n_samples,))
+    labels : np.ndarray
+        Binary labels (0/1) (shape: (n_samples,))
+    objective_func : Callable
+        Custom fitness function
+    
+    Returns
+    -------
+    np.ndarray
+        Optimized segment boundaries
+    
+    Examples
+    --------
+    >>> cuts = segment_scores(scores, labels, my_fitness_func)
+    """
+```
+
+## Reporting Issues
+
+Use GitHub Issues with:
+
+- Clear title
+- Steps to reproduce
+- Expected vs actual behavior
+- Python version and environment
+- Minimal code example
+
+## Questions?
+
+- Open a GitHub Discussion
+- Check existing documentation and issues first
+
+---
+
+Thank you for contributing! 🎉

pso_segmentation-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pso-segmentation contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pso_segmentation-0.1.0/PKG-INFO

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: pso-segmentation
+Version: 0.1.0
+Summary: Robust package for segmentation optimization using Particle Swarm Optimization (PSO)
+Author-email: Léo Colin <leocolin7002@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: PSO,data science,optimization,particle swarm optimization,segmentation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.12
+Requires-Dist: build>=1.5.0
+Requires-Dist: numpy>=1.20
+Requires-Dist: pandas>=1.3
+Requires-Dist: twine>=6.2.0
+Provides-Extra: all
+Requires-Dist: mypy; extra == 'all'
+Requires-Dist: myst-parser; extra == 'all'
+Requires-Dist: plotly>=6.0; extra == 'all'
+Requires-Dist: pytest-cov; extra == 'all'
+Requires-Dist: pytest>=7.0; extra == 'all'
+Requires-Dist: ruff; extra == 'all'
+Requires-Dist: sphinx-rtd-theme; extra == 'all'
+Requires-Dist: sphinx>=5.0; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: myst-parser; extra == 'docs'
+Requires-Dist: sphinx-rtd-theme; extra == 'docs'
+Requires-Dist: sphinx>=5.0; extra == 'docs'
+Provides-Extra: viz
+Requires-Dist: plotly>=6.0; extra == 'viz'
+Description-Content-Type: text/markdown
+
+# pso-segmentation
+
+[![Python Version](https://img.shields.io/badge/python-3.12%2B-blue)](https://www.python.org/)
+[![Code style: ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+`pso-segmentation` is a PSO-based package for building interpretable segmentations on any continuous variable.
+
+## Overview
+
+The package gives you a compact way to:
+
+- optimize cut points on continuous variables
+- encode business-specific constraints inside custom objective functions
+- select the number of segments with a dedicated helper
+- export results and persist optimizer state
+- compare candidates with a business-specific selection function
+
+## Installation
+
+```bash
+pip install pso-segmentation
+```
+
+For development and documentation work:
+
+```bash
+pip install -e ".[dev,docs]"
+```
+
+## Quick Start
+
+### Functional API
+
+```python
+import numpy as np
+from pso_segmentation import make_objective, segment_scores
+
+scores = np.random.uniform(0, 100, 1000)
+labels = np.random.binomial(1, 0.15, 1000)  # target (binary here)
+objective = make_objective(scores, labels, metric="r2")
+
+result = segment_scores(scores, labels, objective)
+
+print(f"R2: {result.r2:.3f}")
+print(f"Segments: {result.n_segments}")
+```
+
+### Object-Oriented API
+
+```python
+import numpy as np
+from pso_segmentation import (
+    make_objective,
+    monotonic_penalty,
+    OptimizerConfig,
+    SegmentationOptimizer,
+    segment_size_penalty,
+)
+
+scores = np.random.uniform(0, 100, 1000)
+labels = np.random.binomial(1, 0.15, 1000)  # target (binary here)
+objective = make_objective(
+    scores,
+    labels,
+    metric="r2",
+    penalties=[
+        monotonic_penalty(weight=0.3),
+        segment_size_penalty(min_size=0.05, max_size=0.4, weight=0.2),
+    ],
+)
+
+config = OptimizerConfig(n_segments=5, pop_size=50, max_iter=100, seed=42)
+optimizer = SegmentationOptimizer(config)
+optimizer.fit(scores, labels, objective)
+
+print(optimizer.summary())
+print(optimizer.get_metrics())
+```
+
+### Selecting the number of segments
+
+```python
+from pso_segmentation import make_objective, monotonic_penalty, select_n_segments
+
+
+def objective_factory(scores, labels, n_segments, params):
+    return make_objective(
+        scores,
+        labels,
+        metric="r2",
+        penalties=[monotonic_penalty(weight=params["monotonic_weight"])],
+    )
+
+selection = select_n_segments(
+    scores,
+    labels,
+    segment_range=(3, 7),
+    objective_factory=objective_factory,
+    param_grid={"monotonic_weight": [0.0, 0.2, 0.5]},
+)
+
+print(selection.best_candidate.n_segments)
+print(selection.best_candidate.cuts)
+```
+
+## Documentation
+
+The full user guide lives in the `docs/` folder. The notebooks are intentionally limited to:
+
+- `notebooks/00_quick_start.ipynb` (generic segmentation + objective contract)
+- `notebooks/01_business_use_case.ipynb` (PD segmentation with a custom objective)
+
+## Development
+
+Run the test and quality checks from the repository root:
+
+```bash
+pytest
+ruff check .
+ruff format .
+mypy src/
+```
+
+## License
+
+MIT License - see [LICENSE](LICENSE).
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the development workflow and contribution rules.
+
+## Status
+
+Version 0.1.0 is the current alpha release line. The package API is stable enough for
+experimentation, notebooks, and internal use, while production release work continues.

pso_segmentation-0.1.0/README.md

@@ -0,0 +1,136 @@
+# pso-segmentation
+
+[![Python Version](https://img.shields.io/badge/python-3.12%2B-blue)](https://www.python.org/)
+[![Code style: ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+`pso-segmentation` is a PSO-based package for building interpretable segmentations on any continuous variable.
+
+## Overview
+
+The package gives you a compact way to:
+
+- optimize cut points on continuous variables
+- encode business-specific constraints inside custom objective functions
+- select the number of segments with a dedicated helper
+- export results and persist optimizer state
+- compare candidates with a business-specific selection function
+
+## Installation
+
+```bash
+pip install pso-segmentation
+```
+
+For development and documentation work:
+
+```bash
+pip install -e ".[dev,docs]"
+```
+
+## Quick Start
+
+### Functional API
+
+```python
+import numpy as np
+from pso_segmentation import make_objective, segment_scores
+
+scores = np.random.uniform(0, 100, 1000)
+labels = np.random.binomial(1, 0.15, 1000)  # target (binary here)
+objective = make_objective(scores, labels, metric="r2")
+
+result = segment_scores(scores, labels, objective)
+
+print(f"R2: {result.r2:.3f}")
+print(f"Segments: {result.n_segments}")
+```
+
+### Object-Oriented API
+
+```python
+import numpy as np
+from pso_segmentation import (
+    make_objective,
+    monotonic_penalty,
+    OptimizerConfig,
+    SegmentationOptimizer,
+    segment_size_penalty,
+)
+
+scores = np.random.uniform(0, 100, 1000)
+labels = np.random.binomial(1, 0.15, 1000)  # target (binary here)
+objective = make_objective(
+    scores,
+    labels,
+    metric="r2",
+    penalties=[
+        monotonic_penalty(weight=0.3),
+        segment_size_penalty(min_size=0.05, max_size=0.4, weight=0.2),
+    ],
+)
+
+config = OptimizerConfig(n_segments=5, pop_size=50, max_iter=100, seed=42)
+optimizer = SegmentationOptimizer(config)
+optimizer.fit(scores, labels, objective)
+
+print(optimizer.summary())
+print(optimizer.get_metrics())
+```
+
+### Selecting the number of segments
+
+```python
+from pso_segmentation import make_objective, monotonic_penalty, select_n_segments
+
+
+def objective_factory(scores, labels, n_segments, params):
+    return make_objective(
+        scores,
+        labels,
+        metric="r2",
+        penalties=[monotonic_penalty(weight=params["monotonic_weight"])],
+    )
+
+selection = select_n_segments(
+    scores,
+    labels,
+    segment_range=(3, 7),
+    objective_factory=objective_factory,
+    param_grid={"monotonic_weight": [0.0, 0.2, 0.5]},
+)
+
+print(selection.best_candidate.n_segments)
+print(selection.best_candidate.cuts)
+```
+
+## Documentation
+
+The full user guide lives in the `docs/` folder. The notebooks are intentionally limited to:
+
+- `notebooks/00_quick_start.ipynb` (generic segmentation + objective contract)
+- `notebooks/01_business_use_case.ipynb` (PD segmentation with a custom objective)
+
+## Development
+
+Run the test and quality checks from the repository root:
+
+```bash
+pytest
+ruff check .
+ruff format .
+mypy src/
+```
+
+## License
+
+MIT License - see [LICENSE](LICENSE).
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the development workflow and contribution rules.
+
+## Status
+
+Version 0.1.0 is the current alpha release line. The package API is stable enough for
+experimentation, notebooks, and internal use, while production release work continues.