pyfru api¶

class pyfru.random_forest.RandomForestClassifier(trees=500, tries=None, save_forest=True, calculate_importance=False, oob=False, seed=None, threads=None)[source]¶

Bases: _RandomForestBase

Random Forest Classifier implementing a fast multi-thread implementation of the original Random Forest model [1]. Thanks to the Arrow PyCapsule interface, Pyfru supports a wide range of DataFrame libraries. In addition to prediction, it supports out-of-bag (OOB) predictions and feature importance. The importance measure is computed in a novel, efficient way.

Parameters:

trees (int) – Number of trees to grow in the forest (often called ntree in other software). Must be greater than zero. The value should be large enough to provide stable results (prediction accuracy or importance). Larger datasets typically require more trees. Computation time grows linearly with the number of trees. Defaults to 500.
tries (int | None) – Number of features to try at each split (often called mtry). Must be greater than zero and less than or equal to the number of features. By default, it is set to the rounded square root of the number of features. Higher values increase correlation between trees. In most cases, the default setting is recommended.
save_forest (bool) – If True, the fitted forest is stored and can be used for prediction or serialization. Set to False when only importance or OOB results are needed. Defaults to True.
calculate_importance (bool) – If True, feature importance is calculated. Defaults to False.
oob (bool) – If True, out-of-bag predictions are calculated. Defaults to True.
seed (int | None) – Seed used by the algorithm. Set to None to use a random seed.
threads (int | None) – Number of threads to use. Must be greater than zero. If None, all available CPU cores are used. Defaults to None.

Notes

The Random Forest Classifier selects the best feature at each split using Gini impurity. For numerical features, the threshold is optimized by an exhaustive scan. The threshold is the midpoint between adjacent values. In case of ties, the smaller threshold is chosen.

Ordered categorical variables are currently treated as categorical. Variables with six or more levels are treated as integers. Variables with five or fewer levels are split by exhaustively evaluating all possible partitions into two subsets using the Gini criterion.

The maximum tree depth is fixed at 512. A leaf is created when the sample size reaches one. Leaves may also be formed earlier if no valid split is found; in such cases, ties are broken randomly.

Pyfru uses its own PRNG, the pcg32 method by Melissa E. O’Neill [2], to provide reproducible results in parallel settings. For a given input and seed, the same trees are built regardless of the number of threads, although their order may differ. OOB predictions and importance scores are therefore consistent up to numerical precision.

References

fit(X, y)[source]¶

Build a forest of trees from the training data.

Parameters:

X (Arrow PyCapsule) – A DataFrame-like object supporting the Arrow PyCapsule interface. Any library supporting this interface can be used (e.g., pandas, polars). Columns can be boolean, numerical, or categorical. Mixed column types are allowed. Other data types are not supported and will raise an exception. NaN values are not allowed.
y (Arrow PyCapsule) – A Series-like object supporting the Arrow PyCapsule interface. Any library supporting this interface can be used. For classification, y must be categorical, otherwise an exception is raised. NaN values are not allowed. The length of y must match the number of rows in X.

importance(scale=False, to_pycapsule=False)¶

Extract permutation (mean decrease in accuracy) importance from the model.

Parameters:

scale (bool) – If True, values are scaled by their standard deviation over the ensemble. Defaults to False.
to_pycapsule (bool) – If True, results are returned as an Arrow PyCapsule. If False, results are returned as NumPy arrays, similar to scikit-learn. Defaults to False.

Returns:

By default, a 1D NumPy array is returned. It contains the importance value for each column. If to_pycapsule=True, an object implementing the Arrow PyCapsule interface is returned. This object can be loaded as a DataFrame in libraries supporting the Arrow PyCapsule interface. It has two columns: column and importance.

Return type:

numpy.ndarray or Arrow PyCapsule

Notes

Other packages often scale importance by its standard error estimate, producing importance values larger by a factor of the square root of the number of trees compared to fru.

predict(X=None, votes=False, validate_input=True, to_pycapsule=False)[source]¶

Predict for X. The predicted class is the one with the highest number of votes across the trees. If no X is given, out-of-bag predictions are returned. If votes=True, vote counts are returned instead of predictions.

Parameters:

X (Arrow PyCapsule | None) – A DataFrame-like object supporting the Arrow PyCapsule interface. Cannot contain NaN values. If None (default), out-of-bag predictions are returned.
votes (bool) – If True, the number of votes from each tree is returned instead of predictions. Defaults to False.
validate_input (bool) – If True, column data types and names in X are checked against the data provided to fit. For categorical columns, category names and their order must match.
to_pycapsule (bool, optional) – If True, results are returned as an Arrow PyCapsule. Otherwise, NumPy arrays are returned. Defaults to False.

Returns:

For predictions, a 1D NumPy array is returned with one prediction per observation. Categorical predictions are represented as strings. For votes, a 2D NumPy array is returned. If to_pycapsule=True, results are returned as an Arrow PyCapsule that can be loaded as a Series in libraries supporting this interface.

