Metadata-Version: 2.5
Name: coneforest
Version: 0.1.0
Summary: ConeForest: an isolation-style anomaly detector that is one table lookup per tree
Project-URL: Homepage, https://divanov.eu/articles/coneforest.html
Author: Dmitry Ivanov
License-Expression: GPL-3.0-only
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: jax>=0.4.30
Requires-Dist: numpy>=1.24
Provides-Extra: bench
Requires-Dist: matplotlib>=3.10.8; extra == 'bench'
Requires-Dist: optuna>=3.0.0; extra == 'bench'
Requires-Dist: pandas>=2.3.3; extra == 'bench'
Requires-Dist: scikit-learn>=1.3.0; extra == 'bench'
Requires-Dist: scipy>=1.10.0; extra == 'bench'
Description-Content-Type: text/markdown

# ConeForest

ConeForest is an isolation-style anomaly detector for numeric tabular data. It uses
random oblivious trees and JAX array operations to provide fast fitting and scoring on
CPUs and GPUs. Higher anomaly scores indicate more anomalous rows.

The [project article](https://divanov.eu/articles/coneforest.html) describes the design,
evaluation, ablations, and limitations in detail.

## Installation

```bash
pip install coneforest
```

ConeForest requires Python 3.10 or newer. JAX and NumPy are installed as dependencies.
To use a GPU, install the appropriate JAX build for your hardware.

## Usage

```python
import numpy as np
from coneforest import ConeForest

rng = np.random.default_rng(0)
X_train = rng.normal(size=(1000, 5)).astype(np.float32)
X_test = rng.normal(size=(100, 5)).astype(np.float32)

model = ConeForest(b=256, psi=256, seed=0)
scores = model.fit(X_train).decision_function(X_test)
```

`X_train` and `X_test` are two-dimensional arrays of numeric features. The returned
`scores` are a one-dimensional NumPy array with one anomaly score per row. To fit and
score the same data in one call, use:

```python
scores = ConeForest(seed=0).fit_predict(X_train)
```

The constructor accepts three parameters:

- `b`: number of trees, defaulting to 256.
- `psi`: maximum number of training rows sampled per tree, defaulting to 256.
- `seed`: seed controlling all random draws, defaulting to 0.

No feature scaling or rank transformation is applied. ConeForest returns continuous
anomaly scores; choosing a decision threshold is left to the application.

## Design

Each tree is **oblivious**: all nodes at a given level use the same feature and
threshold. A tree of depth `K` therefore consists of only `K` feature-threshold pairs,
and each row's leaf is represented by a `K`-bit code.

For each tree, fitting:

1. Samples up to `psi` training rows and sets `K = ceil(log2(m))`, where `m` is the
   sample size.
2. Draws one feature per level, with replacement, and a threshold uniformly from that
   feature's observed range in the sample.
3. Converts every sampled row to its cell code and counts the rows in each cell at every
   depth.
4. Smooths each cell's mass as `(count + 1) / (m + 2)` and stores, for every full-depth
   code, the mean negative log mass of its prefix cells.

Scoring computes a row's cell code in each tree, retrieves the precomputed score with
one table lookup per tree, and averages the results. There is no per-node tree traversal
or branching. Fitting touches at most `b × psi` rows regardless of the full training-set
size, while scoring costs `b × K` comparisons and `b` lookups per row.

## License

ConeForest is distributed under the
[GNU General Public License v3.0](LICENSE).
