Downsample observations
Summarize measurements at a coarser interval, such as hourly or daily averages.
Pandas · Module
df.resample
DataFrame.resample groups time-series data into frequency-based bins for frequency conversion or aggregation. Use a datetime-like index, or identify a datetime-like column or level with on or level.
How it works
DataFrame.resample creates a Resampler for time-based grouping. Supply a frequency rule and either use a datetime-like index or identify a datetime-like column with on; finish with an aggregation or other Resampler operation.
Syntax
DataFrame.resample(rule, closed=None, label=None, convention='start', on=None, level=None, origin='start_day', offset=None, group_keys=False)Parameters
| Name | Type | Description |
|---|---|---|
rule | DateOffset, Timedelta or str | DateOffset, Timedelta, or string representing the target conversion frequency. |
closed | {'right', 'left'} or None | Side of each bin interval that is closed; defaults to None. |
label | {'right', 'left'} or None | Bin edge used as the resulting label; defaults to None. |
convention | {'start', 'end', 's', 'e'} | For PeriodIndex, whether to use the start or end of the rule. |
on | str or None | DataFrame column to use instead of the index; it must be datetime-like. |
level | int, str, or None | Datetime-like index level to use for resampling. |
origin | Timestamp or str | Timestamp or supported string used to adjust grouping alignment. |
offset | Timedelta-like or None | Offset applied when adjusting grouping alignment. |
group_keys | bool | Whether grouping keys are included when applying a function. |
Returns
A pandas.api.typing.Resampler instance.
Key points
- Use this method to partition time-series observations into frequency-based bins.
- It supports both changing frequency and aggregating time-series data.
- rule accepts a DateOffset, Timedelta, or string that specifies the target frequency.
- closed chooses whether the left or right edge belongs to each interval.
- label chooses whether bins are named by their left or right edge.
- origin controls the timestamp used to align the resampling groups.
Common mistakes
- Without on or level, the DataFrame index must be datetime-like; an ordinary index is not sufficient.
- The column selected through on must contain datetime-like values.
Example: Hourly means from a datetime column
import pandas as pd
frame = pd.DataFrame(
{"time": pd.to_datetime(["2024-01-01 00:15", "2024-01-01 00:45", "2024-01-01 01:10"]), "value": [2, 4, 3]}
)
result = frame.resample("h", on="time")["value"].mean()
print(result)Groups rows into hourly time bins using the datetime column, then computes each bin's mean.
When to use it
Upsample a time series
Convert a time series to a finer frequency before filling or interpolating values.
Resample on a column
Group by timestamps stored in a regular DataFrame column without setting it as the index.
Control bin alignment
Align bins to a chosen timestamp or time offset when calendar boundaries are not appropriate.
Interview questions
QWhat does DataFrame.resample return and what prerequisite does it have?
It groups time-series rows into bins defined by rule and returns a Resampler. The DataFrame needs a DatetimeIndex, PeriodIndex, or TimedeltaIndex, unless a datetime-like column or level is supplied through on or level.
Follow-up: How would you resample using a timestamp column while preserving that column? Use df.set_index(column, drop=False).resample(rule), because the documentation notes that an on column is otherwise excluded.
QHow do rule, closed, and label affect resampling?
rule is a DateOffset, Timedelta, or string describing the target frequency. Parameters such as closed and label control interval closure and the edge used for bin labels.
Follow-up: How can grouping alignment be changed? Set origin to the timestamp or supported origin string and optionally use offset to adjust it.
QHow can a DataFrame be resampled when its datetime values are not in the index?
Use on to resample by a datetime-like DataFrame column instead of the index, or level to use a datetime-like index level. After obtaining the Resampler, apply an aggregation such as mean, sum, or another supported operation.
Follow-up: What is the purpose of convention? For a PeriodIndex, it selects whether the start or end of the resampling rule is used.
Related
pandas.api.typing.Resamplerpandas.Series.resampleResampler.applyResampler.aggregateResampler.meanResampler.sum