Home

Awesome

PyPI version PyPI license Build Status Coverage Status PyPI pyversions

vecstack

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

Get started

Installation

Note: Python 3.5 or higher is required. If you’re still using Python 2.7 or 3.4 see installation details here

Usage. Functional API

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 features

Usage. Scikit-learn API

from 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

Stacking FAQ

  1. How can I report an issue? How can I ask a question about stacking or vecstack package?
  2. How can I say thanks?
  3. How to cite vecstack?
  4. What is stacking?
  5. What about stacking name?
  6. Do I need stacking at all?
  7. Can you explain stacking (stacked generalization) in 10 lines of code?
  8. Why do I need complicated inner procedure for stacking?
  9. I want to implement stacking (stacked generalization) from scratch. Can you help me?
  10. What is OOF?
  11. What are estimator, learner, model?
  12. What is blending? How is it related to stacking?
  13. How to optimize weights for weighted average?
  14. What is better: weighted average for current level or additional level?
  15. What is bagging? How is it related to stacking?
  16. How many models should I use on a given stacking level?
  17. How many stacking levels should I use?
  18. How do I choose models for stacking?
  19. I am trying hard but still can't beat my best single model with stacking. What is wrong?
  20. What should I choose: functional API (stacking function) or Scikit-learn API (StackingTransformer)?
  21. How do parameters of stacking function and StackingTransformer correspond?
  22. Why Scikit-learn API was implemented as transformer and not predictor?
  23. How to estimate stacking training time and number of models which will be built?
  24. Which stacking variant should I use: 'A' ('oof_pred_bag') or 'B' ('oof_pred')?
  25. How to choose number of folds?
  26. When I transform train set I see 'Train set was detected'. What does it mean?
  27. How is the very first stacking level called: L0 or L1? Where does counting start?
  28. Can I use (Randomized)GridSearchCV to tune the whole stacking Pipeline?
  29. How to define custom metric, especially AUC?
  30. Do folds (splits) have to be the same across estimators and stacking levels? How does random_state work?

1. How can I report an issue? How can I ask a question about stacking or vecstack package?

Just open an issue here.
Ask me anything on the topic.
I'm a bit busy, so typically I answer on the next day.

2. How can I say thanks?

Just give me a star in the top right corner of the repository page.

3. How to cite vecstack?

@misc{vecstack2016,
       author = {Igor Ivanov},
       title = {Vecstack},
       year = {2016},
       publisher = {GitHub},
       howpublished = {\url{https://github.com/vecxoz/vecstack}},
}

4. What is stacking?

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:

5. What about stacking name?

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.

6. Do I need stacking at all?

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.

7. Can you explain stacking (stacked generalization) in 10 lines of code?

Of course

8. Why do I need complicated inner procedure for stacking?

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.

9. I want to implement stacking (stacked generalization) from scratch. Can you help me?

Not a problem

10. What is OOF?

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.

11. What are estimator, learner, model?

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.

12. What is blending? How is it related to stacking?

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:

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.

13. How to optimize weights for weighted average?

You can use for example:

14. What is better: weighted average for current level or additional level?

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.

15. What is bagging? How is it related to stacking?

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:

So if we run stacking and just average predictions - it is bagging.

16. How many models should I use on a given stacking level?

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.

You can also find some winning stacking architectures on Kaggle blog, e.g.: 1st place in Homesite Quote Conversion.

17. How many stacking levels should I use?

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.

18. How do I choose models for stacking?

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.

19. I am trying hard but still can't beat my best single model with stacking. What is wrong?

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:

Stacking API comparison:

Propertystacking functionStackingTransformer
Execution timeSameSame
RAMConsumes 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 trainingNoYes
Compatibility with Pipeline and FeatureUnionNoYes
Estimator implementation restrictionsMust have only fit and predict (predict_proba) methodsMust be fully scikit-learn compatible
NaN and inf in input dataAllowedNot allowed
Can automatically save OOF and log in filesYesNo
Input dimensionality (X_train, X_test)Arbitrary2-D

21. How do parameters of stacking function and StackingTransformer correspond?

stacking functionStackingTransformer
models=[Ridge()]estimators=[('ridge', Ridge())]
mode='oof_pred_bag' (alias 'A')variant='A'
mode='oof_pred' (alias 'B')variant='B'

22. Why Scikit-learn API was implemented as transformer and not predictor?

23. How to estimate stacking training time and number of models which will be built?

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:

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:

Compute time:

24. Which stacking variant should I use: 'A' ('oof_pred_bag') or 'B' ('oof_pred')?

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.

25. How to choose number of folds?

Note: Remember that higher number of folds substantially increase training time (and RAM consumption for StackingTransformer). See Q23.

26. When I transform train set I see 'Train set was detected'. What does it mean?

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.

27. How is the very first stacking level called: L0 or L1? Where does counting start?

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.

28. Can I use (Randomized)GridSearchCV to tune the whole stacking Pipeline?

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.

29. How to define custom metric, especially AUC?

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_score

30. 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.

Stacking concept

  1. 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).
  2. Any model can be used as 1st level model or 2nd level model.
  3. 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.
  4. The common practice is to use from 3 to 10 folds.
  5. 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 completion 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.
  6. As an example we look at stacking implemented with single 1st level model and 3-fold cross-validation.
  7. 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.
  8. We can repeat this cycle using other 1st level models to get more features for 2nd level model.
  9. You can also look at animation of Variant A and Variant B.

Variant A

Fold 1 of 3

Fold 2 of 3

Fold 3 of 3

Variant A. Animation

Variant A. Animation

Variant B

Step 1 of 4

Step 2 of 4

Step 3 of 4

Step 4 of 4

Variant B. Animation

Variant B. Animation