Introduction
Grouping sales by quarter, testing for weekday effects, or building a seasonal
forecast all start with the same question: which calendar period does each row belong
to? AddDateNumberColumns answers it in one call, decomposing a date column into year,
quarter, month, day, and day-of-week columns with a consistent naming convention, so
you can group, filter, and chart by any temporal grain without repeating .dt accessor
calls. Reach for it whenever a question depends on when something happened relative
to the calendar, not just its raw timestamp.
The function is particularly useful for:
- Time series analysis and seasonal pattern detection
- Grouping data by temporal periods (yearly, quarterly, monthly)
- Creating date-based filters and segments
- Generating time-based reports and visualizations
- Preparing data for machine learning models with temporal features
- Calendar-based business intelligence and analytics
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
dataframerequired | | — | A pandas DataFrame containing at least one column with date or datetime values. The DataFrame will be modified in place by adding new columns. |
date_column_namerequired | | — | Name of the column containing date or datetime values from which to extract temporal components. The column must be datetime-compatible or convertible to datetime format. |
Returns
The input DataFrame with five additional columns appended: {date_column_name}.Year
(four-digit year), .Quarter (1-4), .Month (1-12), .Day (1-31), and .DayOfWeek
(0=Monday, 6=Sunday).
Example
from analysistoolbox.data_processing import AddDateNumberColumns
import pandas as pd
# Add date components to a sales dataset
sales_df = pd.DataFrame({
'order_date': pd.date_range('2023-01-01', periods=5, freq='D'),
'amount': [100, 150, 200, 175, 225]
})
sales_df = AddDateNumberColumns(sales_df, 'order_date')
# Result includes: order_date.Year, order_date.Quarter, order_date.Month, etc.