citylearn.internal.occupant_models module

Occupant set-point models stored as scikit-learn tree pickles, evaluated with NumPy.

The bundled Quebec datasets ship RandomForestClassifier pickles written by scikit-learn 1.0.2. scikit-learn 1.3 changed the tree node layout and cannot unpickle them, which used to pin scikit-learn to <=1.2.2 and, through it, NumPy to <2 and Python to <3.12.

These files are read by a restricted unpickler, whichever pickle protocol (0 to 5) wrote them. It rebuilds only NumPy arrays and records the state of the three scikit-learn classes involved, so no scikit-learn installation is needed and no other callable named in the file can run. A numpy.random.RandomState passed as random_state is recorded as an inert placeholder, since prediction never draws from it.

Predictions reproduce predict and predict_proba of single-output RandomForestClassifier and DecisionTreeClassifier as the scikit-learn release that wrote the file computes them: inputs are cast to float32, trees are traversed with the stored thresholds, and leaf values are averaged in estimator order. Releases before 1.4 store weighted class counts in the leaves and normalise them per tree; later releases store class fractions and use them as stored. Releases before 1.3 reject missing (NaN) inputs; later ones store at each split which child receives them (missing_go_to_left), and NaN inputs follow it as in Tree.apply (only 1.3’s forests still rejected NaN on input). Infinite inputs are rejected, as in scikit-learn. Trees whose nodes hold other fields are left to the installed scikit-learn.

class citylearn.internal.occupant_models.TreeClassifierModel(classes: ndarray, trees: List[_TreeArrays], n_features: int, forest: bool, *, accepts_missing: bool = True)[source]

Bases: object

NumPy evaluation of a pickled scikit-learn RandomForestClassifier or DecisionTreeClassifier.

classmethod from_pickle(filepath: str | Path) → TreeClassifierModel[source]
predict(x) → ndarray[source]
predict_proba(x) → ndarray[source]
exception citylearn.internal.occupant_models.UnsupportedModelError[source]

Bases: UnpicklingError

The file holds something other than a scikit-learn decision tree or random forest.

citylearn.internal.occupant_models.load_occupant_model(filepath: str | Path)[source]

Load an occupant model; tree classifiers never need scikit-learn or run code from the file.

Other pickled models still load through pickle and need a compatible library.