maxframe.learn.ensemble.RandomForestClassifier

class maxframe.learn.ensemble.RandomForestClassifier(*, n_estimators=100, criterion='gini', max_depth=None, max_bins=32, min_samples_split=2, min_samples_leaf=1, min_weight_fraction_leaf=0.0, max_features='sqrt', bootstrap=True, oob_score=False, random_state=None, verbose=0, max_samples=None, max_memory_in_mb=256, feature_subset_strategy='auto')

A distributed random forest classifier.

A random forest is a meta estimator that fits a number of decision tree classifiers on various sub-samples of the dataset and uses averaging to improve the predictive accuracy and control over-fitting.

This distributed implementation trains all trees simultaneously using a single pass over the data per tree level, which is significantly more efficient than training trees independently. Bootstrap sampling is handled via per-tree Poisson-distributed sample weights at the partition level.

Parameters:

• n_estimators (int, default=100) – The number of trees in the forest.

• criterion ({"gini", "entropy"}, default="gini") – The function to measure the quality of a split. Supported criteria are “gini” for the Gini impurity and “entropy” for the information gain.

• max_depth (int, default=None) – The maximum depth of the tree. If None, then nodes are expanded until all leaves are pure or until all leaves contain less than min_samples_split samples.

• max_bins (int, default=32) – The maximum number of bins used to discretize continuous features. See DecisionTreeClassifier for details.

• min_samples_split (int or float, default=2) – The minimum number of samples required to split an internal node.

• min_samples_leaf (int or float, default=1) – The minimum number of samples required to be at a leaf node.

• min_weight_fraction_leaf (float, default=0.0) – The minimum weighted fraction of the sum total of weights required to be at a leaf node.

• max_features ({"sqrt", "log2"}, int or float, default="sqrt") –

  The number of features to consider when looking for the best split. Note: “auto” is not supported; use “sqrt” explicitly.

  • If int, then consider max_features features at each split.

  • If float, then max_features is a fraction and max(1, int(max_features * n_features)) features are considered.

  • If “sqrt”, then max_features=sqrt(n_features).

  • If “log2”, then max_features=log2(n_features).

• bootstrap (bool, default=True) – Whether bootstrap samples are used when building trees. If False, the whole dataset is used to build each tree.

• oob_score (bool, default=False) –

  Whether to use out-of-bag samples to estimate the generalization score.

  Warning

  Out-of-bag scoring is not yet implemented. Setting oob_score=True will raise NotImplementedError.

• random_state (int, RandomState instance or None, default=None) – Controls both the randomness of the bootstrapping of the samples used when building trees (if bootstrap=True) and the sampling of the features to consider when looking for the best split at each node.

• verbose (int, default=0) – Controls the verbosity when fitting and predicting.

• max_samples (int or float, default=None) –

  If bootstrap is True, the number of samples to draw from X to train each base estimator.

  • If None (default), then draw X.shape[0] samples.

  • If int, then draw max_samples samples.

  • If float, then draw max(round(n_samples * max_samples), 1) samples. Thus, max_samples should be in the interval (0.0, 1.0].

• max_memory_in_mb (int, default=256) – The maximum memory in MB to use for aggregating statistics for a group of nodes during training. When training many trees, memory is shared across all trees at the same level. Fewer trees per group are processed when the budget is exceeded.

• feature_subset_strategy ({"auto", "sqrt", "log2", "onethird", "all"} or int, default="auto") –

  The strategy for selecting features at each node split:

  • ”auto”: “sqrt” for classification, “onethird” for regression.

  • ”sqrt”: ceil(sqrt(n_features)) features.

  • ”log2”: max(1, ceil(log2(n_features))) features.

  • ”onethird”: ceil(n_features / 3) features.

  • ”all”: all features (equivalent to bagging without feature subsampling).

  • If int: the exact number of features.

estimator_

The child estimator template used to create the collection of fitted sub-estimators.

Type:

DecisionTreeClassifier

estimators_

