fred-quincast 0.1.6

A package for exploratory time series analysis and forecasting with FRED integration.

FRED Timeseries Analysis Package

This package is currently under consideration for publication in the Journal of Open Source Software (JOSS).

Table of Contents
1. Overview	2. FRED API Key Requirement
3. Installation	4. Package Structure
5. Techniques and Defaults	6. Function Descriptions
7. Summary    - Functions and Purposes    - Techniques Used	8. License
9. Contributing

FRED-Timeseries-Analysis-Package is a Python package for fetching, analyzing, and forecasting economic time series data, built on top of FRED, pandas, and statsmodels.

It includes:

• Data fetching and resampling
• Stationarity testing (ADF)
• ARIMA and SARIMA modeling
• Automatic model selection
• Jupyter-optimized visualizations

An example notebook is included in the examples/ folder.

FRED API Key Requirement

In order to fetch data from the FRED database, you must obtain a free FRED API key.

How to get a FRED API key:

1. Visit the FRED API Key Request page.
2. Create a free account if you do not already have one.
3. Request an API key from your account dashboard.
4. You will receive a personal API key that you can use in all fetch operations.

Where to use the API key:

• The fetch_series function requires your FRED API key as an input.
• Provide it once when calling fetch_series, and your data will load automatically.

Example usage:

from fredapi import Fred
fred = Fred(api_key='your-api-key-here')
fred_api_key = 'your-api-key-here'
gdp = fetch_series('GDP', start_date='2010-01-01', api_key=fred_api_key)

---

Package Structure

FRED-Timeseries-Analysis-Package/
│
├── fred_quincast/        <- the code folder (same name as PyPI project)
│   ├── __init__.py             <- makes it a package
│   ├── ts.py         <- (check_stationarity, check_stationarity_diff)

│
├── examples/                  <- Jupyter notebooks showing usage
│   └── basic_usage.ipynb
│
├── README.md                   <- describe project, functions
├── pyproject.toml              <- (for packaging)
├── requirements.txt            <- dependencies (fredapi, pandas, statsmodels, matplotlib, etc.)

---

Installation

You can install the package directly from PyPI:

pip install fred-quincast

Or install it from the GitHub repository:

pip install git+https://github.com/RoryQo/FRED-Timeseries-Analysis-Package.git

Requirements (automatically handled with pip install):

• fredapi
• pandas
• statsmodels
• matplotlib
• scikit-learn
• numpy

Make sure you have Python 3.8 or later.

Important Note:
The fredapi package must be installed and imported separately when using this toolkit.
While fredapi is included as a dependency, users must create and manage their own Fred object with their FRED API key when working with the toolkit’s functions.

from fredapi import Fred
fred = Fred(api_key='your-api-key-here')

---

Techniques and Defaults

• Missing Data Handling:
  By default, series are cleaned using .dropna(). When resampling, missing periods are filled by forward-fill (ffill) unless otherwise specified.

• Frequency Handling:
  Functions can infer time series frequency from the index or allow manual override (freq argument).

• Model Stability Checks:
  Automatic model selection (ARIMA and SARIMA) rejects unstable fits (e.g., AR/MA terms near 1, singular covariance matrices).

• Plotting:
  All forecasting functions plot observed + forecasted values unless plot=False.

---

Function Descriptions

Import

from fred_quincast.ts import (
    fetch_series,
    resample_series,
    log_diff,
    check_stationarity,
    check_stationarity_diff,
    quick_arima_forecast,
    quick_arima_forecast_testing,
    auto_arima_forecast,
    sarima_forecast,
    auto_sarima_forecast)
from fredapi import Fred

fetch_series

Description:
Fetches a single time series from the FRED database.

Inputs:

• series_id (str): The FRED series ID.
• start_date, end_date (optional, str or datetime): Date range.
• api_key (str): User’s FRED API key.

Outputs:

• pandas.Series indexed by dates.

Default behavior:
Entire available series is fetched if no date range is specified.

Reminder:
This function requires that you manage your own Fred object separately.
Ensure that fredapi is installed and imported before fetching data.
See the Installation section for guidance on how to properly import fredapi.

---

resample_series

Description:
Resamples a series to a new frequency.

Inputs:

• series (pandas.Series): Input series.
• freq (str): Target frequency ('Q', 'M', 'A', etc.).
• method (str): Fill method ('ffill' or 'bfill').

Outputs:

• pandas.Series resampled.

