{"id":15293005,"url":"https://github.com/arthurleroy/magmaclustr","last_synced_at":"2025-07-25T16:37:14.413Z","repository":{"id":39582114,"uuid":"381543854","full_name":"ArthurLeroy/MagmaClustR","owner":"ArthurLeroy","description":"Clustering and Predictions with Multi-Task Gaussian Processes","archived":false,"fork":false,"pushed_at":"2024-12-21T16:58:33.000Z","size":775414,"stargazers_count":16,"open_issues_count":0,"forks_count":7,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-27T03:22:30.484Z","etag":null,"topics":["gaussian-processes","multi-task-learning","multi-task-prediction","r","r-package"],"latest_commit_sha":null,"homepage":"https://arthurleroy.github.io/MagmaClustR/","language":"R","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ArthurLeroy.png","metadata":{"files":{"readme":"README.Rmd","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}},"created_at":"2021-06-30T01:43:38.000Z","updated_at":"2025-03-21T03:50:29.000Z","dependencies_parsed_at":"2023-10-02T21:17:32.538Z","dependency_job_id":"8c2abe46-8444-4441-b331-e5dc11ba5d7c","html_url":"https://github.com/ArthurLeroy/MagmaClustR","commit_stats":{"total_commits":118,"total_committers":3,"mean_commits":"39.333333333333336","dds":0.09322033898305082,"last_synced_commit":"71fe202a76b1512a430e90f2cc897161a39c4e3a"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ArthurLeroy%2FMagmaClustR","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ArthurLeroy%2FMagmaClustR/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ArthurLeroy%2FMagmaClustR/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ArthurLeroy%2FMagmaClustR/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ArthurLeroy","download_url":"https://codeload.github.com/ArthurLeroy/MagmaClustR/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248711169,"owners_count":21149306,"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":["gaussian-processes","multi-task-learning","multi-task-prediction","r","r-package"],"created_at":"2024-09-30T16:37:15.046Z","updated_at":"2025-04-13T12:21:02.567Z","avatar_url":"https://github.com/ArthurLeroy.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  fig.align = 'center',\n  dpi = 300,\n  out.width = \"80%\"\n)\n```\n\n# MagmaClustR \u003cimg src=\"man/figures/logo.png\" align=\"right\" width=\"120\" /\u003e\n\n\u003c!-- badges: start --\u003e\n[![R-CMD-check](https://github.com/ArthurLeroy/MagmaClustR/actions/workflows/R-CMD-check.yaml/badge.svg?branch=master)](https://github.com/ArthurLeroy/MagmaClustR/actions/workflows/R-CMD-check.yaml)\n[![CRAN status](https://www.r-pkg.org/badges/version/MagmaClustR)](https://CRAN.R-project.org/package=MagmaClustR)\n[![Lifecycle: stable](https://img.shields.io/badge/lifecycle-stable-brightgreen.svg)](https://lifecycle.r-lib.org/articles/stages.html#stable)\n[![codecov](https://codecov.io/gh/ArthurLeroy/MagmaClustR/branch/master/graph/badge.svg?token=KH7SOKOLKX)](https://app.codecov.io/gh/ArthurLeroy/MagmaClustR)\n\u003c!-- badges: end --\u003e\n\nThe *MagmaClustR* package implements two main algorithms, called Magma (*Leroy et al., 2022*) and MagmaClust (*Leroy et al., 2020*), using a multi-task Gaussian processes (GP) model to perform predictions for supervised learning problems. Applications involving functional data, such as multiple time series, are particularly well-handled. Theses approaches leverage the learning of cluster-specific mean processes, which are common across similar tasks, to provide enhanced prediction performances (even far from data points) at a linear computational cost (in the number of tasks). MagmaClust is a generalisation of Magma where the tasks are simultaneously clustered into groups, each being associated to a specific mean process. User-oriented functions in the package are decomposed into training, prediction and plotting functions. Some basic features of standard GPs are also implemented.\n\nLeroy, A., Latouche, P., Guedj, B., Gey, S. MAGMA: inference and prediction using multi-task Gaussian processes with common mean. *Mach Learn* **111**, 1821–1849 (2022). https://doi.org/10.1007/s10994-022-06172-1\n\nLeroy, A., Latouche, P., Guedj, B., \u0026 Gey, S. Cluster-Specific Predictions with Multi-Task Gaussian Processes. *JMLR* 24(5):1−49, (2023). https://www.jmlr.org/papers/v24/20-1321.html\n\n## Installation\n\nYou can install the released version of MagmaClustR from [CRAN](https://CRAN.R-project.org) with:\n\n``` r\ninstall.packages(\"MagmaClustR\")\n```\n\nAnd the development version from [GitHub](https://github.com/) with:\n\n``` r\n# install.packages(\"devtools\")\ndevtools::install_github(\"ArthurLeroy/MagmaClustR\")\n```\n## Example: Magma\n\nHere is a basic example on how to simulate a dataset with the adequate format, then train a Magma model and use it to perform predictions.\n\n### Data generation\n```{r generate data Magma}\nlibrary(MagmaClustR)\n## Simulate a dataset with 11 individuals, each observed at 10 input locations\nset.seed(17)\ndata_magma \u003c- simu_db(M = 11, N = 10, common_input = FALSE)\n## Split individuals into training and prediction sets, and define test points\nmagma_train \u003c- data_magma %\u003e% subset(ID %in% 1:10)\nmagma_pred \u003c- data_magma %\u003e% subset(ID == 11) %\u003e% head(7)\nmagma_test \u003c- data_magma %\u003e% subset(ID == 11) %\u003e% tail(3)\n\ndata_magma\n```\nAs displayed above, any dataset processed in MagmaClustR should provide columns named `ID`, `Input`, and `Output`. Any additional column would be treated as a covariate (and thus define multi-dimensional inputs). \n\n### Training and prediction with Magma \n\n```{r train_and_predict_Magma}\nmodel \u003c- train_magma(data = magma_train, common_hp = F)\n\npred  \u003c- pred_magma(data = magma_pred,\n                    trained_model = model, \n                    grid_inputs = seq(0,10, 0.01))\n```\n\nNote that the `common_hp` and `grid_inputs` arguments are optional. They respectively indicate that a specific set of hyper-parameters is trained for each curve, and control the grid of values on which the prediction is performed.\n\n### Display the resulting predictions\n\nSeveral other arguments are available in dedicated plotting functions to offer extended options in the display of results. For instance, the GP predictions can be represented as a heatmap of probabilities:\n\n```{r display_Magma}\nplot_gp(pred_gp = pred,\n        data = magma_pred,\n        data_train = magma_train,\n        prior_mean = model$hyperpost$mean,\n        heatmap = TRUE) \n```\n\nAdditionally, it is also possible to create animated representations by using functions that generate GIFs. For instance, below, the true testing points have been represented as red dots and we can observe how the prediction evolves as we add more data points to our prediction dataset.\n\n```{r gif_Magma, message=FALSE}\n\npred_gif  \u003c- pred_gif(data = magma_pred,\n                      trained_model = model,\n                      grid_inputs = seq(0, 10, 0.01))\n\nplot_gif(pred_gp = pred_gif,\n         data = magma_pred,\n         data_train = magma_train,\n         prior_mean = model$hyperpost$mean) + \n  ggplot2::geom_point(data = magma_test,\n                      ggplot2::aes(x = Input, y = Output),\n                      color = 'red', size = 2)\n```\n\n## Example: MagmaClust\n\nHere is a basic example on how to simulate a dataset with the adequate format, then train a MagmaClust model and use it to perform simultaneous clustering and predictions.\n\n### Data generation\n\n```{r generate data MagmaClust}\n## Simulate a dataset containing 3 clusters of 4 individuals, each observed at 10 input locations\nset.seed(4) \ndata_magmaclust \u003c- simu_db(M = 4, N = 10, K = 3, common_input = FALSE) \n## Split individuals into training and prediction sets, and define test points\nlist_ID = unique(data_magmaclust$ID)\nmagmaclust_train \u003c- data_magmaclust %\u003e% subset(ID %in% list_ID[1:11])\nmagmaclust_pred \u003c- data_magmaclust %\u003e% subset(ID == list_ID[12]) %\u003e% head(5)\nmagmaclust_test \u003c- data_magmaclust %\u003e% subset(ID == list_ID[12]) %\u003e% tail(5)\n\ndata_magmaclust\n```\n\n\n### Training and prediction with MagmaClust\n\n```{r train_and_predict_MagmaClust, message=FALSE}\nmodel_clust \u003c- train_magmaclust(data = magmaclust_train)\n\npred_clust  \u003c- pred_magmaclust(data = magmaclust_pred,\n                               trained_model = model_clust,\n                               grid_inputs = seq(0, 10, 0.01), \n                               plot = FALSE)\n```\n\n\n### Display the resulting predictions\n\nAs before, a specific plotting function is provided. For MagmaClust, we advise to use the heatmap representation in priority, as a mixture of GPs may not be unimodal in general (and thus prevents the definition of Credible Interval).\n\n```{r display_MagmaClust, message=FALSE}\n## Allocate individuals to their most probable cluster to colour them by clusters afterwards\ndata_train_with_clust = data_allocate_cluster(model_clust)\n\nplot_magmaclust(pred = pred_clust,\n                cluster = \"all\",\n                data = magmaclust_pred,\n                data_train = data_train_with_clust,\n                col_clust = TRUE,\n                prior_mean = model_clust$hyperpost$mean,\n                y_grid = seq(10, 55, 0.5),\n                heatmap = TRUE) \n```\n\n## Example: in 2-dimensions\n\nAlthough unidimensional-input problems are easier to visualise, both Magma and MagmaClust can also be applied with as many covariates as desired in the model.\n\n### Data generation\n```{r generate data 2-D}\n## Dataset with 11 individuals, 10 reference input locations and a covariate\nset.seed(5) \ndata_dim2 \u003c- simu_db(M = 11, N = 10, covariate = TRUE) \n## Split individuals into training and prediction sets, and define test points\ndim2_train \u003c- data_dim2 %\u003e% subset(ID %in% 1:10)\ndim2_pred \u003c- data_dim2 %\u003e% subset(ID == 11)\n\ndata_dim2\n```\n\n### Training and prediction with Magma \n\n```{r train_and_predict_Magma_in_2-D, message=FALSE, warning=FALSE}\nmodel_dim2 \u003c- train_magma(data = dim2_train)\n\npred_dim2  \u003c- pred_magma(data = dim2_pred,\n                         trained_model = model_dim2)\n```\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farthurleroy%2Fmagmaclustr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farthurleroy%2Fmagmaclustr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farthurleroy%2Fmagmaclustr/lists"}