Metadata-Version: 2.4
Name: gato-hep
Version: 0.1.0
Summary: GATO: Gradient-based categorization optimization for HEP analyses
Author-email: Florian Mausolf <florian.mausolf@rwth-aachen.de>
License: MIT License
        
        Copyright (c) 2025 Florian Mausolf
        
        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.
Project-URL: Homepage, https://github.com/FloMau/gato-hep
Project-URL: Repository, https://github.com/FloMau/gato-hep
Project-URL: Documentation, https://gato-hep.readthedocs.io/en/latest/
Project-URL: Issues, https://github.com/FloMau/gato-hep/issues
Keywords: differentiable,binning,optimization,HEP,significance
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.26
Requires-Dist: tensorflow<2.20,>=2.17
Requires-Dist: tensorflow-probability>=0.24
Requires-Dist: tf_keras==2.19.0
Requires-Dist: ml_dtypes>=0.4.1
Requires-Dist: mplhep
Requires-Dist: matplotlib>=3.7
Requires-Dist: scipy
Requires-Dist: pandas
Requires-Dist: hist
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=5.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints; extra == "docs"
Requires-Dist: sphinx-autoapi; extra == "docs"
Requires-Dist: myst-parser; extra == "docs"
Requires-Dist: pydata-sphinx-theme; extra == "docs"
Dynamic: license-file

gato-hep: Gradient-based Categorization Optimizer for High Energy Physics
==============================================

[![Documentation Status](https://readthedocs.org/projects/gato-hep/badge/?version=latest)](https://gato-hep.readthedocs.io/en/latest/)


A toolkit for binning / categorisation optimisation with respect to signal 
significance for HEP analyses, using gradient-descent methods.
gatohep relies on TensorFlow with TensorFlow-Probability.

The categorisation can be performed directly in a multidimensional discriminant 
space, e.g. from a mutliclassifier with softmax activation.
The bins are defined by learnable multidimensional Gaussians as a Gaussian Mixture Model (GMM), or, well working in 1D, using bin boundaries approximated by steep sigmoid functions of learnable position.

See the full documentation at <https://gato-hep.readthedocs.io/>.

--------------------------------------------------------------------
Quick install (editable mode)
--------------------------------------------------------------------
```bash
git clone https://github.com/FloMau/gato-hep.git
cd gato-hep
python3 -m venv gato_env       # or use conda
source gato_env/bin/activate
pip install -e .
```

Dependencies are declared in *pyproject.toml*. 
Note: The only tricky part is to find matching versions of tensorflow, tensorflow-probability and ml-dtypes. The requirements mentioned here should work, however, other combinations may work as well.

--------------------------------------------------------------------
## Running the toy examples
--------------------------------------------------------------------
### 1D toy (signal vs. multi-background)
```python
python examples/1D_example/run_toy_example.py
```

### 3-class soft-max (2 D slice of 3 D)
```python
python examples/three_class_softmax_example/run_example.py
```

Each script writes plots & a significance comparison table.

--------------------------------------------------------------------
## Apply gato-hep to your own data
--------------------------------------------------------------------
``` python
# standard GMM model for ND optimisation
from gatohep.models import gato_gmm_model
# more to be included here later on

# see ./examples for a full workflow!
```

--------------------------------------------------------------------
## Directory layout
--------------------------------------------------------------------
```
gato-hep/                       project root
│
├─ pyproject.toml           metadata + dependencies
├─ src/gatohep/                installable Python package
│   │
│   ├─ __init__.py
│   ├─ models.py            Trainable model class
│   └─ losses.py            custom loss / penalty terms
│   ├─ utils.py             misc helpers
│   ├─ plotting_utils.py    helper plots (stacked hists, bin boundaries, ...)
│   ├─ data_generation.py   toy data generators (1D / 3-class softmax)
│
└─ examples/                runnable demos
    ├─ 1D_example/run_example.py
    └─ three_class_softmax_example/run_example.py
```

--------------------------------------------------------------------
## Contributing
--------------------------------------------------------------------
1. `git checkout -b feature/xyz`
2. Code under *src/gatohep/*, add tests under *tests/*.
3. Update version in *pyproject.toml*.
4. `black` / `isort` / `pytest`, then open a PR.