Default behavior:
Forward-fill (ffill) is used for missing values.

---

log_diff

Description:
Applies log transformation and differencing to stabilize variance and mean.

Inputs:

• series (pandas.Series): Input series.
• periods (int): Number of periods to difference.

Outputs:

• pandas.Series after log and differencing.

Default behavior:
1-period difference.

---

check_stationarity

Description:
Performs the Augmented Dickey-Fuller (ADF) test for stationarity.

Inputs:

• series (pandas.Series)
• alpha (float): Significance level (default 0.05).
• regression (str): Trend type ('c', 'ct', 'ctt', 'n').
• autolag (str): Criterion for lag selection ('AIC', 'BIC').
• resample_freq, resample_method (optional): If provided, resample before testing.

Outputs:

• Dictionary summarizing ADF test results.

Default behavior:
Original series used without resampling. Displays formatted summary and plot.

---

check_stationarity_diff

Description:
Same as check_stationarity but first differences the series before applying the ADF test.

Inputs:
Same as check_stationarity.

Outputs:

• Dictionary summarizing ADF test on differenced series.

Default behavior:
First difference applied automatically.

---

quick_arima_forecast

Description:
Fits an ARIMA model and forecasts future periods.

Inputs:

• ARIMA orders (p, d, q).
• forecast_steps (int): Number of periods ahead to forecast.

Outputs:

• Dictionary with model fit, forecast, AIC, BIC.

Default behavior:
Forecast 5 future periods, plot results.

---

quick_arima_forecast_testing

Description:
Splits data into train/test sets, fits ARIMA, forecasts, and evaluates RMSE.

Inputs:

• train_ratio (float): Fraction of data to train on (default 0.8).

Outputs:

• Dictionary with model, forecast, AIC, BIC, RMSE.

Default behavior:
80% train / 20% test split, forecast matching test set size.

---

auto_arima_forecast

Description:
Automatically searches ARIMA(p,d,q) models using AIC or BIC.

Inputs:

• Search ranges for p, d, q.
• ic (str): 'aic' or 'bic'.

Outputs:

• Best model, best order, forecast, AIC, BIC.

Default behavior:
Minimizes AIC, autoreject unstable models.

---

sarima_forecast

Description:
Manually fits SARIMA(p,d,q)x(P,D,Q,s) model.

Inputs:

• Non-seasonal (p,d,q) and seasonal (P,D,Q,s) orders.
• Forecast frequency (freq) optional.

Outputs:

• Model fit, forecast, AIC, BIC.

Default behavior:
No seasonality unless specified. Forecast 5 periods ahead.

---

auto_sarima_forecast

Description:
Automatically selects best SARIMA(p,d,q)x(P,D,Q,s) model.

Inputs:

• Search ranges for p, d, q, P, D, Q, and seasonality s.
• ic (str): 'aic' or 'bic'.

Outputs:

• Best model fit, best order, forecast, AIC, BIC.

Default behavior:
Default seasonality s=4 (quarterly). Autoreject unstable models.

---

Summary

Functions and Purposes

Function	Purpose
fetch_series	Fetch time series data from FRED
resample_series	Resample to new frequency
log_diff	Log-transform and difference a series
check_stationarity	ADF stationarity test
check_stationarity_diff	ADF test after differencing
quick_arima_forecast	Fit ARIMA and forecast
quick_arima_forecast_testing	ARIMA with train/test evaluation
auto_arima_forecast	Auto-select ARIMA model
sarima_forecast	Fit SARIMA manually
auto_sarima_forecast	Auto-select SARIMA model

Techniques Used

Feature	Behavior
Missing Data	.dropna() at start; resample() uses 'ffill'
Frequency	Infer from index if not provided, or manually set
Model Stability	Auto-reject AR/MA terms near unit root or singular covariance
Plotting	Enabled by default, can be turned off
Forecasting	Extends beyond last date, aligns future dates automatically

---

License

This project is licensed under the MIT License.
See the LICENSE file for details.

---

Contributing

Contributions are welcome!

If you would like to improve this package, feel free to open:

• An Issue (for bug reports, feature requests, or clarifications)
• A Pull Request (for proposed changes or additions)

When contributing, please:

• Keep code style clean and readable
• Follow the organization structure (group similar functions together)
• Include clear function descriptions (Inputs, Outputs, Purpose)
• Update the examples/ notebook if you add major functionality

For large changes, it is recommended to open an issue first to discuss the proposed approach.

---