{"id":19647066,"url":"https://github.com/idsia/bayesrecon","last_synced_at":"2025-04-28T15:31:16.282Z","repository":{"id":173945856,"uuid":"621389836","full_name":"IDSIA/bayesRecon","owner":"IDSIA","description":"Source of bayesRecon R package 📈","archived":false,"fork":false,"pushed_at":"2025-01-20T17:20:37.000Z","size":35035,"stargazers_count":6,"open_issues_count":0,"forks_count":1,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-04-21T02:54:46.296Z","etag":null,"topics":["reconciliation","timeseries"],"latest_commit_sha":null,"homepage":"https://idsia.github.io/bayesRecon/","language":"R","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/IDSIA.png","metadata":{"files":{"readme":"README.Rmd","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","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}},"created_at":"2023-03-30T15:06:07.000Z","updated_at":"2025-03-14T02:04:20.000Z","dependencies_parsed_at":"2023-12-01T17:26:21.215Z","dependency_job_id":"348c78e0-c613-4bb3-837e-dccf067488a0","html_url":"https://github.com/IDSIA/bayesRecon","commit_stats":null,"previous_names":["idsia/bayesrecon"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IDSIA%2FbayesRecon","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IDSIA%2FbayesRecon/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IDSIA%2FbayesRecon/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IDSIA%2FbayesRecon/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/IDSIA","download_url":"https://codeload.github.com/IDSIA/bayesRecon/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251338612,"owners_count":21573584,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["reconciliation","timeseries"],"created_at":"2024-11-11T14:42:14.475Z","updated_at":"2025-04-28T15:31:16.242Z","avatar_url":"https://github.com/IDSIA.png","language":"R","funding_links":[],"categories":[],"sub_categories":[],"readme":"---\noutput: github_document\n---\n\n\u003c!-- README.md is generated from README.Rmd. Please edit that file --\u003e\n\n```{r, include = FALSE}\nknitr::opts_chunk$set(\n  collapse = TRUE,\n  comment = \"#\u003e\",\n  fig.path = \"man/figures/README-\",\n  out.width = \"100%\"\n)\n```\n\n# bayesRecon: BAyesian reCONciliation of hierarchical forecasts\n\u003c!-- \n\u003cimg src=\"./man/figures/logo.png\" align=\"right\" /\u003e\n--\u003e\n\n\u003c!-- badges: start --\u003e\n[![R-CMD-check](https://github.com/IDSIA/bayesRecon/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/IDSIA/bayesRecon/actions/workflows/R-CMD-check.yaml)\n[![CRAN status](https://www.r-pkg.org/badges/version/bayesRecon)](https://CRAN.R-project.org/package=bayesRecon)\n[![](http://cranlogs.r-pkg.org/badges/grand-total/bayesRecon)](https://cran.r-project.org/package=bayesRecon)\n[![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)\n[![License: LGPL (\u003e= 3)](https://img.shields.io/badge/license-LGPL (\u003e= 3)-yellow.svg)](https://www.gnu.org/licences/lgpl-3.0)\n[![coverage](https://coveralls.io/repos/github/IDSIA/bayesRecon/badge.svg)](https://coveralls.io/github/IDSIA/bayesRecon)\n\u003c!-- badges: end --\u003e\n\nThe package `bayesRecon` implements several methods for probabilistic reconciliation of hierarchical time series forecasts.\n\nThe main functions are:\n\n * `reconc_gaussian`: reconciliation via conditioning of multivariate Gaussian base forecasts; \n    this is done analytically;\n * `reconc_BUIS`: reconciliation via conditioning of any probabilistic forecast via importance sampling;\n    this is the recommended option for non-Gaussian base forecasts;\n * `reconc_MCMC`: reconciliation via conditioning of discrete probabilistic forecasts via Markov Chain Monte Carlo;\n * `reconc_MixCond`: reconciliation via conditioning of mixed hierarchies, where \n    the upper forecasts are multivariate Gaussian and the bottom forecasts are discrete distributions;\n * `reconc_TDcond`: reconciliation via top-down conditioning of mixed hierarchies, where the upper forecasts are\n    multivariate Gaussian and the bottom forecasts are discrete distributions.\n \n## News\n:boom: [2024-05-29] Added `reconc_MixCond` and `reconc_TDcond` and the vignette \"Reconciliation of M5 hierarchy with mixed-type forecasts\". \n\n:boom: [2023-12-19] Added the vignette \"Properties of the reconciled distribution via conditioning\".\n\n:boom: [2023-08-23] Added the vignette \"Probabilistic Reconciliation via Conditioning with bayesRecon\". Added the `schaferStrimmer_cov` function.\n\n:boom: [2023-05-26] bayesRecon v0.1.0 is released!\n \n## Installation\n\nYou can install the **stable** version on [R\nCRAN](https://cran.r-project.org/package=bayesRecon)\n\n``` r\ninstall.packages(\"bayesRecon\", dependencies = TRUE)\n```\n\nYou can also install the **development** version from\n[Github](https://github.com/IDSIA/bayesRecon)\n\n``` r\n# install.packages(\"devtools\")\ndevtools::install_github(\"IDSIA/bayesRecon\", build_vignettes = TRUE, dependencies = TRUE)\n```\n\n\n## Usage\n\nLet us consider the minimal temporal hierarchy in the figure,\nwhere the bottom variables are the two 6-monthly forecasts and the upper variable is the yearly forecast. We denote the variables for the two semesters and the year by $S_1, S_2, Y$ respectively. \n\n```{r echo=FALSE, out.width='50%', fig.align='center'}\nknitr::include_graphics('./man/figures/minimal_hierarchy.png')\n```\n\nThe hierarchy is described by the *aggregation matrix* A,\nwhich can be obtained using the function `get_reconc_matrices`.\n\n```{r}\nlibrary(bayesRecon)\n\nrec_mat \u003c- get_reconc_matrices(agg_levels = c(1, 2), h = 2)\nA \u003c- rec_mat$A\nprint(A)\n```\n\n### Example 1: Poisson base forecasts\n\nWe assume that the base forecasts are Poisson distributed, with parameters given by $\\lambda_{Y} = 9$, $\\lambda_{S_1} = 2$, and $\\lambda_{S_2} = 4$. \n\n```{r}\nlambdaS1 \u003c- 2\nlambdaS2 \u003c- 4\nlambdaY \u003c- 9\nlambdas \u003c- c(lambdaY, lambdaS1, lambdaS2)\nn_tot = length(lambdas)\n\nbase_forecasts = list()\nfor (i in 1:n_tot) {\n  base_forecasts[[i]] = list(lambda = lambdas[i])\n}\n```\n\nWe recommend using the BUIS algorithm (Zambon et al., 2024) to sample from the reconciled distribution.\n\n```{r}\nbuis \u003c- reconc_BUIS(\n  A,\n  base_forecasts,\n  in_type = \"params\",\n  distr = \"poisson\",\n  num_samples = 100000,\n  seed = 42\n)\n\nsamples_buis \u003c- buis$reconciled_samples\n```\n\n\nSince there is a positive incoherence in the forecasts ($\\lambda_Y \u003e \\lambda_{S_1}+\\lambda_{S_2}$), the mean of the bottom reconciled forecast increases. We show below this behavior for $S_1$.  \n\n```{r, out.width='80%', fig.align='center'}\nreconciled_forecast_S1 \u003c- buis$bottom_reconciled_samples[1,]\nrange_forecats \u003c- range(reconciled_forecast_S1)\nhist(\n  reconciled_forecast_S1,\n  breaks = seq(range_forecats[1] - 0.5, range_forecats[2] + 0.5),\n  freq = F,\n  xlab = \"S_1\",\n  ylab = NULL,\n  main = \"base vs reconciled\"\n)\npoints(\n  seq(range_forecats[1], range_forecats[2]),\n  stats::dpois(seq(range_forecats[1], range_forecats[2]), lambda =\n                 lambdaS1),\n  pch = 16,\n  col = 4,\n  cex = 2\n)\n```\n\nThe blue circles represent the probability mass function of a Poisson with parameter $\\lambda_{S_1}$ plotted on top of the histogram of the reconciled bottom forecasts for $S_1$. Note how the histogram is shifted to the right.\n\nMoreover, while the base bottom forecast were assumed independent, the operation of reconciliation introduced a negative correlation between $S_1$ and $S_2$. We can visualize it with the plot below which shows the empirical correlations between the reconciled samples of $S_1$ and the reconciled samples of $S_2$. \n\n```{r,  out.width='80%', fig.align='center'}\nAA \u003c-\n  xyTable(buis$bottom_reconciled_samples[1, ],\n          buis$bottom_reconciled_samples[2, ])\nplot(\n  AA$x ,\n  AA$y ,\n  cex = AA$number * 0.001  ,\n  pch = 16 ,\n  col = rgb(0, 0, 1, 0.4) ,\n  xlab = \"S_1\" ,\n  ylab = \"S_2\" ,\n  xlim = range(buis$bottom_reconciled_samples[1, ]) ,\n  ylim = range(buis$bottom_reconciled_samples[2, ])\n)\n```\n\n\nWe also provide a function for sampling using Markov Chain Monte Carlo (Corani et al., 2023). \n\n```{r}\nmcmc = reconc_MCMC(\n  A,\n  base_forecasts,\n  distr = \"poisson\",\n  num_samples = 30000,\n  seed = 42\n)\n\nsamples_mcmc \u003c- mcmc$reconciled_samples\n```\n\n\n### Example 2: Gaussian base forecasts\n\nWe now assume that the base forecasts are Gaussian distributed, with parameters given by \n\n* $\\mu_{Y} = 9$, $\\mu_{S_1} = 2$, and $\\mu_{S_2} = 4$;\n* $\\sigma_{Y} = 2$, $\\sigma_{S_1} = 2$, and $\\sigma_{S_2} = 3$. \n\n```{r}\nmuS1 \u003c- 2\nmuS2 \u003c- 4\nmuY \u003c- 9\nmus \u003c- c(muY, muS1, muS2)\n\nsigmaS1 \u003c- 2\nsigmaS2 \u003c- 2\nsigmaY \u003c- 3\nsigmas \u003c- c(sigmaY, sigmaS1, sigmaS2)\n\nbase_forecasts = list()\nfor (i in 1:n_tot) {\n  base_forecasts[[i]] = list(mean = mus[[i]], sd = sigmas[[i]])\n}\n```\n\nWe use the BUIS algorithm to sample from the reconciled distribution:\n\n```{r}\nbuis \u003c- reconc_BUIS(\n  A,\n  base_forecasts,\n  in_type = \"params\",\n  distr = \"gaussian\",\n  num_samples = 100000,\n  seed = 42\n)\nsamples_buis \u003c- buis$reconciled_samples\nbuis_means \u003c- rowMeans(samples_buis)\n```\n\nIf the base forecasts are Gaussian, the reconciled distribution is still Gaussian and can be computed in closed form:\n\n```{r}\nSigma \u003c- diag(sigmas ^ 2)  #transform into covariance matrix\nanalytic_rec \u003c- reconc_gaussian(A,\n                                base_forecasts.mu = mus,\n                                base_forecasts.Sigma = Sigma)\nanalytic_means_bottom \u003c- analytic_rec$bottom_reconciled_mean\nanalytic_means_upper \u003c- A %*% analytic_means_bottom\nanalytic_means \u003c- rbind(analytic_means_upper,analytic_means_bottom)\n```\n\nThe base means of $Y$, $S_1$, and $S_2$ are\n`r round(mus,2)`.\n\nThe reconciled means obtained analytically are\n`r round(analytic_means,2)`,\nwhile the reconciled means obtained via BUIS are\n`r round(buis_means,2)`.\n\n\n## References\n\nCorani, G., Azzimonti, D., Augusto, J.P.S.C., Zaffalon, M. (2021). \n*Probabilistic Reconciliation of Hierarchical Forecast via Bayes’ Rule*. \nECML PKDD 2020. Lecture Notes in Computer Science, vol 12459.\n[DOI](https://doi.org/10.1007/978-3-030-67664-3_13)\n\nCorani, G., Azzimonti, D., Rubattu, N. (2024). \n*Probabilistic reconciliation of count time series*. \nInternational Journal of Forecasting 40 (2), 457-469.\n[DOI](https://doi.org/10.1016/j.ijforecast.2023.04.003)\n\nZambon, L., Azzimonti, D. \u0026 Corani, G. (2024). \n*Efficient probabilistic reconciliation of forecasts for real-valued and count time series*.\nStatistics and Computing 34 (1), 21.\n[DOI](https://doi.org/10.1007/s11222-023-10343-y)\n\nZambon, L., Agosto, A., Giudici, P., Corani, G. (2024). \n*Properties of the reconciled distributions for Gaussian and count forecasts*.\nInternational Journal of Forecasting 40 (4), 1438-1448.\n[DOI](https://doi.org/10.1016/j.ijforecast.2023.12.004)\n\nZambon, L., Azzimonti, D., Rubattu, N., Corani, G. (2024).\n*Probabilistic reconciliation of mixed-type hierarchical time series*.\nProceedings of the Fortieth Conference on Uncertainty in Artificial Intelligence,\nin Proceedings of Machine Learning Research 244:4078-4095. [Available here](https://proceedings.mlr.press/v244/zambon24a.html).\n\n## Contributors\n\n\u003c!-- prettier-ignore-start --\u003e\n\u003c!-- markdownlint-disable --\u003e\n\u003ctable\u003e\n  \u003ctbody\u003e\n    \u003ctr\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\n        \u003ca href=\"https://sites.google.com/view/darioazzimonti/home\"\u003e\n        \u003cimg src=\"https://github.com/dazzimonti.png\" width=\"100px;\" alt=\"Dario Azzimonti\" style=\"border-radius:50%;border:1px solid #646464;\"/\u003e\u003cbr /\u003e\n        \u003csub\u003e\u003cb\u003eDario Azzimonti\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\n        \u003csub\u003e(Maintainer)\u003c/sub\u003e\u003cbr /\u003e\n        \u003ca href=\"mailto:dario.azzimonti@gmail.com?subject=bayesRecon package!\"\u003edario.azzimonti@gmail.com\u003c/a\u003e\n      \u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\n        \u003ca href=\"#\"\u003e\n        \u003cimg src=\"https://github.com/nicorbtt.png\" width=\"100px;\" alt=\"Nicolò Rubattu\" style=\"border-radius:50%;border:1px solid #646464;\"/\u003e\u003cbr /\u003e\n        \u003csub\u003e\u003cb\u003eNicolò Rubattu\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\n        \u003ca href=\"mailto:nicolo.rubattu@idsia.ch?subject=bayesRecon package!\"\u003enicolo.rubattu@idsia.ch\u003c/a\u003e\n      \u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\n        \u003ca href=\"#\"\u003e\n        \u003cimg src=\"https://github.com/LorenzoZambon.png\" width=\"100px;\" alt=\"Lorenzo Zambon\" style=\"border-radius:50%;border:1px solid #646464;\"/\u003e\u003cbr /\u003e\n        \u003csub\u003e\u003cb\u003eLorenzo Zambon\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\n        \u003ca href=\"mailto:lorenzo.zambon@idsia.ch?subject=bayesRecon package!\"\u003elorenzo.zambon@idsia.ch\u003c/a\u003e\n      \u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\n        \u003ca href=\"https://sites.google.com/site/awerbhjkl678214/home\"\u003e\n        \u003cimg src=\"https://github.com/gcorani.png\" width=\"100px;\" alt=\"Giorgio Corani\" style=\"border-radius:50%;border:1px solid #646464;\"/\u003e\u003cbr /\u003e\n        \u003csub\u003e\u003cb\u003eGiorgio Corani\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\n        \u003ca href=\"mailto:giorgio.corani@idsia.ch\"\u003egiorgio.corani@idsia.ch\u003c/a\u003e\n      \u003c/td\u003e\n      \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\n\u003c!-- markdownlint-restore --\u003e\n\u003c!-- prettier-ignore-end --\u003e\n\n## Getting help\n\nIf you encounter a clear bug, please file a minimal reproducible example\non [GitHub](https://github.com/IDSIA/bayesRecon/issues).\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fidsia%2Fbayesrecon","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fidsia%2Fbayesrecon","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fidsia%2Fbayesrecon/lists"}