FlexCPI is under active development for inflation analysis and customized economic indexing.
| Table of Contents | |
| 1. Overview | 2. Installation |
| 3. Requirements | 4. BLS API Key Requirement |
| 5. Package Structure | 6. Core Functions |
| 7. Function Inputs/Outputs | 8. Usage Example |
| 9. License | 10. Contributing |
FlexCPI is a Python package for creating and analyzing custom Consumer Price Index (CPI) baskets using Bureau of Labor Statistics (BLS) data. It allows users to:
- Search CPI series by keyword and region
- Match series to official expenditure weights
- Construct custom CPI indexes using weighted BLS series
- Plot and compare with official CPI indexes
This toolkit is ideal for economic researchers, policy analysts, and students of macroeconomics who want flexible, reproducible CPI constructions.
Install from PyPI:
pip install flexcpi-
pandas -
requests -
matplotlib -
statsmodelsImportant:
Before using most functions in
flexcpi, you must first load the necessary data tables using the following functions:from flexcpi.toolkit import load_catalog_tables, load_weight_tables full_catalog = load_catalog_tables() table1, table2 = load_weight_tables()These data tables are required inputs for key operations like matching series to weights and computing custom CPI indexes.
The flexcpi package is fundamentally built on top of the U.S. Bureau of Labor Statistics (BLS) data infrastructure.
It enables users to search, extract, and customize Consumer Price Index (CPI) series directly from BLS.
To access CPI data, users must register for a free BLS API key.
How to get an API key:
- Visit the BLS Public Data API Registration Page
- Fill out your name and email to request an API key.
- BLS will email you a unique
registrationkey.
How to use the API key:
Pass the key to any function that supports the api_key parameter:
custom_cpi_df = compute_custom_cpi_index(matched_df, start_year=2020, end_year=2025, api_key="your_api_key")FlexCPI/
│
├── flexcpi/
│ ├── __init__.py
│ ├── toolkit.py
│ └── data/
│ ├── cu.series.txt
│ ├── cu.item.txt
│ ├── cu.area.txt
│ ├── bls_cpi_weights_table1.csv
│ └── bls_cpi_weights_table2.csv
│
├── examples/
│ └── usage_examples.ipynb
│
├── .github/
│ └── workflows/
│ └── publish.yml
│
├── pyproject.toml
├── README.md
└── LICENSE
Important:
Before using most functions inflexcpi, you must first load the necessary data tables: Reference Requirements for code instructions
- These data tables are required inputs for key operations like matching series to weights and computing custom CPI indexes.
| Function | Purpose |
|---|---|
load_catalog_tables() |
Load CPI metadata: series, items, and areas |
load_weight_tables() |
Load cleaned BLS relative importance weight tables |
keyword_search_cpi() |
Search CPI catalog for keyword matches |
auto_select_series() |
Automatically select series IDs by keyword from catalog |
match_series_ids_to_weights() |
Fuzzy match series IDs to weighted categories |
assign_manual_weights() |
Manually assign weights to selected CPI series |
fetch_cpi_series_data() |
Fetch monthly CPI values from BLS API |
student_base_cpi() |
Generate a ready-to-use CPI index for a typical student consumption basket |
compute_custom_cpi_index() |
Compute CPI index using matched or manual weights |
compute_inflation_rate() |
Calculate year-over-year inflation from CPI index |
fetch_actual_cpi_series() |
Fetch official CPI series from BLS for comparison |
plot_custom_cpi() |
Plot custom CPI and optionally official CPI |
plot_inflation_comparison() |
Compare custom YoY inflation to official CPI inflation |
export_cpi_data() |
Export custom CPI index and weights to CSV files |
forecast_custom_cpi() |
Fit ARIMA model to custom CPI index and forecast future values |
| Function Name | Target Group | Key Features |
|---|---|---|
student_base_cpi() |
Students (college/university) | Focus on rent, food, tuition, public transit, and computers |
senior_base_cpi() |
Retirees / Older adults | Emphasizes housing, food at home, and medical care |
urban_low_income_cpi() |
Low-income urban households | High weight on rent, food at home, and public transit |
young_professional_cpi() |
Early-career professionals | Balanced mix of rent, dining out, computers, and transportation |
-
Inputs: None
-
Outputs:
DataFramewith merged BLS catalog (series, item, area) -
Description: Merges CPI series metadata into one DataFrame.
- Necessary to load to use following functions (reference requirements for details)
-
Inputs: None
-
Outputs: Two
DataFrames: Table 1 and Table 2 weights. -
Description: Loads and cleans official relative importance weights.
- Necessary to load to use following functions (reference requirements for details)
-
Inputs: Catalog DataFrame, search keyword, area filter (optional), result limit
-
Outputs: Filtered
DataFramewith series_id, item_name, and area_name -
Description: Finds matching series from the catalog based on keyword.
-
Inputs:
keywords(list of str): Keywords to search in the CPI item names.full_catalog(DataFrame): Loaded CPI catalog fromload_catalog_tables().area_filter(str): Optional filter for CPI region (default "U.S. city average").max_per_keyword(int): Max number of series returned per keyword.
-
Outputs:
list: A list of matched CPI series IDs.
-
Description: This function provides a simple way to automatically select relevant CPI series based on keyword searches. It filters by area and returns the most relevant series IDs.
-
Inputs: Series ID list, catalog, weights table, weight type, match cutoff
-
Outputs:
DataFramewith series_id, item_name, matched_category, weight, normalized_weight -
Description: Matches each series to its category and assigns normalized weights.
-
Inputs:
series_ids(list): List of CPI series IDsweights_dict(dict): Dictionary of user-defined weights keyed by series ID
-
Outputs:
DataFramewith columns:series_id,raw_weight, andnormalized_weight
-
Description:
Allows users to manually specify weights for each CPI series in their basket.
The output can be used directly withcompute_custom_cpi_index().
-
Inputs:
Series ID listyear rangeAPI key
-
Outputs:
DataFramewith year, month, value, series_id -
Description: Retrieves time series CPI values from the BLS API.
-
Inputs:
Matched DataFrameyear rangeAPI key
-
Outputs:
DataFramewith weighted CPI values over time -
Description: Computes index using weights to form a custom CPI.
-
Inputs:
CPI series IDyear rangeBLS API key
-
Outputs: Official CPI
DataFrame(date and value) -
Description: Retrieves a standard CPI series from BLS.
-
Inputs:
cpi_df(DataFrame): A DataFrame containing at least["date", "custom_cpi_index"]columns.
-
Outputs:
DataFrame: The input DataFrame with an additionalyoy_inflationcolumn (year-over-year % change).
-
Description:
Calculates the year-over-year inflation rate for each month using the custom CPI index.
plot_custom_cpi(custom_cpi_df, compare_to_actual=False, api_key=None, actual_series_id='CUSR0000SA0', title='Custom CPI Index Over Time')
-
Inputs:
Computed custom CPI DataFramecompare flagoptional API keyactual series IDplot title
-
Outputs: Matplotlib plot
-
Description: Visualizes the custom CPI trend and optionally overlays official CPI.
plot_inflation_comparison(custom_df, compare_to_actual=False, actual_series_id="CUSR0000SA0", api_key=None, title="Custom vs Official YoY Inflation")
-
Inputs:
custom_df(DataFrame): A DataFrame withdateandyoy_inflationcolumns (e.g. fromcompute_inflation_rate()).compare_to_actual(bool): Whether to plot official CPI YoY inflation alongside custom inflation.actual_series_id(str): BLS series ID for official CPI (default is "CUSR0000SA0" for All Items, U.S. city average).api_key(str): Your BLS API key. Required ifcompare_to_actual=True.title(str): Plot title.
-
Outputs:
- Displays a matplotlib line plot comparing custom and official YoY inflation.
-
Description: This function creates a visual comparison between the custom year-over-year inflation index and the official BLS CPI inflation index, if enabled.
Description:
Exports the custom CPI index and basket definition to CSV files for external use or archiving.
Inputs:
index_df(pandas.DataFrame): Output fromcompute_custom_cpi_index(). Must includedateandcustom_cpi_index.basket_df(pandas.DataFrame): Output frommatch_series_ids_to_weights()orassign_manual_weights().out_dir(str, optional): Folder path to save the files. Defaults to the current directory".".base_name(str, optional): Prefix for output filenames. Defaults to"custom_cpi".
Outputs:
- Saves two CSV files:
<base_name>_index.csv: CPI index values with dates.<base_name>_basket.csv: Series IDs, item names, matched categories, raw and normalized weights.
Description:
Forecasts future values of a computed custom CPI index using ARIMA modeling.
Inputs:
custom_cpi_df(pd.DataFrame): Output fromcompute_custom_cpi_index()containing"date"and"custom_cpi_index"columns.forecast_periods(int): Number of months to forecast (default is 12).order(tuple): ARIMA model order in the form(p, d, q)(default is(1, 1, 1)).plot(bool): Whether to plot the forecasted index alongside historical data (default isTrue).
Output:
pd.DataFrame: DataFrame containing the original custom CPI index plus forecasted values.
Behavior:
- Fits an ARIMA model using the
statsmodelslibrary to the provided CPI index. - Automatically extends the time series into the future and appends the forecasted CPI values.
- Optionally generates a line plot showing historical and projected CPI index.
-
Inputs:
weights_version(str, optional):"table1"(default) or"table2"area_code(str, optional): BLS area code, default is"0000"(U.S. city average)
-
Outputs:
DataFrameof monthly CPI index values for a representative student consumption basket
-
Description:
Generates a ready-to-use custom CPI for a predefined student basket, including rent, food, transit, tuition, and electronics.
Usesbuild_custom_cpi()internally with hardcoded weights and common BLS item codes reflecting student spending patterns.
-
Inputs:
weights_version(str, optional):"table1"(default) or"table2"area_code(str, optional): BLS area code, default is"0000"(U.S. city average)
-
Outputs:
DataFrameof monthly CPI index for a typical senior household
-
Description:
Constructs a CPI index emphasizing housing, food at home, medical care, and utilities—reflecting consumption priorities of older adults. Built usingbuild_custom_cpi()with fixed item weights.
-
Inputs:
weights_version(str, optional):"table1"(default) or"table2"area_code(str, optional): BLS area code, default is"0000"(U.S. city average)
-
Outputs:
DataFrameof monthly CPI index values for a low-income urban household
-
Description:
Estimates inflation for low-income renters in urban areas.
Heavy emphasis on rent, food at home, and public transportation.
Supports geographic customization using BLS area codes.
-
Inputs:
weights_version(str, optional):"table1"(default) or"table2"area_code(str, optional): BLS area code, default is"0000"(U.S. city average)
-
Outputs:
DataFrameof monthly CPI index values for a young professional’s basket
-
Description:
Simulates inflation exposure for early-career professionals.
Includes rent, dining out, technology, and public transit as major components.
An example Jupyter notebook demonstrating all core functions of the flexcpi package is available in the repository:
This notebook walks through:
- Loading catalog and weight tables
- Defining a custom CPI basket
- Computing weighted inflation
- Visualizing inflation trends
Sample Snippet
from flexcpi import (
load_catalog_tables, load_weight_tables,
keyword_search_cpi, match_series_ids_to_weights,
compute_custom_cpi_index, plot_custom_cpi
)
# Load data
catalog = load_catalog_tables()
table1, _ = load_weight_tables()
# Define your basket
series_ids = ["CUSR0000SAS2RS", "CUSR0000SA0L1", "CUSR0000SA311", "CUSR0000SAS24"]
matched = match_series_ids_to_weights(series_ids, catalog, table1, use="cpi_u_weight")
# Compute index
custom_cpi = compute_custom_cpi_index(matched, start_year=2019, end_year=2024, api_key="YOUR_BLS_KEY")
# Plot
plot_custom_cpi(custom_cpi, compare_to_actual=True, api_key="YOUR_BLS_KEY")This package is distributed under the MIT License. See LICENSE for details.
All contributions are welcome! Open an issue or pull request to:
- Add support for new CPI series or weighting schemes
- Improve performance of the matching logic
- Enhance visualization or reporting capabilities