Time-series changes
Compute period-over-period changes in metrics stored by row.
Pandas · Module
df.diff
Computes discrete differences between DataFrame elements, comparing with the previous row by default. Use periods to control the shift and axis to choose rows or columns.
How it works
DataFrame.diff compares each value with the value a specified number of periods away. By default it compares with the preceding row; setting axis=1 compares across columns, and the output uses float64 values.
Syntax
DataFrame.diff(periods=1, axis=0)Parameters
| Name | Type | Description |
|---|---|---|
periods | int, default 1 | Number of periods to shift before calculating the difference; negative values are accepted. |
axis | {0 or 'index', 1 or 'columns'}, default 0 | Direction of the difference: 0 or 'index' for rows, or 1 or 'columns' for columns. |
Returns
DataFrame — first differences.
Key points
- The method returns first discrete differences for a DataFrame.
- With default arguments, each element is compared with the corresponding element in the previous row.
- Use periods to choose how far apart compared values are, including backward shifts with negative values.
- axis=0 computes differences down rows, while axis=1 computes them across columns.
- The return value is a DataFrame containing the calculated first differences.
Common mistakes
- Boolean columns use logical XOR semantics rather than numeric subtraction.
Example: Difference between consecutive rows
import pandas as pd
df = pd.DataFrame({"sales": [10, 14, 11, 18]})
df["change"] = df["sales"].diff()
print(df)Computes each row's sales change from the preceding row; the first result is missing because no preceding row exists.
When to use it
Column-wise comparisons
Measure horizontal changes between related columns.
Feature engineering
Create lag-based features for modeling or analysis.
Interview questions
QWhat does DataFrame.diff() calculate by default?
It computes first discrete differences between DataFrame elements. With the defaults, each row is compared with the previous row, so the leading row has no earlier value to compare against.
Follow-up: How would you compare adjacent columns instead? Pass axis=1, which takes differences across columns rather than rows.
QWhat is the purpose of periods?
periods controls the shift distance used for the comparison and defaults to 1. It also accepts negative values, allowing comparison in the opposite direction.
Follow-up: What does periods=3 do? Each value is compared with the value three rows earlier when using the default axis.
QHow does axis change the operation?
axis accepts 0 or 'index' for differences over rows, and 1 or 'columns' for differences over columns. The default is axis=0.
Follow-up: What output type should callers expect? The method returns a DataFrame containing the first differences.
Related
pandas.DataFrame.shiftpandas.Series.diffpandas.api.typing.DataFrameGroupBy.diff