Python package for stacking (stacked generalization) featuring lightweight functional API and fully compatible scikit-learn API
Convenient way to automate OOF computation, prediction and bagging using any number of models
- Functional API:
- Minimalistic. Get your stacked features in a single line
- RAM-friendly. The lowest possible memory consumption
- Kaggle-ready. Stacked features and hyperparameters from each run can be automatically saved in files. No more mess at the end of the competition. Log example
- Scikit-learn API:
- Standardized. Fully scikit-learn compatible transformer class exposing
fitandtransformmethods - Pipeline-certified. Implement and deploy multilevel stacking like it's no big deal using
sklearn.pipeline.Pipeline - And of course
FeatureUnionis also invited to the party
- Standardized. Fully scikit-learn compatible transformer class exposing
- Overall specs:
- Use any sklearn-like estimators
- Perform classification and regression tasks
- Predict class labels or probabilities in classification task
- Apply any user-defined metric
- Apply any user-defined transformations for target and prediction
- Python 3.5 and higher, unofficial support for Python 2.7 and 3.4
- Win, Linux, Mac
- MIT license
- Depends on numpy, scipy, scikit-learn>=0.18
- FAQ
- Installation guide
- Usage:
- Tutorials:
- Examples (all examples are valid for both API with little difference in parameters):
- Functional API:
- Scikit-learn API:
- Documentation:
- Functional API or type
>>> help(stacking) - Scikit-learn API or type
>>> help(StackingTransformer)
- Functional API or type
Note: Python 3.5 or higher is required. If you’re still using Python 2.7 or 3.4 see installation details here
- Classic 1st time installation (recommended):
pip install vecstack
- Install for current user only (if you have some troubles with write permission):
pip install --user vecstack
- If your PATH doesn't work:
/usr/bin/python -m pip install vecstackC:/Python36/python -m pip install vecstack
- Upgrade vecstack and all dependencies:
pip install --upgrade vecstack
- Upgrade vecstack WITHOUT upgrading dependencies:
pip install --upgrade --no-deps vecstack
- Upgrade directly from GitHub WITHOUT upgrading dependencies:
pip install --upgrade --no-deps https://github.com/vecxoz/vecstack/archive/master.zip
- Uninstall
pip uninstall vecstack
from vecstack import stacking
# Get your data
# Initialize 1st level estimators
models = [LinearRegression(),
Ridge(random_state=0)]
# Get your stacked features in a single line
S_train, S_test = stacking(models, X_train, y_train, X_test, regression=True, verbose=2)
# Use 2nd level estimator with stacked featuresfrom vecstack import StackingTransformer
# Get your data
# Initialize 1st level estimators
estimators = [('lr', LinearRegression()),
('ridge', Ridge(random_state=0))]
# Initialize StackingTransformer
stack = StackingTransformer(estimators, regression=True, verbose=2)
# Fit
stack = stack.fit(X_train, y_train)
# Get your stacked features
S_train = stack.transform(X_train)
S_test = stack.transform(X_test)
# Use 2nd level estimator with stacked features- How can I report an issue? How can I ask a question about stacking or vecstack package?
- How can I say thanks?
- How to cite vecstack?
- What is stacking?
- What about stacking name?
- Do I need stacking at all?
- Can you explain stacking (stacked generalization) in 10 lines of code?
- Why do I need complicated inner procedure for stacking?
- I want to implement stacking (stacked generalization) from scratch. Can you help me?
- What is OOF?
- What are estimator, learner, model?
- What is blending? How is it related to stacking?
- How to optimize weights for weighted average?
- What is better: weighted average for current level or additional level?
- What is bagging? How is it related to stacking?
- How many models should I use on a given stacking level?
- How many stacking levels should I use?
- How do I choose models for stacking?
- I am trying hard but still can't beat my best single model with stacking. What is wrong?
- What should I choose: functional API (
stackingfunction) or Scikit-learn API (StackingTransformer)? - How do parameters of
stackingfunction andStackingTransformercorrespond? - Why Scikit-learn API was implemented as transformer and not predictor?
- How to estimate stacking training time and number of models which will be built?
- Which stacking variant should I use: 'A' ('oof_pred_bag') or 'B' ('oof_pred')?
- How to choose number of folds?
- When I transform train set I see 'Train set was detected'. What does it mean?
- How is the very first stacking level called: L0 or L1? Where does counting start?
- Can I use
(Randomized)GridSearchCVto tune the whole stacking Pipeline? - How to define custom metric, especially AUC?
- Do folds (splits) have to be the same across estimators and stacking levels? How does
random_statework?
Just open an issue here.
Ask me anything on the topic.
I'm a bit busy, so typically I answer on the next day.
Just give me a star in the top right corner of the repository page.
@misc{vecstack2016,
author = {Igor Ivanov},
title = {Vecstack},
year = {2016},
publisher = {GitHub},
howpublished = {\url{https://github.com/vecxoz/vecstack}},
}
Stacking (stacked generalization) is a machine learning ensembling technique.
Main idea is to use predictions as features.
More specifically we predict train set (in CV-like fashion) and test set using some 1st level model(s), and then use these predictions as features for 2nd level model. You can find more details (concept, pictures, code) in stacking tutorial.
Also make sure to check out:
- Ensemble Learning (Stacking) in Wikipedia
- Classical Kaggle Ensembling Guide
- Stacked Generalization paper by David H. Wolpert
Often it is also called stacked generalization. The term is derived from the verb to stack (to put together, to put on top of each other). It implies that we put some models on top of other models, i.e. train some models on predictions of other models. From another point of view we can say that we stack predictions in order to use them as features.
It depends on specific business case. The main thing to know about stacking is that it requires significant computing resources. No Free Lunch Theorem applies as always. Stacking can give you an improvement but for certain price (deployment, computation, maintenance). Only experiment for given business case will give you an answer: is it worth an effort and money.
At current point large part of stacking users are participants of machine learning competitions. On Kaggle you can't go too far without ensembling. I can secretly tell you that at least top half of leaderboard in pretty much any competition uses ensembling (stacking) in some way. Stacking is less popular in production due to time and resource constraints, but I think it gains popularity.
I can just do the following. Why not?
model_L1 = XGBRegressor()
model_L1 = model_L1.fit(X_train, y_train)
S_train = model_L1.predict(X_train).reshape(-1, 1) # <- DOES NOT work due to overfitting. Must be CV
S_test = model_L1.predict(X_test).reshape(-1, 1)
model_L2 = LinearRegression()
model_L2 = model_L2.fit(S_train, y_train)
final_prediction = model_L2.predict(S_test)Code above will give meaningless result. If we fit on X_train we can’t just predict X_train, because our 1st level model has already seen X_train, and its prediction will be overfitted. To avoid overfitting we perform cross-validation procedure and in each fold we predict out-of-fold (OOF) part of X_train. You can find more details (concept, pictures, code) in stacking tutorial.
OOF is abbreviation for out-of-fold prediction. It's also known as OOF features, stacked features, stacking features, etc. Basically it means predictions for the part of train data that model haven't seen during training.
Basically it is the same thing meaning machine learning algorithm. Often these terms are used interchangeably.
Speaking about inner stacking mechanics, you should remember that when you have single 1st level model there will be at least n_folds separate models trained in each CV fold on different subsets of data. See Q23 for more details.
Basically it is the same thing. Both approaches use predictions as features.
Often this terms are used interchangeably.
The difference is how we generate features (predictions) for the next level:
- stacking: perform cross-validation procedure and predict each part of train set (OOF)
- blending: predict fixed holdout set
vecstack package supports only stacking i.e. cross-validation approach. For given random_state value (e.g. 42) folds (splits) will be the same across all estimators. See also Q30.
You can use for example:
scipy.optimize.minimizescipy.optimize.differential_evolution
By default you can start from weighted average. It is easier to apply and more chances that it will give good result. Then you can try additional level which potentially can outperform weighted average (but not always and not in an easy way). Experiment is your friend.
Bagging or Bootstrap aggregating works as follows: generate subsets of training set, train models on these subsets and then find average of predictions.
Also term bagging is often used to describe following approaches:
- train several different models on the same data and average predictions
- train same model with different random seeds on the same data and average predictions
So if we run stacking and just average predictions - it is bagging.
Note 1: The best architecture can be found only by experiment.
Note 2: Always remember that higher number of levels or models does NOT guarantee better result. The key to success in stacking (and ensembling in general) is diversity - low correlation between models.
It depends on many factors like type of problem, type of data, quality of models, correlation of models, expected result, etc.
Some example configurations are listed below.
- Reasonable starting point:
L1: 2-10 models -> L2: weighted (rank) average or single model
- Then try to add more 1st level models and additional level:
L1: 10-50 models -> L2: 2-10 models -> L3: weighted (rank) average
- If you're crunching numbers at Kaggle and decided to go wild:
L1: 100-inf models -> L2: 10-50 models -> L3: 2-10 models -> L4: weighted (rank) average
You can also find some winning stacking architectures on Kaggle blog, e.g.: 1st place in Homesite Quote Conversion.
Note 1: The best architecture can be found only by experiment.
Note 2: Always remember that higher number of levels or models does NOT guarantee better result. The key to success in stacking (and ensembling in general) is diversity - low correlation between models.
For some example configurations see Q16.
Based on experiments and correlation (e.g. Pearson). Less correlated models give better result. It means that we should never judge our models by accuracy only. We should also consider correlation (how given model is different from others). Sometimes inaccurate but very different model can add substantial value to resulting ensemble.
Nothing is wrong. Stacking is advanced complicated technique. It's hard to make it work. Solution: make sure to try weighted (rank) average first instead of additional level with some advanced models. Average is much easier to apply and in most cases it will surely outperform your best model. If still no luck - then probably your models are highly correlated.
20. What should I choose: functional API (stacking function) or Scikit-learn API (StackingTransformer)?
Quick guide:
- By default start from
StackingTransformerwith familiar scikit-learn interface and logic - If you need low RAM consumption try
stackingfunction but remember that it does not store models and does not have scikit-learn capabilities
Stacking API comparison:
| Property | stacking function | StackingTransformer |
|---|---|---|
| Execution time | Same | Same |
| RAM | Consumes the smallest possible amount of RAM. Does not store models. At any point in time only one model is alive. Logic: train model -> predict -> delete -> etc. When execution ends all RAM is released. | Consumes much more RAM. It stores all models built in each fold. This price is paid for standard scikit-learn capabilities like Pipeline and FeatureUnion. |
| Access to models after training | No | Yes |
Compatibility with Pipeline and FeatureUnion |
No | Yes |
| Estimator implementation restrictions | Must have only fit and predict (predict_proba) methods |
Must be fully scikit-learn compatible |
NaN and inf in input data |
Allowed | Not allowed |
| Can automatically save OOF and log in files | Yes | No |
Input dimensionality (X_train, X_test) |
Arbitrary | 2-D |
| stacking function | StackingTransformer |
|---|---|
models=[Ridge()] |
estimators=[('ridge', Ridge())] |
mode='oof_pred_bag' (alias 'A') |
variant='A' |
mode='oof_pred' (alias 'B') |
variant='B' |
- By nature stacking procedure is predictor, but by application it is definitely transformer.
- Transformer architecture was chosen because first of all user needs direct access to OOF. I.e. the ability to compute correlations, weighted average, etc.
- If you need predictor based on
StackingTransformeryou can easily create it viaPipelineby adding on the top ofStackingTransformersome regressor or classifier. - Transformer makes it easy to create any number of stacking levels. Using Pipeline we can easily create multilevel stacking by just adding several
StackingTransformer's on top of each other and then some final regressor or classifier.
Note: Stacking usually takes long time. It's expected (inevitable) behavior.
We can compute total number of models which will be built during stacking procedure using following formulas:
- Variant A:
n_models_total = n_estimators * n_folds - Variant B:
n_models_total = n_estimators * n_folds + n_estimators
Let's look at example. Say we define our stacking procedure as follows:
estimators_L1 = [('lr', LinearRegression()),
('ridge', Ridge())]
stack = StackingTransformer(estimators_L1, n_folds=4)So we have two 1st level estimators and 4 folds. It means stacking procedure will build the following number of models:
- Variant A: 8 models total. Each model is trained on 3/4 of
X_train. - Variant B: 10 models total. 8 models are trained on 3/4 of
X_trainand 2 models on fullX_train.
Compute time:
- If estimators have relatively similar training time, we can roughly compute total training time as:
time_total = n_models_total * time_of_one_model - If estimators have different training time, we should compute number of models and time for each estimator separately (set
n_estimators=1in formulas above) and then sum up times.
You can find out only by experiment. Default choice is variant A, because it takes less time and there should be no significant difference in result. But of course you may also try variant B. For more details see stacking tutorial.
Note: Remember that higher number of folds substantially increase training time (and RAM consumption for StackingTransformer). See Q23.
- Standard approach: 4 or 5 folds.
- If data is big: 3 folds.
- If data is small: you can try more folds like 10 or so.
Note 1: It is NOT allowed to change train set between calls to fit and transform methods. Due to stacking nature transformation is different for train set and any other set. If train set is changed after training, stacking procedure will not be able to correctly identify it and transformation will be wrong.
Note 2: To be correctly detected train set does not necessarily have to be identical (exactly the same). It must have the same shape and all values must be close (np.isclose is used for checking). So if you somehow regenerate your train set you should not worry about numerical precision.
If you transform X_train and see 'Train set was detected' everything is OK. If you transform X_train but you don't see this message then something went wrong. Probably your train set was changed (it is not allowed). In this case you have to retrain StackingTransformer. For more details see stacking tutorial or Q8.
Common convention: The very first bunch of models which are trained on initial raw data are called L1. On top of L1 we have so called stacker level or meta level or L2 i.e. models which are trained on predictions of L1 models. Count continues in the same fashion up to arbitrary number of levels.
I use this convention in my code and docs. But of course your Kaggle teammates may use some other naming approach, so you should clarify this for your specific case.
Yes, technically you can, but it is not recommended because this approach will lead to redundant computations. General practical advice is to tune each estimator separately and then use tuned estimators on the 1st level of stacking. Higher level estimators should be tuned in the same fashion using OOF from previous level. For manual tuning you can use stacking function or StackingTransformer with a single 1st level estimator.
from sklearn.metrics import roc_auc_score
from sklearn.preprocessing import OneHotEncoder
def auc(y_true, y_pred):
"""ROC AUC metric for both binary and multiclass classification.
Parameters
----------
y_true : 1d numpy array
True class labels
y_pred : 2d numpy array
Predicted probabilities for each class
"""
ohe = OneHotEncoder(sparse=False)
y_true = ohe.fit_transform(y_true.reshape(-1, 1))
auc_score = roc_auc_score(y_true, y_pred)
return auc_score30. Do folds (splits) have to be the same across estimators and stacking levels? How does random_state work?
To ensure better result, folds (splits) have to be the same across all estimators and all stacking levels. It means that random_state has to be the same in every call to stacking function or StackingTransformer. This is default behavior of stacking function and StackingTransformer (by default random_state=0). If you want to try different folds (splits) try to set different random_state values.
- We want to predict train set and test set with some 1st level model(s), and then use these predictions as features for 2nd level model(s).
- Any model can be used as 1st level model or 2nd level model.
- To avoid overfitting (for train set) we use cross-validation technique and in each fold we predict out-of-fold (OOF) part of train set.
- The common practice is to use from 3 to 10 folds.
- Predict test set:
- Variant A: In each fold we predict test set, so after completion of all folds we need to find mean (mode) of all temporary test set predictions made in each fold.
- Variant B: We do not predict test set during cross-validation cycle. After comple 67E6 tion of all folds we perform additional step: fit model on full train set and predict test set once. This approach takes more time because we need to perform one additional fitting.
- As an example we look at stacking implemented with single 1st level model and 3-fold cross-validation.
- Pictures:
- Variant A: Three pictures describe three folds of cross-validation. After completion of all three folds we get single train feature and single test feature to use with 2nd level model.
- Variant B: First three pictures describe three folds of cross-validation (like in Variant A) to get single train feature and fourth picture describes additional step to get single test feature.
- We can repeat this cycle using other 1st level models to get more features for 2nd level model.
- You can also look at animation of Variant A and Variant B.
