Getting started

Installation

The process is similar to installing other Python packages. The Python version of fru is available as pyfru on PyPI. Use your favorite package manager to install it. The package requires python >= 3.12.

For this tutorial, you will also need pandas and polars.

Basic usage example

The package provides a scikit-learn-like API. You can initialize a model and use fit and predict in a similar way. For most users, the only parameter that needs adjustment is trees, which specifies the number of trees.

Warning

Pandas fully supports the PyCapsule interface starting from version 3. We support pandas version 3 and above.

Warning

The target must be a categorical series with string categories. Passing NumPy arrays is not supported. If you are using NumPy arrays, convert them to pandas.DataFrame and pandas.Series.

from sklearn.model_selection import train_test_split
from sklearn.datasets import load_iris

from pyfru import RandomForestClassifier

# load data
data = load_iris(as_frame=True)

# convert target to a categorical series with string categories
y = data["target"].astype(str).astype("category")

X_train, X_test, y_train, y_test = train_test_split(data["data"], y, test_size=0.2)

# create model instance
rf = RandomForestClassifier(trees=100)

# fit model
rf.fit(X_train, y_train)

# make predictions
rf.predict(X_test)

Permutation importance and out-of-bag

One of the key features of this model is support for permutation importance and out-of-bag (OOB) estimation. These features must be enabled when initializing the model by setting calculate_importance=True and oob=True.

from sklearn.model_selection import train_test_split
from sklearn.datasets import load_iris

from pyfru import RandomForestClassifier

# load data
data = load_iris(as_frame=True)
X = data["data"]
y = data["target"].astype(str).astype("category")

# create model instance with additional features enabled
rf = RandomForestClassifier(trees=100, calculate_importance=True, oob=True)
# fit model
rf.fit(X, y)

# get permutation importance
rf.importance()

# make predictions
rf.predict()

# get predictions with voting details
rf.predict(votes=True)

Regressor model

The package also supports regression. The target value can be any numeric type. Internally, it is converted to float64, and predictions are returned as float64 as well.

from sklearn.model_selection import train_test_split
from sklearn.datasets import load_diabetes

from pyfru import RandomForestRegressor

# load data
data = load_diabetes(as_frame=True)
X = data.data
y = data.target

# create model instancec
rf = RandomForestRegressor(trees=100, calculate_importance=True, oob=True)

# fit model
rf.fit(X, y)

# get permutation importance
rf.importance()

# get out-of-bag predictions
rf.predict()

Polars example

Another feature of Pyfru is that it works with libraries supporting the Arrow PyCapsule interface, such as pandas, polars, pyarrow, duckdb, and others.

import polars as pl

from sklearn.datasets import load_iris

from pyfru import RandomForestClassifier

# load data
data = load_iris(as_frame=True)

# create model instance
x = pl.from_pandas(data["data"])
y = pl.from_pandas(data["target"].astype(str).astype("category"))

# create model instance
rf = RandomForestClassifier(trees=100, calculate_importance=True, oob=True)

# fit model
rf.fit(X, y)

# get permutation importance
rf.importance()

# get out-of-bag predictions
rf.predict()

Result as PyCapsule (optional)

Results can optionally be returned as an Arrow PyCapsule. This allows them to be loaded into any data frame library supporting the Arrow PyCapsule interface.

import pandas as pd

from sklearn.datasets import load_iris

from pyfru import RandomForestClassifier

# load data
data = load_iris(as_frame=True)
X = data["data"]
y = data["target"].astype(str).astype("category")

# create model instance
    rf = RandomForestClassifier(trees=100, calculate_importance=True, oob=True)

# fit model
rf.fit(X, y)

# convert results from PyCapsule
pd.DataFrame.from_arrow(rf.importance(to_pycapsule=True))
pd.Series.from_arrow(rf.predict(to_pycapsule=True))
pd.DataFrame.from_arrow(rf.predict(votes=True, to_pycapsule=True))

Serialization

The model can be serialized using pickle.

import pickle

from sklearn.datasets import load_iris

from pyfru import RandomForestClassifier


# load data
data = load_iris(as_frame=True)
X = data["data"]
y = data["target"].astype(str).astype("category")

# create model instance
rf = RandomForestClassifier(trees=100, calculate_importance=True, oob=True)

# fit model
rf.fit(X, y)

# save model
with open("rf.pkl", "wb") as f:
    pickle.dump(rf, f)

# load model
with open("rf.pkl", "rb") as f:
    loaded_rf = pickle.load(f)

# use loaded model
loaded_rf.predict()