pandas.DataFrame.stack — pandas 3.0.0.dev0+2102.g839747c3f6 documentation (original) (raw)

DataFrame.stack(level=-1, dropna=<no_default>, sort=<no_default>, future_stack=True)[source]#

Stack the prescribed level(s) from columns to index.

Return a reshaped DataFrame or Series having a multi-level index with one or more new inner-most levels compared to the current DataFrame. The new inner-most levels are created by pivoting the columns of the current dataframe:

• if the columns have a single level, the output is a Series;
• if the columns have multiple levels, the new index level(s) is (are) taken from the prescribed level(s) and the output is a DataFrame.

Parameters:

levelint, str, list, default -1

Level(s) to stack from the column axis onto the index axis, defined as one index or label, or a list of indices or labels.

dropnabool, default True

Whether to drop rows in the resulting Frame/Series with missing values. Stacking a column level onto the index axis can create combinations of index and column values that are missing from the original dataframe. See Examples section.

sortbool, default True

Whether to sort the levels of the resulting MultiIndex.

future_stackbool, default True

Whether to use the new implementation that will replace the current implementation in pandas 3.0. When True, dropna and sort have no impact on the result and must remain unspecified. See pandas 2.1.0 Release notes for more details.

Returns:

DataFrame or Series

Stacked dataframe or series.

Notes

The function is named by analogy with a collection of books being reorganized from being side by side on a horizontal position (the columns of the dataframe) to being stacked vertically on top of each other (in the index of the dataframe).

Reference the user guide for more examples.

Examples

Single level columns

df_single_level_cols = pd.DataFrame( ... [[0, 1], [2, 3]], index=["cat", "dog"], columns=["weight", "height"] ... )

Stacking a dataframe with a single level column axis returns a Series:

df_single_level_cols weight height cat 0 1 dog 2 3 df_single_level_cols.stack() cat weight 0 height 1 dog weight 2 height 3 dtype: int64

Multi level columns: simple case

multicol1 = pd.MultiIndex.from_tuples( ... [("weight", "kg"), ("weight", "pounds")] ... ) df_multi_level_cols1 = pd.DataFrame( ... [[1, 2], [2, 4]], index=["cat", "dog"], columns=multicol1 ... )

Stacking a dataframe with a multi-level column axis:

df_multi_level_cols1 weight kg pounds cat 1 2 dog 2 4 df_multi_level_cols1.stack() weight cat kg 1 pounds 2 dog kg 2 pounds 4

Missing values

multicol2 = pd.MultiIndex.from_tuples([("weight", "kg"), ("height", "m")]) df_multi_level_cols2 = pd.DataFrame( ... [[1.0, 2.0], [3.0, 4.0]], index=["cat", "dog"], columns=multicol2 ... )

It is common to have missing values when stacking a dataframe with multi-level columns, as the stacked dataframe typically has more values than the original dataframe. Missing values are filled with NaNs:

df_multi_level_cols2 weight height kg m cat 1.0 2.0 dog 3.0 4.0 df_multi_level_cols2.stack() weight height cat kg 1.0 NaN m NaN 2.0 dog kg 3.0 NaN m NaN 4.0

Prescribing the level(s) to be stacked

The first parameter controls which level or levels are stacked:

df_multi_level_cols2.stack(0) kg m cat weight 1.0 NaN height NaN 2.0 dog weight 3.0 NaN height NaN 4.0 df_multi_level_cols2.stack([0, 1]) cat weight kg 1.0 height m 2.0 dog weight kg 3.0 height m 4.0 dtype: float64