{"id":37076558,"url":"https://github.com/roryqo/fred-timeseries-analysis-package","last_synced_at":"2026-01-14T09:00:08.462Z","repository":{"id":313829077,"uuid":"983825839","full_name":"RoryQo/FRED-Timeseries-Analysis-Package","owner":"RoryQo","description":"Python package for fetching, analyzing, and forecasting economic time series from FRED. Includes ARIMA modeling, stationarity tests, automatic model selection, and visualization tools.","archived":false,"fork":false,"pushed_at":"2025-11-06T23:20:15.000Z","size":759,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-11-07T01:13:38.163Z","etag":null,"topics":["econometrics","financial-data","forecasting","fred","pypi-package","time-series-analysis"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/RoryQo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-05-15T01:26:23.000Z","updated_at":"2025-11-06T23:20:18.000Z","dependencies_parsed_at":"2025-09-09T02:51:00.660Z","dependency_job_id":"fafec4e0-a2df-4e85-8034-d32dbf329fa8","html_url":"https://github.com/RoryQo/FRED-Timeseries-Analysis-Package","commit_stats":null,"previous_names":["roryqo/fred-timeseries-analysis-package"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/RoryQo/FRED-Timeseries-Analysis-Package","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RoryQo%2FFRED-Timeseries-Analysis-Package","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RoryQo%2FFRED-Timeseries-Analysis-Package/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RoryQo%2FFRED-Timeseries-Analysis-Package/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RoryQo%2FFRED-Timeseries-Analysis-Package/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RoryQo","download_url":"https://codeload.github.com/RoryQo/FRED-Timeseries-Analysis-Package/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RoryQo%2FFRED-Timeseries-Analysis-Package/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28414732,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T08:38:59.149Z","status":"ssl_error","status_checked_at":"2026-01-14T08:38:43.588Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["econometrics","financial-data","forecasting","fred","pypi-package","time-series-analysis"],"created_at":"2026-01-14T09:00:07.694Z","updated_at":"2026-01-14T09:00:08.421Z","avatar_url":"https://github.com/RoryQo.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003eFred-Quincast: A Python Package for Time Series Analysis with FRED\u003c/h1\u003e  \n \n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://pypi.org/project/fred-quincast/\"\u003e \n    \u003cimg src=\"https://img.shields.io/pypi/v/fred-quincast?label=PyPI\u0026logo=pypi\u0026logoColor=white\u0026color=blue\" alt=\"PyPI version\"\u003e\n  \u003c/a\u003e\n \n \n\n\u003ctable align=\"center\"\u003e\n  \u003ctr\u003e\n    \u003ctd colspan=\"2\" align=\"center\" style=\"background-color: white; color: black;\"\u003e\u003cstrong\u003eTable of Contents\u003c/strong\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n\n  \u003ctr\u003e\n    \u003ctd style=\"background-color: white; color: black; padding: 10px;\"\u003e\n      1. \u003ca href=\"#fred-timeseries-analysis-package\" style=\"color: black;\"\u003eOverview\u003c/a\u003e\u003cbr\u003e\n    \u003c/td\u003e\n    \u003ctd style=\"background-color: gray; color: black; padding: 10px;\"\u003e\n      2. \u003ca href=\"#fred-api-key-requirement\" style=\"color: black;\"\u003eFRED API Key Requirement\u003c/a\u003e\u003cbr\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\n  \u003ctr\u003e\n    \u003ctd style=\"background-color: gray; color: black; padding: 10px;\"\u003e\n      3. \u003ca href=\"#installation\" style=\"color: black;\"\u003eInstallation\u003c/a\u003e\u003cbr\u003e\n    \u003c/td\u003e\n    \u003ctd style=\"background-color: white; color: black; padding: 10px;\"\u003e\n      4. \u003ca href=\"#package-structure\" style=\"color: black;\"\u003ePackage Structure\u003c/a\u003e\u003cbr\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\n  \u003ctr\u003e\n    \u003ctd style=\"background-color: white; color: black; padding: 10px;\"\u003e\n      5. \u003ca href=\"#techniques-and-defaults\" style=\"color: black;\"\u003eTechniques and Defaults\u003c/a\u003e\u003cbr\u003e\n    \u003c/td\u003e\n    \u003ctd style=\"background-color: gray; color: black; padding: 10px;\"\u003e\n      6. \u003ca href=\"#function-descriptions\" style=\"color: black;\"\u003eFunction Descriptions\u003c/a\u003e\u003cbr\u003e\n  \u003c/tr\u003e\n\n  \u003ctr\u003e\n    \u003ctd style=\"background-color: gray; color: black; padding: 10px;\"\u003e\n      7. \u003ca href=\"#summary\" style=\"color: black;\"\u003eSummary\u003c/a\u003e\u003cbr\u003e\n      \u0026nbsp;\u0026nbsp;\u0026nbsp;- \u003ca href=\"#functions-and-purposes\" style=\"color: black;\"\u003eFunctions and Purposes\u003c/a\u003e\u003cbr\u003e\n      \u0026nbsp;\u0026nbsp;\u0026nbsp;- \u003ca href=\"#techniques-used\" style=\"color: black;\"\u003eTechniques Used\u003c/a\u003e\u003cbr\u003e\n    \u003c/td\u003e\n    \u003ctd style=\"background-color: white; color: black; padding: 10px;\"\u003e\n      8. \u003ca href=\"#license\" style=\"color: black;\"\u003eLicense\u003c/a\u003e\u003cbr\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\n  \u003ctr\u003e\n    \u003ctd colspan=\"2\" style=\"background-color: white; color: black; padding: 10px;\"\u003e\n \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp; \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\n      9. \u003ca href=\"#contributing\" style=\"color: black;\"\u003eContributing\u003c/a\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n\n\n\n\n**Fred-Quincast** is a Python package for fetching, analyzing, and forecasting economic time series data, built on top of [FRED](https://fred.stlouisfed.org/), `pandas`, and `statsmodels`.\n\nIt includes:\n- Data fetching and resampling\n- Stationarity testing (ADF)\n- ARIMA and SARIMA modeling\n- Automatic model selection\n- Jupyter-optimized visualizations\n\nAn example notebook is included in the `examples/` folder.\n\n## FRED API Key Requirement\n\nIn order to fetch data from the FRED database, you must obtain a free FRED API key.\n\n**How to get a FRED API key:**\n1. Visit the [FRED API Key Request page](https://fredaccount.stlouisfed.org/apikey).\n2. Create a free account if you do not already have one.\n3. Request an API key from your account dashboard.\n4. You will receive a personal API key that you can use in all fetch operations.\n\n**Where to use the API key:**\n- The `fetch_series` function requires your FRED API key as an input.\n- Provide it once when calling `fetch_series`, and your data will load automatically.\n\nExample usage:\n\n```python\nfrom fredapi import Fred\nfred = Fred(api_key='your-api-key-here')\nfred_api_key = 'your-api-key-here'\ngdp = fetch_series('GDP', start_date='2010-01-01', api_key=fred_api_key)\n```\n---\n\n## Package Structure\n\n```\nFRED-Timeseries-Analysis-Package/\n│\n├── fred_quincast/        \u003c- the code folder (same name as PyPI project)\n│   ├── __init__.py             \u003c- makes it a package\n│   ├── ts.py         \u003c- (check_stationarity, check_stationarity_diff)\n\n│\n├── examples/                  \u003c- Jupyter notebooks showing usage\n│   └── basic_usage.ipynb\n│\n├── README.md                   \u003c- describe project, functions\n├── pyproject.toml              \u003c- (for packaging)\n├── requirements.txt            \u003c- dependencies (fredapi, pandas, statsmodels, matplotlib, etc.)\n```\n\n---\n## Installation\n\nYou can install the package directly from PyPI:\n\n```python\npip install fred-quincast\n```\nOr install it from the GitHub repository:\n\n```bash\npip install git+https://github.com/RoryQo/FRED-Timeseries-Analysis-Package.git\n```\n\n**Requirements** (automatically handled with pip install):\n\n- `fredapi`\n- `pandas`\n- `statsmodels`\n- `matplotlib`\n- `scikit-learn`\n- `numpy`\n\nMake sure you have Python 3.8 or later.\n\n\n\u003e **Important Note:**  \nThe `fredapi` package must be installed and imported separately when using this toolkit.  \nWhile `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.\n\n```python\nfrom fredapi import Fred\nfred = Fred(api_key='your-api-key-here')\n```\n\n\n---\n\n## Techniques and Defaults\n\n- **Missing Data Handling:**  \n  By default, series are cleaned using `.dropna()`. When resampling, missing periods are filled by **forward-fill (`ffill`)** unless otherwise specified.\n\n- **Frequency Handling:**  \n  Functions can **infer** time series frequency from the index or allow **manual override** (`freq` argument).\n\n- **Model Stability Checks:**  \n  Automatic model selection (ARIMA and SARIMA) rejects unstable fits (e.g., AR/MA terms near 1, singular covariance matrices).\n\n- **Plotting:**  \n  All forecasting functions plot observed + forecasted values unless `plot=False`.\n\n---\n\n#  Function Descriptions\n\n### `Import`\n\n```python\nfrom fred_quincast.ts import (\n    fetch_series,\n    resample_series,\n    log_diff,\n    check_stationarity,\n    check_stationarity_diff,\n    quick_arima_forecast,\n    quick_arima_forecast_testing,\n    auto_arima_forecast,\n    sarima_forecast,\n    auto_sarima_forecast)\nfrom fredapi import Fred\n```\n\n### `fetch_series`\n\n**Description:**  \nFetches a single time series from the FRED database.\n\n**Inputs:**\n- `series_id` (str): The FRED series ID.\n- `start_date`, `end_date` (optional, str or datetime): Date range.\n- `api_key` (str): User’s FRED API key.\n\n**Outputs:**\n- `pandas.Series` indexed by dates.\n\n**Default behavior:**  \nEntire available series is fetched if no date range is specified.\n\n**Reminder:**  \nThis function requires that you manage your own `Fred` object separately.  \nEnsure that `fredapi` is installed and imported before fetching data.  \nSee the **Installation** section for guidance on how to properly import `fredapi`.\n\n---\n\n### `resample_series`\n\n**Description:**  \nResamples a series to a new frequency.\n\n**Inputs:**\n- `series` (pandas.Series): Input series.\n- `freq` (str): Target frequency (`'Q'`, `'M'`, `'A'`, etc.).\n- `method` (str): Fill method (`'ffill'` or `'bfill'`).\n\n**Outputs:**\n- `pandas.Series` resampled.\n\n**Default behavior:**  \nForward-fill (`ffill`) is used for missing values.\n\n---\n\n### `log_diff`\n\n**Description:**  \nApplies log transformation and differencing to stabilize variance and mean.\n\n**Inputs:**\n- `series` (pandas.Series): Input series.\n- `periods` (int): Number of periods to difference.\n\n**Outputs:**\n- `pandas.Series` after log and differencing.\n\n**Default behavior:**  \n1-period difference.\n\n---\n\n\n### `check_stationarity`\n\n**Description:**  \nPerforms the Augmented Dickey-Fuller (ADF) test for stationarity.\n\n**Inputs:**\n- `series` (pandas.Series)\n- `alpha` (float): Significance level (default 0.05).\n- `regression` (str): Trend type ('c', 'ct', 'ctt', 'n').\n- `autolag` (str): Criterion for lag selection ('AIC', 'BIC').\n- `resample_freq`, `resample_method` (optional): If provided, resample before testing.\n\n**Outputs:**\n- Dictionary summarizing ADF test results.\n\n**Default behavior:**  \nOriginal series used without resampling. Displays formatted summary and plot.\n\n---\n\n### `check_stationarity_diff`\n\n**Description:**  \nSame as `check_stationarity` but first differences the series before applying the ADF test.\n\n**Inputs:**  \nSame as `check_stationarity`.\n\n**Outputs:**\n- Dictionary summarizing ADF test on differenced series.\n\n**Default behavior:**  \nFirst difference applied automatically.\n\n---\n\n### `quick_arima_forecast`\n\n**Description:**  \nFits an ARIMA model and forecasts future periods.\n\n**Inputs:**\n- ARIMA orders (`p`, `d`, `q`).\n- `forecast_steps` (int): Number of periods ahead to forecast.\n\n**Outputs:**\n- Dictionary with model fit, forecast, AIC, BIC.\n\n**Default behavior:**  \nForecast 5 future periods, plot results.\n\n---\n\n### `quick_arima_forecast_testing`\n\n**Description:**  \nSplits data into train/test sets, fits ARIMA, forecasts, and evaluates RMSE.\n\n**Inputs:**\n- `train_ratio` (float): Fraction of data to train on (default 0.8).\n\n**Outputs:**\n- Dictionary with model, forecast, AIC, BIC, RMSE.\n\n**Default behavior:**  \n80% train / 20% test split, forecast matching test set size.\n\n---\n\n### `auto_arima_forecast`\n\n**Description:**  \nAutomatically searches ARIMA(p,d,q) models using AIC or BIC.\n\n**Inputs:**\n- Search ranges for p, d, q.\n- `ic` (str): 'aic' or 'bic'.\n\n**Outputs:**\n- Best model, best order, forecast, AIC, BIC.\n\n**Default behavior:**  \nMinimizes AIC, autoreject unstable models.\n\n---\n\n\n### `sarima_forecast`\n\n**Description:**  \nManually fits SARIMA(p,d,q)x(P,D,Q,s) model.\n\n**Inputs:**\n- Non-seasonal (`p,d,q`) and seasonal (`P,D,Q,s`) orders.\n- Forecast frequency (`freq`) optional.\n\n**Outputs:**\n- Model fit, forecast, AIC, BIC.\n\n**Default behavior:**  \nNo seasonality unless specified. Forecast 5 periods ahead.\n\n---\n\n### `auto_sarima_forecast`\n\n**Description:**  \nAutomatically selects best SARIMA(p,d,q)x(P,D,Q,s) model.\n\n**Inputs:**\n- Search ranges for p, d, q, P, D, Q, and seasonality s.\n- `ic` (str): 'aic' or 'bic'.\n\n**Outputs:**\n- Best model fit, best order, forecast, AIC, BIC.\n\n**Default behavior:**  \nDefault seasonality `s=4` (quarterly). Autoreject unstable models.\n\n---\n\n# Summary\n\n\n## Functions and Purposes\n\n| Function | Purpose |\n|:---------|:--------|\n| fetch_series | Fetch time series data from FRED |\n| resample_series | Resample to new frequency |\n| log_diff | Log-transform and difference a series |\n| check_stationarity | ADF stationarity test |\n| check_stationarity_diff | ADF test after differencing |\n| quick_arima_forecast | Fit ARIMA and forecast |\n| quick_arima_forecast_testing | ARIMA with train/test evaluation |\n| auto_arima_forecast | Auto-select ARIMA model |\n| sarima_forecast | Fit SARIMA manually |\n| auto_sarima_forecast | Auto-select SARIMA model |\n\n\n\n## Techniques Used\n\n| Feature | Behavior |\n|:--------|:---------|\n| Missing Data | `.dropna()` at start; `resample()` uses `'ffill'` |\n| Frequency | Infer from index if not provided, or manually set |\n| Model Stability | Auto-reject AR/MA terms near unit root or singular covariance |\n| Plotting | Enabled by default, can be turned off |\n| Forecasting | Extends beyond last date, aligns future dates automatically |\n\n\n---\n\n## License\n\nThis project is licensed under the MIT License.  \nSee the `LICENSE` file for details.\n\n---\n\n## Contributing\n\nContributions are welcome!\n\nIf you would like to improve this package, feel free to open:\n- An Issue (for bug reports, feature requests, or clarifications)\n- A Pull Request (for proposed changes or additions)\n\nWhen contributing, please:\n- Keep code style clean and readable\n- Follow the organization structure (group similar functions together)\n- Include clear function descriptions (Inputs, Outputs, Purpose)\n- Update the `examples/` notebook if you add major functionality\n\nFor large changes, it is recommended to open an issue first to discuss the proposed approach.\n\n\n---\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Froryqo%2Ffred-timeseries-analysis-package","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Froryqo%2Ffred-timeseries-analysis-package","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Froryqo%2Ffred-timeseries-analysis-package/lists"}