Metadata-Version: 2.4
Name: rfmsu
Version: 0.1.3
Summary: Weka-inspired Random Forest with Multivariate Symmetrical Uncertainty
Author: Miguel Garcia Torres, Thomas Vanhaeren
License-Expression: MIT
Project-URL: Repository, https://github.com/mgarciat/rf-msu
Project-URL: Documentation, https://github.com/mgarciat/rf-msu/tree/main/manual
Project-URL: Scientific Paper, https://doi.org/10.1016/j.patcog.2025.111939
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.23
Requires-Dist: pandas>=1.5
Requires-Dist: joblib>=1.2
Provides-Extra: fast
Requires-Dist: numba>=0.57; extra == "fast"
Requires-Dist: polars>=2.0; extra == "fast"

# RFMSU

Random Tree and Random Forest classifiers based on
Multivariate Symmetrical Uncertainty (MSU).

## Features

- Random Tree classifier.
- Random Tree with MSU.
- Random Forest classifier.
- Random Forest with MSU.
- Local and global discretization.
- Parallel training using Joblib.
- Out-of-bag evaluation.

## Installation

```bash
pip install rfmsu
```

## Usage Examples

### 1. Basic Configuration

The following example trains a Random Forest with MSU using 100 trees, local discretization, and parallel tree construction.

```python
from rfmsu import RandomForestMSU

clf = RandomForestMSU(
    numIterations=100,
    rediscretize_msu_per_node=True,
    n_jobs=-1
)

clf.fit(X_train, y_train)
predictions = clf.predict(X_test)
```

### 2. Weka-Oriented Configuration (Closest to the Original Java Implementation)

The following configuration is the closest to the original Weka implementation of RFMSU, using local discretization and weighted bootstrap sampling.

Local discretization recomputes the discretization at each tree node, while weighted bootstrap sampling represents bootstrap repetitions through instance weights, following the approach used in Weka.

```python
from rfmsu import RandomForestMSU

clf = RandomForestMSU(
    numIterations=100,
    kValue=0,
    maxDepth=0,
    minNum=1,
    seed=42,
    debug=False,
    rediscretize_msu_per_node=True,
    bootstrap_mode="weighted",
    n_jobs=12,
    parallel_backend="loky",
    use_joblib_discretization=False,
    discretization_n_jobs=1
)

clf.fit(X_train, y_train)
predictions = clf.predict(X_test)
```

### Parallelization Options

RFMSU supports parallel tree construction and optional parallel feature discretization.

- `n_jobs`: Controls the number of parallel workers used for tree construction in both local and global discretization modes.
- `parallel_backend`: Specifies the Joblib backend used for tree construction (`loky`, `threading`, or `multiprocessing`).
- `use_joblib_discretization`: Enables parallel feature discretization when global discretization is used.
- `discretization_n_jobs`: Specifies the number of workers used for global feature discretization when Joblib is enabled.

**Important:** In the current implementation, local discretization (`rediscretize_msu_per_node=True`) is performed sequentially within each tree. Therefore, `use_joblib_discretization` and `discretization_n_jobs` do not affect node-level discretization. However, tree construction can still be parallelized using `n_jobs`.

When global discretization is selected (`rediscretize_msu_per_node=False`), Joblib can additionally parallelize feature discretization.

### Comparison with Weka

The second configuration is recommended for experiments aiming to reproduce the behavior of the original Weka implementation.

However, exact equivalence is not guaranteed due to possible differences in random number generation, bootstrap handling, and other implementation details.


## References

RFMSU implements Random Tree and Random Forest
classifiers incorporating Multivariate Symmetrical
Uncertainty (MSU).

For further details about RFmsu and its theoretical
foundations, see:

García-Torres, M., Saucedo, F., Divina, F., & Gómez-Guerrero, S. (2026).
RFMSU: A multivariate symmetrical uncertainty-based random forest.
Pattern Recognition, 169, 111939.
DOI: https://doi.org/10.1016/j.patcog.2025.111939

## License

MIT License.