Return type:

numpy.ndarray or Arrow PyCapsule

Notes

Voting in classification may result in ties. In such cases, a PRNG is used to break ties. If seed=None, different seeds are used on each execution, so ties may be resolved differently. For deterministic behavior, set seed or use votes=True to inspect vote counts.

This method checks that the input structure matches the training data structure stored in the object. This may take time for large data or low-latency use cases. Set validate_input=False to skip validation and assume the input is correct.

class pyfru.random_forest.RandomForestRegressor(trees=500, tries=None, save_forest=True, calculate_importance=False, oob=False, seed=None, threads=None)[source]¶

Bases: _RandomForestBase

Random Forest Regressor implementing a fast multi-threaded version of the original Random Forest model [3]. Thanks to the Arrow PyCapsule interface, Pyfru supports a wide range of DataFrame libraries. In addition to prediction, it supports out-of-bag (OOB) predictions and feature importance. The importance measure is computed in a novel, efficient way.

Parameters:

trees (int) – Number of trees to grow in the forest (often called ntree in other software). Must be greater than zero. The value should be large enough to provide stable results (prediction accuracy or importance). Larger datasets typically require more trees. Computation time grows linearly with the number of trees. Defaults to 500.
tries (int | None) – Number of features to try at each split (often called mtry). Must be greater than zero and less than or equal to the number of features. By default, it is set to the rounded square root of the number of features. Higher values increase correlation between trees. In most cases, the default setting is recommended.
save_forest (bool) – If True, the fitted forest is stored and can be used for prediction or serialization. Set to False when only importance or OOB results are needed. Defaults to True.
calculate_importance (bool) – If True, feature importance is calculated. Defaults to False.
oob (bool) – If True, out-of-bag predictions are calculated. Defaults to True.
seed (int | None) – Seed used by the algorithm. Set to None to use a random seed.
threads (int | None) – Number of threads to use. Must be greater than zero. If None, all available CPU cores are used. Defaults to None.

Notes

The Random Forest Regressor selects the best feature at each split using variance reduction. For numerical features, the threshold is optimized by an exhaustive scan. For float features, the threshold is the midpoint between adjacent values; for integer features, it is the smaller of the two values. In case of ties, the smaller threshold is chosen.

The maximum tree depth is fixed at 512. A leaf is created when the sample size reaches four. This means regression typically requires at least ten samples to be practical.

Pyfru uses its own PRNG, the pcg32 method by Melissa E. O’Neill [4], to provide reproducible results in parallel settings. For a given input and seed, the same trees are built regardless of the number of threads, although their order may differ. OOB predictions and importance scores are therefore consistent up to numerical precision.

References

fit(X, y)[source]¶

Build a forest of trees from the training set.

Parameters:

X (Arrow PyCapsule) – A DataFrame-like object supporting the Arrow PyCapsule interface. Any library supporting this interface can be used (e.g., pandas, polars). Columns can be boolean, numerical, or categorical. Mixed column types are allowed. Other data types are not supported and will raise an exception. NaN values are not allowed.
y (Arrow PyCapsule) – A Series-like object supporting the Arrow PyCapsule interface. Any library supporting this interface can be used. For regression, y must be of type float or int; otherwise an exception is raised. NaN values are not allowed. The length of y must match the number of rows in X.

importance(scale=False, to_pycapsule=False)¶

Extract permutation (mean decrease in accuracy) importance from the model.

Parameters:

scale (bool) – If True, values are scaled by their standard deviation over the ensemble. Defaults to False.
to_pycapsule (bool) – If True, results are returned as an Arrow PyCapsule. If False, results are returned as NumPy arrays, similar to scikit-learn. Defaults to False.

Returns:

Return type:

numpy.ndarray or Arrow PyCapsule

Notes

Other packages often scale importance by its standard error estimate, producing importance values larger by a factor of the square root of the number of trees compared to fru.

predict(X=None, validate_input=True, to_pycapsule=False)[source]¶

Predict for X using the mean over the ensemble. If no X is given, out-of-bag predictions are returned.

Parameters:

X (Arrow PyCapsule | None) – A DataFrame-like object supporting the Arrow PyCapsule interface. Cannot contain NaN values. If None (default), out-of-bag predictions are returned.
validate_input (bool) – If True, column data types and names in X are checked against the data provided to fit. For categorical columns, category names and their order must match.
to_pycapsule (bool, optional) – If True, results are returned as an Arrow PyCapsule. Otherwise, NumPy arrays are returned. Defaults to False.

Returns:

For predictions, a 1D NumPy array is returned containing one prediction per observation. If to_pycapsule=True, results are returned as an Arrow PyCapsule, which can be loaded as a Series in libraries supporting this interface.

Return type:

numpy.ndarray or Arrow PyCapsule

Notes

Regression is performed using leaf averages, which is deterministic, aside from potential small numerical differences due to multithreading and tree construction order.