Running totals
Track a cumulative metric over time, such as total sales or accumulated scores.
Pandas · Module
df.expanding
Creates an expanding-window object for a DataFrame. Each subsequent position can aggregate all data available from the beginning through that position.
How it works
Calling expanding creates an Expanding object whose window starts at the first row and grows through each subsequent row. Apply an aggregation such as sum, mean, or max to calculate a statistic over all available observations at each position; min_periods controls when results begin appearing.
Syntax
DataFrame.expanding(*min_periods=1*, *method='single'*)Parameters
| Name | Type | Description |
|---|---|---|
min_periods | int, default 1 | Minimum number of observations in the window required to produce a value; otherwise the result is NaN. Default: 1. |
method | str {'single', 'table'}, default 'single' | Whether to operate per single column or row ('single') or over the entire object ('table'). Default: 'single'. Table mode is implemented only with engine='numba' in the method call. |
Returns
pandas.api.typing.Expanding, an expanding-window object for further calculations.
Key points
- The method prepares a growing window for calculations such as cumulative sums or means.
- At each row, the aggregation includes every available value from the start through the current position.
- min_periods specifies how many observations are needed before an output is considered valid.
- The method argument chooses independent one-dimensional processing or whole-object processing.
- The result is an Expanding object, so an aggregation method must normally follow it to obtain calculated values.
Common mistakes
- Rows before min_periods valid observations are reached produce NaN.
- The table method is not generally available; it is supported only when the aggregation call uses the Numba engine.
Example: Cumulative expanding sum
import pandas as pd
scores = pd.DataFrame({"score": [2, 4, 6, 8]})
scores["running_total"] = scores["score"].expanding(min_periods=2).sum()
print(scores)Creates a cumulative sum that starts after two valid observations are available.
When to use it
Cumulative averages
Calculate a progressively updated average as new rows arrive.
Progressive bounds
Apply growing-window extrema to monitor the highest or lowest value seen so far.
Interview questions
QWhat does DataFrame.expanding return?
It returns an Expanding object for subsequent expanding-window calculations. Each position can then aggregate all data available from the beginning through that position.
Follow-up: How would you delay output until enough observations exist? Pass a larger min_periods value to expanding before applying the aggregation.
QWhat is the purpose of min_periods?
min_periods sets the minimum number of observations required before a value is produced. With the default of 1, the first eligible observation can produce a result; otherwise the result is NaN.
Follow-up: What happens with missing data? The aggregation follows its own missing-value behavior, while min_periods determines whether enough observations are present.
QHow do the method options differ?
method='single' applies the operation to each individual column or row, while method='table' applies it to the entire object. The documentation limits table mode to calls using engine='numba'.
Follow-up: When would table mode be relevant? Use it when a Numba-enabled operation needs to process the complete object rather than independent one-dimensional inputs.
Related
pandas.api.typing.Expandingpandas.Series.expandingpandas.api.typing.Expanding.sumpandas.api.typing.Expanding.meanpandas.api.typing.Expanding.max