The collection of fitted sub-estimators.

Type:

list of DecisionTreeClassifier

classes_

The class labels.

Type:

ndarray of shape (n_classes,) or a list of such arrays

n_classes_

The number of classes.

Type:

int or list

n_features_in_

Number of features seen during fit.

Type:

int

feature_names_in_

Names of features seen during fit.

Type:

ndarray of shape (n_features_in_,)

n_outputs_

The number of outputs when fit is performed.

Type:

int

feature_importances_

The impurity-based feature importances. Currently returns all zeros (not yet implemented). Tracked as a known limitation.

Type:

ndarray of shape (n_features,)

oob_score_

Score of the training dataset obtained using an out-of-bag estimate. This attribute exists only when oob_score is True.

Type:

float

oob_decision_function_

Decision function computed with out-of-bag estimate on the training set. This attribute exists only when oob_score is True.

Type:

ndarray of shape (n_samples, n_classes)

See also

DecisionTreeClassifier

A distributed decision tree classifier.

RandomForestRegressor

A distributed random forest regressor.

Notes

Distributed Algorithm

All trees in the forest are trained simultaneously using a single distributed data pass per tree level. This is much more efficient than training trees independently, as the cost of a data pass is amortized across all trees.

The training process:

1. Bootstrap sampling: For each tree, per-sample weights are drawn from a Poisson(1) distribution at each partition, effectively creating bootstrap samples without data movement.

2. Feature subsampling: At each node, a random subset of features (controlled by feature_subset_strategy) is selected. The same random seed ensures consistent feature selection across partitions.

3. Sufficient statistics aggregation: Per-bin class counts are aggregated across all partitions and reduced via a shuffle operation for all trees simultaneously.

4. Split evaluation: Best splits are found independently for each tree using the merged statistics.

Limitations compared to scikit-learn

In addition to the limitations documented in DecisionTreeClassifier:

• n_jobs: Not applicable. Distributed parallelism is handled automatically by the MaxCompute execution engine.

• warm_start: Not supported. Incremental forest training is not available in the distributed setting.

• class_weight: Not yet supported.

• oob_score: Not yet implemented.

• ccp_alpha: Cost-complexity pruning is not supported.

• monotonic_cst: Monotonicity constraints are not supported.

Performance Considerations

• Training time scales with the deepest tree, not the average depth, since all trees are grown level-by-level together.

• The total memory per iteration is proportional to n_estimators * n_features * max_bins * n_classes. For very large forests, reduce max_bins or max_memory_in_mb.

• The number of distributed communication rounds equals the maximum tree depth across all trees.

References

[1]

L. Breiman, “Random Forests”, Machine Learning, 45(1), 5-32, 2001.

Examples

>>> from maxframe.learn.ensemble import RandomForestClassifier
>>> clf = RandomForestClassifier(n_estimators=100, max_depth=5)
>>> clf.fit(X_train, y_train)
RandomForestClassifier(max_depth=5, n_estimators=100)
>>> predictions = clf.predict(X_test)
>>> proba = clf.predict_proba(X_test)

__init__(*, n_estimators=100, criterion='gini', max_depth=None, max_bins=32, min_samples_split=2, min_samples_leaf=1, min_weight_fraction_leaf=0.0, max_features='sqrt', bootstrap=True, oob_score=False, random_state=None, verbose=0, max_samples=None, max_memory_in_mb=256, feature_subset_strategy='auto')

Methods

__init__(*[, n_estimators, criterion, ...])
execute([session, run_kwargs, extra_tileables])
fetch([session, run_kwargs])
fit(X, y[, sample_weight, execute, session, ...])	Fit a distributed random forest classifier.
predict(X[, execute, session, run_kwargs])	Predict class for X.
predict_log_proba(X[, execute, session, ...])	Predict class log-probabilities for X.
predict_proba(X[, execute, session, run_kwargs])	Predict class probabilities for X.
score(X, y[, sample_weight])	Return the mean accuracy on the given test data and labels.