{"id":32206239,"url":"https://github.com/inesortega/neuralgam","last_synced_at":"2025-10-22T05:09:50.473Z","repository":{"id":192999161,"uuid":"610689789","full_name":"inesortega/neuralGAM","owner":"inesortega","description":"An R package which provides a a neural network framework based on Generalized Additive Models","archived":false,"fork":false,"pushed_at":"2025-10-15T07:00:16.000Z","size":4566,"stargazers_count":2,"open_issues_count":1,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-10-15T19:44:07.884Z","etag":null,"topics":["deep-neural-networks","explainable-ai","gam","gann","generalized-additive-models","generalized-additive-neural-network","r","r-package","self-explanatory-ml","xai"],"latest_commit_sha":null,"homepage":"https://inesortega.github.io/neuralGAM/","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/inesortega.png","metadata":{"files":{"readme":"README.md","changelog":"NEWS.md","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,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-03-07T09:33:10.000Z","updated_at":"2025-10-08T20:07:18.000Z","dependencies_parsed_at":"2025-07-28T08:23:18.054Z","dependency_job_id":"11e6419e-f618-4999-a195-65d1b0606b3c","html_url":"https://github.com/inesortega/neuralGAM","commit_stats":null,"previous_names":["inesortega/neuralgam"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/inesortega/neuralGAM","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inesortega%2FneuralGAM","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inesortega%2FneuralGAM/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inesortega%2FneuralGAM/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inesortega%2FneuralGAM/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/inesortega","download_url":"https://codeload.github.com/inesortega/neuralGAM/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inesortega%2FneuralGAM/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":280383000,"owners_count":26321423,"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","status":"online","status_checked_at":"2025-10-22T02:00:06.515Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["deep-neural-networks","explainable-ai","gam","gann","generalized-additive-models","generalized-additive-neural-network","r","r-package","self-explanatory-ml","xai"],"created_at":"2025-10-22T05:09:46.263Z","updated_at":"2025-10-22T05:09:50.465Z","avatar_url":"https://github.com/inesortega.png","language":"R","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!-- badges: start --\u003e\n[![R-CMD-check](https://github.com/inesortega/NeuralGAM/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/inesortega/NeuralGAM/actions/workflows/R-CMD-check.yaml)\n[![test-coverage](https://github.com/inesortega/NeuralGAM/actions/workflows/test-coverage.yaml/badge.svg)](https://github.com/inesortega/NeuralGAM/actions/workflows/test-coverage.yaml)\n[![Codecov test coverage](https://codecov.io/gh/inesortega/neuralGAM/branch/main/graph/badge.svg)](https://app.codecov.io/gh/inesortega/neuralGAM?branch=main)\n[![CRAN Downloads](https://cranlogs.r-pkg.org/badges/grand-total/neuralGAM)](https://cranlogs.r-pkg.org/downloads/total/2023-09-01:2024-09-25/neuralGAM)\n\u003c!-- badges: end --\u003e\n\n# neuralGAM: Interpretable Neural Network Based on Generalized Additive Models\n\nneuralGAM is a fully explainable Deep Learning framework based on Generalized Additive Models, which trains a different neural network to estimate the contribution of each feature to the response variable. \n\nThe networks are trained independently leveraging the local scoring and backfitting algorithms to ensure that the Generalized Additive Model converges and it is additive. The resultant Neural Network is a highly accurate and interpretable deep learning model, which can be used for high-risk AI practices where decision-making should be based on accountable and interpretable algorithms. \n\nThe full methodology of the method to train Generalized Additive Models using Deep Neural Networks is published in the following paper: \n\n\u003e Ortega-Fernandez, I., Sestelo, M. \u0026 Villanueva, N.M. _Explainable generalized additive neural networks with independent neural network training_. Statistics \u0026 Computing 34, 6 (2024). https://doi.org/10.1007/s11222-023-10320-5\n\nand is also available in Python at the following [Github repository](https://github.com/inesortega/pyNeuralGAM/).\n  \n## Requirements\n\nneuralGAM is based on Deep Neural Networks, and depends on Tensorflow and Keras packages. Therefore, a working Python\u003e3.10 installation with those packages installed is required. \n\nWe provide a helper function to get a working python installation from RStudio, which creates a miniconda environment with all the required packages.   \n\n```r\nlibrary(neuralGAM)\ninstall_neuralGAM()\n```\n\n## Quick start\n\n### Fit a neuralGAM with deep smooth terms\n\nIn the following example, we use synthetic data to showcase the performance of neuralGAM by fitting a model with a single layer with 1024 units.\n\n```r\nn \u003c- 5000\nseed \u003c- 42\nset.seed(seed)\n\nx1 \u003c- runif(n, -2.5, 2.5)\nx2 \u003c- runif(n, -2.5, 2.5)\nx3 \u003c- runif(n, -2.5, 2.5)\n\nf1 \u003c- x1**2\nf2 \u003c- 2 * x2\nf3 \u003c- sin(x3)\nf1 \u003c- f1 - mean(f1)\nf2 \u003c- f2 - mean(f2)\nf3 \u003c- f3 - mean(f3)\n\neta0 \u003c- 2 + f1 + f2 + f3\ny \u003c- eta0 + rnorm(n, 0.25)\ntrain \u003c- data.frame(x1, x2, x3, y)\n\nngam \u003c- neuralGAM(\n  y ~ s(x1) + x2 + s(x3), \n  data = train,\n  num_units = 128, family = \"gaussian\",\n  activation = \"relu\",\n  learning_rate = 0.001, bf_threshold = 0.001,\n  max_iter_backfitting = 10, max_iter_ls = 10,\n  uncertainty_method = \"epistemic\", forward_passes = 100,\n  seed = seed\n)\n\nsummary(ngam)\n```\n\nYou can then use the `plot` function to visualize the learnt partial effects: \n\n```r\nplot(ngam)\n```\nOr the custom `autoplot` function for more advanced graphics using the ggplot2 library, including Confidence Intervals (if available)\n\n```r\nautoplot(ngam, which=\"terms\", term = \"x1\", interval = \"confidence\")\n```\nTo obtain predictions from new data, use the `predict` function: \n\n```r\nn \u003c- 5000\nx1 \u003c- runif(n, -2.5, 2.5)\nx2 \u003c- runif(n, -2.5, 2.5)\nx3 \u003c- runif(n, -2.5, 2.5)\n\ntest \u003c- data.frame(x1, x2, x3)\n\n# Obtain linear predictor\neta \u003c- predict(ngam, newdata = test, type = \"link\")\n\n# Obtain predicted response using se.fit = TRUE to obtain standard errors:\nyhat \u003c- predict(ngam, newdata = test, type = \"response\", se.fit = TRUE)\n\nhead(yhat$fit)\nhead(yhat$se.fit)\n\n# Obtain each component of the linear predictor \nterms \u003c- predict(ngam, newdata = test, type = \"terms\")\n\n# Obtain only certain terms: \nterms \u003c- predict(ngam, newdata = test, type = \"terms\", terms = c(\"x1\", \"x2\"))\n```\n\n### Per-term configuration\n\n`neuralGAM` from version 2.0 allows to specify hyperparameters per smooth term inside s(), overriding global defaults, and the `summary()` now print each smooth term configuraion:\n\n```r\nngam \u003c- neuralGAM(\n  y ~ s(x1, num_units = 32) + x2 + s(x3, activation = \"tanh\"), \n  data = train,\n  num_units = 64,  # default for terms without explicit num_units\n  seed = seed\n)\n```\n\nPer-term configuration supports custom initializers and regularizers for both weights and biases, enabling fine control over model complexity and stability. \nFor example, you can set one of the neural networks to use L2 regularization and He initialization using Keras functions directly (i.e. `keras::regularizer_l1()`). \n\nThis is useful for:\n\n- Preventing overfitting (L1/L2 regularization)\n- Stabilizing training for deep smooth terms (He/Glorot initializers)\n- Applying different constraints to specific smooth terms (for example, more complex functions might require more complex / deeper architectures)\n\n```r\nngam \u003c- neuralGAM(\n  y ~ s(\n         x1, \n         kernel_initializer = keras::initializer_he_normal(),\n         bias_initializer   = keras::initializer_zeros(),\n         kernel_regularizer = keras::regularizer_l2(0.01),\n         bias_regularizer   = keras::regularizer_l1(0.001)\n       ) +\n       s(x2),\n  data = train,\n  num_units = 64,\n  activation = \"relu\",\n  seed = seed\n)\n```\n\nThe `summary()` now prints each smooth terms configuration and the essential parameters of each network's architecture. \n\n### Confidence Intervals\n\nEnable confidence intervals by setting `uncertainty_method` and specifying a sensitivity level via `alpha` (i.e. `0.05` for 95% coverage). For epistemic variance, `forward_passes \u003e 150` is recommended.\n\n```r\nngam \u003c- neuralGAM(\n  y ~ s(x1) + s(x2),\n  data = train,\n  uncertainty_method = \"epistemic\",\n  forward_passes = 100,\n  alpha = 0.05,\n  num_units = 1024,\n  seed = seed\n)\npred \u003c- predict(ngam, newdata = test, type = \"response\")\nhead(pred)\n```\n\n### Cross-validation and Training History\n\nYou can monitor the validation loss during training using the `validation_split` parameter. You can then visualize the how the loss evolves per backfitting iteration using the `plot_history()` function. \n\n```r\nngam \u003c- neuralGAM(y ~ s(x1) + x2 + s(x3),\n                  data = train,\n                  num_units = 1024, family = \"gaussian\",\n                  activation = \"relu\",\n                  learning_rate = 0.001, bf_threshold = 0.001,\n                  max_iter_backfitting = 10, max_iter_ls = 10,\n                  validation_split = 0.2,\n                  seed = seed)\n\n# Plot loss per backfitting iteration\nplot_history(ngam)\nplot_history(ngam, select = \"x1\")       # Plot just x1\nplot_history(ngam, metric = \"val_loss\") # Plot only validation loss\n```\n\n### Detailed model inspection\n\nThe enhanced summary() shows:\n\n- Family, formula, sample size, intercept, deviance explained, MSE\n- Per-term hyperparameters (units, activation, learning rate, initializers, regularizers)\n- Layer configuration for each Keras model\n- Linear coefficients (if a parametric part exists)\n- Compact training history\n\nMoreover, after fitting a `neuralGAM` model, it is important to evaluate whether the model assumptions are reasonable and whether predictions are well calibrated.  \n\nThe helper function `diagnose()` provides a **2×2 diagnostic panel** similar to `gratia::appraise()` for `mgcv` models.\n\nThe four panels are:\n\n1. **QQ plot of residuals** (top-left)  \n   Compares sample residuals to theoretical quantiles. A straight line indicates a good fit.  \n   Deviations suggest skewness, heavy tails, or outliers.\n\n2. **Residuals vs linear predictor η** (top-right)  \n   Shows residuals against the fitted linear predictor, with a LOESS smoother.  \n   A flat trend near 0 is ideal. Systematic curvature means the model missed a trend; funnel shapes suggest heteroscedasticity.\n\n3. **Histogram of residuals** (bottom-left)  \n   Displays the distribution of residuals. Ideally symmetric and centered at 0.  \n   Skewness or multimodality may indicate model misspecification.\n\n4. **Observed vs fitted** (bottom-right)  \n   Compares predicted values with observed outcomes. For continuous data, points should align with the 45° line.  \n   For binary outcomes, this acts as a calibration plot: predicted probabilities should match observed frequencies.\n\n**Notes** \n\n1. `residual_type` can be `deviance` (default), `pearson`, or `quantile`.\nQuantile residuals (Dunn–Smyth) are recommended for discrete families (binomial, Poisson) because they are continuous and approximately normal.\n\n2. `qq_method` controls reference quantiles: \n\n    - `uniform`: fast and default. \n    - `simulate`: most faithful and provides bands, but slower\n    - `normal`: fallback\n\nTogether, these diagnosis plots help assess whether residuals behave like noise, whether systematic trends remain and if predictions are unbiased and calibrated. \n\n## Citation\n\nIf you use neuralGAM in your research, please cite the following paper:\n\n\u003e Ortega-Fernandez, I., Sestelo, M. \u0026 Villanueva, N.M. _Explainable generalized additive neural networks with independent neural network training_. Statistics \u0026 Computing 34, 6 (2024). https://doi.org/10.1007/s11222-023-10320-5\n\n```bibtex\n@article{ortega2024explainable,\nauthor = {Ortega-Fernandez, Ines and Sestelo, Marta and Villanueva, Nora M},\ndoi = {10.1007/s11222-023-10320-5},\nissn = {1573-1375},\njournal = {Statistics and Computing},\nnumber = {1},\npages = {6},\ntitle = {{Explainable generalized additive neural networks with independent neural network training}},\nurl = {https://doi.org/10.1007/s11222-023-10320-5},\nvolume = {34},\nyear = {2023}\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finesortega%2Fneuralgam","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finesortega%2Fneuralgam","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finesortega%2Fneuralgam/lists"}