diff --git a/pkgdown.yml b/pkgdown.yml index e5c0a620..fcb5328f 100644 --- a/pkgdown.yml +++ b/pkgdown.yml @@ -6,7 +6,7 @@ articles: data-slices: data-slices.html gratia: gratia.html articles/posterior-simulation: posterior-simulation.html -last_built: 2024-11-25T10:52Z +last_built: 2024-11-25T11:07Z urls: reference: https://gavinsimpson.github.io/gratia/reference article: https://gavinsimpson.github.io/gratia/articles diff --git a/reference/conditional_values-3.png b/reference/conditional_values-3.png index ccde041b..8cd84a2c 100644 Binary files a/reference/conditional_values-3.png and b/reference/conditional_values-3.png differ diff --git a/reference/conditional_values.html b/reference/conditional_values.html index 01ec8148..3b4c94c1 100644 --- a/reference/conditional_values.html +++ b/reference/conditional_values.html @@ -146,9 +146,8 @@

Examples# * `x3` at its mean a d mean +/- sd cv <- conditional_values( m1, - condition = list("x2", x1 = "decile", x0 = "quartile", "threenum") + condition = list("x2", x1 = "decile", x0 = "quartile", x3 = "threenum") ) -#> Warning: argument is not numeric or logical: returning NA # plot cv |> draw() diff --git a/reference/draw.smooth_samples-2.png b/reference/draw.smooth_samples-2.png index 6232b565..d151e6be 100644 Binary files a/reference/draw.smooth_samples-2.png and b/reference/draw.smooth_samples-2.png differ diff --git a/reference/link.html b/reference/link.html index 279364cf..b8934e28 100644 --- a/reference/link.html +++ b/reference/link.html @@ -174,11 +174,11 @@

Exampleslink(mod, parameter = "scale") #> function (mu) #> log(1/mu - 0.01) -#> <environment: 0x555925d469c8> +#> <environment: 0x55be4c3428c8> inv_link(mod, parameter = "scale") #> function (eta) #> 1/(exp(eta) + 0.01) -#> <environment: 0x555925d469c8> +#> <environment: 0x55be4c3428c8> ## Works with `family` objects too link(shash(), parameter = "skewness") diff --git a/search.json b/search.json index e703a004..b4218627 100644 --- a/search.json +++ b/search.json @@ -1 +1 @@ -[{"path":[]},{"path":"https://gavinsimpson.github.io/gratia/CODE_OF_CONDUCT.html","id":"our-pledge","dir":"","previous_headings":"","what":"Our Pledge","title":"Contributor Covenant Code of Conduct","text":"members, contributors, leaders pledge make participation community harassment-free experience everyone, regardless age, body size, visible invisible disability, ethnicity, sex characteristics, gender identity expression, level experience, education, socio-economic status, nationality, personal appearance, race, religion, sexual identity orientation. pledge act interact ways contribute open, welcoming, diverse, inclusive, healthy community.","code":""},{"path":"https://gavinsimpson.github.io/gratia/CODE_OF_CONDUCT.html","id":"our-standards","dir":"","previous_headings":"","what":"Our Standards","title":"Contributor Covenant Code of Conduct","text":"Examples behavior contributes positive environment community include: Demonstrating empathy kindness toward people respectful differing opinions, viewpoints, experiences Giving gracefully accepting constructive feedback Accepting responsibility apologizing affected mistakes, learning experience Focusing best just us individuals, overall community Examples unacceptable behavior include: use sexualized language imagery, sexual attention advances kind Trolling, insulting derogatory comments, personal political attacks Public private harassment Publishing others’ private information, physical email address, without explicit permission conduct reasonably considered inappropriate professional setting","code":""},{"path":"https://gavinsimpson.github.io/gratia/CODE_OF_CONDUCT.html","id":"enforcement-responsibilities","dir":"","previous_headings":"","what":"Enforcement Responsibilities","title":"Contributor Covenant Code of Conduct","text":"Community leaders responsible clarifying enforcing standards acceptable behavior take appropriate fair corrective action response behavior deem inappropriate, threatening, offensive, harmful. Community leaders right responsibility remove, edit, reject comments, commits, code, wiki edits, issues, contributions aligned Code Conduct, communicate reasons moderation decisions appropriate.","code":""},{"path":"https://gavinsimpson.github.io/gratia/CODE_OF_CONDUCT.html","id":"scope","dir":"","previous_headings":"","what":"Scope","title":"Contributor Covenant Code of Conduct","text":"Code Conduct applies within community spaces, also applies individual officially representing community public spaces. Examples representing community include using official e-mail address, posting via official social media account, acting appointed representative online offline event.","code":""},{"path":"https://gavinsimpson.github.io/gratia/CODE_OF_CONDUCT.html","id":"enforcement","dir":"","previous_headings":"","what":"Enforcement","title":"Contributor Covenant Code of Conduct","text":"Instances abusive, harassing, otherwise unacceptable behavior may reported package maintainer, Gavin Simpson (see email address CRAN package page) . complaints reviewed investigated promptly fairly. community leaders obligated respect privacy security reporter incident.","code":""},{"path":"https://gavinsimpson.github.io/gratia/CODE_OF_CONDUCT.html","id":"enforcement-guidelines","dir":"","previous_headings":"","what":"Enforcement Guidelines","title":"Contributor Covenant Code of Conduct","text":"Community leaders follow Community Impact Guidelines determining consequences action deem violation Code Conduct:","code":""},{"path":"https://gavinsimpson.github.io/gratia/CODE_OF_CONDUCT.html","id":"id_1-correction","dir":"","previous_headings":"Enforcement Guidelines","what":"1. Correction","title":"Contributor Covenant Code of Conduct","text":"Community Impact: Use inappropriate language behavior deemed unprofessional unwelcome community. Consequence: private, written warning community leaders, providing clarity around nature violation explanation behavior inappropriate. public apology may requested.","code":""},{"path":"https://gavinsimpson.github.io/gratia/CODE_OF_CONDUCT.html","id":"id_2-warning","dir":"","previous_headings":"Enforcement Guidelines","what":"2. Warning","title":"Contributor Covenant Code of Conduct","text":"Community Impact: violation single incident series actions. Consequence: warning consequences continued behavior. interaction people involved, including unsolicited interaction enforcing Code Conduct, specified period time. includes avoiding interactions community spaces well external channels like social media. Violating terms may lead temporary permanent ban.","code":""},{"path":"https://gavinsimpson.github.io/gratia/CODE_OF_CONDUCT.html","id":"id_3-temporary-ban","dir":"","previous_headings":"Enforcement Guidelines","what":"3. Temporary Ban","title":"Contributor Covenant Code of Conduct","text":"Community Impact: serious violation community standards, including sustained inappropriate behavior. Consequence: temporary ban sort interaction public communication community specified period time. public private interaction people involved, including unsolicited interaction enforcing Code Conduct, allowed period. Violating terms may lead permanent ban.","code":""},{"path":"https://gavinsimpson.github.io/gratia/CODE_OF_CONDUCT.html","id":"id_4-permanent-ban","dir":"","previous_headings":"Enforcement Guidelines","what":"4. Permanent Ban","title":"Contributor Covenant Code of Conduct","text":"Community Impact: Demonstrating pattern violation community standards, including sustained inappropriate behavior, harassment individual, aggression toward disparagement classes individuals. Consequence: permanent ban sort public interaction within community.","code":""},{"path":"https://gavinsimpson.github.io/gratia/CODE_OF_CONDUCT.html","id":"attribution","dir":"","previous_headings":"","what":"Attribution","title":"Contributor Covenant Code of Conduct","text":"Code Conduct adapted Contributor Covenant, version 2.0, available https://www.contributor-covenant.org/version/2/0/code_of_conduct.html. Community Impact Guidelines inspired Mozilla’s code conduct enforcement ladder. answers common questions code conduct, see FAQ https://www.contributor-covenant.org/faq. Translations available https://www.contributor-covenant.org/translations.","code":""},{"path":[]},{"path":"https://gavinsimpson.github.io/gratia/CONTRIBUTING.html","id":"something-isnt-working-right-or-generating-an-error","dir":"","previous_headings":"","what":"Something isn’t working right or generating an error","title":"Contributing","text":"something isn’t working, either might expect/want contrary documentation, probably bug missing feature. ’re getting error running {gratia}, ’s also likely bug, opportunity catch use-case wasn’t expecting. First, check issue hasn’t already fixed -development version Github. Install current development version {gratia} R-universe using issue remains, please file issue via Issues page. ’s OK report issue even ’re sure ’s problem, problem better described question, use Discussions page (see ). Feature requests welcome! problem {gratia} hit top TODO list quickly cen provide reproducible example demonstrating problem.","code":"install.packages(\"gratia\", repos = c( \"https://gavinsimpson.r-universe.dev\", \"https://cloud.r-project.org\" ))"},{"path":"https://gavinsimpson.github.io/gratia/CONTRIBUTING.html","id":"got-a-question-want-to-show-how-to-do-something-with-gratia","dir":"","previous_headings":"","what":"Got a question? Want to show how to do something with {gratia}?","title":"Contributing","text":"issue best described question, want know something {gratia}, cool example using {gratia} want share , please consider using Discussions page. ’re sure, can always ask issue Question (Use Q&category) , really bug, can easily create Issue discussion.","code":""},{"path":"https://gavinsimpson.github.io/gratia/CONTRIBUTING.html","id":"code-contributions","dir":"","previous_headings":"","what":"Code contributions","title":"Contributing","text":"Code contributions form Pull Requests always appreciated. suitable workflow: Fork repo Github account Clone version account machine account, e.g,. git clone https://github.com//gratia.git Make sure track progress upstream (.e., version gratis gavinsimpson/gratia) git remote add upstream https://github.com/gavinsimpson/gratia.git. making changes make sure pull changes upstream either git fetch upstream merge later git pull upstream fetch merge one step Make changes (bonus points making changes new feature branch) Push account Submit pull request home base gavinsimpson/gratia","code":""},{"path":"https://gavinsimpson.github.io/gratia/CONTRIBUTING.html","id":"development-tools--paradigm--ethos","dir":"","previous_headings":"Code contributions","what":"Development tools / paradigm / ethos","title":"Contributing","text":"Please note following contributing code: {gratia} tightly aligned tidyverse use {dplyr} related packages lot internally developing package. plan replacing code lower-level code using {vctrs}, right now development focus filling functionality package premature optimisation. original aim {gratia} provide {ggplot2} plotting smooths; please stick principle use plotting paradigm. aim {mgcv}-feature complete; {mgcv} can something terms plotting smooths, handling specialists smooths, etc, principle {gratia} support . aim general compatibility {mgcv}; {gratia} deviates {mgcv} things, needs good justification; example {gratia} deviates multivariate isotropic smooths fitted s() plotted, Dave Miller (@dill) argued convincingly way. Don’t add dependencies! Unless accompanied strong justification, want reduce dependencies increase number. ’m using {styler} style code, using 2 spaces indent. code written change, however. Respect 80 character line length limit. contribute functionality fix bug, please add test using {testthat} framework insure new things works correctly bug stays fixed. contributions must result new NOTES, WARNINGS, ERRORS running R CMD check ---cran; please check contributions Winbuilder example.","code":""},{"path":"https://gavinsimpson.github.io/gratia/CONTRIBUTING.html","id":"email","dir":"","previous_headings":"","what":"Email","title":"Contributing","text":"hate email! can email GMail address — ’s like can stop :-) — unless capture attention immediately label message {gratia}-related, quickly get swamped never seen . Even label , ’s guarantee ever get round replying; usually happens ’ll forget don’t remember check gratia label often. end result email , get response , tardy. infinitely better use Discussions Issues pages Github ask questions package report problems. Please don’t email work (academic) address (email address might find ) {gratia}. question GAMs, much better ask CrossValidated StackOverflow depending whether question statistical programming related. relates {gratia} can use Discussions page. Asking question public allows others reply public, contributes body knowledge easily available others. circumstances send email multiple addresses; quickest way get message trash.","code":""},{"path":"https://gavinsimpson.github.io/gratia/LICENSE.html","id":null,"dir":"","previous_headings":"","what":"The MIT License (MIT)","title":"The MIT License (MIT)","text":"Copyright (c) 2013-2024 Gavin L. Simpson Permission hereby granted, free charge, person obtaining copy software associated documentation files (“Software”), deal Software without restriction, including without limitation rights use, copy, modify, merge, publish, distribute, sublicense, /sell copies Software, permit persons Software furnished , subject following conditions: copyright notice permission notice shall included copies substantial portions Software. SOFTWARE PROVIDED “”, WITHOUT WARRANTY KIND, EXPRESS IMPLIED, INCLUDING LIMITED WARRANTIES MERCHANTABILITY, FITNESS PARTICULAR PURPOSE NONINFRINGEMENT. EVENT SHALL AUTHORS COPYRIGHT HOLDERS LIABLE CLAIM, DAMAGES LIABILITY, WHETHER ACTION CONTRACT, TORT OTHERWISE, ARISING , CONNECTION SOFTWARE USE DEALINGS SOFTWARE.","code":""},{"path":"https://gavinsimpson.github.io/gratia/articles/custom-plotting.html","id":"background","dir":"Articles","previous_headings":"","what":"Background","title":"Customizing plots","text":"draw() function {gratia} envisaged ggplot-based alternative mgcv:::plot.gam(). , never intended allow sorts customization possible ggplot() packages use ggplot() plotting layer. largely due decision produce multiple separate ggplot() plots GAMs multiple smooths, subsequently combined single figure device, initially using {cowplot} recently {patchwork}. things way evident consider might represent smooths 3 4 variables (common might think; consider space-time models via te(x, y, time, d = c(2,1)) space-depth-time models [think ocean atmospheric data space depth (height), observed time] via te(x, y, depth, time, d = c(2, 1, 1))), require facets top produce small multiples, means can’t use facets plot separate smooths. Additional complications arise consider complex smooth types, splines sphere, might want us different coordinate systems geoms best represent underlying smooth. gone root combining multiple ggplot objects single figure, problem customizing plots quickly rears head. vignette presents solutions problem modifying adding plots produced draw() culminating example illustrating use {gratia}’s utility functions produce plots lower-lever components.","code":""},{"path":"https://gavinsimpson.github.io/gratia/articles/custom-plotting.html","id":"adding-layers-to-plots-with-the-operator","dir":"Articles","previous_headings":"","what":"Adding layers to plots with the & operator","title":"Customizing plots","text":"start simulating data fitting GAM four smooth functions default plot produced draw() want change theme plots, can’t append theme() layer p affects last plot patchwork1 One way apply theme plots patchwork & operator.","code":"library(\"gratia\") library(\"mgcv\") #> Loading required package: nlme #> This is mgcv 1.9-1. For overview type 'help(\"mgcv-package\")'. library(\"ggplot2\") library(\"dplyr\") #> #> Attaching package: 'dplyr' #> The following object is masked from 'package:nlme': #> #> collapse #> The following objects are masked from 'package:stats': #> #> filter, lag #> The following objects are masked from 'package:base': #> #> intersect, setdiff, setequal, union library(\"patchwork\") # simulate data n <- 400 eg1 <- data_sim(\"eg1\", n = n, seed = 1) # fit model m <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = eg1, method = \"REML\") p <- draw(m) p p + theme_bw() p & theme_bw()"},{"path":"https://gavinsimpson.github.io/gratia/articles/custom-plotting.html","id":"combining-individual-plots-produced-by-draw","dir":"Articles","previous_headings":"","what":"Combining individual plots produced by draw()","title":"Customizing plots","text":"draw() methods like draw.gam() return object created patchwork::wrap_plots(), result isn’t straightforward combine objects new patchwork avoid error, need use patchwork::plot_layout() set dimensions want achieved directly via draw() instructive know combine outputs draw() need arise, want create patchwork plots different models.","code":"p1 <- draw(m, select = \"s(x0)\") p2 <- draw(m, select = \"s(x1)\") p3 <- draw(m, select = \"s(x2)\") p1 + p2 + p3 #> Error in `wrap_dims()`: #> ! Need 3 panels, but together `nrow` and `ncol` only provide 1. #> ℹ Please increase `ncol` and/or `nrow`. p1 + p2 + p3 + plot_layout(ncol = 3) draw(m, select = c(\"s(x0)\", \"s(x1)\", \"s(x2)\"), ncol = 3)"},{"path":"https://gavinsimpson.github.io/gratia/articles/custom-plotting.html","id":"building-your-own-plot-by-hand","dir":"Articles","previous_headings":"","what":"Building your own plot by hand","title":"Customizing plots","text":"{gratia} provides high-level functions like draw() get good graphical overview fitted model, little option customisation — isn’t possible desirable allow possible customisation options fatures {ggplot2} single function. Think many arguments require! Instead, {gratia} also exports lower-level functions used draw() can create plot using whatever {ggplot2} functions make sense. next code blocks ’ll see plot created draw(m) can recreated hand using lower-level building blocks. main thing need evaluate smooths values covariates. done using smooth_estimates(). also need add credible interval evaluations, can done tidyverse-style via add_confint() default draw.gam() add partial residuals partial effects plots. achieve effect, need add partial residuals data used fit model. can done via add_partial_residuals() will2 add columns names \"s(x0)\". \"s(x1)\", etc. data. Now everything need recreate plots created draw.gam(). code block filter sm focus specific smooth, f(x2)f(x2) (\"s(x2)\"), add rug plot observed values x2, credible interval around estimated smooth, partial residuals point layer, estimated smooth line layer, annotation Assuming repeat steps smooths, creating plot objects p_sx0, p_sx1, p_sx2, p_sx3 (code shown), can complete plot creating patchwork desired number rows columns real benefit complete control data plotted can use power {ggplot2} map additional variables plot aesthetics. example, let’s assume factor variable original data want colour partial residuals according levels factor. Let’s create factor Now can modify plotting code map fac colour aesthetic plot partial residuals. save typing, ’ll reorder layers plot add partial residuals last can also simple model checking plotting smooth partial residuals coloured according one covariates (also plotting actual residuals covariates). code chunk , map covariate x1 colour size aesthetics (note deleted cex = 1.5 allow mapping size) resulting plot doesn’t show particular problems model way data simulated, hopefully illustrates can possible use low-level functions provided {gratia}.","code":"# evaluate the smooths sm <- smooth_estimates(m) |> add_confint() sm #> # A tibble: 400 × 11 #> .smooth .type .by .estimate .se x0 x1 x2 x3 .lower_ci #> #> 1 s(x0) TPRS NA -0.929 0.422 0.0131 NA NA NA -1.76 #> 2 s(x0) TPRS NA -0.881 0.396 0.0230 NA NA NA -1.66 #> 3 s(x0) TPRS NA -0.834 0.372 0.0329 NA NA NA -1.56 #> 4 s(x0) TPRS NA -0.786 0.348 0.0429 NA NA NA -1.47 #> 5 s(x0) TPRS NA -0.738 0.326 0.0528 NA NA NA -1.38 #> 6 s(x0) TPRS NA -0.690 0.305 0.0627 NA NA NA -1.29 #> 7 s(x0) TPRS NA -0.643 0.287 0.0727 NA NA NA -1.20 #> 8 s(x0) TPRS NA -0.595 0.270 0.0826 NA NA NA -1.12 #> 9 s(x0) TPRS NA -0.548 0.255 0.0925 NA NA NA -1.05 #> 10 s(x0) TPRS NA -0.501 0.242 0.102 NA NA NA -0.975 #> # ℹ 390 more rows #> # ℹ 1 more variable: .upper_ci # add partial residuals to data eg1 <- eg1 |> add_partial_residuals(m) names(eg1) #> [1] \"y\" \"x0\" \"x1\" \"x2\" \"x3\" \"f\" \"f0\" \"f1\" \"f2\" #> [10] \"f3\" \"s(x0)\" \"s(x1)\" \"s(x2)\" \"s(x3)\" p_sx2 <- sm |> filter(.smooth == \"s(x2)\") |> ggplot() + geom_rug(aes(x = x2), data = eg1, sides = \"b\", length = grid::unit(0.02, \"npc\") ) + geom_ribbon(aes(ymin = .lower_ci, ymax = .upper_ci, x = x2), alpha = 0.2 ) + geom_point(aes(x = x2, y = `s(x2)`), data = eg1, cex = 1.5, colour = \"steelblue3\" ) + geom_line(aes(x = x2, y = .estimate), lwd = 1.2) + labs(y = \"Partial effect\", title = \"s(x2)\") p_sx2 p_sx0 + p_sx1 + p_sx2 + p_sx3 + plot_layout(ncol = 2) set.seed(12) eg1 <- eg1 |> mutate(fac = sample(letters[1:4], n(), replace = TRUE)) plt <- sm |> filter(.smooth == \"s(x2)\") |> ggplot() + geom_rug(aes(x = x2), data = eg1, sides = \"b\", length = grid::unit(0.02, \"npc\") ) + geom_ribbon(aes(ymin = .lower_ci, ymax = .upper_ci, x = x2), alpha = 0.2 ) + geom_line(aes(x = x2, y = .estimate), lwd = 1.2) + labs(y = \"Partial effect\", title = \"s(x2)\") plt + geom_point( aes( x = x2, y = `s(x2)`, colour = fac ), # <-- map fac to colour aesthetic data = eg1, cex = 1.5 ) plt + geom_point( aes( x = x2, y = `s(x2)`, colour = x1, size = x1 ), # <-- map fac to colour aesthetic data = eg1, alpha = 0.3 ) + # <-- deleted cex!! scale_colour_viridis_c(option = \"plasma\")"},{"path":"https://gavinsimpson.github.io/gratia/articles/data-slices.html","id":"carbon-dioxide-uptake-in-grass-plants","dir":"Articles","previous_headings":"","what":"Carbon Dioxide Uptake in Grass Plants","title":"Data slices","text":"first example uses small data set experimental study cold tolerance grass Echinochloa crusgalli. data data frame CO2 provided {datasets} package ships R. One way model data allow different smooths combinations treatment type covariates can look fitted smooths using draw() might want compare model fitted values treatment types (origins), ignoring random effect component. want evaluate model range values covariate conc combinations factors. data slice covariate space, can create using data_slice(). create data slice conc Quebec type chilled treatment use Notice data_slice() filled something remaining covariates didn’t mention? case, data_slice() doesn’t know tt created, chosen modal level tt factor, correct choice case. Instead, need specify correct level explicitly tt created data slice, can predict model using combination covariate values specified slice. use predict.gam() , fitted_values() function {gratia} easier use, especially non-Gaussian models Notice excluded random effect term; even though specify something plant covariate can ignore term model using exclude argument. fitted_values() creates credible interval scale link function back-transforms response scale scale = \"response\", also default. Plotting fitted values data slice now requires simple {ggplot2} knowledge Next, let’s compare fitted effects treatment Mississippi origin plants , replaced automatically-generated tt variable correctly specified call fct_cross(), retaining levels type treatment factors. insures correct combinations corresponding treatment type factors also preserve original levels tt covariate created. can visualise fitted values data slice creating data slices, used helper functions specify covariate values slice. {gratia} provides several helper functions: evenly(x, n = 100) — creates n evenly spaced values range covariate, evenly(x, = 5 — creates evenly spaced values range covariate increments 5, evenly(x, ..., lower = 5, upper = 10) — either two uses evenly() shown use lower upper limits vector x. Arguments lower upper can used change one upper lower bounds. evenly(fct) — produces new factor containing level specified factor fct just , ref_level(fct) — creates new factor containing just reference level specified factor covariate fct, level(fct, \"level\") — creates factor requested \"level\" factor fct. cases involving factors, helper functions set levels factor match original model fit2. second argument data_slice() ... ... argument allows provide expressions create covariate values want data slice. Expressions passed ... evaluated within model frame fitted model (argument object) data (supplied). restricted either using helper functions provide {gratia}; R function used long makes sense context model frame, returns something can combined using tidyr::expand_grid().","code":"## data load and prep data(CO2, package = \"datasets\") plant <- CO2 |> as_tibble() |> rename(plant = Plant, type = Type, treatment = Treatment) |> mutate(plant = factor(plant, ordered = FALSE)) plant_ylab <- expression(CO[2] ~ uptake ~ (mu * mol ~ m^{-3})) plant_xlab <- expression(CO[2] ~ concentration ~ (mL ~ L^{-1})) plant |> ggplot(aes(x = conc, y = uptake, group = plant, colour = treatment)) + geom_point() + geom_line() + facet_wrap(~type) + labs(y = plant_ylab, x = plant_xlab, colour = \"Treatment\") plant <- plant |> mutate(tt = fct_cross(treatment, type)) m_plant <- gam(uptake ~ treatment * type + s(conc, by = tt, k = 6) + s(plant, bs = \"re\"), data = plant, method = \"REML\", family = Gamma(link = \"log\") ) overview(m_plant) #> #> Generalized Additive Model with 8 terms #> #> term type k edf statistic p.value #> #> 1 treatment parametric NA 1 1.59 0.2124864 #> 2 type parametric NA 1 11.2 0.0014830 #> 3 treatment:type parametric NA 1 7.45 0.0085489 #> 4 s(conc):ttnonchilled:Quebec TPRS 5 4.72 69.7 < 0.001 #> 5 s(conc):ttchilled:Quebec TPRS 5 4.71 86.5 < 0.001 #> 6 s(conc):ttnonchilled:Mississippi TPRS 5 4.62 74.1 < 0.001 #> 7 s(conc):ttchilled:Mississippi TPRS 5 4.39 25.3 < 0.001 #> 8 s(plant) Random effect 12 7.40 12.8 < 0.001 draw(m_plant, residuals = TRUE, scales = \"fixed\") ds1 <- data_slice(m_plant, conc = evenly(conc, n = 100), type = level(type, \"Quebec\"), treatment = level(treatment, \"chilled\") ) ds1 #> # A tibble: 100 × 5 #> conc type treatment tt plant #> #> 1 95 Quebec chilled nonchilled:Quebec Qn1 #> 2 104. Quebec chilled nonchilled:Quebec Qn1 #> 3 113. Quebec chilled nonchilled:Quebec Qn1 #> 4 122. Quebec chilled nonchilled:Quebec Qn1 #> 5 132. Quebec chilled nonchilled:Quebec Qn1 #> 6 141. Quebec chilled nonchilled:Quebec Qn1 #> 7 150. Quebec chilled nonchilled:Quebec Qn1 #> 8 159. Quebec chilled nonchilled:Quebec Qn1 #> 9 168. Quebec chilled nonchilled:Quebec Qn1 #> 10 177. Quebec chilled nonchilled:Quebec Qn1 #> # ℹ 90 more rows ds1 <- data_slice(m_plant, conc = evenly(conc, n = 100), treatment = level(treatment, \"chilled\"), type = level(type, \"Quebec\"), tt = level(tt, \"chilled:Quebec\") ) ds1 #> # A tibble: 100 × 5 #> conc treatment type tt plant #> #> 1 95 chilled Quebec chilled:Quebec Qn1 #> 2 104. chilled Quebec chilled:Quebec Qn1 #> 3 113. chilled Quebec chilled:Quebec Qn1 #> 4 122. chilled Quebec chilled:Quebec Qn1 #> 5 132. chilled Quebec chilled:Quebec Qn1 #> 6 141. chilled Quebec chilled:Quebec Qn1 #> 7 150. chilled Quebec chilled:Quebec Qn1 #> 8 159. chilled Quebec chilled:Quebec Qn1 #> 9 168. chilled Quebec chilled:Quebec Qn1 #> 10 177. chilled Quebec chilled:Quebec Qn1 #> # ℹ 90 more rows fv1 <- fitted_values(m_plant, data = ds1, scale = \"response\", exclude = \"s(plant)\") fv1 #> # A tibble: 100 × 10 #> .row conc treatment type tt plant .fitted .se .lower_ci .upper_ci #> #> 1 1 95 chilled Quebec chille… Qn1 13.0 0.0783 11.2 15.2 #> 2 2 104. chilled Quebec chille… Qn1 14.1 0.0757 12.1 16.3 #> 3 3 113. chilled Quebec chille… Qn1 15.2 0.0737 13.1 17.5 #> 4 4 122. chilled Quebec chille… Qn1 16.3 0.0722 14.2 18.8 #> 5 5 132. chilled Quebec chille… Qn1 17.6 0.0714 15.3 20.2 #> 6 6 141. chilled Quebec chille… Qn1 18.9 0.0711 16.4 21.7 #> 7 7 150. chilled Quebec chille… Qn1 20.2 0.0712 17.6 23.3 #> 8 8 159. chilled Quebec chille… Qn1 21.6 0.0716 18.8 24.9 #> 9 9 168. chilled Quebec chille… Qn1 23.0 0.0721 20.0 26.5 #> 10 10 177. chilled Quebec chille… Qn1 24.4 0.0726 21.2 28.1 #> # ℹ 90 more rows fv1 |> ggplot(aes(x = conc, y = .fitted)) + geom_point( data = plant |> filter(type == \"Quebec\", treatment == \"chilled\"), mapping = aes(y = uptake), alpha = 0.8, colour = \"steelblue\" ) + geom_ribbon(aes(ymin = .lower_ci, ymax = .upper_ci), alpha = 0.2) + geom_line() + labs( x = plant_xlab, y = plant_ylab, title = expression(Estimated ~ CO[2] ~ uptake), subtitle = \"Chilled plants of the Quebec type\" ) ds2 <- data_slice(m_plant, conc = evenly(conc, n = 100), treatment = evenly(treatment), type = level(type, \"Mississippi\") ) |> mutate(tt = fct_cross(treatment, type, keep_empty = TRUE)) ds2 #> # A tibble: 200 × 5 #> conc treatment type tt plant #> #> 1 95 nonchilled Mississippi nonchilled:Mississippi Qn1 #> 2 95 chilled Mississippi chilled:Mississippi Qn1 #> 3 104. nonchilled Mississippi nonchilled:Mississippi Qn1 #> 4 104. chilled Mississippi chilled:Mississippi Qn1 #> 5 113. nonchilled Mississippi nonchilled:Mississippi Qn1 #> 6 113. chilled Mississippi chilled:Mississippi Qn1 #> 7 122. nonchilled Mississippi nonchilled:Mississippi Qn1 #> 8 122. chilled Mississippi chilled:Mississippi Qn1 #> 9 132. nonchilled Mississippi nonchilled:Mississippi Qn1 #> 10 132. chilled Mississippi chilled:Mississippi Qn1 #> # ℹ 190 more rows fitted_values(m_plant, data = ds2, scale = \"response\", exclude = \"s(plant)\" ) |> ggplot(aes(x = conc, y = .fitted, group = treatment)) + geom_point( data = plant |> filter(type == \"Mississippi\"), mapping = aes(y = uptake, colour = treatment), alpha = 0.8 ) + geom_ribbon(aes(ymin = .lower_ci, ymax = .upper_ci, fill = treatment), alpha = 0.2 ) + geom_line(aes(colour = treatment)) + labs( x = plant_xlab, y = plant_ylab, title = expression(Estimated ~ CO[2] ~ uptake), subtitle = \"Comparison of treatment in plants of the Mississippi type\", colour = \"Treatment\", fill = \"Treatment\" ) args(gratia:::data_slice.gam) #> function (object, ..., data = NULL, envir = NULL) #> NULL"},{"path":"https://gavinsimpson.github.io/gratia/articles/data-slices.html","id":"slices-through-a-2d-smooth","dir":"Articles","previous_headings":"","what":"Slices through a 2D smooth","title":"Data slices","text":"second example, ’ll use bivariate example data set {mgcv} fit tensor product covariates x z aim example create univariate data slice 2D smooth user-specified values x holding z one fixed values. visualise effect smooth level, using smooth_estimates(), response level, using fitted_values().","code":"# simulate data from the bivariate surface df <- data_sim(\"eg2\", n = 1000, scale = 0.25, seed = 2) # fit the GAM m_biv <- gam(y ~ te(x, z), data = df, method = \"REML\")"},{"path":"https://gavinsimpson.github.io/gratia/articles/data-slices.html","id":"using-smooth_estimates","dir":"Articles","previous_headings":"Slices through a 2D smooth","what":"Using smooth_estimates()","title":"Data slices","text":"begin creating slice data space. also create label point nice axis label. evaluate smooth desired values add confidence interval can plot sm using {ggplot2} Note interval Marra Wood (2012) interval. doesn’t include uncertainty model constant term moment, unless smooth close linear shouldn’t make much difference. extends multiple slices asking several discrete z","code":"ds3 <- data_slice(m_biv, x = evenly(x, n = 100), z = quantile(z, probs = 0.25) ) z_val <- with(ds3, round(quantile(z, probs = 0.25), 2)) ylab <- bquote(hat(f)(x, .(z_val))) sm <- smooth_estimates(m_biv, select = \"te(x,z)\", data = ds3) |> add_confint() sm #> # A tibble: 100 × 9 #> .smooth .type .by .estimate .se x z .lower_ci .upper_ci #> #> 1 te(x,z) Tensor prod… NA 0.103 0.0583 6.63e-4 0.245 -0.0107 0.218 #> 2 te(x,z) Tensor prod… NA 0.122 0.0548 1.08e-2 0.245 0.0148 0.230 #> 3 te(x,z) Tensor prod… NA 0.141 0.0514 2.08e-2 0.245 0.0400 0.242 #> 4 te(x,z) Tensor prod… NA 0.159 0.0482 3.09e-2 0.245 0.0648 0.254 #> 5 te(x,z) Tensor prod… NA 0.177 0.0451 4.10e-2 0.245 0.0890 0.266 #> 6 te(x,z) Tensor prod… NA 0.195 0.0422 5.11e-2 0.245 0.113 0.278 #> 7 te(x,z) Tensor prod… NA 0.213 0.0396 6.12e-2 0.245 0.135 0.291 #> 8 te(x,z) Tensor prod… NA 0.230 0.0372 7.13e-2 0.245 0.157 0.303 #> 9 te(x,z) Tensor prod… NA 0.247 0.0351 8.14e-2 0.245 0.178 0.316 #> 10 te(x,z) Tensor prod… NA 0.263 0.0333 9.14e-2 0.245 0.198 0.328 #> # ℹ 90 more rows sm |> ggplot(aes(x = x, y = .estimate)) + geom_ribbon(aes(ymin = .lower_ci, ymax = .upper_ci), alpha = 0.2) + geom_line() + labs( title = \"Evaluation of smooth te(x,z) at fixed z\", y = ylab ) ds4 <- data_slice(m_biv, x = evenly(x, n = 100), z = round(quantile(z, probs = c(0.25, 0.5, 0.75)), 2) ) sm <- smooth_estimates(m_biv, select = \"te(x,z)\", data = ds4) |> add_confint() |> mutate(fz = factor(z)) sm |> ggplot(aes(x = x, y = .estimate, colour = fz, group = fz)) + geom_ribbon(aes(ymin = .lower_ci, ymax = .upper_ci, fill = fz, colour = NULL), alpha = 0.2 ) + geom_line() + labs( title = \"Evaluation of smooth te(x,z) at fixed z\", y = expression(hat(f)(x, z)), colour = \"z\", fill = \"z\" )"},{"path":"https://gavinsimpson.github.io/gratia/articles/data-slices.html","id":"using-fitted_samples","dir":"Articles","previous_headings":"Slices through a 2D smooth","what":"Using fitted_samples()","title":"Data slices","text":"want evaluate surface x fixed z conditional upon values covariates (model predicted fitted values) fitted_samples() tidy wrapper predict.gam(). single z multiple z difference now model constant included well uncertainty.","code":"fitted_values(m_biv, data = ds3) |> # default is response scale, not link ggplot(aes(x = x, y = .fitted)) + geom_ribbon(aes(ymin = .lower_ci, ymax = .upper_ci), alpha = 0.2) + geom_line() + labs( title = \"Fitted values from model\", y = expression(hat(y)) ) fitted_values(m_biv, data = ds4) |> mutate(fz = factor(z)) |> ggplot(aes(x = x, y = .fitted, colour = fz, group = fz)) + geom_ribbon(aes(ymin = .lower_ci, ymax = .upper_ci, fill = fz, colour = NULL), alpha = 0.2 ) + geom_line() + labs( title = \"Fitted values from model\", y = expression(hat(y)), colour = \"z\", fill = \"z\" )"},{"path":"https://gavinsimpson.github.io/gratia/articles/gratia.html","id":"plotting","dir":"Articles","previous_headings":"","what":"Plotting","title":"Getting started with gratia","text":"gratia provides draw() function produce plots using ggplot2 📦. draw estimated smooths GAM fitted , use intended reasonable overview estimated model, offers limited option modify resulting plot. want full control, can obtain data used create plot smooth_estimates() evaluate smooths unevenly spaced values range covariate(s). want evaluate selected smooths, can specify via smooth argument. takes smooth labels names smooths known mgcv. list labels smooths use evaluate f(x2)f(x_2) use can generate plot using ggplot2 package, example","code":"draw(m) sm <- smooth_estimates(m) sm #> # A tibble: 400 × 9 #> .smooth .type .by .estimate .se x0 x1 x2 x3 #> #> 1 s(x0) TPRS NA -1.32 0.390 0.000239 NA NA NA #> 2 s(x0) TPRS NA -1.24 0.365 0.0103 NA NA NA #> 3 s(x0) TPRS NA -1.17 0.340 0.0204 NA NA NA #> 4 s(x0) TPRS NA -1.09 0.318 0.0304 NA NA NA #> 5 s(x0) TPRS NA -1.02 0.297 0.0405 NA NA NA #> 6 s(x0) TPRS NA -0.947 0.279 0.0506 NA NA NA #> 7 s(x0) TPRS NA -0.875 0.263 0.0606 NA NA NA #> 8 s(x0) TPRS NA -0.803 0.249 0.0707 NA NA NA #> 9 s(x0) TPRS NA -0.732 0.237 0.0807 NA NA NA #> 10 s(x0) TPRS NA -0.662 0.228 0.0908 NA NA NA #> # ℹ 390 more rows smooths(m) #> [1] \"s(x0)\" \"s(x1)\" \"s(x2)\" \"s(x3)\" sm <- smooth_estimates(m, smooth = \"s(x2)\") #> Warning: The `smooth` argument of `smooth_estimates()` is deprecated as of gratia #> 0.8.9.9. #> ℹ Please use the `select` argument instead. #> This warning is displayed once every 8 hours. #> Call `lifecycle::last_lifecycle_warnings()` to see where this warning was #> generated. sm #> # A tibble: 100 × 6 #> .smooth .type .by .estimate .se x2 #> #> 1 s(x2) TPRS NA -4.47 0.476 0.00359 #> 2 s(x2) TPRS NA -4.00 0.406 0.0136 #> 3 s(x2) TPRS NA -3.53 0.345 0.0237 #> 4 s(x2) TPRS NA -3.06 0.295 0.0338 #> 5 s(x2) TPRS NA -2.58 0.263 0.0438 #> 6 s(x2) TPRS NA -2.09 0.250 0.0539 #> 7 s(x2) TPRS NA -1.59 0.253 0.0639 #> 8 s(x2) TPRS NA -1.08 0.264 0.0740 #> 9 s(x2) TPRS NA -0.564 0.278 0.0841 #> 10 s(x2) TPRS NA -0.0364 0.289 0.0941 #> # ℹ 90 more rows library(\"ggplot2\") library(\"dplyr\") #> #> Attaching package: 'dplyr' #> The following object is masked from 'package:nlme': #> #> collapse #> The following objects are masked from 'package:stats': #> #> filter, lag #> The following objects are masked from 'package:base': #> #> intersect, setdiff, setequal, union sm |> add_confint() |> ggplot(aes(y = .estimate, x = x2)) + geom_ribbon(aes(ymin = .lower_ci, ymax = .upper_ci), alpha = 0.2, fill = \"forestgreen\" ) + geom_line(colour = \"forestgreen\", linewidth = 1.5) + labs( y = \"Partial effect\", title = expression(\"Partial effect of\" ~ f(x[2])), x = expression(x[2]) )"},{"path":"https://gavinsimpson.github.io/gratia/articles/gratia.html","id":"model-diagnostics","dir":"Articles","previous_headings":"","what":"Model diagnostics","title":"Getting started with gratia","text":"appraise() function provides standard diagnostic plots GAMs plots produced (left--right, top--bottom), quantile-quantile (QQ) plot deviance residuals, scatterplot deviance residuals linear predictor, histogram deviance residuals, scatterplot observed vs fitted values. Adding partial residuals partial effect plots produced draw() can also help diagnose problems model, oversmoothing","code":"appraise(m) draw(m, residuals = TRUE)"},{"path":"https://gavinsimpson.github.io/gratia/articles/gratia.html","id":"want-to-learn-more","dir":"Articles","previous_headings":"","what":"Want to learn more?","title":"Getting started with gratia","text":"gratia active development area development currently lacking documentation. find package, look help pages package look examples code help get going.","code":""},{"path":"https://gavinsimpson.github.io/gratia/articles/posterior-simulation.html","id":"what-are-we-simulating","dir":"Articles","previous_headings":"","what":"What are we simulating?","title":"Posterior Simulation","text":"Posterior simulation involves randomly sampling MVN(𝛃̂,𝐕b)\\text{MVN}(\\hat{\\boldsymbol{\\beta}}, \\mathbf{V}_{\\text{b}}) EF(μi,ϕ)\\text{EF}(\\mu_i, \\phi), . might simulate posterior distribution single estimated smooth function see uncertainty estimate function. simulate just subset βj⋅\\beta_{j \\cdot} associated fjf_j interest. Instead, might interested uncertainty expectation (expected value) model given values covariates, case can simulate 𝛃\\boldsymbol{\\beta} sample posterior 𝔼(yi)\\mathbb{E}(y_i), fitted values model. might want generate new values response variable via draws conditional distribution response, simulating new response data 𝕪*\\mathbb{y}^{\\ast}, either observed 𝐱\\mathbf{x} new values $^{}, yi*|𝛈,𝐱∼EF(μî,ϕ)y^{\\ast}_i | \\boldsymbol{\\eta}, \\mathbf{x} \\sim \\text{EF}(\\hat{\\mu_i}, \\phi). Finally, can combine posterior simulation distributions generate posterior draws new data 𝕪*\\mathbb{y}^{\\ast} also include uncertainty expected values. gratia functionality options following functions smooth_samples() generates draws posterior distribution single estimated smooth functions, fitted_samples() generates draws posterior distribution 𝔼(yi|𝐗i=xi)\\mathbb{E}(y_i | \\mathbf{X}_i = x_i), expected value responss, predicted_samples(), generates new response data given supplied values covariates yi*|𝐗i=xi*y^{\\ast}_i | \\mathbf{X}_i = x^{\\ast}_i posterior_samples(), generates draws posterior distribution model, including uncertainty estimated parameters model. simpler terms, fitted_samples() generates predictions “average” expected value response values covariates. predictions include uncertainty estimated values model coefficients. contrast, posterior_samples() generates predictions actual values response might expect observe (model correct) given values covariates. predicted values include variance sampling distribution (error term). predicted_samples() lies somewhere two; predicted values include variation sampling distribution, take model fixed, known. worth reminding posterior draws conditional upon selected values smoothing parameter(s) λj\\lambda_j. act wiggliness estimated smooths known, actual fact estimated (selected perhaps better description) wiglinesses data model fitting. estimated GAM fitted method argument \"REML\", \"ML\", version 𝐕b\\mathbf{V}_{\\text{b}} corrected selected smoothing parameters, 𝐕c\\mathbf{V}_{\\text{c}}, generally available. allows, extent, posterior simulation account additional source uncertainty chosen values 𝛌\\boldsymbol{\\lambda}. two additional functions available gratia posterior simulation: simulate(), derivative_samples(). gratia provides simulate() methods models estimated using gam(), bam(), gamm(), well fitted via scam() scam package. simulate() base R convention thing predicted_samples(), just non-tidy way (pejorative; returns simulated response values matrix, arguably useful math statistical computation.) derivative_samples() provides draws posterior distribution derivative response variable small change focal covariate value. derivative_samples() less general version fitted_samples(); achieve thing two separate calls fitted_samples(). ’ll reserve discussion derivative_samples() separate vignette focused estimating derivatives GAMs. following sections ’ll look four main posterior simulation functions turn.","code":""},{"path":"https://gavinsimpson.github.io/gratia/articles/posterior-simulation.html","id":"posterior-smooths-and-smooth_samples","dir":"Articles","previous_headings":"","what":"Posterior smooths and smooth_samples()","title":"Posterior Simulation","text":"can sample posterior distribution coefficients particular smooth β̂j\\hat{\\beta}_j given values smoothing parameters 𝛌̂\\hat{\\boldsymbol{\\lambda}}. generate posterior samples smooths sampling 𝛃j⋆∼N(β̂j,𝐕β̂j)\\boldsymbol{\\beta}_{j\\star} \\sim N(\\hat{\\beta}_j, \\mathbf{V}_{\\hat{\\beta}_j}) forming 𝐗𝛃̂j𝛃j⋆𝖳\\mathbf{X}_{\\hat{\\boldsymbol{\\beta}}_j} \\boldsymbol{\\beta}_{j\\star}^{\\mathsf{T}}. sampling can done using smooth_samples(). illustrate , ’ll simulate data Gu & Wabha’s 4 smooth example, fit GAM simulated data simulating posterior distribution estimated smooth, sampling coefficients particular smooth. model, coefficients smooth f(x0)f(x_0) stored elements 2 10 coefficients vector. sample posterior distribution coefficients use smooth_samples() choosing particular smooth ’re interested using select argument; want sample smooths posteriors smooths model, select can left default value. Typically ’re bothered particular values covariate evaluate posterior smooths; ask 100 evenly spaced values x0 using n_vals, can provide covariates values via data argument. number posterior smooths sampled controlled argument n; ask 100 samples. Objects returned smooth_samples() draw() method available draw posterior smooths can set n_samples randomly select many smooths draw (seed can provided via argument seed make set chosen smooths repeatable.) credible interval smooth contain smooths. standard 95% credible interval, sampled smooths exceed limits interval. Following Marra & Wood (2012), blue credible interval contain average 95% grey lines (posterior smooths) given value x0x_0. across function frequentist interpretation credible interval implies values x0x_0 coverage less 95% values greater 95%.","code":"ss_df <- data_sim(\"eg1\", seed = 42) m_ss <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = ss_df, method = \"REML\") s_x0 <- get_smooth(m_ss, \"s(x0)\") smooth_coef_indices(s_x0) #> [1] 2 3 4 5 6 7 8 9 10 sm_samp <- smooth_samples(m_ss, select = \"s(x0)\", n_vals = 100, n = 100, seed = 21) sm_samp |> draw(alpha = 0.3) # evaluate the fitted smooth over x0 and add on a credible interval sm_est <- smooth_estimates(m_ss, select = \"s(x0)\") |> add_confint() # plot the smooth, credible interval, and posterior smooths sm_est |> ggplot(aes(x = x0)) + geom_lineribbon(aes(ymin = .lower_ci, ymax = .upper_ci), orientation = \"vertical\", fill = \"#56B4E9\", alpha = 0.5 ) + geom_line( data = sm_samp, aes(y = .value, group = .draw), alpha = 0.2 ) + geom_line(aes(y = .estimate), linewidth = 1, colour = \"#E69F00\") + labs(y = smooth_label(s_x0))"},{"path":"https://gavinsimpson.github.io/gratia/articles/posterior-simulation.html","id":"posterior-fitted-values-via-fitted_samples","dir":"Articles","previous_headings":"","what":"Posterior fitted values via fitted_samples()","title":"Posterior Simulation","text":"Posterior fitted values draws posterior distribution mean expected value response. expectations returned use predict() estimated GAM, except fitted_samples() includes uncertainty estimated model coefficients, whereas predict() just uses estimated coefficients. example, using data_sim() simulate data example 6 Luo & Wahba (1997) sin(2⋅(4x−2))+2⋅exp(−256⋅(x−0.5)2) \\sin(2 \\cdot (4x - 2)) + 2 \\cdot \\exp(-256 \\cdot (x - 0.5)^2) data fit adaptive smoother Next create data slice 200 values interval (0,1) ’ll predict model generate posterior fitted values compute fitted values new data posterior fitted values drawn fitted_samples() using Gaussian approximation posterior. just take 10 draws posterior observation new_df merge posterior draws data Adding posterior fitted samples plot data, superimposing Bayesian credible interval fitted values see posterior draws largely contained credible interval. difference smooth_samples() now ’re including effects model terms. simple model single smooth identity link, difference model constant term uncertainty included samples.","code":"f <- function(x) { sin(2 * ((4 * x) - 2)) + (2 * exp(-256 * (x - 0.5)^2)) } df <- data_sim(\"lwf6\", dist = \"normal\", scale = 0.3, seed = 2) plt <- df |> ggplot(aes(x = x, y = y)) + geom_point(alpha = 0.5) + geom_function(fun = f) plt m <- gam(y ~ s(x, k = 25, bs = \"ad\"), data = df, method = \"REML\") new_df <- data_slice(m, x = evenly(x, lower = 0, upper = 1, n = 200)) |> mutate(.row = row_number()) fv <- fitted_values(m, data = new_df) fs <- fitted_samples(m, data = new_df, n = 10, seed = 4) |> left_join(new_df |> select(.row, x), by = join_by(.row == .row)) plt + geom_ribbon(data = fv, aes(y = .fitted, ymin = .lower_ci, ymax = .upper_ci), fill = \"red\", alpha = 0.3) + geom_line(data = fs, aes(group = .draw, x = x, y = .fitted), colour = \"yellow\", alpha = 0.4)"},{"path":[]},{"path":"https://gavinsimpson.github.io/gratia/articles/posterior-simulation.html","id":"prediction-intervals","dir":"Articles","previous_headings":"Additional examples","what":"Prediction intervals","title":"Posterior Simulation","text":"One use posterior simulation generate prediction intervals fitted model. Prediction intervals include two sources uncertainty; estimated model , plus sampling uncertainty error arises drawing observations conditional distribution response. example, Gaussian GAM, first source uncertainty comes uncertainty estimates βj\\beta_j, model coefficients. uncertainty mean expected value response. second source uncertainty stems error term, estimated variance response. two parameters define conditional distribution YiY_i. value covariate(s) 𝐗\\mathbf{X}, estimated model defines entire distribution response values might expect observe covariate values. illustrate, ’ll fit simple GAM single smooth function data simulate Gu & Wabha’s function f2f_2 using data_sim(). simulate 400 values Gaussian distribution variance σ2=1\\sigma^2 = 1. simulated data, true function generated shown GAM data contains single smooth function x consider new value covariate x, x*=0.5x^{\\ast} = 0.5, expected value response given model, 𝔼(y*|x=x*)\\mathbb{E}(y^{*} | x = x^{*}), ~2.92, obtain using predict() value mean Gaussian distribution , model correct description data, describes distribution values YY might take x=0.5x = 0.5. Gaussian distribution defined two parameters; mean, μ\\mu, describes middle distribution, variance, σ2\\sigma^2, describes spread distribution mean. fully describe Gaussian distribution response x=0.5x = 0.5, need estimate variance. didn’t model explicitly GAM, get estimate model’s scale parameter, ϕ\\phi. stored element scale model object can visualise distribution looks like magic ggdist package orange region shows expected density response values x*=0.5x^{\\ast} = 0.5 model predicts expect observe. region assumes uncertainty estimate mean variance. Prediction intervals take account variation expected value, plus uncertainty expected value. fitted_values() conveniently returns uncertainty us, default 95% credible interval .se column standard error (standard deviation) estimated value (.fitted), .lower_ci .upper_ci lower upper uncertainty bounds (95% level) estimated value respectively. GAMs fitted mgcv don’t corresponding estimate uncertainty scale parameter, ϕ\\phi, model estimated standard deviation σ̂\\hat{\\sigma}. pretty easy compute upper lower tail quantiles fitted Gaussian distribution range values x get prediction interval, ’d ignoring uncertainty model estimates mean. Posterior simulation provides simple convenient way generate prediction interval includes model uncertainty, works principle families available mgcv (although practice, families currently supported gratia). compute prediction interval x GAM, creating set data evenly range x observed data used fit model added variable .row used later match posterior simulated values row prediction data set ds. also compute fitted values new observations using fitted_values(). step isn’t required order posterior simulation gratia, ’ll use fitted values later show model estimated values uncertainty contrast prediction interval. use posterior_samples() generate new response data new x values ds use join add prediction data draw asked 10000 posterior draws new value x. Ideally ’d generate least three four times many draws get precise estimate prediction interval, keep number low vignette avoid excessive computation time. ’re also using smoothness parameter selection corrected version Bayesian covariance matrix; matrix adjusted account us knowing value smoothing parameter f(xi)f(x_i). ps tibble, n * nrow(ds) rows. .draw variable groups simulated values posterior draw, .row groups posterior draws value x. summarise posterior draws using {dplyr} need function compute quantiles posterior distribution value x (.row). following function simple wrapper around quantile() function base R, arranges output quantile() data frame. apply function set posterior draws, grouping .row summarise separately posterior distribution new value x. reframe() used summarise posterior using quantile_fun() function. ease use, pivot resulting summary long wide format add covariate values joining .row variable 95% prediction interval shown first 10 rows prediction data. column labelled .q50 median posterior distribution. can now use various objects produced plot fitted values model (uncertainties), well prediction intervals just generated. add observed data used fit model black points, summarise posterior samples (ps) using hexagonal binning (avoid plotting 2 million posterior samples) outermost pair blue lines plot prediction interval created. interval encloses, expected, almost observe data points. also encloses, design, posterior samples, indicated filled hexagonal bins, warmer colours indicating larger counts posterior draws.","code":"df <- data_sim(\"gwf2\", n = 400, scale = 1, dist = \"normal\", seed = 8) df |> ggplot(aes(x = x, y = y)) + geom_point() + geom_function(fun = gw_f2, colour = \"#0072B2\", linewidth = 1.5) m <- gam(y ~ s(x), data = df, method = \"REML\", family = gaussian()) mu <- predict(m, newdata = data.frame(x = 0.5)) mu #> 1 #> 2.919094 sigma <- m$scale sigma #> [1] 1.019426 df |> ggplot(aes(x = x, y = y)) + stat_halfeye(aes(ydist = dist_normal(mean = mu, sd = sigma)), x = 0.5, scale = 0.2, slab_fill = \"#E69F00\", slab_alpha = 0.7 ) + geom_point() + geom_function(fun = gw_f2, colour = \"#0072B2\", linewidth = 1.5) + geom_point(x = 0.5, y = mu, colour = \"red\") fitted_values(m, data = data.frame(x = 0.5)) #> # A tibble: 1 × 6 #> .row x .fitted .se .lower_ci .upper_ci #> #> 1 1 0.5 2.92 0.161 2.60 3.23 ds <- data_slice(m, x = evenly(x, n = 200)) |> mutate(.row = row_number()) fv <- fitted_values(m, data = ds) ps <- posterior_samples(m, n = 10000, data = ds, seed = 24, unconditional = TRUE) |> left_join(ds, by = join_by(.row == .row)) ps #> # A tibble: 2,000,000 × 4 #> .row .draw .response x #> #> 1 1 1 -1.34 0.00129 #> 2 2 1 -0.0495 0.00629 #> 3 3 1 0.0308 0.0113 #> 4 4 1 -0.783 0.0163 #> 5 5 1 0.861 0.0213 #> 6 6 1 0.475 0.0263 #> 7 7 1 0.858 0.0313 #> 8 8 1 0.143 0.0363 #> 9 9 1 -0.0344 0.0413 #> 10 10 1 1.04 0.0463 #> # ℹ 1,999,990 more rows quantile_fun <- function(x, probs = c(0.025, 0.5, 0.975), ...) { tibble::tibble( .value = quantile(x, probs = probs, ...), .q = probs * 100 ) } p_int <- ps |> group_by(.row) |> reframe(quantile_fun(.response)) |> pivot_wider( id_cols = .row, names_from = .q, values_from = .value, names_prefix = \".q\" ) |> left_join(ds, by = join_by(.row == .row)) p_int #> # A tibble: 200 × 5 #> .row .q2.5 .q50 .q97.5 x #> #> 1 1 -2.84 -0.847 1.25 0.00129 #> 2 2 -2.70 -0.651 1.41 0.00629 #> 3 3 -2.50 -0.434 1.62 0.0113 #> 4 4 -2.24 -0.207 1.83 0.0163 #> 5 5 -2.04 -0.0197 2.01 0.0213 #> 6 6 -1.81 0.191 2.25 0.0263 #> 7 7 -1.59 0.391 2.41 0.0313 #> 8 8 -1.38 0.594 2.60 0.0363 #> 9 9 -1.20 0.831 2.84 0.0413 #> 10 10 -0.935 1.06 3.04 0.0463 #> # ℹ 190 more rows fv |> ggplot(aes(x = x, y = .fitted)) + # summarise the posterior samples geom_hex( data = ps, aes(x = x, y = .response, fill = after_stat(count)), bins = 50, alpha = 0.7 ) + # add the lower and upper prediction intervals geom_line(data = p_int, aes(y = .q2.5), colour = \"#56B4E9\", linewidth = 1.5) + geom_line(data = p_int, aes(y = .q97.5), colour = \"#56B4E9\", linewidth = 1.5) + # add the lower and upper credible intervals geom_line(aes(y = .lower_ci), colour = \"#56B4E9\", linewidth = 1) + geom_line(aes(y = .upper_ci), colour = \"#56B4E9\", linewidth = 1) + # add the fitted model geom_line() + # add the observed data geom_point(data = df, aes(x = x, y = y)) + scale_fill_viridis_c(option = \"plasma\") + theme(legend.position = \"none\") + labs(y = \"Response\")"},{"path":"https://gavinsimpson.github.io/gratia/articles/posterior-simulation.html","id":"metropolis-hastings-sampler","dir":"Articles","previous_headings":"Additional examples","what":"Metropolis Hastings sampler","title":"Posterior Simulation","text":"cases, Gaussian approximation posterior distribution model coefficients can fail. Simon Wood shows example just failure ?gam.mh help page, Gaussian approximation basically useless binomial GAM large numbers zeroes. mgcv::gam.mh() implements simple Metropolis Hastings sampler, alternates proposals Gaussian t distribution approximation posterior random walk proposals based shrunken approximate posterior covariance matrix. section, rework Simon’s example failure Gaussian approximation ?gam.mh show use gratia generate posterior draws using Metropolis Hastings sampler provided gam.mh(). begin defining function simulate data example. use simulate data set plot Note zeroes large parts covariate space response zeroes. fit binomial (logistic) GAM data generate sample posterior distribution using default Gaussian approximation subsequently using simpler Metropolis Hastings sampler. method argument used select Metropolis Hastings sampler, specify two additional arguments: thin, controls many draws skipped retained sample, rw_scale, scaling factor posterior covariance matrix shrunk random walk proposals. leave two important arguments defaults: burnin = 1000, number samples discard prior sampling, t_df = 40, degrees freedom t proposals. degrees freedom t proposals large, ’re effectively Gaussian approximation default, alternating proposals random walk proposals. collected posterior draws, summarise set 50%, 80%, 95% intervals using ggdist::median_qi(), add data locations left join First plot intervals Gaussian approximation posterior, repeat plot using intervals derived Metropolis Hastings sampler, arranging two plots using patchwork Gaussian approximation-based intervals shown left figure, range x largely useless, covering entire range response, despite fact observed zeroes large parts covariate space. Contrast intervals ones obtained using Metropolis Hastings sampler; intervals much better reflect uncertainty estimated response function x data zeroes.","code":"ga_fail <- function(seed) { df <- tibble(y = c( rep(0, 89), 1, 0, 1, 0, 0, 1, rep(0, 13), 1, 0, 0, 1, rep(0, 10), 1, 0, 0, 1, 1, 0, 1, rep(0, 4), 1, rep(0, 3), 1, rep(0, 3), 1, rep(0, 10), 1, rep(0, 4), 1, 0, 1, 0, 0, rep(1, 4), 0, rep(1, 5), rep(0, 4), 1, 1, rep(0, 46) )) |> mutate( x = withr::with_seed( seed, sort(c(0:10 * 5, rnorm(length(y) - 11) * 20 + 100)) ), .row = row_number() ) |> relocate(.row, .before = 1L) df } df <- ga_fail(3) df |> ggplot(aes(x = x, y = y)) + geom_point() m_logit <- gam(y ~ s(x, k = 15), data = df, method = \"REML\", family = binomial) fs_ga <- fitted_samples(m_logit, n = 2000, seed = 2) fs_mh <- fitted_samples(m_logit, n = 2000, seed = 2, method = \"mh\", thin = 2, rw_scale = 0.4 ) excl_col <- c(\".draw\", \".parameter\", \".row\") int_ga <- fs_ga |> group_by(.row) |> median_qi(.width = c(0.5, 0.8, 0.95), .exclude = excl_col) |> left_join(df, by = join_by(.row == .row)) int_mh <- fs_mh |> group_by(.row) |> median_qi(.width = c(0.5, 0.8, 0.95), .exclude = excl_col) |> left_join(df, by = join_by(.row == .row)) plt_ga <- df |> ggplot(aes(x = x, y = y)) + geom_point() + geom_lineribbon( data = int_ga, aes(x = x, y = .fitted, ymin = .lower, ymax = .upper) ) + scale_fill_brewer() + labs(title = \"Gaussian approximation\") plt_mh <- df |> ggplot(aes(x = x, y = y)) + geom_point() + geom_lineribbon( data = int_mh, aes(x = x, y = .fitted, ymin = .lower, ymax = .upper) ) + scale_fill_brewer() + labs(title = \"Metropolis Hastings sampler\") plt_ga + plt_mh + plot_layout(guides = \"collect\")"},{"path":[]},{"path":"https://gavinsimpson.github.io/gratia/authors.html","id":null,"dir":"","previous_headings":"","what":"Authors","title":"Authors and Citation","text":"Gavin L. Simpson. Author, maintainer, copyright holder. Henrik Singmann. Contributor.","code":""},{"path":"https://gavinsimpson.github.io/gratia/authors.html","id":"citation","dir":"","previous_headings":"","what":"Citation","title":"Authors and Citation","text":"Simpson G (????). gratia: Graceful ggplot-Based Graphics Functions GAMs Fitted using mgcv. R package version 0.9.2.9012, https://gavinsimpson.github.io/gratia/.","code":"@Manual{, title = {{gratia}: Graceful {ggplot}-Based Graphics and Other Functions for {GAM}s Fitted using {mgcv}}, author = {Gavin L. Simpson}, abstract = {Graceful ggplot-based graphics and utility functions for working with generalized additive models (GAMs) fitted using the mgcv package. Provides a reimplementation of the plot() method for GAMs that mgcv provides, as well as tidyverse-compatible representations of estimated smooths.}, note = {R package version 0.9.2.9012}, url = {https://gavinsimpson.github.io/gratia/}, }"},{"path":[]},{"path":"https://gavinsimpson.github.io/gratia/index.html","id":"overview","dir":"","previous_headings":"","what":"Overview","title":"An R package for working with generalized additive models","text":"Working GAMs within ‘tidyverse’ can tedious even difficult without good understanding GAMs model returned ‘mgcv’ model objects contain. ‘gratia’ designed help . ‘gratia’ provides ‘ggplot’-based graphics utility functions working generalized additive models (GAMs) fitted using ‘mgcv’ package, via reimplementation plot() method GAMs ‘mgcv’ provides, well ‘tidyverse’ compatible representations estimated smooths.","code":""},{"path":"https://gavinsimpson.github.io/gratia/index.html","id":"features","dir":"","previous_headings":"","what":"Features","title":"An R package for working with generalized additive models","text":"main features gratia currently ggplot2-based replacement mgcv:::plot.gam(): draw.gam(). example, classic four term additive example Gu & Wahba: Estimated smooths GAM bivariate smooth: Estimated smooths GAM Note specialist smoothers (bs %% c(\"mrf\",\"sw\", \"sf\")) currently supported, univariate, factor continuous -variable smooths, simple random effect smooths (bs = 're'), factor-smooth interaction smooths (bs = \"fs\"), constrained factor smooths (bs = \"sz\"), full soap film smooths (bs = \"\"), bivariate, trivariate, quadvariate TPRS tensor product smooths supported, Estimation derivatives fitted smoothers: derivatives(), Estimation point-wise across--function confidence intervals simultaneous intervals smooths: confint.gam(). Model diagnostics via appraise() Model diagnostics figure","code":""},{"path":"https://gavinsimpson.github.io/gratia/index.html","id":"installing-gratia","dir":"","previous_headings":"","what":"Installing gratia","title":"An R package for working with generalized additive models","text":"gratia now available CRAN, can installed however gratia active development may wish install development version github. easiest way via install_github() function package remotes. Make sure remotes installed, run install package. Alternatively, binary packages development version available rOpenSci’s R Universe service:","code":"install.packages(\"gratia\") remotes::install_github(\"gavinsimpson/gratia\") # Install gratia in R install.packages(\"gratia\", repos = c( \"https://gavinsimpson.r-universe.dev\", \"https://cloud.r-project.org\" ))"},{"path":"https://gavinsimpson.github.io/gratia/index.html","id":"history","dir":"","previous_headings":"","what":"History","title":"An R package for working with generalized additive models","text":"gratia grew earlier package, schoenberg, development earlier package tsgam, originally intended used GAMs fitted time series. developing tsgam however became clear package used generally name “tsgam” longer appropriate. avoid breaking blog posts written using tsgam decided copy git repo history new repo package name schoenberg. later date someone released another package called schoenberg CRAN, scuppered idea. Now ’m calling package gratia. Hopefully won’t change …","code":""},{"path":"https://gavinsimpson.github.io/gratia/index.html","id":"why-gratia","dir":"","previous_headings":"","what":"Why gratia?","title":"An R package for working with generalized additive models","text":"naming greta package, Nick Golding observed recent phenomena naming statistical modelling software, Stan Edward, individuals played prominent role development field. lead Nick name Tensor Flow-based package greta Grete Hermann. spirit, gratia named recognition contributions Grace Wahba, pioneering work penalised spline models foundation way GAMs estimated mgcv. wanted name package grace, explicitly recognise Grace’s contributions, unfortunately already package named Grace CRAN. looked elsewhere inspiration. English word “grace” derives Latin gratia, meaning “favor, charm, thanks” (according Merriam Webster). chair Grace Wabha currently holds named Isaac J Schoenberg, former University Madison-Wisconsin Professor Mathematics, 1946 paper provided first mathematical reference “splines”. (Hence previous name package.)","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/add_confint.html","id":null,"dir":"Reference","previous_headings":"","what":"Add a confidence interval to an existing object — add_confint","title":"Add a confidence interval to an existing object — add_confint","text":"Add confidence interval existing object","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/add_confint.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Add a confidence interval to an existing object — add_confint","text":"","code":"add_confint(object, coverage = 0.95, ...) # S3 method for class 'smooth_estimates' add_confint(object, coverage = 0.95, ...) # S3 method for class 'parametric_effects' add_confint(object, coverage = 0.95, ...) # Default S3 method add_confint(object, coverage = 0.95, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/add_confint.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Add a confidence interval to an existing object — add_confint","text":"object R object. coverage numeric; coverage interval. Must range 0 < coverage < 1. ... arguments passed methods.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/add_constant.html","id":null,"dir":"Reference","previous_headings":"","what":"Add a constant to estimated values — add_constant","title":"Add a constant to estimated values — add_constant","text":"Add constant estimated values","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/add_constant.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Add a constant to estimated values — add_constant","text":"","code":"add_constant(object, constant = NULL, ...) # S3 method for class 'smooth_estimates' add_constant(object, constant = NULL, ...) # S3 method for class 'smooth_samples' add_constant(object, constant = NULL, ...) # S3 method for class 'mgcv_smooth' add_constant(object, constant = NULL, ...) # S3 method for class 'parametric_effects' add_constant(object, constant = NULL, ...) # S3 method for class 'tbl_df' add_constant(object, constant = NULL, column = NULL, ...) # S3 method for class 'evaluated_parametric_term' add_constant(object, constant = NULL, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/add_constant.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Add a constant to estimated values — add_constant","text":"object object add constant . constant constant add. ... additional arguments passed methods. column character; \"tbl_df\" method, column add constant .","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/add_constant.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Add a constant to estimated values — add_constant","text":"Returns object estimate shifted addition supplied constant.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/add_constant.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Add a constant to estimated values — add_constant","text":"Gavin L. Simpson","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/add_fitted.gam.html","id":null,"dir":"Reference","previous_headings":"","what":"Add fitted values from a GAM to a data frame — add_fitted.gam","title":"Add fitted values from a GAM to a data frame — add_fitted.gam","text":"Add fitted values GAM data frame","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/add_fitted.gam.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Add fitted values from a GAM to a data frame — add_fitted.gam","text":"","code":"# S3 method for class 'gam' add_fitted(data, model, value = \".fitted\", type = \"response\", ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/add_fitted.gam.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Add fitted values from a GAM to a data frame — add_fitted.gam","text":"data data frame containing values variables used fit model. Passed stats::predict() newdata. model fitted model stats::predict() method available. S3 method dispatch performed model argument. value character; name variable model predictions stored. type character; type predictions return. See mgcv::predict.gam() options. ... additional arguments passed mgcv::predict.gam().","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/add_fitted.gam.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Add fitted values from a GAM to a data frame — add_fitted.gam","text":"data frame (tibble) formed data predictions model.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/add_fitted.gam.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Add fitted values from a GAM to a data frame — add_fitted.gam","text":"","code":"load_mgcv() df <- data_sim(\"eg1\", seed = 1) df <- df[, c(\"y\", \"x0\", \"x1\", \"x2\", \"x3\")] m <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = df, method = \"REML\") # add fitted values to our data add_fitted(df, m) #> # A tibble: 400 x 6 #> y x0 x1 x2 x3 .fitted #> #> 1 3.34 0.266 0.659 0.859 0.367 5.90 #> 2 -0.0758 0.372 0.185 0.0344 0.741 3.15 #> 3 10.7 0.573 0.954 0.971 0.934 8.28 #> 4 8.73 0.908 0.898 0.745 0.673 8.65 #> 5 15.0 0.202 0.944 0.273 0.701 15.7 #> 6 7.67 0.898 0.724 0.677 0.848 8.38 #> 7 7.58 0.945 0.370 0.348 0.706 7.84 #> 8 8.51 0.661 0.781 0.947 0.859 6.74 #> 9 10.6 0.629 0.0111 0.339 0.446 9.14 #> 10 3.72 0.0618 0.940 0.0317 0.677 7.04 #> # i 390 more rows # with type = \"terms\" or \"iterms\" add_fitted(df, m, type = \"terms\") #> # A tibble: 400 x 10 #> y x0 x1 x2 x3 .constant `s(x0)` `s(x1)` `s(x2)` `s(x3)` #> #> 1 3.34 0.266 0.659 0.859 0.367 7.94 0.175 0.559 -2.81 0.0351 #> 2 -0.0758 0.372 0.185 0.0344 0.741 7.94 0.435 -1.92 -3.23 -0.0687 #> 3 10.7 0.573 0.954 0.971 0.934 7.94 0.593 3.35 -3.47 -0.122 #> 4 8.73 0.908 0.898 0.745 0.673 7.94 -0.812 2.77 -1.19 -0.0498 #> 5 15.0 0.202 0.944 0.273 0.701 7.94 -0.0589 3.23 4.63 -0.0576 #> 6 7.67 0.898 0.724 0.677 0.848 7.94 -0.745 1.15 0.146 -0.0981 #> 7 7.58 0.945 0.370 0.348 0.706 7.94 -1.07 -1.31 2.34 -0.0589 #> 8 8.51 0.661 0.781 0.947 0.859 7.94 0.434 1.67 -3.20 -0.101 #> 9 10.6 0.629 0.0111 0.339 0.446 7.94 0.512 -1.95 2.63 0.0132 #> 10 3.72 0.0618 0.940 0.0317 0.677 7.94 -0.695 3.20 -3.35 -0.0508 #> # i 390 more rows"},{"path":"https://gavinsimpson.github.io/gratia/reference/add_fitted.html","id":null,"dir":"Reference","previous_headings":"","what":"Add fitted values from a model to a data frame — add_fitted","title":"Add fitted values from a model to a data frame — add_fitted","text":"Add fitted values model data frame","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/add_fitted.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Add fitted values from a model to a data frame — add_fitted","text":"","code":"add_fitted(data, model, value = \".value\", ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/add_fitted.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Add fitted values from a model to a data frame — add_fitted","text":"data data frame containing values variables used fit model. Passed stats::predict() newdata. model fitted model stats::predict() method available. S3 method dispatch performed model argument. value character; name variable model predictions stored. ... additional arguments passed methods.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/add_fitted.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Add fitted values from a model to a data frame — add_fitted","text":"data frame (tibble) formed data fitted values model.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/add_fitted_samples.html","id":null,"dir":"Reference","previous_headings":"","what":"Add posterior draws from a model to a data object — add_fitted_samples","title":"Add posterior draws from a model to a data object — add_fitted_samples","text":"Adds draws posterior distribution model data object using one fitted_samples(), predicted_samples(), posterior_samples().","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/add_fitted_samples.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Add posterior draws from a model to a data object — add_fitted_samples","text":"","code":"add_fitted_samples(object, model, n = 1, seed = NULL, ...) add_predicted_samples(object, model, n = 1, seed = NULL, ...) add_posterior_samples(object, model, n = 1, seed = NULL, ...) add_smooth_samples(object, model, n = 1, seed = NULL, select = NULL, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/add_fitted_samples.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Add posterior draws from a model to a data object — add_fitted_samples","text":"object data frame tibble posterior draws added. model fitted GAM (GAM-like) object posterior draw method exists. n integer; number posterior draws add. seed numeric; value seed random number generator. ... arguments passed posterior draw function, currently one fitted_samples(), predicted_samples(), posterior_samples(). n seed already specified arguments also passed posterior sampling function. select character; select smooth's posterior draw . default, NULL, means posteriors smooths model wil sampled individually. supplied, character vector requested smooth terms.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/add_fitted_samples.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Add posterior draws from a model to a data object — add_fitted_samples","text":"","code":"load_mgcv() df <- data_sim(\"eg1\", n = 400, seed = 42) m <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = df, method = \"REML\") # add fitted samples (posterior draws of the expected value of the response) # note that there are 800 rows in the output: 400 data by `n = 2` samples. df |> add_fitted_samples(m, n = 2, seed = 84) #> # A tibble: 800 × 14 #> y x0 x1 x2 x3 f f0 f1 f2 f3 .row .draw #> #> 1 2.99 0.915 0.0227 0.909 0.402 1.62 0.529 1.05 0.0397 0 1 1 #> 2 2.99 0.915 0.0227 0.909 0.402 1.62 0.529 1.05 0.0397 0 1 2 #> 3 4.70 0.937 0.513 0.900 0.432 3.25 0.393 2.79 0.0630 0 2 1 #> 4 4.70 0.937 0.513 0.900 0.432 3.25 0.393 2.79 0.0630 0 2 2 #> 5 13.9 0.286 0.631 0.192 0.664 13.5 1.57 3.53 8.41 0 3 1 #> 6 13.9 0.286 0.631 0.192 0.664 13.5 1.57 3.53 8.41 0 3 2 #> 7 5.71 0.830 0.419 0.532 0.182 6.12 1.02 2.31 2.79 0 4 1 #> 8 5.71 0.830 0.419 0.532 0.182 6.12 1.02 2.31 2.79 0 4 2 #> 9 7.63 0.642 0.879 0.522 0.838 10.4 1.80 5.80 2.76 0 5 1 #> 10 7.63 0.642 0.879 0.522 0.838 10.4 1.80 5.80 2.76 0 5 2 #> # ℹ 790 more rows #> # ℹ 2 more variables: .parameter , .fitted # add posterior draws from smooth s(x2) df |> add_smooth_samples(m, n = 2, seed = 2, select= \"s(x2)\") #> # A tibble: 800 × 15 #> y x0 x1 x2 x3 f f0 f1 f2 f3 .row .smooth #> #> 1 2.99 0.915 0.0227 0.909 0.402 1.62 0.529 1.05 0.0397 0 1 s(x2) #> 2 2.99 0.915 0.0227 0.909 0.402 1.62 0.529 1.05 0.0397 0 1 s(x2) #> 3 4.70 0.937 0.513 0.900 0.432 3.25 0.393 2.79 0.0630 0 2 s(x2) #> 4 4.70 0.937 0.513 0.900 0.432 3.25 0.393 2.79 0.0630 0 2 s(x2) #> 5 13.9 0.286 0.631 0.192 0.664 13.5 1.57 3.53 8.41 0 3 s(x2) #> 6 13.9 0.286 0.631 0.192 0.664 13.5 1.57 3.53 8.41 0 3 s(x2) #> 7 5.71 0.830 0.419 0.532 0.182 6.12 1.02 2.31 2.79 0 4 s(x2) #> 8 5.71 0.830 0.419 0.532 0.182 6.12 1.02 2.31 2.79 0 4 s(x2) #> 9 7.63 0.642 0.879 0.522 0.838 10.4 1.80 5.80 2.76 0 5 s(x2) #> 10 7.63 0.642 0.879 0.522 0.838 10.4 1.80 5.80 2.76 0 5 s(x2) #> # ℹ 790 more rows #> # ℹ 3 more variables: .term , .draw , .value "},{"path":"https://gavinsimpson.github.io/gratia/reference/add_partial_residuals.html","id":null,"dir":"Reference","previous_headings":"","what":"Add partial residuals — add_partial_residuals","title":"Add partial residuals — add_partial_residuals","text":"Add partial residuals","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/add_partial_residuals.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Add partial residuals — add_partial_residuals","text":"","code":"add_partial_residuals(data, model, ...) # S3 method for class 'gam' add_partial_residuals(data, model, select = NULL, partial_match = FALSE, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/add_partial_residuals.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Add partial residuals — add_partial_residuals","text":"data data frame containing values variables used fit model. Passed stats::residuals() newdata. model fitted model stats::residuals() method available. S3 method dispatch performed model argument. ... arguments passed methods. select character, logical, numeric; smooths plot. NULL, default, model smooths drawn. Numeric select indexes smooths order specified formula stored object. Character select matches labels smooths shown example output summary(object). Logical select operates per numeric select order smooths stored. partial_match logical; smooths selected partial matches select? TRUE, select can single string match .","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/add_partial_residuals.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Add partial residuals — add_partial_residuals","text":"","code":"load_mgcv() df <- data_sim(\"eg1\", seed = 1) df <- df[, c(\"y\", \"x0\", \"x1\", \"x2\", \"x3\")] m <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = df, method = \"REML\") ## add partial residuals add_partial_residuals(df, m) #> # A tibble: 400 x 9 #> y x0 x1 x2 x3 `s(x0)` `s(x1)` `s(x2)` `s(x3)` #> #> 1 3.34 0.266 0.659 0.859 0.367 -2.38 -2.00 -5.36 -2.52 #> 2 -0.0758 0.372 0.185 0.0344 0.741 -2.79 -5.15 -6.45 -3.29 #> 3 10.7 0.573 0.954 0.971 0.934 2.99 5.75 -1.07 2.28 #> 4 8.73 0.908 0.898 0.745 0.673 -0.734 2.84 -1.11 0.0287 #> 5 15.0 0.202 0.944 0.273 0.701 -0.752 2.54 3.94 -0.750 #> 6 7.67 0.898 0.724 0.677 0.848 -1.46 0.432 -0.567 -0.812 #> 7 7.58 0.945 0.370 0.348 0.706 -1.33 -1.57 2.08 -0.318 #> 8 8.51 0.661 0.781 0.947 0.859 2.21 3.44 -1.42 1.68 #> 9 10.6 0.629 0.0111 0.339 0.446 2.01 -0.445 4.13 1.51 #> 10 3.72 0.0618 0.940 0.0317 0.677 -4.02 -0.123 -6.67 -3.37 #> # i 390 more rows ## add partial residuals for selected smooths add_partial_residuals(df, m, select = \"s(x0)\") #> # A tibble: 400 x 6 #> y x0 x1 x2 x3 `s(x0)` #> #> 1 3.34 0.266 0.659 0.859 0.367 -2.38 #> 2 -0.0758 0.372 0.185 0.0344 0.741 -2.79 #> 3 10.7 0.573 0.954 0.971 0.934 2.99 #> 4 8.73 0.908 0.898 0.745 0.673 -0.734 #> 5 15.0 0.202 0.944 0.273 0.701 -0.752 #> 6 7.67 0.898 0.724 0.677 0.848 -1.46 #> 7 7.58 0.945 0.370 0.348 0.706 -1.33 #> 8 8.51 0.661 0.781 0.947 0.859 2.21 #> 9 10.6 0.629 0.0111 0.339 0.446 2.01 #> 10 3.72 0.0618 0.940 0.0317 0.677 -4.02 #> # i 390 more rows"},{"path":"https://gavinsimpson.github.io/gratia/reference/add_residuals.gam.html","id":null,"dir":"Reference","previous_headings":"","what":"Add residuals from a GAM to a data frame — add_residuals.gam","title":"Add residuals from a GAM to a data frame — add_residuals.gam","text":"Add residuals GAM data frame","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/add_residuals.gam.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Add residuals from a GAM to a data frame — add_residuals.gam","text":"","code":"# S3 method for class 'gam' add_residuals(data, model, value = \".residual\", type = \"deviance\", ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/add_residuals.gam.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Add residuals from a GAM to a data frame — add_residuals.gam","text":"data data frame containing values variables used fit model. Passed stats::predict() newdata. model fitted model stats::predict() method available. S3 method dispatch performed model argument. value character; name variable model predictions stored. type character; type residuals return. See mgcv::residuals.gam() options. ... additional arguments passed mgcv::residuals.gam().","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/add_residuals.gam.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Add residuals from a GAM to a data frame — add_residuals.gam","text":"data frame (tibble) formed data residuals model.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/add_residuals.gam.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Add residuals from a GAM to a data frame — add_residuals.gam","text":"","code":"load_mgcv() df <- data_sim(\"eg1\", seed = 1) df <- df[, c(\"y\", \"x0\", \"x1\", \"x2\", \"x3\")] m <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = df, method = \"REML\") ## add_residuals(df, m) #> # A tibble: 400 x 6 #> y x0 x1 x2 x3 .residual #> #> 1 3.34 0.266 0.659 0.859 0.367 -2.56 #> 2 -0.0758 0.372 0.185 0.0344 0.741 -3.22 #> 3 10.7 0.573 0.954 0.971 0.934 2.40 #> 4 8.73 0.908 0.898 0.745 0.673 0.0785 #> 5 15.0 0.202 0.944 0.273 0.701 -0.693 #> 6 7.67 0.898 0.724 0.677 0.848 -0.714 #> 7 7.58 0.945 0.370 0.348 0.706 -0.259 #> 8 8.51 0.661 0.781 0.947 0.859 1.78 #> 9 10.6 0.629 0.0111 0.339 0.446 1.50 #> 10 3.72 0.0618 0.940 0.0317 0.677 -3.32 #> # i 390 more rows"},{"path":"https://gavinsimpson.github.io/gratia/reference/add_residuals.html","id":null,"dir":"Reference","previous_headings":"","what":"Add residuals from a model to a data frame — add_residuals","title":"Add residuals from a model to a data frame — add_residuals","text":"Add residuals model data frame","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/add_residuals.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Add residuals from a model to a data frame — add_residuals","text":"","code":"add_residuals(data, model, value = \".residual\", ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/add_residuals.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Add residuals from a model to a data frame — add_residuals","text":"data data frame containing values variables used fit model. Passed stats::residuals() newdata. model fitted model stats::residuals() method available. S3 method dispatch performed model argument. value character; name variable model residuals stored. ... additional arguments passed methods.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/add_residuals.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Add residuals from a model to a data frame — add_residuals","text":"data frame (tibble) formed data residuals model.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/add_sizer.html","id":null,"dir":"Reference","previous_headings":"","what":"Add indicators of significant change after SiZeR — add_sizer","title":"Add indicators of significant change after SiZeR — add_sizer","text":"Add indicators significant change SiZeR","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/add_sizer.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Add indicators of significant change after SiZeR — add_sizer","text":"","code":"add_sizer(object, type = c(\"change\", \"sizer\"), ...) # S3 method for class 'derivatives' add_sizer(object, type = c(\"change\", \"sizer\"), ...) # S3 method for class 'smooth_estimates' add_sizer(object, type = c(\"change\", \"sizer\"), derivatives = NULL, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/add_sizer.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Add indicators of significant change after SiZeR — add_sizer","text":"object R object. Currently supported methods classes \"derivatives\". type character; \"change\" adds single variable object indicating credible interval derivative excludes 0. \"sizer\" adds two variables indicating whether derivative postive negative. ... arguments passed methods derivatives object class \"derivatives\", resulting call derivatives().","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/add_sizer.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Add indicators of significant change after SiZeR — add_sizer","text":"","code":"load_mgcv() df <- data_sim(\"eg1\", n = 400, dist = \"normal\", scale = 2, seed = 42) m <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = df, method = \"REML\") ## first derivatives of all smooths using central finite differences d <- derivatives(m, type = \"central\") |> add_sizer() # default adds a .change column names(d) #> [1] \".smooth\" \".by\" \".fs\" \".derivative\" \".se\" #> [6] \".crit\" \".lower_ci\" \".upper_ci\" \".change\" \"x0\" #> [11] \"x1\" \"x2\" \"x3\""},{"path":"https://gavinsimpson.github.io/gratia/reference/appraise.html","id":null,"dir":"Reference","previous_headings":"","what":"Model diagnostic plots — appraise","title":"Model diagnostic plots — appraise","text":"Model diagnostic plots","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/appraise.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Model diagnostic plots — appraise","text":"","code":"appraise(model, ...) # S3 method for class 'gam' appraise( model, method = c(\"uniform\", \"simulate\", \"normal\", \"direct\"), use_worm = FALSE, n_uniform = 10, n_simulate = 50, seed = NULL, type = c(\"deviance\", \"pearson\", \"response\"), n_bins = c(\"sturges\", \"scott\", \"fd\"), ncol = NULL, nrow = NULL, guides = \"keep\", level = 0.9, ci_col = \"black\", ci_alpha = 0.2, point_col = \"black\", point_alpha = 1, line_col = \"red\", ... ) # S3 method for class 'lm' appraise(model, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/appraise.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Model diagnostic plots — appraise","text":"model fitted model. Currently models inheriting class \"gam\", well classes \"glm\" \"lm\" calls stats::glm stats::lm supported. ... arguments passed patchwork::wrap_plots(). method character; method used generate theoretical quantiles. default \"uniform\", generates reference quantiles using random draws uniform distribution inverse cummulative distribution function (CDF) fitted values. reference quantiles averaged n_uniform draws. \"simulate\" generates reference quantiles simulating new response data model observed values covariates, residualised generate reference quantiles, using n_simulate simulated data sets. \"normal\" generates reference quantiles using standard normal distribution. \"uniform\" computationally efficient, \"simulate\" allows reference bands drawn QQ-plot. \"normal\" avoided used fall back random number generator (\"simulate\") inverse CDF (\"uniform\"``) available family` used model fitting. Note method = \"direct\" deprecated favour method = \"uniform\". use_worm logical; worm plot drawn place QQ plot? n_uniform numeric; number times randomize uniform quantiles direct computation method (method = \"direct\") QQ plots. n_simulate numeric; number data sets simulate estimated model using simulation method (method = \"simulate\") QQ plots. seed numeric; random number seed use method = \"simulate\" method = \"uniform\". type character; type residuals use. \"deviance\", \"response\", \"pearson\" residuals allowed. n_bins character numeric; either number bins string indicating calculate number bins. ncol, nrow numeric; numbers rows columns spread plots. guides character; one \"keep\" (default), \"collect\", \"auto\". Passed patchwork::plot_layout() level numeric; coverage level QQ plot reference intervals. Must strictly 0 < level < 1. used method = \"simulate\". ci_alpha, ci_col colour transparency used draw QQ plot reference interval method = \"simulate\". point_col, point_alpha colour transparency used draw points plots. See graphics::par() section Color Specification. passed individual plotting functions, therefore affects points plots. line_col colour specification 1:1 line QQ plot reference line residuals vs linear predictor plot.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/appraise.html","id":"note","dir":"Reference","previous_headings":"","what":"Note","title":"Model diagnostic plots — appraise","text":"wording used mgcv::qq.gam() uses direct reference simulated residuals method (method = \"simulated\"). avoid confusion, method = \"direct\" deprecated favour method = \"uniform\".","code":""},{"path":[]},{"path":"https://gavinsimpson.github.io/gratia/reference/appraise.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Model diagnostic plots — appraise","text":"","code":"load_mgcv() ## simulate some data... dat <- data_sim(\"eg1\", n = 400, dist = \"normal\", scale = 2, seed = 2) mod <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = dat) ## run some basic model checks appraise(mod, point_col = \"steelblue\", point_alpha = 0.4) ## To change the theme for all panels use the & operator, for example to ## change the ggplot theme for all panels library(\"ggplot2\") appraise(mod, seed = 42, point_col = \"steelblue\", point_alpha = 0.4, line_col = \"black\" ) & theme_minimal()"},{"path":"https://gavinsimpson.github.io/gratia/reference/basis.html","id":null,"dir":"Reference","previous_headings":"","what":"Basis expansions for smooths — basis","title":"Basis expansions for smooths — basis","text":"Creates basis expansion definition smoother using syntax mgcv's smooths via mgcv::s()., mgcv::te(), mgcv::ti(), mgcv::t2(), fitted GAM(M).","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/basis.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Basis expansions for smooths — basis","text":"","code":"basis(object, ...) # S3 method for class 'gam' basis( object, select = NULL, term = deprecated(), data = NULL, n = 100, n_2d = 50, n_3d = 16, n_4d = 4, partial_match = FALSE, ... ) # S3 method for class 'scam' basis( object, select = NULL, term = deprecated(), data = NULL, n = 100, n_2d = 50, n_3d = 16, n_4d = 4, partial_match = FALSE, ... ) # S3 method for class 'gamm' basis( object, select = NULL, term = deprecated(), data = NULL, n = 100, n_2d = 50, n_3d = 16, n_4d = 4, partial_match = FALSE, ... ) # S3 method for class 'list' basis( object, select = NULL, term = deprecated(), data = NULL, n = 100, n_2d = 50, n_3d = 16, n_4d = 4, partial_match = FALSE, ... ) # Default S3 method basis( object, data, knots = NULL, constraints = FALSE, at = NULL, diagonalize = FALSE, ... )"},{"path":"https://gavinsimpson.github.io/gratia/reference/basis.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Basis expansions for smooths — basis","text":"object smooth specification, result call one mgcv::s()., mgcv::te(), mgcv::ti(), mgcv::t2(), fitted GAM(M) model. ... arguments passed mgcv::smoothCon(). select character; select smooths fitted model term argument renamed select data data frame containing variables used smooth. n numeric; number points range covariate evaluate smooth. n_2d numeric; number new observations dimension bivariate smooth. currently used; n used dimensions. n_3d numeric; number new observations generate third dimension 3D smooth. n_4d numeric; number new observations generate dimensions higher 2 (!) kD smooth (k >= 4). example, smooth 4D smooth, dimensions 3 4 get n_4d new observations. partial_match logical; case character select, select match partially smooths? partial_match = TRUE, select must single string, character vector length 1. knots list data frame named components containing knots locations. Names must match covariates basis required. See mgcv::smoothCon(). constraints logical; identifiability constraints applied smooth basis. See argument absorb.cons mgcv::smoothCon(). data frame containing values smooth covariate(s) basis evaluated. diagonalize logical; TRUE, reparameterises smooth associated penalty identity matrix. effect turning last diagonal elements penalty zero, highlights penalty null space.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/basis.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Basis expansions for smooths — basis","text":"tibble.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/basis.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Basis expansions for smooths — basis","text":"Gavin L. Simpson","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/basis.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Basis expansions for smooths — basis","text":"","code":"load_mgcv() df <- data_sim(\"eg4\", n = 400, seed = 42) bf <- basis(s(x0), data = df) bf <- basis(s(x2, by = fac, bs = \"bs\"), data = df, constraints = TRUE)"},{"path":"https://gavinsimpson.github.io/gratia/reference/basis_size.html","id":null,"dir":"Reference","previous_headings":"","what":"Extract basis dimension of a smooth — basis_size","title":"Extract basis dimension of a smooth — basis_size","text":"Extract basis dimension smooth","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/basis_size.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Extract basis dimension of a smooth — basis_size","text":"","code":"basis_size(object, ...) # S3 method for class 'mgcv.smooth' basis_size(object, ...) # S3 method for class 'gam' basis_size(object, ...) # S3 method for class 'gamm' basis_size(object, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/basis_size.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Extract basis dimension of a smooth — basis_size","text":"object fitted GAM(M). Currently mgcv::gam() (anything inherits \"gam\" class, e.g. mgcv::bam()) mgcv::gamm() supported. ... Arguments passed methods.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/basis_size.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Extract basis dimension of a smooth — basis_size","text":"","code":"load_mgcv() df <- data_sim(\"eg1\", n = 200, seed = 1) m <- bam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = df) basis_size(m) #> s(x0) s(x1) s(x2) s(x3) #> 9 9 9 9"},{"path":"https://gavinsimpson.github.io/gratia/reference/bird_move.html","id":null,"dir":"Reference","previous_headings":"","what":"Simulated bird migration data — bird_move","title":"Simulated bird migration data — bird_move","text":"Data generated hypothetical study bird movement along migration corridor, sampled throughout year. dataset consists simulated sample records numbers observed locations 100 tagged individuals six species bird, ten locations along latitudinal gradient, one observation taken every four weeks. Counts simulated randomly species location week creating species-specific migration curve gave probability finding individual given species given location, simulated distribution individuals across sites using multinomial distribution, subsampling using binomial distribution simulation observation error (.e. every bird present location detected). data set (bird_move) consists variables count, latitude, week species.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/bird_move.html","id":"format","dir":"Reference","previous_headings":"","what":"Format","title":"Simulated bird migration data — bird_move","text":"data frame","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/bird_move.html","id":"source","dir":"Reference","previous_headings":"","what":"Source","title":"Simulated bird migration data — bird_move","text":"Pedersen EJ, Miller DL, Simpson GL, Ross N. 2018. Hierarchical generalized additive models: introduction mgcv. PeerJ Preprints 6:e27320v1 doi:10.7287/peerj.preprints.27320v1 .","code":""},{"path":[]},{"path":"https://gavinsimpson.github.io/gratia/reference/boundary.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Extract the boundary of a soap film smooth — boundary","text":"","code":"boundary(x, ...) # S3 method for class 'soap.film' boundary(x, ...) # S3 method for class 'gam' boundary(x, select, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/boundary.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Extract the boundary of a soap film smooth — boundary","text":"x R object. Currently objects inherit classes \"soap.film\" \"gam\". ... arguments passed methods. select character; label soap film smooth extract boundary.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/boundary.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Extract the boundary of a soap film smooth — boundary","text":"list lists data frames specifying loops define boundary soap film smooth.","code":""},{"path":[]},{"path":"https://gavinsimpson.github.io/gratia/reference/check_user_select_smooths.html","id":null,"dir":"Reference","previous_headings":"","what":"Select smooths based on user's choices — check_user_select_smooths","title":"Select smooths based on user's choices — check_user_select_smooths","text":"Given vector indexing smooths GAM, returns logical vector selecting requested smooths.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/check_user_select_smooths.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Select smooths based on user's choices — check_user_select_smooths","text":"","code":"check_user_select_smooths( smooths, select = NULL, partial_match = FALSE, model_name = NULL )"},{"path":"https://gavinsimpson.github.io/gratia/reference/check_user_select_smooths.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Select smooths based on user's choices — check_user_select_smooths","text":"smooths character; vector smooth labels. select numeric, logical, character vector selected smooths. partial_match logical; case character select, select match partially smooths? partial_match = TRUE, select must single string, character vector length 1. model_name character; model name used error messages.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/check_user_select_smooths.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Select smooths based on user's choices — check_user_select_smooths","text":"logical vector length length(smooths) indicating smooths selected.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/check_user_select_smooths.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Select smooths based on user's choices — check_user_select_smooths","text":"Gavin L. Simpson","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/coef.scam.html","id":null,"dir":"Reference","previous_headings":"","what":"Extract coefficients from a fitted scam model. — coef.scam","title":"Extract coefficients from a fitted scam model. — coef.scam","text":"Extract coefficients fitted scam model.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/coef.scam.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Extract coefficients from a fitted scam model. — coef.scam","text":"","code":"# S3 method for class 'scam' coef(object, parametrized = TRUE, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/coef.scam.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Extract coefficients from a fitted scam model. — coef.scam","text":"object model object fitted scam() parametrized logical; extract parametrized coefficients, respect linear inequality constraints model. ... arguments.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/compare_smooths.html","id":null,"dir":"Reference","previous_headings":"","what":"Compare smooths across models — compare_smooths","title":"Compare smooths across models — compare_smooths","text":"Compare smooths across models","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/compare_smooths.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Compare smooths across models — compare_smooths","text":"","code":"compare_smooths( model, ..., select = NULL, smooths = deprecated(), n = 100, data = NULL, unconditional = FALSE, overall_uncertainty = TRUE, partial_match = FALSE )"},{"path":"https://gavinsimpson.github.io/gratia/reference/compare_smooths.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Compare smooths across models — compare_smooths","text":"model Primary model comparison. ... Additional models compare smooths model. select character; select smooths compare. default (NULL) means smooths model compared. Numeric select indexes smooths order specified formula stored model. Character select matches labels smooths shown example output summary(object). Logical select operates per numeric select order smooths stored. smooths Use select instead. n numeric; number points range covariate evaluate smooth. data data frame covariate values evaluate smooth. unconditional logical; confidence intervals include uncertainty due smoothness selection? TRUE, corrected Bayesian covariance matrix used. overall_uncertainty logical; uncertainty model constant term included standard error evaluate values smooth? partial_match logical; smooths selected partial matches select? TRUE, select can single string match .","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/compare_smooths.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Compare smooths across models — compare_smooths","text":"","code":"load_mgcv() dat <- data_sim(\"eg1\", seed = 2) ## models to compare smooths across - artificially create differences m1 <- gam(y ~ s(x0, k = 5) + s(x1, k = 5) + s(x2, k = 5) + s(x3, k = 5), data = dat, method = \"REML\" ) m2 <- gam(y ~ s(x0, bs = \"ts\") + s(x1, bs = \"ts\") + s(x2, bs = \"ts\") + s(x3, bs = \"ts\"), data = dat, method = \"REML\") ## build comparisons comp <- compare_smooths(m1, m2) comp #> # A tibble: 8 x 5 #> .model .smooth .type .by data #> #> 1 m1 s(x0) TPRS NA #> 2 m2 s(x0) TPRS (shrink) NA #> 3 m1 s(x1) TPRS NA #> 4 m2 s(x1) TPRS (shrink) NA #> 5 m1 s(x2) TPRS NA #> 6 m2 s(x2) TPRS (shrink) NA #> 7 m1 s(x3) TPRS NA #> 8 m2 s(x3) TPRS (shrink) NA ## notice that the result is a nested tibble draw(comp)"},{"path":"https://gavinsimpson.github.io/gratia/reference/conditional_values.html","id":null,"dir":"Reference","previous_headings":"","what":"Generated predicted values from a GAM, conditional upon supplied values of covariates — conditional_values","title":"Generated predicted values from a GAM, conditional upon supplied values of covariates — conditional_values","text":"Generated predicted values GAM, conditional upon supplied values covariates","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/conditional_values.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Generated predicted values from a GAM, conditional upon supplied values of covariates — conditional_values","text":"","code":"conditional_values( model, condition = NULL, data = NULL, scale = c(\"response\", \"link\", \"linear_predictor\"), ... ) # S3 method for class 'gam' conditional_values( model, condition = NULL, data = NULL, scale = c(\"response\", \"link\", \"linear_predictor\"), n_vals = 100, ci_level = 0.95, ... )"},{"path":"https://gavinsimpson.github.io/gratia/reference/conditional_values.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Generated predicted values from a GAM, conditional upon supplied values of covariates — conditional_values","text":"model fitted GAM object. condition either character vector list supplying names covariates, possibly values, condition . order values determines plotted via draw.conditional_values() method; first element mapped x channel, second element colour channel, third ggplot2::facet_wrap() fourth element present, present, fourth element mapped rows third element mapped columns ggplot2::facet_grid(). data data frame values predict. supplied overrides values supplied condition. scale character; scale predictions returned ? ... arguments passed fitted_values(). n_vals numeric; number values generate numeric variables named condition. ci_level numeric; number interval (0,1) giving coverage credible intervals.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/conditional_values.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Generated predicted values from a GAM, conditional upon supplied values of covariates — conditional_values","text":"","code":"load_mgcv() df <- data_sim(\"eg1\", seed = 2) m1 <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = df, method = \"REML\") # predictions conditional on values evenly spaced over x2, all other # variables in model are held at representative values cv <- conditional_values( m1, condition = \"x2\" ) # plot cv |> draw() # as above but condition on `x1` also. When plotted, `x1` is mapped to the # colour channel, noting that it has been summarised using fivenum() cv <- conditional_values( m1, condition = c(\"x2\", \"x1\") ) # plot cv |> draw() # can pass `condition` a list, allowing for greater flexibility # For example, here we condition on all four variables in the model, # summarising: # * `x1` at its deciles, # * `x0 at its quartiles # * `x3` at its mean a d mean +/- sd cv <- conditional_values( m1, condition = list(\"x2\", x1 = \"decile\", x0 = \"quartile\", \"threenum\") ) #> Warning: argument is not numeric or logical: returning NA # plot cv |> draw() # some model terms can be exclude from the conditional predictions using the # `exclude` mechanism of `predict.gam`. Here we exclude the effects of # `s(x0)` and `s(x3)` from the conditional predictions. This, in effect, # treats these smooths as having **0** effect on the conditional predictions # of the response, even though the two smooths conditioned on (`s(x2)` and # `s(x1)`) were estimated given the two excluded smooths were in the model cv <- conditional_values( m1, condition = list(\"x2\", x1 = \"minmax\"), exclude = c(\"s(x0)\", \"s(x3)\") ) # plot cv |> draw() # categorical conditions are also handled df <- data_sim(\"eg4\", seed = 2) m2 <- gam(y ~ fac + s(x2, by = fac) + s(x0), data = df, method = \"REML\") cv <- conditional_values( m2, condition = list(\"fac\", x2 = \"fivenum\") ) # plot - we see a discrete x axis cv |> draw() # in this example we condition on `x2` and `fac %in% c(2,3)` cv <- conditional_values( m2, condition = list(\"x2\", fac = 2:3) ) # plot - smooths of `x2` for `fac == 2` and `fac == 3` cv |> draw()"},{"path":"https://gavinsimpson.github.io/gratia/reference/confint.fderiv.html","id":null,"dir":"Reference","previous_headings":"","what":"Point-wise and simultaneous confidence intervals for derivatives of smooths — confint.fderiv","title":"Point-wise and simultaneous confidence intervals for derivatives of smooths — confint.fderiv","text":"Calculates point-wise confidence simultaneous intervals first derivatives smooth terms fitted GAM.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/confint.fderiv.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Point-wise and simultaneous confidence intervals for derivatives of smooths — confint.fderiv","text":"","code":"# S3 method for class 'fderiv' confint( object, parm, level = 0.95, type = c(\"confidence\", \"simultaneous\"), nsim = 10000, ncores = 1L, ... )"},{"path":"https://gavinsimpson.github.io/gratia/reference/confint.fderiv.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Point-wise and simultaneous confidence intervals for derivatives of smooths — confint.fderiv","text":"object object class \"fderiv\" containing estimated derivatives. parm parameters (smooth terms) given intervals vector terms. missing, parameters considered. level numeric, 0 < level < 1; confidence level point-wise simultaneous interval. default 0.95 95% interval. type character; type interval compute. One \"confidence\" point-wise intervals, \"simultaneous\" simultaneous intervals. nsim integer; number simulations used computing simultaneous intervals. ncores number cores generating random variables multivariate normal distribution. Passed mvnfast::rmvn(). Parallelization take place OpenMP supported (appears work Windows current R). ... additional arguments methods","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/confint.fderiv.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Point-wise and simultaneous confidence intervals for derivatives of smooths — confint.fderiv","text":"data frame components: term; factor indicating term row relates, lower; lower limit confidence simultaneous interval, est; estimated derivative upper; upper limit confidence simultaneous interval.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/confint.fderiv.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Point-wise and simultaneous confidence intervals for derivatives of smooths — confint.fderiv","text":"Gavin L. Simpson","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/confint.fderiv.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Point-wise and simultaneous confidence intervals for derivatives of smooths — confint.fderiv","text":"","code":"load_mgcv() dat <- data_sim(\"eg1\", n = 1000, dist = \"normal\", scale = 2, seed = 2) mod <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = dat, method = \"REML\") # new data to evaluate the derivatives at, say over the middle 50% of range # of each covariate middle <- function(x, n = 25, coverage = 0.5) { v <- (1 - coverage) / 2 q <- quantile(x, prob = c(0 + v, 1 - v), type = 8) seq(q[1], q[2], length = n) } new_data <- sapply(dat[c(\"x0\", \"x1\", \"x2\", \"x3\")], middle) new_data <- data.frame(new_data) ## first derivatives of all smooths... fd <- fderiv(mod, newdata = new_data) #> Warning: `fderiv()` was deprecated in gratia 0.7.0. #> i Please use `derivatives()` instead. ## point-wise interval ci <- confint(fd, type = \"confidence\") ci #> # A tibble: 100 x 4 #> term lower est upper #> #> 1 s(x0) 1.7 4.1 6.6 #> 2 s(x0) 1.3 3.8 6.3 #> 3 s(x0) 0.99 3.5 6.0 #> 4 s(x0) 0.68 3.1 5.6 #> 5 s(x0) 0.37 2.8 5.2 #> 6 s(x0) 0.0049 2.4 4.8 #> 7 s(x0) -0.40 2.0 4.5 #> 8 s(x0) -0.79 1.7 4.2 #> 9 s(x0) -1.1 1.3 3.8 #> 10 s(x0) -1.4 0.99 3.4 #> # i 90 more rows ## simultaneous interval for smooth term of x2 x2_sint <- confint(fd, parm = \"x2\", type = \"simultaneous\", nsim = 10000, ncores = 2 ) # \\donttest{ x2_sint #> # A tibble: 25 x 4 #> term lower est upper #> #> 1 s(x2) -24. -15. -5.6 #> 2 s(x2) -35. -26. -16. #> 3 s(x2) -41. -33. -24. #> 4 s(x2) -44. -36. -29. #> 5 s(x2) -44. -36. -28. #> 6 s(x2) -42. -34. -25. #> 7 s(x2) -38. -30. -21. #> 8 s(x2) -33. -24. -16. #> 9 s(x2) -27. -19. -11. #> 10 s(x2) -22. -14. -5.8 #> # i 15 more rows # }"},{"path":"https://gavinsimpson.github.io/gratia/reference/confint.gam.html","id":null,"dir":"Reference","previous_headings":"","what":"Point-wise and simultaneous confidence intervals for smooths — confint.gam","title":"Point-wise and simultaneous confidence intervals for smooths — confint.gam","text":"Calculates point-wise confidence simultaneous intervals smooth terms fitted GAM.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/confint.gam.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Point-wise and simultaneous confidence intervals for smooths — confint.gam","text":"","code":"# S3 method for class 'gam' confint( object, parm, level = 0.95, data = newdata, n = 100, type = c(\"confidence\", \"simultaneous\"), nsim = 10000, shift = FALSE, transform = FALSE, unconditional = FALSE, ncores = 1, partial_match = FALSE, ..., newdata = NULL ) # S3 method for class 'gamm' confint(object, ...) # S3 method for class 'list' confint(object, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/confint.gam.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Point-wise and simultaneous confidence intervals for smooths — confint.gam","text":"object object class \"gam\" \"gamm\". parm parameters (smooth terms) given intervals vector terms. missing, parameters considered, although currently implemented. level numeric, 0 < level < 1; confidence level point-wise simultaneous interval. default 0.95 95% interval. data data frame; new values covariates used model fit. selected smooth(s) wil evaluated supplied values. n numeric; number points evaluate smooths . type character; type interval compute. One \"confidence\" point-wise intervals, \"simultaneous\" simultaneous intervals. nsim integer; number simulations used computing simultaneous intervals. shift logical; constant term add smooth? transform logical; smooth evaluated transformed scale? generalised models, involves applying inverse link function used fit model. Alternatively, name , actual, function can supplied transform smooth confidence interval. unconditional logical; TRUE (freq == FALSE) Bayesian smoothing parameter uncertainty corrected covariance matrix returned, available. ncores number cores generating random variables multivariate normal distribution. Passed mvnfast::rmvn(). Parallelization take place OpenMP supported (appears work Windows current R). partial_match logical; matching parm use partial match exact match? Can used length(parm) 1. ... additional arguments methods newdata DEPRECATED! data frame; containing new values covariates used model fit. selected smooth(s) wil evaluated supplied values.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/confint.gam.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Point-wise and simultaneous confidence intervals for smooths — confint.gam","text":"tibble components: .smooth; character indicating term row relates, .type; type smooth, .name variable smooth, NA otherwise, one vectors values smooth evaluated, named per variables smooth, zero variables containing values variable, .estimate; estimated value smooth, .se; standard error estimated value smooth, .crit; critical value 100 * level% confidence interval. .lower_ci; lower limit confidence simultaneous interval, .upper_ci; upper limit confidence simultaneous interval,","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/confint.gam.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Point-wise and simultaneous confidence intervals for smooths — confint.gam","text":"Gavin L. Simpson","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/confint.gam.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Point-wise and simultaneous confidence intervals for smooths — confint.gam","text":"","code":"load_mgcv() dat <- data_sim(\"eg1\", n = 1000, dist = \"normal\", scale = 2, seed = 2) mod <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = dat, method = \"REML\") # new data to evaluate the smooths at, say over the middle 50% of range # of each covariate middle <- function(x, n = 50, coverage = 0.5) { v <- (1 - coverage) / 2 q <- quantile(x, prob = c(0 + v, 1 - v), type = 8) seq(q[1], q[2], length = n) } new_data <- sapply(dat[c(\"x0\", \"x1\", \"x2\", \"x3\")], middle) new_data <- data.frame(new_data) ## point-wise interval for smooth of x2 ci <- confint(mod, parm = \"s(x2)\", type = \"confidence\", data = new_data) ci #> # A tibble: 50 x 9 #> .smooth .type .by x2 .estimate .se .crit .lower_ci .upper_ci #> #> 1 s(x2) TPRS NA 0.26 5.3 0.18 2.0 5.0 5.7 #> 2 s(x2) TPRS NA 0.27 5.1 0.18 2.0 4.8 5.5 #> 3 s(x2) TPRS NA 0.28 4.9 0.18 2.0 4.6 5.3 #> 4 s(x2) TPRS NA 0.29 4.6 0.18 2.0 4.3 5.0 #> 5 s(x2) TPRS NA 0.30 4.3 0.19 2.0 3.9 4.7 #> 6 s(x2) TPRS NA 0.32 4.0 0.19 2.0 3.6 4.3 #> 7 s(x2) TPRS NA 0.33 3.6 0.20 2.0 3.2 4.0 #> 8 s(x2) TPRS NA 0.34 3.2 0.20 2.0 2.9 3.6 #> 9 s(x2) TPRS NA 0.35 2.9 0.20 2.0 2.5 3.3 #> 10 s(x2) TPRS NA 0.36 2.5 0.19 2.0 2.1 2.9 #> # i 40 more rows"},{"path":"https://gavinsimpson.github.io/gratia/reference/data_combos.html","id":null,"dir":"Reference","previous_headings":"","what":"All combinations of factor levels plus typical values of continuous variables — data_combos","title":"All combinations of factor levels plus typical values of continuous variables — data_combos","text":"combinations factor levels plus typical values continuous variables","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/data_combos.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"All combinations of factor levels plus typical values of continuous variables — data_combos","text":"","code":"data_combos(object, ...) # S3 method for class 'gam' data_combos( object, vars = everything(), complete = TRUE, envir = environment(formula(object)), data = NULL, ... )"},{"path":"https://gavinsimpson.github.io/gratia/reference/data_combos.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"All combinations of factor levels plus typical values of continuous variables — data_combos","text":"object fitted model object. ... arguments passed methods. vars terms include exclude returned object. Uses tidyselect principles. complete logical; combinations factor levels returned? FALSE, combinations levels observed model retained. envir environment within recreate data used fit object. data optional data frame data used fit mdoel reconstruction data model work.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/data_sim.html","id":null,"dir":"Reference","previous_headings":"","what":"Simulate example data for fitting GAMs — data_sim","title":"Simulate example data for fitting GAMs — data_sim","text":"tidy reimplementation functions implemented mgcv::gamSim() can used fit GAMs. new feature sampling distribution can applied example types.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/data_sim.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Simulate example data for fitting GAMs — data_sim","text":"","code":"data_sim( model = \"eg1\", n = 400, scale = NULL, theta = 3, power = 1.5, dist = c(\"normal\", \"poisson\", \"binary\", \"negbin\", \"tweedie\", \"gamma\", \"ocat\", \"ordered categorical\"), n_cat = 4, cuts = c(-1, 0, 5), seed = NULL, gfam_families = c(\"binary\", \"tweedie\", \"normal\") )"},{"path":"https://gavinsimpson.github.io/gratia/reference/data_sim.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Simulate example data for fitting GAMs — data_sim","text":"model character; either \"egX\" X integer 1:7, name model. See Details possible options. n numeric; number observations simulate. scale numeric; level noise use. theta numeric; dispersion parameter \\(\\theta\\) use. default entirely arbitrary, chosen provide simulated data exhibits extra dispersion beyond assumed Poisson. power numeric; Tweedie power parameter. dist character; sampling distribution response variable. \"ordered categorical\" synonym \"ocat\". n_cat integer; number categories categorical response. Currently used distr %% c(\"ocat\", \"ordered categorical\"). cuts numeric; vector cut points latent variable, excluding end points -Inf Inf. Must one fewer number categories: length(cuts) == n_cat - 1. seed numeric; seed random number generator. Passed base::set.seed(). gfam_families character; vector distributions use generating data grouped families use family = gfam(). allowed distributions per dist.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/data_sim.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Simulate example data for fitting GAMs — data_sim","text":"data_sim() can simulate data several underlying models known true functions. available options currently : \"eg1\": four term additive true model. classic Gu & Wahba four univariate term test model. See gw_functions details underlying four functions. \"eg2\": bivariate smooth true model. \"eg3\": example containing continuous smooth (varying coefficient) true model. model \\(\\hat{y}_i = f_2(x_{1i})x_{2i}\\) function \\(f_2()\\) \\(f_2(x) = 0.2 * x^{11} * (10 * (1 - x))^6 + 10 * (10 * x)^3 * (1 - x)^{10}\\). \"eg4\": factor smooth true model. true model contains factor 3 levels, response nth level follows nth Gu & Wabha function (\\(n \\{1, 2, 3}\\)). \"eg5\": additive plus factor true model. response linear combination Gu & Wabha functions 2, 3, 4 (latter null function) plus factor term four levels. \"eg6\": additive plus random effect term true model. ´\"eg7\": version model \"eg1\"`, covariates correlated. \"gwf2\": model response Gu & Wabha's \\(f_2(x_i)\\) plus noise. \"lwf6\": model response Luo & Wabha's \"example 6\" function \\(sin(2(4x-2)) + 2 exp(-256(x-0.5)^2)\\) plus noise. \"gfam\": simulates data use GAMs family = gfam(families). See example mgcv::gfam(). model specified dist ignored gfam_families used specify distributions included simulated data. Can vector families allowed dist. \"ocat\" %% gfam_families (\"ordered categorical\"), 4 classes assumed, changed. Link functions used \"identity\" \"normal\", \"logit\" \"binary\", \"ocat\", \"ordered categorical\", \"exp\" elsewhere. random component providing noise sampling variation can follow one distributions, specified via argument dist \"normal\": Gaussian, \"poisson\": Poisson, \"binary\": Bernoulli, \"negbin\": Negative binomial, \"tweedie\": Tweedie, \"gamma\": gamma , \"ordered categorical\": ordered categorical arguments provide parameters distribution.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/data_sim.html","id":"references","dir":"Reference","previous_headings":"","what":"References","title":"Simulate example data for fitting GAMs — data_sim","text":"Gu, C., Wahba, G., (1993). Smoothing Spline ANOVA Component-Wise Bayesian \"Confidence Intervals.\" J. Comput. Graph. Stat. 2, 97–117. Luo, Z., Wahba, G., (1997). Hybrid adaptive splines. J. . Stat. Assoc. 92, 107–116.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/data_sim.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Simulate example data for fitting GAMs — data_sim","text":"","code":"data_sim(\"eg1\", n = 100, seed = 1) #> # A tibble: 100 x 10 #> y x0 x1 x2 x3 f f0 f1 f2 f3 #> #> 1 14.532 0.26551 0.65472 0.26751 0.67371 13.713 1.4814 3.7041 8.5277 0 #> 2 16.113 0.37212 0.35320 0.21865 0.094858 12.735 1.8408 2.0267 8.8680 0 #> 3 9.5835 0.57285 0.27026 0.51680 0.49260 6.4103 1.9478 1.7169 2.7456 0 #> 4 15.687 0.90821 0.99268 0.26895 0.46155 16.349 0.56879 7.2817 8.4980 0 #> 5 8.2216 0.20168 0.63349 0.18117 0.37522 12.792 1.1841 3.5501 8.0578 0 #> 6 9.9034 0.89839 0.21321 0.51858 0.99110 4.9081 0.62765 1.5318 2.7487 0 #> 7 5.9362 0.94468 0.12937 0.56278 0.17635 4.6020 0.34587 1.2953 2.9609 0 #> 8 10.839 0.66080 0.47812 0.12916 0.81344 9.7565 1.7502 2.6019 5.4045 0 #> 9 16.883 0.62911 0.92407 0.25637 0.068447 16.909 1.8377 6.3481 8.7237 0 #> 10 7.3603 0.061786 0.59876 0.71794 0.40045 6.3401 0.38578 3.3119 2.6424 0 #> # i 90 more rows # an ordered categorical response data_sim(\"eg1\", n = 100, dist = \"ocat\", n_cat = 4, cuts = c(-1, 0, 5)) #> # A tibble: 100 x 11 #> y x0 x1 x2 x3 f f0 f1 f2 #> #> 1 1 0.93708 0.21716 0.51711 0.44457 -3.5517 0.39280 1.5439 2.7461 #> 2 1 0.28614 0.21657 0.85193 0.060386 -4.7654 1.5653 1.5421 0.36166 #> 3 1 0.83045 0.38895 0.44280 0.32751 -1.7693 1.0157 2.1769 3.2727 #> 4 4 0.64175 0.94246 0.15788 0.87843 7.2150 1.8050 6.5858 7.0588 #> 5 3 0.51910 0.96261 0.44232 0.93060 3.8994 1.9964 6.8566 3.2808 #> 6 1 0.73659 0.73986 0.96773 0.39218 -2.3701 1.4725 4.3917 0.00015734 #> 7 1 0.13467 0.73325 0.48459 0.15885 -0.27657 0.82112 4.3340 2.8028 #> 8 3 0.65699 0.53576 0.25246 0.31995 5.2247 1.7616 2.9198 8.7777 #> 9 3 0.70506 0.0022730 0.25969 0.30697 3.0408 1.5991 1.0046 8.6716 #> 10 2 0.45774 0.60894 0.54202 0.10781 -0.036524 1.9824 3.3800 2.8356 #> # i 90 more rows #> # i 2 more variables: f3 , latent "},{"path":"https://gavinsimpson.github.io/gratia/reference/data_slice.html","id":null,"dir":"Reference","previous_headings":"","what":"Prepare a data slice through model covariates — data_slice","title":"Prepare a data slice through model covariates — data_slice","text":"Prepare data slice model covariates","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/data_slice.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Prepare a data slice through model covariates — data_slice","text":"","code":"data_slice(object, ...) # Default S3 method data_slice(object, ...) # S3 method for class 'data.frame' data_slice(object, ...) # S3 method for class 'gam' data_slice(object, ..., data = NULL, envir = NULL) # S3 method for class 'gamm' data_slice(object, ...) # S3 method for class 'list' data_slice(object, ...) # S3 method for class 'scam' data_slice(object, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/data_slice.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Prepare a data slice through model covariates — data_slice","text":"object R model object. ... User supplied variables defining data slice. Arguments passed via ... need named. data alternative data frame values containing variables needed fit model. NULL, default, data used fit model recovered using model.frame. User-supplied expressions passed ... evaluated data. envir environment within recreate data used fit object.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/data_slice.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Prepare a data slice through model covariates — data_slice","text":"data slice data set results one (covariates) varied systematically () range specified subset values interest, remaining covariates model held fixed, representative values. known reference grid package emmeans data grid marginaleffects package. GAMs, covariates specified via ... take representative values determined data used fit model follows: numeric covariates, value fitting data closest median value used, factor covariates, modal (frequently observed) level used, first level (sorted per vector returned base::levels() several levels observed number times. values already computed calling gam() bam() example can found var.summary component fitted model. Function typical_values() extract values interested. Convenience functions evenly(), ref_level(), level() provided help users specify data slices. ref_level(), level() also ensure factor covariates correct levels, needed mgcv::predict.gam() example. extended discussion data_slice() examples, see vignette(\"data-slices\", package = \"gratia\").","code":""},{"path":[]},{"path":"https://gavinsimpson.github.io/gratia/reference/data_slice.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Prepare a data slice through model covariates — data_slice","text":"","code":"load_mgcv() # simulate some Gaussian data df <- data_sim(\"eg1\", n = 50, seed = 2) # fit a GAM with 1 smooth and 1 linear term m <- gam(y ~ s(x2, k = 7) + x1, data = df, method = \"REML\") # Want to predict over f(x2) while holding `x1` at some value. # Default will use the observation closest to the median for unspecified # variables. ds <- data_slice(m, x2 = evenly(x2, n = 50)) ds #> # A tibble: 50 x 2 #> x2 x1 #> #> 1 0.0228 0.403 #> 2 0.0424 0.403 #> 3 0.0619 0.403 #> 4 0.0815 0.403 #> 5 0.101 0.403 #> 6 0.121 0.403 #> 7 0.140 0.403 #> 8 0.160 0.403 #> 9 0.179 0.403 #> 10 0.199 0.403 #> # i 40 more rows # for full control, specify the values you want ds <- data_slice(m, x2 = evenly(x2, n = 50), x1 = 0.3) # or provide an expression (function call) which will be evaluated in the # data frame passed to `data` or `model.frame(object)` ds <- data_slice(m, x2 = evenly(x2, n = 50), x1 = mean(x1))"},{"path":"https://gavinsimpson.github.io/gratia/reference/datagen.html","id":null,"dir":"Reference","previous_headings":"","what":"Generate data over the range of variables used in smooths — datagen","title":"Generate data over the range of variables used in smooths — datagen","text":"smooth GAM, generate new data range variables involved smooth. function deprecated useful narrow use-case. Use data_slice() instead.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/datagen.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Generate data over the range of variables used in smooths — datagen","text":"","code":"datagen(x, ...) # S3 method for class 'mgcv.smooth' datagen(x, n = 100, data, ...) # S3 method for class 'fs.interaction' datagen(x, n = 100, data, ...) # S3 method for class 'gam' datagen(x, smooth = NULL, n = 200, ...) # S3 method for class 'gamm' datagen(x, ...) # S3 method for class 'list' datagen(x, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/datagen.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Generate data over the range of variables used in smooths — datagen","text":"x object new data required. Currently objects classes \"gam\", \"gamm\" supported, smooths mgcv inheriting class \"mgcv.smooth\". ... arguments passed methods n numeric; number data values generate per term smooth. data data frame; \"mgcv.smooth\" objects, data used fit GAM need supplied.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/datagen.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Generate data over the range of variables used in smooths — datagen","text":"data frame new values spread range observed values.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/datagen.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Generate data over the range of variables used in smooths — datagen","text":"Gavin L. Simpson","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/derivative_samples.html","id":null,"dir":"Reference","previous_headings":"","what":"Posterior expectations of derivatives from an estimated model — derivative_samples","title":"Posterior expectations of derivatives from an estimated model — derivative_samples","text":"Posterior expectations derivatives estimated model","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/derivative_samples.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Posterior expectations of derivatives from an estimated model — derivative_samples","text":"","code":"derivative_samples(object, ...) # Default S3 method derivative_samples(object, ...) # S3 method for class 'gamm' derivative_samples(object, ...) # S3 method for class 'gam' derivative_samples( object, focal = NULL, data = NULL, order = 1L, type = c(\"forward\", \"backward\", \"central\"), scale = c(\"response\", \"linear_predictor\"), method = c(\"gaussian\", \"mh\", \"inla\", \"user\"), n = 100, eps = 1e-07, n_sim = 10000, level = lifecycle::deprecated(), seed = NULL, envir = environment(formula(object)), draws = NULL, mvn_method = c(\"mvnfast\", \"mgcv\"), ... )"},{"path":"https://gavinsimpson.github.io/gratia/reference/derivative_samples.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Posterior expectations of derivatives from an estimated model — derivative_samples","text":"object R object compute derivatives ... arguments passed methods fitted_samples() focal character; name focal variable. response derivative response respect variable returned. variables involved model held constant values. can missing supplying data, case, focal variable identified one variable constant. data data frame containing values model covariates evaluate first derivatives smooths. supplied, one variable must held constant value. order numeric; order derivative. type character; type finite difference used. One \"forward\", \"backward\", \"central\". scale character; derivative estimated response linear predictor (link) scale? One \"response\" (default), \"linear predictor\". method character; method used draw samples posterior distribution. \"gaussian\" uses Gaussian (Laplace) approximation posterior. \"mh\" uses Metropolis Hastings sample alternates t proposals proposals based shrunken version posterior covariance matrix. \"inla\" uses variant Integrated Nested Laplace Approximation due Wood (2019), (currently implemented). \"user\" allows user-supplied posterior draws (currently implemented). n numeric; number points evaluate derivative (data supplied). eps numeric; finite difference. n_sim integer; number simulations used computing simultaneous intervals. level seed numeric; random seed simulations. envir environment within recreate data used fit object. draws matrix; user supplied posterior draws used method = \"user\". mvn_method character; one \"mvnfast\" \"mgcv\". default uses mvnfast::rmvn(), can considerably faster generate large numbers MVN random values mgcv::rmvn(), might work marginal fits, covariance matrix close singular.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/derivative_samples.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Posterior expectations of derivatives from an estimated model — derivative_samples","text":"tibble, currently following variables: .derivative: estimated partial derivative, additional columns containing covariate values derivative evaluated.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/derivative_samples.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Posterior expectations of derivatives from an estimated model — derivative_samples","text":"Gavin L. Simpson","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/derivative_samples.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Posterior expectations of derivatives from an estimated model — derivative_samples","text":"","code":"load_mgcv() df <- data_sim(\"eg1\", dist = \"negbin\", scale = 0.25, seed = 42) # fit the GAM (note: for execution time reasons using bam()) m <- bam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = df, family = nb(), method = \"fREML\") # data slice through data along x2 - all other covariates will be set to # typical values (value closest to median) ds <- data_slice(m, x2 = evenly(x2, n = 200)) # samples from posterior of derivatives fd_samp <- derivative_samples(m, data = ds, type = \"central\", focal = \"x2\", eps = 0.01, seed = 21, n_sim = 100 ) # plot the first 20 posterior draws if (requireNamespace(\"ggplot2\") && requireNamespace(\"dplyr\")) { library(\"ggplot2\") fd_samp |> dplyr::filter(.draw <= 20) |> ggplot(aes(x = x2, y = .derivative, group = .draw)) + geom_line(alpha = 0.5) }"},{"path":"https://gavinsimpson.github.io/gratia/reference/derivatives.html","id":null,"dir":"Reference","previous_headings":"","what":"Derivatives of estimated smooths via finite differences — derivatives","title":"Derivatives of estimated smooths via finite differences — derivatives","text":"Derivatives estimated smooths via finite differences","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/derivatives.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Derivatives of estimated smooths via finite differences — derivatives","text":"","code":"derivatives(object, ...) # Default S3 method derivatives(object, ...) # S3 method for class 'gamm' derivatives(object, ...) # S3 method for class 'gam' derivatives( object, select = NULL, term = deprecated(), data = newdata, order = 1L, type = c(\"forward\", \"backward\", \"central\"), n = 100, eps = 1e-07, interval = c(\"confidence\", \"simultaneous\"), n_sim = 10000, level = 0.95, unconditional = FALSE, frequentist = FALSE, offset = NULL, ncores = 1, partial_match = FALSE, ..., newdata = NULL )"},{"path":"https://gavinsimpson.github.io/gratia/reference/derivatives.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Derivatives of estimated smooths via finite differences — derivatives","text":"object R object compute derivatives . ... arguments passed methods. select character; select smooth's posterior draw . default (NULL) means posteriors smooths model wil sampled . supplied, character vector requested terms. Can partial match smooth term; see argument partial_match . term Use select instead. data data frame containing values model covariates evaluate first derivatives smooths. order numeric; order derivative. type character; type finite difference used. One \"forward\", \"backward\", \"central\". n numeric; number points evaluate derivative . eps numeric; finite difference. interval character; type interval compute. One \"confidence\" point-wise intervals, \"simultaneous\" simultaneous intervals. n_sim integer; number simulations used computing simultaneous intervals. level numeric; 0 < level < 1; confidence level point-wise simultaneous interval. default 0.95 95% interval. unconditional logical; use smoothness selection-corrected Bayesian covariance matrix? frequentist logical; use frequentist covariance matrix? offset numeric; value use offset term ncores number cores generating random variables multivariate normal distribution. Passed mvnfast::rmvn(). Parallelization take place OpenMP supported (appears work Windows current R). partial_match logical; smooths selected partial matches term? TRUE, term can single string match . newdata Deprecated: use data instead.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/derivatives.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Derivatives of estimated smooths via finite differences — derivatives","text":"tibble, currently following variables: smooth: smooth row refers , var: name variable involved smooth, data: values var derivative evaluated, derivative: estimated derivative, se: standard error estimated derivative, crit: critical value derivative ± (crit * se) gives upper lower bounds requested confidence simultaneous interval (given level), lower: lower bound confidence simultaneous interval, upper: upper bound confidence simultaneous interval.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/derivatives.html","id":"note","dir":"Reference","previous_headings":"","what":"Note","title":"Derivatives of estimated smooths via finite differences — derivatives","text":"derivatives() ignore random effect smooths encounters object.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/derivatives.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Derivatives of estimated smooths via finite differences — derivatives","text":"Gavin L. Simpson","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/derivatives.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Derivatives of estimated smooths via finite differences — derivatives","text":"","code":"load_mgcv() dat <- data_sim(\"eg1\", n = 400, dist = \"normal\", scale = 2, seed = 42) mod <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = dat, method = \"REML\") ## first derivatives of all smooths using central finite differences derivatives(mod, type = \"central\") #> # A tibble: 400 x 12 #> .smooth .by .fs .derivative .se .crit .lower_ci .upper_ci x0 x1 #> #> 1 s(x0) NA NA 7.41 3.33 1.96 0.874 13.9 2.39e-4 NA #> 2 s(x0) NA NA 7.40 3.33 1.96 0.884 13.9 1.03e-2 NA #> 3 s(x0) NA NA 7.39 3.30 1.96 0.929 13.8 2.04e-2 NA #> 4 s(x0) NA NA 7.36 3.24 1.96 1.01 13.7 3.04e-2 NA #> 5 s(x0) NA NA 7.32 3.15 1.96 1.14 13.5 4.05e-2 NA #> 6 s(x0) NA NA 7.26 3.04 1.96 1.30 13.2 5.06e-2 NA #> 7 s(x0) NA NA 7.18 2.90 1.96 1.49 12.9 6.06e-2 NA #> 8 s(x0) NA NA 7.09 2.76 1.96 1.69 12.5 7.07e-2 NA #> 9 s(x0) NA NA 6.99 2.61 1.96 1.87 12.1 8.07e-2 NA #> 10 s(x0) NA NA 6.87 2.47 1.96 2.03 11.7 9.08e-2 NA #> # i 390 more rows #> # i 2 more variables: x2 , x3 ## derivatives for a selected smooth derivatives(mod, type = \"central\", select = \"s(x1)\") #> # A tibble: 100 x 9 #> .smooth .by .fs .derivative .se .crit .lower_ci .upper_ci x1 #> #> 1 s(x1) NA NA -0.907 3.12 1.96 -7.02 5.20 0.000405 #> 2 s(x1) NA NA -0.906 3.11 1.96 -7.01 5.20 0.0105 #> 3 s(x1) NA NA -0.898 3.10 1.96 -6.97 5.17 0.0205 #> 4 s(x1) NA NA -0.880 3.06 1.96 -6.88 5.12 0.0306 #> 5 s(x1) NA NA -0.849 3.00 1.96 -6.73 5.03 0.0406 #> 6 s(x1) NA NA -0.803 2.92 1.96 -6.52 4.92 0.0507 #> 7 s(x1) NA NA -0.740 2.81 1.96 -6.25 4.77 0.0607 #> 8 s(x1) NA NA -0.659 2.69 1.96 -5.93 4.61 0.0708 #> 9 s(x1) NA NA -0.557 2.56 1.96 -5.57 4.46 0.0809 #> 10 s(x1) NA NA -0.436 2.42 1.96 -5.19 4.32 0.0909 #> # i 90 more rows ## or via a partial match derivatives(mod, type = \"central\", select = \"x1\", partial_match = TRUE) #> # A tibble: 100 x 9 #> .smooth .by .fs .derivative .se .crit .lower_ci .upper_ci x1 #> #> 1 s(x1) NA NA -0.907 3.12 1.96 -7.02 5.20 0.000405 #> 2 s(x1) NA NA -0.906 3.11 1.96 -7.01 5.20 0.0105 #> 3 s(x1) NA NA -0.898 3.10 1.96 -6.97 5.17 0.0205 #> 4 s(x1) NA NA -0.880 3.06 1.96 -6.88 5.12 0.0306 #> 5 s(x1) NA NA -0.849 3.00 1.96 -6.73 5.03 0.0406 #> 6 s(x1) NA NA -0.803 2.92 1.96 -6.52 4.92 0.0507 #> 7 s(x1) NA NA -0.740 2.81 1.96 -6.25 4.77 0.0607 #> 8 s(x1) NA NA -0.659 2.69 1.96 -5.93 4.61 0.0708 #> 9 s(x1) NA NA -0.557 2.56 1.96 -5.57 4.46 0.0809 #> 10 s(x1) NA NA -0.436 2.42 1.96 -5.19 4.32 0.0909 #> # i 90 more rows"},{"path":"https://gavinsimpson.github.io/gratia/reference/difference_smooths.html","id":null,"dir":"Reference","previous_headings":"","what":"Differences of factor smooth interactions — difference_smooths","title":"Differences of factor smooth interactions — difference_smooths","text":"Estimates pairwise differences (comparisons) factor smooth interactions (smooths factor argument) pairs groups defined factor. group means can optionally included difference.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/difference_smooths.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Differences of factor smooth interactions — difference_smooths","text":"","code":"difference_smooths(model, ...) # S3 method for class 'gam' difference_smooths( model, select = NULL, smooth = deprecated(), n = 100, ci_level = 0.95, data = NULL, group_means = FALSE, partial_match = TRUE, unconditional = FALSE, frequentist = FALSE, ... )"},{"path":"https://gavinsimpson.github.io/gratia/reference/difference_smooths.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Differences of factor smooth interactions — difference_smooths","text":"model fitted model. ... arguments passed methods. currently used. select character, logical, numeric; smooths plot. NULL, default, model smooths drawn. Numeric select indexes smooths order specified formula stored object. Character select matches labels smooths shown example output summary(object). Logical select operates per numeric select order smooths stored. smooth Use select instead. n numeric; number points evaluate difference pairs smooths. ci_level numeric 0 1; coverage credible interval. data data frame locations evaluate difference smooths. group_means logical; group means included difference? partial_match logical; smooth match partially smooths? partial_match = TRUE, smooth must single string, character vector length 1. Unlike similar functions, default TRUE intention users matching factor-smooth labels. unconditional logical; account smoothness selection model? frequentist logical; use frequentist covariance matrix?","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/difference_smooths.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Differences of factor smooth interactions — difference_smooths","text":"","code":"load_mgcv() df <- data_sim(\"eg4\", seed = 42) m <- gam(y ~ fac + s(x2, by = fac) + s(x0), data = df, method = \"REML\") sm_dif <- difference_smooths(m, select = \"s(x2)\") sm_dif #> # A tibble: 300 x 9 #> .smooth .by .level_1 .level_2 .diff .se .lower_ci .upper_ci x2 #> #> 1 s(x2) fac 1 2 0.386 0.618 -0.824 1.60 0.00359 #> 2 s(x2) fac 1 2 0.479 0.574 -0.646 1.60 0.0136 #> 3 s(x2) fac 1 2 0.572 0.534 -0.474 1.62 0.0237 #> 4 s(x2) fac 1 2 0.665 0.497 -0.308 1.64 0.0338 #> 5 s(x2) fac 1 2 0.758 0.464 -0.151 1.67 0.0438 #> 6 s(x2) fac 1 2 0.850 0.435 -0.00342 1.70 0.0539 #> 7 s(x2) fac 1 2 0.941 0.412 0.134 1.75 0.0639 #> 8 s(x2) fac 1 2 1.03 0.393 0.262 1.80 0.0740 #> 9 s(x2) fac 1 2 1.12 0.378 0.380 1.86 0.0841 #> 10 s(x2) fac 1 2 1.21 0.367 0.489 1.93 0.0941 #> # i 290 more rows draw(sm_dif) # include the groups means for `fac` in the difference sm_dif2 <- difference_smooths(m, select = \"s(x2)\", group_means = TRUE) draw(sm_dif2)"},{"path":[]},{"path":"https://gavinsimpson.github.io/gratia/reference/dispersion.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Dispersion parameter for fitted model — dispersion","text":"","code":"dispersion(model, ...) # S3 method for class 'gam' dispersion(model, ...) # S3 method for class 'glm' dispersion(model, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/dispersion.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Dispersion parameter for fitted model — dispersion","text":"model fitted model. ... arguments passed methods.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.basis.html","id":null,"dir":"Reference","previous_headings":"","what":"Plot basis functions — draw.basis","title":"Plot basis functions — draw.basis","text":"Plots basis functions using ggplot2","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.basis.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Plot basis functions — draw.basis","text":"","code":"# S3 method for class 'basis' draw( object, legend = FALSE, labeller = NULL, ylab = NULL, title = NULL, subtitle = NULL, caption = NULL, ncol = NULL, nrow = NULL, angle = NULL, guides = \"keep\", contour = FALSE, n_contour = 10, contour_col = \"black\", ... )"},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.basis.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Plot basis functions — draw.basis","text":"object object, result call basis(). legend logical; legend drawn indicate basis functions? labeller labeller function label facets. default use ggplot2::label_both(). ylab character expression; label y axis. supplied, suitable label generated object. title character expression; title plot. See ggplot2::labs(). subtitle character expression; subtitle plot. See ggplot2::labs(). caption character expression; plot caption. See ggplot2::labs(). ncol, nrow numeric; numbers rows columns spread plots angle numeric; angle x axis tick labels drawn passed angle argument ggplot2::guide_axis(). guides character; one \"keep\" (default), \"collect\", \"auto\". Passed patchwork::plot_layout() contour logical; contours draw plot using ggplot2::geom_contour(). n_contour numeric; number contour bins. result n_contour - 1 contour lines drawn. See ggplot2::geom_contour(). contour_col colour specification contour lines. ... arguments passed methods. used method.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.basis.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Plot basis functions — draw.basis","text":"patchwork object.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.basis.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Plot basis functions — draw.basis","text":"Gavin L. Simpson","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.basis.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Plot basis functions — draw.basis","text":"","code":"load_mgcv() df <- data_sim(\"eg1\", n = 400, seed = 42) m <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = df, method = \"REML\") bf <- basis(m) draw(bf) bf <- basis(m, \"s(x2)\") draw(bf)"},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.compare_smooths.html","id":null,"dir":"Reference","previous_headings":"","what":"Plot comparisons of smooths — draw.compare_smooths","title":"Plot comparisons of smooths — draw.compare_smooths","text":"Plot comparisons smooths","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.compare_smooths.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Plot comparisons of smooths — draw.compare_smooths","text":"","code":"# S3 method for class 'compare_smooths' draw(object, ncol = NULL, nrow = NULL, guides = \"collect\", ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.compare_smooths.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Plot comparisons of smooths — draw.compare_smooths","text":"object class \"compare_smooths\", result call compare_smooths(). ncol, nrow numeric; numbers rows columns spread plots guides character; one \"keep\" (default), \"collect\", \"auto\". Passed patchwork::plot_layout() ... additional arguments passed patchwork::wrap_plots().","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.conditional_values.html","id":null,"dir":"Reference","previous_headings":"","what":"Plot conditional predictions — draw.conditional_values","title":"Plot conditional predictions — draw.conditional_values","text":"Plot conditional predictions","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.conditional_values.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Plot conditional predictions — draw.conditional_values","text":"","code":"# S3 method for class 'conditional_values' draw( object, facet_scales = \"fixed\", discrete_colour = NULL, discrete_fill = NULL, ... )"},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.conditional_values.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Plot conditional predictions — draw.conditional_values","text":"object object class \"conditional_values\", result call conditional_values(). facet_scales character; facets axis scales across facets? See ggplot2::facet_wrap() details. Options : \"fixed\" (default), \"free_x\", \"free_y\", \"free\". discrete_colour suitable colour scale used plotting discrete variables. discrete_fill suitable fill scale used plotting discrete variables. ... additional arguments passed patchwork::wrap_plots().","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.derivatives.html","id":null,"dir":"Reference","previous_headings":"","what":"Plot derivatives of smooths — draw.derivatives","title":"Plot derivatives of smooths — draw.derivatives","text":"Plot derivatives smooths","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.derivatives.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Plot derivatives of smooths — draw.derivatives","text":"","code":"# S3 method for class 'derivatives' draw( object, select = NULL, scales = c(\"free\", \"fixed\"), add_change = FALSE, change_type = c(\"change\", \"sizer\"), alpha = 0.2, change_col = \"black\", decrease_col = \"#56B4E9\", increase_col = \"#E69F00\", lwd_change = 1.5, ncol = NULL, nrow = NULL, guides = \"keep\", angle = NULL, ... ) # S3 method for class 'partial_derivatives' draw( object, select = NULL, scales = c(\"free\", \"fixed\"), alpha = 0.2, ncol = NULL, nrow = NULL, guides = \"keep\", angle = NULL, ... )"},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.derivatives.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Plot derivatives of smooths — draw.derivatives","text":"object fitted GAM, result call mgcv::gam(). select character, logical, numeric; smooths plot. NULL, default, model smooths drawn. Numeric select indexes smooths order specified formula stored object. Character select matches labels smooths shown example output summary(object). Logical select operates per numeric select order smooths stored. scales character; univariate smooths plotted y-axis scale? scales = \"free\", default, univariate smooth y-axis scale. scales = \"fixed\", common y axis scale used univariate smooths. Currently affect y-axis scale plots parametric terms. add_change logical; periods significant change highlighted plot? change_type character; type change indicate. \"change\", differentiation made periods significant increase decrease. \"sizer\", periods increase decrease differentiated resulting plot. alpha numeric; alpha transparency confidence simultaneous interval. change_col, decrease_col, increase_col colour specifications use indicating periods change. col_change used change_type = \"change\", col_decrease col_increase used `change_type = \"sizer\"“. lwd_change numeric; linewidth use change indicators. ncol, nrow numeric; numbers rows columns spread plots guides character; one \"keep\" (default), \"collect\", \"auto\". Passed patchwork::plot_layout() angle numeric; angle x axis tick labels drawn passed angle argument ggplot2::guide_axis(). ... additional arguments passed patchwork::wrap_plots().","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.derivatives.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Plot derivatives of smooths — draw.derivatives","text":"","code":"load_mgcv() dat <- data_sim(\"eg1\", n = 800, dist = \"normal\", scale = 2, seed = 42) mod <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = dat, method = \"REML\") ## first derivative of all smooths df <- derivatives(mod, type = \"central\") draw(df) ## fixed axis scales draw(df, scales = \"fixed\")"},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.difference_smooth.html","id":null,"dir":"Reference","previous_headings":"","what":"Plot differences of smooths — draw.difference_smooth","title":"Plot differences of smooths — draw.difference_smooth","text":"Plot differences smooths","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.difference_smooth.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Plot differences of smooths — draw.difference_smooth","text":"","code":"# S3 method for class 'difference_smooth' draw( object, select = NULL, rug = FALSE, ref_line = FALSE, contour = FALSE, contour_col = \"black\", n_contour = NULL, ci_alpha = 0.2, ci_col = \"black\", smooth_col = \"black\", line_col = \"red\", scales = c(\"free\", \"fixed\"), ncol = NULL, nrow = NULL, guides = \"keep\", xlab = NULL, ylab = NULL, title = NULL, subtitle = NULL, caption = NULL, angle = NULL, ... )"},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.difference_smooth.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Plot differences of smooths — draw.difference_smooth","text":"object fitted GAM, result call mgcv::gam(). select character, logical, numeric; smooths plot. NULL, default, model smooths drawn. Numeric select indexes smooths order specified formula stored object. Character select matches labels smooths shown example output summary(object). Logical select operates per numeric select order smooths stored. rug logical; ref_line logical; contour logical; contour lines added smooth surfaces? contour_col colour specification contour lines. n_contour numeric; number contour bins. result n_contour - 1 contour lines drawn. See ggplot2::geom_contour(). ci_alpha numeric; alpha transparency confidence simultaneous interval. ci_col colour specification confidence/credible intervals band. Affects fill interval. smooth_col colour specification smooth difference line. line_col colour specification drawing reference lines scales character; univariate smooths plotted y-axis scale? scales = \"free\", default, univariate smooth y-axis scale. scales = \"fixed\", common y axis scale used univariate smooths. Currently affect y-axis scale plots parametric terms. ncol, nrow numeric; numbers rows columns spread plots guides character; one \"keep\" (default), \"collect\", \"auto\". Passed patchwork::plot_layout() xlab, ylab, title, subtitle, caption character; labels annotate plots angle numeric; angle x axis tick labels drawn passed angle argument ggplot2::guide_axis(). ... additional arguments passed patchwork::wrap_plots().","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.difference_smooth.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Plot differences of smooths — draw.difference_smooth","text":"","code":"load_mgcv() # simulate some data; a factor smooth example df <- data_sim(\"eg4\", seed = 42) # fit GAM m <- gam(y ~ fac + s(x2, by = fac) + s(x0), data = df, method = \"REML\") # calculate the differences between pairs of smooths the f_j(x2) term diffs <- difference_smooths(m, select = \"s(x2)\") draw(diffs)"},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.evaluated_parametric_term.html","id":null,"dir":"Reference","previous_headings":"","what":"Plot estimated parametric effects — draw.evaluated_parametric_term","title":"Plot estimated parametric effects — draw.evaluated_parametric_term","text":"Plots estimated univariate bivariate smooths using ggplot2.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.evaluated_parametric_term.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Plot estimated parametric effects — draw.evaluated_parametric_term","text":"","code":"# S3 method for class 'evaluated_parametric_term' draw( object, ci_level = 0.95, constant = NULL, fun = NULL, xlab, ylab, title = NULL, subtitle = NULL, caption = NULL, rug = TRUE, position = \"identity\", response_range = NULL, ... )"},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.evaluated_parametric_term.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Plot estimated parametric effects — draw.evaluated_parametric_term","text":"object object, result call evaluate_parametric_term(). ci_level numeric 0 1; coverage credible interval. constant numeric; constant add estimated values smooth. constant, supplied, added estimated value confidence band computed. fun function; function applied estimated values confidence interval plotting. Can function name function. Function fun applied adding constant, provided. xlab character expression; label x axis. supplied, suitable label generated object. ylab character expression; label y axis. supplied, suitable label generated object. title character expression; title plot. See ggplot2::labs(). subtitle character expression; subtitle plot. See ggplot2::labs(). caption character expression; plot caption. See ggplot2::labs(). rug evaluate_parametric_terms(), logical indicate rug plot drawn. position Position adjustment, either string, result call position adjustment function. response_range numeric; vector two values giving range response data guide. Used fix plots common scale/range. Ignored show set \"se\". ... arguments passed methods.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.evaluated_parametric_term.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Plot estimated parametric effects — draw.evaluated_parametric_term","text":"ggplot2::ggplot() object.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.evaluated_parametric_term.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Plot estimated parametric effects — draw.evaluated_parametric_term","text":"Gavin L. Simpson","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.gam.html","id":null,"dir":"Reference","previous_headings":"","what":"Plot estimated smooths from a fitted GAM — draw.gam","title":"Plot estimated smooths from a fitted GAM — draw.gam","text":"Plots estimated smooths fitted GAM model similar way mgcv::plot.gam() instead using base graphics, ggplot2::ggplot() used instead.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.gam.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Plot estimated smooths from a fitted GAM — draw.gam","text":"","code":"# S3 method for class 'gam' draw( object, data = NULL, select = NULL, parametric = FALSE, terms = NULL, residuals = FALSE, scales = c(\"free\", \"fixed\"), ci_level = 0.95, n = 100, n_3d = 16, n_4d = 4, unconditional = FALSE, overall_uncertainty = TRUE, constant = NULL, fun = NULL, dist = 0.1, rug = TRUE, contour = TRUE, grouped_by = FALSE, ci_alpha = 0.2, ci_col = \"black\", smooth_col = \"black\", resid_col = \"steelblue3\", contour_col = \"black\", n_contour = NULL, partial_match = FALSE, discrete_colour = NULL, discrete_fill = NULL, continuous_colour = NULL, continuous_fill = NULL, position = \"identity\", angle = NULL, ncol = NULL, nrow = NULL, guides = \"keep\", widths = NULL, heights = NULL, crs = NULL, default_crs = NULL, lims_method = \"cross\", wrap = TRUE, caption = TRUE, envir = environment(formula(object)), ... )"},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.gam.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Plot estimated smooths from a fitted GAM — draw.gam","text":"object fitted GAM, result call mgcv::gam(). data optional data frame used supply data smooths evaluated plotted. usually needed, option need fine control exactly data used plotting. select character, logical, numeric; smooths plot. NULL, default, model smooths drawn. Numeric select indexes smooths order specified formula stored object. Character select matches labels smooths shown example output summary(object). Logical select operates per numeric select order smooths stored. parametric logical; plot parametric terms also? Note select used selecting smooths plot. terms argument used select parametric effects plotted. default, mgcv::plot.gam(), draw parametric effects. terms character; model parametric terms drawn? Default NULL plot parametric terms can drawn. residuals logical; partial residuals smooth drawn? Ignored anything simple univariate smooth. scales character; univariate smooths plotted y-axis scale? scales = \"free\", default, univariate smooth y-axis scale. scales = \"fixed\", common y axis scale used univariate smooths. Currently affect y-axis scale plots parametric terms. ci_level numeric 0 1; coverage credible interval. n numeric; number points range covariate evaluate smooth. n_3d numeric; number new observations generate third dimension 3D smooth. n_4d numeric; number new observations generate dimensions higher 2 (!) kD smooth (k >= 4). example, smooth 4D smooth, dimensions 3 4 get n_4d new observations. unconditional logical; confidence intervals include uncertainty due smoothness selection? TRUE, corrected Bayesian covariance matrix used. overall_uncertainty logical; uncertainty model constant term included standard error evaluate values smooth? constant numeric; constant add estimated values smooth. constant, supplied, added estimated value confidence band computed. fun function; function applied estimated values confidence interval plotting. Can function name function. Function fun applied adding constant, provided. dist numeric; greater 0, used determine location far data plotted plotting 2-D smooths. data scaled unit square deciding exclude, dist distance within unit square. See mgcv::exclude..far() details. rug logical; draw rug plot bottom plot 1-D smooths plot locations data higher dimensions. contour logical; contours draw plot using ggplot2::geom_contour(). grouped_by logical; factor smooths drawn one panel per level factor (FALSE, default), individual smooths combined single panel containing levels (TRUE)? ci_alpha numeric; alpha transparency confidence simultaneous interval. ci_col colour specification confidence/credible intervals band. Affects fill interval. smooth_col colour specification smooth line. resid_col colour specification partial residuals. contour_col colour specification contour lines. n_contour numeric; number contour bins. result n_contour - 1 contour lines drawn. See ggplot2::geom_contour(). partial_match logical; smooths selected partial matches select? TRUE, select can single string match . discrete_colour suitable colour scale used plotting discrete variables. discrete_fill suitable fill scale used plotting discrete variables. continuous_colour suitable colour scale used plotting continuous variables. continuous_fill suitable fill scale used plotting continuous variables. position Position adjustment, either string, result call position adjustment function. angle numeric; angle x axis tick labels drawn passed angle argument ggplot2::guide_axis(). ncol, nrow numeric; numbers rows columns spread plots guides character; one \"keep\" (default), \"collect\", \"auto\". Passed patchwork::plot_layout() widths, heights relative widths heights column row grid. get repeated match dimensions grid. 1 plot widths = NULL, value widths set internally widths = 1 accommodate plots smooths use fixed aspect ratio. crs coordinate reference system (CRS) use plot. data projected CRS. See ggplot2::coord_sf() details. default_crs coordinate reference system (CRS) use non-sf layers plot. left default NULL, CRS used 4326 (WGS84), appropriate spline---sphere smooths, parameterized terms latitude longitude coordinates. See ggplot2::coord_sf() details. lims_method character; affects axis limits determined. See ggplot2::coord_sf(). careful; testing examples, changing \"orthogonal\" example chlorophyll-example Simon Wood's GAM book quickly used RAM test system OS killed R. incorrect usage part; right now grid points SOS smooths evaluated (supplied user) can produce invalid coordinates corners tiles grid generated tile centres without respect spacing tiles. wrap logical; wrap plots patchwork? FALSE, list ggplot objects returned, 1 per term plotted. caption logical; show smooth type caption plot? envir environment look data within. ... additional arguments passed patchwork::wrap_plots().","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.gam.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Plot estimated smooths from a fitted GAM — draw.gam","text":"object returned created patchwork::wrap_plots().","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.gam.html","id":"note","dir":"Reference","previous_headings":"","what":"Note","title":"Plot estimated smooths from a fitted GAM — draw.gam","text":"Internally, plots smooth created using ggplot2::ggplot() composed single plot using patchwork::wrap_plots(). result, possible use + add plots way one might typically work ggplot() plots. Instead, use & operator; see examples.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.gam.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Plot estimated smooths from a fitted GAM — draw.gam","text":"Gavin L. Simpson","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.gam.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Plot estimated smooths from a fitted GAM — draw.gam","text":"","code":"load_mgcv() # simulate some data df1 <- data_sim(\"eg1\", n = 400, dist = \"normal\", scale = 2, seed = 2) # fit GAM m1 <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = df1, method = \"REML\") # plot all smooths draw(m1) # can add partial residuals draw(m1, residuals = TRUE) df2 <- data_sim(\"eg2\", n = 1000, dist = \"normal\", scale = 1, seed = 2) m2 <- gam(y ~ s(x, z, k = 40), data = df2, method = \"REML\") draw(m2, contour = FALSE, n = 50) # See https://gavinsimpson.github.io/gratia/articles/custom-plotting.html # for more examples and for details on how to modify the theme of all the # plots produced by draw(). To modify all panels, for example to change the # theme, use the & operator"},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.gamlss.html","id":null,"dir":"Reference","previous_headings":"","what":"Plot smooths of a GAMLSS model estimated by GJRM::gamlss — draw.gamlss","title":"Plot smooths of a GAMLSS model estimated by GJRM::gamlss — draw.gamlss","text":"Provides draw() method GAMLSS (distributional GAMs) fitted GJRM::gamlss().","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.gamlss.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Plot smooths of a GAMLSS model estimated by GJRM::gamlss — draw.gamlss","text":"","code":"# S3 method for class 'gamlss' draw( object, scales = c(\"free\", \"fixed\"), ncol = NULL, nrow = NULL, guides = \"keep\", widths = NULL, heights = NULL, ... )"},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.gamlss.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Plot smooths of a GAMLSS model estimated by GJRM::gamlss — draw.gamlss","text":"object model, fitted GJRM::gamlss() scales character; univariate smooths plotted y-axis scale? scales = \"free\", default, univariate smooth y-axis scale. scales = \"fixed\", common y axis scale used univariate smooths. Currently affect y-axis scale plots parametric terms. ncol, nrow numeric; numbers rows columns spread plots guides character; one \"keep\" (default), \"collect\", \"auto\". Passed patchwork::plot_layout() widths, heights relative widths heights column row grid. get repeated match dimensions grid. 1 plot widths = NULL, value widths set internally widths = 1 accommodate plots smooths use fixed aspect ratio. ... arguments passed draw.gam()","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.gamlss.html","id":"note","dir":"Reference","previous_headings":"","what":"Note","title":"Plot smooths of a GAMLSS model estimated by GJRM::gamlss — draw.gamlss","text":"Plots smooths labelled linear predictor belong.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.gamlss.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Plot smooths of a GAMLSS model estimated by GJRM::gamlss — draw.gamlss","text":"","code":"if (require(\"GJRM\", quietly = TRUE)) { # follow example from ?GJRM::gamlss load_mgcv() suppressPackageStartupMessages(library(\"GJRM\")) set.seed(0) n <- 100 x1 <- round(runif(n)) x2 <- runif(n) x3 <- runif(n) f1 <- function(x) cos(pi * 2 * x) + sin(pi * x) y1 <- -1.55 + 2 * x1 + f1(x2) + rnorm(n) dataSim <- data.frame(y1, x1, x2, x3) eq_mu <- y1 ~ x1 + s(x2) eq_s <- ~ s(x3, k = 6) fl <- list(eq_mu, eq_s) m <- gamlss(fl, data = dataSim) draw(m) }"},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.html","id":null,"dir":"Reference","previous_headings":"","what":"Generic plotting via ggplot2 — draw","title":"Generic plotting via ggplot2 — draw","text":"Generic plotting via ggplot2","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Generic plotting via ggplot2 — draw","text":"","code":"draw(object, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Generic plotting via ggplot2 — draw","text":"object R object plot. ... arguments passed methods.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Generic plotting via ggplot2 — draw","text":"ggplot2::ggplot() object.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Generic plotting via ggplot2 — draw","text":"Generic function plotting R objects uses ggplot2 package.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Generic plotting via ggplot2 — draw","text":"Gavin L. Simpson","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.mgcv_smooth.html","id":null,"dir":"Reference","previous_headings":"","what":"Plot basis functions — draw.mgcv_smooth","title":"Plot basis functions — draw.mgcv_smooth","text":"Plots basis functions using ggplot2","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.mgcv_smooth.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Plot basis functions — draw.mgcv_smooth","text":"","code":"# S3 method for class 'mgcv_smooth' draw( object, legend = FALSE, use_facets = TRUE, labeller = NULL, xlab, ylab, title = NULL, subtitle = NULL, caption = NULL, angle = NULL, ... )"},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.mgcv_smooth.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Plot basis functions — draw.mgcv_smooth","text":"object object, result call basis(). legend logical; legend drawn indicate basis functions? use_facets logical; factor smooths, use facets show basis functions level factor? FALSE, separate ggplot object created level combined using patchwork::wrap_plots(). Currently ignored. labeller labeller function label facets. default use ggplot2::label_both(). xlab character expression; label x axis. supplied, suitable label generated object. ylab character expression; label y axis. supplied, suitable label generated object. title character expression; title plot. See ggplot2::labs(). subtitle character expression; subtitle plot. See ggplot2::labs(). caption character expression; plot caption. See ggplot2::labs(). angle numeric; angle x axis tick labels drawn passed angle argument ggplot2::guide_axis(). ... arguments passed methods. used method.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.mgcv_smooth.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Plot basis functions — draw.mgcv_smooth","text":"ggplot2::ggplot() object.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.mgcv_smooth.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Plot basis functions — draw.mgcv_smooth","text":"Gavin L. Simpson","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.mgcv_smooth.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Plot basis functions — draw.mgcv_smooth","text":"","code":"load_mgcv() df <- data_sim(\"eg4\", n = 400, seed = 42) bf <- basis(s(x0), data = df) draw(bf) bf <- basis(s(x2, by = fac, bs = \"bs\"), data = df) draw(bf)"},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.pairwise_concurvity.html","id":null,"dir":"Reference","previous_headings":"","what":"Plot concurvity measures — draw.pairwise_concurvity","title":"Plot concurvity measures — draw.pairwise_concurvity","text":"Plot concurvity measures","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.pairwise_concurvity.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Plot concurvity measures — draw.pairwise_concurvity","text":"","code":"# S3 method for class 'pairwise_concurvity' draw( object, title = \"Smooth-wise concurvity\", subtitle = NULL, caption = NULL, x_lab = \"Term\", y_lab = \"With\", fill_lab = \"Concurvity\", continuous_colour = NULL, ... ) # S3 method for class 'overall_concurvity' draw( object, title = \"Overall concurvity\", subtitle = NULL, caption = NULL, y_lab = \"Concurvity\", x_lab = NULL, bar_col = \"steelblue\", bar_fill = \"steelblue\", ... )"},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.pairwise_concurvity.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Plot concurvity measures — draw.pairwise_concurvity","text":"object object inheriting class \"concurvity\", usually result call model_concurvity() abbreviated form concrvity(). title character; plot title. subtitle character; plot subtitle. caption character; plot caption x_lab character; label x axis. y_lab character; label y axis. fill_lab character; label use fill guide. continuous_colour function; continuous colour (fill) scale use. ... arguments passed methods. bar_col colour specification bar colour. bar_fill colour specification bar fill","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.parametric_effects.html","id":null,"dir":"Reference","previous_headings":"","what":"Plot estimated effects for model parametric terms — draw.parametric_effects","title":"Plot estimated effects for model parametric terms — draw.parametric_effects","text":"Plot estimated effects model parametric terms","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.parametric_effects.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Plot estimated effects for model parametric terms — draw.parametric_effects","text":"","code":"# S3 method for class 'parametric_effects' draw( object, scales = c(\"free\", \"fixed\"), ci_level = 0.95, ci_col = \"black\", ci_alpha = 0.2, line_col = \"black\", constant = NULL, fun = NULL, rug = TRUE, position = \"identity\", angle = NULL, ..., ncol = NULL, nrow = NULL, guides = \"keep\" )"},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.parametric_effects.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Plot estimated effects for model parametric terms — draw.parametric_effects","text":"object fitted GAM, result call mgcv::gam(). scales character; univariate smooths plotted y-axis scale? scales = \"free\", default, univariate smooth y-axis scale. scales = \"fixed\", common y axis scale used univariate smooths. Currently affect y-axis scale plots parametric terms. ci_level numeric 0 1; coverage credible interval. ci_col colour specification confidence/credible intervals band. Affects fill interval. ci_alpha numeric; alpha transparency confidence simultaneous interval. line_col colour specification used regression lines linear continuous terms. constant numeric; constant add estimated values smooth. constant, supplied, added estimated value confidence band computed. fun function; function applied estimated values confidence interval plotting. Can function name function. Function fun applied adding constant, provided. rug logical; draw rug plot bottom plot 1-D smooths plot locations data higher dimensions. position Position adjustment, either string, result call position adjustment function. angle numeric; angle x axis tick labels drawn passed angle argument ggplot2::guide_axis(). ... additional arguments passed patchwork::wrap_plots(). ncol, nrow numeric; numbers rows columns spread plots guides character; one \"keep\" (default), \"collect\", \"auto\". Passed patchwork::plot_layout()","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.penalty_df.html","id":null,"dir":"Reference","previous_headings":"","what":"Display penalty matrices of smooths using ggplot — draw.penalty_df","title":"Display penalty matrices of smooths using ggplot — draw.penalty_df","text":"Displays penalty matrices smooths heatmap using ggplot","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.penalty_df.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Display penalty matrices of smooths using ggplot — draw.penalty_df","text":"","code":"# S3 method for class 'penalty_df' draw( object, normalize = FALSE, as_matrix = TRUE, continuous_fill = NULL, xlab = NULL, ylab = NULL, title = NULL, subtitle = NULL, caption = NULL, ncol = NULL, nrow = NULL, guides = \"keep\", ... )"},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.penalty_df.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Display penalty matrices of smooths using ggplot — draw.penalty_df","text":"object fitted GAM, result call mgcv::gam(). normalize logical; normalize penalty range -1, 1? as_matrix logical; plotted penalty matrix oriented? TRUE row 1, column 1 penalty matrix draw upper left, whereas, FALSE drawn lower left plot. continuous_fill suitable fill scale used plotting continuous variables. xlab character expression; label x axis. supplied, axis label drawn. May vector, one per penalty. ylab character expression; label y axis. supplied, axis label drawn. May vector, one per penalty. title character expression; title plot. See ggplot2::labs(). May vector, one per penalty. subtitle character expression; subtitle plot. See ggplot2::labs(). May vector, one per penalty. caption character expression; plot caption. See ggplot2::labs(). May vector, one per penalty. ncol, nrow numeric; numbers rows columns spread plots. guides character; one \"keep\" (default), \"collect\", \"auto\". Passed patchwork::plot_layout() ... additional arguments passed patchwork::wrap_plots().","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.penalty_df.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Display penalty matrices of smooths using ggplot — draw.penalty_df","text":"","code":"load_mgcv() dat <- data_sim(\"eg4\", n = 400, seed = 42) m <- gam(y ~ s(x0) + s(x1, bs = \"cr\") + s(x2, bs = \"bs\", by = fac), data = dat, method = \"REML\" ) ## produce a multi-panel plot of all penalties draw(penalty(m)) # for a specific smooth draw(penalty(m, select = \"s(x2):fac1\"))"},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.rootogram.html","id":null,"dir":"Reference","previous_headings":"","what":"Draw a rootogram — draw.rootogram","title":"Draw a rootogram — draw.rootogram","text":"rootogram model diagnostic tool assesses goodness fit statistical model. observed values response compared expected fitted model. discrete, count responses, frequency count (0, 1, 2, etc) observed data expected conditional distribution response implied model compared. continuous variables, observed expected frequencies obtained grouping data bins. rootogram drawn using ggplot2::ggplot() graphics. design closely follows Kleiber & Zeileis (2016).","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.rootogram.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Draw a rootogram — draw.rootogram","text":"","code":"# S3 method for class 'rootogram' draw( object, type = c(\"hanging\", \"standing\", \"suspended\"), sqrt = TRUE, ref_line = TRUE, warn_limits = TRUE, fitted_colour = \"steelblue\", bar_colour = NA, bar_fill = \"grey\", ref_line_colour = \"black\", warn_line_colour = \"black\", ylab = NULL, xlab = NULL, ... )"},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.rootogram.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Draw a rootogram — draw.rootogram","text":"object R object plot. type character; type rootogram draw. sqrt logical; show observed fitted frequencies ref_line logical; draw reference line zero? warn_limits logical; draw Tukey's warning limit lines +/- 1? fitted_colour, bar_colour, bar_fill, ref_line_colour, warn_line_colour colours used draw respective element rootogram. xlab, ylab character; labels x y axis rootogram. May missing (NULL), case suitable labels used. ' ... arguments passed methods.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.rootogram.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Draw a rootogram — draw.rootogram","text":"'ggplot' object.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.rootogram.html","id":"references","dir":"Reference","previous_headings":"","what":"References","title":"Draw a rootogram — draw.rootogram","text":"Kleiber, C., Zeileis, ., (2016) Visualizing Count Data Regressions Using Rootograms. . Stat. 70, 296–303. doi:10.1080/00031305.2016.1173590","code":""},{"path":[]},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.rootogram.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Draw a rootogram — draw.rootogram","text":"","code":"load_mgcv() df <- data_sim(\"eg1\", n = 1000, dist = \"poisson\", scale = 0.1, seed = 6) # A poisson example m <- gam(y ~ s(x0, bs = \"cr\") + s(x1, bs = \"cr\") + s(x2, bs = \"cr\") + s(x3, bs = \"cr\"), family = poisson(), data = df, method = \"REML\") rg <- rootogram(m) # plot the rootogram draw(rg) # change the type of rootogram draw(rg, type = \"suspended\")"},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.smooth_estimates.html","id":null,"dir":"Reference","previous_headings":"","what":"Plot the result of a call to smooth_estimates() — draw.smooth_estimates","title":"Plot the result of a call to smooth_estimates() — draw.smooth_estimates","text":"Plot result call smooth_estimates()","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.smooth_estimates.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Plot the result of a call to smooth_estimates() — draw.smooth_estimates","text":"","code":"# S3 method for class 'smooth_estimates' draw( object, constant = NULL, fun = NULL, contour = TRUE, grouped_by = FALSE, contour_col = \"black\", n_contour = NULL, ci_alpha = 0.2, ci_col = \"black\", smooth_col = \"black\", resid_col = \"steelblue3\", decrease_col = \"#56B4E9\", increase_col = \"#E69F00\", change_lwd = 1.75, partial_match = FALSE, discrete_colour = NULL, discrete_fill = NULL, continuous_colour = NULL, continuous_fill = NULL, angle = NULL, ylim = NULL, crs = NULL, default_crs = NULL, lims_method = \"cross\", caption = TRUE, ... )"},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.smooth_estimates.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Plot the result of a call to smooth_estimates() — draw.smooth_estimates","text":"object fitted GAM, result call mgcv::gam(). constant numeric; constant add estimated values smooth. constant, supplied, added estimated value confidence band computed. fun function; function applied estimated values confidence interval plotting. Can function name function. Function fun applied adding constant, provided. contour logical; contours draw plot using ggplot2::geom_contour(). grouped_by logical; factor smooths drawn one panel per level factor (FALSE, default), individual smooths combined single panel containing levels (TRUE)? contour_col colour specification contour lines. n_contour numeric; number contour bins. result n_contour - 1 contour lines drawn. See ggplot2::geom_contour(). ci_alpha numeric; alpha transparency confidence simultaneous interval. ci_col colour specification confidence/credible intervals band. Affects fill interval. smooth_col colour specification smooth line. resid_col colour specification partial residuals. decrease_col, increase_col colour specifications use indicating periods change. col_change used change_type = \"change\", col_decrease col_increase used `change_type = \"sizer\"“. change_lwd numeric; value set linewidth ggplot2::geom_line(), used represent periods change. partial_match logical; smooths selected partial matches select? TRUE, select can single string match . discrete_colour suitable colour scale used plotting discrete variables. discrete_fill suitable fill scale used plotting discrete variables. continuous_colour suitable colour scale used plotting continuous variables. continuous_fill suitable fill scale used plotting continuous variables. angle numeric; angle x axis tick labels drawn passed angle argument ggplot2::guide_axis(). ylim numeric; vector y axis limits use panels drawn. crs coordinate reference system (CRS) use plot. data projected CRS. See ggplot2::coord_sf() details. default_crs coordinate reference system (CRS) use non-sf layers plot. left default NULL, CRS used 4326 (WGS84), appropriate spline---sphere smooths, parameterized terms latitude longitude coordinates. See ggplot2::coord_sf() details. lims_method character; affects axis limits determined. See ggplot2::coord_sf(). careful; testing examples, changing \"orthogonal\" example chlorophyll-example Simon Wood's GAM book quickly used RAM test system OS killed R. incorrect usage part; right now grid points SOS smooths evaluated (supplied user) can produce invalid coordinates corners tiles grid generated tile centres without respect spacing tiles. caption logical; show smooth type caption plot? ... additional arguments passed patchwork::wrap_plots().","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.smooth_estimates.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Plot the result of a call to smooth_estimates() — draw.smooth_estimates","text":"","code":"load_mgcv() # example data df <- data_sim(\"eg1\", seed = 21) # fit GAM m <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = df, method = \"REML\") # plot all of the estimated smooths sm <- smooth_estimates(m) draw(sm) # evaluate smooth of `x2` sm <- smooth_estimates(m, select = \"s(x2)\") # plot it draw(sm) # customising some plot elements draw(sm, ci_col = \"steelblue\", smooth_col = \"forestgreen\", ci_alpha = 0.3) # Add a constant to the plotted smooth draw(sm, constant = coef(m)[1]) # Adding change indicators to smooths based on derivatives of the smooth d <- derivatives(m, n = 100) # n to match smooth_estimates() smooth_estimates(m) |> add_sizer(derivatives = d, type = \"sizer\") |> draw()"},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.smooth_samples.html","id":null,"dir":"Reference","previous_headings":"","what":"Plot posterior smooths — draw.smooth_samples","title":"Plot posterior smooths — draw.smooth_samples","text":"Plot posterior smooths","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.smooth_samples.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Plot posterior smooths — draw.smooth_samples","text":"","code":"# S3 method for class 'smooth_samples' draw( object, select = NULL, n_samples = NULL, seed = NULL, xlab = NULL, ylab = NULL, title = NULL, subtitle = NULL, caption = NULL, alpha = 1, colour = \"black\", contour = FALSE, contour_col = \"black\", n_contour = NULL, scales = c(\"free\", \"fixed\"), rug = TRUE, partial_match = FALSE, angle = NULL, ncol = NULL, nrow = NULL, guides = \"keep\", ... )"},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.smooth_samples.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Plot posterior smooths — draw.smooth_samples","text":"object fitted GAM, result call mgcv::gam(). select character, logical, numeric; smooths plot. NULL, default, model smooths drawn. Numeric select indexes smooths order specified formula stored object. Character select matches labels smooths shown example output summary(object). Logical select operates per numeric select order smooths stored. n_samples numeric; NULL, sample n_samples posterior draws plotting. seed numeric; random seed used sampling draws. xlab character expression; label x axis. supplied, suitable label generated object. ylab character expression; label y axis. supplied, suitable label generated object. title character expression; title plot. See ggplot2::labs(). subtitle character expression; subtitle plot. See ggplot2::labs(). caption character expression; plot caption. See ggplot2::labs(). alpha numeric; alpha transparency confidence simultaneous interval. colour colour use draw posterior smooths. Passed ggplot2::geom_line() argument colour. contour logical; contour lines added smooth surfaces? contour_col colour specification contour lines. n_contour numeric; number contour bins. result n_contour - 1 contour lines drawn. See ggplot2::geom_contour(). scales character; univariate smooths plotted y-axis scale? scales = \"free\", default, univariate smooth y-axis scale. scales = \"fixed\", common y axis scale used univariate smooths. Currently affect y-axis scale plots parametric terms. rug logical; draw rug plot bottom plot 1-D smooths plot locations data higher dimensions. partial_match logical; smooths selected partial matches select? TRUE, select can single string match . angle numeric; angle x axis tick labels drawn passed angle argument ggplot2::guide_axis(). ncol, nrow numeric; numbers rows columns spread plots guides character; one \"keep\" (default), \"collect\", \"auto\". Passed patchwork::plot_layout() ... arguments passed patchwork::wrap_plots().","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.smooth_samples.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Plot posterior smooths — draw.smooth_samples","text":"Gavin L. Simpson","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.smooth_samples.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Plot posterior smooths — draw.smooth_samples","text":"","code":"load_mgcv() dat1 <- data_sim(\"eg1\", n = 400, dist = \"normal\", scale = 1, seed = 1) ## a single smooth GAM m1 <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = dat1, method = \"REML\") ## posterior smooths from m1 sm1 <- smooth_samples(m1, n = 15, seed = 23478) ## plot draw(sm1, alpha = 0.7) ## plot only 5 randomly smapled draws draw(sm1, n_samples = 5, alpha = 0.7) ## A factor-by smooth example dat2 <- data_sim(\"eg4\", n = 400, dist = \"normal\", scale = 1, seed = 1) ## a multi-smooth GAM with a factor-by smooth m2 <- gam(y ~ fac + s(x2, by = fac) + s(x0), data = dat2, method = \"REML\") ## posterior smooths from m1 sm2 <- smooth_samples(m2, n = 15, seed = 23478) ## plot, this time selecting only the factor-by smooth draw(sm2, select = \"s(x2)\", partial_match = TRUE, alpha = 0.7) # \\donttest{ ## A 2D smooth example dat3 <- data_sim(\"eg2\", n = 400, dist = \"normal\", scale = 1, seed = 1) ## fit a 2D smooth m3 <- gam(y ~ te(x, z), data = dat3, method = \"REML\") ## get samples sm3 <- smooth_samples(m3, n = 10) ## plot just 6 of the draws, with contour line overlays draw(sm3, n_samples = 6, contour = TRUE, seed = 42) # }"},{"path":"https://gavinsimpson.github.io/gratia/reference/draw_parametric_effect.html","id":null,"dir":"Reference","previous_headings":"","what":"Internal function to draw an individual parametric effect — draw_parametric_effect","title":"Internal function to draw an individual parametric effect — draw_parametric_effect","text":"Internal function draw individual parametric effect","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw_parametric_effect.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Internal function to draw an individual parametric effect — draw_parametric_effect","text":"","code":"draw_parametric_effect( object, ci_level = 0.95, ci_col = \"black\", ci_alpha = 0.2, line_col = \"black\", constant = NULL, fun = NULL, xlab = NULL, ylab = NULL, title = NULL, subtitle = NULL, caption = NULL, rug = TRUE, position = \"identity\", ylim = NULL, angle = NULL, factor_levels = NULL, ... )"},{"path":"https://gavinsimpson.github.io/gratia/reference/draw_parametric_effect.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Internal function to draw an individual parametric effect — draw_parametric_effect","text":"object fitted GAM, result call mgcv::gam(). ci_level numeric 0 1; coverage credible interval. ci_col colour specification confidence/credible intervals band. Affects fill interval. ci_alpha numeric; alpha transparency confidence simultaneous interval. constant numeric; constant add estimated values smooth. constant, supplied, added estimated value confidence band computed. fun function; function applied estimated values confidence interval plotting. Can function name function. Function fun applied adding constant, provided. xlab character expression; label x axis. supplied, suitable label generated object. ylab character expression; label y axis. supplied, suitable label generated object. title character expression; title plot. See ggplot2::labs(). subtitle character expression; subtitle plot. See ggplot2::labs(). caption character expression; plot caption. See ggplot2::labs(). rug logical; draw rug plot bottom plot 1-D smooths plot locations data higher dimensions. position Position adjustment, either string, result call position adjustment function. angle numeric; angle x axis tick labels drawn passed angle argument ggplot2::guide_axis(). factor_levels list; named list factor levels ... additional arguments passed patchwork::wrap_plots().","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/edf.html","id":null,"dir":"Reference","previous_headings":"","what":"Effective degrees of freedom for smooths and GAMs — edf","title":"Effective degrees of freedom for smooths and GAMs — edf","text":"Extracts effective degrees freedom (EDF) model smooth terms overall EDF fitted GAMs","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/edf.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Effective degrees of freedom for smooths and GAMs — edf","text":"","code":"edf(object, ...) # S3 method for class 'gam' edf( object, select = NULL, smooth = deprecated(), type = c(\"default\", \"unconditional\", \"alternative\"), partial_match = FALSE, ... ) model_edf(object, ..., type = c(\"default\", \"unconditional\", \"alternative\"))"},{"path":"https://gavinsimpson.github.io/gratia/reference/edf.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Effective degrees of freedom for smooths and GAMs — edf","text":"object fitted model extract smooth-specific EDFs. ... arguments passed methods. select character, logical, numeric; smooths plot. NULL, default, model smooths drawn. Numeric select indexes smooths order specified formula stored object. Character select matches labels smooths shown example output summary(object). Logical select operates per numeric select order smooths stored. smooth Use select instead. extracted. NULL, default, EDFs smooths returned. type character: type EDF return. \"default\" returns standard EDF; \"unconditional\" selects EDF corrected smoothness parameter selection, available; \"alternative\" returns alternative formulation EDF Wood (2017, pp. 252) partial_match logical; smooths selected partial matches select? TRUE, select can single string match .","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/edf.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Effective degrees of freedom for smooths and GAMs — edf","text":"Multiple formulations effective degrees freedom available. additional uncertainty due selection smoothness parameters can taken account computing EDF smooths. form EDF available type = \"unconditional\". Wood (2017; pp. 252) describes alternative EDF model $$\\mathrm{EDF} = 2\\mathrm{tr}(\\mathbf{F}) - \\mathrm{tr}(\\mathbf{FF}),$$ \\(\\mathrm{tr}\\) matrix trace \\(\\mathbf{F}\\) matrix mapping un-penalized coefficient estimates penalized coefficient estimates. trace \\(\\mathbf{F}\\) effectively average shrinkage coefficients multipled number coefficients (Wood, 2017). Smooth-specific EDFs obtained summing relevent elements \\(\\mathrm{diag}(2\\mathbf{F} - \\mathbf{FF})\\).","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/edf.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Effective degrees of freedom for smooths and GAMs — edf","text":"","code":"load_mgcv() df <- data_sim(\"eg1\", n = 400, seed = 42) m <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = df, method = \"REML\") # extract the EDFs for all smooths edf(m) #> # A tibble: 4 x 2 #> .smooth .edf #> #> 1 s(x0) 3.4248 #> 2 s(x1) 3.2213 #> 3 s(x2) 7.9049 #> 4 s(x3) 1.8847 # or selected smooths edf(m, select = c(\"s(x0)\", \"s(x2)\")) #> # A tibble: 2 x 2 #> .smooth .edf #> #> 1 s(x0) 3.4248 #> 2 s(x2) 7.9049 # accounting for smoothness parameter uncertainty edf(m, type = \"unconditional\") #> # A tibble: 4 x 2 #> .smooth .edf #> #> 1 s(x0) 3.7697 #> 2 s(x1) 3.8728 #> 3 s(x2) 8.0670 #> 4 s(x3) 2.8834 # over EDF of the model, including the intercept model_edf(m) #> # A tibble: 1 x 2 #> .model .edf #> #> 1 m 17.436 # can get model EDF for multiple models m2 <- gam(y ~ s(x0) + s(x1) + s(x3), data = df, method = \"REML\") model_edf(m, m2) #> # A tibble: 2 x 2 #> .model .edf #> #> 1 m 17.436 #> 2 m2 7.5777"},{"path":"https://gavinsimpson.github.io/gratia/reference/eval_smooth.html","id":null,"dir":"Reference","previous_headings":"","what":"S3 methods to evaluate individual smooths — eval_smooth","title":"S3 methods to evaluate individual smooths — eval_smooth","text":"S3 methods evaluate individual smooths","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/eval_smooth.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"S3 methods to evaluate individual smooths — eval_smooth","text":"","code":"eval_smooth(smooth, ...) # S3 method for class 'mgcv.smooth' eval_smooth( smooth, model, n = 100, n_3d = NULL, n_4d = NULL, data = NULL, unconditional = FALSE, overall_uncertainty = TRUE, dist = NULL, ... ) # S3 method for class 'soap.film' eval_smooth( smooth, model, n = 100, n_3d = NULL, n_4d = NULL, data = NULL, unconditional = FALSE, overall_uncertainty = TRUE, ... ) # S3 method for class 'scam_smooth' eval_smooth( smooth, model, n = 100, n_3d = NULL, n_4d = NULL, data = NULL, unconditional = FALSE, overall_uncertainty = TRUE, dist = NULL, ... ) # S3 method for class 'fs.interaction' eval_smooth( smooth, model, n = 100, data = NULL, unconditional = FALSE, overall_uncertainty = TRUE, ... ) # S3 method for class 'sz.interaction' eval_smooth( smooth, model, n = 100, data = NULL, unconditional = FALSE, overall_uncertainty = TRUE, ... ) # S3 method for class 'random.effect' eval_smooth( smooth, model, n = 100, data = NULL, unconditional = FALSE, overall_uncertainty = TRUE, ... ) # S3 method for class 'mrf.smooth' eval_smooth( smooth, model, n = 100, data = NULL, unconditional = FALSE, overall_uncertainty = TRUE, ... ) # S3 method for class 't2.smooth' eval_smooth( smooth, model, n = 100, n_3d = NULL, n_4d = NULL, data = NULL, unconditional = FALSE, overall_uncertainty = TRUE, dist = NULL, ... ) # S3 method for class 'tensor.smooth' eval_smooth( smooth, model, n = 100, n_3d = NULL, n_4d = NULL, data = NULL, unconditional = FALSE, overall_uncertainty = TRUE, dist = NULL, ... )"},{"path":"https://gavinsimpson.github.io/gratia/reference/eval_smooth.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"S3 methods to evaluate individual smooths — eval_smooth","text":"smooth currently object inherits class mgcv.smooth. ... arguments passed methods model fitted model; currently mgcv::gam() mgcv::bam() models suported. n numeric; number points range covariate evaluate smooth. n_3d, n_4d numeric; number points range last covariate 3D 4D smooth. default NULL achieves standard behaviour using n points range covariate, resulting n^d evaluation points, d dimension smooth. d > 2 can result many evaluation points slow performance. smooths d > 4, value n_4d used dimensions > 4, unless NULL, case default behaviour (using n dimensions) observed. data optional data frame values evaluate smooth . unconditional logical; confidence intervals include uncertainty due smoothness selection? TRUE, corrected Bayesian covariance matrix used. overall_uncertainty logical; uncertainty model constant term included standard error evaluate values smooth? dist numeric; greater 0, used determine location far data plotted plotting 2-D smooths. data scaled unit square deciding exclude, dist distance within unit square. See mgcv::exclude..far() details.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/evaluate_parametric_term.html","id":null,"dir":"Reference","previous_headings":"","what":"Evaluate parametric model terms — evaluate_parametric_term","title":"Evaluate parametric model terms — evaluate_parametric_term","text":"Returns values parametric model terms values factor terms grid covariate values linear parametric terms. function now deprecated favour parametric_effects().","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/evaluate_parametric_term.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Evaluate parametric model terms — evaluate_parametric_term","text":"","code":"evaluate_parametric_term(object, ...) # S3 method for class 'gam' evaluate_parametric_term(object, term, unconditional = FALSE, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/evaluate_parametric_term.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Evaluate parametric model terms — evaluate_parametric_term","text":"object object class \"gam\" \"gamm\". ... arguments passed methods. term character; parametric term whose effects evaluated unconditional logical; confidence intervals include uncertainty due smoothness selection? TRUE, corrected Bayesian covariance matrix used.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/evaluate_smooth.html","id":null,"dir":"Reference","previous_headings":"","what":"Evaluate a smooth — evaluate_smooth","title":"Evaluate a smooth — evaluate_smooth","text":"Evaluate smooth grid evenly spaced value range covariate associated smooth. Alternatively, set points smooth evaluated can supplied.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/evaluate_smooth.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Evaluate a smooth — evaluate_smooth","text":"","code":"evaluate_smooth(object, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/evaluate_smooth.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Evaluate a smooth — evaluate_smooth","text":"object object class \"gam\" \"gamm\". ... arguments passed methods.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/evaluate_smooth.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Evaluate a smooth — evaluate_smooth","text":"data frame, class \"evaluated_1d_smooth\" evaluated_2d_smooth, inherit classes \"evaluated_smooth\" \"data.frame\".","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/evaluate_smooth.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Evaluate a smooth — evaluate_smooth","text":"evaluate_smooth() deprecated favour smooth_estimates(), provides cleaner way evaluate smooth range covariate values. smooth_estimates() can handle much wider range models evaluate_smooth() capable smooth_estimates() much easier extend handle new smooth types. code uses evaluate_smooth() work simply changing function call smooth_estimates(). However, differences: newdata argument becomes data","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/evenly.html","id":null,"dir":"Reference","previous_headings":"","what":"Create a sequence of evenly-spaced values — evenly","title":"Create a sequence of evenly-spaced values — evenly","text":"continuous vector x, evenly seq_min_max() create sequence n evenly-spaced values range lower – upper. default, lower defined min(x) upper max(x), excluding NAs. factor x, function returns levels(x).","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/evenly.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Create a sequence of evenly-spaced values — evenly","text":"","code":"evenly(x, n = 100, by = NULL, lower = NULL, upper = NULL) seq_min_max(x, n, by = NULL, lower = NULL, upper = NULL)"},{"path":"https://gavinsimpson.github.io/gratia/reference/evenly.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Create a sequence of evenly-spaced values — evenly","text":"x numeric; vector evenly-spaced values returned n numeric; number evenly-spaced values return. default 100 used convenience typically used evaluating smooth. numeric; increment sequence. specified, argument n ignored sequence returned min(x) max(x) increments . lower numeric; lower bound interval. upper numeric; upper bound interval.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/evenly.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Create a sequence of evenly-spaced values — evenly","text":"numeric vector length n.","code":""},{"path":[]},{"path":"https://gavinsimpson.github.io/gratia/reference/evenly.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Create a sequence of evenly-spaced values — evenly","text":"","code":"x <- rnorm(10) n <- 10L # 10 values evenly over the range of `x` evenly(x, n = n) #> [1] -0.83562861 -0.56552757 -0.29542652 -0.02532547 0.24477557 0.51487662 #> [7] 0.78497766 1.05507871 1.32517976 1.59528080 # evenly spaced values, incrementing by 0.2 evenly(x, by = 0.2) #> [1] -0.83562861 -0.63562861 -0.43562861 -0.23562861 -0.03562861 0.16437139 #> [7] 0.36437139 0.56437139 0.76437139 0.96437139 1.16437139 1.36437139 #> [13] 1.56437139 # evenly spaced values, incrementing by 0.2, starting at -2 evenly(x, by = 0.2, lower = -2) #> [1] -2.0 -1.8 -1.6 -1.4 -1.2 -1.0 -0.8 -0.6 -0.4 -0.2 0.0 0.2 0.4 0.6 0.8 #> [16] 1.0 1.2 1.4"},{"path":"https://gavinsimpson.github.io/gratia/reference/factor_combos.html","id":null,"dir":"Reference","previous_headings":"","what":"All combinations of factor levels — factor_combos","title":"All combinations of factor levels — factor_combos","text":"combinations factor levels","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/factor_combos.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"All combinations of factor levels — factor_combos","text":"","code":"factor_combos(object, ...) # S3 method for class 'gam' factor_combos(object, vars = everything(), complete = TRUE, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/factor_combos.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"All combinations of factor levels — factor_combos","text":"object fitted model object. ... arguments passed methods. vars terms include exclude returned object. Uses tidyselect principles. complete logical; combinations factor levels returned? FALSE, combinations levels observed model retained.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/family.gam.html","id":null,"dir":"Reference","previous_headings":"","what":"Extract family objects from models — family.gam","title":"Extract family objects from models — family.gam","text":"Provides stats::family() method range GAM objects.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/family.gam.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Extract family objects from models — family.gam","text":"","code":"# S3 method for class 'gam' family(object, ...) # S3 method for class 'gamm' family(object, ...) # S3 method for class 'bam' family(object, ...) # S3 method for class 'list' family(object, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/family.gam.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Extract family objects from models — family.gam","text":"object fitted model. Models fitted mgcv::gam(), mgcv::bam(), mgcv::gamm(), gamm4::gamm4() currently supported. ... arguments passed methods.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/family_name.html","id":null,"dir":"Reference","previous_headings":"","what":"Name of family used to fit model — family_name","title":"Name of family used to fit model — family_name","text":"Extracts name family used fit supplied model.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/family_name.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Name of family used to fit model — family_name","text":"","code":"family_name(object, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/family_name.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Name of family used to fit model — family_name","text":"object R object. ... arguments passed methods.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/family_name.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Name of family used to fit model — family_name","text":"character vector containing family name.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/family_type.html","id":null,"dir":"Reference","previous_headings":"","what":"Extracts the type of family in a consistent way — family_type","title":"Extracts the type of family in a consistent way — family_type","text":"Extracts type family consistent way","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/family_type.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Extracts the type of family in a consistent way — family_type","text":"","code":"family_type(object, ...) # S3 method for class 'family' family_type(object, ...) # Default S3 method family_type(object, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/family_type.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Extracts the type of family in a consistent way — family_type","text":"object R object. Currently family() objects anything family() method. ... arguments passed methods.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/fderiv.html","id":null,"dir":"Reference","previous_headings":"","what":"First derivatives of fitted GAM functions — fderiv","title":"First derivatives of fitted GAM functions — fderiv","text":"function deprecated limited first order forward finite differences derivatives , improved offer needed functionality without breaking backwards compatability papers blog posts already used fderiv(). replacement, derivatives(), now available recommended new analyses.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/fderiv.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"First derivatives of fitted GAM functions — fderiv","text":"","code":"fderiv(model, ...) # S3 method for class 'gam' fderiv( model, newdata, term, n = 200, eps = 1e-07, unconditional = FALSE, offset = NULL, ... ) # S3 method for class 'gamm' fderiv(model, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/fderiv.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"First derivatives of fitted GAM functions — fderiv","text":"model fitted GAM. Currently models fitted mgcv::gam() mgcv::gamm() supported. ... Arguments passed methods. newdata data frame containing values model covariates evaluate first derivatives smooths. term character; vector one terms derivatives required. missing, derivatives smooth terms returned. n integer; newdata missing original data can reconstructed model n controls number values range covariate populate newdata. eps numeric; value finite difference used approximate first derivative. unconditional logical; TRUE, smoothing parameter uncertainty corrected covariance matrix used, available, otherwise uncorrected Bayesian posterior covariance matrix used. offset numeric; value offset use generating predictions.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/fderiv.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"First derivatives of fitted GAM functions — fderiv","text":"object class \"fderiv\" returned.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/fderiv.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"First derivatives of fitted GAM functions — fderiv","text":"Gavin L. Simpson","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/fderiv.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"First derivatives of fitted GAM functions — fderiv","text":"","code":"load_mgcv() dat <- data_sim(\"eg1\", seed = 2) mod <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = dat, method = \"REML\") ## first derivatives of all smooths... fd <- fderiv(mod) ## now use --> fd <- derivatives(mod) ## ...and a selected smooth fd2 <- fderiv(mod, term = \"x1\") ## now use --> fd2 <- derivatives(mod, select = \"s(x1)\") ## Models with factors dat <- data_sim(\"eg4\", n = 400, dist = \"normal\", scale = 2, seed = 2) mod <- gam(y ~ s(x0) + s(x1) + fac, data = dat, method = \"REML\") ## first derivatives of all smooths... fd <- fderiv(mod) ## now use --> fd <- derivatives(mod) ## ...and a selected smooth fd2 <- fderiv(mod, term = \"x1\") ## now use --> fd2 <- derivatives(mod, select = \"s(x1)\")"},{"path":"https://gavinsimpson.github.io/gratia/reference/fitted_samples.html","id":null,"dir":"Reference","previous_headings":"","what":"Draw fitted values from the posterior distribution — fitted_samples","title":"Draw fitted values from the posterior distribution — fitted_samples","text":"Expectations (fitted values) response drawn posterior distribution fitted model using Gaussian approximation posterior simple Metropolis Hastings sampler.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/fitted_samples.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Draw fitted values from the posterior distribution — fitted_samples","text":"","code":"fitted_samples(model, ...) # S3 method for class 'gam' fitted_samples( model, n = 1, data = newdata, seed = NULL, scale = c(\"response\", \"linear_predictor\"), method = c(\"gaussian\", \"mh\", \"inla\", \"user\"), n_cores = 1, burnin = 1000, thin = 1, t_df = 40, rw_scale = 0.25, freq = FALSE, unconditional = FALSE, draws = NULL, mvn_method = c(\"mvnfast\", \"mgcv\"), ..., newdata = NULL, ncores = NULL )"},{"path":"https://gavinsimpson.github.io/gratia/reference/fitted_samples.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Draw fitted values from the posterior distribution — fitted_samples","text":"model fitted model supported types ... arguments passed methods. fitted_samples(), passed mgcv::predict.gam(). posterior_samples() passed fitted_samples(). predicted_samples() passed relevant simulate() method. n numeric; number posterior samples return. data data frame; new observations posterior draws model evaluated. supplied, data used fit model used data, available model. seed numeric; random seed simulations. scale character; scale fitted values returned ? \"linear predictor\" synonym \"link\" prefer terminology. method character; method used draw samples posterior distribution. \"gaussian\" uses Gaussian (Laplace) approximation posterior. \"mh\" uses Metropolis Hastings sampler alternates t proposals proposals based shrunken version posterior covariance matrix. \"inla\" uses variant Integrated Nested Laplace Approximation due Wood (2019), (currently implemented). \"user\" allows user-supplied posterior draws (currently implemented). n_cores number cores generating random variables multivariate normal distribution. Passed mvnfast::rmvn(). Parallelization take place OpenMP supported (appears work Windows current R). burnin numeric; number samples discard burnin draws. used method = \"mh\". thin numeric; number samples skip taking n draws. Results thin * n draws posterior taken. used method = \"mh\". t_df numeric; degrees freedom t distribution proposals. used method = \"mh\". rw_scale numeric; Factor scale posterior covariance matrix generating random walk proposals. Negative non finite skip random walk step. used method = \"mh\". freq logical; TRUE use frequentist covariance matrix parameter estimators, FALSE use Bayesian posterior covariance matrix parameters. unconditional logical; TRUE (freq == FALSE) Bayesian smoothing parameter uncertainty corrected covariance matrix used, available. draws matrix; user supplied posterior draws used method = \"user\". mvn_method character; one \"mvnfast\" \"mgcv\". default uses mvnfast::rmvn(), can considerably faster generate large numbers MVN random values mgcv::rmvn(), might work marginal fits, covariance matrix close singular. newdata Deprecated: use data instead. ncores Deprecated; use n_cores instead. number cores generating random variables multivariate normal distribution. Passed mvnfast::rmvn(). Parallelization take place OpenMP supported (appears work Windows current R).","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/fitted_samples.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Draw fitted values from the posterior distribution — fitted_samples","text":"tibble (data frame) 3 columns containing posterior predicted values long format. columns row (integer) row data posterior draw relates , draw (integer) index, range 1:n, indicating draw row relates , response (numeric) predicted response indicated row data.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/fitted_samples.html","id":"note","dir":"Reference","previous_headings":"","what":"Note","title":"Draw fitted values from the posterior distribution — fitted_samples","text":"Models offset terms supplied via offset argument mgcv::gam() etc. ignored mgcv::predict.gam(). , kind offset term also ignored posterior_samples(). Offset terms included model formula supplied mgcv::gam() etc ignored posterior samples produced reflect offset term values. side effect requiring new data values provided posterior_samples() via data argument must include offset variable.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/fitted_samples.html","id":"references","dir":"Reference","previous_headings":"","what":"References","title":"Draw fitted values from the posterior distribution — fitted_samples","text":"Wood, S.N., (2020). Simplified integrated nested Laplace approximation. Biometrika 107, 223–230. doi:10.1093/biomet/asz044","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/fitted_samples.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Draw fitted values from the posterior distribution — fitted_samples","text":"Gavin L. Simpson","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/fitted_samples.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Draw fitted values from the posterior distribution — fitted_samples","text":"","code":"load_mgcv() dat <- data_sim(\"eg1\", n = 1000, dist = \"normal\", scale = 2, seed = 2) m1 <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = dat, method = \"REML\") fs <- fitted_samples(m1, n = 5, seed = 42) # \\donttest{ fs #> # A tibble: 5,000 x 4 #> .row .draw .parameter .fitted #> #> 1 1 1 location 6.34 #> 2 2 1 location 5.08 #> 3 3 1 location 6.84 #> 4 4 1 location 7.71 #> 5 5 1 location 9.23 #> 6 6 1 location 8.03 #> 7 7 1 location 6.19 #> 8 8 1 location 7.28 #> 9 9 1 location 14.0 #> 10 10 1 location 12.7 #> # i 4,990 more rows # } # can generate own set of draws and use them drws <- generate_draws(m1, n = 2, seed = 24) fs2 <- fitted_samples(m1, method = \"user\", draws = drws) # \\donttest{ fs2 #> # A tibble: 2,000 x 4 #> .row .draw .parameter .fitted #> #> 1 1 1 location 6.30 #> 2 2 1 location 5.12 #> 3 3 1 location 7.40 #> 4 4 1 location 7.42 #> 5 5 1 location 9.40 #> 6 6 1 location 8.04 #> 7 7 1 location 5.83 #> 8 8 1 location 7.30 #> 9 9 1 location 14.3 #> 10 10 1 location 13.1 #> # i 1,990 more rows # }"},{"path":"https://gavinsimpson.github.io/gratia/reference/fitted_values.html","id":null,"dir":"Reference","previous_headings":"","what":"Generate fitted values from a estimated GAM — fitted_values","title":"Generate fitted values from a estimated GAM — fitted_values","text":"Generate fitted values estimated GAM","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/fitted_values.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Generate fitted values from a estimated GAM — fitted_values","text":"","code":"fitted_values(object, ...) # S3 method for class 'gam' fitted_values( object, data = NULL, scale = c(\"response\", \"link\", \"linear predictor\"), ci_level = 0.95, ... ) # S3 method for class 'gamm' fitted_values(object, ...) # S3 method for class 'scam' fitted_values(object, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/fitted_values.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Generate fitted values from a estimated GAM — fitted_values","text":"object fitted model. Currently models fitted mgcv::gam() mgcv::bam() supported. ... arguments passed mgcv::predict.gam(). Note type, newdata, se.fit already used passed mgcv::predict.gam(). data optional data frame covariate values fitted values returned. scale character; scale fitted values returned ? \"linear predictor\" synonym \"link\" prefer terminology. ci_level numeric; value 0 1 indicating coverage credible interval.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/fitted_values.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Generate fitted values from a estimated GAM — fitted_values","text":"tibble (data frame) whose first m columns contain either data used fit model (data NULL), variables supplied data. Four columns added: fitted: fitted values specified scale, se: standard error fitted values (always link scale), lower, upper: limits credible interval fitted values, specified scale. Models fitted certain families include additional variables mgcv::ocat() models: scale = \"repsonse\", returned object contain row column category column, indicate row data row returned object belongs. Additionally, nrow(data) * n_categories rows returned object; row predicted probability single category response.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/fitted_values.html","id":"note","dir":"Reference","previous_headings":"","what":"Note","title":"Generate fitted values from a estimated GAM — fitted_values","text":"families, regardless scale fitted values returned, se component returned object link (linear predictor) scale, response scale. exception mgcv::ocat() family, se response scale scale = \"response\".","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/fitted_values.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Generate fitted values from a estimated GAM — fitted_values","text":"","code":"load_mgcv() sim_df <- data_sim(\"eg1\", n = 400, dist = \"normal\", scale = 2, seed = 2) m <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = sim_df, method = \"REML\") fv <- fitted_values(m) fv #> # A tibble: 400 x 9 #> .row x0 x1 x2 x3 .fitted .se .lower_ci #> #> 1 1 0.184882 0.617142 0.415244 0.132410 8.73875 0.354677 8.04360 #> 2 2 0.702374 0.569064 0.531439 0.365331 7.62581 0.337779 6.96378 #> 3 3 0.573326 0.153970 0.00324621 0.454532 3.12106 0.591862 1.96103 #> 4 4 0.168052 0.0348332 0.252100 0.537114 11.1124 0.402378 10.3237 #> 5 5 0.943839 0.997953 0.155229 0.185495 14.0533 0.452947 13.1655 #> 6 6 0.943475 0.835574 0.878840 0.449276 6.13080 0.364521 5.41635 #> 7 7 0.129159 0.586562 0.203511 0.256527 12.4838 0.355808 11.7864 #> 8 8 0.833449 0.339117 0.583528 0.618458 6.25215 0.344700 5.57655 #> 9 9 0.468019 0.166883 0.804473 0.880744 4.21463 0.372003 3.48552 #> 10 10 0.549984 0.807410 0.264717 0.317747 15.5283 0.369999 14.8031 #> # i 390 more rows #> # i 1 more variable: .upper_ci "},{"path":"https://gavinsimpson.github.io/gratia/reference/fix_offset.html","id":null,"dir":"Reference","previous_headings":"","what":"Fix the names of a data frame containing an offset variable. — fix_offset","title":"Fix the names of a data frame containing an offset variable. — fix_offset","text":"Identifies variable, , model offset, fixed name offset(foo(var)) converted var, possibly sets values variable offset_val.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/fix_offset.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Fix the names of a data frame containing an offset variable. — fix_offset","text":"","code":"fix_offset(model, newdata, offset_val = NULL)"},{"path":"https://gavinsimpson.github.io/gratia/reference/fix_offset.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Fix the names of a data frame containing an offset variable. — fix_offset","text":"model fitted GAM. newdata data frame; new values predict . offset_val numeric, optional; provided, offset variable newdata set constant value returning newdata","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/fix_offset.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Fix the names of a data frame containing an offset variable. — fix_offset","text":"original newdata returned fixed names possibly modified offset variable.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/fix_offset.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Fix the names of a data frame containing an offset variable. — fix_offset","text":"Gavin L. Simpson","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/fix_offset.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Fix the names of a data frame containing an offset variable. — fix_offset","text":"","code":"load_mgcv() df <- data_sim(\"eg1\", n = 400, dist = \"normal\", seed = 2) m <- gam(y ~ s(x0) + s(x1) + offset(x2), data = df, method = \"REML\") names(model.frame(m)) #> [1] \"y\" \"offset(x2)\" \"x0\" \"x1\" names(fix_offset(m, model.frame(m), offset_val = 1L)) #> [1] \"y\" \"x2\" \"x0\" \"x1\""},{"path":"https://gavinsimpson.github.io/gratia/reference/fixef.gam.html","id":null,"dir":"Reference","previous_headings":"","what":"Extract fixed effects estimates from a fitted GAM — fixef.gam","title":"Extract fixed effects estimates from a fitted GAM — fixef.gam","text":"Extract fixed effects estimates fitted GAM","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/fixef.gam.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Extract fixed effects estimates from a fitted GAM — fixef.gam","text":"","code":"# S3 method for class 'gam' fixef(object, ...) # S3 method for class 'gamm' fixef(object, ...) # S3 method for class 'lm' fixef(object, ...) # S3 method for class 'glm' fixef(object, ...) fixed_effects(object, ...) # Default S3 method fixed_effects(object, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/fixef.gam.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Extract fixed effects estimates from a fitted GAM — fixef.gam","text":"object fitted GAM ... arguments passed methods","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/fixef.gam.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Extract fixed effects estimates from a fitted GAM — fixef.gam","text":"","code":"load_mgcv() # run example if lme4 is available if (require(\"lme4\")) { data(sleepstudy, package = \"lme4\") m <- gam( Reaction ~ Days + s(Subject, bs = \"re\") + s(Days, Subject, bs = \"re\"), data = sleepstudy, method = \"REML\" ) fixef(m) } #> Loading required package: lme4 #> Loading required package: Matrix #> (Intercept) Days #> 251.40510 10.46729"},{"path":"https://gavinsimpson.github.io/gratia/reference/fixef.html","id":null,"dir":"Reference","previous_headings":"","what":"Extract fixed effects estimates — fixef","title":"Extract fixed effects estimates — fixef","text":"Extract fixed effects estimates","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/fixef.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Extract fixed effects estimates — fixef","text":"object fitted GAM ... arguments passed methods","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/gaussian_draws.html","id":null,"dir":"Reference","previous_headings":"","what":"Posterior samples using a simple Metropolis Hastings sampler — gaussian_draws","title":"Posterior samples using a simple Metropolis Hastings sampler — gaussian_draws","text":"Posterior samples using simple Metropolis Hastings sampler","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/gaussian_draws.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Posterior samples using a simple Metropolis Hastings sampler — gaussian_draws","text":"","code":"gaussian_draws(model, ...) # S3 method for class 'gam' gaussian_draws( model, n, n_cores = 1L, index = NULL, frequentist = FALSE, unconditional = FALSE, mvn_method = \"mvnfast\", ... ) # S3 method for class 'scam' gaussian_draws( model, n, n_cores = 1L, index = NULL, frequentist = FALSE, parametrized = TRUE, mvn_method = \"mvnfast\", ... )"},{"path":"https://gavinsimpson.github.io/gratia/reference/gaussian_draws.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Posterior samples using a simple Metropolis Hastings sampler — gaussian_draws","text":"model fitted R model. Currently models fitted mgcv::gam() mgcv::bam(), return object inherits objects supported. , \"inherits\" used loose fashion; models fitted scam::scam() support even though models strictly inherit class \"gam\" far inherits() concerned. ... arguments passed methods. n numeric; number posterior draws take. n_cores integer; number CPU cores use generating multivariate normal distributed random values. used mvn_method = \"mvnfast\" method = \"gaussian\". index numeric; vector indices coefficients use. Can used subset mean vector covariance matrix extracted model. frequentist logical; TRUE, frequentist covariance matrix parameter estimates used. FALSE, Bayesian posterior covariance matrix parameters used. See mgcv::vcov.gam(). unconditional logical; TRUE Bayesian smoothing parameter uncertainty corrected covariance matrix used, available model. See mgcv::vcov.gam(). mvn_method character; one \"mvnfast\" \"mgcv\". default uses mvnfast::rmvn(), can considerably faster generate large numbers MVN random values mgcv::rmvn(), might work marginal fits, covariance matrix close singular. parametrized logical; use parametrized coefficients covariance matrix, respect linear inequality constraints model. scam::scam() model fits.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/get_by_smooth.html","id":null,"dir":"Reference","previous_headings":"","what":"Extract an factor-by smooth by name — get_by_smooth","title":"Extract an factor-by smooth by name — get_by_smooth","text":"Extract factor-smooth name","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/get_by_smooth.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Extract an factor-by smooth by name — get_by_smooth","text":"","code":"get_by_smooth(object, term, level)"},{"path":"https://gavinsimpson.github.io/gratia/reference/get_by_smooth.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Extract an factor-by smooth by name — get_by_smooth","text":"object fitted GAM model object. term character; name smooth term extract. level character; level factor exrtact smooth .","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/get_by_smooth.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Extract an factor-by smooth by name — get_by_smooth","text":"single smooth object, list smooths several match named term.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/get_smooth.html","id":null,"dir":"Reference","previous_headings":"","what":"Extract an mgcv smooth by name — get_smooth","title":"Extract an mgcv smooth by name — get_smooth","text":"Extract mgcv smooth name","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/get_smooth.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Extract an mgcv smooth by name — get_smooth","text":"","code":"get_smooth(object, term)"},{"path":"https://gavinsimpson.github.io/gratia/reference/get_smooth.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Extract an mgcv smooth by name — get_smooth","text":"object fitted GAM model object. term character; name smooth term extract","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/get_smooth.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Extract an mgcv smooth by name — get_smooth","text":"single smooth object, list smooths several match named term.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/get_smooths_by_id.html","id":null,"dir":"Reference","previous_headings":"","what":"Extract an mgcv smooth given its position in the model object — get_smooths_by_id","title":"Extract an mgcv smooth given its position in the model object — get_smooths_by_id","text":"Extract mgcv smooth given position model object","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/get_smooths_by_id.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Extract an mgcv smooth given its position in the model object — get_smooths_by_id","text":"","code":"get_smooths_by_id(object, id) # S3 method for class 'gam' get_smooths_by_id(object, id) # S3 method for class 'scam' get_smooths_by_id(object, id) # S3 method for class 'gamm' get_smooths_by_id(object, id) # S3 method for class 'gamm4' get_smooths_by_id(object, id) # S3 method for class 'list' get_smooths_by_id(object, id)"},{"path":"https://gavinsimpson.github.io/gratia/reference/get_smooths_by_id.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Extract an mgcv smooth given its position in the model object — get_smooths_by_id","text":"object fitted GAM model object. id numeric; position smooth model object.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/gratia-package.html","id":null,"dir":"Reference","previous_headings":"","what":"gratia: Graceful 'ggplot'-Based Graphics and Other Functions for GAMs Fitted Using 'mgcv' — gratia-package","title":"gratia: Graceful 'ggplot'-Based Graphics and Other Functions for GAMs Fitted Using 'mgcv' — gratia-package","text":"Graceful 'ggplot'-based graphics utility functions working generalized additive models (GAMs) fitted using 'mgcv' package. Provides reimplementation plot() method GAMs 'mgcv' provides, well 'tidyverse' compatible representations estimated smooths.","code":""},{"path":[]},{"path":"https://gavinsimpson.github.io/gratia/reference/gratia-package.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"gratia: Graceful 'ggplot'-Based Graphics and Other Functions for GAMs Fitted Using 'mgcv' — gratia-package","text":"Maintainer: Gavin L. Simpson ucfagls@gmail.com (ORCID) [copyright holder] contributors: Henrik Singmann (ORCID) [contributor]","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/gss_vocab.html","id":null,"dir":"Reference","previous_headings":"","what":"Data from the General Social Survey (GSS) from the National Opinion Research Center of the University of Chicago — gss_vocab","title":"Data from the General Social Survey (GSS) from the National Opinion Research Center of the University of Chicago — gss_vocab","text":"subset data carData::GSSvocab dataset carData package, containing observations 2016 .","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/gss_vocab.html","id":"format","dir":"Reference","previous_headings":"","what":"Format","title":"Data from the General Social Survey (GSS) from the National Opinion Research Center of the University of Chicago — gss_vocab","text":"data frame 1858 rows 3 variables: vocab: numeric; number words 10 correct vocabulary test. nativeBorn: factor; respondent born US? factor levels yes. ageGroup: factor; grouped age respondent levels 18-29 30-39, 40-49, 50-59, 60+.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/gw_functions.html","id":null,"dir":"Reference","previous_headings":"","what":"Gu and Wabha test functions — gw_f0","title":"Gu and Wabha test functions — gw_f0","text":"Gu Wabha test functions","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/gw_functions.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Gu and Wabha test functions — gw_f0","text":"","code":"gw_f0(x, ...) gw_f1(x, ...) gw_f2(x, ...) gw_f3(x, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/gw_functions.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Gu and Wabha test functions — gw_f0","text":"x numeric; vector points evaluate function , interval (0,1) ... arguments passed methods, ignored.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/gw_functions.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Gu and Wabha test functions — gw_f0","text":"","code":"x <- seq(0, 1, length = 6) gw_f0(x) #> [1] 0.000e+00 1.176e+00 1.902e+00 1.902e+00 1.176e+00 2.449e-16 gw_f1(x) #> [1] 1.000 1.492 2.226 3.320 4.953 7.389 gw_f2(x) #> [1] 0.000 8.591 4.261 3.199 1.100 0.000 gw_f3(x) # should be constant 0 #> [1] 0 0 0 0 0 0"},{"path":"https://gavinsimpson.github.io/gratia/reference/has_theta.html","id":null,"dir":"Reference","previous_headings":"","what":"Are additional parameters available for a GAM? — has_theta","title":"Are additional parameters available for a GAM? — has_theta","text":"additional parameters available GAM?","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/has_theta.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Are additional parameters available for a GAM? — has_theta","text":"","code":"has_theta(object)"},{"path":"https://gavinsimpson.github.io/gratia/reference/has_theta.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Are additional parameters available for a GAM? — has_theta","text":"object R object, either family() object object whose class family() method.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/has_theta.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Are additional parameters available for a GAM? — has_theta","text":"logical; TRUE additional parameters available, FALSE otherwise.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/has_theta.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Are additional parameters available for a GAM? — has_theta","text":"","code":"load_mgcv() df <- data_sim(\"eg1\", dist = \"poisson\", seed = 42, scale = 1 / 5) m <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = df, method = \"REML\", family = nb() ) has_theta(m) #> [1] TRUE p <- theta(m)"},{"path":"https://gavinsimpson.github.io/gratia/reference/is_by_smooth.html","id":null,"dir":"Reference","previous_headings":"","what":"Tests for by variable smooths — is_by_smooth","title":"Tests for by variable smooths — is_by_smooth","text":"Functions check smooth -variable one test type -variable smooth factor-smooth continous-smooth interaction.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/is_by_smooth.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Tests for by variable smooths — is_by_smooth","text":"","code":"is_by_smooth(smooth) is_factor_by_smooth(smooth) is_continuous_by_smooth(smooth) by_variable(smooth) by_level(smooth)"},{"path":"https://gavinsimpson.github.io/gratia/reference/is_by_smooth.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Tests for by variable smooths — is_by_smooth","text":"smooth object class \"mgcv.smooth\"","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/is_by_smooth.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Tests for by variable smooths — is_by_smooth","text":"logical vector.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/is_by_smooth.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Tests for by variable smooths — is_by_smooth","text":"Gavin L. Simpson","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/is_factor_term.html","id":null,"dir":"Reference","previous_headings":"","what":"Is a model term a factor (categorical)? — is_factor_term","title":"Is a model term a factor (categorical)? — is_factor_term","text":"Given name (term label) term model, identify term factor term numeric. useful considering interactions, terms like fac1:fac2 num1:fac1 may requested user. terms type fac1:fac2 function return TRUE.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/is_factor_term.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Is a model term a factor (categorical)? — is_factor_term","text":"","code":"is_factor_term(object, term, ...) # S3 method for class 'terms' is_factor_term(object, term, ...) # S3 method for class 'gam' is_factor_term(object, term, ...) # S3 method for class 'bam' is_factor_term(object, term, ...) # S3 method for class 'gamm' is_factor_term(object, term, ...) # S3 method for class 'list' is_factor_term(object, term, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/is_factor_term.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Is a model term a factor (categorical)? — is_factor_term","text":"object R object method dispatch performed term character; name model term, sense attr(terms(object), \"term.labels\"). Currently checked see term exists model. ... arguments passed methods.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/is_factor_term.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Is a model term a factor (categorical)? — is_factor_term","text":"logical: TRUE variables involved term factors, otherwise FALSE.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/is_mgcv_smooth.html","id":null,"dir":"Reference","previous_headings":"","what":"Check if objects are smooths or are a particular type of smooth — is_mgcv_smooth","title":"Check if objects are smooths or are a particular type of smooth — is_mgcv_smooth","text":"Check objects smooths particular type smooth","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/is_mgcv_smooth.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Check if objects are smooths or are a particular type of smooth — is_mgcv_smooth","text":"","code":"is_mgcv_smooth(smooth) stop_if_not_mgcv_smooth(smooth) check_is_mgcv_smooth(smooth) is_mrf_smooth(smooth)"},{"path":"https://gavinsimpson.github.io/gratia/reference/is_mgcv_smooth.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Check if objects are smooths or are a particular type of smooth — is_mgcv_smooth","text":"smooth R object, typically list","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/is_mgcv_smooth.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Check if objects are smooths or are a particular type of smooth — is_mgcv_smooth","text":"Check smooth inherits class \"mgcv.smooth\". stop_if_not_mgcv_smooth() wrapper around is_mgcv_smooth(), useful programming checking supplied object one mgcv's smooths, throwing consistent error . check_is_mgcv_smooth() similar stop_if_not_mgcv_smooth() returns result is_mgcv_smooth() invisibly.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/is_offset.html","id":null,"dir":"Reference","previous_headings":"","what":"Is a model term an offset? — is_offset","title":"Is a model term an offset? — is_offset","text":"Given character vector model terms, checks see , , model offset.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/is_offset.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Is a model term an offset? — is_offset","text":"","code":"is_offset(terms)"},{"path":"https://gavinsimpson.github.io/gratia/reference/is_offset.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Is a model term an offset? — is_offset","text":"terms character vector model terms.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/is_offset.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Is a model term an offset? — is_offset","text":"logical vector length terms.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/is_offset.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Is a model term an offset? — is_offset","text":"Gavin L. Simpson","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/is_offset.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Is a model term an offset? — is_offset","text":"","code":"load_mgcv() df <- data_sim(\"eg1\", n = 400, dist = \"normal\") m <- gam(y ~ s(x0) + s(x1) + offset(x0), data = df, method = \"REML\") nm <- names(model.frame(m)) nm #> [1] \"y\" \"offset(x0)\" \"x0\" \"x1\" is_offset(nm) #> [1] FALSE TRUE FALSE FALSE"},{"path":"https://gavinsimpson.github.io/gratia/reference/link.html","id":null,"dir":"Reference","previous_headings":"","what":"Extract link and inverse link functions from models — link","title":"Extract link and inverse link functions from models — link","text":"Returns link inverse estimated model, provides simple way extract functions complex models multiple links, location scale models.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/link.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Extract link and inverse link functions from models — link","text":"","code":"link(object, ...) # S3 method for class 'family' link(object, parameter = NULL, which_eta = NULL, ...) # S3 method for class 'gam' link(object, parameter = NULL, which_eta = NULL, ...) # S3 method for class 'bam' link(object, parameter = NULL, which_eta = NULL, ...) # S3 method for class 'gamm' link(object, ...) # S3 method for class 'glm' link(object, ...) # S3 method for class 'list' link(object, ...) inv_link(object, ...) # S3 method for class 'family' inv_link(object, parameter = NULL, which_eta = NULL, ...) # S3 method for class 'gam' inv_link(object, parameter = NULL, which_eta = NULL, ...) # S3 method for class 'bam' inv_link(object, parameter = NULL, which_eta = NULL, ...) # S3 method for class 'gamm' inv_link(object, ...) # S3 method for class 'list' inv_link(object, ...) # S3 method for class 'glm' inv_link(object, ...) extract_link(family, ...) # S3 method for class 'family' extract_link(family, inverse = FALSE, ...) # S3 method for class 'general.family' extract_link(family, parameter, inverse = FALSE, which_eta = NULL, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/link.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Extract link and inverse link functions from models — link","text":"object family object fitted model extract family object. Models fitted stats::glm(), mgcv::gam(), mgcv::bam(), mgcv::gamm(), gamm4::gamm4() currently supported. ... arguments passed methods. parameter character; parameter distribution. Usually \"location\" \"scale\" \"shape\" may provided location scale models. options include \"mu\" synonym \"location\", \"sigma\" scale parameter mgcv::gaulss(), \"pi\" zero-inflation term mgcv::ziplss(), \"power\" mgcv::twlss() power parameter, \"xi\", shape parameter mgcv::gevlss(), \"epsilon\" \"skewness\" skewness \"delta\" \"kurtosis\" kurtosis parameter mgcv::shash(), \"phi\" scale parameter mgcv::gammals() & mgcv::twlss(). which_eta numeric; linear predictor extract families mgcv::mvn() mgcv::multinom(). family family object, result call family(). inverse logical; return inverse link function?","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/link.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Extract link and inverse link functions from models — link","text":"Gavin L. Simpson","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/link.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Extract link and inverse link functions from models — link","text":"","code":"load_mgcv() link(gaussian()) #> function (mu) #> mu #> link(nb()) #> function (mu) #> log(mu) #> inv_link(nb()) #> function (eta) #> pmax(exp(eta), .Machine$double.eps) #> dat <- data_sim(\"eg1\", seed = 4234) mod <- gam(list(y ~ s(x0) + s(x1) + s(x2) + s(x3), ~1), data = dat, family = gaulss ) link(mod, parameter = \"scale\") #> function (mu) #> log(1/mu - 0.01) #> inv_link(mod, parameter = \"scale\") #> function (eta) #> 1/(exp(eta) + 0.01) #> ## Works with `family` objects too link(shash(), parameter = \"skewness\") #> function (mu) #> mu #> "},{"path":"https://gavinsimpson.github.io/gratia/reference/load_mgcv.html","id":null,"dir":"Reference","previous_headings":"","what":"Load mgcv quietly — load_mgcv","title":"Load mgcv quietly — load_mgcv","text":"Simple function loads mgcv package whilst suppressing startup messages prints console.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/load_mgcv.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Load mgcv quietly — load_mgcv","text":"","code":"load_mgcv()"},{"path":"https://gavinsimpson.github.io/gratia/reference/load_mgcv.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Load mgcv quietly — load_mgcv","text":"Returns logical vectors invisibly, indicating whether package loaded .","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/lp_matrix.html","id":null,"dir":"Reference","previous_headings":"","what":"Return the linear prediction matrix of a fitted GAM — lp_matrix","title":"Return the linear prediction matrix of a fitted GAM — lp_matrix","text":"lp_matrix() wrapper predict(..., type = \"lpmatrix\") returning linear predictor matrix model training data (data = NULL), user-specified data values supplied via data.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/lp_matrix.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Return the linear prediction matrix of a fitted GAM — lp_matrix","text":"","code":"lp_matrix(model, ...) # S3 method for class 'gam' lp_matrix(model, data = NULL, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/lp_matrix.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Return the linear prediction matrix of a fitted GAM — lp_matrix","text":"model fitted model ... arguments passed methods predict methods including mgcv::predict.gam() mgcv::predict.bam() data data frame values return linear prediction matrix.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/lp_matrix.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Return the linear prediction matrix of a fitted GAM — lp_matrix","text":"linear prediction matrix returned matrix. object returned class \"lp_matrix\", inherits classes \"matrix\" \"array\". special class allows printing matrix controlled, printing matrix tibble.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/lp_matrix.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Return the linear prediction matrix of a fitted GAM — lp_matrix","text":"linear prediction matrix \\(\\mathbf{X}_p\\) matrix maps values parameters \\(\\hat{\\mathbf{\\beta}}_p\\) values linear predictor model \\(\\hat{\\eta}_p = \\mathbf{X}_p \\hat{\\mathbf{\\beta}}_p\\). \\(\\mathbf{X}_p\\) model matrix spline covariates replaced values basis functions evaluated respective covariates. Parametric covariates also included.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/lp_matrix.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Return the linear prediction matrix of a fitted GAM — lp_matrix","text":"","code":"load_mgcv() df <- data_sim(\"eg1\", seed = 1) m <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = df) # linear prediction matrix for observed data xp <- lp_matrix(m) ## IGNORE_RDIFF_BEGIN xp #> Linear prediction matrix (400 x 37) #> `(Intercept)` `s(x0).1` `s(x0).2` `s(x0).3` `s(x0).4` `s(x0).5` `s(x0).6` #> #> 1 1 0.961 0.227 0.706 -0.135 0.457 -0.146 #> 2 1 0.651 -0.241 0.0684 -0.308 0.394 -0.00994 #> 3 1 -0.385 -0.549 0.0660 -0.204 -0.416 -0.247 #> 4 1 -1.27 0.156 -1.53 0.222 -1.60 0.198 #> 5 1 1.05 0.420 1.11 0.214 0.893 0.0351 #> # i 395 more rows ## IGNORE_RDIFF_END # the object `xp` *is* a matrix class(xp) #> [1] \"lp_matrix\" \"matrix\" \"array\" # but we print like a tibble to avoid spamming the R console # linear predictor matrix for new data set ds <- data_slice(m, x2 = evenly(x2)) xp <- lp_matrix(m, data = ds) ## IGNORE_RDIFF_BEGIN xp #> Linear prediction matrix (100 x 37) #> `(Intercept)` `s(x0).1` `s(x0).2` `s(x0).3` `s(x0).4` `s(x0).5` `s(x0).6` #> #> 1 1 0.170 -0.542 -0.0371 -0.0534 0.144 -0.353 #> 2 1 0.170 -0.542 -0.0371 -0.0534 0.144 -0.353 #> 3 1 0.170 -0.542 -0.0371 -0.0534 0.144 -0.353 #> 4 1 0.170 -0.542 -0.0371 -0.0534 0.144 -0.353 #> 5 1 0.170 -0.542 -0.0371 -0.0534 0.144 -0.353 #> # i 95 more rows ## IGNORE_RDIFF_END"},{"path":"https://gavinsimpson.github.io/gratia/reference/lss_parameters.html","id":null,"dir":"Reference","previous_headings":"","what":"General names of LSS parameters for each GAM family — lss_parameters","title":"General names of LSS parameters for each GAM family — lss_parameters","text":"General names LSS parameters GAM family","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/lss_parameters.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"General names of LSS parameters for each GAM family — lss_parameters","text":"","code":"lss_parameters(object)"},{"path":"https://gavinsimpson.github.io/gratia/reference/mh_draws.html","id":null,"dir":"Reference","previous_headings":"","what":"Posterior samples using a Gaussian approximation to the posterior distribution — mh_draws","title":"Posterior samples using a Gaussian approximation to the posterior distribution — mh_draws","text":"Posterior samples using Gaussian approximation posterior distribution","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/mh_draws.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Posterior samples using a Gaussian approximation to the posterior distribution — mh_draws","text":"","code":"mh_draws(model, ...) # S3 method for class 'gam' mh_draws( model, n, burnin = 1000, thin = 1, t_df = 40, rw_scale = 0.25, index = NULL, ... )"},{"path":"https://gavinsimpson.github.io/gratia/reference/mh_draws.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Posterior samples using a Gaussian approximation to the posterior distribution — mh_draws","text":"model fitted R model. Currently models fitted mgcv::gam() mgcv::bam(), return object inherits objects supported. , \"inherits\" used loose fashion; models fitted scam::scam() support even though models strictly inherit class \"gam\" far inherits() concerned. ... arguments passed methods. n numeric; number posterior draws take. burnin numeric; length initial burn period discard. See mgcv::gam.mh(). thin numeric; retain thin samples. See mgcv::gam.mh(). t_df numeric; degrees freedom static multivariate t proposal. See mgcv::gam.mh(). rw_scale numeric; factor scale posterior covariance matrix generating random walk proposals. See mgcv::gam.mh(). index numeric; vector indices coefficients use. Can used subset mean vector covariance matrix extracted model.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/model_concurvity.html","id":null,"dir":"Reference","previous_headings":"","what":"Concurvity of an estimated GAM — model_concurvity","title":"Concurvity of an estimated GAM — model_concurvity","text":"Concurvity estimated GAM","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/model_concurvity.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Concurvity of an estimated GAM — model_concurvity","text":"","code":"model_concurvity(model, ...) # S3 method for class 'gam' model_concurvity( model, terms = everything(), type = c(\"all\", \"estimate\", \"observed\", \"worst\"), pairwise = FALSE, ... ) concrvity( model, terms = everything(), type = c(\"all\", \"estimate\", \"observed\", \"worst\"), pairwise = FALSE, ... )"},{"path":"https://gavinsimpson.github.io/gratia/reference/model_concurvity.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Concurvity of an estimated GAM — model_concurvity","text":"model fitted GAM. Currently objects class \"gam\" supported ... arguents passed methods. terms currently ignored type character; pairwise logical; extract pairwise concurvity model terms?","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/model_concurvity.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Concurvity of an estimated GAM — model_concurvity","text":"","code":"## simulate data with concurvity... library(\"tibble\") load_mgcv() set.seed(8) n <- 200 df <- tibble( t = sort(runif(n)), x = gw_f2(t) + rnorm(n) * 3, y = sin(4 * pi * t) + exp(x / 20) + rnorm(n) * 0.3 ) ## fit model m <- gam(y ~ s(t, k = 15) + s(x, k = 15), data = df, method = \"REML\") ## overall concurvity o_conc <- concrvity(m) draw(o_conc) ## pairwise concurvity p_conc <- concrvity(m, pairwise = TRUE) draw(p_conc)"},{"path":"https://gavinsimpson.github.io/gratia/reference/model_constant.html","id":null,"dir":"Reference","previous_headings":"","what":"Extract the model constant term — model_constant","title":"Extract the model constant term — model_constant","text":"Extracts model constant term(s), model intercept, fitted model object.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/model_constant.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Extract the model constant term — model_constant","text":"","code":"model_constant(model, ...) # S3 method for class 'gam' model_constant(model, lp = NULL, ...) # S3 method for class 'gamlss' model_constant(model, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/model_constant.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Extract the model constant term — model_constant","text":"model fitted model coef() method exists. ... arguments passed methods. lp numeric; linear predictors extract constant terms .","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/model_constant.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Extract the model constant term — model_constant","text":"","code":"load_mgcv() # simulate a small example df <- data_sim(\"eg1\", seed = 42) # fit the GAM m <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = df, method = \"REML\") # extract the estimate of the constant term model_constant(m) #> [1] 7.495 #> attr(,\"par_names\") #> [1] \"location\" # same as coef(m)[1L] coef(m)[1L] #> (Intercept) #> 7.495"},{"path":"https://gavinsimpson.github.io/gratia/reference/model_vars.html","id":null,"dir":"Reference","previous_headings":"","what":"List the variables involved in a model fitted with a formula — model_vars","title":"List the variables involved in a model fitted with a formula — model_vars","text":"List variables involved model fitted formula","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/model_vars.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"List the variables involved in a model fitted with a formula — model_vars","text":"","code":"model_vars(model, ...) # S3 method for class 'gam' model_vars(model, ...) # Default S3 method model_vars(model, ...) # S3 method for class 'bam' model_vars(model, ...) # S3 method for class 'gamm' model_vars(model, ...) # S3 method for class 'gamm4' model_vars(model, ...) # S3 method for class 'list' model_vars(model, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/model_vars.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"List the variables involved in a model fitted with a formula — model_vars","text":"model fitted model object $pred.formula, $terms component \"terms\" attribute ... Arguments passed methods. Currently ignored.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/model_vars.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"List the variables involved in a model fitted with a formula — model_vars","text":"","code":"load_mgcv() # simulate some Gaussian data df <- data_sim(\"eg1\", n = 50, seed = 2) # fit a GAM with 1 smooth and 1 linear term m1 <- gam(y ~ s(x2, k = 7) + x1, data = df, method = \"REML\") model_vars(m1) #> [1] \"x1\" \"x2\" # fit a lm with two linear terms m2 <- lm(y ~ x2 + x1, data = df) model_vars(m2) #> [1] \"x2\" \"x1\""},{"path":"https://gavinsimpson.github.io/gratia/reference/n_eta.html","id":null,"dir":"Reference","previous_headings":"","what":"The Number of linear predictors in model — n_eta","title":"The Number of linear predictors in model — n_eta","text":"Extracts number linear predictors fitted model.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/n_eta.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"The Number of linear predictors in model — n_eta","text":"","code":"n_eta(model, ...) # S3 method for class 'gam' n_eta(model, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/n_eta.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"The Number of linear predictors in model — n_eta","text":"model fitted model. Currently, models inheriting class \"gam\" supported. ... arguments passed methods.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/n_eta.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"The Number of linear predictors in model — n_eta","text":"integer vector length 1 containing number linear predictors model.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/n_smooths.html","id":null,"dir":"Reference","previous_headings":"","what":"How many smooths in a fitted model — n_smooths","title":"How many smooths in a fitted model — n_smooths","text":"many smooths fitted model","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/n_smooths.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"How many smooths in a fitted model — n_smooths","text":"","code":"n_smooths(object) # Default S3 method n_smooths(object) # S3 method for class 'gam' n_smooths(object) # S3 method for class 'gamm' n_smooths(object) # S3 method for class 'bam' n_smooths(object)"},{"path":"https://gavinsimpson.github.io/gratia/reference/n_smooths.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"How many smooths in a fitted model — n_smooths","text":"object fitted GAM related model. Typically result call mgcv::gam(), mgcv::bam(), mgcv::gamm().","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/nb_theta.html","id":null,"dir":"Reference","previous_headings":"","what":"Negative binomial parameter theta — nb_theta","title":"Negative binomial parameter theta — nb_theta","text":"Negative binomial parameter theta","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/nb_theta.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Negative binomial parameter theta — nb_theta","text":"","code":"nb_theta(model) # S3 method for class 'gam' nb_theta(model)"},{"path":"https://gavinsimpson.github.io/gratia/reference/nb_theta.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Negative binomial parameter theta — nb_theta","text":"model fitted model.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/nb_theta.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Negative binomial parameter theta — nb_theta","text":"numeric vector length 1 containing estimated value theta.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/nb_theta.html","id":"methods-by-class-","dir":"Reference","previous_headings":"","what":"Methods (by class)","title":"Negative binomial parameter theta — nb_theta","text":"nb_theta(gam): Method class \"gam\"","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/nb_theta.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Negative binomial parameter theta — nb_theta","text":"","code":"load_mgcv() df <- data_sim(\"eg1\", n = 500, dist = \"poisson\", scale = 0.1, seed = 6) m <- gam(y ~ s(x0, bs = \"cr\") + s(x1, bs = \"cr\") + s(x2, bs = \"cr\") + s(x3, bs = \"cr\"), family = nb, data = df, method = \"REML\") ## IGNORE_RDIFF_BEGIN nb_theta(m) #> [1] 239333.8 ## IGNORE_RDIFF_END"},{"path":"https://gavinsimpson.github.io/gratia/reference/nested_partial_residuals.html","id":null,"dir":"Reference","previous_headings":"","what":"Partial residuals in nested form — nested_partial_residuals","title":"Partial residuals in nested form — nested_partial_residuals","text":"Computes partial residuals smooth terms, formats long/tidy format, nests partial_residual column result nested data frame one row per smooth.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/nested_partial_residuals.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Partial residuals in nested form — nested_partial_residuals","text":"","code":"nested_partial_residuals(object, terms = NULL, data = NULL)"},{"path":"https://gavinsimpson.github.io/gratia/reference/nested_partial_residuals.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Partial residuals in nested form — nested_partial_residuals","text":"object fitted GAM model terms vector terms include partial residuals . Passed argument terms mgcv::predict.gam()]. data optional data frame","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/nested_partial_residuals.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Partial residuals in nested form — nested_partial_residuals","text":"nested tibble (data frame) one row per smooth term. Contains two columns: smooth - label indicating smooth term partial_residual - list column containing tibble (data frame) 1 column partial_residual containing requested partial residuals indicated smooth.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/nested_rug_values.html","id":null,"dir":"Reference","previous_headings":"","what":"Values for rug plot in nested form — nested_rug_values","title":"Values for rug plot in nested form — nested_rug_values","text":"Extracts original data smooth terms, formats long/tidy format, nests data column(s) result nested data frame one row per smooth.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/nested_rug_values.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Values for rug plot in nested form — nested_rug_values","text":"","code":"nested_rug_values(object, terms = NULL, data = NULL)"},{"path":"https://gavinsimpson.github.io/gratia/reference/nested_rug_values.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Values for rug plot in nested form — nested_rug_values","text":"object fitted GAM model terms vector terms include original data . Passed argument terms mgcv::predict.gam()]. data optional data frame","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/nested_rug_values.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Values for rug plot in nested form — nested_rug_values","text":"nested tibble (data frame) one row per smooth term.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/null_deviance.html","id":null,"dir":"Reference","previous_headings":"","what":"Extract the null deviance of a fitted model — null_deviance","title":"Extract the null deviance of a fitted model — null_deviance","text":"Extract null deviance fitted model","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/null_deviance.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Extract the null deviance of a fitted model — null_deviance","text":"","code":"null_deviance(model, ...) # Default S3 method null_deviance(model, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/null_deviance.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Extract the null deviance of a fitted model — null_deviance","text":"model fitted model ... arguments passed methods","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/observed_fitted_plot.html","id":null,"dir":"Reference","previous_headings":"","what":"Plot of fitted against observed response values — observed_fitted_plot","title":"Plot of fitted against observed response values — observed_fitted_plot","text":"Plot fitted observed response values","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/observed_fitted_plot.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Plot of fitted against observed response values — observed_fitted_plot","text":"","code":"observed_fitted_plot( model, ylab = NULL, xlab = NULL, title = NULL, subtitle = NULL, caption = NULL, point_col = \"black\", point_alpha = 1 )"},{"path":"https://gavinsimpson.github.io/gratia/reference/observed_fitted_plot.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Plot of fitted against observed response values — observed_fitted_plot","text":"model fitted model. Currently class \"gam\". ylab character expression; label y axis. supplied, suitable label generated. xlab character expression; label y axis. supplied, suitable label generated. title character expression; title plot. See ggplot2::labs(). subtitle character expression; subtitle plot. See ggplot2::labs(). caption character expression; plot caption. See ggplot2::labs(). point_col colour used draw points plots. See graphics::par() section Color Specification. passed individual plotting functions, therefore affects points plots. point_alpha numeric; alpha transparency points plots.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/overview.html","id":null,"dir":"Reference","previous_headings":"","what":"Provides an overview of a model and the terms in that model — overview","title":"Provides an overview of a model and the terms in that model — overview","text":"Provides overview model terms model","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/overview.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Provides an overview of a model and the terms in that model — overview","text":"","code":"overview(model, ...) # S3 method for class 'gam' overview( model, parametric = TRUE, random_effects = TRUE, dispersion = NULL, frequentist = FALSE, accuracy = 0.001, stars = FALSE, ... )"},{"path":"https://gavinsimpson.github.io/gratia/reference/overview.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Provides an overview of a model and the terms in that model — overview","text":"model fitted model object overview. ... arguments passed methods. parametric logical; include model parametric terms overview? random_effects tests fully penalized smooth terms (zero-dimensional null space, e.g. random effects) computationally expensive large data sets producing p values can take long time. random_effects = FALSE, tests expensive terms skipped. dispersion numeric; known value dispersion parameter. default NULL implies estimated value default value (1 Poisson distribution example) specified used instead. frequentist logical; default Bayesian estimated covariance matrix parameter estimates used calculate p values parametric terms. frequentist = FALSE, frequentist covariance matrix parameter estimates used. accuracy numeric; accuracy report p values, p values value displayed \"< accuracy\". stars logical; significance stars added output?","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/overview.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Provides an overview of a model and the terms in that model — overview","text":"","code":"load_mgcv() df <- data_sim(n = 400, seed = 2) m <- gam(y ~ x3 + s(x0) + s(x1, bs = \"bs\") + s(x2, bs = \"ts\"), data = df, method = \"REML\" ) overview(m) #> #> Generalized Additive Model with 4 terms #> #> term type k edf statistic p.value #> #> 1 x3 parametric NA 1 4.28 0.03926 #> 2 s(x0) TPRS 9 3.02 6.25 < 0.001 #> 3 s(x1) B spline 9 2.81 71.0 < 0.001 #> 4 s(x2) TPRS (shrink) 9 7.91 83.8 < 0.001"},{"path":"https://gavinsimpson.github.io/gratia/reference/parametric_effects.html","id":null,"dir":"Reference","previous_headings":"","what":"Estimated values for parametric model terms — parametric_effects","title":"Estimated values for parametric model terms — parametric_effects","text":"Estimated values parametric model terms","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/parametric_effects.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Estimated values for parametric model terms — parametric_effects","text":"","code":"parametric_effects(object, ...) # S3 method for class 'gam' parametric_effects( object, terms = NULL, data = NULL, unconditional = FALSE, unnest = TRUE, ci_level = 0.95, envir = environment(formula(object)), transform = FALSE, ... )"},{"path":"https://gavinsimpson.github.io/gratia/reference/parametric_effects.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Estimated values for parametric model terms — parametric_effects","text":"object fitted model object. ... arguments passed methods. terms character; model parametric terms drawn? Default NULL plot parametric terms can drawn. data optional data frame may may used? FIXME! unconditional logical; confidence intervals include uncertainty due smoothness selection? TRUE, corrected Bayesian covariance matrix used. unnest logical; unnest parametric effect objects? ci_level numeric; coverage required confidence interval. Currently ignored. envir environment look data within. transform logical; TRUE, parametric effect plotted transformed scale result effect straight line. FALSE, effect plotted raw data (.e. log10(x), poly(z), x-axis plot x z respectively.)","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/parametric_terms.html","id":null,"dir":"Reference","previous_headings":"","what":"Names of any parametric terms in a GAM — parametric_terms","title":"Names of any parametric terms in a GAM — parametric_terms","text":"Names parametric terms GAM","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/parametric_terms.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Names of any parametric terms in a GAM — parametric_terms","text":"","code":"parametric_terms(model, ...) # Default S3 method parametric_terms(model, ...) # S3 method for class 'gam' parametric_terms(model, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/parametric_terms.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Names of any parametric terms in a GAM — parametric_terms","text":"model fitted model. ... arguments passed methods.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/partial_derivatives.html","id":null,"dir":"Reference","previous_headings":"","what":"Partial derivatives of estimated multivariate smooths via finite differences — partial_derivatives","title":"Partial derivatives of estimated multivariate smooths via finite differences — partial_derivatives","text":"Partial derivatives estimated multivariate smooths via finite differences","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/partial_derivatives.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Partial derivatives of estimated multivariate smooths via finite differences — partial_derivatives","text":"","code":"partial_derivatives(object, ...) # Default S3 method partial_derivatives(object, ...) # S3 method for class 'gamm' partial_derivatives(object, ...) # S3 method for class 'gam' partial_derivatives( object, select = NULL, term = deprecated(), focal = NULL, data = newdata, order = 1L, type = c(\"forward\", \"backward\", \"central\"), n = 100, eps = 1e-07, interval = c(\"confidence\", \"simultaneous\"), n_sim = 10000, level = 0.95, unconditional = FALSE, frequentist = FALSE, offset = NULL, ncores = 1, partial_match = FALSE, seed = NULL, ..., newdata = NULL )"},{"path":"https://gavinsimpson.github.io/gratia/reference/partial_derivatives.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Partial derivatives of estimated multivariate smooths via finite differences — partial_derivatives","text":"object R object compute derivatives . ... arguments passed methods. select character; vector one smooth terms derivatives required. missing, derivatives smooth terms returned. Can partial match smooth term; see argument partial_match . term Use select instead. focal character; name focal variable. partial derivative estimated smooth respect variable returned. variables involved smooth held constant. can missing supplying data, case, focal variable identified one variable constant. data data frame containing values model covariates evaluate first derivatives smooths. supplied, one variable must held constant value. order numeric; order derivative. type character; type finite difference used. One \"forward\", \"backward\", \"central\". n numeric; number points evaluate derivative . eps numeric; finite difference. interval character; type interval compute. One \"confidence\" point-wise intervals, \"simultaneous\" simultaneous intervals. n_sim integer; number simulations used computing simultaneous intervals. level numeric; 0 < level < 1; confidence level point-wise simultaneous interval. default 0.95 95% interval. unconditional logical; use smoothness selection-corrected Bayesian covariance matrix? frequentist logical; use frequentist covariance matrix? offset numeric; value use offset term ncores number cores generating random variables multivariate normal distribution. Passed mvnfast::rmvn(). Parallelization take place OpenMP supported (appears work Windows current R). partial_match logical; smooths selected partial matches term? TRUE, term can single string match . seed numeric; RNG seed use. newdata Deprecated: use data instead.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/partial_derivatives.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Partial derivatives of estimated multivariate smooths via finite differences — partial_derivatives","text":"tibble, currently following variables: .smooth: smooth row refers , .partial_deriv: estimated partial derivative, .se: standard error estimated partial derivative, .crit: critical value derivative ± (crit * se) gives upper lower bounds requested confidence simultaneous interval (given level), .lower_ci: lower bound confidence simultaneous interval, .upper_ci: upper bound confidence simultaneous interval.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/partial_derivatives.html","id":"note","dir":"Reference","previous_headings":"","what":"Note","title":"Partial derivatives of estimated multivariate smooths via finite differences — partial_derivatives","text":"partial_derivatives() ignore random effect smooths encounters object.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/partial_derivatives.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Partial derivatives of estimated multivariate smooths via finite differences — partial_derivatives","text":"Gavin L. Simpson","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/partial_derivatives.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Partial derivatives of estimated multivariate smooths via finite differences — partial_derivatives","text":"","code":"library(\"ggplot2\") library(\"patchwork\") load_mgcv() df <- data_sim(\"eg2\", n = 2000, dist = \"normal\", scale = 0.5, seed = 42) # fit the GAM (note: for execution time reasons, k is set articifially low) m <- gam(y ~ te(x, z, k = c(5, 5)), data = df, method = \"REML\") # data slice through te(x,z) holding z == 0.4 ds <- data_slice(m, x = evenly(x, n = 100), z = 0.4) # evaluate te(x,z) at values of x & z sm <- smooth_estimates(m, select = \"te(x,z)\", data = ds) |> add_confint() # partial derivatives pd_x <- partial_derivatives(m, data = ds, type = \"central\", focal = \"x\") # draw te(x,z) p1 <- draw(m, rug = FALSE) & geom_hline(yintercept = 0.4, linewidth = 1) p1 # draw te(x,z) along slice cap <- expression(z == 0.4) p2 <- sm |> ggplot(aes(x = x, y = .estimate)) + geom_ribbon(aes(ymin = .lower_ci, ymax = .upper_ci), alpha = 0.2) + geom_line() + labs( x = \"x\", y = \"Partial effect\", title = \"te(x,z)\", caption = cap ) p2 # draw partial derivs p3 <- pd_x |> draw() + labs(caption = cap) p3 # draw all three panels p1 + p2 + p3 + plot_layout(ncol = 3)"},{"path":"https://gavinsimpson.github.io/gratia/reference/partial_residuals.html","id":null,"dir":"Reference","previous_headings":"","what":"Partial residuals — partial_residuals","title":"Partial residuals — partial_residuals","text":"Partial residuals","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/partial_residuals.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Partial residuals — partial_residuals","text":"","code":"partial_residuals(object, ...) # S3 method for class 'gam' partial_residuals(object, select = NULL, partial_match = FALSE, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/partial_residuals.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Partial residuals — partial_residuals","text":"object R object, typically model. Currently objects class \"gam\" (inherit class) supported. ... arguments passed methods. select character, logical, numeric; smooths plot. NULL, default, model smooths drawn. Numeric select indexes smooths order specified formula stored object. Character select matches labels smooths shown example output summary(object). Logical select operates per numeric select order smooths stored. partial_match logical; smooths selected partial matches select? TRUE, select can single string match .","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/partial_residuals.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Partial residuals — partial_residuals","text":"","code":"## load mgcv load_mgcv() ## example data - Gu & Wabha four term model df <- data_sim(\"eg1\", n = 400, seed = 42) ## fit the model m <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = df, method = \"REML\") ## extract partial residuals partial_residuals(m) #> # A tibble: 400 x 4 #> `s(x0)` `s(x1)` `s(x2)` `s(x3)` #> #> 1 -0.3527 -1.321 -2.180 0.6077 #> 2 -0.1233 0.5013 -1.775 0.9613 #> 3 1.429 1.515 5.609 0.9910 #> 4 -1.110 -1.700 -0.8882 -0.6593 #> 5 -2.120 -0.01378 -2.733 -3.012 #> 6 1.254 -1.224 3.915 0.07275 #> 7 -0.5220 3.023 -0.8197 -1.019 #> 8 1.398 0.2184 7.055 1.897 #> 9 2.797 0.4969 7.329 2.498 #> 10 1.151 -0.2267 0.7202 0.7437 #> # i 390 more rows ## and for a select term partial_residuals(m, select = \"s(x2)\") #> # A tibble: 400 x 1 #> `s(x2)` #> #> 1 -2.180 #> 2 -1.775 #> 3 5.609 #> 4 -0.8882 #> 5 -2.733 #> 6 3.915 #> 7 -0.8197 #> 8 7.055 #> 9 7.329 #> 10 0.7202 #> # i 390 more rows ## or with partial matching partial_residuals(m, select = \"x\", partial_match = TRUE) # returns all #> # A tibble: 400 x 4 #> `s(x0)` `s(x1)` `s(x2)` `s(x3)` #> #> 1 -0.3527 -1.321 -2.180 0.6077 #> 2 -0.1233 0.5013 -1.775 0.9613 #> 3 1.429 1.515 5.609 0.9910 #> 4 -1.110 -1.700 -0.8882 -0.6593 #> 5 -2.120 -0.01378 -2.733 -3.012 #> 6 1.254 -1.224 3.915 0.07275 #> 7 -0.5220 3.023 -0.8197 -1.019 #> 8 1.398 0.2184 7.055 1.897 #> 9 2.797 0.4969 7.329 2.498 #> 10 1.151 -0.2267 0.7202 0.7437 #> # i 390 more rows"},{"path":"https://gavinsimpson.github.io/gratia/reference/penalty.html","id":null,"dir":"Reference","previous_headings":"","what":"Extract and tidy penalty matrices — penalty","title":"Extract and tidy penalty matrices — penalty","text":"Extract tidy penalty matrices","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/penalty.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Extract and tidy penalty matrices — penalty","text":"","code":"penalty(object, ...) # Default S3 method penalty( object, rescale = FALSE, data, knots = NULL, constraints = FALSE, diagonalize = FALSE, ... ) # S3 method for class 'gam' penalty( object, select = NULL, smooth = deprecated(), rescale = FALSE, partial_match = FALSE, ... ) # S3 method for class 'mgcv.smooth' penalty(object, rescale = FALSE, ...) # S3 method for class 'tensor.smooth' penalty(object, margins = FALSE, ...) # S3 method for class 't2.smooth' penalty(object, margins = FALSE, ...) # S3 method for class 're.smooth.spec' penalty(object, data, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/penalty.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Extract and tidy penalty matrices — penalty","text":"object fitted GAM smooth. ... additional arguments passed methods. rescale logical; default, mgcv scale penalty matrix better performance mgcv::gamm(). rescale TRUE, scaling undone put penalty matrix back original scale. data data frame; data frame values terms mentioned smooth specification. knots list data frame named components containing knots locations. Names must match covariates basis required. See mgcv::smoothCon(). constraints logical; identifiability constraints applied smooth basis. See argument absorb.cons mgcv::smoothCon(). diagonalize logical; TRUE, reparameterises smooth associated penalty identity matrix. effect turning last diagonal elements penalty zero, highlights penalty null space. select character, logical, numeric; smooths extract penalties . NULL, default, penalties model smooths drawn. Numeric select indexes smooths order specified formula stored object. Character select matches labels smooths shown example output summary(object). Logical select operates per numeric select order smooths stored. smooth Use select instead. partial_match logical; smooths selected partial matches select? TRUE, select can single string match . margins logical; extract penalty matrices tensor product marginal smooths tensor product?","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/penalty.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Extract and tidy penalty matrices — penalty","text":"'tibble' (data frame) class penalty_df inheriting tbl_df, following components: .smooth - character; label mgcv uses refer smooth, .type - character; type smooth, .penalty - character; label specific penalty. smooths multiple penalty matrices, penalty component identifies particular penalty matrix uses labelling mgcv uses internally, .row - character; label form fn n integer nth basis function, referencing columns penalty matrix, .col - character; label form fn n integer nth basis function, referencing columns penalty matrix, .value - double; value penalty matrix combination row col,","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/penalty.html","id":"note","dir":"Reference","previous_headings":"","what":"Note","title":"Extract and tidy penalty matrices — penalty","text":"print() method uses base::zapsmall() turn small numbers 0s display purposes ; underlying values penalty matrix matrices changed. smooths subject eigendecomposition (e.g. default thin plate regression splines, bs = \"tp\"), signs eigenvectors defined can expect differences across systems penalties smooths system-, OS-, CPU architecture- specific.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/penalty.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Extract and tidy penalty matrices — penalty","text":"Gavin L. Simpson","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/penalty.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Extract and tidy penalty matrices — penalty","text":"","code":"load_mgcv() dat <- data_sim(\"eg4\", n = 400, seed = 42) m <- gam( y ~ s(x0, bs = \"cr\") + s(x1, bs = \"cr\") + s(x2, by = fac, bs = \"cr\"), data = dat, method = \"REML\" ) # penalties for all smooths penalty(m) #> # A tibble: 405 x 6 #> .smooth .type .penalty .row .col .value #> #> 1 s(x0) CRS s(x0) F1 F1 0.783 #> 2 s(x0) CRS s(x0) F1 F2 -0.635 #> 3 s(x0) CRS s(x0) F1 F3 0.265 #> 4 s(x0) CRS s(x0) F1 F4 -0.0203 #> 5 s(x0) CRS s(x0) F1 F5 0.0441 #> 6 s(x0) CRS s(x0) F1 F6 0.0378 #> 7 s(x0) CRS s(x0) F1 F7 0.0482 #> 8 s(x0) CRS s(x0) F1 F8 0.0216 #> 9 s(x0) CRS s(x0) F1 F9 0.0247 #> 10 s(x0) CRS s(x0) F2 F1 -0.635 #> # i 395 more rows # for a specific smooth penalty(m, select = \"s(x2):fac1\") #> # A tibble: 81 x 6 #> .smooth .type .penalty .row .col .value #> #> 1 s(x2):fac1 CRS s(x2):fac1 F1 F1 1.66 #> 2 s(x2):fac1 CRS s(x2):fac1 F1 F2 -0.755 #> 3 s(x2):fac1 CRS s(x2):fac1 F1 F3 0.430 #> 4 s(x2):fac1 CRS s(x2):fac1 F1 F4 0.0846 #> 5 s(x2):fac1 CRS s(x2):fac1 F1 F5 0.192 #> 6 s(x2):fac1 CRS s(x2):fac1 F1 F6 0.152 #> 7 s(x2):fac1 CRS s(x2):fac1 F1 F7 0.188 #> 8 s(x2):fac1 CRS s(x2):fac1 F1 F8 0.164 #> 9 s(x2):fac1 CRS s(x2):fac1 F1 F9 0.0597 #> 10 s(x2):fac1 CRS s(x2):fac1 F2 F1 -0.755 #> # i 71 more rows"},{"path":"https://gavinsimpson.github.io/gratia/reference/post_draws.html","id":null,"dir":"Reference","previous_headings":"","what":"Low-level Functions to generate draws from the posterior distribution of model coefficients — post_draws","title":"Low-level Functions to generate draws from the posterior distribution of model coefficients — post_draws","text":"Low-level Functions generate draws posterior distribution model coefficients Generate posterior draws fitted model","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/post_draws.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Low-level Functions to generate draws from the posterior distribution of model coefficients — post_draws","text":"","code":"post_draws(model, ...) # Default S3 method post_draws( model, n, method = c(\"gaussian\", \"mh\", \"inla\", \"user\"), mu = NULL, sigma = NULL, n_cores = 1L, burnin = 1000, thin = 1, t_df = 40, rw_scale = 0.25, index = NULL, frequentist = FALSE, unconditional = FALSE, parametrized = TRUE, mvn_method = c(\"mvnfast\", \"mgcv\"), draws = NULL, seed = NULL, ... ) generate_draws(model, ...) # S3 method for class 'gam' generate_draws( model, n, method = c(\"gaussian\", \"mh\", \"inla\"), mu = NULL, sigma = NULL, n_cores = 1L, burnin = 1000, thin = 1, t_df = 40, rw_scale = 0.25, index = NULL, frequentist = FALSE, unconditional = FALSE, mvn_method = c(\"mvnfast\", \"mgcv\"), seed = NULL, ... )"},{"path":"https://gavinsimpson.github.io/gratia/reference/post_draws.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Low-level Functions to generate draws from the posterior distribution of model coefficients — post_draws","text":"model fitted R model. Currently models fitted mgcv::gam() mgcv::bam(), return object inherits objects supported. , \"inherits\" used loose fashion; models fitted scam::scam() support even though models strictly inherit class \"gam\" far inherits() concerned. ... arguments passed methods. n numeric; number posterior draws take. method character; algorithm use sample posterior. Currently implemented methods : \"gaussian\" \"mh\". \"gaussian\" calls gaussian_draws() uses Gaussian approximation posterior distribution. \"mh\" uses simple Metropolis Hasting sampler alternates static proposals based Gaussian approximation posterior, random walk proposals. Note, setting t_df low value result heavier-tailed statistic proposals. See mgcv::gam.mh() details. mu numeric; user-supplied mean vector (vector model coefficients). Currently ignored. sigma matrix; user-supplied covariance matrix mu. Currently ignored. n_cores integer; number CPU cores use generating multivariate normal distributed random values. used mvn_method = \"mvnfast\" method = \"gaussian\". burnin numeric; length initial burn period discard. See mgcv::gam.mh(). thin numeric; retain thin samples. See mgcv::gam.mh(). t_df numeric; degrees freedom static multivariate t proposal. See mgcv::gam.mh(). rw_scale numeric; factor scale posterior covariance matrix generating random walk proposals. See mgcv::gam.mh(). index numeric; vector indices coefficients use. Can used subset mean vector covariance matrix extracted model. frequentist logical; TRUE, frequentist covariance matrix parameter estimates used. FALSE, Bayesian posterior covariance matrix parameters used. See mgcv::vcov.gam(). unconditional logical; TRUE Bayesian smoothing parameter uncertainty corrected covariance matrix used, available model. See mgcv::vcov.gam(). parametrized logical; use parametrized coefficients covariance matrix, respect linear inequality constraints model. scam::scam() model fits. mvn_method character; one \"mvnfast\" \"mgcv\". default uses mvnfast::rmvn(), can considerably faster generate large numbers MVN random values mgcv::rmvn(), might work marginal fits, covariance matrix close singular. draws matrix; user supplied posterior draws used method = \"user\". seed numeric; random seed use. NULL, random seed generated without affecting current state R's RNG.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/post_link_funs.html","id":null,"dir":"Reference","previous_headings":"","what":"A list of transformation functions named for LSS parameters in a GAMLSS — post_link_funs","title":"A list of transformation functions named for LSS parameters in a GAMLSS — post_link_funs","text":"list transformation functions named LSS parameters GAMLSS","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/post_link_funs.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"A list of transformation functions named for LSS parameters in a GAMLSS — post_link_funs","text":"","code":"post_link_funs( location = identity_fun, scale = identity_fun, shape = identity_fun, skewness = identity_fun, kurtosis = identity_fun, power = identity_fun, pi = identity_fun )"},{"path":"https://gavinsimpson.github.io/gratia/reference/posterior_samples.html","id":null,"dir":"Reference","previous_headings":"","what":"Draw samples from the posterior distribution of an estimated model — posterior_samples","title":"Draw samples from the posterior distribution of an estimated model — posterior_samples","text":"Draw samples posterior distribution estimated model","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/posterior_samples.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Draw samples from the posterior distribution of an estimated model — posterior_samples","text":"","code":"posterior_samples(model, ...) # S3 method for class 'gam' posterior_samples( model, n = 1, data = newdata, seed = NULL, method = c(\"gaussian\", \"mh\", \"inla\", \"user\"), n_cores = 1, burnin = 1000, thin = 1, t_df = 40, rw_scale = 0.25, freq = FALSE, unconditional = FALSE, weights = NULL, draws = NULL, mvn_method = c(\"mvnfast\", \"mgcv\"), ..., newdata = NULL, ncores = NULL )"},{"path":"https://gavinsimpson.github.io/gratia/reference/posterior_samples.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Draw samples from the posterior distribution of an estimated model — posterior_samples","text":"model fitted model supported types ... arguments passed methods. fitted_samples(), passed mgcv::predict.gam(). posterior_samples() passed fitted_samples(). predicted_samples() passed relevant simulate() method. n numeric; number posterior samples return. data data frame; new observations posterior draws model evaluated. supplied, data used fit model used data, available model. seed numeric; random seed simulations. method character; method used draw samples posterior distribution. \"gaussian\" uses Gaussian (Laplace) approximation posterior. \"mh\" uses Metropolis Hastings sampler alternates t proposals proposals based shrunken version posterior covariance matrix. \"inla\" uses variant Integrated Nested Laplace Approximation due Wood (2019), (currently implemented). \"user\" allows user-supplied posterior draws (currently implemented). n_cores number cores generating random variables multivariate normal distribution. Passed mvnfast::rmvn(). Parallelization take place OpenMP supported (appears work Windows current R). burnin numeric; number samples discard burnin draws. used method = \"mh\". thin numeric; number samples skip taking n draws. Results thin * n draws posterior taken. used method = \"mh\". t_df numeric; degrees freedom t distribution proposals. used method = \"mh\". rw_scale numeric; Factor scale posterior covariance matrix generating random walk proposals. Negative non finite skip random walk step. used method = \"mh\". freq logical; TRUE use frequentist covariance matrix parameter estimators, FALSE use Bayesian posterior covariance matrix parameters. unconditional logical; TRUE (freq == FALSE) Bayesian smoothing parameter uncertainty corrected covariance matrix used, available. weights numeric; vector prior weights. data null defaults object[[\"prior.weights\"]], otherwise vector ones. draws matrix; user supplied posterior draws used method = \"user\". mvn_method character; one \"mvnfast\" \"mgcv\". default uses mvnfast::rmvn(), can considerably faster generate large numbers MVN random values mgcv::rmvn(), might work marginal fits, covariance matrix close singular. newdata Deprecated: use data instead. ncores Deprecated; use n_cores instead. number cores generating random variables multivariate normal distribution. Passed mvnfast::rmvn(). Parallelization take place OpenMP supported (appears work Windows current R).","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/posterior_samples.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Draw samples from the posterior distribution of an estimated model — posterior_samples","text":"tibble (data frame) 3 columns containing posterior predicted values long format. columns row (integer) row data posterior draw relates , draw (integer) index, range 1:n, indicating draw row relates , response (numeric) predicted response indicated row data.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/posterior_samples.html","id":"note","dir":"Reference","previous_headings":"","what":"Note","title":"Draw samples from the posterior distribution of an estimated model — posterior_samples","text":"Models offset terms supplied via offset argument mgcv::gam() etc. ignored mgcv::predict.gam(). , kind offset term also ignored posterior_samples(). Offset terms included model formula supplied mgcv::gam() etc ignored posterior samples produced reflect offset term values. side effect requiring new data values provided posterior_samples() via data argument must include offset variable.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/posterior_samples.html","id":"references","dir":"Reference","previous_headings":"","what":"References","title":"Draw samples from the posterior distribution of an estimated model — posterior_samples","text":"Wood, S.N., (2020). Simplified integrated nested Laplace approximation. Biometrika 107, 223–230. doi:10.1093/biomet/asz044","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/posterior_samples.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Draw samples from the posterior distribution of an estimated model — posterior_samples","text":"Gavin L. Simpson","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/predicted_samples.html","id":null,"dir":"Reference","previous_headings":"","what":"Draw new response values from the conditional distribution of the response — predicted_samples","title":"Draw new response values from the conditional distribution of the response — predicted_samples","text":"Predicted values response (new response data) drawn fitted model, created via simulate() (e.g. simulate.gam()) returned tidy, long, format. predicted values include uncertainty estimated model; simply draws conditional distribution response.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/predicted_samples.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Draw new response values from the conditional distribution of the response — predicted_samples","text":"","code":"predicted_samples(model, ...) # S3 method for class 'gam' predicted_samples( model, n = 1, data = newdata, seed = NULL, weights = NULL, ..., newdata = NULL )"},{"path":"https://gavinsimpson.github.io/gratia/reference/predicted_samples.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Draw new response values from the conditional distribution of the response — predicted_samples","text":"model fitted model supported types ... arguments passed methods. fitted_samples(), passed mgcv::predict.gam(). posterior_samples() passed fitted_samples(). predicted_samples() passed relevant simulate() method. n numeric; number posterior samples return. data data frame; new observations posterior draws model evaluated. supplied, data used fit model used data, available model. seed numeric; random seed simulations. weights numeric; vector prior weights. data null defaults object[[\"prior.weights\"]], otherwise vector ones. newdata Deprecated: use data instead.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/predicted_samples.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Draw new response values from the conditional distribution of the response — predicted_samples","text":"tibble (data frame) 3 columns containing posterior predicted values long format. columns row (integer) row data posterior draw relates , draw (integer) index, range 1:n, indicating draw row relates , response (numeric) predicted response indicated row data.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/predicted_samples.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Draw new response values from the conditional distribution of the response — predicted_samples","text":"Gavin L. Simpson","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/predicted_samples.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Draw new response values from the conditional distribution of the response — predicted_samples","text":"","code":"load_mgcv() dat <- data_sim(\"eg1\", n = 1000, dist = \"normal\", scale = 2, seed = 2) m <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = dat, method = \"REML\") predicted_samples(m, n = 5, seed = 42) #> # A tibble: 5,000 x 3 #> .row .draw .response #> #> 1 1 1 8.93 #> 2 2 1 4.23 #> 3 3 1 7.71 #> 4 4 1 8.51 #> 5 5 1 10.1 #> 6 6 1 8.20 #> 7 7 1 8.95 #> 8 8 1 7.20 #> 9 9 1 18.1 #> 10 10 1 12.7 #> # i 4,990 more rows ## Can pass arguments to predict.gam() newd <- data.frame( x0 = runif(10), x1 = runif(10), x2 = runif(10), x3 = runif(10) ) ## Exclude s(x2) predicted_samples(m, n = 5, newd, exclude = \"s(x2)\", seed = 25) #> # A tibble: 50 x 3 #> .row .draw .response #> #> 1 1 1 9.42 #> 2 2 1 6.97 #> 3 3 1 8.10 #> 4 4 1 9.95 #> 5 5 1 6.75 #> 6 6 1 10.3 #> 7 7 1 10.8 #> 8 8 1 10.5 #> 9 9 1 8.43 #> 10 10 1 12.2 #> # i 40 more rows ## Exclude s(x1) predicted_samples(m, n = 5, newd, exclude = \"s(x1)\", seed = 25) #> # A tibble: 50 x 3 #> .row .draw .response #> #> 1 1 1 6.05 #> 2 2 1 5.28 #> 3 3 1 5.96 #> 4 4 1 13.7 #> 5 5 1 4.36 #> 6 6 1 5.11 #> 7 7 1 12.5 #> 8 8 1 5.66 #> 9 9 1 12.6 #> 10 10 1 8.38 #> # i 40 more rows ## Select which terms --- result should be the same as previous ## but note that we have to include any parametric terms, including the ## constant term predicted_samples(m, n = 5, newd, seed = 25, terms = c(\"Intercept\", \"s(x0)\", \"s(x2)\", \"s(x3)\") ) #> # A tibble: 50 x 3 #> .row .draw .response #> #> 1 1 1 -1.94 #> 2 2 1 -2.71 #> 3 3 1 -2.03 #> 4 4 1 5.73 #> 5 5 1 -3.63 #> 6 6 1 -2.87 #> 7 7 1 4.48 #> 8 8 1 -2.33 #> 9 9 1 4.65 #> 10 10 1 0.395 #> # i 40 more rows"},{"path":"https://gavinsimpson.github.io/gratia/reference/qq_plot.html","id":null,"dir":"Reference","previous_headings":"","what":"Quantile-quantile plot of model residuals — qq_plot","title":"Quantile-quantile plot of model residuals — qq_plot","text":"Quantile-quantile plots (QQ-plots) GAMs using reference quantiles Augustin et al (2012).","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/qq_plot.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Quantile-quantile plot of model residuals — qq_plot","text":"","code":"qq_plot(model, ...) # Default S3 method qq_plot(model, ...) # S3 method for class 'gam' qq_plot( model, method = c(\"uniform\", \"simulate\", \"normal\", \"direct\"), type = c(\"deviance\", \"response\", \"pearson\"), n_uniform = 10, n_simulate = 50, seed = NULL, level = 0.9, ylab = NULL, xlab = NULL, title = NULL, subtitle = NULL, caption = NULL, ci_col = \"black\", ci_alpha = 0.2, point_col = \"black\", point_alpha = 1, line_col = \"red\", ... ) # S3 method for class 'glm' qq_plot(model, ...) # S3 method for class 'lm' qq_plot(model, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/qq_plot.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Quantile-quantile plot of model residuals — qq_plot","text":"model fitted model. Currently models inheriting class \"gam\", well classes \"glm\" \"lm\" calls stats::glm stats::lm supported. ... arguments passed ot methods. method character; method used generate theoretical quantiles. default \"uniform\", generates reference quantiles using random draws uniform distribution inverse cummulative distribution function (CDF) fitted values. reference quantiles averaged n_uniform draws. \"simulate\" generates reference quantiles simulating new response data model observed values covariates, residualised generate reference quantiles, using n_simulate simulated data sets. \"normal\" generates reference quantiles using standard normal distribution. \"uniform\" computationally efficient, \"simulate\" allows reference bands drawn QQ-plot. \"normal\" avoided used fall back random number generator (\"simulate\") inverse CDF available family used model fitting (`\"uniform\"“). Note method = \"direct\" deprecated favour method = \"uniform\". type character; type residuals use. \"deviance\", \"response\", \"pearson\" residuals allowed. n_uniform numeric; number times randomize uniform quantiles direct computation method (method = \"uniform\"). n_simulate numeric; number data sets simulate estimated model using simulation method (method = \"simulate\"). seed numeric; random number seed use method = \"simulate\" method = \"uniform\". level numeric; coverage level reference intervals. Must strictly 0 < level < 1. used method = \"simulate\". ylab character expression; label y axis. supplied, suitable label generated. xlab character expression; label y axis. supplied, suitable label generated. title character expression; title plot. See ggplot2::labs(). May vector, one per penalty. subtitle character expression; subtitle plot. See ggplot2::labs(). May vector, one per penalty. caption character expression; plot caption. See ggplot2::labs(). May vector, one per penalty. ci_col fill colour reference interval method = \"simulate\". ci_alpha alpha transparency reference interval method = \"simulate\". point_col colour points QQ plot. point_alpha alpha transparency points QQ plot. line_col colour used draw reference line.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/qq_plot.html","id":"note","dir":"Reference","previous_headings":"","what":"Note","title":"Quantile-quantile plot of model residuals — qq_plot","text":"wording used mgcv::qq.gam() uses direct reference simulated residuals method (method = \"simulated\"). avoid confusion, method = \"direct\" deprecated favour method = \"uniform\".","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/qq_plot.html","id":"references","dir":"Reference","previous_headings":"","what":"References","title":"Quantile-quantile plot of model residuals — qq_plot","text":"underlying methodology used method \"simulate\" \"uniform\" described Augustin et al (2012): Augustin, N.H., Sauleau, E.-., Wood, S.N., (2012) quantile quantile plots generalized linear models. Computational Statatistics Data Analysis 56, 2404-2409 doi:10.1016/j.csda.2012.01.026 .","code":""},{"path":[]},{"path":"https://gavinsimpson.github.io/gratia/reference/qq_plot.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Quantile-quantile plot of model residuals — qq_plot","text":"","code":"load_mgcv() ## simulate binomial data... dat <- data_sim(\"eg1\", n = 200, dist = \"binary\", scale = .33, seed = 0) p <- binomial()$linkinv(dat$f) # binomial p n <- sample(c(1, 3), 200, replace = TRUE) # binomial n dat <- transform(dat, y = rbinom(n, n, p), n = n) m <- gam(y / n ~ s(x0) + s(x1) + s(x2) + s(x3), family = binomial, data = dat, weights = n, method = \"REML\" ) ## Q-Q plot; default using direct randomization of uniform quantiles qq_plot(m) ## Alternatively use simulate new data from the model, which ## allows construction of reference intervals for the Q-Q plot qq_plot(m, method = \"simulate\", seed = 42, point_col = \"steelblue\", point_alpha = 0.4 ) ## ... or use the usual normality assumption qq_plot(m, method = \"normal\")"},{"path":"https://gavinsimpson.github.io/gratia/reference/ref_level.html","id":null,"dir":"Reference","previous_headings":"","what":"Return the reference or specific level of a factor — ref_level","title":"Return the reference or specific level of a factor — ref_level","text":"Extracts reference specific level supplied factor, returning factor levels one supplied.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/ref_level.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Return the reference or specific level of a factor — ref_level","text":"","code":"ref_level(fct) level(fct, level)"},{"path":"https://gavinsimpson.github.io/gratia/reference/ref_level.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Return the reference or specific level of a factor — ref_level","text":"fct factor; factor reference specific level extracted. level character; specific level extract case level().","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/ref_level.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Return the reference or specific level of a factor — ref_level","text":"length 1 factor levels supplied factor fct.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/ref_level.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Return the reference or specific level of a factor — ref_level","text":"","code":"f <- factor(sample(letters[1:5], 100, replace = TRUE)) # the reference level ref_level(f) #> [1] a #> Levels: a b c d e # a specific level level(f, level = \"b\") #> [1] b #> Levels: a b c d e # note that the levels will always match the input factor identical(levels(f), levels(ref_level(f))) #> [1] TRUE identical(levels(f), levels(level(f, \"c\"))) #> [1] TRUE"},{"path":"https://gavinsimpson.github.io/gratia/reference/ref_sims.html","id":null,"dir":"Reference","previous_headings":"","what":"Reference simulation data — ref_sims","title":"Reference simulation data — ref_sims","text":"set reference objects testing data_sim().","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/ref_sims.html","id":"format","dir":"Reference","previous_headings":"","what":"Format","title":"Reference simulation data — ref_sims","text":"named list simulated data sets created data_sim().","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/reorder_fs_smooth_terms.html","id":null,"dir":"Reference","previous_headings":"","what":"Reorder random factor smooth terms to place factor last — reorder_fs_smooth_terms","title":"Reorder random factor smooth terms to place factor last — reorder_fs_smooth_terms","text":"Reorder random factor smooth terms place factor last","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/reorder_fs_smooth_terms.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Reorder random factor smooth terms to place factor last — reorder_fs_smooth_terms","text":"","code":"reorder_fs_smooth_terms(smooth)"},{"path":"https://gavinsimpson.github.io/gratia/reference/reorder_fs_smooth_terms.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Reorder random factor smooth terms to place factor last — reorder_fs_smooth_terms","text":"smooth mgcv smooth object","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/reorder_tensor_smooth_terms.html","id":null,"dir":"Reference","previous_headings":"","what":"Reorder tensor product terms for nicer plotting — reorder_tensor_smooth_terms","title":"Reorder tensor product terms for nicer plotting — reorder_tensor_smooth_terms","text":"tensor product smooth 3 terms contains 2d marginal smooth, get nicer output smooth_estimates() hence nicer plot draw.smooth_estimates() method reorder terms smooth vary terms 2d marginal first, terms vary slowly generate data evaluate smooth . results automatically generated data focuses (first one) 2d marginal smooth, end result smooth_estimates() shows 2d smooth changes terms involved smooth.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/reorder_tensor_smooth_terms.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Reorder tensor product terms for nicer plotting — reorder_tensor_smooth_terms","text":"","code":"reorder_tensor_smooth_terms(smooth)"},{"path":"https://gavinsimpson.github.io/gratia/reference/reorder_tensor_smooth_terms.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Reorder tensor product terms for nicer plotting — reorder_tensor_smooth_terms","text":"smooth mgcv smooth object","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/rep_first_factor_value.html","id":null,"dir":"Reference","previous_headings":"","what":"Repeat the first level of a factor n times — rep_first_factor_value","title":"Repeat the first level of a factor n times — rep_first_factor_value","text":"Function repeat first level factor n times return vector factor original levels intact","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/rep_first_factor_value.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Repeat the first level of a factor n times — rep_first_factor_value","text":"","code":"rep_first_factor_value(f, n)"},{"path":"https://gavinsimpson.github.io/gratia/reference/rep_first_factor_value.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Repeat the first level of a factor n times — rep_first_factor_value","text":"f factor n numeric; number times repeat first level f","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/rep_first_factor_value.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Repeat the first level of a factor n times — rep_first_factor_value","text":"factor length n levels f, whose elements first level f.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/residuals_hist_plot.html","id":null,"dir":"Reference","previous_headings":"","what":"Histogram of model residuals — residuals_hist_plot","title":"Histogram of model residuals — residuals_hist_plot","text":"Histogram model residuals","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/residuals_hist_plot.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Histogram of model residuals — residuals_hist_plot","text":"","code":"residuals_hist_plot( model, type = c(\"deviance\", \"pearson\", \"response\"), n_bins = c(\"sturges\", \"scott\", \"fd\"), ylab = NULL, xlab = NULL, title = NULL, subtitle = NULL, caption = NULL )"},{"path":"https://gavinsimpson.github.io/gratia/reference/residuals_hist_plot.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Histogram of model residuals — residuals_hist_plot","text":"model fitted model. Currently class \"gam\". type character; type residuals use. \"deviance\", \"response\", \"pearson\" residuals allowed. n_bins character numeric; either number bins string indicating calculate number bins. ylab character expression; label y axis. supplied, suitable label generated. xlab character expression; label y axis. supplied, suitable label generated. title character expression; title plot. See ggplot2::labs(). subtitle character expression; subtitle plot. See ggplot2::labs(). caption character expression; plot caption. See ggplot2::labs().","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/residuals_linpred_plot.html","id":null,"dir":"Reference","previous_headings":"","what":"Plot of residuals versus linear predictor values — residuals_linpred_plot","title":"Plot of residuals versus linear predictor values — residuals_linpred_plot","text":"Plot residuals versus linear predictor values","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/residuals_linpred_plot.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Plot of residuals versus linear predictor values — residuals_linpred_plot","text":"","code":"residuals_linpred_plot( model, type = c(\"deviance\", \"pearson\", \"response\"), ylab = NULL, xlab = NULL, title = NULL, subtitle = NULL, caption = NULL, point_col = \"black\", point_alpha = 1, line_col = \"red\" )"},{"path":"https://gavinsimpson.github.io/gratia/reference/residuals_linpred_plot.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Plot of residuals versus linear predictor values — residuals_linpred_plot","text":"model fitted model. Currently class \"gam\". type character; type residuals use. \"deviance\", \"response\", \"pearson\" residuals allowed. ylab character expression; label y axis. supplied, suitable label generated. xlab character expression; label y axis. supplied, suitable label generated. title character expression; title plot. See ggplot2::labs(). subtitle character expression; subtitle plot. See ggplot2::labs(). caption character expression; plot caption. See ggplot2::labs(). point_col colour used draw points plots. See graphics::par() section Color Specification. passed individual plotting functions, therefore affects points plots. point_alpha numeric; alpha transparency points plots. line_col colour specification 1:1 line.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/response_derivatives.html","id":null,"dir":"Reference","previous_headings":"","what":"Derivatives on the response scale from an estimated GAM — response_derivatives","title":"Derivatives on the response scale from an estimated GAM — response_derivatives","text":"Derivatives response scale estimated GAM","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/response_derivatives.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Derivatives on the response scale from an estimated GAM — response_derivatives","text":"","code":"response_derivatives(object, ...) # Default S3 method response_derivatives(object, ...) # S3 method for class 'gamm' response_derivatives(object, ...) # S3 method for class 'gam' response_derivatives( object, focal = NULL, data = NULL, order = 1L, type = c(\"forward\", \"backward\", \"central\"), scale = c(\"response\", \"linear_predictor\"), method = c(\"gaussian\", \"mh\", \"inla\", \"user\"), n = 100, eps = 1e-07, n_sim = 10000, level = 0.95, seed = NULL, mvn_method = c(\"mvnfast\", \"mgcv\"), ... )"},{"path":"https://gavinsimpson.github.io/gratia/reference/response_derivatives.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Derivatives on the response scale from an estimated GAM — response_derivatives","text":"object R object compute derivatives . ... arguments passed methods fitted_samples() focal character; name focal variable. response derivative response respect variable returned. variables involved model held constant values. can missing supplying data, case, focal variable identified one variable constant. data data frame containing values model covariates evaluate first derivatives smooths. supplied, one variable must held constant value. order numeric; order derivative. type character; type finite difference used. One \"forward\", \"backward\", \"central\". scale character; derivative estimated response linear predictor (link) scale? One \"response\" (default), \"linear predictor\". method character; method used draw samples posterior distribution. \"gaussian\" uses Gaussian (Laplace) approximation posterior. \"mh\" uses Metropolis Hastings sample alternates t proposals proposals based shrunken version posterior covariance matrix. \"inla\" uses variant Integrated Nested Laplace Approximation due Wood (2019), (currently implemented). \"user\" allows user-supplied posterior draws (currently implemented). n numeric; number points evaluate derivative (data supplied). eps numeric; finite difference. n_sim integer; number simulations used computing simultaneous intervals. level numeric; 0 < level < 1; coverage level credible interval. default 0.95 95% interval. seed numeric; random seed simulations. mvn_method character; one \"mvnfast\" \"mgcv\". default uses mvnfast::rmvn(), can considerably faster generate large numbers MVN random values mgcv::rmvn(), might work marginal fits, covariance matrix close singular.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/response_derivatives.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Derivatives on the response scale from an estimated GAM — response_derivatives","text":"tibble, currently following variables: .row: integer, indexing row data row output represents .focal: name variable partial derivative evaluated, .derivative: estimated partial derivative, .lower_ci: lower bound confidence simultaneous interval, .upper_ci: upper bound confidence simultaneous interval, additional columns containing covariate values derivative evaluated.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/response_derivatives.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Derivatives on the response scale from an estimated GAM — response_derivatives","text":"Gavin L. Simpson","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/response_derivatives.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Derivatives on the response scale from an estimated GAM — response_derivatives","text":"","code":"library(\"ggplot2\") library(\"patchwork\") load_mgcv() df <- data_sim(\"eg1\", dist = \"negbin\", scale = 0.25, seed = 42) # fit the GAM (note: for execution time reasons using bam()) m <- bam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = df, family = nb(), method = \"fREML\" ) # data slice through data along x2 - all other covariates will be set to # typical values (value closest to median) ds <- data_slice(m, x2 = evenly(x2, n = 100)) # fitted values along x2 fv <- fitted_values(m, data = ds) # response derivatives - ideally n_sim = >10000 y_d <- response_derivatives(m, data = ds, type = \"central\", focal = \"x2\", eps = 0.01, seed = 21, n_sim = 1000 ) # draw fitted values along x2 p1 <- fv |> ggplot(aes(x = x2, y = .fitted)) + geom_ribbon(aes(ymin = .lower_ci, ymax = .upper_ci, y = NULL), alpha = 0.2 ) + geom_line() + labs( title = \"Estimated count as a function of x2\", y = \"Estimated count\" ) # draw response derivatives p2 <- y_d |> ggplot(aes(x = x2, y = .derivative)) + geom_ribbon(aes(ymin = .lower_ci, ymax = .upper_ci), alpha = 0.2) + geom_line() + labs( title = \"Estimated 1st derivative of estimated count\", y = \"First derivative\" ) # draw both panels p1 + p2 + plot_layout(nrow = 2)"},{"path":"https://gavinsimpson.github.io/gratia/reference/rootogram.html","id":null,"dir":"Reference","previous_headings":"","what":"Rootograms to assess goodness of model fit — rootogram","title":"Rootograms to assess goodness of model fit — rootogram","text":"rootogram model diagnostic tool assesses goodness fit statistical model. observed values response compared expected fitted model. discrete, count responses, frequency count (0, 1, 2, etc) observed data expected conditional distribution response implied model compared. continuous variables, observed expected frequencies obtained grouping data bins. rootogram drawn using ggplot2::ggplot() graphics. design closely follows Kleiber & Zeileis (2016).","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/rootogram.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Rootograms to assess goodness of model fit — rootogram","text":"","code":"rootogram(object, ...) # S3 method for class 'gam' rootogram(object, max_count = NULL, breaks = \"Sturges\", ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/rootogram.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Rootograms to assess goodness of model fit — rootogram","text":"object R object ... arguments passed methods max_count integer; largest count consider breaks continuous responses, group response. Can anything acceptable breaks argument graphics::hist.default()","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/rootogram.html","id":"references","dir":"Reference","previous_headings":"","what":"References","title":"Rootograms to assess goodness of model fit — rootogram","text":"Kleiber, C., Zeileis, ., (2016) Visualizing Count Data Regressions Using Rootograms. . Stat. 70, 296–303. doi:10.1080/00031305.2016.1173590","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/rootogram.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Rootograms to assess goodness of model fit — rootogram","text":"","code":"load_mgcv() df <- data_sim(\"eg1\", n = 1000, dist = \"poisson\", scale = 0.1, seed = 6) # A poisson example m <- gam(y ~ s(x0, bs = \"cr\") + s(x1, bs = \"cr\") + s(x2, bs = \"cr\") + s(x3, bs = \"cr\"), family = poisson(), data = df, method = \"REML\") rg <- rootogram(m) rg #> # A tibble: 21 x 3 #> .bin .observed .fitted #> #> 1 0 113 116.640 #> 2 1 236 227.869 #> 3 2 230 239.168 #> 4 3 200 181.679 #> 5 4 94 113.432 #> 6 5 68 62.4881 #> 7 6 27 31.6795 #> 8 7 22 15.1323 #> 9 8 4 6.88637 #> 10 9 3 2.99628 #> # i 11 more rows draw(rg) # plot the rootogram # A Gaussian example df <- data_sim(\"eg1\", dist = \"normal\", seed = 2) m <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = df, method = \"REML\") draw(rootogram(m, breaks = \"FD\"), type = \"suspended\")"},{"path":"https://gavinsimpson.github.io/gratia/reference/seq_min_max_eps.html","id":null,"dir":"Reference","previous_headings":"","what":"Create a sequence of evenly-spaced values adjusted to accommodate a small adjustment — seq_min_max_eps","title":"Create a sequence of evenly-spaced values adjusted to accommodate a small adjustment — seq_min_max_eps","text":"Creates sequence n evenly-spaced values range min(x) – max(x), minimum maximum adjusted always contained within range x x may shifted forwards backwards amount related eps. particularly useful computing derivatives via finite differences without adjustment may predicting values outside range data hence conmstraints penalty.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/seq_min_max_eps.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Create a sequence of evenly-spaced values adjusted to accommodate a small adjustment — seq_min_max_eps","text":"","code":"seq_min_max_eps(x, n, order, type = c(\"forward\", \"backward\", \"central\"), eps)"},{"path":"https://gavinsimpson.github.io/gratia/reference/seq_min_max_eps.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Create a sequence of evenly-spaced values adjusted to accommodate a small adjustment — seq_min_max_eps","text":"x numeric; vector evenly-spaced values returned n numeric; number evenly-spaced values return order integer; order derivative. Either 1 2 first second order derivatives type character; type finite difference used. One \"forward\", \"backward\", \"central\" eps numeric; finite difference","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/seq_min_max_eps.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Create a sequence of evenly-spaced values adjusted to accommodate a small adjustment — seq_min_max_eps","text":"numeric vector length n.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/shift_values.html","id":null,"dir":"Reference","previous_headings":"","what":"Shift numeric values in a data frame by an amount eps — shift_values","title":"Shift numeric values in a data frame by an amount eps — shift_values","text":"Shift numeric values data frame amount eps","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/shift_values.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Shift numeric values in a data frame by an amount eps — shift_values","text":"","code":"shift_values(df, h, i, FUN = `+`, focal = NULL)"},{"path":"https://gavinsimpson.github.io/gratia/reference/shift_values.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Shift numeric values in a data frame by an amount eps — shift_values","text":"df data frame tibble. h numeric; amount shift values df . logical; vector indexing columns df included shift. FUN function; function applut shift. Typically + -. focal character; focal variable computing partial derivatives. allows shifting focal variable eps.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/simulate.html","id":null,"dir":"Reference","previous_headings":"","what":"Simulate from the posterior distribution of a GAM — simulate.gam","title":"Simulate from the posterior distribution of a GAM — simulate.gam","text":"Simulations posterior distribution fitted GAM model involve computing predicted values observation data simulated data required, generating random draws probability distribution used fitting model.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/simulate.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Simulate from the posterior distribution of a GAM — simulate.gam","text":"","code":"# S3 method for class 'gam' simulate( object, nsim = 1, seed = NULL, data = newdata, weights = NULL, ..., newdata = NULL ) # S3 method for class 'gamm' simulate( object, nsim = 1, seed = NULL, data = newdata, weights = NULL, ..., newdata = NULL ) # S3 method for class 'scam' simulate( object, nsim = 1, seed = NULL, data = newdata, weights = NULL, ..., newdata = NULL )"},{"path":"https://gavinsimpson.github.io/gratia/reference/simulate.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Simulate from the posterior distribution of a GAM — simulate.gam","text":"object fitted GAM, typically result call mgcv::gam` mgcv::gamm(). nsim numeric; number posterior simulations return. seed numeric; random seed simulations. data data frame; new observations posterior draws model evaluated. supplied, data used fit model used newdata, available object. weights numeric; vector prior weights. newdata null defaults object[[\"prior.weights\"]], otherwise vector ones. ... arguments passed methods. simulate.gam() simulate.scam() pass ... predict.gam(). can pass additional arguments terms, exclude, select model terms included predictions. may useful, example, excluding effects random effect terms. newdata Deprecated. Use data instead.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/simulate.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Simulate from the posterior distribution of a GAM — simulate.gam","text":"(Currently) matrix nsim columns.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/simulate.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Simulate from the posterior distribution of a GAM — simulate.gam","text":"simulate.gam() function, family component fitted model must contain, updateable contain, required random number generator. See mgcv::fix.family.rd().","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/simulate.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Simulate from the posterior distribution of a GAM — simulate.gam","text":"Gavin L. Simpson","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/simulate.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Simulate from the posterior distribution of a GAM — simulate.gam","text":"","code":"load_mgcv() dat <- data_sim(\"eg1\", n = 400, dist = \"normal\", scale = 2, seed = 2) m1 <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = dat, method = \"REML\") sims <- simulate(m1, nsim = 5, seed = 42) head(sims) #> [,1] [,2] [,3] [,4] [,5] #> [1,] 11.445470 11.374304 10.098681 7.264881 8.796630 #> [2,] 6.510912 5.909584 9.057362 7.698084 11.444781 #> [3,] 3.837995 3.230610 3.550240 3.759380 4.774581 #> [4,] 12.361830 11.209226 10.714215 11.861957 10.746417 #> [5,] 14.851461 12.911440 11.356984 15.783913 15.106270 #> [6,] 5.921276 4.158963 5.520856 7.973614 9.654888"},{"path":"https://gavinsimpson.github.io/gratia/reference/smallAges.html","id":null,"dir":"Reference","previous_headings":"","what":"Lead-210 age-depth measurements for Small Water — smallAges","title":"Lead-210 age-depth measurements for Small Water — smallAges","text":"dataset containing lead-210 based age depth measurements SMALL1 core Small Water.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/smallAges.html","id":"format","dir":"Reference","previous_headings":"","what":"Format","title":"Lead-210 age-depth measurements for Small Water — smallAges","text":"data frame 12 rows 7 variables.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/smallAges.html","id":"source","dir":"Reference","previous_headings":"","what":"Source","title":"Lead-210 age-depth measurements for Small Water — smallAges","text":"Simpson, G.L. (Unpublished data).","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/smallAges.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Lead-210 age-depth measurements for Small Water — smallAges","text":"variables follows: Depth Drymass Date Age Error SedAccRate SedPerCentChange","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_coef_indices.html","id":null,"dir":"Reference","previous_headings":"","what":"Indices of the parametric terms for a particular smooth — smooth_coef_indices","title":"Indices of the parametric terms for a particular smooth — smooth_coef_indices","text":"Returns vector indices parametric terms represent supplied smooth. Useful extracting model coefficients columns covariance matrix.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_coef_indices.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Indices of the parametric terms for a particular smooth — smooth_coef_indices","text":"","code":"smooth_coef_indices(smooth)"},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_coef_indices.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Indices of the parametric terms for a particular smooth — smooth_coef_indices","text":"smooth object inherits class mgcv.smooth","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_coef_indices.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Indices of the parametric terms for a particular smooth — smooth_coef_indices","text":"numeric vector indices.","code":""},{"path":[]},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_coef_indices.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Indices of the parametric terms for a particular smooth — smooth_coef_indices","text":"Gavin L. Simpson","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_coefs.html","id":null,"dir":"Reference","previous_headings":"","what":"Coefficients for a particular smooth — smooth_coefs","title":"Coefficients for a particular smooth — smooth_coefs","text":"Returns vector model coefficients parametric terms represent supplied smooth.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_coefs.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Coefficients for a particular smooth — smooth_coefs","text":"","code":"smooth_coefs(object, ...) # S3 method for class 'gam' smooth_coefs(object, select, term = deprecated(), ...) # S3 method for class 'bam' smooth_coefs(object, select, term = deprecated(), ...) # S3 method for class 'gamm' smooth_coefs(object, select, term = deprecated(), ...) # S3 method for class 'gamm4' smooth_coefs(object, select, term = deprecated(), ...) # S3 method for class 'list' smooth_coefs(object, select, term = deprecated(), ...) # S3 method for class 'mgcv.smooth' smooth_coefs(object, model, ...) # S3 method for class 'scam' smooth_coefs(object, select, term = deprecated(), ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_coefs.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Coefficients for a particular smooth — smooth_coefs","text":"object fitted GAM(M) object, , \"mgcv.smooth\" method, object inherits class mgcv.smooth. ... arguments passed methods. select character; label smooth whose coefficients returned. term Use select instead. model fitted GAM(M) object.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_coefs.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Coefficients for a particular smooth — smooth_coefs","text":"numeric vector model coefficients.","code":""},{"path":[]},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_coefs.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Coefficients for a particular smooth — smooth_coefs","text":"Gavin L. Simpson","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_coefs.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Coefficients for a particular smooth — smooth_coefs","text":"","code":"load_mgcv() df <- data_sim(\"eg1\", seed = 2) m <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = df, method = \"REML\") ## IGNORE_RDIFF_BEGIN smooth_coefs(m, select = \"s(x2)\") #> s(x2).1 s(x2).2 s(x2).3 s(x2).4 s(x2).5 s(x2).6 s(x2).7 s(x2).8 #> -6.533373 9.694277 2.194078 -1.967280 -2.374874 1.207638 -1.572586 9.269744 #> s(x2).9 #> 5.622738 ## IGNORE_RDIFF_END"},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_data.html","id":null,"dir":"Reference","previous_headings":"","what":"Generate regular data over the covariates of a smooth — smooth_data","title":"Generate regular data over the covariates of a smooth — smooth_data","text":"Generate regular data covariates smooth","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_data.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Generate regular data over the covariates of a smooth — smooth_data","text":"","code":"smooth_data( model, id, n = 100, n_2d = NULL, n_3d = NULL, n_4d = NULL, offset = NULL, include_all = FALSE, var_order = NULL )"},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_data.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Generate regular data over the covariates of a smooth — smooth_data","text":"model fitted model id number ID smooth within model process. n numeric; number new observations generate. n_2d numeric; number new observations generate second dimension 2D smooth. Currently ignored. n_3d numeric; number new observations generate third dimension 3D smooth. n_4d numeric; number new observations generate dimensions higher 2 (!) kD smooth (k >= 4). example, smooth 4D smooth, dimensions 3 4 get n_4d new observations. offset numeric; value model offset use. include_all logical; include covariates involved smooth? FALSE, covariates involved smooth included returned data frame. TRUE, representative value included covariates model actually used smooth. can useful want pass returned data frame mgcv::PredictMat(). var_order character; order terms smooth processed. useful tensor products least one 2d marginal smooth.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_data.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Generate regular data over the covariates of a smooth — smooth_data","text":"","code":"load_mgcv() df <- data_sim(\"eg1\", seed = 42) m <- bam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = df) # generate data over range of x1 for smooth s(x1) smooth_data(m, id = 2) #> # A tibble: 100 x 1 #> x1 #> #> 1 0.0004050 #> 2 0.01046 #> 3 0.02052 #> 4 0.03057 #> 5 0.04063 #> 6 0.05069 #> 7 0.06074 #> 8 0.07080 #> 9 0.08086 #> 10 0.09091 #> # i 90 more rows # generate data over range of x1 for smooth s(x1), with typical value for # other covariates in the model smooth_data(m, id = 2, include_all = TRUE) #> # A tibble: 100 x 4 #> x1 x0 x2 x3 #> #> 1 0.0004050 0.4883 0.4708 0.4879 #> 2 0.01046 0.4883 0.4708 0.4879 #> 3 0.02052 0.4883 0.4708 0.4879 #> 4 0.03057 0.4883 0.4708 0.4879 #> 5 0.04063 0.4883 0.4708 0.4879 #> 6 0.05069 0.4883 0.4708 0.4879 #> 7 0.06074 0.4883 0.4708 0.4879 #> 8 0.07080 0.4883 0.4708 0.4879 #> 9 0.08086 0.4883 0.4708 0.4879 #> 10 0.09091 0.4883 0.4708 0.4879 #> # i 90 more rows"},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_dim.html","id":null,"dir":"Reference","previous_headings":"","what":"Dimension of a smooth — smooth_dim","title":"Dimension of a smooth — smooth_dim","text":"Extracts dimension estimated smooth.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_dim.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Dimension of a smooth — smooth_dim","text":"","code":"smooth_dim(object) # S3 method for class 'gam' smooth_dim(object) # S3 method for class 'gamm' smooth_dim(object) # S3 method for class 'mgcv.smooth' smooth_dim(object)"},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_dim.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Dimension of a smooth — smooth_dim","text":"object R object. See Details list supported objects.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_dim.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Dimension of a smooth — smooth_dim","text":"numeric vector dimensions smooth.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_dim.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Dimension of a smooth — smooth_dim","text":"generic function methods objects class \"gam\", \"gamm\", \"mgcv.smooth\".","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_dim.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Dimension of a smooth — smooth_dim","text":"Gavin L. Simpson","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_estimates.html","id":null,"dir":"Reference","previous_headings":"","what":"Evaluate smooths at covariate values — smooth_estimates","title":"Evaluate smooths at covariate values — smooth_estimates","text":"Evaluate smooth grid evenly spaced value range covariate associated smooth. Alternatively, set points smooth evaluated can supplied. smooth_estimates() new implementation evaluate_smooth(), replaces function, removed package.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_estimates.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Evaluate smooths at covariate values — smooth_estimates","text":"","code":"smooth_estimates(object, ...) # S3 method for class 'gam' smooth_estimates( object, select = NULL, smooth = deprecated(), n = 100, n_3d = 16, n_4d = 4, data = NULL, unconditional = FALSE, overall_uncertainty = TRUE, dist = NULL, unnest = TRUE, partial_match = FALSE, ... )"},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_estimates.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Evaluate smooths at covariate values — smooth_estimates","text":"object object class \"gam\" \"gamm\". ... arguments passed methods. select character; select smooth's posterior draw . default (NULL) means posteriors smooths model wil sampled . supplied, character vector requested terms. smooth Use select instead. n numeric; number points range covariate evaluate smooth. n_3d, n_4d numeric; number points range last covariate 3D 4D smooth. default NULL achieves standard behaviour using n points range covariate, resulting n^d evaluation points, d dimension smooth. d > 2 can result many evaluation points slow performance. smooths d > 4, value n_4d used dimensions > 4, unless NULL, case default behaviour (using n dimensions) observed. data data frame covariate values evaluate smooth. unconditional logical; confidence intervals include uncertainty due smoothness selection? TRUE, corrected Bayesian covariance matrix used. overall_uncertainty logical; uncertainty model constant term included standard error evaluate values smooth? dist numeric; greater 0, used determine location far data plotted plotting 2-D smooths. data scaled unit square deciding exclude, dist distance within unit square. See mgcv::exclude..far() details. unnest logical; unnest smooth objects? partial_match logical; case character select, select match partially smooths? partial_match = TRUE, select must single string, character vector length 1.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_estimates.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Evaluate smooths at covariate values — smooth_estimates","text":"data frame (tibble), class \"smooth_estimates\".","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_estimates.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Evaluate smooths at covariate values — smooth_estimates","text":"","code":"load_mgcv() dat <- data_sim(\"eg1\", n = 400, dist = \"normal\", scale = 2, seed = 2) m1 <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = dat, method = \"REML\") ## evaluate all smooths smooth_estimates(m1) #> # A tibble: 400 x 9 #> .smooth .type .by .estimate .se x0 x1 x2 x3 #> #> 1 s(x0) TPRS NA -0.966542 0.316118 0.00710904 NA NA NA #> 2 s(x0) TPRS NA -0.925391 0.297170 0.0171157 NA NA NA #> 3 s(x0) TPRS NA -0.884233 0.279256 0.0271224 NA NA NA #> 4 s(x0) TPRS NA -0.843050 0.262594 0.0371291 NA NA NA #> 5 s(x0) TPRS NA -0.801824 0.247376 0.0471358 NA NA NA #> 6 s(x0) TPRS NA -0.760536 0.233728 0.0571425 NA NA NA #> 7 s(x0) TPRS NA -0.719175 0.221701 0.0671492 NA NA NA #> 8 s(x0) TPRS NA -0.677736 0.211261 0.0771559 NA NA NA #> 9 s(x0) TPRS NA -0.636220 0.202303 0.0871626 NA NA NA #> 10 s(x0) TPRS NA -0.594641 0.194685 0.0971693 NA NA NA #> # i 390 more rows ## or selected smooths smooth_estimates(m1, select = c(\"s(x0)\", \"s(x1)\")) #> # A tibble: 200 x 7 #> .smooth .type .by .estimate .se x0 x1 #> #> 1 s(x0) TPRS NA -0.966542 0.316118 0.00710904 NA #> 2 s(x0) TPRS NA -0.925391 0.297170 0.0171157 NA #> 3 s(x0) TPRS NA -0.884233 0.279256 0.0271224 NA #> 4 s(x0) TPRS NA -0.843050 0.262594 0.0371291 NA #> 5 s(x0) TPRS NA -0.801824 0.247376 0.0471358 NA #> 6 s(x0) TPRS NA -0.760536 0.233728 0.0571425 NA #> 7 s(x0) TPRS NA -0.719175 0.221701 0.0671492 NA #> 8 s(x0) TPRS NA -0.677736 0.211261 0.0771559 NA #> 9 s(x0) TPRS NA -0.636220 0.202303 0.0871626 NA #> 10 s(x0) TPRS NA -0.594641 0.194685 0.0971693 NA #> # i 190 more rows"},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_label.html","id":null,"dir":"Reference","previous_headings":"","what":"Extract the label for a smooth used by 'mgcv' — smooth_label","title":"Extract the label for a smooth used by 'mgcv' — smooth_label","text":"label 'mgcv' uses smooths useful many contexts, including selecting smooths labelling plots. smooth_label() extracts label 'mgcv' smooth object, .e. object inherits class \"mgcv.smooth\". typically found $smooth component GAM fitted mgcv::gam() mgcv::bam(), related functions.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_label.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Extract the label for a smooth used by 'mgcv' — smooth_label","text":"","code":"smooth_label(object, ...) # S3 method for class 'gam' smooth_label(object, id, ...) # S3 method for class 'mgcv.smooth' smooth_label(object, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_label.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Extract the label for a smooth used by 'mgcv' — smooth_label","text":"object R object. Currently, methods class \"gam\" mgcv smooth objects inheriting class \"mgcv.smooth\" supported. ... arguments passed methods. id numeric; indices smooths whose labels extracted. missing, labels smooths model returned.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_label.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Extract the label for a smooth used by 'mgcv' — smooth_label","text":"character vector.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_label.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Extract the label for a smooth used by 'mgcv' — smooth_label","text":"","code":"load_mgcv() df <- data_sim(\"gwf2\", n = 100) m <- gam(y ~ s(x), data = df, method = \"REML\") # extract the smooth sm <- get_smooths_by_id(m, id = 1)[[1]] # extract the label smooth_label(sm) #> [1] \"s(x)\" # or directly on the fitted GAM smooth_label(m$smooth[[1]]) #> [1] \"s(x)\" # or extract labels by idex/position smooth_label(m, id = 1) #> [1] \"s(x)\""},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_samples.html","id":null,"dir":"Reference","previous_headings":"","what":"Posterior draws for individual smooths — smooth_samples","title":"Posterior draws for individual smooths — smooth_samples","text":"Returns draws posterior distributions smooth functions GAM. Useful, example, visualising uncertainty individual estimated functions.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_samples.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Posterior draws for individual smooths — smooth_samples","text":"","code":"smooth_samples(model, ...) # S3 method for class 'gam' smooth_samples( model, select = NULL, term = deprecated(), n = 1, data = newdata, method = c(\"gaussian\", \"mh\", \"inla\", \"user\"), seed = NULL, freq = FALSE, unconditional = FALSE, n_cores = 1L, n_vals = 200, burnin = 1000, thin = 1, t_df = 40, rw_scale = 0.25, rng_per_smooth = FALSE, draws = NULL, partial_match = NULL, mvn_method = c(\"mvnfast\", \"mgcv\"), ..., newdata = NULL, ncores = NULL )"},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_samples.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Posterior draws for individual smooths — smooth_samples","text":"model fitted model supported types ... arguments passed methods. fitted_samples(), passed mgcv::predict.gam(). posterior_samples() passed fitted_samples(). predicted_samples() passed relevant simulate() method. select character; select smooth's posterior draw . default (NULL) means posteriors smooths model wil sampled . supplied, character vector requested terms. term Use select instead. n numeric; number posterior samples return. data data frame; new observations posterior draws model evaluated. supplied, data used fit model used data, available model. method character; method used draw samples posterior distribution. \"gaussian\" uses Gaussian (Laplace) approximation posterior. \"mh\" uses Metropolis Hastings sampler alternates t proposals proposals based shrunken version posterior covariance matrix. \"inla\" uses variant Integrated Nested Laplace Approximation due Wood (2019), (currently implemented). \"user\" allows user-supplied posterior draws (currently implemented). seed numeric; random seed simulations. freq logical; TRUE use frequentist covariance matrix parameter estimators, FALSE use Bayesian posterior covariance matrix parameters. unconditional logical; TRUE (freq == FALSE) Bayesian smoothing parameter uncertainty corrected covariance matrix used, available. n_cores number cores generating random variables multivariate normal distribution. Passed mvnfast::rmvn(). Parallelization take place OpenMP supported (appears work Windows current R). n_vals numeric; many locations evaluate smooth data supplied burnin numeric; number samples discard burnin draws. used method = \"mh\". thin numeric; number samples skip taking n draws. Results thin * n draws posterior taken. used method = \"mh\". t_df numeric; degrees freedom t distribution proposals. used method = \"mh\". rw_scale numeric; Factor scale posterior covariance matrix generating random walk proposals. Negative non finite skip random walk step. used method = \"mh\". rng_per_smooth logical; TRUE, behaviour gratia version 0.8.1 earlier used, whereby separate call random number generator (RNG) performed smooth. FALSE, single call RNG performed model parameters draws matrix; user supplied posterior draws used method = \"user\". partial_match logical; smooths selected partial matches select? TRUE, select can single string match . mvn_method character; one \"mvnfast\" \"mgcv\". default uses mvnfast::rmvn(), can considerably faster generate large numbers MVN random values mgcv::rmvn(), might work marginal fits, covariance matrix close singular. newdata Deprecated: use data instead. ncores Deprecated; use n_cores instead. number cores generating random variables multivariate normal distribution. Passed mvnfast::rmvn(). Parallelization take place OpenMP supported (appears work Windows current R).","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_samples.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Posterior draws for individual smooths — smooth_samples","text":"tibble additional classes \"smooth_samples\" `\"posterior_samples\". \"gam\" method, columns currently returned (order) : .smooth; character vector. Indicates smooth function particular draw, .term; character vector. Similar smooth, contain full label smooth, differentiate factor-smooths example. .; character vector. smooth involves term, variable named , NA_character_ otherwise. .row; integer. vector values seq_len(n_vals), repeated n > 1L. Indexes row data particular draw. .draw; integer. vector integer values indexing particular posterior draw row belongs . .value; numeric. value smooth function posterior draw covariate combination. xxx; numeric. series one columns containing data required smooth, named per variables involved respective smooth. Additional columns present case factor smooths, contain level factor named by_variable particular posterior draw.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_samples.html","id":"warning","dir":"Reference","previous_headings":"","what":"Warning","title":"Posterior draws for individual smooths — smooth_samples","text":"set variables returned order tibble subject change future versions. rely position.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_samples.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Posterior draws for individual smooths — smooth_samples","text":"Gavin L. Simpson","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_samples.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Posterior draws for individual smooths — smooth_samples","text":"","code":"load_mgcv() dat <- data_sim(\"eg1\", n = 400, seed = 2) m1 <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = dat, method = \"REML\") sms <- smooth_samples(m1, select = \"s(x0)\", n = 5, seed = 42) # \\donttest{ sms #> # A tibble: 1,000 x 8 #> .smooth .term .type .by .row .draw .value x0 #> #> 1 s(x0) s(x0) TPRS NA 1 1 -0.357 0.00711 #> 2 s(x0) s(x0) TPRS NA 1 2 -0.465 0.00711 #> 3 s(x0) s(x0) TPRS NA 1 3 -0.720 0.00711 #> 4 s(x0) s(x0) TPRS NA 1 4 -1.27 0.00711 #> 5 s(x0) s(x0) TPRS NA 1 5 -1.18 0.00711 #> 6 s(x0) s(x0) TPRS NA 2 1 -0.365 0.0121 #> 7 s(x0) s(x0) TPRS NA 2 2 -0.464 0.0121 #> 8 s(x0) s(x0) TPRS NA 2 3 -0.708 0.0121 #> 9 s(x0) s(x0) TPRS NA 2 4 -1.24 0.0121 #> 10 s(x0) s(x0) TPRS NA 2 5 -1.16 0.0121 #> # i 990 more rows # } ## A factor by example (with a spurious covariate x0) dat <- data_sim(\"eg4\", n = 1000, seed = 2) ## fit model... m2 <- gam(y ~ fac + s(x2, by = fac) + s(x0), data = dat) sms <- smooth_samples(m2, n = 5, seed = 42) draw(sms)"},{"path":[]},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_terms.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"List the variables involved in smooths — smooth_terms","text":"","code":"smooth_terms(object, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_terms.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"List the variables involved in smooths — smooth_terms","text":"object R object result call mgcv::gam(), mgcv::bam(), mgcv::gamm(), inherits classes \"gam\" \"mgcv.smooth\", \"fs.interaction\". ... arguments passed methods. Currently unused.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_type.html","id":null,"dir":"Reference","previous_headings":"","what":"Determine the type of smooth and return it n a human readable form — smooth_type","title":"Determine the type of smooth and return it n a human readable form — smooth_type","text":"Determine type smooth return n human readable form","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_type.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Determine the type of smooth and return it n a human readable form — smooth_type","text":"","code":"smooth_type(smooth) # Default S3 method smooth_type(smooth) # S3 method for class 'tprs.smooth' smooth_type(smooth) # S3 method for class 'ts.smooth' smooth_type(smooth) # S3 method for class 'cr.smooth' smooth_type(smooth) # S3 method for class 'cs.smooth' smooth_type(smooth) # S3 method for class 'cyclic.smooth' smooth_type(smooth) # S3 method for class 'pspline.smooth' smooth_type(smooth) # S3 method for class 'cpspline.smooth' smooth_type(smooth) # S3 method for class 'Bspline.smooth' smooth_type(smooth) # S3 method for class 'duchon.spline' smooth_type(smooth) # S3 method for class 'fs.interaction' smooth_type(smooth) # S3 method for class 'sz.interaction' smooth_type(smooth) # S3 method for class 'gp.smooth' smooth_type(smooth) # S3 method for class 'mrf.smooth' smooth_type(smooth) # S3 method for class 'random.effect' smooth_type(smooth) # S3 method for class 'sw' smooth_type(smooth) # S3 method for class 'sf' smooth_type(smooth) # S3 method for class 'soap.film' smooth_type(smooth) # S3 method for class 't2.smooth' smooth_type(smooth) # S3 method for class 'sos.smooth' smooth_type(smooth) # S3 method for class 'tensor.smooth' smooth_type(smooth) # S3 method for class 'mpi.smooth' smooth_type(smooth) # S3 method for class 'mpd.smooth' smooth_type(smooth) # S3 method for class 'cx.smooth' smooth_type(smooth) # S3 method for class 'cv.smooth' smooth_type(smooth) # S3 method for class 'micx.smooth' smooth_type(smooth) # S3 method for class 'micv.smooth' smooth_type(smooth) # S3 method for class 'mdcx.smooth' smooth_type(smooth) # S3 method for class 'mdcv.smooth' smooth_type(smooth) # S3 method for class 'miso.smooth' smooth_type(smooth) # S3 method for class 'mifo.smooth' smooth_type(smooth)"},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_type.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Determine the type of smooth and return it n a human readable form — smooth_type","text":"smooth object inheriting class mgcv.smooth.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/smooths.html","id":null,"dir":"Reference","previous_headings":"","what":"Names of smooths in a GAM — smooths","title":"Names of smooths in a GAM — smooths","text":"Names smooths GAM","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/smooths.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Names of smooths in a GAM — smooths","text":"","code":"smooths(object) # Default S3 method smooths(object) # S3 method for class 'gamm' smooths(object)"},{"path":"https://gavinsimpson.github.io/gratia/reference/smooths.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Names of smooths in a GAM — smooths","text":"object fitted GAM related model. Typically result call mgcv::gam(), mgcv::bam(), mgcv::gamm().","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/spline_values.html","id":null,"dir":"Reference","previous_headings":"","what":"Evaluate a spline at provided covariate values — spline_values","title":"Evaluate a spline at provided covariate values — spline_values","text":"Evaluate spline provided covariate values","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/spline_values.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Evaluate a spline at provided covariate values — spline_values","text":"","code":"spline_values( smooth, data, model, unconditional, overall_uncertainty = TRUE, frequentist = FALSE )"},{"path":"https://gavinsimpson.github.io/gratia/reference/spline_values.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Evaluate a spline at provided covariate values — spline_values","text":"smooth currently object inherits class mgcv.smooth. data data frame values evaluate smooth . model fitted model; currently mgcv::gam() mgcv::bam() models suported. unconditional logical; confidence intervals include uncertainty due smoothness selection? TRUE, corrected Bayesian covariance matrix used. overall_uncertainty logical; uncertainty model constant term included standard error evaluate values smooth? frequentist logical; use frequentist covariance matrix?","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/spline_values2.html","id":null,"dir":"Reference","previous_headings":"","what":"Evaluate a spline at provided covariate values — spline_values2","title":"Evaluate a spline at provided covariate values — spline_values2","text":"function spline_values2() renamed spline_values() version 0.9.0. allowed following removal evaluate_smooth(), function using spline_values(). spline_values2() renamed spline_values().","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/spline_values2.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Evaluate a spline at provided covariate values — spline_values2","text":"","code":"spline_values2( smooth, data, model, unconditional, overall_uncertainty = TRUE, frequentist = FALSE )"},{"path":"https://gavinsimpson.github.io/gratia/reference/spline_values2.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Evaluate a spline at provided covariate values — spline_values2","text":"smooth currently object inherits class mgcv.smooth. data optional data frame values evaluate smooth . model fitted model; currently mgcv::gam() mgcv::bam() models suported. unconditional logical; confidence intervals include uncertainty due smoothness selection? TRUE, corrected Bayesian covariance matrix used. overall_uncertainty logical; uncertainty model constant term included standard error evaluate values smooth? frequentist logical; use frequentist covariance matrix?","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/term_names.html","id":null,"dir":"Reference","previous_headings":"","what":"Extract names of all variables needed to fit a GAM or a smooth — term_names","title":"Extract names of all variables needed to fit a GAM or a smooth — term_names","text":"Extract names variables needed fit GAM smooth","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/term_names.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Extract names of all variables needed to fit a GAM or a smooth — term_names","text":"","code":"term_names(object, ...) # S3 method for class 'gam' term_names(object, ...) # S3 method for class 'mgcv.smooth' term_names(object, ...) # S3 method for class 'gamm' term_names(object, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/term_names.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Extract names of all variables needed to fit a GAM or a smooth — term_names","text":"object fitted GAM object (inheriting class \"gam\" mgcv::smooth.construct smooth object, inheriting class \"mgcv.smooth\". ... arguments passed methods. currently used.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/term_names.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Extract names of all variables needed to fit a GAM or a smooth — term_names","text":"vector variable names required terms model","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/term_variables.html","id":null,"dir":"Reference","previous_headings":"","what":"Names of variables involved in a specified model term — term_variables","title":"Names of variables involved in a specified model term — term_variables","text":"Given name (term label) term model, returns names variables involved term.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/term_variables.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Names of variables involved in a specified model term — term_variables","text":"","code":"term_variables(object, term, ...) # S3 method for class 'terms' term_variables(object, term, ...) # S3 method for class 'gam' term_variables(object, term, ...) # S3 method for class 'bam' term_variables(object, term, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/term_variables.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Names of variables involved in a specified model term — term_variables","text":"object R object method dispatch performed term character; name model term, sense attr(terms(object), \"term.labels\"). Currently checked see term exists model. ... arguments passed methods.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/term_variables.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Names of variables involved in a specified model term — term_variables","text":"character vector variable names.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/theta.html","id":null,"dir":"Reference","previous_headings":"","what":"General extractor for additional parameters in mgcv models — theta","title":"General extractor for additional parameters in mgcv models — theta","text":"General extractor additional parameters mgcv models","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/theta.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"General extractor for additional parameters in mgcv models — theta","text":"","code":"theta(object, ...) # S3 method for class 'gam' theta(object, transform = TRUE, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/theta.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"General extractor for additional parameters in mgcv models — theta","text":"object fitted model ... arguments passed methods. transform logical; transform natural scale parameter","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/theta.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"General extractor for additional parameters in mgcv models — theta","text":"Returns numeric vector additional parameters","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/theta.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"General extractor for additional parameters in mgcv models — theta","text":"","code":"load_mgcv() df <- data_sim(\"eg1\", dist = \"poisson\", seed = 42, scale = 1 / 5) m <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = df, method = \"REML\", family = nb() ) p <- theta(m)"},{"path":"https://gavinsimpson.github.io/gratia/reference/tidy_basis.html","id":null,"dir":"Reference","previous_headings":"","what":"A tidy basis representation of a smooth object — tidy_basis","title":"A tidy basis representation of a smooth object — tidy_basis","text":"Takes object class mgcv.smooth returns tidy representation basis.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/tidy_basis.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"A tidy basis representation of a smooth object — tidy_basis","text":"","code":"tidy_basis(smooth, data = NULL, at = NULL, coefs = NULL, p_ident = NULL)"},{"path":"https://gavinsimpson.github.io/gratia/reference/tidy_basis.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"A tidy basis representation of a smooth object — tidy_basis","text":"smooth smooth object inheriting class \"mgcv.smooth\". Typically, objects returned part fitted GAM GAMM $smooth component model object $gam$smooth component model fitted mgcv::gamm() gamm4::gamm4(). data data frame containing variables used smooth. data frame containing values smooth covariate(s) basis evaluated. coefs numeric; optional vector coefficients smooth p_ident logical vector; used handling scam::scam() smooths.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/tidy_basis.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"A tidy basis representation of a smooth object — tidy_basis","text":"tibble.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/tidy_basis.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"A tidy basis representation of a smooth object — tidy_basis","text":"Gavin L. Simpson","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/tidy_basis.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"A tidy basis representation of a smooth object — tidy_basis","text":"","code":"load_mgcv() df <- data_sim(\"eg1\", n = 400, seed = 42) # fit model m <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = df, method = \"REML\") # tidy representaition of a basis for a smooth definition # extract the smooth sm <- get_smooth(m, \"s(x2)\") # get the tidy basis - need to pass where we want it to be evaluated bf <- tidy_basis(sm, at = df) # can weight the basis by the model coefficients for this smooth bf <- tidy_basis(sm, at = df, coefs = smooth_coefs(sm, model = m))"},{"path":"https://gavinsimpson.github.io/gratia/reference/to_na.html","id":null,"dir":"Reference","previous_headings":"","what":"Sets the elements of vector to NA — to_na","title":"Sets the elements of vector to NA — to_na","text":"Given vector indexing elements x, sets selected elements x NA.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/to_na.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Sets the elements of vector to NA — to_na","text":"","code":"to_na(x, i)"},{"path":"https://gavinsimpson.github.io/gratia/reference/to_na.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Sets the elements of vector to NA — to_na","text":"x vector values vector values used subset x","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/to_na.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Sets the elements of vector to NA — to_na","text":"Returns x possibly elements set NA","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/too_far.html","id":null,"dir":"Reference","previous_headings":"","what":"Exclude values that lie too far from the support of data — too_far","title":"Exclude values that lie too far from the support of data — too_far","text":"Identifies pairs covariate values lie far original data. function currently basic wrapper around mgcv::exclude..far().","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/too_far.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Exclude values that lie too far from the support of data — too_far","text":"","code":"too_far(x, y, ref_1, ref_2, dist = NULL)"},{"path":"https://gavinsimpson.github.io/gratia/reference/too_far.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Exclude values that lie too far from the support of data — too_far","text":"x, y numeric; vector values covariates compare observed data ref_1, ref_2 numeric; vectors covariate values represent reference x1 x2` compared dist supplied, numeric vector length 1 representing distance data beyond observation excluded. example, want exclude values lie observation 10% range observed data, use 0.1.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/too_far.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Exclude values that lie too far from the support of data — too_far","text":"Returns logical vector length x1.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/too_far_to_na.html","id":null,"dir":"Reference","previous_headings":"","what":"Set rows of data to NA if the lie too far from a reference set of values — too_far_to_na","title":"Set rows of data to NA if the lie too far from a reference set of values — too_far_to_na","text":"Set rows data NA lie far reference set values","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/too_far_to_na.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Set rows of data to NA if the lie too far from a reference set of values — too_far_to_na","text":"","code":"too_far_to_na(smooth, input, reference, cols, dist = NULL)"},{"path":"https://gavinsimpson.github.io/gratia/reference/too_far_to_na.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Set rows of data to NA if the lie too far from a reference set of values — too_far_to_na","text":"smooth mgcv smooth object input data frame containing input observations columns set NA reference data frame containing reference values cols character vector columns whose elements set NA data lies far reference set dist numeric, distance reference set beyond elements input set NA","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/transform_fun.html","id":null,"dir":"Reference","previous_headings":"","what":"Transform estimated values and confidence intervals by applying a function — transform_fun","title":"Transform estimated values and confidence intervals by applying a function — transform_fun","text":"Transform estimated values confidence intervals applying function","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/transform_fun.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Transform estimated values and confidence intervals by applying a function — transform_fun","text":"","code":"transform_fun(object, fun = NULL, ...) # S3 method for class 'smooth_estimates' transform_fun(object, fun = NULL, constant = NULL, ...) # S3 method for class 'smooth_samples' transform_fun(object, fun = NULL, constant = NULL, ...) # S3 method for class 'mgcv_smooth' transform_fun(object, fun = NULL, constant = NULL, ...) # S3 method for class 'evaluated_parametric_term' transform_fun(object, fun = NULL, constant = NULL, ...) # S3 method for class 'parametric_effects' transform_fun(object, fun = NULL, constant = NULL, ...) # S3 method for class 'tbl_df' transform_fun(object, fun = NULL, column = NULL, constant = NULL, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/transform_fun.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Transform estimated values and confidence intervals by applying a function — transform_fun","text":"object object apply transform function . fun function apply. ... additional arguments passed methods. constant numeric; constant apply transformation. column character; \"tbl_df\" method, column transform.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/transform_fun.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Transform estimated values and confidence intervals by applying a function — transform_fun","text":"Returns object estimate upper lower values confidence interval transformed via function.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/transform_fun.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Transform estimated values and confidence intervals by applying a function — transform_fun","text":"Gavin L. Simpson","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/typical_values.html","id":null,"dir":"Reference","previous_headings":"","what":"Typical values of model covariates — typical_values","title":"Typical values of model covariates — typical_values","text":"Typical values model covariates","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/typical_values.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Typical values of model covariates — typical_values","text":"","code":"typical_values(object, ...) # S3 method for class 'gam' typical_values( object, vars = everything(), envir = environment(formula(object)), data = NULL, ... ) # S3 method for class 'data.frame' typical_values(object, vars = everything(), ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/typical_values.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Typical values of model covariates — typical_values","text":"object fitted GAM(M) model. ... arguments passed methods. vars terms include exclude returned object. Uses tidyselect principles. envir environment within recreate data used fit object. data optional data frame data used fit model reconstruction data model work.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/user_draws.html","id":null,"dir":"Reference","previous_headings":"","what":"Handle user-supplied posterior draws — user_draws","title":"Handle user-supplied posterior draws — user_draws","text":"Handle user-supplied posterior draws","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/user_draws.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Handle user-supplied posterior draws — user_draws","text":"","code":"user_draws(model, draws, ...) # S3 method for class 'gam' user_draws(model, draws, index = NULL, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/user_draws.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Handle user-supplied posterior draws — user_draws","text":"model fitted R model. Currently models fitted mgcv::gam() mgcv::bam(), return object inherits objects supported. , \"inherits\" used loose fashion; models fitted scam::scam() support even though models strictly inherit class \"gam\" far inherits() concerned. draws matrix; user supplied posterior draws used method = \"user\". ... arguments passed methods. index vector index (subset) columns draws.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/user_draws.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Handle user-supplied posterior draws — user_draws","text":"supplied draws must matrix (currently), 1 column per model coefficient, 1 row per posterior draw. \"gam\" method argument index, can used subset (select) coefficients (columns) draws. index can valid way selecting (indexing) columns matrix. index useful set posterior draws entire model (say mgcv::gam.mh()) wish use draws individual smooth, via smooth_samples().","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/variance_comp.html","id":null,"dir":"Reference","previous_headings":"","what":"Variance components of smooths from smoothness estimates — variance_comp","title":"Variance components of smooths from smoothness estimates — variance_comp","text":"wrapper mgcv::gam.vcomp() returns smoothing parameters expressed variance components.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/variance_comp.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Variance components of smooths from smoothness estimates — variance_comp","text":"","code":"variance_comp(object, ...) # S3 method for class 'gam' variance_comp(object, rescale = TRUE, coverage = 0.95, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/variance_comp.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Variance components of smooths from smoothness estimates — variance_comp","text":"object R object. Currently models fitted mgcv::gam() mgcv::bam() supported. ... arguments passed methods rescale logical; numerical stability reasons penalty matrices smooths rescaled fitting. rescale = TRUE, rescaling undone, resulting variance components original scale. needed comparing mixed model software, lmer(). coverage numeric; value 0 1 indicating (approximate) coverage confidence interval returned.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/variance_comp.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Variance components of smooths from smoothness estimates — variance_comp","text":"function wrapper mgcv::gam.vcomp() performs three additional services suppresses annoying text output mgcv::gam.vcomp() prints terminal, returns variance smooth well standard deviation, returns variance components tibble.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/vars_from_label.html","id":null,"dir":"Reference","previous_headings":"","what":"Returns names of variables from a smooth label — vars_from_label","title":"Returns names of variables from a smooth label — vars_from_label","text":"Returns names variables smooth label","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/vars_from_label.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Returns names of variables from a smooth label — vars_from_label","text":"","code":"vars_from_label(label)"},{"path":"https://gavinsimpson.github.io/gratia/reference/vars_from_label.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Returns names of variables from a smooth label — vars_from_label","text":"label character; length 1 character vector containing label smooth.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/vars_from_label.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Returns names of variables from a smooth label — vars_from_label","text":"","code":"vars_from_label(\"s(x1)\") #> [1] \"x1\" vars_from_label(\"t2(x1,x2,x3)\") #> [1] \"x1\" \"x2\" \"x3\""},{"path":"https://gavinsimpson.github.io/gratia/reference/which_smooths.html","id":null,"dir":"Reference","previous_headings":"","what":"Identify a smooth term by its label — which_smooths","title":"Identify a smooth term by its label — which_smooths","text":"Identify smooth term label","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/which_smooths.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Identify a smooth term by its label — which_smooths","text":"","code":"which_smooths(object, ...) # Default S3 method which_smooths(object, ...) # S3 method for class 'gam' which_smooths(object, terms, ...) # S3 method for class 'bam' which_smooths(object, terms, ...) # S3 method for class 'gamm' which_smooths(object, terms, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/which_smooths.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Identify a smooth term by its label — which_smooths","text":"object fitted GAM. ... arguments passed methods. terms character; one (partial) term labels identify required smooths.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/worm_plot.html","id":null,"dir":"Reference","previous_headings":"","what":"Worm plot of model residuals — worm_plot","title":"Worm plot of model residuals — worm_plot","text":"Worm plot model residuals","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/worm_plot.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Worm plot of model residuals — worm_plot","text":"","code":"worm_plot(model, ...) # S3 method for class 'gam' worm_plot( model, method = c(\"uniform\", \"simulate\", \"normal\", \"direct\"), type = c(\"deviance\", \"response\", \"pearson\"), n_uniform = 10, n_simulate = 50, level = 0.9, ylab = NULL, xlab = NULL, title = NULL, subtitle = NULL, caption = NULL, ci_col = \"black\", ci_alpha = 0.2, point_col = \"black\", point_alpha = 1, line_col = \"red\", ... ) # S3 method for class 'glm' worm_plot(model, ...) # S3 method for class 'lm' worm_plot(model, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/worm_plot.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Worm plot of model residuals — worm_plot","text":"model fitted model. Currently models inheriting class \"gam\", well classes \"glm\" \"lm\" calls stats::glm stats::lm supported. ... arguments passed ot methods. method character; method used generate theoretical quantiles. default \"uniform\", generates reference quantiles using random draws uniform distribution inverse cummulative distribution function (CDF) fitted values. reference quantiles averaged n_uniform draws. \"simulate\" generates reference quantiles simulating new response data model observed values covariates, residualised generate reference quantiles, using n_simulate simulated data sets. \"normal\" generates reference quantiles using standard normal distribution. \"uniform\" computationally efficient, \"simulate\" allows reference bands drawn QQ-plot. \"normal\" avoided used fall back random number generator (\"simulate\") inverse CDF available family used model fitting (`\"uniform\"“). Note method = \"direct\" deprecated favour method = \"uniform\". type character; type residuals use. \"deviance\", \"response\", \"pearson\" residuals allowed. n_uniform numeric; number times randomize uniform quantiles direct computation method (method = \"uniform\"). n_simulate numeric; number data sets simulate estimated model using simulation method (method = \"simulate\"). level numeric; coverage level reference intervals. Must strictly 0 < level < 1. used method = \"simulate\". ylab character expression; label y axis. supplied, suitable label generated. xlab character expression; label y axis. supplied, suitable label generated. title character expression; title plot. See ggplot2::labs(). May vector, one per penalty. subtitle character expression; subtitle plot. See ggplot2::labs(). May vector, one per penalty. caption character expression; plot caption. See ggplot2::labs(). May vector, one per penalty. ci_col fill colour reference interval method = \"simulate\". ci_alpha alpha transparency reference interval method = \"simulate\". point_col colour points QQ plot. point_alpha alpha transparency points QQ plot. line_col colour used draw reference line.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/worm_plot.html","id":"note","dir":"Reference","previous_headings":"","what":"Note","title":"Worm plot of model residuals — worm_plot","text":"wording used mgcv::qq.gam() uses direct reference simulated residuals method (method = \"simulated\"). avoid confusion, method = \"direct\" deprecated favour method = \"uniform\".","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/worm_plot.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Worm plot of model residuals — worm_plot","text":"","code":"load_mgcv() ## simulate binomial data... dat <- data_sim(\"eg1\", n = 200, dist = \"binary\", scale = .33, seed = 0) p <- binomial()$linkinv(dat$f) # binomial p n <- sample(c(1, 3), 200, replace = TRUE) # binomial n dat <- transform(dat, y = rbinom(n, n, p), n = n) m <- gam(y / n ~ s(x0) + s(x1) + s(x2) + s(x3), family = binomial, data = dat, weights = n, method = \"REML\" ) ## Worm plot; default using direct randomization of uniform quantiles ## Note no reference bands are drawn with this method. worm_plot(m) ## Alternatively use simulate new data from the model, which ## allows construction of reference intervals for the Q-Q plot worm_plot(m, method = \"simulate\", point_col = \"steelblue\", point_alpha = 0.4 ) ## ... or use the usual normality assumption worm_plot(m, method = \"normal\")"},{"path":"https://gavinsimpson.github.io/gratia/reference/zooplankton.html","id":null,"dir":"Reference","previous_headings":"","what":"Madison lakes zooplankton data — zooplankton","title":"Madison lakes zooplankton data — zooplankton","text":"Madison lake zooplankton data long-term study seasonal dynamics zooplankton, collected Richard Lathrop. data collected chain lakes Wisconsin (Mendota, Monona, Kegnonsa, Waubesa) approximately bi-weekly 1976 1994. consist samples zooplankton communities, taken deepest point lake via vertical tow. data provided Wisconsin Department Natural Resources collection processing fully described Lathrop (2000).","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/zooplankton.html","id":"format","dir":"Reference","previous_headings":"","what":"Format","title":"Madison lakes zooplankton data — zooplankton","text":"data frame","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/zooplankton.html","id":"source","dir":"Reference","previous_headings":"","what":"Source","title":"Madison lakes zooplankton data — zooplankton","text":"Pedersen EJ, Miller DL, Simpson GL, Ross N. 2018. Hierarchical generalized additive models: introduction mgcv. PeerJ Preprints 6:e27320v1 doi:10.7287/peerj.preprints.27320v1 .","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/zooplankton.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Madison lakes zooplankton data — zooplankton","text":"record consists counts given zooplankton taxon taken subsample single vertical net tow, scaled account relative volume subsample versus whole net sample area net tow rounded nearest 1000 give estimated population density per m2 taxon point time sampled lake.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/zooplankton.html","id":"references","dir":"Reference","previous_headings":"","what":"References","title":"Madison lakes zooplankton data — zooplankton","text":"Lathrop RC. (2000). Madison Wisonsin Lakes Zooplankton 1976–1994. Environmental Data Initiative.","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"gratia-092","dir":"Changelog","previous_headings":"","what":"gratia 0.9.2","title":"gratia 0.9.2","text":"CRAN release: 2024-06-25","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"breaking-changes-0-9-2","dir":"Changelog","previous_headings":"","what":"Breaking changes","title":"gratia 0.9.2","text":"parametric_effects() slightly escaped great renaming happened 0.9.0. Columns type term gain prefix .. now rectified two columns now .type .term.","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"user-visible-changes-0-9-2","dir":"Changelog","previous_headings":"","what":"User visible changes","title":"gratia 0.9.2","text":"Plots random effects now labelled smooth label. Previously, title taken fro variable involved smooth, doesn’t work terms like s(subject, continuous_var, bs = \"re\") random slopes, previsouly title \"subject\". Now terms title \"s(subject,continuous_var)\". Simple random intercept terms, s(subject, bs = \"re\"), now titled \"s(subject)\". #287 vignettes custom-plotting.Rmd, posterior-simulation.Rmd moved vignettes/articles thus longer available package vignettes. Instead, accessible Articles package website: https://gavinsimpson.github.io/gratia/","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"new-features-0-9-2","dir":"Changelog","previous_headings":"","what":"New features","title":"gratia 0.9.2","text":"fitted_samples() now works gam() models multiple linear predictors, currently location parameter supported. parameter indicated new variable .parameter returned object.","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"bug-fixes-0-9-2","dir":"Changelog","previous_headings":"","what":"Bug fixes","title":"gratia 0.9.2","text":"partial_residuals() computing partial residuals deviance residuals. compatibility mgcv::plot.gam(), partial residuals now computed working residuals. Reported @wStockhausen #273 appraise() passing ci_col argument qq_plot() worm_plot(). Reported Sate Ahmed. Couldn’t pass mvn_method posterior sampling functions user facing functions fitted_samples(), posterior_samples(), smooth_samples(), derivative_samples(), repsonse_derivatives(). Reported @stefgehrig #279 fitted_values() works quantile GAMs fitted qgam(). confint.gam() applying shift estimate upper lower interval. #280 reported @TIMAVID & @rbentham parametric_effects() draw.parametric_effects() forget levels factors (intentionally), lead problems ordered factors ordering levels preserved. Now, parametric_effects() returns named list factor levels attribute \"factor_levels\" containing required information order levels preserved plotting. #284 Reported @mhpob parametric_effects() fail parametric terms model interaction terms (don’t currently handle). #282","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"gratia-090","dir":"Changelog","previous_headings":"","what":"gratia 0.9.0","title":"gratia 0.9.0","text":"CRAN release: 2024-03-27","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"breaking-changes-0-9-0","dir":"Changelog","previous_headings":"","what":"Breaking changes","title":"gratia 0.9.0","text":"Many functions now return objects different named variables. order avoid clashes variable names used user’s models data, period (.) now used prefix generated variable names. functions whose names changed : smooth_estimates(), fitted_values(), fitted_samples(), posterior_samples(), derivatives(), partial_derivatives(), derivative_samples(). addition, add_confint() also adds newly-named variables. derivatives() partial_derivatives() now work like smooth_estimates(); place var data columns, gratia now stores data variables derivatives evaluated columns object actual variable names. way spline---sphere (SOS) smooths (bs = \"sos\") plotted changed use ggplot2::coord_sf() instead previously-used ggplot2::coord_map(). changed made result coord_map() soft-deprecated (“superseded”) minor versions ggplot2 now already, changes guides system version 3.5.0 ggplot2. axes plots created coord_map() never really worked correctly changing angle tick labels never worked. coord_map() superseded, didn’t receive updates guides system side effect changes, code plotted SOS smooths producing warning release ggplot2 version 3.5.0. projection settings used draw SOS smooths previously controlled via arguments projection orientation. arguments affect ggplot2::coord_sf(), Instead projection used controlled new argument crs, takes PROJ string detailing projection use integer refers known coordinate reference system (CRS). default projection used +proj=ortho +lat_0=20 +lon_0=XX XX mean longitude coordinates data points.","code":"1. `est` is now `.estimate`, 2. `lower` and `upper` are now `.lower_ci` and `.upper_ci`, 3. `draw` and `row` and now `.draw` and `.row` respectively, 4. `fitted`, `se`, `crit` are now `.fitted`, `.se`, `.crit`, respectively 5. `smooth`, `by`, and `type` in `smooth_estimates()` are now `.smooth`, `.by`, `.type`, respectively."},{"path":[]},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"defunct-0-9-0","dir":"Changelog","previous_headings":"Breaking changes > Defunct and deprecated functions and arguments","what":"Defunct","title":"gratia 0.9.0","text":"evaluate_smooth() deprecated gratia version 0.7.0. function ’s methods removed package. Use smooth_estimates() instead.","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"deprecated-functions-0-9-0","dir":"Changelog","previous_headings":"Breaking changes > Defunct and deprecated functions and arguments","what":"Deprecated functions","title":"gratia 0.9.0","text":"following functions deprecated version 0.9.0 gratia. eventually removed package part clean ahead eventual 1.0.0 release. functions become defunct version 0.11.0 1.0.0, whichever released soonest. evaluate_parametric_term() deprecated. Use parametric_effects() instead. datagen() deprecated. never really originally designed , replaced data_slice().","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"deprecated-arguments-0-9-0","dir":"Changelog","previous_headings":"Breaking changes > Defunct and deprecated functions and arguments","what":"Deprecated arguments","title":"gratia 0.9.0","text":"make functions package consistent, arguments select, term, smooth used thing hence latter two deprecated favour select. deprecated argument used, warning issued value assigned argument assigned select function continue.","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"user-visible-changes-0-9-0","dir":"Changelog","previous_headings":"","what":"User visible changes","title":"gratia 0.9.0","text":"smooth_samples() now uses single call RNG generate draws posterior smooths. Previous version 0.9.0, smooth_samples() separate call mvnfast::rmvn() smooth. result, result call smooth_samples() model multiple smooths now produce different results generated previously. regain old behaviour, add rng_per_smooth = TRUE smooth_samples() call. Note, however, using per-smooth RNG calls method = \"mh\" inefficient , method, posterior draws coefficients model sampled . , use rng_per_smooth = TRUE method = \"gaussian\". output smooth_estimates() draw() method changed tensor product smooths involve one 2D marginal smooths. Now, covariate values supplied via data argument, smooth_estimates() identifies one marginals 2d surface allows covariates involved surface vary fastest, ahead terms marginals. change made provides better default nothing provided data. also affects draw.gam(). fitted_values() now level support location, scale, shape families. Supported families mgcv::gaulss(), mgcv::gammals(), mgcv::gumbls(), mgcv::gevlss(), mgcv::shash(), mgcv::twlss(), mgcv::ziplss(). gratia now requires dplyr versions >= 1.1.0 tidyselect >= 1.2.0. new vignette Posterior Simulation available, describes posterior simulation fitted GAMs using {gratia}.","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"new-features-0-9-0","dir":"Changelog","previous_headings":"","what":"New features","title":"gratia 0.9.0","text":"Soap film smooths using basis bs = \"\" now handled draw(), smooth_estimates() etc. #8 response_derivatives() new function computing derivatives response respect (continuous) focal variable. First second order derivatives can computed using forward, backward, central finite differences. uncertainty estimated derivative determined using posterior sampling via fitted_samples(), hence can derived Gaussian approximation posterior using Metropolis Hastings sampler (see .) derivative_samples() work horse function behind response_derivatives(), computes returns posterior draws derivatives additive combination model terms. Requested @jonathanmellor #237 data_sim() can now simulate response data gamma, Tweedie ordered categorical distributions. data_sim() gains two new example models \"gwf2\", simulating data Gu & Wabha’s f2 function, \"lwf6\", example function 6 Luo & Wabha (1997 JASA 92(437), 107-116). data_sim() can also simulate data use GAMs fitted using family = gfam() grouped families different types data response handled. #266 part #265 fitted_samples() smooth_samples() can now use Metropolis Hastings sampler mgcv::gam.mh(), instead Gaussian approximation, sample posterior distribution model specific smooths respectively. posterior_samples() new function family fitted_samples() smooth_samples(). posterior_samples() returns draws posterior distribution response, combining uncertainty estimated expected value response dispersion response distribution. difference posterior_samples() predicted_samples() latter includes variation due drawing samples conditional distribution response (uncertainty expected values ignored), former includes sources uncertainty. fitted_samples() can new use matrix user-supplied posterior draws. Related #120 add_fitted_samples(), add_predicted_samples(), add_posterior_samples(), add_smooth_samples() new utility functions add respective draws posterior distribution existing data object covariate values object: obj |> add_posterior_draws(model). #50 basis_size() new function extract basis dimension (number basis functions) smooths. Methods available objects inherit classes \"gam\", \"gamm\", \"mgcv.smooth\" (individual smooths). data_slice() gains method data frames tibbles. typical_values() gains method data frames tibbles. fitted_values() now works models fitted using mgcv::ocat() family. predicted probability category returned, alongside Wald interval created using standard error (SE) estimated probability. SE estimated probabilities transformed logit (linear predictor) scale, Wald credible interval formed, back-transformed response (probability) scale. fitted_values() now works GAMMs fitted using mgcv::gamm(). Fitted (predicted) values use GAM part model, thus exclude random effects. link() inv_link() work models fitted using cnorm() family. worm plot can now drawn place QQ plot appraise() via new argument use_worm = TRUE. #62 smooths() now works models fitted mgcv::gamm(). overview() now returns basis dimension smooth gains argument stars TRUE add significance stars output plus legend printed tibble footer. Part wish @noamross #214 New add_constant() transform_fun() methods smooth_samples(). evenly() gains arguments lower upper modify lower / upper bound interval evenly spaced values generated. add_sizer() new function add information whether derivative smooth significantly changing (credible interval excludes 0). Currently, methods derivatives() smooth_estimates() objects implemented. Part request @asanders11 #117 draw.derivatives() gains arguments add_change change_type allow derivatives smooths plotted indicators credible interval derivative excludes 0. Options allow periods decrease increase differentiated via change_type = \"sizer\" instead default change_type = \"change\", emphasises either type change way. Part wish @asanders11 #117 draw.gam() can now group factor smooths given factor single panel, rather plotting smooths level separate panels. achieved via new argument grouped_by. Requested @RPanczak #89 draw.smooth_estimates() can now also group factor smooths given factor single panel. underlying plotting code used draw_smooth_estimates() univariate smooths can now add change indicators plots smooths change indicators added object created smooth_estimates() using add_sizer(). See example ?draw.smooth_estimates. smooth_estimates() can, evaluating 3D 4D tensor product smooth, identify one 2D smooths marginal tensor product. users provide covariate values evaluate smooths, smooth_estimates() focus 2D marginal smooth (first one involved tensor product), instead following ordering terms definition tensor product. #191 example, te(z, x, y, bs = c(cr, ds), d = c(1, 2)), second marginal smooth 2D Duchon spline covariates x y. Previously, smooth_estimates() generated n values z x n_3d values y, evaluated tensor product combinations generated values. ignore structure implicit tensor product, likely want know surface estimated Duchon spline x y smoothly varies z. Previously smooth_estimates() generate surfaces z x, varying y. Now, smooth_estimates() correctly identifies one marginal smooths tensor product 2D surface focus surface varying terms tensor product. improved behaviour needed bam() models always possible obvious thing reorder smooths defining tensor product te(x, y, z, bs = c(ds, cr), d = c(2, 1)). discrete = TRUE used bam() terms tensor product may get rearranged model setup maximum efficiency (See Details ?mgcv::bam). Additionally, draw.gam() now also works way. New function null_deviance() extracts null deviance fitted model. draw(), smooth_estimates(), fitted_values(), data_slice(), smooth_samples() now work models fitted scam::scam(). matters, current support extends univariate smooths. generate_draws() new low-level function generating posterior draws fitted model coefficients. generate_daws() S3 generic function extensible users. Currently provides simple interface simple Gaussian approximation sampler (gaussian_draws()) simple Metropolis Hasting sample (mh_draws()) available via mgcv::gam.mh(). #211 smooth_label() new function extracting labels ‘mgcv’ creates smooths smooth object . penalty() default method works s(), te(), t2(), ti(), create smooth specification. transform_fun() gains argument constant allow addition constant value objects (e.g. estimate confidence interval). enables single obj |> transform_fun(fun = exp, constant = 5) instead separate calls add_constant() transform_fun(). Part discussion #79 model_constant() new function simply extracts first coefficient estimated model.","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"bug-fixes-0-9-0","dir":"Changelog","previous_headings":"","what":"Bug fixes","title":"gratia 0.9.0","text":"link(), inv_link(), related family functions ocat() weren’t correctly identifying family name result throw error even passed object correct family. link() inv_link() now work correctly betar() family fitted GAM. print() method lp_matrix() now converts matrix data frame conversion tibble. makes sense results typical behaviour columns printed object doubles. Constrained factor smooths (bs = \"sz\") factor first variable mentioned smooth (.e. s(x, f, bs = \"sz\") continuous x factor f) now plotable draw(). #208 parametric_effects() unable handle special parametric terms like poly(x) log(x) formulas. Reported @fhui28 #212 parametric_effects() now works better location, scale, shape models. Reported @pboesu #45 parametric_effects now works missing values one variables used fitted GAM. #219 response_derivatives() incorrectly using .data tidyselect selectors. typical_values() handle logical variables GAM fit mgcv stores numerics var.summary. affected evenly() data_slice(). #222 parametric_effects() fail two ordered factors model. Reported @dsmi31 #221 Continuous smooths evaluated median value variable instead value 1. #224 fitted_samples() (hence posterior_samples()) now handles models offset terms formula. Offset terms supplied via offset argument ignored mgcv:::predict.gam() hence ignored also gratia. Reported @jonathonmellor #231 #233 smooth_estimates() fail \"fs\" smooth multivariate base smoother used factor last variable specified definition smooth: s(x1, x2, f, bs = \"fs\", xt = list(bs = \"ds\")) work, s(f, x1, x2, bs = \"fs\", xt = list(bs = \"ds\")) (ordering variables places factor last) emit obscure error. ordering terms involved smooth now doesn’t matter. Reported @chrisaak #249. draw.gam() fail plotting multivariate base smoother used \"sz\" smooth. Now, use case identified message printed indicating (currently) gratia doesn’t know plot smooth. Reported @chrisaak #249. draw.gam() fail plotting multivariate base smoother used \"fs\" smooth. Now, use case identified message printed indicating (currently) gratia doesn’t know plot smooth. Reported @chrisaak #249. derivative_samples() fail order = 2 computing forward finite differences, regardless type order = 1. Partly reported @samlipworth #251. draw() method penalty() normalizing penalty range 0–1, claimed documented -1–1 argument normalize = TRUE. now fixed. smooth_samples() failing data supplied contained variables used smooth sampled. Hence generally fail unless single smooth sampled model contained single smooth. function never intended retain variables data written way fail relocating data columns end posterior sampling object. #255 draw.gam() draw.smooth_estimates() fail plotting univariate tensor product smooth (e.g. te(x), ti(x), t2()). Reported @wStockhausen #260 plot.smooth() printing factor level subtitles ordered factor smooths.","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"gratia-082","dir":"Changelog","previous_headings":"","what":"gratia 0.8.2","title":"gratia 0.8.2","text":"CRAN release: 2024-01-09 Small fixes CRAN.","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"gratia-081","dir":"Changelog","previous_headings":"","what":"gratia 0.8.1","title":"gratia 0.8.1","text":"CRAN release: 2023-02-02","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"user-visible-changes-0-8-1","dir":"Changelog","previous_headings":"","what":"User visible changes","title":"gratia 0.8.1","text":"smooth_samples() now returns objects variables involved smooths correct name. Previously variables named .x1, .x2, etc. Fixing #126 improving compatibility compare_smooths() smooth_estimates() allowed variables named correctly. gratia now depends version 1.8-41 later mgcv package.","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"new-features-0-8-1","dir":"Changelog","previous_headings":"","what":"New features","title":"gratia 0.8.1","text":"draw.gam() can now handle tensor products include marginal random effect smooth. Beware plotting smooths many levels, however, separate surface plot produced level.","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"bug-fixes-0-8-1","dir":"Changelog","previous_headings":"","what":"Bug fixes","title":"gratia 0.8.1","text":"Additional fixes changes dplyr 1.1.0. smooth_samples() now works sampling posteriors multiple smooths different dimension. #126 reported @Aariq","code":""},{"path":[]},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"user-visible-changes-0-8-0","dir":"Changelog","previous_headings":"","what":"User visible changes","title":"gratia 0.8.0","text":"{gratia} now depends R version 4.1 later. new vignette “Data slices” supplied {gratia}. Functions {gratia} harmonised use argument named data instead newdata passing new data evaluate features smooths. message printed newdata used now . Existing code need changed data takes value newdata. Note due way ... handled R, R script uses data argument, run versions gratia prior 8.0 (released; 0.7.3.8 using development version) user-supplied data silently ignored. , scripts using data check installed version gratia >= 0.8 package developers update depend versions >= 0.8 using gratia (>= 0.8) DESCRIPTION. order plots smooths changed draw.gam() match order smooths specified model formula. See Bug Fixes detail #154.","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"new-features-0-8-0","dir":"Changelog","previous_headings":"","what":"New features","title":"gratia 0.8.0","text":"Added basic support GAMLSS (distributional GAMs) fitted gamlss() function package GJRM. Support currently restricted draw() method. difference_smooths() can now include group means difference, many users expected. include group means use group_means = TRUE function call, e.g. difference_smooths(model, smooth = \"s(x)\", group_means = TRUE). Note: function still differs plot_diff() package itsadug, essentially computes differences model predictions. main practical difference effects beyond factor smooth, including random effects, may included plot_diff(). implements main wish #108 (@dinga92) #143 (@mbolyanatz) despite protestations complicated cases (isn’t; complexity just cancels .) data_slice() totally revised. Now, user provides values variables want slice variables model specified held typical values (.e. value observation closest median numeric variables, modal factor level.) Data slices now produced passing name = value pairs variables values want appear slice. example value pair can expression looked (evaluated) data argument model frame fitted model (default). example, resulting slice data frame 100 observations, comprising x1, vector 100 values spread evenly range x1, constant value mean x2 x2 variable, constant factor level, model class fac, fac variable model. partial_derivatives() new function computing partial derivatives multivariate smooths (e.g. s(x,z), te(x,z)) respect one margins smooth. Multivariate smooths dimension handled, one dimensions allowed vary. Partial derivatives estimated using method finite differences, forward, backward, central finite differences available. Requested @noamross #101 overview() provides simple overview model terms fitted GAMs. new bs = \"sz\" basis released mgcv version 1.18-41 now supported smooth_estimates(), draw.gam(), draw.smooth_estimates() basis unique plotting method. #202 basis() now method fitted GAM(M)s can extract estimated basis model plot , using estimated coefficients smooth weight basis. #137 also new draw.basis() method plotting results call basis(). method can now also handle bivariate bases. tidy_basis() lower level function heavy lifting basis(), now exported. tidy_basis() returns tidy representation basis supplied object inheriting class \"mgcv.smooth\". objects returned $smooth component fitted GAM(M) model. lp_matrix() new utility function quickly return linear predictor matrix estimated model. wrapper predict(..., type = \"lpmatrix\") evenly() synonym seq_min_max() preferred going forward. Gains argument produce sequences covariate increment units . ref_level() level() new utility functions extracting reference specific level factor respectively. useful specifying covariate values condition data slice. model_vars() new, public facing way returning vector variables used model. difference_smooths() now use user-supplied data points evaluate pair smooths. Also note argument newdata renamed data. #175 draw() method difference_smooths() now uses better labels plot titles avoid long labels even modest factor levels. derivatives() now works factor-smooth interaction (\"fs\") smooths. draw() methods now allow angle tick labels x axis plots rotated using argument angle. Requested @tamas-ferenci #87 draw.gam() related functions (draw.parametric_effects(), draw.smooth_estimates()) now add basis plot using caption. #155 smooth_coefs() new utility function extracting coefficients particular smooth fitted model. smooth_coef_indices() associated function returns indices (positions) vector model coefficients (returned coef(gam_model)) coefficients pertain stated smooth. draw.gam() now better handles patchworks plots one plots fixed aspect ratios. #190","code":"m <- gam(y ~ s(x1) + x2 + fac) data_slice(model, x1 = evenly(x1, n = 100), x2 = mean(x2))"},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"bug-fixes-0-8-0","dir":"Changelog","previous_headings":"","what":"Bug fixes","title":"gratia 0.8.0","text":"draw.posterior_smooths now plots posterior samples fixed aspect ratio smooth isotropic. #148 derivatives() now ignores random effect smooths (derivatives don’t make sense anyway). #168 confint.gam(...., method = \"simultaneous\") now works factor smooths parm passed full name specific smooth s(x)faclevel. order plots produced gratia::draw.gam() matches order smooths entered model formula. Recent changes internals gratia::draw.gam() switch smooth_estimates() undertaken lead change behaviour resulting use dplyr::group_split(), ’s coercion internally character vector factor. factor now created explicitly, levels set correct order. #154 Setting dist argument set response smooth values NA lay far support data multivariate smooths, lead incorrect scale response guide. now fixed. #193 Argument fun draw.gam() applied parametric terms. Reported @grasshoppermouse #195 draw.gam() adding uncertainty linear predictors smooths overall_uncertainty = TRUE used. Now draw.gam() includes uncertainty linear predictors smooth takes part. #158 partial_derivatives() works provided single data point evaluate derivative. #199 transform_fun.smooth_estimates() addressing wrong variable names trying transform confidence interval. #201 data_slice() doesn’t fail error used model contains offset term. #198 confint.gam() longer uses evaluate_smooth(), soft deprecated. #167 qq_plot() worm_plot() compute wrong deviance residuals used generate theoretical quantiles exotic families (distributions) available mgcv. also affected appraise() QQ plot; residuals shown plots deviance residuals shown y-axis QQ plot correct. generation reference intervals/quantiles affected.","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"gratia-073","dir":"Changelog","previous_headings":"","what":"gratia 0.7.3","title":"gratia 0.7.3","text":"CRAN release: 2022-05-09","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"user-visible-changes-0-7-3","dir":"Changelog","previous_headings":"","what":"User visible changes","title":"gratia 0.7.3","text":"Plots smooths now use “Partial effect” y-axis label place “Effect”, better indicate displayed.","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"new-features-0-7-3","dir":"Changelog","previous_headings":"","what":"New features","title":"gratia 0.7.3","text":"confint.fderiv() confint.gam() now return results tibble instead common--garden data frame. latter mostly already . Examples confint.fderiv() confint.gam() reworked, part remove inconsistent output examples run M1 macs.","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"bug-fixes-0-7-3","dir":"Changelog","previous_headings":"","what":"Bug fixes","title":"gratia 0.7.3","text":"compare_smooths() failed passed non-standard model “names” like compare_smooths(m_gam, m_gamm$gam) compare_smooths(l[[1]], l[[2]]) even evaluated objects valid GAM(M) models. Reported Andrew Irwin #150","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"gratia-072","dir":"Changelog","previous_headings":"","what":"gratia 0.7.2","title":"gratia 0.7.2","text":"CRAN release: 2022-03-17","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"new-features-0-7-2","dir":"Changelog","previous_headings":"","what":"New features","title":"gratia 0.7.2","text":"draw.gam() draw.smooth_estimates() can now handle splines sphere (s(lat, long, bs = \"sos\")) special plotting methods using ggplot2::coord_map() handle projection spherical coordinates. orthographic projection used default, essentially arbitrary (northern hemisphere-centric) default orientation view. fitted_values() insures data (hence returned object) tibble rather common garden data frame.","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"bug-fixes-0-7-2","dir":"Changelog","previous_headings":"","what":"Bug fixes","title":"gratia 0.7.2","text":"draw.posterior_smooths() redundantly plotting duplicate data rug plot. Now unique set covariate values used drawing rug. data_sim() passing scale argument bivariate example setting (\"eg2\"). draw() methods gamm() gamm4::gamm4() fits passing arguments draw.gam(). draw.smooth_estimates() produce subtitle data continuous smooth factor smooth. Now subtitle contains name continuous variable.","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"gratia-071","dir":"Changelog","previous_headings":"","what":"gratia 0.7.1","title":"gratia 0.7.1","text":"Due issue size package source tarball, wasn’t discovered submission CRAN, 0.7.1 never released.","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"new-features-0-7-1","dir":"Changelog","previous_headings":"","what":"New features","title":"gratia 0.7.1","text":"draw.gam() draw.smooth_estimates(): {gratia} can now handle smooths 3 4 covariates plotting. smooths 3 covariates, third covariate handled ggplot2::facet_wrap() set (default n = 16) small multiples drawn, 2d surface evaluated specified value third covariate. smooths 4 covariates, ggplot2::facet_grid() used draw small multiples, default producing 4 rows 4 columns plots specific values third fourth covariates. number small multiples produced controlled new arguments n_3d (default = n_3d = 16) n_4d (default n_4d = 4, yielding n_4d * n_4d = 16 facets) respectively. affects plotting; smooth_estimates() able handle smooths number covariates . handling higher-dimensional smooths, actually drawing plots default device can slow, especially default value n = 100 (3D 4D smooths result 160,000 data points plotted). recommended reduce n smaller value: n = 50 reasonable compromise resolution speed. model_concurvity() returns concurvity measures mgcv::concurvity() estimated GAMs tidy format. synonym concrvity() also provided. draw() method provided produces bar plot heatmap concurvity values depending whether overall concurvity smooth pairwise concurvity smooth model requested. draw.gam() gains argument resid_col = \"steelblue3\" allows colour partial residuals (plotted) changed.","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"bug-fixes-0-7-1","dir":"Changelog","previous_headings":"","what":"Bug fixes","title":"gratia 0.7.1","text":"model_edf() using type argument. result ever returned default EDF type. add_constant() methods weren’t applying constant required variables. draw.gam(), draw.parametric_effects() now actually work model parametric effects. #142 Reported @Nelson-Gon parametric_effects() fail model parametric terms predict.gam() returns empty arrays passed exclude = character(0).","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"gratia-070","dir":"Changelog","previous_headings":"","what":"gratia 0.7.0","title":"gratia 0.7.0","text":"CRAN release: 2022-02-07","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"major-changes-0-7-0","dir":"Changelog","previous_headings":"","what":"Major changes","title":"gratia 0.7.0","text":"draw.gam() now uses smooth_estimates() internally consequently uses draw() method underlying plotting code. simplified code compared evaluate_smooth() methods, allow future development addition features easily evaluate_smooth() retained. Similarly, evaluate_parametric_terms() now deprecated favour parametric_effects(), also used internally draw.gam() parametric terms present model (parametric = TRUE). lot code reused differences plots result change minimal, corner cases may missed. File Issue notice something changed think shouldn’t. draw.gam() now plots 2D isotropic smooths (TPRS Duchon splines) equally-scaled x y coordinates using coord_equal(ratio = 1). Alignment plots little different now plotting models multiple smooths. See Issue #81.","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"deprecated-functions-0-7-0","dir":"Changelog","previous_headings":"Major changes","what":"Deprecated functions","title":"gratia 0.7.0","text":"version 0.7.0, following functions considered deprecated use discouraged: fderiv() soft-deprecated favour derivatives(), evaluate_smooth() soft-deprecated favour smooth_estimates(), evaluate_parametric_term() soft-deprecated favour parametric_effects(). first call one functions generate warning, pointing newer, alternative, function. safe ignore warnings, deprecated functions longer receive updates thus risk removed package future date. newer alternatives can handle types models smooths, especially case smooth_estimates().","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"new-features-0-7-0","dir":"Changelog","previous_headings":"","what":"New features","title":"gratia 0.7.0","text":"fitted_values() provides tidy wrapper around predict.gam() generating fitted values model. New covariate values can provided via argument data. credible interval fitted values returned, values can link (linear predictor) response scale. Note function returns expected values response. Hence, “fitted values” used instead “predictions” case new covariate values differentiate values case generating new response values fitted model. rootogram() draw() method produce rootograms diagnostic plots fitted models. Currently models fitted poisson(), nb(), negbin(), gaussian() families. New helper functions typical_values(), factor_combos() data_combos() quickly creating data sets producing predictions fitted models covariatess fixed come typical representative values. typical_values() new helper function return typical values covariates fitted model. returns value observation closest median numerical covariates modal level factor preserving levels factor. typical_values() useful preparing data slices scenarios fitted values estimated model required. factor_combos() extracts returns combinations levels factors found data used fit model. Unlike typical_values(), factor_combos() returns combinations factor levels observed data, just modal level. Optionally, combinations factor levels can returned, just observed data. data_combos() combines returns factor data factor_combos() plus typical values numerical covariates. useful want generate predictions model combination factor terms holding continuous covariates median values. nb_theta() new extractor function returns theta parameter fitted negative binomial GAM (families nb() negbin()). Additionally, theta() has_theta() provide additional functionality. theta() experimental function extracting additional parameters model family. has_theta() useful checking additional parameters available family model. edf() extracts effective degrees freedom (EDF) fitted model specific smooth model. Various forms EDF can extracted. model_edf() returns EDF overall model. supplied multiple models, EDFs model returned comparison. draw.gam() can now show “rug” plot bivariate smooth drawing small points high transparency smooth surface data coordinates. addition, rugs plots factor smooths now show locations covariate values specific level factor levels. better reflects data used estimate smooth, even though basis smooth set using covariate locations. draw.gam() draw.smooth_estimates() now allow aspects plot changed: fill (colour) alpha attributes credible interval, line colour smooth can now specified using arguments ci_col, ci_alpha, smooth_col respectively. Partial residuals can now plotted factor smooths. allow , partial residuals filtered residuals associated particular level’s smooth drawn plot smooth. smooth_estimates() uses check_user_select_smooths() handle user-specified selection smooth terms. flexible previously, allows easier selection smooths evaluate. fixef() now imported (re-exported) nlme package, methods models fitted gam() gamm(), extract fixed effects estimates fitted models. fixed_effects() alias fixef(). draw() method smooth_samples() can now handle 2D smooths. Additionally, number posterior draws plot can now specified plotting using new argument n_samples, result n_samples draws selected random set draws plotting. New argument seed allows selection draws repeatable.","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"bug-fixes-0-7-0","dir":"Changelog","previous_headings":"","what":"Bug fixes","title":"gratia 0.7.0","text":"smooth_estimates() filtering user-supplied data level specific smooth used factor smooths. result smooth evaluated rows user-supplied data, therefore result nrow(user_data) * nlevels(by_variable) rows returned object instead nrow(user_data) rows. add_confint() method smooth_estimates() upper lower intervals reversed. #107 Reported @Aariq draw.gam() smooth_estimates() ignoring dist argument allows covariate values lie far support data excluded returning estimated values smooth plotting . #111 Reported @Aariq smooth_samples() factor GAM return samples first factor level . Reported @rroyaute discussion #121 smooth_samples() fail model contained random effect “smooths”. now ignored message running smooth_samples(). Reported @isabellaghement #121 link(), inv_link() failing models fitted family = scat(). Reported @Aariq #130","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"gratia-060","dir":"Changelog","previous_headings":"","what":"gratia 0.6.0","title":"gratia 0.6.0","text":"CRAN release: 2021-04-18","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"major-changes-0-6-0","dir":"Changelog","previous_headings":"","what":"Major changes","title":"gratia 0.6.0","text":"{cowplot} package replaced {patchwork} package producing multi-panel figures draw() appraise(). shouldn’t affect code used {gratia} , passed additional arguments cowplot::plot_grid() used align axis arguments draw() appraise(), ’ll need adapt code accordingly. Typically, can simply delete align axis arguments {patchwork} just work align plots nicely. arguments passed via ... cowplot::plot_grid() just ignored patchwork::wrap_plots() unless passed arguments match arguments patchwork::wrap_plots().","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"new-features-0-6-0","dir":"Changelog","previous_headings":"","what":"New features","title":"gratia 0.6.0","text":"{patchwork} package now used multi-panel figures. , {gratia} longer Imports {cowplot} package. Worm plot diagnostic plots available via new function worm_plot(). Worm plots detrended Q-Q plots, deviation Q-Q reference line emphasized deviations around line occupy full height plot. worm_plot() methods available models classes \"gam\", \"glm\", \"lm\". (#62) Smooths can now compared across models using compare_smooths(), comparisons visualised associated draw() method. (#85 @dill) feature bit experimental; returned object uses nested lists may change future users find confusing. reference line qq_plot() method = \"normal\" previously drawn line intercept 0 slope 1, match methods. inconsistent stats::qqplot() drew line 1st 3rd quartiles. qq_plot() method = \"normal\" now uses robust reference line. Reference lines methods remain drawn slope 1 intercept 0. qq_plot() method = \"normal\" now draws point-wise reference band using standard error order statistic. draw() method penalty() now plots penalty matrix heatmaps -logical orientation, match matrices might written printed R console. link(), inv_link() now work models fitted gumbls() shash() families. (#84) extract_link() lower level utility function related link() inv_link(), now exported.","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"user-visible-changes-0-6-0","dir":"Changelog","previous_headings":"","what":"User visible changes","title":"gratia 0.6.0","text":"default method name generating reference quantiles qq_plot() changed \"direct\" \"uniform\", avoid confusion mgcv::qq.gam() help page description methods. Accordingly using method = \"direct\" deprecated message effect displayed used. way smooths/terms selected derivatives() switched use mechanism draw.gam()’s select argument. get partial match term, now need also specify partial_match = TRUE call derivatives().","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"bug-fixes-0-6-0","dir":"Changelog","previous_headings":"","what":"Bug fixes","title":"gratia 0.6.0","text":"transform_fun() copy paste bug definition generic. (#96 @Aariq) derivatives() user-supplied newdata fail factor smooths interval = \"simultaneous\" introduce rows derivative == 0 interval = \"confidence\" didn’t subset rows newdata specific level factor computing derivatives. (#102 @sambweber) evaluate_smooth() can now handle random effect smooths defined using ordered factor. (#99 @StefanoMezzini)","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"gratia-051","dir":"Changelog","previous_headings":"","what":"gratia 0.5.1","title":"gratia 0.5.1","text":"CRAN release: 2021-01-23","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"new-features-0-5-1","dir":"Changelog","previous_headings":"","what":"New features","title":"gratia 0.5.1","text":"smooth_estimates() can now handle bivariate multivariate thinplate regression spline smooths, e.g.  s(x, z, ), tensor product smooths (te(), t2(), & ti()), e.g. te(x, z, ) factor smooth interactions, e.g. s(x, f, bs = \"fs\") random effect smooths, e.g. s(f, bs = \"re\") penalty() provides tidy representation penalty matrices smooths. tidy representation suitable plotting ggplot(). draw() method provided, represents penalty matrix heatmap.","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"user-visible-changes-0-5-1","dir":"Changelog","previous_headings":"","what":"User visible changes","title":"gratia 0.5.1","text":"newdata argument smooth_estimates() changed data originally intended.","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"gratia-050","dir":"Changelog","previous_headings":"","what":"gratia 0.5.0","title":"gratia 0.5.0","text":"CRAN release: 2021-01-10","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"new-features-0-5-0","dir":"Changelog","previous_headings":"","what":"New features","title":"gratia 0.5.0","text":"Partial residuals models can computed partial_residuals(). partial residuals weighted residuals model added contribution smooth term (returned predict(model, type = \"terms\"). Wish #76 (@noamross) Also, new function add_partial_residuals() can used add partial residuals data frames. Users can now control extent colour fill scales used plotting smooths draw() methods use . useful change fill scale plotting 2D smooths, change discrete colour scale used plotting random factor smooths (bs = \"fs\"). user can pass scales via arguments discrete_colour continuous_fill. effects certain smooths can excluded data simulated model using simulate.gam() predicted_samples() passing exclude terms predict.gam(). allows excluding random effects, example, model predicted values used simulate new data conditional distribution. See example predicted_samples(). Wish #74 (@hgoldspiel) draw.gam() related functions gain arguments constant fun allow user-defined constants transformations smooth estimates confidence intervals applied. Part wish Wish #79. confint.gam() now works 2D smooths also. smooth_estimates() early version code replace (likely supersede) evaluate_smooth(). smooth_estimates() can currently handle 1D smooths standard types.","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"user-visible-changes-0-5-0","dir":"Changelog","previous_headings":"","what":"User visible changes","title":"gratia 0.5.0","text":"meaning parm confint.gam changed. argument now requires smooth label match smooth. vector labels can provided, partial matching smooth label works single parm value. default behaviour remains unchanged however; parm NULL smooths evaluated returned confidence intervals. data_class() longer exported; ever intended internal function.","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"bug-fixes-0-5-0","dir":"Changelog","previous_headings":"","what":"Bug Fixes","title":"gratia 0.5.0","text":"confint.gam() failing tensor product smooth due matching issues. Reported @tamas-ferenci #88 also fixes #80 related issue selecting specific smooth. vdiffr package now used conditionally package tests. Reported Brian Ripley #93","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"gratia-041","dir":"Changelog","previous_headings":"","what":"gratia 0.4.1","title":"gratia 0.4.1","text":"CRAN release: 2020-05-30","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"user-visible-changes-0-4-1","dir":"Changelog","previous_headings":"","what":"User visible changes","title":"gratia 0.4.1","text":"draw.gam() scales = \"fixed\" now applies terms can plotted, including 2d smooths. Reported @StefanoMezzini #73","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"bug-fixes-0-4-1","dir":"Changelog","previous_headings":"","what":"Bug fixes","title":"gratia 0.4.1","text":"dplyr::combine() deprecated. Switch vctrs::vec_c(). draw.gam() scales = \"fixed\" wasn’t using fixed scales 2d smooths model. Reported @StefanoMezzini #73","code":""},{"path":[]},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"new-features-0-4-0","dir":"Changelog","previous_headings":"","what":"New features","title":"gratia 0.4.0","text":"draw.gam() can include partial residuals drawing univariate smooths. Use residuals = TRUE add partial residuals univariate smooth drawn. feature available smooths one variable, smooths, factor-smooth interactions (bs = \"fs\"). coverage credible confidence intervals drawn draw.gam() can specified via argument ci_level. default arbitrarily 0.95 reason (rough) compatibility plot.gam(). change effect making intervals slightly narrower previous versions gratia; intervals drawn ± 2 × standard error. default intervals now drawn ± ~1.96 × standard error. New function difference_smooths() computing differences factor smooth interactions. Methods available gam(), bam(), gamm() gamm4::gamm4(). Also draw() method, can handle differences 1D 2D smooths currently (handling 3D 4D smooths planned). New functions add_fitted() add_residuals() add fitted values (expectations) model residuals existing data frame. Currently methods available objects fitted gam() bam(). data_sim() tidy reimplementation mgcv::gamSim() added ability use sampling distributions Gaussian models implemented. Currently Gaussian, Poisson, Bernoulli sampling distributions available. smooth_samples() can handle continuous variable smooths varying coefficient models. link() inv_link() now work families available mgcv, including location, scale, shape families, specialised families described ?mgcv::family.mgcv. evaluate_smooth(), data_slice(), family(), link(), inv_link() methods models fitted using gamm4() gamm4 package. data_slice() can generate data 1-d slice (single variable varying). colour points, reference lines, simulation band appraise() can now specified via arguments point_col, point_alpha, ci_col ci_alpha line_col passed qq_plot(), observed_fitted_plot(), residuals_linpred_plot(), residuals_hist_plot(), also now take new arguments applicable. Added utility functions is_factor_term() term_variables() working models. is_factor_term() identifies named term factor using information terms() object fitted model. term_variables() returns character vector variable names involved model term. strictly working parametric terms models. appraise() now works models fitted glm() lm(), underlying functions calls, especially qq_plot. appraise() also works models fitted family gaulss(). location scale models models fitted extended family functions supported upcoming releases.","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"user-visible-changes-0-4-0","dir":"Changelog","previous_headings":"","what":"User visible changes","title":"gratia 0.4.0","text":"datagen() now internal function longer exported. Use data_slice() instead. evaluate_parametric_term() now much stricter can evaluate main effect terms, .e. whose order, stored terms object model 1.","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"bug-fixes-0-4-0","dir":"Changelog","previous_headings":"","what":"Bug fixes","title":"gratia 0.4.0","text":"draw() method derivatives() getting x-axis label factor smooths correctly, instead using NA second subsequent levels factor. datagen() method class \"gam\" couldn’t possibly worked anything simplest models fail even simple factor smooths. issues fixed, behaviour datagen() changed, function now intended use users. Fixed issue models terms form factor1:factor2 incorrectly identified numeric parametric terms. #68","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"gratia-031","dir":"Changelog","previous_headings":"","what":"gratia 0.3.1","title":"gratia 0.3.1","text":"CRAN release: 2020-03-29","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"new-features-0-3-1","dir":"Changelog","previous_headings":"","what":"New features","title":"gratia 0.3.1","text":"New functions link() inv_link() access link function inverse fitted models family functions. Methods classes: \"glm\", \"gam\", \"bam\", \"gamm\" currently. #58 Adds explicit family() methods objects classes \"gam\", \"bam\", \"gamm\". derivatives() now handles non-numeric creating shifted data finite differences. Fixes problem stringsAsFactors = FALSE default R-devel. #64","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"bug-fixes-0-3-1","dir":"Changelog","previous_headings":"","what":"Bug fixes","title":"gratia 0.3.1","text":"Updated gratia work tibble versions >= 3.0","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"gratia-030","dir":"Changelog","previous_headings":"","what":"gratia 0.3.0","title":"gratia 0.3.0","text":"CRAN release: 2020-01-19","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"new-features-0-3-0","dir":"Changelog","previous_headings":"","what":"New features","title":"gratia 0.3.0","text":"gratia now uses mvnfast package random draws multivariate normal distribution (mvnfast::rmvn()). Contributed Henrik Singmann #28 New function basis() generating tidy representations basis expansions mgcv-like definition smooth, e.g. s(), te(), ti(), t2(). basic smooth types also simple draw() method plotting basis. basis() simple wrapper around mgcv::smoothCon() post processing basis model matrix tidy format. #42 New function smooth_samples() draw samples entire smooth functions posterior distribution. Also draw() method plotting posterior samples.","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"bug-fixes-0-3-0","dir":"Changelog","previous_headings":"","what":"Bug fixes","title":"gratia 0.3.0","text":"draw.gam() produce empty plots panels parametric terms 2 parametric terms model. Reported @sklayn #39. derivatives() now works factor smooths, including ordered factor smooths. function also now works correctly complex models multiple covariates/smooths. #47 derivatives() also now handles 'fs' smooths. Reported @tomand-uio #57. evaluate_parametric_term() hence draw.gam() fail ziplss() model ) gratia didn’t handle parametric terms models multiple linear predictors correctly, ii) gratia didn’t convert naming convention mgcv terms higher linear predictors. Reported @pboesu #45","code":""}] +[{"path":[]},{"path":"https://gavinsimpson.github.io/gratia/CODE_OF_CONDUCT.html","id":"our-pledge","dir":"","previous_headings":"","what":"Our Pledge","title":"Contributor Covenant Code of Conduct","text":"members, contributors, leaders pledge make participation community harassment-free experience everyone, regardless age, body size, visible invisible disability, ethnicity, sex characteristics, gender identity expression, level experience, education, socio-economic status, nationality, personal appearance, race, religion, sexual identity orientation. pledge act interact ways contribute open, welcoming, diverse, inclusive, healthy community.","code":""},{"path":"https://gavinsimpson.github.io/gratia/CODE_OF_CONDUCT.html","id":"our-standards","dir":"","previous_headings":"","what":"Our Standards","title":"Contributor Covenant Code of Conduct","text":"Examples behavior contributes positive environment community include: Demonstrating empathy kindness toward people respectful differing opinions, viewpoints, experiences Giving gracefully accepting constructive feedback Accepting responsibility apologizing affected mistakes, learning experience Focusing best just us individuals, overall community Examples unacceptable behavior include: use sexualized language imagery, sexual attention advances kind Trolling, insulting derogatory comments, personal political attacks Public private harassment Publishing others’ private information, physical email address, without explicit permission conduct reasonably considered inappropriate professional setting","code":""},{"path":"https://gavinsimpson.github.io/gratia/CODE_OF_CONDUCT.html","id":"enforcement-responsibilities","dir":"","previous_headings":"","what":"Enforcement Responsibilities","title":"Contributor Covenant Code of Conduct","text":"Community leaders responsible clarifying enforcing standards acceptable behavior take appropriate fair corrective action response behavior deem inappropriate, threatening, offensive, harmful. Community leaders right responsibility remove, edit, reject comments, commits, code, wiki edits, issues, contributions aligned Code Conduct, communicate reasons moderation decisions appropriate.","code":""},{"path":"https://gavinsimpson.github.io/gratia/CODE_OF_CONDUCT.html","id":"scope","dir":"","previous_headings":"","what":"Scope","title":"Contributor Covenant Code of Conduct","text":"Code Conduct applies within community spaces, also applies individual officially representing community public spaces. Examples representing community include using official e-mail address, posting via official social media account, acting appointed representative online offline event.","code":""},{"path":"https://gavinsimpson.github.io/gratia/CODE_OF_CONDUCT.html","id":"enforcement","dir":"","previous_headings":"","what":"Enforcement","title":"Contributor Covenant Code of Conduct","text":"Instances abusive, harassing, otherwise unacceptable behavior may reported package maintainer, Gavin Simpson (see email address CRAN package page) . complaints reviewed investigated promptly fairly. community leaders obligated respect privacy security reporter incident.","code":""},{"path":"https://gavinsimpson.github.io/gratia/CODE_OF_CONDUCT.html","id":"enforcement-guidelines","dir":"","previous_headings":"","what":"Enforcement Guidelines","title":"Contributor Covenant Code of Conduct","text":"Community leaders follow Community Impact Guidelines determining consequences action deem violation Code Conduct:","code":""},{"path":"https://gavinsimpson.github.io/gratia/CODE_OF_CONDUCT.html","id":"id_1-correction","dir":"","previous_headings":"Enforcement Guidelines","what":"1. Correction","title":"Contributor Covenant Code of Conduct","text":"Community Impact: Use inappropriate language behavior deemed unprofessional unwelcome community. Consequence: private, written warning community leaders, providing clarity around nature violation explanation behavior inappropriate. public apology may requested.","code":""},{"path":"https://gavinsimpson.github.io/gratia/CODE_OF_CONDUCT.html","id":"id_2-warning","dir":"","previous_headings":"Enforcement Guidelines","what":"2. Warning","title":"Contributor Covenant Code of Conduct","text":"Community Impact: violation single incident series actions. Consequence: warning consequences continued behavior. interaction people involved, including unsolicited interaction enforcing Code Conduct, specified period time. includes avoiding interactions community spaces well external channels like social media. Violating terms may lead temporary permanent ban.","code":""},{"path":"https://gavinsimpson.github.io/gratia/CODE_OF_CONDUCT.html","id":"id_3-temporary-ban","dir":"","previous_headings":"Enforcement Guidelines","what":"3. Temporary Ban","title":"Contributor Covenant Code of Conduct","text":"Community Impact: serious violation community standards, including sustained inappropriate behavior. Consequence: temporary ban sort interaction public communication community specified period time. public private interaction people involved, including unsolicited interaction enforcing Code Conduct, allowed period. Violating terms may lead permanent ban.","code":""},{"path":"https://gavinsimpson.github.io/gratia/CODE_OF_CONDUCT.html","id":"id_4-permanent-ban","dir":"","previous_headings":"Enforcement Guidelines","what":"4. Permanent Ban","title":"Contributor Covenant Code of Conduct","text":"Community Impact: Demonstrating pattern violation community standards, including sustained inappropriate behavior, harassment individual, aggression toward disparagement classes individuals. Consequence: permanent ban sort public interaction within community.","code":""},{"path":"https://gavinsimpson.github.io/gratia/CODE_OF_CONDUCT.html","id":"attribution","dir":"","previous_headings":"","what":"Attribution","title":"Contributor Covenant Code of Conduct","text":"Code Conduct adapted Contributor Covenant, version 2.0, available https://www.contributor-covenant.org/version/2/0/code_of_conduct.html. Community Impact Guidelines inspired Mozilla’s code conduct enforcement ladder. answers common questions code conduct, see FAQ https://www.contributor-covenant.org/faq. Translations available https://www.contributor-covenant.org/translations.","code":""},{"path":[]},{"path":"https://gavinsimpson.github.io/gratia/CONTRIBUTING.html","id":"something-isnt-working-right-or-generating-an-error","dir":"","previous_headings":"","what":"Something isn’t working right or generating an error","title":"Contributing","text":"something isn’t working, either might expect/want contrary documentation, probably bug missing feature. ’re getting error running {gratia}, ’s also likely bug, opportunity catch use-case wasn’t expecting. First, check issue hasn’t already fixed -development version Github. Install current development version {gratia} R-universe using issue remains, please file issue via Issues page. ’s OK report issue even ’re sure ’s problem, problem better described question, use Discussions page (see ). Feature requests welcome! problem {gratia} hit top TODO list quickly cen provide reproducible example demonstrating problem.","code":"install.packages(\"gratia\", repos = c( \"https://gavinsimpson.r-universe.dev\", \"https://cloud.r-project.org\" ))"},{"path":"https://gavinsimpson.github.io/gratia/CONTRIBUTING.html","id":"got-a-question-want-to-show-how-to-do-something-with-gratia","dir":"","previous_headings":"","what":"Got a question? Want to show how to do something with {gratia}?","title":"Contributing","text":"issue best described question, want know something {gratia}, cool example using {gratia} want share , please consider using Discussions page. ’re sure, can always ask issue Question (Use Q&category) , really bug, can easily create Issue discussion.","code":""},{"path":"https://gavinsimpson.github.io/gratia/CONTRIBUTING.html","id":"code-contributions","dir":"","previous_headings":"","what":"Code contributions","title":"Contributing","text":"Code contributions form Pull Requests always appreciated. suitable workflow: Fork repo Github account Clone version account machine account, e.g,. git clone https://github.com//gratia.git Make sure track progress upstream (.e., version gratis gavinsimpson/gratia) git remote add upstream https://github.com/gavinsimpson/gratia.git. making changes make sure pull changes upstream either git fetch upstream merge later git pull upstream fetch merge one step Make changes (bonus points making changes new feature branch) Push account Submit pull request home base gavinsimpson/gratia","code":""},{"path":"https://gavinsimpson.github.io/gratia/CONTRIBUTING.html","id":"development-tools--paradigm--ethos","dir":"","previous_headings":"Code contributions","what":"Development tools / paradigm / ethos","title":"Contributing","text":"Please note following contributing code: {gratia} tightly aligned tidyverse use {dplyr} related packages lot internally developing package. plan replacing code lower-level code using {vctrs}, right now development focus filling functionality package premature optimisation. original aim {gratia} provide {ggplot2} plotting smooths; please stick principle use plotting paradigm. aim {mgcv}-feature complete; {mgcv} can something terms plotting smooths, handling specialists smooths, etc, principle {gratia} support . aim general compatibility {mgcv}; {gratia} deviates {mgcv} things, needs good justification; example {gratia} deviates multivariate isotropic smooths fitted s() plotted, Dave Miller (@dill) argued convincingly way. Don’t add dependencies! Unless accompanied strong justification, want reduce dependencies increase number. ’m using {styler} style code, using 2 spaces indent. code written change, however. Respect 80 character line length limit. contribute functionality fix bug, please add test using {testthat} framework insure new things works correctly bug stays fixed. contributions must result new NOTES, WARNINGS, ERRORS running R CMD check ---cran; please check contributions Winbuilder example.","code":""},{"path":"https://gavinsimpson.github.io/gratia/CONTRIBUTING.html","id":"email","dir":"","previous_headings":"","what":"Email","title":"Contributing","text":"hate email! can email GMail address — ’s like can stop :-) — unless capture attention immediately label message {gratia}-related, quickly get swamped never seen . Even label , ’s guarantee ever get round replying; usually happens ’ll forget don’t remember check gratia label often. end result email , get response , tardy. infinitely better use Discussions Issues pages Github ask questions package report problems. Please don’t email work (academic) address (email address might find ) {gratia}. question GAMs, much better ask CrossValidated StackOverflow depending whether question statistical programming related. relates {gratia} can use Discussions page. Asking question public allows others reply public, contributes body knowledge easily available others. circumstances send email multiple addresses; quickest way get message trash.","code":""},{"path":"https://gavinsimpson.github.io/gratia/LICENSE.html","id":null,"dir":"","previous_headings":"","what":"The MIT License (MIT)","title":"The MIT License (MIT)","text":"Copyright (c) 2013-2024 Gavin L. Simpson Permission hereby granted, free charge, person obtaining copy software associated documentation files (“Software”), deal Software without restriction, including without limitation rights use, copy, modify, merge, publish, distribute, sublicense, /sell copies Software, permit persons Software furnished , subject following conditions: copyright notice permission notice shall included copies substantial portions Software. SOFTWARE PROVIDED “”, WITHOUT WARRANTY KIND, EXPRESS IMPLIED, INCLUDING LIMITED WARRANTIES MERCHANTABILITY, FITNESS PARTICULAR PURPOSE NONINFRINGEMENT. EVENT SHALL AUTHORS COPYRIGHT HOLDERS LIABLE CLAIM, DAMAGES LIABILITY, WHETHER ACTION CONTRACT, TORT OTHERWISE, ARISING , CONNECTION SOFTWARE USE DEALINGS SOFTWARE.","code":""},{"path":"https://gavinsimpson.github.io/gratia/articles/custom-plotting.html","id":"background","dir":"Articles","previous_headings":"","what":"Background","title":"Customizing plots","text":"draw() function {gratia} envisaged ggplot-based alternative mgcv:::plot.gam(). , never intended allow sorts customization possible ggplot() packages use ggplot() plotting layer. largely due decision produce multiple separate ggplot() plots GAMs multiple smooths, subsequently combined single figure device, initially using {cowplot} recently {patchwork}. things way evident consider might represent smooths 3 4 variables (common might think; consider space-time models via te(x, y, time, d = c(2,1)) space-depth-time models [think ocean atmospheric data space depth (height), observed time] via te(x, y, depth, time, d = c(2, 1, 1))), require facets top produce small multiples, means can’t use facets plot separate smooths. Additional complications arise consider complex smooth types, splines sphere, might want us different coordinate systems geoms best represent underlying smooth. gone root combining multiple ggplot objects single figure, problem customizing plots quickly rears head. vignette presents solutions problem modifying adding plots produced draw() culminating example illustrating use {gratia}’s utility functions produce plots lower-lever components.","code":""},{"path":"https://gavinsimpson.github.io/gratia/articles/custom-plotting.html","id":"adding-layers-to-plots-with-the-operator","dir":"Articles","previous_headings":"","what":"Adding layers to plots with the & operator","title":"Customizing plots","text":"start simulating data fitting GAM four smooth functions default plot produced draw() want change theme plots, can’t append theme() layer p affects last plot patchwork1 One way apply theme plots patchwork & operator.","code":"library(\"gratia\") library(\"mgcv\") #> Loading required package: nlme #> This is mgcv 1.9-1. For overview type 'help(\"mgcv-package\")'. library(\"ggplot2\") library(\"dplyr\") #> #> Attaching package: 'dplyr' #> The following object is masked from 'package:nlme': #> #> collapse #> The following objects are masked from 'package:stats': #> #> filter, lag #> The following objects are masked from 'package:base': #> #> intersect, setdiff, setequal, union library(\"patchwork\") # simulate data n <- 400 eg1 <- data_sim(\"eg1\", n = n, seed = 1) # fit model m <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = eg1, method = \"REML\") p <- draw(m) p p + theme_bw() p & theme_bw()"},{"path":"https://gavinsimpson.github.io/gratia/articles/custom-plotting.html","id":"combining-individual-plots-produced-by-draw","dir":"Articles","previous_headings":"","what":"Combining individual plots produced by draw()","title":"Customizing plots","text":"draw() methods like draw.gam() return object created patchwork::wrap_plots(), result isn’t straightforward combine objects new patchwork avoid error, need use patchwork::plot_layout() set dimensions want achieved directly via draw() instructive know combine outputs draw() need arise, want create patchwork plots different models.","code":"p1 <- draw(m, select = \"s(x0)\") p2 <- draw(m, select = \"s(x1)\") p3 <- draw(m, select = \"s(x2)\") p1 + p2 + p3 #> Error in `wrap_dims()`: #> ! Need 3 panels, but together `nrow` and `ncol` only provide 1. #> ℹ Please increase `ncol` and/or `nrow`. p1 + p2 + p3 + plot_layout(ncol = 3) draw(m, select = c(\"s(x0)\", \"s(x1)\", \"s(x2)\"), ncol = 3)"},{"path":"https://gavinsimpson.github.io/gratia/articles/custom-plotting.html","id":"building-your-own-plot-by-hand","dir":"Articles","previous_headings":"","what":"Building your own plot by hand","title":"Customizing plots","text":"{gratia} provides high-level functions like draw() get good graphical overview fitted model, little option customisation — isn’t possible desirable allow possible customisation options fatures {ggplot2} single function. Think many arguments require! Instead, {gratia} also exports lower-level functions used draw() can create plot using whatever {ggplot2} functions make sense. next code blocks ’ll see plot created draw(m) can recreated hand using lower-level building blocks. main thing need evaluate smooths values covariates. done using smooth_estimates(). also need add credible interval evaluations, can done tidyverse-style via add_confint() default draw.gam() add partial residuals partial effects plots. achieve effect, need add partial residuals data used fit model. can done via add_partial_residuals() will2 add columns names \"s(x0)\". \"s(x1)\", etc. data. Now everything need recreate plots created draw.gam(). code block filter sm focus specific smooth, f(x2)f(x2) (\"s(x2)\"), add rug plot observed values x2, credible interval around estimated smooth, partial residuals point layer, estimated smooth line layer, annotation Assuming repeat steps smooths, creating plot objects p_sx0, p_sx1, p_sx2, p_sx3 (code shown), can complete plot creating patchwork desired number rows columns real benefit complete control data plotted can use power {ggplot2} map additional variables plot aesthetics. example, let’s assume factor variable original data want colour partial residuals according levels factor. Let’s create factor Now can modify plotting code map fac colour aesthetic plot partial residuals. save typing, ’ll reorder layers plot add partial residuals last can also simple model checking plotting smooth partial residuals coloured according one covariates (also plotting actual residuals covariates). code chunk , map covariate x1 colour size aesthetics (note deleted cex = 1.5 allow mapping size) resulting plot doesn’t show particular problems model way data simulated, hopefully illustrates can possible use low-level functions provided {gratia}.","code":"# evaluate the smooths sm <- smooth_estimates(m) |> add_confint() sm #> # A tibble: 400 × 11 #> .smooth .type .by .estimate .se x0 x1 x2 x3 .lower_ci #> #> 1 s(x0) TPRS NA -0.929 0.422 0.0131 NA NA NA -1.76 #> 2 s(x0) TPRS NA -0.881 0.396 0.0230 NA NA NA -1.66 #> 3 s(x0) TPRS NA -0.834 0.372 0.0329 NA NA NA -1.56 #> 4 s(x0) TPRS NA -0.786 0.348 0.0429 NA NA NA -1.47 #> 5 s(x0) TPRS NA -0.738 0.326 0.0528 NA NA NA -1.38 #> 6 s(x0) TPRS NA -0.690 0.305 0.0627 NA NA NA -1.29 #> 7 s(x0) TPRS NA -0.643 0.287 0.0727 NA NA NA -1.20 #> 8 s(x0) TPRS NA -0.595 0.270 0.0826 NA NA NA -1.12 #> 9 s(x0) TPRS NA -0.548 0.255 0.0925 NA NA NA -1.05 #> 10 s(x0) TPRS NA -0.501 0.242 0.102 NA NA NA -0.975 #> # ℹ 390 more rows #> # ℹ 1 more variable: .upper_ci # add partial residuals to data eg1 <- eg1 |> add_partial_residuals(m) names(eg1) #> [1] \"y\" \"x0\" \"x1\" \"x2\" \"x3\" \"f\" \"f0\" \"f1\" \"f2\" #> [10] \"f3\" \"s(x0)\" \"s(x1)\" \"s(x2)\" \"s(x3)\" p_sx2 <- sm |> filter(.smooth == \"s(x2)\") |> ggplot() + geom_rug(aes(x = x2), data = eg1, sides = \"b\", length = grid::unit(0.02, \"npc\") ) + geom_ribbon(aes(ymin = .lower_ci, ymax = .upper_ci, x = x2), alpha = 0.2 ) + geom_point(aes(x = x2, y = `s(x2)`), data = eg1, cex = 1.5, colour = \"steelblue3\" ) + geom_line(aes(x = x2, y = .estimate), lwd = 1.2) + labs(y = \"Partial effect\", title = \"s(x2)\") p_sx2 p_sx0 + p_sx1 + p_sx2 + p_sx3 + plot_layout(ncol = 2) set.seed(12) eg1 <- eg1 |> mutate(fac = sample(letters[1:4], n(), replace = TRUE)) plt <- sm |> filter(.smooth == \"s(x2)\") |> ggplot() + geom_rug(aes(x = x2), data = eg1, sides = \"b\", length = grid::unit(0.02, \"npc\") ) + geom_ribbon(aes(ymin = .lower_ci, ymax = .upper_ci, x = x2), alpha = 0.2 ) + geom_line(aes(x = x2, y = .estimate), lwd = 1.2) + labs(y = \"Partial effect\", title = \"s(x2)\") plt + geom_point( aes( x = x2, y = `s(x2)`, colour = fac ), # <-- map fac to colour aesthetic data = eg1, cex = 1.5 ) plt + geom_point( aes( x = x2, y = `s(x2)`, colour = x1, size = x1 ), # <-- map fac to colour aesthetic data = eg1, alpha = 0.3 ) + # <-- deleted cex!! scale_colour_viridis_c(option = \"plasma\")"},{"path":"https://gavinsimpson.github.io/gratia/articles/data-slices.html","id":"carbon-dioxide-uptake-in-grass-plants","dir":"Articles","previous_headings":"","what":"Carbon Dioxide Uptake in Grass Plants","title":"Data slices","text":"first example uses small data set experimental study cold tolerance grass Echinochloa crusgalli. data data frame CO2 provided {datasets} package ships R. One way model data allow different smooths combinations treatment type covariates can look fitted smooths using draw() might want compare model fitted values treatment types (origins), ignoring random effect component. want evaluate model range values covariate conc combinations factors. data slice covariate space, can create using data_slice(). create data slice conc Quebec type chilled treatment use Notice data_slice() filled something remaining covariates didn’t mention? case, data_slice() doesn’t know tt created, chosen modal level tt factor, correct choice case. Instead, need specify correct level explicitly tt created data slice, can predict model using combination covariate values specified slice. use predict.gam() , fitted_values() function {gratia} easier use, especially non-Gaussian models Notice excluded random effect term; even though specify something plant covariate can ignore term model using exclude argument. fitted_values() creates credible interval scale link function back-transforms response scale scale = \"response\", also default. Plotting fitted values data slice now requires simple {ggplot2} knowledge Next, let’s compare fitted effects treatment Mississippi origin plants , replaced automatically-generated tt variable correctly specified call fct_cross(), retaining levels type treatment factors. insures correct combinations corresponding treatment type factors also preserve original levels tt covariate created. can visualise fitted values data slice creating data slices, used helper functions specify covariate values slice. {gratia} provides several helper functions: evenly(x, n = 100) — creates n evenly spaced values range covariate, evenly(x, = 5 — creates evenly spaced values range covariate increments 5, evenly(x, ..., lower = 5, upper = 10) — either two uses evenly() shown use lower upper limits vector x. Arguments lower upper can used change one upper lower bounds. evenly(fct) — produces new factor containing level specified factor fct just , ref_level(fct) — creates new factor containing just reference level specified factor covariate fct, level(fct, \"level\") — creates factor requested \"level\" factor fct. cases involving factors, helper functions set levels factor match original model fit2. second argument data_slice() ... ... argument allows provide expressions create covariate values want data slice. Expressions passed ... evaluated within model frame fitted model (argument object) data (supplied). restricted either using helper functions provide {gratia}; R function used long makes sense context model frame, returns something can combined using tidyr::expand_grid().","code":"## data load and prep data(CO2, package = \"datasets\") plant <- CO2 |> as_tibble() |> rename(plant = Plant, type = Type, treatment = Treatment) |> mutate(plant = factor(plant, ordered = FALSE)) plant_ylab <- expression(CO[2] ~ uptake ~ (mu * mol ~ m^{-3})) plant_xlab <- expression(CO[2] ~ concentration ~ (mL ~ L^{-1})) plant |> ggplot(aes(x = conc, y = uptake, group = plant, colour = treatment)) + geom_point() + geom_line() + facet_wrap(~type) + labs(y = plant_ylab, x = plant_xlab, colour = \"Treatment\") plant <- plant |> mutate(tt = fct_cross(treatment, type)) m_plant <- gam(uptake ~ treatment * type + s(conc, by = tt, k = 6) + s(plant, bs = \"re\"), data = plant, method = \"REML\", family = Gamma(link = \"log\") ) overview(m_plant) #> #> Generalized Additive Model with 8 terms #> #> term type k edf statistic p.value #> #> 1 treatment parametric NA 1 1.59 0.2124864 #> 2 type parametric NA 1 11.2 0.0014830 #> 3 treatment:type parametric NA 1 7.45 0.0085489 #> 4 s(conc):ttnonchilled:Quebec TPRS 5 4.72 69.7 < 0.001 #> 5 s(conc):ttchilled:Quebec TPRS 5 4.71 86.5 < 0.001 #> 6 s(conc):ttnonchilled:Mississippi TPRS 5 4.62 74.1 < 0.001 #> 7 s(conc):ttchilled:Mississippi TPRS 5 4.39 25.3 < 0.001 #> 8 s(plant) Random effect 12 7.40 12.8 < 0.001 draw(m_plant, residuals = TRUE, scales = \"fixed\") ds1 <- data_slice(m_plant, conc = evenly(conc, n = 100), type = level(type, \"Quebec\"), treatment = level(treatment, \"chilled\") ) ds1 #> # A tibble: 100 × 5 #> conc type treatment tt plant #> #> 1 95 Quebec chilled nonchilled:Quebec Qn1 #> 2 104. Quebec chilled nonchilled:Quebec Qn1 #> 3 113. Quebec chilled nonchilled:Quebec Qn1 #> 4 122. Quebec chilled nonchilled:Quebec Qn1 #> 5 132. Quebec chilled nonchilled:Quebec Qn1 #> 6 141. Quebec chilled nonchilled:Quebec Qn1 #> 7 150. Quebec chilled nonchilled:Quebec Qn1 #> 8 159. Quebec chilled nonchilled:Quebec Qn1 #> 9 168. Quebec chilled nonchilled:Quebec Qn1 #> 10 177. Quebec chilled nonchilled:Quebec Qn1 #> # ℹ 90 more rows ds1 <- data_slice(m_plant, conc = evenly(conc, n = 100), treatment = level(treatment, \"chilled\"), type = level(type, \"Quebec\"), tt = level(tt, \"chilled:Quebec\") ) ds1 #> # A tibble: 100 × 5 #> conc treatment type tt plant #> #> 1 95 chilled Quebec chilled:Quebec Qn1 #> 2 104. chilled Quebec chilled:Quebec Qn1 #> 3 113. chilled Quebec chilled:Quebec Qn1 #> 4 122. chilled Quebec chilled:Quebec Qn1 #> 5 132. chilled Quebec chilled:Quebec Qn1 #> 6 141. chilled Quebec chilled:Quebec Qn1 #> 7 150. chilled Quebec chilled:Quebec Qn1 #> 8 159. chilled Quebec chilled:Quebec Qn1 #> 9 168. chilled Quebec chilled:Quebec Qn1 #> 10 177. chilled Quebec chilled:Quebec Qn1 #> # ℹ 90 more rows fv1 <- fitted_values(m_plant, data = ds1, scale = \"response\", exclude = \"s(plant)\") fv1 #> # A tibble: 100 × 10 #> .row conc treatment type tt plant .fitted .se .lower_ci .upper_ci #> #> 1 1 95 chilled Quebec chille… Qn1 13.0 0.0783 11.2 15.2 #> 2 2 104. chilled Quebec chille… Qn1 14.1 0.0757 12.1 16.3 #> 3 3 113. chilled Quebec chille… Qn1 15.2 0.0737 13.1 17.5 #> 4 4 122. chilled Quebec chille… Qn1 16.3 0.0722 14.2 18.8 #> 5 5 132. chilled Quebec chille… Qn1 17.6 0.0714 15.3 20.2 #> 6 6 141. chilled Quebec chille… Qn1 18.9 0.0711 16.4 21.7 #> 7 7 150. chilled Quebec chille… Qn1 20.2 0.0712 17.6 23.3 #> 8 8 159. chilled Quebec chille… Qn1 21.6 0.0716 18.8 24.9 #> 9 9 168. chilled Quebec chille… Qn1 23.0 0.0721 20.0 26.5 #> 10 10 177. chilled Quebec chille… Qn1 24.4 0.0726 21.2 28.1 #> # ℹ 90 more rows fv1 |> ggplot(aes(x = conc, y = .fitted)) + geom_point( data = plant |> filter(type == \"Quebec\", treatment == \"chilled\"), mapping = aes(y = uptake), alpha = 0.8, colour = \"steelblue\" ) + geom_ribbon(aes(ymin = .lower_ci, ymax = .upper_ci), alpha = 0.2) + geom_line() + labs( x = plant_xlab, y = plant_ylab, title = expression(Estimated ~ CO[2] ~ uptake), subtitle = \"Chilled plants of the Quebec type\" ) ds2 <- data_slice(m_plant, conc = evenly(conc, n = 100), treatment = evenly(treatment), type = level(type, \"Mississippi\") ) |> mutate(tt = fct_cross(treatment, type, keep_empty = TRUE)) ds2 #> # A tibble: 200 × 5 #> conc treatment type tt plant #> #> 1 95 nonchilled Mississippi nonchilled:Mississippi Qn1 #> 2 95 chilled Mississippi chilled:Mississippi Qn1 #> 3 104. nonchilled Mississippi nonchilled:Mississippi Qn1 #> 4 104. chilled Mississippi chilled:Mississippi Qn1 #> 5 113. nonchilled Mississippi nonchilled:Mississippi Qn1 #> 6 113. chilled Mississippi chilled:Mississippi Qn1 #> 7 122. nonchilled Mississippi nonchilled:Mississippi Qn1 #> 8 122. chilled Mississippi chilled:Mississippi Qn1 #> 9 132. nonchilled Mississippi nonchilled:Mississippi Qn1 #> 10 132. chilled Mississippi chilled:Mississippi Qn1 #> # ℹ 190 more rows fitted_values(m_plant, data = ds2, scale = \"response\", exclude = \"s(plant)\" ) |> ggplot(aes(x = conc, y = .fitted, group = treatment)) + geom_point( data = plant |> filter(type == \"Mississippi\"), mapping = aes(y = uptake, colour = treatment), alpha = 0.8 ) + geom_ribbon(aes(ymin = .lower_ci, ymax = .upper_ci, fill = treatment), alpha = 0.2 ) + geom_line(aes(colour = treatment)) + labs( x = plant_xlab, y = plant_ylab, title = expression(Estimated ~ CO[2] ~ uptake), subtitle = \"Comparison of treatment in plants of the Mississippi type\", colour = \"Treatment\", fill = \"Treatment\" ) args(gratia:::data_slice.gam) #> function (object, ..., data = NULL, envir = NULL) #> NULL"},{"path":"https://gavinsimpson.github.io/gratia/articles/data-slices.html","id":"slices-through-a-2d-smooth","dir":"Articles","previous_headings":"","what":"Slices through a 2D smooth","title":"Data slices","text":"second example, ’ll use bivariate example data set {mgcv} fit tensor product covariates x z aim example create univariate data slice 2D smooth user-specified values x holding z one fixed values. visualise effect smooth level, using smooth_estimates(), response level, using fitted_values().","code":"# simulate data from the bivariate surface df <- data_sim(\"eg2\", n = 1000, scale = 0.25, seed = 2) # fit the GAM m_biv <- gam(y ~ te(x, z), data = df, method = \"REML\")"},{"path":"https://gavinsimpson.github.io/gratia/articles/data-slices.html","id":"using-smooth_estimates","dir":"Articles","previous_headings":"Slices through a 2D smooth","what":"Using smooth_estimates()","title":"Data slices","text":"begin creating slice data space. also create label point nice axis label. evaluate smooth desired values add confidence interval can plot sm using {ggplot2} Note interval Marra Wood (2012) interval. doesn’t include uncertainty model constant term moment, unless smooth close linear shouldn’t make much difference. extends multiple slices asking several discrete z","code":"ds3 <- data_slice(m_biv, x = evenly(x, n = 100), z = quantile(z, probs = 0.25) ) z_val <- with(ds3, round(quantile(z, probs = 0.25), 2)) ylab <- bquote(hat(f)(x, .(z_val))) sm <- smooth_estimates(m_biv, select = \"te(x,z)\", data = ds3) |> add_confint() sm #> # A tibble: 100 × 9 #> .smooth .type .by .estimate .se x z .lower_ci .upper_ci #> #> 1 te(x,z) Tensor prod… NA 0.103 0.0583 6.63e-4 0.245 -0.0107 0.218 #> 2 te(x,z) Tensor prod… NA 0.122 0.0548 1.08e-2 0.245 0.0148 0.230 #> 3 te(x,z) Tensor prod… NA 0.141 0.0514 2.08e-2 0.245 0.0400 0.242 #> 4 te(x,z) Tensor prod… NA 0.159 0.0482 3.09e-2 0.245 0.0648 0.254 #> 5 te(x,z) Tensor prod… NA 0.177 0.0451 4.10e-2 0.245 0.0890 0.266 #> 6 te(x,z) Tensor prod… NA 0.195 0.0422 5.11e-2 0.245 0.113 0.278 #> 7 te(x,z) Tensor prod… NA 0.213 0.0396 6.12e-2 0.245 0.135 0.291 #> 8 te(x,z) Tensor prod… NA 0.230 0.0372 7.13e-2 0.245 0.157 0.303 #> 9 te(x,z) Tensor prod… NA 0.247 0.0351 8.14e-2 0.245 0.178 0.316 #> 10 te(x,z) Tensor prod… NA 0.263 0.0333 9.14e-2 0.245 0.198 0.328 #> # ℹ 90 more rows sm |> ggplot(aes(x = x, y = .estimate)) + geom_ribbon(aes(ymin = .lower_ci, ymax = .upper_ci), alpha = 0.2) + geom_line() + labs( title = \"Evaluation of smooth te(x,z) at fixed z\", y = ylab ) ds4 <- data_slice(m_biv, x = evenly(x, n = 100), z = round(quantile(z, probs = c(0.25, 0.5, 0.75)), 2) ) sm <- smooth_estimates(m_biv, select = \"te(x,z)\", data = ds4) |> add_confint() |> mutate(fz = factor(z)) sm |> ggplot(aes(x = x, y = .estimate, colour = fz, group = fz)) + geom_ribbon(aes(ymin = .lower_ci, ymax = .upper_ci, fill = fz, colour = NULL), alpha = 0.2 ) + geom_line() + labs( title = \"Evaluation of smooth te(x,z) at fixed z\", y = expression(hat(f)(x, z)), colour = \"z\", fill = \"z\" )"},{"path":"https://gavinsimpson.github.io/gratia/articles/data-slices.html","id":"using-fitted_samples","dir":"Articles","previous_headings":"Slices through a 2D smooth","what":"Using fitted_samples()","title":"Data slices","text":"want evaluate surface x fixed z conditional upon values covariates (model predicted fitted values) fitted_samples() tidy wrapper predict.gam(). single z multiple z difference now model constant included well uncertainty.","code":"fitted_values(m_biv, data = ds3) |> # default is response scale, not link ggplot(aes(x = x, y = .fitted)) + geom_ribbon(aes(ymin = .lower_ci, ymax = .upper_ci), alpha = 0.2) + geom_line() + labs( title = \"Fitted values from model\", y = expression(hat(y)) ) fitted_values(m_biv, data = ds4) |> mutate(fz = factor(z)) |> ggplot(aes(x = x, y = .fitted, colour = fz, group = fz)) + geom_ribbon(aes(ymin = .lower_ci, ymax = .upper_ci, fill = fz, colour = NULL), alpha = 0.2 ) + geom_line() + labs( title = \"Fitted values from model\", y = expression(hat(y)), colour = \"z\", fill = \"z\" )"},{"path":"https://gavinsimpson.github.io/gratia/articles/gratia.html","id":"plotting","dir":"Articles","previous_headings":"","what":"Plotting","title":"Getting started with gratia","text":"gratia provides draw() function produce plots using ggplot2 📦. draw estimated smooths GAM fitted , use intended reasonable overview estimated model, offers limited option modify resulting plot. want full control, can obtain data used create plot smooth_estimates() evaluate smooths unevenly spaced values range covariate(s). want evaluate selected smooths, can specify via smooth argument. takes smooth labels names smooths known mgcv. list labels smooths use evaluate f(x2)f(x_2) use can generate plot using ggplot2 package, example","code":"draw(m) sm <- smooth_estimates(m) sm #> # A tibble: 400 × 9 #> .smooth .type .by .estimate .se x0 x1 x2 x3 #> #> 1 s(x0) TPRS NA -1.32 0.390 0.000239 NA NA NA #> 2 s(x0) TPRS NA -1.24 0.365 0.0103 NA NA NA #> 3 s(x0) TPRS NA -1.17 0.340 0.0204 NA NA NA #> 4 s(x0) TPRS NA -1.09 0.318 0.0304 NA NA NA #> 5 s(x0) TPRS NA -1.02 0.297 0.0405 NA NA NA #> 6 s(x0) TPRS NA -0.947 0.279 0.0506 NA NA NA #> 7 s(x0) TPRS NA -0.875 0.263 0.0606 NA NA NA #> 8 s(x0) TPRS NA -0.803 0.249 0.0707 NA NA NA #> 9 s(x0) TPRS NA -0.732 0.237 0.0807 NA NA NA #> 10 s(x0) TPRS NA -0.662 0.228 0.0908 NA NA NA #> # ℹ 390 more rows smooths(m) #> [1] \"s(x0)\" \"s(x1)\" \"s(x2)\" \"s(x3)\" sm <- smooth_estimates(m, smooth = \"s(x2)\") #> Warning: The `smooth` argument of `smooth_estimates()` is deprecated as of gratia #> 0.8.9.9. #> ℹ Please use the `select` argument instead. #> This warning is displayed once every 8 hours. #> Call `lifecycle::last_lifecycle_warnings()` to see where this warning was #> generated. sm #> # A tibble: 100 × 6 #> .smooth .type .by .estimate .se x2 #> #> 1 s(x2) TPRS NA -4.47 0.476 0.00359 #> 2 s(x2) TPRS NA -4.00 0.406 0.0136 #> 3 s(x2) TPRS NA -3.53 0.345 0.0237 #> 4 s(x2) TPRS NA -3.06 0.295 0.0338 #> 5 s(x2) TPRS NA -2.58 0.263 0.0438 #> 6 s(x2) TPRS NA -2.09 0.250 0.0539 #> 7 s(x2) TPRS NA -1.59 0.253 0.0639 #> 8 s(x2) TPRS NA -1.08 0.264 0.0740 #> 9 s(x2) TPRS NA -0.564 0.278 0.0841 #> 10 s(x2) TPRS NA -0.0364 0.289 0.0941 #> # ℹ 90 more rows library(\"ggplot2\") library(\"dplyr\") #> #> Attaching package: 'dplyr' #> The following object is masked from 'package:nlme': #> #> collapse #> The following objects are masked from 'package:stats': #> #> filter, lag #> The following objects are masked from 'package:base': #> #> intersect, setdiff, setequal, union sm |> add_confint() |> ggplot(aes(y = .estimate, x = x2)) + geom_ribbon(aes(ymin = .lower_ci, ymax = .upper_ci), alpha = 0.2, fill = \"forestgreen\" ) + geom_line(colour = \"forestgreen\", linewidth = 1.5) + labs( y = \"Partial effect\", title = expression(\"Partial effect of\" ~ f(x[2])), x = expression(x[2]) )"},{"path":"https://gavinsimpson.github.io/gratia/articles/gratia.html","id":"model-diagnostics","dir":"Articles","previous_headings":"","what":"Model diagnostics","title":"Getting started with gratia","text":"appraise() function provides standard diagnostic plots GAMs plots produced (left--right, top--bottom), quantile-quantile (QQ) plot deviance residuals, scatterplot deviance residuals linear predictor, histogram deviance residuals, scatterplot observed vs fitted values. Adding partial residuals partial effect plots produced draw() can also help diagnose problems model, oversmoothing","code":"appraise(m) draw(m, residuals = TRUE)"},{"path":"https://gavinsimpson.github.io/gratia/articles/gratia.html","id":"want-to-learn-more","dir":"Articles","previous_headings":"","what":"Want to learn more?","title":"Getting started with gratia","text":"gratia active development area development currently lacking documentation. find package, look help pages package look examples code help get going.","code":""},{"path":"https://gavinsimpson.github.io/gratia/articles/posterior-simulation.html","id":"what-are-we-simulating","dir":"Articles","previous_headings":"","what":"What are we simulating?","title":"Posterior Simulation","text":"Posterior simulation involves randomly sampling MVN(𝛃̂,𝐕b)\\text{MVN}(\\hat{\\boldsymbol{\\beta}}, \\mathbf{V}_{\\text{b}}) EF(μi,ϕ)\\text{EF}(\\mu_i, \\phi), . might simulate posterior distribution single estimated smooth function see uncertainty estimate function. simulate just subset βj⋅\\beta_{j \\cdot} associated fjf_j interest. Instead, might interested uncertainty expectation (expected value) model given values covariates, case can simulate 𝛃\\boldsymbol{\\beta} sample posterior 𝔼(yi)\\mathbb{E}(y_i), fitted values model. might want generate new values response variable via draws conditional distribution response, simulating new response data 𝕪*\\mathbb{y}^{\\ast}, either observed 𝐱\\mathbf{x} new values $^{}, yi*|𝛈,𝐱∼EF(μî,ϕ)y^{\\ast}_i | \\boldsymbol{\\eta}, \\mathbf{x} \\sim \\text{EF}(\\hat{\\mu_i}, \\phi). Finally, can combine posterior simulation distributions generate posterior draws new data 𝕪*\\mathbb{y}^{\\ast} also include uncertainty expected values. gratia functionality options following functions smooth_samples() generates draws posterior distribution single estimated smooth functions, fitted_samples() generates draws posterior distribution 𝔼(yi|𝐗i=xi)\\mathbb{E}(y_i | \\mathbf{X}_i = x_i), expected value responss, predicted_samples(), generates new response data given supplied values covariates yi*|𝐗i=xi*y^{\\ast}_i | \\mathbf{X}_i = x^{\\ast}_i posterior_samples(), generates draws posterior distribution model, including uncertainty estimated parameters model. simpler terms, fitted_samples() generates predictions “average” expected value response values covariates. predictions include uncertainty estimated values model coefficients. contrast, posterior_samples() generates predictions actual values response might expect observe (model correct) given values covariates. predicted values include variance sampling distribution (error term). predicted_samples() lies somewhere two; predicted values include variation sampling distribution, take model fixed, known. worth reminding posterior draws conditional upon selected values smoothing parameter(s) λj\\lambda_j. act wiggliness estimated smooths known, actual fact estimated (selected perhaps better description) wiglinesses data model fitting. estimated GAM fitted method argument \"REML\", \"ML\", version 𝐕b\\mathbf{V}_{\\text{b}} corrected selected smoothing parameters, 𝐕c\\mathbf{V}_{\\text{c}}, generally available. allows, extent, posterior simulation account additional source uncertainty chosen values 𝛌\\boldsymbol{\\lambda}. two additional functions available gratia posterior simulation: simulate(), derivative_samples(). gratia provides simulate() methods models estimated using gam(), bam(), gamm(), well fitted via scam() scam package. simulate() base R convention thing predicted_samples(), just non-tidy way (pejorative; returns simulated response values matrix, arguably useful math statistical computation.) derivative_samples() provides draws posterior distribution derivative response variable small change focal covariate value. derivative_samples() less general version fitted_samples(); achieve thing two separate calls fitted_samples(). ’ll reserve discussion derivative_samples() separate vignette focused estimating derivatives GAMs. following sections ’ll look four main posterior simulation functions turn.","code":""},{"path":"https://gavinsimpson.github.io/gratia/articles/posterior-simulation.html","id":"posterior-smooths-and-smooth_samples","dir":"Articles","previous_headings":"","what":"Posterior smooths and smooth_samples()","title":"Posterior Simulation","text":"can sample posterior distribution coefficients particular smooth β̂j\\hat{\\beta}_j given values smoothing parameters 𝛌̂\\hat{\\boldsymbol{\\lambda}}. generate posterior samples smooths sampling 𝛃j⋆∼N(β̂j,𝐕β̂j)\\boldsymbol{\\beta}_{j\\star} \\sim N(\\hat{\\beta}_j, \\mathbf{V}_{\\hat{\\beta}_j}) forming 𝐗𝛃̂j𝛃j⋆𝖳\\mathbf{X}_{\\hat{\\boldsymbol{\\beta}}_j} \\boldsymbol{\\beta}_{j\\star}^{\\mathsf{T}}. sampling can done using smooth_samples(). illustrate , ’ll simulate data Gu & Wabha’s 4 smooth example, fit GAM simulated data simulating posterior distribution estimated smooth, sampling coefficients particular smooth. model, coefficients smooth f(x0)f(x_0) stored elements 2 10 coefficients vector. sample posterior distribution coefficients use smooth_samples() choosing particular smooth ’re interested using select argument; want sample smooths posteriors smooths model, select can left default value. Typically ’re bothered particular values covariate evaluate posterior smooths; ask 100 evenly spaced values x0 using n_vals, can provide covariates values via data argument. number posterior smooths sampled controlled argument n; ask 100 samples. Objects returned smooth_samples() draw() method available draw posterior smooths can set n_samples randomly select many smooths draw (seed can provided via argument seed make set chosen smooths repeatable.) credible interval smooth contain smooths. standard 95% credible interval, sampled smooths exceed limits interval. Following Marra & Wood (2012), blue credible interval contain average 95% grey lines (posterior smooths) given value x0x_0. across function frequentist interpretation credible interval implies values x0x_0 coverage less 95% values greater 95%.","code":"ss_df <- data_sim(\"eg1\", seed = 42) m_ss <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = ss_df, method = \"REML\") s_x0 <- get_smooth(m_ss, \"s(x0)\") smooth_coef_indices(s_x0) #> [1] 2 3 4 5 6 7 8 9 10 sm_samp <- smooth_samples(m_ss, select = \"s(x0)\", n_vals = 100, n = 100, seed = 21) sm_samp |> draw(alpha = 0.3) # evaluate the fitted smooth over x0 and add on a credible interval sm_est <- smooth_estimates(m_ss, select = \"s(x0)\") |> add_confint() # plot the smooth, credible interval, and posterior smooths sm_est |> ggplot(aes(x = x0)) + geom_lineribbon(aes(ymin = .lower_ci, ymax = .upper_ci), orientation = \"vertical\", fill = \"#56B4E9\", alpha = 0.5 ) + geom_line( data = sm_samp, aes(y = .value, group = .draw), alpha = 0.2 ) + geom_line(aes(y = .estimate), linewidth = 1, colour = \"#E69F00\") + labs(y = smooth_label(s_x0))"},{"path":"https://gavinsimpson.github.io/gratia/articles/posterior-simulation.html","id":"posterior-fitted-values-via-fitted_samples","dir":"Articles","previous_headings":"","what":"Posterior fitted values via fitted_samples()","title":"Posterior Simulation","text":"Posterior fitted values draws posterior distribution mean expected value response. expectations returned use predict() estimated GAM, except fitted_samples() includes uncertainty estimated model coefficients, whereas predict() just uses estimated coefficients. example, using data_sim() simulate data example 6 Luo & Wahba (1997) sin(2⋅(4x−2))+2⋅exp(−256⋅(x−0.5)2) \\sin(2 \\cdot (4x - 2)) + 2 \\cdot \\exp(-256 \\cdot (x - 0.5)^2) data fit adaptive smoother Next create data slice 200 values interval (0,1) ’ll predict model generate posterior fitted values compute fitted values new data posterior fitted values drawn fitted_samples() using Gaussian approximation posterior. just take 10 draws posterior observation new_df merge posterior draws data Adding posterior fitted samples plot data, superimposing Bayesian credible interval fitted values see posterior draws largely contained credible interval. difference smooth_samples() now ’re including effects model terms. simple model single smooth identity link, difference model constant term uncertainty included samples.","code":"f <- function(x) { sin(2 * ((4 * x) - 2)) + (2 * exp(-256 * (x - 0.5)^2)) } df <- data_sim(\"lwf6\", dist = \"normal\", scale = 0.3, seed = 2) plt <- df |> ggplot(aes(x = x, y = y)) + geom_point(alpha = 0.5) + geom_function(fun = f) plt m <- gam(y ~ s(x, k = 25, bs = \"ad\"), data = df, method = \"REML\") new_df <- data_slice(m, x = evenly(x, lower = 0, upper = 1, n = 200)) |> mutate(.row = row_number()) fv <- fitted_values(m, data = new_df) fs <- fitted_samples(m, data = new_df, n = 10, seed = 4) |> left_join(new_df |> select(.row, x), by = join_by(.row == .row)) plt + geom_ribbon(data = fv, aes(y = .fitted, ymin = .lower_ci, ymax = .upper_ci), fill = \"red\", alpha = 0.3) + geom_line(data = fs, aes(group = .draw, x = x, y = .fitted), colour = \"yellow\", alpha = 0.4)"},{"path":[]},{"path":"https://gavinsimpson.github.io/gratia/articles/posterior-simulation.html","id":"prediction-intervals","dir":"Articles","previous_headings":"Additional examples","what":"Prediction intervals","title":"Posterior Simulation","text":"One use posterior simulation generate prediction intervals fitted model. Prediction intervals include two sources uncertainty; estimated model , plus sampling uncertainty error arises drawing observations conditional distribution response. example, Gaussian GAM, first source uncertainty comes uncertainty estimates βj\\beta_j, model coefficients. uncertainty mean expected value response. second source uncertainty stems error term, estimated variance response. two parameters define conditional distribution YiY_i. value covariate(s) 𝐗\\mathbf{X}, estimated model defines entire distribution response values might expect observe covariate values. illustrate, ’ll fit simple GAM single smooth function data simulate Gu & Wabha’s function f2f_2 using data_sim(). simulate 400 values Gaussian distribution variance σ2=1\\sigma^2 = 1. simulated data, true function generated shown GAM data contains single smooth function x consider new value covariate x, x*=0.5x^{\\ast} = 0.5, expected value response given model, 𝔼(y*|x=x*)\\mathbb{E}(y^{*} | x = x^{*}), ~2.92, obtain using predict() value mean Gaussian distribution , model correct description data, describes distribution values YY might take x=0.5x = 0.5. Gaussian distribution defined two parameters; mean, μ\\mu, describes middle distribution, variance, σ2\\sigma^2, describes spread distribution mean. fully describe Gaussian distribution response x=0.5x = 0.5, need estimate variance. didn’t model explicitly GAM, get estimate model’s scale parameter, ϕ\\phi. stored element scale model object can visualise distribution looks like magic ggdist package orange region shows expected density response values x*=0.5x^{\\ast} = 0.5 model predicts expect observe. region assumes uncertainty estimate mean variance. Prediction intervals take account variation expected value, plus uncertainty expected value. fitted_values() conveniently returns uncertainty us, default 95% credible interval .se column standard error (standard deviation) estimated value (.fitted), .lower_ci .upper_ci lower upper uncertainty bounds (95% level) estimated value respectively. GAMs fitted mgcv don’t corresponding estimate uncertainty scale parameter, ϕ\\phi, model estimated standard deviation σ̂\\hat{\\sigma}. pretty easy compute upper lower tail quantiles fitted Gaussian distribution range values x get prediction interval, ’d ignoring uncertainty model estimates mean. Posterior simulation provides simple convenient way generate prediction interval includes model uncertainty, works principle families available mgcv (although practice, families currently supported gratia). compute prediction interval x GAM, creating set data evenly range x observed data used fit model added variable .row used later match posterior simulated values row prediction data set ds. also compute fitted values new observations using fitted_values(). step isn’t required order posterior simulation gratia, ’ll use fitted values later show model estimated values uncertainty contrast prediction interval. use posterior_samples() generate new response data new x values ds use join add prediction data draw asked 10000 posterior draws new value x. Ideally ’d generate least three four times many draws get precise estimate prediction interval, keep number low vignette avoid excessive computation time. ’re also using smoothness parameter selection corrected version Bayesian covariance matrix; matrix adjusted account us knowing value smoothing parameter f(xi)f(x_i). ps tibble, n * nrow(ds) rows. .draw variable groups simulated values posterior draw, .row groups posterior draws value x. summarise posterior draws using {dplyr} need function compute quantiles posterior distribution value x (.row). following function simple wrapper around quantile() function base R, arranges output quantile() data frame. apply function set posterior draws, grouping .row summarise separately posterior distribution new value x. reframe() used summarise posterior using quantile_fun() function. ease use, pivot resulting summary long wide format add covariate values joining .row variable 95% prediction interval shown first 10 rows prediction data. column labelled .q50 median posterior distribution. can now use various objects produced plot fitted values model (uncertainties), well prediction intervals just generated. add observed data used fit model black points, summarise posterior samples (ps) using hexagonal binning (avoid plotting 2 million posterior samples) outermost pair blue lines plot prediction interval created. interval encloses, expected, almost observe data points. also encloses, design, posterior samples, indicated filled hexagonal bins, warmer colours indicating larger counts posterior draws.","code":"df <- data_sim(\"gwf2\", n = 400, scale = 1, dist = \"normal\", seed = 8) df |> ggplot(aes(x = x, y = y)) + geom_point() + geom_function(fun = gw_f2, colour = \"#0072B2\", linewidth = 1.5) m <- gam(y ~ s(x), data = df, method = \"REML\", family = gaussian()) mu <- predict(m, newdata = data.frame(x = 0.5)) mu #> 1 #> 2.919094 sigma <- m$scale sigma #> [1] 1.019426 df |> ggplot(aes(x = x, y = y)) + stat_halfeye(aes(ydist = dist_normal(mean = mu, sd = sigma)), x = 0.5, scale = 0.2, slab_fill = \"#E69F00\", slab_alpha = 0.7 ) + geom_point() + geom_function(fun = gw_f2, colour = \"#0072B2\", linewidth = 1.5) + geom_point(x = 0.5, y = mu, colour = \"red\") fitted_values(m, data = data.frame(x = 0.5)) #> # A tibble: 1 × 6 #> .row x .fitted .se .lower_ci .upper_ci #> #> 1 1 0.5 2.92 0.161 2.60 3.23 ds <- data_slice(m, x = evenly(x, n = 200)) |> mutate(.row = row_number()) fv <- fitted_values(m, data = ds) ps <- posterior_samples(m, n = 10000, data = ds, seed = 24, unconditional = TRUE) |> left_join(ds, by = join_by(.row == .row)) ps #> # A tibble: 2,000,000 × 4 #> .row .draw .response x #> #> 1 1 1 -1.34 0.00129 #> 2 2 1 -0.0495 0.00629 #> 3 3 1 0.0308 0.0113 #> 4 4 1 -0.783 0.0163 #> 5 5 1 0.861 0.0213 #> 6 6 1 0.475 0.0263 #> 7 7 1 0.858 0.0313 #> 8 8 1 0.143 0.0363 #> 9 9 1 -0.0344 0.0413 #> 10 10 1 1.04 0.0463 #> # ℹ 1,999,990 more rows quantile_fun <- function(x, probs = c(0.025, 0.5, 0.975), ...) { tibble::tibble( .value = quantile(x, probs = probs, ...), .q = probs * 100 ) } p_int <- ps |> group_by(.row) |> reframe(quantile_fun(.response)) |> pivot_wider( id_cols = .row, names_from = .q, values_from = .value, names_prefix = \".q\" ) |> left_join(ds, by = join_by(.row == .row)) p_int #> # A tibble: 200 × 5 #> .row .q2.5 .q50 .q97.5 x #> #> 1 1 -2.84 -0.847 1.25 0.00129 #> 2 2 -2.70 -0.651 1.41 0.00629 #> 3 3 -2.50 -0.434 1.62 0.0113 #> 4 4 -2.24 -0.207 1.83 0.0163 #> 5 5 -2.04 -0.0197 2.01 0.0213 #> 6 6 -1.81 0.191 2.25 0.0263 #> 7 7 -1.59 0.391 2.41 0.0313 #> 8 8 -1.38 0.594 2.60 0.0363 #> 9 9 -1.20 0.831 2.84 0.0413 #> 10 10 -0.935 1.06 3.04 0.0463 #> # ℹ 190 more rows fv |> ggplot(aes(x = x, y = .fitted)) + # summarise the posterior samples geom_hex( data = ps, aes(x = x, y = .response, fill = after_stat(count)), bins = 50, alpha = 0.7 ) + # add the lower and upper prediction intervals geom_line(data = p_int, aes(y = .q2.5), colour = \"#56B4E9\", linewidth = 1.5) + geom_line(data = p_int, aes(y = .q97.5), colour = \"#56B4E9\", linewidth = 1.5) + # add the lower and upper credible intervals geom_line(aes(y = .lower_ci), colour = \"#56B4E9\", linewidth = 1) + geom_line(aes(y = .upper_ci), colour = \"#56B4E9\", linewidth = 1) + # add the fitted model geom_line() + # add the observed data geom_point(data = df, aes(x = x, y = y)) + scale_fill_viridis_c(option = \"plasma\") + theme(legend.position = \"none\") + labs(y = \"Response\")"},{"path":"https://gavinsimpson.github.io/gratia/articles/posterior-simulation.html","id":"metropolis-hastings-sampler","dir":"Articles","previous_headings":"Additional examples","what":"Metropolis Hastings sampler","title":"Posterior Simulation","text":"cases, Gaussian approximation posterior distribution model coefficients can fail. Simon Wood shows example just failure ?gam.mh help page, Gaussian approximation basically useless binomial GAM large numbers zeroes. mgcv::gam.mh() implements simple Metropolis Hastings sampler, alternates proposals Gaussian t distribution approximation posterior random walk proposals based shrunken approximate posterior covariance matrix. section, rework Simon’s example failure Gaussian approximation ?gam.mh show use gratia generate posterior draws using Metropolis Hastings sampler provided gam.mh(). begin defining function simulate data example. use simulate data set plot Note zeroes large parts covariate space response zeroes. fit binomial (logistic) GAM data generate sample posterior distribution using default Gaussian approximation subsequently using simpler Metropolis Hastings sampler. method argument used select Metropolis Hastings sampler, specify two additional arguments: thin, controls many draws skipped retained sample, rw_scale, scaling factor posterior covariance matrix shrunk random walk proposals. leave two important arguments defaults: burnin = 1000, number samples discard prior sampling, t_df = 40, degrees freedom t proposals. degrees freedom t proposals large, ’re effectively Gaussian approximation default, alternating proposals random walk proposals. collected posterior draws, summarise set 50%, 80%, 95% intervals using ggdist::median_qi(), add data locations left join First plot intervals Gaussian approximation posterior, repeat plot using intervals derived Metropolis Hastings sampler, arranging two plots using patchwork Gaussian approximation-based intervals shown left figure, range x largely useless, covering entire range response, despite fact observed zeroes large parts covariate space. Contrast intervals ones obtained using Metropolis Hastings sampler; intervals much better reflect uncertainty estimated response function x data zeroes.","code":"ga_fail <- function(seed) { df <- tibble(y = c( rep(0, 89), 1, 0, 1, 0, 0, 1, rep(0, 13), 1, 0, 0, 1, rep(0, 10), 1, 0, 0, 1, 1, 0, 1, rep(0, 4), 1, rep(0, 3), 1, rep(0, 3), 1, rep(0, 10), 1, rep(0, 4), 1, 0, 1, 0, 0, rep(1, 4), 0, rep(1, 5), rep(0, 4), 1, 1, rep(0, 46) )) |> mutate( x = withr::with_seed( seed, sort(c(0:10 * 5, rnorm(length(y) - 11) * 20 + 100)) ), .row = row_number() ) |> relocate(.row, .before = 1L) df } df <- ga_fail(3) df |> ggplot(aes(x = x, y = y)) + geom_point() m_logit <- gam(y ~ s(x, k = 15), data = df, method = \"REML\", family = binomial) fs_ga <- fitted_samples(m_logit, n = 2000, seed = 2) fs_mh <- fitted_samples(m_logit, n = 2000, seed = 2, method = \"mh\", thin = 2, rw_scale = 0.4 ) excl_col <- c(\".draw\", \".parameter\", \".row\") int_ga <- fs_ga |> group_by(.row) |> median_qi(.width = c(0.5, 0.8, 0.95), .exclude = excl_col) |> left_join(df, by = join_by(.row == .row)) int_mh <- fs_mh |> group_by(.row) |> median_qi(.width = c(0.5, 0.8, 0.95), .exclude = excl_col) |> left_join(df, by = join_by(.row == .row)) plt_ga <- df |> ggplot(aes(x = x, y = y)) + geom_point() + geom_lineribbon( data = int_ga, aes(x = x, y = .fitted, ymin = .lower, ymax = .upper) ) + scale_fill_brewer() + labs(title = \"Gaussian approximation\") plt_mh <- df |> ggplot(aes(x = x, y = y)) + geom_point() + geom_lineribbon( data = int_mh, aes(x = x, y = .fitted, ymin = .lower, ymax = .upper) ) + scale_fill_brewer() + labs(title = \"Metropolis Hastings sampler\") plt_ga + plt_mh + plot_layout(guides = \"collect\")"},{"path":[]},{"path":"https://gavinsimpson.github.io/gratia/authors.html","id":null,"dir":"","previous_headings":"","what":"Authors","title":"Authors and Citation","text":"Gavin L. Simpson. Author, maintainer, copyright holder. Henrik Singmann. Contributor.","code":""},{"path":"https://gavinsimpson.github.io/gratia/authors.html","id":"citation","dir":"","previous_headings":"","what":"Citation","title":"Authors and Citation","text":"Simpson G (????). gratia: Graceful ggplot-Based Graphics Functions GAMs Fitted using mgcv. R package version 0.9.2.9012, https://gavinsimpson.github.io/gratia/.","code":"@Manual{, title = {{gratia}: Graceful {ggplot}-Based Graphics and Other Functions for {GAM}s Fitted using {mgcv}}, author = {Gavin L. Simpson}, abstract = {Graceful ggplot-based graphics and utility functions for working with generalized additive models (GAMs) fitted using the mgcv package. Provides a reimplementation of the plot() method for GAMs that mgcv provides, as well as tidyverse-compatible representations of estimated smooths.}, note = {R package version 0.9.2.9012}, url = {https://gavinsimpson.github.io/gratia/}, }"},{"path":[]},{"path":"https://gavinsimpson.github.io/gratia/index.html","id":"overview","dir":"","previous_headings":"","what":"Overview","title":"An R package for working with generalized additive models","text":"Working GAMs within ‘tidyverse’ can tedious even difficult without good understanding GAMs model returned ‘mgcv’ model objects contain. ‘gratia’ designed help . ‘gratia’ provides ‘ggplot’-based graphics utility functions working generalized additive models (GAMs) fitted using ‘mgcv’ package, via reimplementation plot() method GAMs ‘mgcv’ provides, well ‘tidyverse’ compatible representations estimated smooths.","code":""},{"path":"https://gavinsimpson.github.io/gratia/index.html","id":"features","dir":"","previous_headings":"","what":"Features","title":"An R package for working with generalized additive models","text":"main features gratia currently ggplot2-based replacement mgcv:::plot.gam(): draw.gam(). example, classic four term additive example Gu & Wahba: Estimated smooths GAM bivariate smooth: Estimated smooths GAM Note specialist smoothers (bs %% c(\"mrf\",\"sw\", \"sf\")) currently supported, univariate, factor continuous -variable smooths, simple random effect smooths (bs = 're'), factor-smooth interaction smooths (bs = \"fs\"), constrained factor smooths (bs = \"sz\"), full soap film smooths (bs = \"\"), bivariate, trivariate, quadvariate TPRS tensor product smooths supported, Estimation derivatives fitted smoothers: derivatives(), Estimation point-wise across--function confidence intervals simultaneous intervals smooths: confint.gam(). Model diagnostics via appraise() Model diagnostics figure","code":""},{"path":"https://gavinsimpson.github.io/gratia/index.html","id":"installing-gratia","dir":"","previous_headings":"","what":"Installing gratia","title":"An R package for working with generalized additive models","text":"gratia now available CRAN, can installed however gratia active development may wish install development version github. easiest way via install_github() function package remotes. Make sure remotes installed, run install package. Alternatively, binary packages development version available rOpenSci’s R Universe service:","code":"install.packages(\"gratia\") remotes::install_github(\"gavinsimpson/gratia\") # Install gratia in R install.packages(\"gratia\", repos = c( \"https://gavinsimpson.r-universe.dev\", \"https://cloud.r-project.org\" ))"},{"path":"https://gavinsimpson.github.io/gratia/index.html","id":"history","dir":"","previous_headings":"","what":"History","title":"An R package for working with generalized additive models","text":"gratia grew earlier package, schoenberg, development earlier package tsgam, originally intended used GAMs fitted time series. developing tsgam however became clear package used generally name “tsgam” longer appropriate. avoid breaking blog posts written using tsgam decided copy git repo history new repo package name schoenberg. later date someone released another package called schoenberg CRAN, scuppered idea. Now ’m calling package gratia. Hopefully won’t change …","code":""},{"path":"https://gavinsimpson.github.io/gratia/index.html","id":"why-gratia","dir":"","previous_headings":"","what":"Why gratia?","title":"An R package for working with generalized additive models","text":"naming greta package, Nick Golding observed recent phenomena naming statistical modelling software, Stan Edward, individuals played prominent role development field. lead Nick name Tensor Flow-based package greta Grete Hermann. spirit, gratia named recognition contributions Grace Wahba, pioneering work penalised spline models foundation way GAMs estimated mgcv. wanted name package grace, explicitly recognise Grace’s contributions, unfortunately already package named Grace CRAN. looked elsewhere inspiration. English word “grace” derives Latin gratia, meaning “favor, charm, thanks” (according Merriam Webster). chair Grace Wabha currently holds named Isaac J Schoenberg, former University Madison-Wisconsin Professor Mathematics, 1946 paper provided first mathematical reference “splines”. (Hence previous name package.)","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/add_confint.html","id":null,"dir":"Reference","previous_headings":"","what":"Add a confidence interval to an existing object — add_confint","title":"Add a confidence interval to an existing object — add_confint","text":"Add confidence interval existing object","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/add_confint.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Add a confidence interval to an existing object — add_confint","text":"","code":"add_confint(object, coverage = 0.95, ...) # S3 method for class 'smooth_estimates' add_confint(object, coverage = 0.95, ...) # S3 method for class 'parametric_effects' add_confint(object, coverage = 0.95, ...) # Default S3 method add_confint(object, coverage = 0.95, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/add_confint.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Add a confidence interval to an existing object — add_confint","text":"object R object. coverage numeric; coverage interval. Must range 0 < coverage < 1. ... arguments passed methods.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/add_constant.html","id":null,"dir":"Reference","previous_headings":"","what":"Add a constant to estimated values — add_constant","title":"Add a constant to estimated values — add_constant","text":"Add constant estimated values","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/add_constant.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Add a constant to estimated values — add_constant","text":"","code":"add_constant(object, constant = NULL, ...) # S3 method for class 'smooth_estimates' add_constant(object, constant = NULL, ...) # S3 method for class 'smooth_samples' add_constant(object, constant = NULL, ...) # S3 method for class 'mgcv_smooth' add_constant(object, constant = NULL, ...) # S3 method for class 'parametric_effects' add_constant(object, constant = NULL, ...) # S3 method for class 'tbl_df' add_constant(object, constant = NULL, column = NULL, ...) # S3 method for class 'evaluated_parametric_term' add_constant(object, constant = NULL, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/add_constant.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Add a constant to estimated values — add_constant","text":"object object add constant . constant constant add. ... additional arguments passed methods. column character; \"tbl_df\" method, column add constant .","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/add_constant.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Add a constant to estimated values — add_constant","text":"Returns object estimate shifted addition supplied constant.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/add_constant.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Add a constant to estimated values — add_constant","text":"Gavin L. Simpson","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/add_fitted.gam.html","id":null,"dir":"Reference","previous_headings":"","what":"Add fitted values from a GAM to a data frame — add_fitted.gam","title":"Add fitted values from a GAM to a data frame — add_fitted.gam","text":"Add fitted values GAM data frame","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/add_fitted.gam.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Add fitted values from a GAM to a data frame — add_fitted.gam","text":"","code":"# S3 method for class 'gam' add_fitted(data, model, value = \".fitted\", type = \"response\", ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/add_fitted.gam.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Add fitted values from a GAM to a data frame — add_fitted.gam","text":"data data frame containing values variables used fit model. Passed stats::predict() newdata. model fitted model stats::predict() method available. S3 method dispatch performed model argument. value character; name variable model predictions stored. type character; type predictions return. See mgcv::predict.gam() options. ... additional arguments passed mgcv::predict.gam().","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/add_fitted.gam.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Add fitted values from a GAM to a data frame — add_fitted.gam","text":"data frame (tibble) formed data predictions model.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/add_fitted.gam.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Add fitted values from a GAM to a data frame — add_fitted.gam","text":"","code":"load_mgcv() df <- data_sim(\"eg1\", seed = 1) df <- df[, c(\"y\", \"x0\", \"x1\", \"x2\", \"x3\")] m <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = df, method = \"REML\") # add fitted values to our data add_fitted(df, m) #> # A tibble: 400 x 6 #> y x0 x1 x2 x3 .fitted #> #> 1 3.34 0.266 0.659 0.859 0.367 5.90 #> 2 -0.0758 0.372 0.185 0.0344 0.741 3.15 #> 3 10.7 0.573 0.954 0.971 0.934 8.28 #> 4 8.73 0.908 0.898 0.745 0.673 8.65 #> 5 15.0 0.202 0.944 0.273 0.701 15.7 #> 6 7.67 0.898 0.724 0.677 0.848 8.38 #> 7 7.58 0.945 0.370 0.348 0.706 7.84 #> 8 8.51 0.661 0.781 0.947 0.859 6.74 #> 9 10.6 0.629 0.0111 0.339 0.446 9.14 #> 10 3.72 0.0618 0.940 0.0317 0.677 7.04 #> # i 390 more rows # with type = \"terms\" or \"iterms\" add_fitted(df, m, type = \"terms\") #> # A tibble: 400 x 10 #> y x0 x1 x2 x3 .constant `s(x0)` `s(x1)` `s(x2)` `s(x3)` #> #> 1 3.34 0.266 0.659 0.859 0.367 7.94 0.175 0.559 -2.81 0.0351 #> 2 -0.0758 0.372 0.185 0.0344 0.741 7.94 0.435 -1.92 -3.23 -0.0687 #> 3 10.7 0.573 0.954 0.971 0.934 7.94 0.593 3.35 -3.47 -0.122 #> 4 8.73 0.908 0.898 0.745 0.673 7.94 -0.812 2.77 -1.19 -0.0498 #> 5 15.0 0.202 0.944 0.273 0.701 7.94 -0.0589 3.23 4.63 -0.0576 #> 6 7.67 0.898 0.724 0.677 0.848 7.94 -0.745 1.15 0.146 -0.0981 #> 7 7.58 0.945 0.370 0.348 0.706 7.94 -1.07 -1.31 2.34 -0.0589 #> 8 8.51 0.661 0.781 0.947 0.859 7.94 0.434 1.67 -3.20 -0.101 #> 9 10.6 0.629 0.0111 0.339 0.446 7.94 0.512 -1.95 2.63 0.0132 #> 10 3.72 0.0618 0.940 0.0317 0.677 7.94 -0.695 3.20 -3.35 -0.0508 #> # i 390 more rows"},{"path":"https://gavinsimpson.github.io/gratia/reference/add_fitted.html","id":null,"dir":"Reference","previous_headings":"","what":"Add fitted values from a model to a data frame — add_fitted","title":"Add fitted values from a model to a data frame — add_fitted","text":"Add fitted values model data frame","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/add_fitted.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Add fitted values from a model to a data frame — add_fitted","text":"","code":"add_fitted(data, model, value = \".value\", ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/add_fitted.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Add fitted values from a model to a data frame — add_fitted","text":"data data frame containing values variables used fit model. Passed stats::predict() newdata. model fitted model stats::predict() method available. S3 method dispatch performed model argument. value character; name variable model predictions stored. ... additional arguments passed methods.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/add_fitted.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Add fitted values from a model to a data frame — add_fitted","text":"data frame (tibble) formed data fitted values model.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/add_fitted_samples.html","id":null,"dir":"Reference","previous_headings":"","what":"Add posterior draws from a model to a data object — add_fitted_samples","title":"Add posterior draws from a model to a data object — add_fitted_samples","text":"Adds draws posterior distribution model data object using one fitted_samples(), predicted_samples(), posterior_samples().","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/add_fitted_samples.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Add posterior draws from a model to a data object — add_fitted_samples","text":"","code":"add_fitted_samples(object, model, n = 1, seed = NULL, ...) add_predicted_samples(object, model, n = 1, seed = NULL, ...) add_posterior_samples(object, model, n = 1, seed = NULL, ...) add_smooth_samples(object, model, n = 1, seed = NULL, select = NULL, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/add_fitted_samples.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Add posterior draws from a model to a data object — add_fitted_samples","text":"object data frame tibble posterior draws added. model fitted GAM (GAM-like) object posterior draw method exists. n integer; number posterior draws add. seed numeric; value seed random number generator. ... arguments passed posterior draw function, currently one fitted_samples(), predicted_samples(), posterior_samples(). n seed already specified arguments also passed posterior sampling function. select character; select smooth's posterior draw . default, NULL, means posteriors smooths model wil sampled individually. supplied, character vector requested smooth terms.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/add_fitted_samples.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Add posterior draws from a model to a data object — add_fitted_samples","text":"","code":"load_mgcv() df <- data_sim(\"eg1\", n = 400, seed = 42) m <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = df, method = \"REML\") # add fitted samples (posterior draws of the expected value of the response) # note that there are 800 rows in the output: 400 data by `n = 2` samples. df |> add_fitted_samples(m, n = 2, seed = 84) #> # A tibble: 800 × 14 #> y x0 x1 x2 x3 f f0 f1 f2 f3 .row .draw #> #> 1 2.99 0.915 0.0227 0.909 0.402 1.62 0.529 1.05 0.0397 0 1 1 #> 2 2.99 0.915 0.0227 0.909 0.402 1.62 0.529 1.05 0.0397 0 1 2 #> 3 4.70 0.937 0.513 0.900 0.432 3.25 0.393 2.79 0.0630 0 2 1 #> 4 4.70 0.937 0.513 0.900 0.432 3.25 0.393 2.79 0.0630 0 2 2 #> 5 13.9 0.286 0.631 0.192 0.664 13.5 1.57 3.53 8.41 0 3 1 #> 6 13.9 0.286 0.631 0.192 0.664 13.5 1.57 3.53 8.41 0 3 2 #> 7 5.71 0.830 0.419 0.532 0.182 6.12 1.02 2.31 2.79 0 4 1 #> 8 5.71 0.830 0.419 0.532 0.182 6.12 1.02 2.31 2.79 0 4 2 #> 9 7.63 0.642 0.879 0.522 0.838 10.4 1.80 5.80 2.76 0 5 1 #> 10 7.63 0.642 0.879 0.522 0.838 10.4 1.80 5.80 2.76 0 5 2 #> # ℹ 790 more rows #> # ℹ 2 more variables: .parameter , .fitted # add posterior draws from smooth s(x2) df |> add_smooth_samples(m, n = 2, seed = 2, select= \"s(x2)\") #> # A tibble: 800 × 15 #> y x0 x1 x2 x3 f f0 f1 f2 f3 .row .smooth #> #> 1 2.99 0.915 0.0227 0.909 0.402 1.62 0.529 1.05 0.0397 0 1 s(x2) #> 2 2.99 0.915 0.0227 0.909 0.402 1.62 0.529 1.05 0.0397 0 1 s(x2) #> 3 4.70 0.937 0.513 0.900 0.432 3.25 0.393 2.79 0.0630 0 2 s(x2) #> 4 4.70 0.937 0.513 0.900 0.432 3.25 0.393 2.79 0.0630 0 2 s(x2) #> 5 13.9 0.286 0.631 0.192 0.664 13.5 1.57 3.53 8.41 0 3 s(x2) #> 6 13.9 0.286 0.631 0.192 0.664 13.5 1.57 3.53 8.41 0 3 s(x2) #> 7 5.71 0.830 0.419 0.532 0.182 6.12 1.02 2.31 2.79 0 4 s(x2) #> 8 5.71 0.830 0.419 0.532 0.182 6.12 1.02 2.31 2.79 0 4 s(x2) #> 9 7.63 0.642 0.879 0.522 0.838 10.4 1.80 5.80 2.76 0 5 s(x2) #> 10 7.63 0.642 0.879 0.522 0.838 10.4 1.80 5.80 2.76 0 5 s(x2) #> # ℹ 790 more rows #> # ℹ 3 more variables: .term , .draw , .value "},{"path":"https://gavinsimpson.github.io/gratia/reference/add_partial_residuals.html","id":null,"dir":"Reference","previous_headings":"","what":"Add partial residuals — add_partial_residuals","title":"Add partial residuals — add_partial_residuals","text":"Add partial residuals","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/add_partial_residuals.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Add partial residuals — add_partial_residuals","text":"","code":"add_partial_residuals(data, model, ...) # S3 method for class 'gam' add_partial_residuals(data, model, select = NULL, partial_match = FALSE, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/add_partial_residuals.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Add partial residuals — add_partial_residuals","text":"data data frame containing values variables used fit model. Passed stats::residuals() newdata. model fitted model stats::residuals() method available. S3 method dispatch performed model argument. ... arguments passed methods. select character, logical, numeric; smooths plot. NULL, default, model smooths drawn. Numeric select indexes smooths order specified formula stored object. Character select matches labels smooths shown example output summary(object). Logical select operates per numeric select order smooths stored. partial_match logical; smooths selected partial matches select? TRUE, select can single string match .","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/add_partial_residuals.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Add partial residuals — add_partial_residuals","text":"","code":"load_mgcv() df <- data_sim(\"eg1\", seed = 1) df <- df[, c(\"y\", \"x0\", \"x1\", \"x2\", \"x3\")] m <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = df, method = \"REML\") ## add partial residuals add_partial_residuals(df, m) #> # A tibble: 400 x 9 #> y x0 x1 x2 x3 `s(x0)` `s(x1)` `s(x2)` `s(x3)` #> #> 1 3.34 0.266 0.659 0.859 0.367 -2.38 -2.00 -5.36 -2.52 #> 2 -0.0758 0.372 0.185 0.0344 0.741 -2.79 -5.15 -6.45 -3.29 #> 3 10.7 0.573 0.954 0.971 0.934 2.99 5.75 -1.07 2.28 #> 4 8.73 0.908 0.898 0.745 0.673 -0.734 2.84 -1.11 0.0287 #> 5 15.0 0.202 0.944 0.273 0.701 -0.752 2.54 3.94 -0.750 #> 6 7.67 0.898 0.724 0.677 0.848 -1.46 0.432 -0.567 -0.812 #> 7 7.58 0.945 0.370 0.348 0.706 -1.33 -1.57 2.08 -0.318 #> 8 8.51 0.661 0.781 0.947 0.859 2.21 3.44 -1.42 1.68 #> 9 10.6 0.629 0.0111 0.339 0.446 2.01 -0.445 4.13 1.51 #> 10 3.72 0.0618 0.940 0.0317 0.677 -4.02 -0.123 -6.67 -3.37 #> # i 390 more rows ## add partial residuals for selected smooths add_partial_residuals(df, m, select = \"s(x0)\") #> # A tibble: 400 x 6 #> y x0 x1 x2 x3 `s(x0)` #> #> 1 3.34 0.266 0.659 0.859 0.367 -2.38 #> 2 -0.0758 0.372 0.185 0.0344 0.741 -2.79 #> 3 10.7 0.573 0.954 0.971 0.934 2.99 #> 4 8.73 0.908 0.898 0.745 0.673 -0.734 #> 5 15.0 0.202 0.944 0.273 0.701 -0.752 #> 6 7.67 0.898 0.724 0.677 0.848 -1.46 #> 7 7.58 0.945 0.370 0.348 0.706 -1.33 #> 8 8.51 0.661 0.781 0.947 0.859 2.21 #> 9 10.6 0.629 0.0111 0.339 0.446 2.01 #> 10 3.72 0.0618 0.940 0.0317 0.677 -4.02 #> # i 390 more rows"},{"path":"https://gavinsimpson.github.io/gratia/reference/add_residuals.gam.html","id":null,"dir":"Reference","previous_headings":"","what":"Add residuals from a GAM to a data frame — add_residuals.gam","title":"Add residuals from a GAM to a data frame — add_residuals.gam","text":"Add residuals GAM data frame","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/add_residuals.gam.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Add residuals from a GAM to a data frame — add_residuals.gam","text":"","code":"# S3 method for class 'gam' add_residuals(data, model, value = \".residual\", type = \"deviance\", ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/add_residuals.gam.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Add residuals from a GAM to a data frame — add_residuals.gam","text":"data data frame containing values variables used fit model. Passed stats::predict() newdata. model fitted model stats::predict() method available. S3 method dispatch performed model argument. value character; name variable model predictions stored. type character; type residuals return. See mgcv::residuals.gam() options. ... additional arguments passed mgcv::residuals.gam().","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/add_residuals.gam.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Add residuals from a GAM to a data frame — add_residuals.gam","text":"data frame (tibble) formed data residuals model.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/add_residuals.gam.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Add residuals from a GAM to a data frame — add_residuals.gam","text":"","code":"load_mgcv() df <- data_sim(\"eg1\", seed = 1) df <- df[, c(\"y\", \"x0\", \"x1\", \"x2\", \"x3\")] m <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = df, method = \"REML\") ## add_residuals(df, m) #> # A tibble: 400 x 6 #> y x0 x1 x2 x3 .residual #> #> 1 3.34 0.266 0.659 0.859 0.367 -2.56 #> 2 -0.0758 0.372 0.185 0.0344 0.741 -3.22 #> 3 10.7 0.573 0.954 0.971 0.934 2.40 #> 4 8.73 0.908 0.898 0.745 0.673 0.0785 #> 5 15.0 0.202 0.944 0.273 0.701 -0.693 #> 6 7.67 0.898 0.724 0.677 0.848 -0.714 #> 7 7.58 0.945 0.370 0.348 0.706 -0.259 #> 8 8.51 0.661 0.781 0.947 0.859 1.78 #> 9 10.6 0.629 0.0111 0.339 0.446 1.50 #> 10 3.72 0.0618 0.940 0.0317 0.677 -3.32 #> # i 390 more rows"},{"path":"https://gavinsimpson.github.io/gratia/reference/add_residuals.html","id":null,"dir":"Reference","previous_headings":"","what":"Add residuals from a model to a data frame — add_residuals","title":"Add residuals from a model to a data frame — add_residuals","text":"Add residuals model data frame","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/add_residuals.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Add residuals from a model to a data frame — add_residuals","text":"","code":"add_residuals(data, model, value = \".residual\", ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/add_residuals.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Add residuals from a model to a data frame — add_residuals","text":"data data frame containing values variables used fit model. Passed stats::residuals() newdata. model fitted model stats::residuals() method available. S3 method dispatch performed model argument. value character; name variable model residuals stored. ... additional arguments passed methods.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/add_residuals.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Add residuals from a model to a data frame — add_residuals","text":"data frame (tibble) formed data residuals model.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/add_sizer.html","id":null,"dir":"Reference","previous_headings":"","what":"Add indicators of significant change after SiZeR — add_sizer","title":"Add indicators of significant change after SiZeR — add_sizer","text":"Add indicators significant change SiZeR","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/add_sizer.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Add indicators of significant change after SiZeR — add_sizer","text":"","code":"add_sizer(object, type = c(\"change\", \"sizer\"), ...) # S3 method for class 'derivatives' add_sizer(object, type = c(\"change\", \"sizer\"), ...) # S3 method for class 'smooth_estimates' add_sizer(object, type = c(\"change\", \"sizer\"), derivatives = NULL, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/add_sizer.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Add indicators of significant change after SiZeR — add_sizer","text":"object R object. Currently supported methods classes \"derivatives\". type character; \"change\" adds single variable object indicating credible interval derivative excludes 0. \"sizer\" adds two variables indicating whether derivative postive negative. ... arguments passed methods derivatives object class \"derivatives\", resulting call derivatives().","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/add_sizer.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Add indicators of significant change after SiZeR — add_sizer","text":"","code":"load_mgcv() df <- data_sim(\"eg1\", n = 400, dist = \"normal\", scale = 2, seed = 42) m <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = df, method = \"REML\") ## first derivatives of all smooths using central finite differences d <- derivatives(m, type = \"central\") |> add_sizer() # default adds a .change column names(d) #> [1] \".smooth\" \".by\" \".fs\" \".derivative\" \".se\" #> [6] \".crit\" \".lower_ci\" \".upper_ci\" \".change\" \"x0\" #> [11] \"x1\" \"x2\" \"x3\""},{"path":"https://gavinsimpson.github.io/gratia/reference/appraise.html","id":null,"dir":"Reference","previous_headings":"","what":"Model diagnostic plots — appraise","title":"Model diagnostic plots — appraise","text":"Model diagnostic plots","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/appraise.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Model diagnostic plots — appraise","text":"","code":"appraise(model, ...) # S3 method for class 'gam' appraise( model, method = c(\"uniform\", \"simulate\", \"normal\", \"direct\"), use_worm = FALSE, n_uniform = 10, n_simulate = 50, seed = NULL, type = c(\"deviance\", \"pearson\", \"response\"), n_bins = c(\"sturges\", \"scott\", \"fd\"), ncol = NULL, nrow = NULL, guides = \"keep\", level = 0.9, ci_col = \"black\", ci_alpha = 0.2, point_col = \"black\", point_alpha = 1, line_col = \"red\", ... ) # S3 method for class 'lm' appraise(model, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/appraise.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Model diagnostic plots — appraise","text":"model fitted model. Currently models inheriting class \"gam\", well classes \"glm\" \"lm\" calls stats::glm stats::lm supported. ... arguments passed patchwork::wrap_plots(). method character; method used generate theoretical quantiles. default \"uniform\", generates reference quantiles using random draws uniform distribution inverse cummulative distribution function (CDF) fitted values. reference quantiles averaged n_uniform draws. \"simulate\" generates reference quantiles simulating new response data model observed values covariates, residualised generate reference quantiles, using n_simulate simulated data sets. \"normal\" generates reference quantiles using standard normal distribution. \"uniform\" computationally efficient, \"simulate\" allows reference bands drawn QQ-plot. \"normal\" avoided used fall back random number generator (\"simulate\") inverse CDF (\"uniform\"``) available family` used model fitting. Note method = \"direct\" deprecated favour method = \"uniform\". use_worm logical; worm plot drawn place QQ plot? n_uniform numeric; number times randomize uniform quantiles direct computation method (method = \"direct\") QQ plots. n_simulate numeric; number data sets simulate estimated model using simulation method (method = \"simulate\") QQ plots. seed numeric; random number seed use method = \"simulate\" method = \"uniform\". type character; type residuals use. \"deviance\", \"response\", \"pearson\" residuals allowed. n_bins character numeric; either number bins string indicating calculate number bins. ncol, nrow numeric; numbers rows columns spread plots. guides character; one \"keep\" (default), \"collect\", \"auto\". Passed patchwork::plot_layout() level numeric; coverage level QQ plot reference intervals. Must strictly 0 < level < 1. used method = \"simulate\". ci_alpha, ci_col colour transparency used draw QQ plot reference interval method = \"simulate\". point_col, point_alpha colour transparency used draw points plots. See graphics::par() section Color Specification. passed individual plotting functions, therefore affects points plots. line_col colour specification 1:1 line QQ plot reference line residuals vs linear predictor plot.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/appraise.html","id":"note","dir":"Reference","previous_headings":"","what":"Note","title":"Model diagnostic plots — appraise","text":"wording used mgcv::qq.gam() uses direct reference simulated residuals method (method = \"simulated\"). avoid confusion, method = \"direct\" deprecated favour method = \"uniform\".","code":""},{"path":[]},{"path":"https://gavinsimpson.github.io/gratia/reference/appraise.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Model diagnostic plots — appraise","text":"","code":"load_mgcv() ## simulate some data... dat <- data_sim(\"eg1\", n = 400, dist = \"normal\", scale = 2, seed = 2) mod <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = dat) ## run some basic model checks appraise(mod, point_col = \"steelblue\", point_alpha = 0.4) ## To change the theme for all panels use the & operator, for example to ## change the ggplot theme for all panels library(\"ggplot2\") appraise(mod, seed = 42, point_col = \"steelblue\", point_alpha = 0.4, line_col = \"black\" ) & theme_minimal()"},{"path":"https://gavinsimpson.github.io/gratia/reference/basis.html","id":null,"dir":"Reference","previous_headings":"","what":"Basis expansions for smooths — basis","title":"Basis expansions for smooths — basis","text":"Creates basis expansion definition smoother using syntax mgcv's smooths via mgcv::s()., mgcv::te(), mgcv::ti(), mgcv::t2(), fitted GAM(M).","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/basis.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Basis expansions for smooths — basis","text":"","code":"basis(object, ...) # S3 method for class 'gam' basis( object, select = NULL, term = deprecated(), data = NULL, n = 100, n_2d = 50, n_3d = 16, n_4d = 4, partial_match = FALSE, ... ) # S3 method for class 'scam' basis( object, select = NULL, term = deprecated(), data = NULL, n = 100, n_2d = 50, n_3d = 16, n_4d = 4, partial_match = FALSE, ... ) # S3 method for class 'gamm' basis( object, select = NULL, term = deprecated(), data = NULL, n = 100, n_2d = 50, n_3d = 16, n_4d = 4, partial_match = FALSE, ... ) # S3 method for class 'list' basis( object, select = NULL, term = deprecated(), data = NULL, n = 100, n_2d = 50, n_3d = 16, n_4d = 4, partial_match = FALSE, ... ) # Default S3 method basis( object, data, knots = NULL, constraints = FALSE, at = NULL, diagonalize = FALSE, ... )"},{"path":"https://gavinsimpson.github.io/gratia/reference/basis.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Basis expansions for smooths — basis","text":"object smooth specification, result call one mgcv::s()., mgcv::te(), mgcv::ti(), mgcv::t2(), fitted GAM(M) model. ... arguments passed mgcv::smoothCon(). select character; select smooths fitted model term argument renamed select data data frame containing variables used smooth. n numeric; number points range covariate evaluate smooth. n_2d numeric; number new observations dimension bivariate smooth. currently used; n used dimensions. n_3d numeric; number new observations generate third dimension 3D smooth. n_4d numeric; number new observations generate dimensions higher 2 (!) kD smooth (k >= 4). example, smooth 4D smooth, dimensions 3 4 get n_4d new observations. partial_match logical; case character select, select match partially smooths? partial_match = TRUE, select must single string, character vector length 1. knots list data frame named components containing knots locations. Names must match covariates basis required. See mgcv::smoothCon(). constraints logical; identifiability constraints applied smooth basis. See argument absorb.cons mgcv::smoothCon(). data frame containing values smooth covariate(s) basis evaluated. diagonalize logical; TRUE, reparameterises smooth associated penalty identity matrix. effect turning last diagonal elements penalty zero, highlights penalty null space.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/basis.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Basis expansions for smooths — basis","text":"tibble.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/basis.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Basis expansions for smooths — basis","text":"Gavin L. Simpson","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/basis.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Basis expansions for smooths — basis","text":"","code":"load_mgcv() df <- data_sim(\"eg4\", n = 400, seed = 42) bf <- basis(s(x0), data = df) bf <- basis(s(x2, by = fac, bs = \"bs\"), data = df, constraints = TRUE)"},{"path":"https://gavinsimpson.github.io/gratia/reference/basis_size.html","id":null,"dir":"Reference","previous_headings":"","what":"Extract basis dimension of a smooth — basis_size","title":"Extract basis dimension of a smooth — basis_size","text":"Extract basis dimension smooth","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/basis_size.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Extract basis dimension of a smooth — basis_size","text":"","code":"basis_size(object, ...) # S3 method for class 'mgcv.smooth' basis_size(object, ...) # S3 method for class 'gam' basis_size(object, ...) # S3 method for class 'gamm' basis_size(object, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/basis_size.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Extract basis dimension of a smooth — basis_size","text":"object fitted GAM(M). Currently mgcv::gam() (anything inherits \"gam\" class, e.g. mgcv::bam()) mgcv::gamm() supported. ... Arguments passed methods.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/basis_size.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Extract basis dimension of a smooth — basis_size","text":"","code":"load_mgcv() df <- data_sim(\"eg1\", n = 200, seed = 1) m <- bam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = df) basis_size(m) #> s(x0) s(x1) s(x2) s(x3) #> 9 9 9 9"},{"path":"https://gavinsimpson.github.io/gratia/reference/bird_move.html","id":null,"dir":"Reference","previous_headings":"","what":"Simulated bird migration data — bird_move","title":"Simulated bird migration data — bird_move","text":"Data generated hypothetical study bird movement along migration corridor, sampled throughout year. dataset consists simulated sample records numbers observed locations 100 tagged individuals six species bird, ten locations along latitudinal gradient, one observation taken every four weeks. Counts simulated randomly species location week creating species-specific migration curve gave probability finding individual given species given location, simulated distribution individuals across sites using multinomial distribution, subsampling using binomial distribution simulation observation error (.e. every bird present location detected). data set (bird_move) consists variables count, latitude, week species.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/bird_move.html","id":"format","dir":"Reference","previous_headings":"","what":"Format","title":"Simulated bird migration data — bird_move","text":"data frame","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/bird_move.html","id":"source","dir":"Reference","previous_headings":"","what":"Source","title":"Simulated bird migration data — bird_move","text":"Pedersen EJ, Miller DL, Simpson GL, Ross N. 2018. Hierarchical generalized additive models: introduction mgcv. PeerJ Preprints 6:e27320v1 doi:10.7287/peerj.preprints.27320v1 .","code":""},{"path":[]},{"path":"https://gavinsimpson.github.io/gratia/reference/boundary.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Extract the boundary of a soap film smooth — boundary","text":"","code":"boundary(x, ...) # S3 method for class 'soap.film' boundary(x, ...) # S3 method for class 'gam' boundary(x, select, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/boundary.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Extract the boundary of a soap film smooth — boundary","text":"x R object. Currently objects inherit classes \"soap.film\" \"gam\". ... arguments passed methods. select character; label soap film smooth extract boundary.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/boundary.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Extract the boundary of a soap film smooth — boundary","text":"list lists data frames specifying loops define boundary soap film smooth.","code":""},{"path":[]},{"path":"https://gavinsimpson.github.io/gratia/reference/check_user_select_smooths.html","id":null,"dir":"Reference","previous_headings":"","what":"Select smooths based on user's choices — check_user_select_smooths","title":"Select smooths based on user's choices — check_user_select_smooths","text":"Given vector indexing smooths GAM, returns logical vector selecting requested smooths.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/check_user_select_smooths.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Select smooths based on user's choices — check_user_select_smooths","text":"","code":"check_user_select_smooths( smooths, select = NULL, partial_match = FALSE, model_name = NULL )"},{"path":"https://gavinsimpson.github.io/gratia/reference/check_user_select_smooths.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Select smooths based on user's choices — check_user_select_smooths","text":"smooths character; vector smooth labels. select numeric, logical, character vector selected smooths. partial_match logical; case character select, select match partially smooths? partial_match = TRUE, select must single string, character vector length 1. model_name character; model name used error messages.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/check_user_select_smooths.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Select smooths based on user's choices — check_user_select_smooths","text":"logical vector length length(smooths) indicating smooths selected.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/check_user_select_smooths.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Select smooths based on user's choices — check_user_select_smooths","text":"Gavin L. Simpson","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/coef.scam.html","id":null,"dir":"Reference","previous_headings":"","what":"Extract coefficients from a fitted scam model. — coef.scam","title":"Extract coefficients from a fitted scam model. — coef.scam","text":"Extract coefficients fitted scam model.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/coef.scam.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Extract coefficients from a fitted scam model. — coef.scam","text":"","code":"# S3 method for class 'scam' coef(object, parametrized = TRUE, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/coef.scam.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Extract coefficients from a fitted scam model. — coef.scam","text":"object model object fitted scam() parametrized logical; extract parametrized coefficients, respect linear inequality constraints model. ... arguments.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/compare_smooths.html","id":null,"dir":"Reference","previous_headings":"","what":"Compare smooths across models — compare_smooths","title":"Compare smooths across models — compare_smooths","text":"Compare smooths across models","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/compare_smooths.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Compare smooths across models — compare_smooths","text":"","code":"compare_smooths( model, ..., select = NULL, smooths = deprecated(), n = 100, data = NULL, unconditional = FALSE, overall_uncertainty = TRUE, partial_match = FALSE )"},{"path":"https://gavinsimpson.github.io/gratia/reference/compare_smooths.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Compare smooths across models — compare_smooths","text":"model Primary model comparison. ... Additional models compare smooths model. select character; select smooths compare. default (NULL) means smooths model compared. Numeric select indexes smooths order specified formula stored model. Character select matches labels smooths shown example output summary(object). Logical select operates per numeric select order smooths stored. smooths Use select instead. n numeric; number points range covariate evaluate smooth. data data frame covariate values evaluate smooth. unconditional logical; confidence intervals include uncertainty due smoothness selection? TRUE, corrected Bayesian covariance matrix used. overall_uncertainty logical; uncertainty model constant term included standard error evaluate values smooth? partial_match logical; smooths selected partial matches select? TRUE, select can single string match .","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/compare_smooths.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Compare smooths across models — compare_smooths","text":"","code":"load_mgcv() dat <- data_sim(\"eg1\", seed = 2) ## models to compare smooths across - artificially create differences m1 <- gam(y ~ s(x0, k = 5) + s(x1, k = 5) + s(x2, k = 5) + s(x3, k = 5), data = dat, method = \"REML\" ) m2 <- gam(y ~ s(x0, bs = \"ts\") + s(x1, bs = \"ts\") + s(x2, bs = \"ts\") + s(x3, bs = \"ts\"), data = dat, method = \"REML\") ## build comparisons comp <- compare_smooths(m1, m2) comp #> # A tibble: 8 x 5 #> .model .smooth .type .by data #> #> 1 m1 s(x0) TPRS NA #> 2 m2 s(x0) TPRS (shrink) NA #> 3 m1 s(x1) TPRS NA #> 4 m2 s(x1) TPRS (shrink) NA #> 5 m1 s(x2) TPRS NA #> 6 m2 s(x2) TPRS (shrink) NA #> 7 m1 s(x3) TPRS NA #> 8 m2 s(x3) TPRS (shrink) NA ## notice that the result is a nested tibble draw(comp)"},{"path":"https://gavinsimpson.github.io/gratia/reference/conditional_values.html","id":null,"dir":"Reference","previous_headings":"","what":"Generated predicted values from a GAM, conditional upon supplied values of covariates — conditional_values","title":"Generated predicted values from a GAM, conditional upon supplied values of covariates — conditional_values","text":"Generated predicted values GAM, conditional upon supplied values covariates","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/conditional_values.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Generated predicted values from a GAM, conditional upon supplied values of covariates — conditional_values","text":"","code":"conditional_values( model, condition = NULL, data = NULL, scale = c(\"response\", \"link\", \"linear_predictor\"), ... ) # S3 method for class 'gam' conditional_values( model, condition = NULL, data = NULL, scale = c(\"response\", \"link\", \"linear_predictor\"), n_vals = 100, ci_level = 0.95, ... )"},{"path":"https://gavinsimpson.github.io/gratia/reference/conditional_values.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Generated predicted values from a GAM, conditional upon supplied values of covariates — conditional_values","text":"model fitted GAM object. condition either character vector list supplying names covariates, possibly values, condition . order values determines plotted via draw.conditional_values() method; first element mapped x channel, second element colour channel, third ggplot2::facet_wrap() fourth element present, present, fourth element mapped rows third element mapped columns ggplot2::facet_grid(). data data frame values predict. supplied overrides values supplied condition. scale character; scale predictions returned ? ... arguments passed fitted_values(). n_vals numeric; number values generate numeric variables named condition. ci_level numeric; number interval (0,1) giving coverage credible intervals.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/conditional_values.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Generated predicted values from a GAM, conditional upon supplied values of covariates — conditional_values","text":"","code":"load_mgcv() df <- data_sim(\"eg1\", seed = 2) m1 <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = df, method = \"REML\") # predictions conditional on values evenly spaced over x2, all other # variables in model are held at representative values cv <- conditional_values( m1, condition = \"x2\" ) # plot cv |> draw() # as above but condition on `x1` also. When plotted, `x1` is mapped to the # colour channel, noting that it has been summarised using fivenum() cv <- conditional_values( m1, condition = c(\"x2\", \"x1\") ) # plot cv |> draw() # can pass `condition` a list, allowing for greater flexibility # For example, here we condition on all four variables in the model, # summarising: # * `x1` at its deciles, # * `x0 at its quartiles # * `x3` at its mean a d mean +/- sd cv <- conditional_values( m1, condition = list(\"x2\", x1 = \"decile\", x0 = \"quartile\", x3 = \"threenum\") ) # plot cv |> draw() # some model terms can be exclude from the conditional predictions using the # `exclude` mechanism of `predict.gam`. Here we exclude the effects of # `s(x0)` and `s(x3)` from the conditional predictions. This, in effect, # treats these smooths as having **0** effect on the conditional predictions # of the response, even though the two smooths conditioned on (`s(x2)` and # `s(x1)`) were estimated given the two excluded smooths were in the model cv <- conditional_values( m1, condition = list(\"x2\", x1 = \"minmax\"), exclude = c(\"s(x0)\", \"s(x3)\") ) # plot cv |> draw() # categorical conditions are also handled df <- data_sim(\"eg4\", seed = 2) m2 <- gam(y ~ fac + s(x2, by = fac) + s(x0), data = df, method = \"REML\") cv <- conditional_values( m2, condition = list(\"fac\", x2 = \"fivenum\") ) # plot - we see a discrete x axis cv |> draw() # in this example we condition on `x2` and `fac %in% c(2,3)` cv <- conditional_values( m2, condition = list(\"x2\", fac = 2:3) ) # plot - smooths of `x2` for `fac == 2` and `fac == 3` cv |> draw()"},{"path":"https://gavinsimpson.github.io/gratia/reference/confint.fderiv.html","id":null,"dir":"Reference","previous_headings":"","what":"Point-wise and simultaneous confidence intervals for derivatives of smooths — confint.fderiv","title":"Point-wise and simultaneous confidence intervals for derivatives of smooths — confint.fderiv","text":"Calculates point-wise confidence simultaneous intervals first derivatives smooth terms fitted GAM.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/confint.fderiv.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Point-wise and simultaneous confidence intervals for derivatives of smooths — confint.fderiv","text":"","code":"# S3 method for class 'fderiv' confint( object, parm, level = 0.95, type = c(\"confidence\", \"simultaneous\"), nsim = 10000, ncores = 1L, ... )"},{"path":"https://gavinsimpson.github.io/gratia/reference/confint.fderiv.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Point-wise and simultaneous confidence intervals for derivatives of smooths — confint.fderiv","text":"object object class \"fderiv\" containing estimated derivatives. parm parameters (smooth terms) given intervals vector terms. missing, parameters considered. level numeric, 0 < level < 1; confidence level point-wise simultaneous interval. default 0.95 95% interval. type character; type interval compute. One \"confidence\" point-wise intervals, \"simultaneous\" simultaneous intervals. nsim integer; number simulations used computing simultaneous intervals. ncores number cores generating random variables multivariate normal distribution. Passed mvnfast::rmvn(). Parallelization take place OpenMP supported (appears work Windows current R). ... additional arguments methods","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/confint.fderiv.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Point-wise and simultaneous confidence intervals for derivatives of smooths — confint.fderiv","text":"data frame components: term; factor indicating term row relates, lower; lower limit confidence simultaneous interval, est; estimated derivative upper; upper limit confidence simultaneous interval.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/confint.fderiv.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Point-wise and simultaneous confidence intervals for derivatives of smooths — confint.fderiv","text":"Gavin L. Simpson","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/confint.fderiv.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Point-wise and simultaneous confidence intervals for derivatives of smooths — confint.fderiv","text":"","code":"load_mgcv() dat <- data_sim(\"eg1\", n = 1000, dist = \"normal\", scale = 2, seed = 2) mod <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = dat, method = \"REML\") # new data to evaluate the derivatives at, say over the middle 50% of range # of each covariate middle <- function(x, n = 25, coverage = 0.5) { v <- (1 - coverage) / 2 q <- quantile(x, prob = c(0 + v, 1 - v), type = 8) seq(q[1], q[2], length = n) } new_data <- sapply(dat[c(\"x0\", \"x1\", \"x2\", \"x3\")], middle) new_data <- data.frame(new_data) ## first derivatives of all smooths... fd <- fderiv(mod, newdata = new_data) #> Warning: `fderiv()` was deprecated in gratia 0.7.0. #> i Please use `derivatives()` instead. ## point-wise interval ci <- confint(fd, type = \"confidence\") ci #> # A tibble: 100 x 4 #> term lower est upper #> #> 1 s(x0) 1.7 4.1 6.6 #> 2 s(x0) 1.3 3.8 6.3 #> 3 s(x0) 0.99 3.5 6.0 #> 4 s(x0) 0.68 3.1 5.6 #> 5 s(x0) 0.37 2.8 5.2 #> 6 s(x0) 0.0049 2.4 4.8 #> 7 s(x0) -0.40 2.0 4.5 #> 8 s(x0) -0.79 1.7 4.2 #> 9 s(x0) -1.1 1.3 3.8 #> 10 s(x0) -1.4 0.99 3.4 #> # i 90 more rows ## simultaneous interval for smooth term of x2 x2_sint <- confint(fd, parm = \"x2\", type = \"simultaneous\", nsim = 10000, ncores = 2 ) # \\donttest{ x2_sint #> # A tibble: 25 x 4 #> term lower est upper #> #> 1 s(x2) -24. -15. -5.6 #> 2 s(x2) -35. -26. -16. #> 3 s(x2) -41. -33. -24. #> 4 s(x2) -44. -36. -29. #> 5 s(x2) -44. -36. -28. #> 6 s(x2) -42. -34. -25. #> 7 s(x2) -38. -30. -21. #> 8 s(x2) -33. -24. -16. #> 9 s(x2) -27. -19. -11. #> 10 s(x2) -22. -14. -5.8 #> # i 15 more rows # }"},{"path":"https://gavinsimpson.github.io/gratia/reference/confint.gam.html","id":null,"dir":"Reference","previous_headings":"","what":"Point-wise and simultaneous confidence intervals for smooths — confint.gam","title":"Point-wise and simultaneous confidence intervals for smooths — confint.gam","text":"Calculates point-wise confidence simultaneous intervals smooth terms fitted GAM.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/confint.gam.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Point-wise and simultaneous confidence intervals for smooths — confint.gam","text":"","code":"# S3 method for class 'gam' confint( object, parm, level = 0.95, data = newdata, n = 100, type = c(\"confidence\", \"simultaneous\"), nsim = 10000, shift = FALSE, transform = FALSE, unconditional = FALSE, ncores = 1, partial_match = FALSE, ..., newdata = NULL ) # S3 method for class 'gamm' confint(object, ...) # S3 method for class 'list' confint(object, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/confint.gam.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Point-wise and simultaneous confidence intervals for smooths — confint.gam","text":"object object class \"gam\" \"gamm\". parm parameters (smooth terms) given intervals vector terms. missing, parameters considered, although currently implemented. level numeric, 0 < level < 1; confidence level point-wise simultaneous interval. default 0.95 95% interval. data data frame; new values covariates used model fit. selected smooth(s) wil evaluated supplied values. n numeric; number points evaluate smooths . type character; type interval compute. One \"confidence\" point-wise intervals, \"simultaneous\" simultaneous intervals. nsim integer; number simulations used computing simultaneous intervals. shift logical; constant term add smooth? transform logical; smooth evaluated transformed scale? generalised models, involves applying inverse link function used fit model. Alternatively, name , actual, function can supplied transform smooth confidence interval. unconditional logical; TRUE (freq == FALSE) Bayesian smoothing parameter uncertainty corrected covariance matrix returned, available. ncores number cores generating random variables multivariate normal distribution. Passed mvnfast::rmvn(). Parallelization take place OpenMP supported (appears work Windows current R). partial_match logical; matching parm use partial match exact match? Can used length(parm) 1. ... additional arguments methods newdata DEPRECATED! data frame; containing new values covariates used model fit. selected smooth(s) wil evaluated supplied values.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/confint.gam.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Point-wise and simultaneous confidence intervals for smooths — confint.gam","text":"tibble components: .smooth; character indicating term row relates, .type; type smooth, .name variable smooth, NA otherwise, one vectors values smooth evaluated, named per variables smooth, zero variables containing values variable, .estimate; estimated value smooth, .se; standard error estimated value smooth, .crit; critical value 100 * level% confidence interval. .lower_ci; lower limit confidence simultaneous interval, .upper_ci; upper limit confidence simultaneous interval,","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/confint.gam.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Point-wise and simultaneous confidence intervals for smooths — confint.gam","text":"Gavin L. Simpson","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/confint.gam.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Point-wise and simultaneous confidence intervals for smooths — confint.gam","text":"","code":"load_mgcv() dat <- data_sim(\"eg1\", n = 1000, dist = \"normal\", scale = 2, seed = 2) mod <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = dat, method = \"REML\") # new data to evaluate the smooths at, say over the middle 50% of range # of each covariate middle <- function(x, n = 50, coverage = 0.5) { v <- (1 - coverage) / 2 q <- quantile(x, prob = c(0 + v, 1 - v), type = 8) seq(q[1], q[2], length = n) } new_data <- sapply(dat[c(\"x0\", \"x1\", \"x2\", \"x3\")], middle) new_data <- data.frame(new_data) ## point-wise interval for smooth of x2 ci <- confint(mod, parm = \"s(x2)\", type = \"confidence\", data = new_data) ci #> # A tibble: 50 x 9 #> .smooth .type .by x2 .estimate .se .crit .lower_ci .upper_ci #> #> 1 s(x2) TPRS NA 0.26 5.3 0.18 2.0 5.0 5.7 #> 2 s(x2) TPRS NA 0.27 5.1 0.18 2.0 4.8 5.5 #> 3 s(x2) TPRS NA 0.28 4.9 0.18 2.0 4.6 5.3 #> 4 s(x2) TPRS NA 0.29 4.6 0.18 2.0 4.3 5.0 #> 5 s(x2) TPRS NA 0.30 4.3 0.19 2.0 3.9 4.7 #> 6 s(x2) TPRS NA 0.32 4.0 0.19 2.0 3.6 4.3 #> 7 s(x2) TPRS NA 0.33 3.6 0.20 2.0 3.2 4.0 #> 8 s(x2) TPRS NA 0.34 3.2 0.20 2.0 2.9 3.6 #> 9 s(x2) TPRS NA 0.35 2.9 0.20 2.0 2.5 3.3 #> 10 s(x2) TPRS NA 0.36 2.5 0.19 2.0 2.1 2.9 #> # i 40 more rows"},{"path":"https://gavinsimpson.github.io/gratia/reference/data_combos.html","id":null,"dir":"Reference","previous_headings":"","what":"All combinations of factor levels plus typical values of continuous variables — data_combos","title":"All combinations of factor levels plus typical values of continuous variables — data_combos","text":"combinations factor levels plus typical values continuous variables","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/data_combos.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"All combinations of factor levels plus typical values of continuous variables — data_combos","text":"","code":"data_combos(object, ...) # S3 method for class 'gam' data_combos( object, vars = everything(), complete = TRUE, envir = environment(formula(object)), data = NULL, ... )"},{"path":"https://gavinsimpson.github.io/gratia/reference/data_combos.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"All combinations of factor levels plus typical values of continuous variables — data_combos","text":"object fitted model object. ... arguments passed methods. vars terms include exclude returned object. Uses tidyselect principles. complete logical; combinations factor levels returned? FALSE, combinations levels observed model retained. envir environment within recreate data used fit object. data optional data frame data used fit mdoel reconstruction data model work.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/data_sim.html","id":null,"dir":"Reference","previous_headings":"","what":"Simulate example data for fitting GAMs — data_sim","title":"Simulate example data for fitting GAMs — data_sim","text":"tidy reimplementation functions implemented mgcv::gamSim() can used fit GAMs. new feature sampling distribution can applied example types.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/data_sim.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Simulate example data for fitting GAMs — data_sim","text":"","code":"data_sim( model = \"eg1\", n = 400, scale = NULL, theta = 3, power = 1.5, dist = c(\"normal\", \"poisson\", \"binary\", \"negbin\", \"tweedie\", \"gamma\", \"ocat\", \"ordered categorical\"), n_cat = 4, cuts = c(-1, 0, 5), seed = NULL, gfam_families = c(\"binary\", \"tweedie\", \"normal\") )"},{"path":"https://gavinsimpson.github.io/gratia/reference/data_sim.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Simulate example data for fitting GAMs — data_sim","text":"model character; either \"egX\" X integer 1:7, name model. See Details possible options. n numeric; number observations simulate. scale numeric; level noise use. theta numeric; dispersion parameter \\(\\theta\\) use. default entirely arbitrary, chosen provide simulated data exhibits extra dispersion beyond assumed Poisson. power numeric; Tweedie power parameter. dist character; sampling distribution response variable. \"ordered categorical\" synonym \"ocat\". n_cat integer; number categories categorical response. Currently used distr %% c(\"ocat\", \"ordered categorical\"). cuts numeric; vector cut points latent variable, excluding end points -Inf Inf. Must one fewer number categories: length(cuts) == n_cat - 1. seed numeric; seed random number generator. Passed base::set.seed(). gfam_families character; vector distributions use generating data grouped families use family = gfam(). allowed distributions per dist.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/data_sim.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Simulate example data for fitting GAMs — data_sim","text":"data_sim() can simulate data several underlying models known true functions. available options currently : \"eg1\": four term additive true model. classic Gu & Wahba four univariate term test model. See gw_functions details underlying four functions. \"eg2\": bivariate smooth true model. \"eg3\": example containing continuous smooth (varying coefficient) true model. model \\(\\hat{y}_i = f_2(x_{1i})x_{2i}\\) function \\(f_2()\\) \\(f_2(x) = 0.2 * x^{11} * (10 * (1 - x))^6 + 10 * (10 * x)^3 * (1 - x)^{10}\\). \"eg4\": factor smooth true model. true model contains factor 3 levels, response nth level follows nth Gu & Wabha function (\\(n \\{1, 2, 3}\\)). \"eg5\": additive plus factor true model. response linear combination Gu & Wabha functions 2, 3, 4 (latter null function) plus factor term four levels. \"eg6\": additive plus random effect term true model. ´\"eg7\": version model \"eg1\"`, covariates correlated. \"gwf2\": model response Gu & Wabha's \\(f_2(x_i)\\) plus noise. \"lwf6\": model response Luo & Wabha's \"example 6\" function \\(sin(2(4x-2)) + 2 exp(-256(x-0.5)^2)\\) plus noise. \"gfam\": simulates data use GAMs family = gfam(families). See example mgcv::gfam(). model specified dist ignored gfam_families used specify distributions included simulated data. Can vector families allowed dist. \"ocat\" %% gfam_families (\"ordered categorical\"), 4 classes assumed, changed. Link functions used \"identity\" \"normal\", \"logit\" \"binary\", \"ocat\", \"ordered categorical\", \"exp\" elsewhere. random component providing noise sampling variation can follow one distributions, specified via argument dist \"normal\": Gaussian, \"poisson\": Poisson, \"binary\": Bernoulli, \"negbin\": Negative binomial, \"tweedie\": Tweedie, \"gamma\": gamma , \"ordered categorical\": ordered categorical arguments provide parameters distribution.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/data_sim.html","id":"references","dir":"Reference","previous_headings":"","what":"References","title":"Simulate example data for fitting GAMs — data_sim","text":"Gu, C., Wahba, G., (1993). Smoothing Spline ANOVA Component-Wise Bayesian \"Confidence Intervals.\" J. Comput. Graph. Stat. 2, 97–117. Luo, Z., Wahba, G., (1997). Hybrid adaptive splines. J. . Stat. Assoc. 92, 107–116.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/data_sim.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Simulate example data for fitting GAMs — data_sim","text":"","code":"data_sim(\"eg1\", n = 100, seed = 1) #> # A tibble: 100 x 10 #> y x0 x1 x2 x3 f f0 f1 f2 f3 #> #> 1 14.532 0.26551 0.65472 0.26751 0.67371 13.713 1.4814 3.7041 8.5277 0 #> 2 16.113 0.37212 0.35320 0.21865 0.094858 12.735 1.8408 2.0267 8.8680 0 #> 3 9.5835 0.57285 0.27026 0.51680 0.49260 6.4103 1.9478 1.7169 2.7456 0 #> 4 15.687 0.90821 0.99268 0.26895 0.46155 16.349 0.56879 7.2817 8.4980 0 #> 5 8.2216 0.20168 0.63349 0.18117 0.37522 12.792 1.1841 3.5501 8.0578 0 #> 6 9.9034 0.89839 0.21321 0.51858 0.99110 4.9081 0.62765 1.5318 2.7487 0 #> 7 5.9362 0.94468 0.12937 0.56278 0.17635 4.6020 0.34587 1.2953 2.9609 0 #> 8 10.839 0.66080 0.47812 0.12916 0.81344 9.7565 1.7502 2.6019 5.4045 0 #> 9 16.883 0.62911 0.92407 0.25637 0.068447 16.909 1.8377 6.3481 8.7237 0 #> 10 7.3603 0.061786 0.59876 0.71794 0.40045 6.3401 0.38578 3.3119 2.6424 0 #> # i 90 more rows # an ordered categorical response data_sim(\"eg1\", n = 100, dist = \"ocat\", n_cat = 4, cuts = c(-1, 0, 5)) #> # A tibble: 100 x 11 #> y x0 x1 x2 x3 f f0 f1 f2 #> #> 1 1 0.93708 0.21716 0.51711 0.44457 -3.5517 0.39280 1.5439 2.7461 #> 2 1 0.28614 0.21657 0.85193 0.060386 -4.7654 1.5653 1.5421 0.36166 #> 3 1 0.83045 0.38895 0.44280 0.32751 -1.7693 1.0157 2.1769 3.2727 #> 4 4 0.64175 0.94246 0.15788 0.87843 7.2150 1.8050 6.5858 7.0588 #> 5 3 0.51910 0.96261 0.44232 0.93060 3.8994 1.9964 6.8566 3.2808 #> 6 1 0.73659 0.73986 0.96773 0.39218 -2.3701 1.4725 4.3917 0.00015734 #> 7 1 0.13467 0.73325 0.48459 0.15885 -0.27657 0.82112 4.3340 2.8028 #> 8 3 0.65699 0.53576 0.25246 0.31995 5.2247 1.7616 2.9198 8.7777 #> 9 3 0.70506 0.0022730 0.25969 0.30697 3.0408 1.5991 1.0046 8.6716 #> 10 2 0.45774 0.60894 0.54202 0.10781 -0.036524 1.9824 3.3800 2.8356 #> # i 90 more rows #> # i 2 more variables: f3 , latent "},{"path":"https://gavinsimpson.github.io/gratia/reference/data_slice.html","id":null,"dir":"Reference","previous_headings":"","what":"Prepare a data slice through model covariates — data_slice","title":"Prepare a data slice through model covariates — data_slice","text":"Prepare data slice model covariates","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/data_slice.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Prepare a data slice through model covariates — data_slice","text":"","code":"data_slice(object, ...) # Default S3 method data_slice(object, ...) # S3 method for class 'data.frame' data_slice(object, ...) # S3 method for class 'gam' data_slice(object, ..., data = NULL, envir = NULL) # S3 method for class 'gamm' data_slice(object, ...) # S3 method for class 'list' data_slice(object, ...) # S3 method for class 'scam' data_slice(object, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/data_slice.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Prepare a data slice through model covariates — data_slice","text":"object R model object. ... User supplied variables defining data slice. Arguments passed via ... need named. data alternative data frame values containing variables needed fit model. NULL, default, data used fit model recovered using model.frame. User-supplied expressions passed ... evaluated data. envir environment within recreate data used fit object.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/data_slice.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Prepare a data slice through model covariates — data_slice","text":"data slice data set results one (covariates) varied systematically () range specified subset values interest, remaining covariates model held fixed, representative values. known reference grid package emmeans data grid marginaleffects package. GAMs, covariates specified via ... take representative values determined data used fit model follows: numeric covariates, value fitting data closest median value used, factor covariates, modal (frequently observed) level used, first level (sorted per vector returned base::levels() several levels observed number times. values already computed calling gam() bam() example can found var.summary component fitted model. Function typical_values() extract values interested. Convenience functions evenly(), ref_level(), level() provided help users specify data slices. ref_level(), level() also ensure factor covariates correct levels, needed mgcv::predict.gam() example. extended discussion data_slice() examples, see vignette(\"data-slices\", package = \"gratia\").","code":""},{"path":[]},{"path":"https://gavinsimpson.github.io/gratia/reference/data_slice.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Prepare a data slice through model covariates — data_slice","text":"","code":"load_mgcv() # simulate some Gaussian data df <- data_sim(\"eg1\", n = 50, seed = 2) # fit a GAM with 1 smooth and 1 linear term m <- gam(y ~ s(x2, k = 7) + x1, data = df, method = \"REML\") # Want to predict over f(x2) while holding `x1` at some value. # Default will use the observation closest to the median for unspecified # variables. ds <- data_slice(m, x2 = evenly(x2, n = 50)) ds #> # A tibble: 50 x 2 #> x2 x1 #> #> 1 0.0228 0.403 #> 2 0.0424 0.403 #> 3 0.0619 0.403 #> 4 0.0815 0.403 #> 5 0.101 0.403 #> 6 0.121 0.403 #> 7 0.140 0.403 #> 8 0.160 0.403 #> 9 0.179 0.403 #> 10 0.199 0.403 #> # i 40 more rows # for full control, specify the values you want ds <- data_slice(m, x2 = evenly(x2, n = 50), x1 = 0.3) # or provide an expression (function call) which will be evaluated in the # data frame passed to `data` or `model.frame(object)` ds <- data_slice(m, x2 = evenly(x2, n = 50), x1 = mean(x1))"},{"path":"https://gavinsimpson.github.io/gratia/reference/datagen.html","id":null,"dir":"Reference","previous_headings":"","what":"Generate data over the range of variables used in smooths — datagen","title":"Generate data over the range of variables used in smooths — datagen","text":"smooth GAM, generate new data range variables involved smooth. function deprecated useful narrow use-case. Use data_slice() instead.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/datagen.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Generate data over the range of variables used in smooths — datagen","text":"","code":"datagen(x, ...) # S3 method for class 'mgcv.smooth' datagen(x, n = 100, data, ...) # S3 method for class 'fs.interaction' datagen(x, n = 100, data, ...) # S3 method for class 'gam' datagen(x, smooth = NULL, n = 200, ...) # S3 method for class 'gamm' datagen(x, ...) # S3 method for class 'list' datagen(x, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/datagen.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Generate data over the range of variables used in smooths — datagen","text":"x object new data required. Currently objects classes \"gam\", \"gamm\" supported, smooths mgcv inheriting class \"mgcv.smooth\". ... arguments passed methods n numeric; number data values generate per term smooth. data data frame; \"mgcv.smooth\" objects, data used fit GAM need supplied.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/datagen.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Generate data over the range of variables used in smooths — datagen","text":"data frame new values spread range observed values.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/datagen.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Generate data over the range of variables used in smooths — datagen","text":"Gavin L. Simpson","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/derivative_samples.html","id":null,"dir":"Reference","previous_headings":"","what":"Posterior expectations of derivatives from an estimated model — derivative_samples","title":"Posterior expectations of derivatives from an estimated model — derivative_samples","text":"Posterior expectations derivatives estimated model","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/derivative_samples.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Posterior expectations of derivatives from an estimated model — derivative_samples","text":"","code":"derivative_samples(object, ...) # Default S3 method derivative_samples(object, ...) # S3 method for class 'gamm' derivative_samples(object, ...) # S3 method for class 'gam' derivative_samples( object, focal = NULL, data = NULL, order = 1L, type = c(\"forward\", \"backward\", \"central\"), scale = c(\"response\", \"linear_predictor\"), method = c(\"gaussian\", \"mh\", \"inla\", \"user\"), n = 100, eps = 1e-07, n_sim = 10000, level = lifecycle::deprecated(), seed = NULL, envir = environment(formula(object)), draws = NULL, mvn_method = c(\"mvnfast\", \"mgcv\"), ... )"},{"path":"https://gavinsimpson.github.io/gratia/reference/derivative_samples.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Posterior expectations of derivatives from an estimated model — derivative_samples","text":"object R object compute derivatives ... arguments passed methods fitted_samples() focal character; name focal variable. response derivative response respect variable returned. variables involved model held constant values. can missing supplying data, case, focal variable identified one variable constant. data data frame containing values model covariates evaluate first derivatives smooths. supplied, one variable must held constant value. order numeric; order derivative. type character; type finite difference used. One \"forward\", \"backward\", \"central\". scale character; derivative estimated response linear predictor (link) scale? One \"response\" (default), \"linear predictor\". method character; method used draw samples posterior distribution. \"gaussian\" uses Gaussian (Laplace) approximation posterior. \"mh\" uses Metropolis Hastings sample alternates t proposals proposals based shrunken version posterior covariance matrix. \"inla\" uses variant Integrated Nested Laplace Approximation due Wood (2019), (currently implemented). \"user\" allows user-supplied posterior draws (currently implemented). n numeric; number points evaluate derivative (data supplied). eps numeric; finite difference. n_sim integer; number simulations used computing simultaneous intervals. level seed numeric; random seed simulations. envir environment within recreate data used fit object. draws matrix; user supplied posterior draws used method = \"user\". mvn_method character; one \"mvnfast\" \"mgcv\". default uses mvnfast::rmvn(), can considerably faster generate large numbers MVN random values mgcv::rmvn(), might work marginal fits, covariance matrix close singular.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/derivative_samples.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Posterior expectations of derivatives from an estimated model — derivative_samples","text":"tibble, currently following variables: .derivative: estimated partial derivative, additional columns containing covariate values derivative evaluated.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/derivative_samples.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Posterior expectations of derivatives from an estimated model — derivative_samples","text":"Gavin L. Simpson","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/derivative_samples.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Posterior expectations of derivatives from an estimated model — derivative_samples","text":"","code":"load_mgcv() df <- data_sim(\"eg1\", dist = \"negbin\", scale = 0.25, seed = 42) # fit the GAM (note: for execution time reasons using bam()) m <- bam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = df, family = nb(), method = \"fREML\") # data slice through data along x2 - all other covariates will be set to # typical values (value closest to median) ds <- data_slice(m, x2 = evenly(x2, n = 200)) # samples from posterior of derivatives fd_samp <- derivative_samples(m, data = ds, type = \"central\", focal = \"x2\", eps = 0.01, seed = 21, n_sim = 100 ) # plot the first 20 posterior draws if (requireNamespace(\"ggplot2\") && requireNamespace(\"dplyr\")) { library(\"ggplot2\") fd_samp |> dplyr::filter(.draw <= 20) |> ggplot(aes(x = x2, y = .derivative, group = .draw)) + geom_line(alpha = 0.5) }"},{"path":"https://gavinsimpson.github.io/gratia/reference/derivatives.html","id":null,"dir":"Reference","previous_headings":"","what":"Derivatives of estimated smooths via finite differences — derivatives","title":"Derivatives of estimated smooths via finite differences — derivatives","text":"Derivatives estimated smooths via finite differences","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/derivatives.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Derivatives of estimated smooths via finite differences — derivatives","text":"","code":"derivatives(object, ...) # Default S3 method derivatives(object, ...) # S3 method for class 'gamm' derivatives(object, ...) # S3 method for class 'gam' derivatives( object, select = NULL, term = deprecated(), data = newdata, order = 1L, type = c(\"forward\", \"backward\", \"central\"), n = 100, eps = 1e-07, interval = c(\"confidence\", \"simultaneous\"), n_sim = 10000, level = 0.95, unconditional = FALSE, frequentist = FALSE, offset = NULL, ncores = 1, partial_match = FALSE, ..., newdata = NULL )"},{"path":"https://gavinsimpson.github.io/gratia/reference/derivatives.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Derivatives of estimated smooths via finite differences — derivatives","text":"object R object compute derivatives . ... arguments passed methods. select character; select smooth's posterior draw . default (NULL) means posteriors smooths model wil sampled . supplied, character vector requested terms. Can partial match smooth term; see argument partial_match . term Use select instead. data data frame containing values model covariates evaluate first derivatives smooths. order numeric; order derivative. type character; type finite difference used. One \"forward\", \"backward\", \"central\". n numeric; number points evaluate derivative . eps numeric; finite difference. interval character; type interval compute. One \"confidence\" point-wise intervals, \"simultaneous\" simultaneous intervals. n_sim integer; number simulations used computing simultaneous intervals. level numeric; 0 < level < 1; confidence level point-wise simultaneous interval. default 0.95 95% interval. unconditional logical; use smoothness selection-corrected Bayesian covariance matrix? frequentist logical; use frequentist covariance matrix? offset numeric; value use offset term ncores number cores generating random variables multivariate normal distribution. Passed mvnfast::rmvn(). Parallelization take place OpenMP supported (appears work Windows current R). partial_match logical; smooths selected partial matches term? TRUE, term can single string match . newdata Deprecated: use data instead.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/derivatives.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Derivatives of estimated smooths via finite differences — derivatives","text":"tibble, currently following variables: smooth: smooth row refers , var: name variable involved smooth, data: values var derivative evaluated, derivative: estimated derivative, se: standard error estimated derivative, crit: critical value derivative ± (crit * se) gives upper lower bounds requested confidence simultaneous interval (given level), lower: lower bound confidence simultaneous interval, upper: upper bound confidence simultaneous interval.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/derivatives.html","id":"note","dir":"Reference","previous_headings":"","what":"Note","title":"Derivatives of estimated smooths via finite differences — derivatives","text":"derivatives() ignore random effect smooths encounters object.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/derivatives.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Derivatives of estimated smooths via finite differences — derivatives","text":"Gavin L. Simpson","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/derivatives.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Derivatives of estimated smooths via finite differences — derivatives","text":"","code":"load_mgcv() dat <- data_sim(\"eg1\", n = 400, dist = \"normal\", scale = 2, seed = 42) mod <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = dat, method = \"REML\") ## first derivatives of all smooths using central finite differences derivatives(mod, type = \"central\") #> # A tibble: 400 x 12 #> .smooth .by .fs .derivative .se .crit .lower_ci .upper_ci x0 x1 #> #> 1 s(x0) NA NA 7.41 3.33 1.96 0.874 13.9 2.39e-4 NA #> 2 s(x0) NA NA 7.40 3.33 1.96 0.884 13.9 1.03e-2 NA #> 3 s(x0) NA NA 7.39 3.30 1.96 0.929 13.8 2.04e-2 NA #> 4 s(x0) NA NA 7.36 3.24 1.96 1.01 13.7 3.04e-2 NA #> 5 s(x0) NA NA 7.32 3.15 1.96 1.14 13.5 4.05e-2 NA #> 6 s(x0) NA NA 7.26 3.04 1.96 1.30 13.2 5.06e-2 NA #> 7 s(x0) NA NA 7.18 2.90 1.96 1.49 12.9 6.06e-2 NA #> 8 s(x0) NA NA 7.09 2.76 1.96 1.69 12.5 7.07e-2 NA #> 9 s(x0) NA NA 6.99 2.61 1.96 1.87 12.1 8.07e-2 NA #> 10 s(x0) NA NA 6.87 2.47 1.96 2.03 11.7 9.08e-2 NA #> # i 390 more rows #> # i 2 more variables: x2 , x3 ## derivatives for a selected smooth derivatives(mod, type = \"central\", select = \"s(x1)\") #> # A tibble: 100 x 9 #> .smooth .by .fs .derivative .se .crit .lower_ci .upper_ci x1 #> #> 1 s(x1) NA NA -0.907 3.12 1.96 -7.02 5.20 0.000405 #> 2 s(x1) NA NA -0.906 3.11 1.96 -7.01 5.20 0.0105 #> 3 s(x1) NA NA -0.898 3.10 1.96 -6.97 5.17 0.0205 #> 4 s(x1) NA NA -0.880 3.06 1.96 -6.88 5.12 0.0306 #> 5 s(x1) NA NA -0.849 3.00 1.96 -6.73 5.03 0.0406 #> 6 s(x1) NA NA -0.803 2.92 1.96 -6.52 4.92 0.0507 #> 7 s(x1) NA NA -0.740 2.81 1.96 -6.25 4.77 0.0607 #> 8 s(x1) NA NA -0.659 2.69 1.96 -5.93 4.61 0.0708 #> 9 s(x1) NA NA -0.557 2.56 1.96 -5.57 4.46 0.0809 #> 10 s(x1) NA NA -0.436 2.42 1.96 -5.19 4.32 0.0909 #> # i 90 more rows ## or via a partial match derivatives(mod, type = \"central\", select = \"x1\", partial_match = TRUE) #> # A tibble: 100 x 9 #> .smooth .by .fs .derivative .se .crit .lower_ci .upper_ci x1 #> #> 1 s(x1) NA NA -0.907 3.12 1.96 -7.02 5.20 0.000405 #> 2 s(x1) NA NA -0.906 3.11 1.96 -7.01 5.20 0.0105 #> 3 s(x1) NA NA -0.898 3.10 1.96 -6.97 5.17 0.0205 #> 4 s(x1) NA NA -0.880 3.06 1.96 -6.88 5.12 0.0306 #> 5 s(x1) NA NA -0.849 3.00 1.96 -6.73 5.03 0.0406 #> 6 s(x1) NA NA -0.803 2.92 1.96 -6.52 4.92 0.0507 #> 7 s(x1) NA NA -0.740 2.81 1.96 -6.25 4.77 0.0607 #> 8 s(x1) NA NA -0.659 2.69 1.96 -5.93 4.61 0.0708 #> 9 s(x1) NA NA -0.557 2.56 1.96 -5.57 4.46 0.0809 #> 10 s(x1) NA NA -0.436 2.42 1.96 -5.19 4.32 0.0909 #> # i 90 more rows"},{"path":"https://gavinsimpson.github.io/gratia/reference/difference_smooths.html","id":null,"dir":"Reference","previous_headings":"","what":"Differences of factor smooth interactions — difference_smooths","title":"Differences of factor smooth interactions — difference_smooths","text":"Estimates pairwise differences (comparisons) factor smooth interactions (smooths factor argument) pairs groups defined factor. group means can optionally included difference.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/difference_smooths.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Differences of factor smooth interactions — difference_smooths","text":"","code":"difference_smooths(model, ...) # S3 method for class 'gam' difference_smooths( model, select = NULL, smooth = deprecated(), n = 100, ci_level = 0.95, data = NULL, group_means = FALSE, partial_match = TRUE, unconditional = FALSE, frequentist = FALSE, ... )"},{"path":"https://gavinsimpson.github.io/gratia/reference/difference_smooths.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Differences of factor smooth interactions — difference_smooths","text":"model fitted model. ... arguments passed methods. currently used. select character, logical, numeric; smooths plot. NULL, default, model smooths drawn. Numeric select indexes smooths order specified formula stored object. Character select matches labels smooths shown example output summary(object). Logical select operates per numeric select order smooths stored. smooth Use select instead. n numeric; number points evaluate difference pairs smooths. ci_level numeric 0 1; coverage credible interval. data data frame locations evaluate difference smooths. group_means logical; group means included difference? partial_match logical; smooth match partially smooths? partial_match = TRUE, smooth must single string, character vector length 1. Unlike similar functions, default TRUE intention users matching factor-smooth labels. unconditional logical; account smoothness selection model? frequentist logical; use frequentist covariance matrix?","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/difference_smooths.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Differences of factor smooth interactions — difference_smooths","text":"","code":"load_mgcv() df <- data_sim(\"eg4\", seed = 42) m <- gam(y ~ fac + s(x2, by = fac) + s(x0), data = df, method = \"REML\") sm_dif <- difference_smooths(m, select = \"s(x2)\") sm_dif #> # A tibble: 300 x 9 #> .smooth .by .level_1 .level_2 .diff .se .lower_ci .upper_ci x2 #> #> 1 s(x2) fac 1 2 0.386 0.618 -0.824 1.60 0.00359 #> 2 s(x2) fac 1 2 0.479 0.574 -0.646 1.60 0.0136 #> 3 s(x2) fac 1 2 0.572 0.534 -0.474 1.62 0.0237 #> 4 s(x2) fac 1 2 0.665 0.497 -0.308 1.64 0.0338 #> 5 s(x2) fac 1 2 0.758 0.464 -0.151 1.67 0.0438 #> 6 s(x2) fac 1 2 0.850 0.435 -0.00342 1.70 0.0539 #> 7 s(x2) fac 1 2 0.941 0.412 0.134 1.75 0.0639 #> 8 s(x2) fac 1 2 1.03 0.393 0.262 1.80 0.0740 #> 9 s(x2) fac 1 2 1.12 0.378 0.380 1.86 0.0841 #> 10 s(x2) fac 1 2 1.21 0.367 0.489 1.93 0.0941 #> # i 290 more rows draw(sm_dif) # include the groups means for `fac` in the difference sm_dif2 <- difference_smooths(m, select = \"s(x2)\", group_means = TRUE) draw(sm_dif2)"},{"path":[]},{"path":"https://gavinsimpson.github.io/gratia/reference/dispersion.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Dispersion parameter for fitted model — dispersion","text":"","code":"dispersion(model, ...) # S3 method for class 'gam' dispersion(model, ...) # S3 method for class 'glm' dispersion(model, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/dispersion.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Dispersion parameter for fitted model — dispersion","text":"model fitted model. ... arguments passed methods.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.basis.html","id":null,"dir":"Reference","previous_headings":"","what":"Plot basis functions — draw.basis","title":"Plot basis functions — draw.basis","text":"Plots basis functions using ggplot2","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.basis.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Plot basis functions — draw.basis","text":"","code":"# S3 method for class 'basis' draw( object, legend = FALSE, labeller = NULL, ylab = NULL, title = NULL, subtitle = NULL, caption = NULL, ncol = NULL, nrow = NULL, angle = NULL, guides = \"keep\", contour = FALSE, n_contour = 10, contour_col = \"black\", ... )"},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.basis.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Plot basis functions — draw.basis","text":"object object, result call basis(). legend logical; legend drawn indicate basis functions? labeller labeller function label facets. default use ggplot2::label_both(). ylab character expression; label y axis. supplied, suitable label generated object. title character expression; title plot. See ggplot2::labs(). subtitle character expression; subtitle plot. See ggplot2::labs(). caption character expression; plot caption. See ggplot2::labs(). ncol, nrow numeric; numbers rows columns spread plots angle numeric; angle x axis tick labels drawn passed angle argument ggplot2::guide_axis(). guides character; one \"keep\" (default), \"collect\", \"auto\". Passed patchwork::plot_layout() contour logical; contours draw plot using ggplot2::geom_contour(). n_contour numeric; number contour bins. result n_contour - 1 contour lines drawn. See ggplot2::geom_contour(). contour_col colour specification contour lines. ... arguments passed methods. used method.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.basis.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Plot basis functions — draw.basis","text":"patchwork object.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.basis.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Plot basis functions — draw.basis","text":"Gavin L. Simpson","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.basis.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Plot basis functions — draw.basis","text":"","code":"load_mgcv() df <- data_sim(\"eg1\", n = 400, seed = 42) m <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = df, method = \"REML\") bf <- basis(m) draw(bf) bf <- basis(m, \"s(x2)\") draw(bf)"},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.compare_smooths.html","id":null,"dir":"Reference","previous_headings":"","what":"Plot comparisons of smooths — draw.compare_smooths","title":"Plot comparisons of smooths — draw.compare_smooths","text":"Plot comparisons smooths","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.compare_smooths.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Plot comparisons of smooths — draw.compare_smooths","text":"","code":"# S3 method for class 'compare_smooths' draw(object, ncol = NULL, nrow = NULL, guides = \"collect\", ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.compare_smooths.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Plot comparisons of smooths — draw.compare_smooths","text":"object class \"compare_smooths\", result call compare_smooths(). ncol, nrow numeric; numbers rows columns spread plots guides character; one \"keep\" (default), \"collect\", \"auto\". Passed patchwork::plot_layout() ... additional arguments passed patchwork::wrap_plots().","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.conditional_values.html","id":null,"dir":"Reference","previous_headings":"","what":"Plot conditional predictions — draw.conditional_values","title":"Plot conditional predictions — draw.conditional_values","text":"Plot conditional predictions","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.conditional_values.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Plot conditional predictions — draw.conditional_values","text":"","code":"# S3 method for class 'conditional_values' draw( object, facet_scales = \"fixed\", discrete_colour = NULL, discrete_fill = NULL, ... )"},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.conditional_values.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Plot conditional predictions — draw.conditional_values","text":"object object class \"conditional_values\", result call conditional_values(). facet_scales character; facets axis scales across facets? See ggplot2::facet_wrap() details. Options : \"fixed\" (default), \"free_x\", \"free_y\", \"free\". discrete_colour suitable colour scale used plotting discrete variables. discrete_fill suitable fill scale used plotting discrete variables. ... additional arguments passed patchwork::wrap_plots().","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.derivatives.html","id":null,"dir":"Reference","previous_headings":"","what":"Plot derivatives of smooths — draw.derivatives","title":"Plot derivatives of smooths — draw.derivatives","text":"Plot derivatives smooths","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.derivatives.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Plot derivatives of smooths — draw.derivatives","text":"","code":"# S3 method for class 'derivatives' draw( object, select = NULL, scales = c(\"free\", \"fixed\"), add_change = FALSE, change_type = c(\"change\", \"sizer\"), alpha = 0.2, change_col = \"black\", decrease_col = \"#56B4E9\", increase_col = \"#E69F00\", lwd_change = 1.5, ncol = NULL, nrow = NULL, guides = \"keep\", angle = NULL, ... ) # S3 method for class 'partial_derivatives' draw( object, select = NULL, scales = c(\"free\", \"fixed\"), alpha = 0.2, ncol = NULL, nrow = NULL, guides = \"keep\", angle = NULL, ... )"},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.derivatives.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Plot derivatives of smooths — draw.derivatives","text":"object fitted GAM, result call mgcv::gam(). select character, logical, numeric; smooths plot. NULL, default, model smooths drawn. Numeric select indexes smooths order specified formula stored object. Character select matches labels smooths shown example output summary(object). Logical select operates per numeric select order smooths stored. scales character; univariate smooths plotted y-axis scale? scales = \"free\", default, univariate smooth y-axis scale. scales = \"fixed\", common y axis scale used univariate smooths. Currently affect y-axis scale plots parametric terms. add_change logical; periods significant change highlighted plot? change_type character; type change indicate. \"change\", differentiation made periods significant increase decrease. \"sizer\", periods increase decrease differentiated resulting plot. alpha numeric; alpha transparency confidence simultaneous interval. change_col, decrease_col, increase_col colour specifications use indicating periods change. col_change used change_type = \"change\", col_decrease col_increase used `change_type = \"sizer\"“. lwd_change numeric; linewidth use change indicators. ncol, nrow numeric; numbers rows columns spread plots guides character; one \"keep\" (default), \"collect\", \"auto\". Passed patchwork::plot_layout() angle numeric; angle x axis tick labels drawn passed angle argument ggplot2::guide_axis(). ... additional arguments passed patchwork::wrap_plots().","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.derivatives.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Plot derivatives of smooths — draw.derivatives","text":"","code":"load_mgcv() dat <- data_sim(\"eg1\", n = 800, dist = \"normal\", scale = 2, seed = 42) mod <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = dat, method = \"REML\") ## first derivative of all smooths df <- derivatives(mod, type = \"central\") draw(df) ## fixed axis scales draw(df, scales = \"fixed\")"},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.difference_smooth.html","id":null,"dir":"Reference","previous_headings":"","what":"Plot differences of smooths — draw.difference_smooth","title":"Plot differences of smooths — draw.difference_smooth","text":"Plot differences smooths","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.difference_smooth.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Plot differences of smooths — draw.difference_smooth","text":"","code":"# S3 method for class 'difference_smooth' draw( object, select = NULL, rug = FALSE, ref_line = FALSE, contour = FALSE, contour_col = \"black\", n_contour = NULL, ci_alpha = 0.2, ci_col = \"black\", smooth_col = \"black\", line_col = \"red\", scales = c(\"free\", \"fixed\"), ncol = NULL, nrow = NULL, guides = \"keep\", xlab = NULL, ylab = NULL, title = NULL, subtitle = NULL, caption = NULL, angle = NULL, ... )"},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.difference_smooth.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Plot differences of smooths — draw.difference_smooth","text":"object fitted GAM, result call mgcv::gam(). select character, logical, numeric; smooths plot. NULL, default, model smooths drawn. Numeric select indexes smooths order specified formula stored object. Character select matches labels smooths shown example output summary(object). Logical select operates per numeric select order smooths stored. rug logical; ref_line logical; contour logical; contour lines added smooth surfaces? contour_col colour specification contour lines. n_contour numeric; number contour bins. result n_contour - 1 contour lines drawn. See ggplot2::geom_contour(). ci_alpha numeric; alpha transparency confidence simultaneous interval. ci_col colour specification confidence/credible intervals band. Affects fill interval. smooth_col colour specification smooth difference line. line_col colour specification drawing reference lines scales character; univariate smooths plotted y-axis scale? scales = \"free\", default, univariate smooth y-axis scale. scales = \"fixed\", common y axis scale used univariate smooths. Currently affect y-axis scale plots parametric terms. ncol, nrow numeric; numbers rows columns spread plots guides character; one \"keep\" (default), \"collect\", \"auto\". Passed patchwork::plot_layout() xlab, ylab, title, subtitle, caption character; labels annotate plots angle numeric; angle x axis tick labels drawn passed angle argument ggplot2::guide_axis(). ... additional arguments passed patchwork::wrap_plots().","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.difference_smooth.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Plot differences of smooths — draw.difference_smooth","text":"","code":"load_mgcv() # simulate some data; a factor smooth example df <- data_sim(\"eg4\", seed = 42) # fit GAM m <- gam(y ~ fac + s(x2, by = fac) + s(x0), data = df, method = \"REML\") # calculate the differences between pairs of smooths the f_j(x2) term diffs <- difference_smooths(m, select = \"s(x2)\") draw(diffs)"},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.evaluated_parametric_term.html","id":null,"dir":"Reference","previous_headings":"","what":"Plot estimated parametric effects — draw.evaluated_parametric_term","title":"Plot estimated parametric effects — draw.evaluated_parametric_term","text":"Plots estimated univariate bivariate smooths using ggplot2.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.evaluated_parametric_term.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Plot estimated parametric effects — draw.evaluated_parametric_term","text":"","code":"# S3 method for class 'evaluated_parametric_term' draw( object, ci_level = 0.95, constant = NULL, fun = NULL, xlab, ylab, title = NULL, subtitle = NULL, caption = NULL, rug = TRUE, position = \"identity\", response_range = NULL, ... )"},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.evaluated_parametric_term.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Plot estimated parametric effects — draw.evaluated_parametric_term","text":"object object, result call evaluate_parametric_term(). ci_level numeric 0 1; coverage credible interval. constant numeric; constant add estimated values smooth. constant, supplied, added estimated value confidence band computed. fun function; function applied estimated values confidence interval plotting. Can function name function. Function fun applied adding constant, provided. xlab character expression; label x axis. supplied, suitable label generated object. ylab character expression; label y axis. supplied, suitable label generated object. title character expression; title plot. See ggplot2::labs(). subtitle character expression; subtitle plot. See ggplot2::labs(). caption character expression; plot caption. See ggplot2::labs(). rug evaluate_parametric_terms(), logical indicate rug plot drawn. position Position adjustment, either string, result call position adjustment function. response_range numeric; vector two values giving range response data guide. Used fix plots common scale/range. Ignored show set \"se\". ... arguments passed methods.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.evaluated_parametric_term.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Plot estimated parametric effects — draw.evaluated_parametric_term","text":"ggplot2::ggplot() object.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.evaluated_parametric_term.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Plot estimated parametric effects — draw.evaluated_parametric_term","text":"Gavin L. Simpson","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.gam.html","id":null,"dir":"Reference","previous_headings":"","what":"Plot estimated smooths from a fitted GAM — draw.gam","title":"Plot estimated smooths from a fitted GAM — draw.gam","text":"Plots estimated smooths fitted GAM model similar way mgcv::plot.gam() instead using base graphics, ggplot2::ggplot() used instead.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.gam.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Plot estimated smooths from a fitted GAM — draw.gam","text":"","code":"# S3 method for class 'gam' draw( object, data = NULL, select = NULL, parametric = FALSE, terms = NULL, residuals = FALSE, scales = c(\"free\", \"fixed\"), ci_level = 0.95, n = 100, n_3d = 16, n_4d = 4, unconditional = FALSE, overall_uncertainty = TRUE, constant = NULL, fun = NULL, dist = 0.1, rug = TRUE, contour = TRUE, grouped_by = FALSE, ci_alpha = 0.2, ci_col = \"black\", smooth_col = \"black\", resid_col = \"steelblue3\", contour_col = \"black\", n_contour = NULL, partial_match = FALSE, discrete_colour = NULL, discrete_fill = NULL, continuous_colour = NULL, continuous_fill = NULL, position = \"identity\", angle = NULL, ncol = NULL, nrow = NULL, guides = \"keep\", widths = NULL, heights = NULL, crs = NULL, default_crs = NULL, lims_method = \"cross\", wrap = TRUE, caption = TRUE, envir = environment(formula(object)), ... )"},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.gam.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Plot estimated smooths from a fitted GAM — draw.gam","text":"object fitted GAM, result call mgcv::gam(). data optional data frame used supply data smooths evaluated plotted. usually needed, option need fine control exactly data used plotting. select character, logical, numeric; smooths plot. NULL, default, model smooths drawn. Numeric select indexes smooths order specified formula stored object. Character select matches labels smooths shown example output summary(object). Logical select operates per numeric select order smooths stored. parametric logical; plot parametric terms also? Note select used selecting smooths plot. terms argument used select parametric effects plotted. default, mgcv::plot.gam(), draw parametric effects. terms character; model parametric terms drawn? Default NULL plot parametric terms can drawn. residuals logical; partial residuals smooth drawn? Ignored anything simple univariate smooth. scales character; univariate smooths plotted y-axis scale? scales = \"free\", default, univariate smooth y-axis scale. scales = \"fixed\", common y axis scale used univariate smooths. Currently affect y-axis scale plots parametric terms. ci_level numeric 0 1; coverage credible interval. n numeric; number points range covariate evaluate smooth. n_3d numeric; number new observations generate third dimension 3D smooth. n_4d numeric; number new observations generate dimensions higher 2 (!) kD smooth (k >= 4). example, smooth 4D smooth, dimensions 3 4 get n_4d new observations. unconditional logical; confidence intervals include uncertainty due smoothness selection? TRUE, corrected Bayesian covariance matrix used. overall_uncertainty logical; uncertainty model constant term included standard error evaluate values smooth? constant numeric; constant add estimated values smooth. constant, supplied, added estimated value confidence band computed. fun function; function applied estimated values confidence interval plotting. Can function name function. Function fun applied adding constant, provided. dist numeric; greater 0, used determine location far data plotted plotting 2-D smooths. data scaled unit square deciding exclude, dist distance within unit square. See mgcv::exclude..far() details. rug logical; draw rug plot bottom plot 1-D smooths plot locations data higher dimensions. contour logical; contours draw plot using ggplot2::geom_contour(). grouped_by logical; factor smooths drawn one panel per level factor (FALSE, default), individual smooths combined single panel containing levels (TRUE)? ci_alpha numeric; alpha transparency confidence simultaneous interval. ci_col colour specification confidence/credible intervals band. Affects fill interval. smooth_col colour specification smooth line. resid_col colour specification partial residuals. contour_col colour specification contour lines. n_contour numeric; number contour bins. result n_contour - 1 contour lines drawn. See ggplot2::geom_contour(). partial_match logical; smooths selected partial matches select? TRUE, select can single string match . discrete_colour suitable colour scale used plotting discrete variables. discrete_fill suitable fill scale used plotting discrete variables. continuous_colour suitable colour scale used plotting continuous variables. continuous_fill suitable fill scale used plotting continuous variables. position Position adjustment, either string, result call position adjustment function. angle numeric; angle x axis tick labels drawn passed angle argument ggplot2::guide_axis(). ncol, nrow numeric; numbers rows columns spread plots guides character; one \"keep\" (default), \"collect\", \"auto\". Passed patchwork::plot_layout() widths, heights relative widths heights column row grid. get repeated match dimensions grid. 1 plot widths = NULL, value widths set internally widths = 1 accommodate plots smooths use fixed aspect ratio. crs coordinate reference system (CRS) use plot. data projected CRS. See ggplot2::coord_sf() details. default_crs coordinate reference system (CRS) use non-sf layers plot. left default NULL, CRS used 4326 (WGS84), appropriate spline---sphere smooths, parameterized terms latitude longitude coordinates. See ggplot2::coord_sf() details. lims_method character; affects axis limits determined. See ggplot2::coord_sf(). careful; testing examples, changing \"orthogonal\" example chlorophyll-example Simon Wood's GAM book quickly used RAM test system OS killed R. incorrect usage part; right now grid points SOS smooths evaluated (supplied user) can produce invalid coordinates corners tiles grid generated tile centres without respect spacing tiles. wrap logical; wrap plots patchwork? FALSE, list ggplot objects returned, 1 per term plotted. caption logical; show smooth type caption plot? envir environment look data within. ... additional arguments passed patchwork::wrap_plots().","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.gam.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Plot estimated smooths from a fitted GAM — draw.gam","text":"object returned created patchwork::wrap_plots().","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.gam.html","id":"note","dir":"Reference","previous_headings":"","what":"Note","title":"Plot estimated smooths from a fitted GAM — draw.gam","text":"Internally, plots smooth created using ggplot2::ggplot() composed single plot using patchwork::wrap_plots(). result, possible use + add plots way one might typically work ggplot() plots. Instead, use & operator; see examples.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.gam.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Plot estimated smooths from a fitted GAM — draw.gam","text":"Gavin L. Simpson","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.gam.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Plot estimated smooths from a fitted GAM — draw.gam","text":"","code":"load_mgcv() # simulate some data df1 <- data_sim(\"eg1\", n = 400, dist = \"normal\", scale = 2, seed = 2) # fit GAM m1 <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = df1, method = \"REML\") # plot all smooths draw(m1) # can add partial residuals draw(m1, residuals = TRUE) df2 <- data_sim(\"eg2\", n = 1000, dist = \"normal\", scale = 1, seed = 2) m2 <- gam(y ~ s(x, z, k = 40), data = df2, method = \"REML\") draw(m2, contour = FALSE, n = 50) # See https://gavinsimpson.github.io/gratia/articles/custom-plotting.html # for more examples and for details on how to modify the theme of all the # plots produced by draw(). To modify all panels, for example to change the # theme, use the & operator"},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.gamlss.html","id":null,"dir":"Reference","previous_headings":"","what":"Plot smooths of a GAMLSS model estimated by GJRM::gamlss — draw.gamlss","title":"Plot smooths of a GAMLSS model estimated by GJRM::gamlss — draw.gamlss","text":"Provides draw() method GAMLSS (distributional GAMs) fitted GJRM::gamlss().","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.gamlss.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Plot smooths of a GAMLSS model estimated by GJRM::gamlss — draw.gamlss","text":"","code":"# S3 method for class 'gamlss' draw( object, scales = c(\"free\", \"fixed\"), ncol = NULL, nrow = NULL, guides = \"keep\", widths = NULL, heights = NULL, ... )"},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.gamlss.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Plot smooths of a GAMLSS model estimated by GJRM::gamlss — draw.gamlss","text":"object model, fitted GJRM::gamlss() scales character; univariate smooths plotted y-axis scale? scales = \"free\", default, univariate smooth y-axis scale. scales = \"fixed\", common y axis scale used univariate smooths. Currently affect y-axis scale plots parametric terms. ncol, nrow numeric; numbers rows columns spread plots guides character; one \"keep\" (default), \"collect\", \"auto\". Passed patchwork::plot_layout() widths, heights relative widths heights column row grid. get repeated match dimensions grid. 1 plot widths = NULL, value widths set internally widths = 1 accommodate plots smooths use fixed aspect ratio. ... arguments passed draw.gam()","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.gamlss.html","id":"note","dir":"Reference","previous_headings":"","what":"Note","title":"Plot smooths of a GAMLSS model estimated by GJRM::gamlss — draw.gamlss","text":"Plots smooths labelled linear predictor belong.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.gamlss.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Plot smooths of a GAMLSS model estimated by GJRM::gamlss — draw.gamlss","text":"","code":"if (require(\"GJRM\", quietly = TRUE)) { # follow example from ?GJRM::gamlss load_mgcv() suppressPackageStartupMessages(library(\"GJRM\")) set.seed(0) n <- 100 x1 <- round(runif(n)) x2 <- runif(n) x3 <- runif(n) f1 <- function(x) cos(pi * 2 * x) + sin(pi * x) y1 <- -1.55 + 2 * x1 + f1(x2) + rnorm(n) dataSim <- data.frame(y1, x1, x2, x3) eq_mu <- y1 ~ x1 + s(x2) eq_s <- ~ s(x3, k = 6) fl <- list(eq_mu, eq_s) m <- gamlss(fl, data = dataSim) draw(m) }"},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.html","id":null,"dir":"Reference","previous_headings":"","what":"Generic plotting via ggplot2 — draw","title":"Generic plotting via ggplot2 — draw","text":"Generic plotting via ggplot2","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Generic plotting via ggplot2 — draw","text":"","code":"draw(object, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Generic plotting via ggplot2 — draw","text":"object R object plot. ... arguments passed methods.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Generic plotting via ggplot2 — draw","text":"ggplot2::ggplot() object.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Generic plotting via ggplot2 — draw","text":"Generic function plotting R objects uses ggplot2 package.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Generic plotting via ggplot2 — draw","text":"Gavin L. Simpson","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.mgcv_smooth.html","id":null,"dir":"Reference","previous_headings":"","what":"Plot basis functions — draw.mgcv_smooth","title":"Plot basis functions — draw.mgcv_smooth","text":"Plots basis functions using ggplot2","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.mgcv_smooth.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Plot basis functions — draw.mgcv_smooth","text":"","code":"# S3 method for class 'mgcv_smooth' draw( object, legend = FALSE, use_facets = TRUE, labeller = NULL, xlab, ylab, title = NULL, subtitle = NULL, caption = NULL, angle = NULL, ... )"},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.mgcv_smooth.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Plot basis functions — draw.mgcv_smooth","text":"object object, result call basis(). legend logical; legend drawn indicate basis functions? use_facets logical; factor smooths, use facets show basis functions level factor? FALSE, separate ggplot object created level combined using patchwork::wrap_plots(). Currently ignored. labeller labeller function label facets. default use ggplot2::label_both(). xlab character expression; label x axis. supplied, suitable label generated object. ylab character expression; label y axis. supplied, suitable label generated object. title character expression; title plot. See ggplot2::labs(). subtitle character expression; subtitle plot. See ggplot2::labs(). caption character expression; plot caption. See ggplot2::labs(). angle numeric; angle x axis tick labels drawn passed angle argument ggplot2::guide_axis(). ... arguments passed methods. used method.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.mgcv_smooth.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Plot basis functions — draw.mgcv_smooth","text":"ggplot2::ggplot() object.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.mgcv_smooth.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Plot basis functions — draw.mgcv_smooth","text":"Gavin L. Simpson","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.mgcv_smooth.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Plot basis functions — draw.mgcv_smooth","text":"","code":"load_mgcv() df <- data_sim(\"eg4\", n = 400, seed = 42) bf <- basis(s(x0), data = df) draw(bf) bf <- basis(s(x2, by = fac, bs = \"bs\"), data = df) draw(bf)"},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.pairwise_concurvity.html","id":null,"dir":"Reference","previous_headings":"","what":"Plot concurvity measures — draw.pairwise_concurvity","title":"Plot concurvity measures — draw.pairwise_concurvity","text":"Plot concurvity measures","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.pairwise_concurvity.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Plot concurvity measures — draw.pairwise_concurvity","text":"","code":"# S3 method for class 'pairwise_concurvity' draw( object, title = \"Smooth-wise concurvity\", subtitle = NULL, caption = NULL, x_lab = \"Term\", y_lab = \"With\", fill_lab = \"Concurvity\", continuous_colour = NULL, ... ) # S3 method for class 'overall_concurvity' draw( object, title = \"Overall concurvity\", subtitle = NULL, caption = NULL, y_lab = \"Concurvity\", x_lab = NULL, bar_col = \"steelblue\", bar_fill = \"steelblue\", ... )"},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.pairwise_concurvity.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Plot concurvity measures — draw.pairwise_concurvity","text":"object object inheriting class \"concurvity\", usually result call model_concurvity() abbreviated form concrvity(). title character; plot title. subtitle character; plot subtitle. caption character; plot caption x_lab character; label x axis. y_lab character; label y axis. fill_lab character; label use fill guide. continuous_colour function; continuous colour (fill) scale use. ... arguments passed methods. bar_col colour specification bar colour. bar_fill colour specification bar fill","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.parametric_effects.html","id":null,"dir":"Reference","previous_headings":"","what":"Plot estimated effects for model parametric terms — draw.parametric_effects","title":"Plot estimated effects for model parametric terms — draw.parametric_effects","text":"Plot estimated effects model parametric terms","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.parametric_effects.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Plot estimated effects for model parametric terms — draw.parametric_effects","text":"","code":"# S3 method for class 'parametric_effects' draw( object, scales = c(\"free\", \"fixed\"), ci_level = 0.95, ci_col = \"black\", ci_alpha = 0.2, line_col = \"black\", constant = NULL, fun = NULL, rug = TRUE, position = \"identity\", angle = NULL, ..., ncol = NULL, nrow = NULL, guides = \"keep\" )"},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.parametric_effects.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Plot estimated effects for model parametric terms — draw.parametric_effects","text":"object fitted GAM, result call mgcv::gam(). scales character; univariate smooths plotted y-axis scale? scales = \"free\", default, univariate smooth y-axis scale. scales = \"fixed\", common y axis scale used univariate smooths. Currently affect y-axis scale plots parametric terms. ci_level numeric 0 1; coverage credible interval. ci_col colour specification confidence/credible intervals band. Affects fill interval. ci_alpha numeric; alpha transparency confidence simultaneous interval. line_col colour specification used regression lines linear continuous terms. constant numeric; constant add estimated values smooth. constant, supplied, added estimated value confidence band computed. fun function; function applied estimated values confidence interval plotting. Can function name function. Function fun applied adding constant, provided. rug logical; draw rug plot bottom plot 1-D smooths plot locations data higher dimensions. position Position adjustment, either string, result call position adjustment function. angle numeric; angle x axis tick labels drawn passed angle argument ggplot2::guide_axis(). ... additional arguments passed patchwork::wrap_plots(). ncol, nrow numeric; numbers rows columns spread plots guides character; one \"keep\" (default), \"collect\", \"auto\". Passed patchwork::plot_layout()","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.penalty_df.html","id":null,"dir":"Reference","previous_headings":"","what":"Display penalty matrices of smooths using ggplot — draw.penalty_df","title":"Display penalty matrices of smooths using ggplot — draw.penalty_df","text":"Displays penalty matrices smooths heatmap using ggplot","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.penalty_df.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Display penalty matrices of smooths using ggplot — draw.penalty_df","text":"","code":"# S3 method for class 'penalty_df' draw( object, normalize = FALSE, as_matrix = TRUE, continuous_fill = NULL, xlab = NULL, ylab = NULL, title = NULL, subtitle = NULL, caption = NULL, ncol = NULL, nrow = NULL, guides = \"keep\", ... )"},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.penalty_df.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Display penalty matrices of smooths using ggplot — draw.penalty_df","text":"object fitted GAM, result call mgcv::gam(). normalize logical; normalize penalty range -1, 1? as_matrix logical; plotted penalty matrix oriented? TRUE row 1, column 1 penalty matrix draw upper left, whereas, FALSE drawn lower left plot. continuous_fill suitable fill scale used plotting continuous variables. xlab character expression; label x axis. supplied, axis label drawn. May vector, one per penalty. ylab character expression; label y axis. supplied, axis label drawn. May vector, one per penalty. title character expression; title plot. See ggplot2::labs(). May vector, one per penalty. subtitle character expression; subtitle plot. See ggplot2::labs(). May vector, one per penalty. caption character expression; plot caption. See ggplot2::labs(). May vector, one per penalty. ncol, nrow numeric; numbers rows columns spread plots. guides character; one \"keep\" (default), \"collect\", \"auto\". Passed patchwork::plot_layout() ... additional arguments passed patchwork::wrap_plots().","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.penalty_df.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Display penalty matrices of smooths using ggplot — draw.penalty_df","text":"","code":"load_mgcv() dat <- data_sim(\"eg4\", n = 400, seed = 42) m <- gam(y ~ s(x0) + s(x1, bs = \"cr\") + s(x2, bs = \"bs\", by = fac), data = dat, method = \"REML\" ) ## produce a multi-panel plot of all penalties draw(penalty(m)) # for a specific smooth draw(penalty(m, select = \"s(x2):fac1\"))"},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.rootogram.html","id":null,"dir":"Reference","previous_headings":"","what":"Draw a rootogram — draw.rootogram","title":"Draw a rootogram — draw.rootogram","text":"rootogram model diagnostic tool assesses goodness fit statistical model. observed values response compared expected fitted model. discrete, count responses, frequency count (0, 1, 2, etc) observed data expected conditional distribution response implied model compared. continuous variables, observed expected frequencies obtained grouping data bins. rootogram drawn using ggplot2::ggplot() graphics. design closely follows Kleiber & Zeileis (2016).","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.rootogram.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Draw a rootogram — draw.rootogram","text":"","code":"# S3 method for class 'rootogram' draw( object, type = c(\"hanging\", \"standing\", \"suspended\"), sqrt = TRUE, ref_line = TRUE, warn_limits = TRUE, fitted_colour = \"steelblue\", bar_colour = NA, bar_fill = \"grey\", ref_line_colour = \"black\", warn_line_colour = \"black\", ylab = NULL, xlab = NULL, ... )"},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.rootogram.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Draw a rootogram — draw.rootogram","text":"object R object plot. type character; type rootogram draw. sqrt logical; show observed fitted frequencies ref_line logical; draw reference line zero? warn_limits logical; draw Tukey's warning limit lines +/- 1? fitted_colour, bar_colour, bar_fill, ref_line_colour, warn_line_colour colours used draw respective element rootogram. xlab, ylab character; labels x y axis rootogram. May missing (NULL), case suitable labels used. ' ... arguments passed methods.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.rootogram.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Draw a rootogram — draw.rootogram","text":"'ggplot' object.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.rootogram.html","id":"references","dir":"Reference","previous_headings":"","what":"References","title":"Draw a rootogram — draw.rootogram","text":"Kleiber, C., Zeileis, ., (2016) Visualizing Count Data Regressions Using Rootograms. . Stat. 70, 296–303. doi:10.1080/00031305.2016.1173590","code":""},{"path":[]},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.rootogram.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Draw a rootogram — draw.rootogram","text":"","code":"load_mgcv() df <- data_sim(\"eg1\", n = 1000, dist = \"poisson\", scale = 0.1, seed = 6) # A poisson example m <- gam(y ~ s(x0, bs = \"cr\") + s(x1, bs = \"cr\") + s(x2, bs = \"cr\") + s(x3, bs = \"cr\"), family = poisson(), data = df, method = \"REML\") rg <- rootogram(m) # plot the rootogram draw(rg) # change the type of rootogram draw(rg, type = \"suspended\")"},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.smooth_estimates.html","id":null,"dir":"Reference","previous_headings":"","what":"Plot the result of a call to smooth_estimates() — draw.smooth_estimates","title":"Plot the result of a call to smooth_estimates() — draw.smooth_estimates","text":"Plot result call smooth_estimates()","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.smooth_estimates.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Plot the result of a call to smooth_estimates() — draw.smooth_estimates","text":"","code":"# S3 method for class 'smooth_estimates' draw( object, constant = NULL, fun = NULL, contour = TRUE, grouped_by = FALSE, contour_col = \"black\", n_contour = NULL, ci_alpha = 0.2, ci_col = \"black\", smooth_col = \"black\", resid_col = \"steelblue3\", decrease_col = \"#56B4E9\", increase_col = \"#E69F00\", change_lwd = 1.75, partial_match = FALSE, discrete_colour = NULL, discrete_fill = NULL, continuous_colour = NULL, continuous_fill = NULL, angle = NULL, ylim = NULL, crs = NULL, default_crs = NULL, lims_method = \"cross\", caption = TRUE, ... )"},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.smooth_estimates.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Plot the result of a call to smooth_estimates() — draw.smooth_estimates","text":"object fitted GAM, result call mgcv::gam(). constant numeric; constant add estimated values smooth. constant, supplied, added estimated value confidence band computed. fun function; function applied estimated values confidence interval plotting. Can function name function. Function fun applied adding constant, provided. contour logical; contours draw plot using ggplot2::geom_contour(). grouped_by logical; factor smooths drawn one panel per level factor (FALSE, default), individual smooths combined single panel containing levels (TRUE)? contour_col colour specification contour lines. n_contour numeric; number contour bins. result n_contour - 1 contour lines drawn. See ggplot2::geom_contour(). ci_alpha numeric; alpha transparency confidence simultaneous interval. ci_col colour specification confidence/credible intervals band. Affects fill interval. smooth_col colour specification smooth line. resid_col colour specification partial residuals. decrease_col, increase_col colour specifications use indicating periods change. col_change used change_type = \"change\", col_decrease col_increase used `change_type = \"sizer\"“. change_lwd numeric; value set linewidth ggplot2::geom_line(), used represent periods change. partial_match logical; smooths selected partial matches select? TRUE, select can single string match . discrete_colour suitable colour scale used plotting discrete variables. discrete_fill suitable fill scale used plotting discrete variables. continuous_colour suitable colour scale used plotting continuous variables. continuous_fill suitable fill scale used plotting continuous variables. angle numeric; angle x axis tick labels drawn passed angle argument ggplot2::guide_axis(). ylim numeric; vector y axis limits use panels drawn. crs coordinate reference system (CRS) use plot. data projected CRS. See ggplot2::coord_sf() details. default_crs coordinate reference system (CRS) use non-sf layers plot. left default NULL, CRS used 4326 (WGS84), appropriate spline---sphere smooths, parameterized terms latitude longitude coordinates. See ggplot2::coord_sf() details. lims_method character; affects axis limits determined. See ggplot2::coord_sf(). careful; testing examples, changing \"orthogonal\" example chlorophyll-example Simon Wood's GAM book quickly used RAM test system OS killed R. incorrect usage part; right now grid points SOS smooths evaluated (supplied user) can produce invalid coordinates corners tiles grid generated tile centres without respect spacing tiles. caption logical; show smooth type caption plot? ... additional arguments passed patchwork::wrap_plots().","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.smooth_estimates.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Plot the result of a call to smooth_estimates() — draw.smooth_estimates","text":"","code":"load_mgcv() # example data df <- data_sim(\"eg1\", seed = 21) # fit GAM m <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = df, method = \"REML\") # plot all of the estimated smooths sm <- smooth_estimates(m) draw(sm) # evaluate smooth of `x2` sm <- smooth_estimates(m, select = \"s(x2)\") # plot it draw(sm) # customising some plot elements draw(sm, ci_col = \"steelblue\", smooth_col = \"forestgreen\", ci_alpha = 0.3) # Add a constant to the plotted smooth draw(sm, constant = coef(m)[1]) # Adding change indicators to smooths based on derivatives of the smooth d <- derivatives(m, n = 100) # n to match smooth_estimates() smooth_estimates(m) |> add_sizer(derivatives = d, type = \"sizer\") |> draw()"},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.smooth_samples.html","id":null,"dir":"Reference","previous_headings":"","what":"Plot posterior smooths — draw.smooth_samples","title":"Plot posterior smooths — draw.smooth_samples","text":"Plot posterior smooths","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.smooth_samples.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Plot posterior smooths — draw.smooth_samples","text":"","code":"# S3 method for class 'smooth_samples' draw( object, select = NULL, n_samples = NULL, seed = NULL, xlab = NULL, ylab = NULL, title = NULL, subtitle = NULL, caption = NULL, alpha = 1, colour = \"black\", contour = FALSE, contour_col = \"black\", n_contour = NULL, scales = c(\"free\", \"fixed\"), rug = TRUE, partial_match = FALSE, angle = NULL, ncol = NULL, nrow = NULL, guides = \"keep\", ... )"},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.smooth_samples.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Plot posterior smooths — draw.smooth_samples","text":"object fitted GAM, result call mgcv::gam(). select character, logical, numeric; smooths plot. NULL, default, model smooths drawn. Numeric select indexes smooths order specified formula stored object. Character select matches labels smooths shown example output summary(object). Logical select operates per numeric select order smooths stored. n_samples numeric; NULL, sample n_samples posterior draws plotting. seed numeric; random seed used sampling draws. xlab character expression; label x axis. supplied, suitable label generated object. ylab character expression; label y axis. supplied, suitable label generated object. title character expression; title plot. See ggplot2::labs(). subtitle character expression; subtitle plot. See ggplot2::labs(). caption character expression; plot caption. See ggplot2::labs(). alpha numeric; alpha transparency confidence simultaneous interval. colour colour use draw posterior smooths. Passed ggplot2::geom_line() argument colour. contour logical; contour lines added smooth surfaces? contour_col colour specification contour lines. n_contour numeric; number contour bins. result n_contour - 1 contour lines drawn. See ggplot2::geom_contour(). scales character; univariate smooths plotted y-axis scale? scales = \"free\", default, univariate smooth y-axis scale. scales = \"fixed\", common y axis scale used univariate smooths. Currently affect y-axis scale plots parametric terms. rug logical; draw rug plot bottom plot 1-D smooths plot locations data higher dimensions. partial_match logical; smooths selected partial matches select? TRUE, select can single string match . angle numeric; angle x axis tick labels drawn passed angle argument ggplot2::guide_axis(). ncol, nrow numeric; numbers rows columns spread plots guides character; one \"keep\" (default), \"collect\", \"auto\". Passed patchwork::plot_layout() ... arguments passed patchwork::wrap_plots().","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.smooth_samples.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Plot posterior smooths — draw.smooth_samples","text":"Gavin L. Simpson","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw.smooth_samples.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Plot posterior smooths — draw.smooth_samples","text":"","code":"load_mgcv() dat1 <- data_sim(\"eg1\", n = 400, dist = \"normal\", scale = 1, seed = 1) ## a single smooth GAM m1 <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = dat1, method = \"REML\") ## posterior smooths from m1 sm1 <- smooth_samples(m1, n = 15, seed = 23478) ## plot draw(sm1, alpha = 0.7) ## plot only 5 randomly smapled draws draw(sm1, n_samples = 5, alpha = 0.7) ## A factor-by smooth example dat2 <- data_sim(\"eg4\", n = 400, dist = \"normal\", scale = 1, seed = 1) ## a multi-smooth GAM with a factor-by smooth m2 <- gam(y ~ fac + s(x2, by = fac) + s(x0), data = dat2, method = \"REML\") ## posterior smooths from m1 sm2 <- smooth_samples(m2, n = 15, seed = 23478) ## plot, this time selecting only the factor-by smooth draw(sm2, select = \"s(x2)\", partial_match = TRUE, alpha = 0.7) # \\donttest{ ## A 2D smooth example dat3 <- data_sim(\"eg2\", n = 400, dist = \"normal\", scale = 1, seed = 1) ## fit a 2D smooth m3 <- gam(y ~ te(x, z), data = dat3, method = \"REML\") ## get samples sm3 <- smooth_samples(m3, n = 10) ## plot just 6 of the draws, with contour line overlays draw(sm3, n_samples = 6, contour = TRUE, seed = 42) # }"},{"path":"https://gavinsimpson.github.io/gratia/reference/draw_parametric_effect.html","id":null,"dir":"Reference","previous_headings":"","what":"Internal function to draw an individual parametric effect — draw_parametric_effect","title":"Internal function to draw an individual parametric effect — draw_parametric_effect","text":"Internal function draw individual parametric effect","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/draw_parametric_effect.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Internal function to draw an individual parametric effect — draw_parametric_effect","text":"","code":"draw_parametric_effect( object, ci_level = 0.95, ci_col = \"black\", ci_alpha = 0.2, line_col = \"black\", constant = NULL, fun = NULL, xlab = NULL, ylab = NULL, title = NULL, subtitle = NULL, caption = NULL, rug = TRUE, position = \"identity\", ylim = NULL, angle = NULL, factor_levels = NULL, ... )"},{"path":"https://gavinsimpson.github.io/gratia/reference/draw_parametric_effect.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Internal function to draw an individual parametric effect — draw_parametric_effect","text":"object fitted GAM, result call mgcv::gam(). ci_level numeric 0 1; coverage credible interval. ci_col colour specification confidence/credible intervals band. Affects fill interval. ci_alpha numeric; alpha transparency confidence simultaneous interval. constant numeric; constant add estimated values smooth. constant, supplied, added estimated value confidence band computed. fun function; function applied estimated values confidence interval plotting. Can function name function. Function fun applied adding constant, provided. xlab character expression; label x axis. supplied, suitable label generated object. ylab character expression; label y axis. supplied, suitable label generated object. title character expression; title plot. See ggplot2::labs(). subtitle character expression; subtitle plot. See ggplot2::labs(). caption character expression; plot caption. See ggplot2::labs(). rug logical; draw rug plot bottom plot 1-D smooths plot locations data higher dimensions. position Position adjustment, either string, result call position adjustment function. angle numeric; angle x axis tick labels drawn passed angle argument ggplot2::guide_axis(). factor_levels list; named list factor levels ... additional arguments passed patchwork::wrap_plots().","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/edf.html","id":null,"dir":"Reference","previous_headings":"","what":"Effective degrees of freedom for smooths and GAMs — edf","title":"Effective degrees of freedom for smooths and GAMs — edf","text":"Extracts effective degrees freedom (EDF) model smooth terms overall EDF fitted GAMs","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/edf.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Effective degrees of freedom for smooths and GAMs — edf","text":"","code":"edf(object, ...) # S3 method for class 'gam' edf( object, select = NULL, smooth = deprecated(), type = c(\"default\", \"unconditional\", \"alternative\"), partial_match = FALSE, ... ) model_edf(object, ..., type = c(\"default\", \"unconditional\", \"alternative\"))"},{"path":"https://gavinsimpson.github.io/gratia/reference/edf.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Effective degrees of freedom for smooths and GAMs — edf","text":"object fitted model extract smooth-specific EDFs. ... arguments passed methods. select character, logical, numeric; smooths plot. NULL, default, model smooths drawn. Numeric select indexes smooths order specified formula stored object. Character select matches labels smooths shown example output summary(object). Logical select operates per numeric select order smooths stored. smooth Use select instead. extracted. NULL, default, EDFs smooths returned. type character: type EDF return. \"default\" returns standard EDF; \"unconditional\" selects EDF corrected smoothness parameter selection, available; \"alternative\" returns alternative formulation EDF Wood (2017, pp. 252) partial_match logical; smooths selected partial matches select? TRUE, select can single string match .","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/edf.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Effective degrees of freedom for smooths and GAMs — edf","text":"Multiple formulations effective degrees freedom available. additional uncertainty due selection smoothness parameters can taken account computing EDF smooths. form EDF available type = \"unconditional\". Wood (2017; pp. 252) describes alternative EDF model $$\\mathrm{EDF} = 2\\mathrm{tr}(\\mathbf{F}) - \\mathrm{tr}(\\mathbf{FF}),$$ \\(\\mathrm{tr}\\) matrix trace \\(\\mathbf{F}\\) matrix mapping un-penalized coefficient estimates penalized coefficient estimates. trace \\(\\mathbf{F}\\) effectively average shrinkage coefficients multipled number coefficients (Wood, 2017). Smooth-specific EDFs obtained summing relevent elements \\(\\mathrm{diag}(2\\mathbf{F} - \\mathbf{FF})\\).","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/edf.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Effective degrees of freedom for smooths and GAMs — edf","text":"","code":"load_mgcv() df <- data_sim(\"eg1\", n = 400, seed = 42) m <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = df, method = \"REML\") # extract the EDFs for all smooths edf(m) #> # A tibble: 4 x 2 #> .smooth .edf #> #> 1 s(x0) 3.4248 #> 2 s(x1) 3.2213 #> 3 s(x2) 7.9049 #> 4 s(x3) 1.8847 # or selected smooths edf(m, select = c(\"s(x0)\", \"s(x2)\")) #> # A tibble: 2 x 2 #> .smooth .edf #> #> 1 s(x0) 3.4248 #> 2 s(x2) 7.9049 # accounting for smoothness parameter uncertainty edf(m, type = \"unconditional\") #> # A tibble: 4 x 2 #> .smooth .edf #> #> 1 s(x0) 3.7697 #> 2 s(x1) 3.8728 #> 3 s(x2) 8.0670 #> 4 s(x3) 2.8834 # over EDF of the model, including the intercept model_edf(m) #> # A tibble: 1 x 2 #> .model .edf #> #> 1 m 17.436 # can get model EDF for multiple models m2 <- gam(y ~ s(x0) + s(x1) + s(x3), data = df, method = \"REML\") model_edf(m, m2) #> # A tibble: 2 x 2 #> .model .edf #> #> 1 m 17.436 #> 2 m2 7.5777"},{"path":"https://gavinsimpson.github.io/gratia/reference/eval_smooth.html","id":null,"dir":"Reference","previous_headings":"","what":"S3 methods to evaluate individual smooths — eval_smooth","title":"S3 methods to evaluate individual smooths — eval_smooth","text":"S3 methods evaluate individual smooths","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/eval_smooth.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"S3 methods to evaluate individual smooths — eval_smooth","text":"","code":"eval_smooth(smooth, ...) # S3 method for class 'mgcv.smooth' eval_smooth( smooth, model, n = 100, n_3d = NULL, n_4d = NULL, data = NULL, unconditional = FALSE, overall_uncertainty = TRUE, dist = NULL, ... ) # S3 method for class 'soap.film' eval_smooth( smooth, model, n = 100, n_3d = NULL, n_4d = NULL, data = NULL, unconditional = FALSE, overall_uncertainty = TRUE, ... ) # S3 method for class 'scam_smooth' eval_smooth( smooth, model, n = 100, n_3d = NULL, n_4d = NULL, data = NULL, unconditional = FALSE, overall_uncertainty = TRUE, dist = NULL, ... ) # S3 method for class 'fs.interaction' eval_smooth( smooth, model, n = 100, data = NULL, unconditional = FALSE, overall_uncertainty = TRUE, ... ) # S3 method for class 'sz.interaction' eval_smooth( smooth, model, n = 100, data = NULL, unconditional = FALSE, overall_uncertainty = TRUE, ... ) # S3 method for class 'random.effect' eval_smooth( smooth, model, n = 100, data = NULL, unconditional = FALSE, overall_uncertainty = TRUE, ... ) # S3 method for class 'mrf.smooth' eval_smooth( smooth, model, n = 100, data = NULL, unconditional = FALSE, overall_uncertainty = TRUE, ... ) # S3 method for class 't2.smooth' eval_smooth( smooth, model, n = 100, n_3d = NULL, n_4d = NULL, data = NULL, unconditional = FALSE, overall_uncertainty = TRUE, dist = NULL, ... ) # S3 method for class 'tensor.smooth' eval_smooth( smooth, model, n = 100, n_3d = NULL, n_4d = NULL, data = NULL, unconditional = FALSE, overall_uncertainty = TRUE, dist = NULL, ... )"},{"path":"https://gavinsimpson.github.io/gratia/reference/eval_smooth.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"S3 methods to evaluate individual smooths — eval_smooth","text":"smooth currently object inherits class mgcv.smooth. ... arguments passed methods model fitted model; currently mgcv::gam() mgcv::bam() models suported. n numeric; number points range covariate evaluate smooth. n_3d, n_4d numeric; number points range last covariate 3D 4D smooth. default NULL achieves standard behaviour using n points range covariate, resulting n^d evaluation points, d dimension smooth. d > 2 can result many evaluation points slow performance. smooths d > 4, value n_4d used dimensions > 4, unless NULL, case default behaviour (using n dimensions) observed. data optional data frame values evaluate smooth . unconditional logical; confidence intervals include uncertainty due smoothness selection? TRUE, corrected Bayesian covariance matrix used. overall_uncertainty logical; uncertainty model constant term included standard error evaluate values smooth? dist numeric; greater 0, used determine location far data plotted plotting 2-D smooths. data scaled unit square deciding exclude, dist distance within unit square. See mgcv::exclude..far() details.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/evaluate_parametric_term.html","id":null,"dir":"Reference","previous_headings":"","what":"Evaluate parametric model terms — evaluate_parametric_term","title":"Evaluate parametric model terms — evaluate_parametric_term","text":"Returns values parametric model terms values factor terms grid covariate values linear parametric terms. function now deprecated favour parametric_effects().","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/evaluate_parametric_term.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Evaluate parametric model terms — evaluate_parametric_term","text":"","code":"evaluate_parametric_term(object, ...) # S3 method for class 'gam' evaluate_parametric_term(object, term, unconditional = FALSE, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/evaluate_parametric_term.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Evaluate parametric model terms — evaluate_parametric_term","text":"object object class \"gam\" \"gamm\". ... arguments passed methods. term character; parametric term whose effects evaluated unconditional logical; confidence intervals include uncertainty due smoothness selection? TRUE, corrected Bayesian covariance matrix used.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/evaluate_smooth.html","id":null,"dir":"Reference","previous_headings":"","what":"Evaluate a smooth — evaluate_smooth","title":"Evaluate a smooth — evaluate_smooth","text":"Evaluate smooth grid evenly spaced value range covariate associated smooth. Alternatively, set points smooth evaluated can supplied.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/evaluate_smooth.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Evaluate a smooth — evaluate_smooth","text":"","code":"evaluate_smooth(object, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/evaluate_smooth.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Evaluate a smooth — evaluate_smooth","text":"object object class \"gam\" \"gamm\". ... arguments passed methods.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/evaluate_smooth.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Evaluate a smooth — evaluate_smooth","text":"data frame, class \"evaluated_1d_smooth\" evaluated_2d_smooth, inherit classes \"evaluated_smooth\" \"data.frame\".","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/evaluate_smooth.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Evaluate a smooth — evaluate_smooth","text":"evaluate_smooth() deprecated favour smooth_estimates(), provides cleaner way evaluate smooth range covariate values. smooth_estimates() can handle much wider range models evaluate_smooth() capable smooth_estimates() much easier extend handle new smooth types. code uses evaluate_smooth() work simply changing function call smooth_estimates(). However, differences: newdata argument becomes data","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/evenly.html","id":null,"dir":"Reference","previous_headings":"","what":"Create a sequence of evenly-spaced values — evenly","title":"Create a sequence of evenly-spaced values — evenly","text":"continuous vector x, evenly seq_min_max() create sequence n evenly-spaced values range lower – upper. default, lower defined min(x) upper max(x), excluding NAs. factor x, function returns levels(x).","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/evenly.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Create a sequence of evenly-spaced values — evenly","text":"","code":"evenly(x, n = 100, by = NULL, lower = NULL, upper = NULL) seq_min_max(x, n, by = NULL, lower = NULL, upper = NULL)"},{"path":"https://gavinsimpson.github.io/gratia/reference/evenly.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Create a sequence of evenly-spaced values — evenly","text":"x numeric; vector evenly-spaced values returned n numeric; number evenly-spaced values return. default 100 used convenience typically used evaluating smooth. numeric; increment sequence. specified, argument n ignored sequence returned min(x) max(x) increments . lower numeric; lower bound interval. upper numeric; upper bound interval.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/evenly.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Create a sequence of evenly-spaced values — evenly","text":"numeric vector length n.","code":""},{"path":[]},{"path":"https://gavinsimpson.github.io/gratia/reference/evenly.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Create a sequence of evenly-spaced values — evenly","text":"","code":"x <- rnorm(10) n <- 10L # 10 values evenly over the range of `x` evenly(x, n = n) #> [1] -0.83562861 -0.56552757 -0.29542652 -0.02532547 0.24477557 0.51487662 #> [7] 0.78497766 1.05507871 1.32517976 1.59528080 # evenly spaced values, incrementing by 0.2 evenly(x, by = 0.2) #> [1] -0.83562861 -0.63562861 -0.43562861 -0.23562861 -0.03562861 0.16437139 #> [7] 0.36437139 0.56437139 0.76437139 0.96437139 1.16437139 1.36437139 #> [13] 1.56437139 # evenly spaced values, incrementing by 0.2, starting at -2 evenly(x, by = 0.2, lower = -2) #> [1] -2.0 -1.8 -1.6 -1.4 -1.2 -1.0 -0.8 -0.6 -0.4 -0.2 0.0 0.2 0.4 0.6 0.8 #> [16] 1.0 1.2 1.4"},{"path":"https://gavinsimpson.github.io/gratia/reference/factor_combos.html","id":null,"dir":"Reference","previous_headings":"","what":"All combinations of factor levels — factor_combos","title":"All combinations of factor levels — factor_combos","text":"combinations factor levels","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/factor_combos.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"All combinations of factor levels — factor_combos","text":"","code":"factor_combos(object, ...) # S3 method for class 'gam' factor_combos(object, vars = everything(), complete = TRUE, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/factor_combos.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"All combinations of factor levels — factor_combos","text":"object fitted model object. ... arguments passed methods. vars terms include exclude returned object. Uses tidyselect principles. complete logical; combinations factor levels returned? FALSE, combinations levels observed model retained.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/family.gam.html","id":null,"dir":"Reference","previous_headings":"","what":"Extract family objects from models — family.gam","title":"Extract family objects from models — family.gam","text":"Provides stats::family() method range GAM objects.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/family.gam.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Extract family objects from models — family.gam","text":"","code":"# S3 method for class 'gam' family(object, ...) # S3 method for class 'gamm' family(object, ...) # S3 method for class 'bam' family(object, ...) # S3 method for class 'list' family(object, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/family.gam.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Extract family objects from models — family.gam","text":"object fitted model. Models fitted mgcv::gam(), mgcv::bam(), mgcv::gamm(), gamm4::gamm4() currently supported. ... arguments passed methods.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/family_name.html","id":null,"dir":"Reference","previous_headings":"","what":"Name of family used to fit model — family_name","title":"Name of family used to fit model — family_name","text":"Extracts name family used fit supplied model.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/family_name.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Name of family used to fit model — family_name","text":"","code":"family_name(object, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/family_name.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Name of family used to fit model — family_name","text":"object R object. ... arguments passed methods.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/family_name.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Name of family used to fit model — family_name","text":"character vector containing family name.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/family_type.html","id":null,"dir":"Reference","previous_headings":"","what":"Extracts the type of family in a consistent way — family_type","title":"Extracts the type of family in a consistent way — family_type","text":"Extracts type family consistent way","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/family_type.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Extracts the type of family in a consistent way — family_type","text":"","code":"family_type(object, ...) # S3 method for class 'family' family_type(object, ...) # Default S3 method family_type(object, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/family_type.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Extracts the type of family in a consistent way — family_type","text":"object R object. Currently family() objects anything family() method. ... arguments passed methods.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/fderiv.html","id":null,"dir":"Reference","previous_headings":"","what":"First derivatives of fitted GAM functions — fderiv","title":"First derivatives of fitted GAM functions — fderiv","text":"function deprecated limited first order forward finite differences derivatives , improved offer needed functionality without breaking backwards compatability papers blog posts already used fderiv(). replacement, derivatives(), now available recommended new analyses.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/fderiv.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"First derivatives of fitted GAM functions — fderiv","text":"","code":"fderiv(model, ...) # S3 method for class 'gam' fderiv( model, newdata, term, n = 200, eps = 1e-07, unconditional = FALSE, offset = NULL, ... ) # S3 method for class 'gamm' fderiv(model, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/fderiv.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"First derivatives of fitted GAM functions — fderiv","text":"model fitted GAM. Currently models fitted mgcv::gam() mgcv::gamm() supported. ... Arguments passed methods. newdata data frame containing values model covariates evaluate first derivatives smooths. term character; vector one terms derivatives required. missing, derivatives smooth terms returned. n integer; newdata missing original data can reconstructed model n controls number values range covariate populate newdata. eps numeric; value finite difference used approximate first derivative. unconditional logical; TRUE, smoothing parameter uncertainty corrected covariance matrix used, available, otherwise uncorrected Bayesian posterior covariance matrix used. offset numeric; value offset use generating predictions.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/fderiv.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"First derivatives of fitted GAM functions — fderiv","text":"object class \"fderiv\" returned.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/fderiv.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"First derivatives of fitted GAM functions — fderiv","text":"Gavin L. Simpson","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/fderiv.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"First derivatives of fitted GAM functions — fderiv","text":"","code":"load_mgcv() dat <- data_sim(\"eg1\", seed = 2) mod <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = dat, method = \"REML\") ## first derivatives of all smooths... fd <- fderiv(mod) ## now use --> fd <- derivatives(mod) ## ...and a selected smooth fd2 <- fderiv(mod, term = \"x1\") ## now use --> fd2 <- derivatives(mod, select = \"s(x1)\") ## Models with factors dat <- data_sim(\"eg4\", n = 400, dist = \"normal\", scale = 2, seed = 2) mod <- gam(y ~ s(x0) + s(x1) + fac, data = dat, method = \"REML\") ## first derivatives of all smooths... fd <- fderiv(mod) ## now use --> fd <- derivatives(mod) ## ...and a selected smooth fd2 <- fderiv(mod, term = \"x1\") ## now use --> fd2 <- derivatives(mod, select = \"s(x1)\")"},{"path":"https://gavinsimpson.github.io/gratia/reference/fitted_samples.html","id":null,"dir":"Reference","previous_headings":"","what":"Draw fitted values from the posterior distribution — fitted_samples","title":"Draw fitted values from the posterior distribution — fitted_samples","text":"Expectations (fitted values) response drawn posterior distribution fitted model using Gaussian approximation posterior simple Metropolis Hastings sampler.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/fitted_samples.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Draw fitted values from the posterior distribution — fitted_samples","text":"","code":"fitted_samples(model, ...) # S3 method for class 'gam' fitted_samples( model, n = 1, data = newdata, seed = NULL, scale = c(\"response\", \"linear_predictor\"), method = c(\"gaussian\", \"mh\", \"inla\", \"user\"), n_cores = 1, burnin = 1000, thin = 1, t_df = 40, rw_scale = 0.25, freq = FALSE, unconditional = FALSE, draws = NULL, mvn_method = c(\"mvnfast\", \"mgcv\"), ..., newdata = NULL, ncores = NULL )"},{"path":"https://gavinsimpson.github.io/gratia/reference/fitted_samples.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Draw fitted values from the posterior distribution — fitted_samples","text":"model fitted model supported types ... arguments passed methods. fitted_samples(), passed mgcv::predict.gam(). posterior_samples() passed fitted_samples(). predicted_samples() passed relevant simulate() method. n numeric; number posterior samples return. data data frame; new observations posterior draws model evaluated. supplied, data used fit model used data, available model. seed numeric; random seed simulations. scale character; scale fitted values returned ? \"linear predictor\" synonym \"link\" prefer terminology. method character; method used draw samples posterior distribution. \"gaussian\" uses Gaussian (Laplace) approximation posterior. \"mh\" uses Metropolis Hastings sampler alternates t proposals proposals based shrunken version posterior covariance matrix. \"inla\" uses variant Integrated Nested Laplace Approximation due Wood (2019), (currently implemented). \"user\" allows user-supplied posterior draws (currently implemented). n_cores number cores generating random variables multivariate normal distribution. Passed mvnfast::rmvn(). Parallelization take place OpenMP supported (appears work Windows current R). burnin numeric; number samples discard burnin draws. used method = \"mh\". thin numeric; number samples skip taking n draws. Results thin * n draws posterior taken. used method = \"mh\". t_df numeric; degrees freedom t distribution proposals. used method = \"mh\". rw_scale numeric; Factor scale posterior covariance matrix generating random walk proposals. Negative non finite skip random walk step. used method = \"mh\". freq logical; TRUE use frequentist covariance matrix parameter estimators, FALSE use Bayesian posterior covariance matrix parameters. unconditional logical; TRUE (freq == FALSE) Bayesian smoothing parameter uncertainty corrected covariance matrix used, available. draws matrix; user supplied posterior draws used method = \"user\". mvn_method character; one \"mvnfast\" \"mgcv\". default uses mvnfast::rmvn(), can considerably faster generate large numbers MVN random values mgcv::rmvn(), might work marginal fits, covariance matrix close singular. newdata Deprecated: use data instead. ncores Deprecated; use n_cores instead. number cores generating random variables multivariate normal distribution. Passed mvnfast::rmvn(). Parallelization take place OpenMP supported (appears work Windows current R).","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/fitted_samples.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Draw fitted values from the posterior distribution — fitted_samples","text":"tibble (data frame) 3 columns containing posterior predicted values long format. columns row (integer) row data posterior draw relates , draw (integer) index, range 1:n, indicating draw row relates , response (numeric) predicted response indicated row data.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/fitted_samples.html","id":"note","dir":"Reference","previous_headings":"","what":"Note","title":"Draw fitted values from the posterior distribution — fitted_samples","text":"Models offset terms supplied via offset argument mgcv::gam() etc. ignored mgcv::predict.gam(). , kind offset term also ignored posterior_samples(). Offset terms included model formula supplied mgcv::gam() etc ignored posterior samples produced reflect offset term values. side effect requiring new data values provided posterior_samples() via data argument must include offset variable.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/fitted_samples.html","id":"references","dir":"Reference","previous_headings":"","what":"References","title":"Draw fitted values from the posterior distribution — fitted_samples","text":"Wood, S.N., (2020). Simplified integrated nested Laplace approximation. Biometrika 107, 223–230. doi:10.1093/biomet/asz044","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/fitted_samples.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Draw fitted values from the posterior distribution — fitted_samples","text":"Gavin L. Simpson","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/fitted_samples.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Draw fitted values from the posterior distribution — fitted_samples","text":"","code":"load_mgcv() dat <- data_sim(\"eg1\", n = 1000, dist = \"normal\", scale = 2, seed = 2) m1 <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = dat, method = \"REML\") fs <- fitted_samples(m1, n = 5, seed = 42) # \\donttest{ fs #> # A tibble: 5,000 x 4 #> .row .draw .parameter .fitted #> #> 1 1 1 location 6.34 #> 2 2 1 location 5.08 #> 3 3 1 location 6.84 #> 4 4 1 location 7.71 #> 5 5 1 location 9.23 #> 6 6 1 location 8.03 #> 7 7 1 location 6.19 #> 8 8 1 location 7.28 #> 9 9 1 location 14.0 #> 10 10 1 location 12.7 #> # i 4,990 more rows # } # can generate own set of draws and use them drws <- generate_draws(m1, n = 2, seed = 24) fs2 <- fitted_samples(m1, method = \"user\", draws = drws) # \\donttest{ fs2 #> # A tibble: 2,000 x 4 #> .row .draw .parameter .fitted #> #> 1 1 1 location 6.30 #> 2 2 1 location 5.12 #> 3 3 1 location 7.40 #> 4 4 1 location 7.42 #> 5 5 1 location 9.40 #> 6 6 1 location 8.04 #> 7 7 1 location 5.83 #> 8 8 1 location 7.30 #> 9 9 1 location 14.3 #> 10 10 1 location 13.1 #> # i 1,990 more rows # }"},{"path":"https://gavinsimpson.github.io/gratia/reference/fitted_values.html","id":null,"dir":"Reference","previous_headings":"","what":"Generate fitted values from a estimated GAM — fitted_values","title":"Generate fitted values from a estimated GAM — fitted_values","text":"Generate fitted values estimated GAM","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/fitted_values.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Generate fitted values from a estimated GAM — fitted_values","text":"","code":"fitted_values(object, ...) # S3 method for class 'gam' fitted_values( object, data = NULL, scale = c(\"response\", \"link\", \"linear predictor\"), ci_level = 0.95, ... ) # S3 method for class 'gamm' fitted_values(object, ...) # S3 method for class 'scam' fitted_values(object, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/fitted_values.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Generate fitted values from a estimated GAM — fitted_values","text":"object fitted model. Currently models fitted mgcv::gam() mgcv::bam() supported. ... arguments passed mgcv::predict.gam(). Note type, newdata, se.fit already used passed mgcv::predict.gam(). data optional data frame covariate values fitted values returned. scale character; scale fitted values returned ? \"linear predictor\" synonym \"link\" prefer terminology. ci_level numeric; value 0 1 indicating coverage credible interval.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/fitted_values.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Generate fitted values from a estimated GAM — fitted_values","text":"tibble (data frame) whose first m columns contain either data used fit model (data NULL), variables supplied data. Four columns added: fitted: fitted values specified scale, se: standard error fitted values (always link scale), lower, upper: limits credible interval fitted values, specified scale. Models fitted certain families include additional variables mgcv::ocat() models: scale = \"repsonse\", returned object contain row column category column, indicate row data row returned object belongs. Additionally, nrow(data) * n_categories rows returned object; row predicted probability single category response.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/fitted_values.html","id":"note","dir":"Reference","previous_headings":"","what":"Note","title":"Generate fitted values from a estimated GAM — fitted_values","text":"families, regardless scale fitted values returned, se component returned object link (linear predictor) scale, response scale. exception mgcv::ocat() family, se response scale scale = \"response\".","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/fitted_values.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Generate fitted values from a estimated GAM — fitted_values","text":"","code":"load_mgcv() sim_df <- data_sim(\"eg1\", n = 400, dist = \"normal\", scale = 2, seed = 2) m <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = sim_df, method = \"REML\") fv <- fitted_values(m) fv #> # A tibble: 400 x 9 #> .row x0 x1 x2 x3 .fitted .se .lower_ci #> #> 1 1 0.184882 0.617142 0.415244 0.132410 8.73875 0.354677 8.04360 #> 2 2 0.702374 0.569064 0.531439 0.365331 7.62581 0.337779 6.96378 #> 3 3 0.573326 0.153970 0.00324621 0.454532 3.12106 0.591862 1.96103 #> 4 4 0.168052 0.0348332 0.252100 0.537114 11.1124 0.402378 10.3237 #> 5 5 0.943839 0.997953 0.155229 0.185495 14.0533 0.452947 13.1655 #> 6 6 0.943475 0.835574 0.878840 0.449276 6.13080 0.364521 5.41635 #> 7 7 0.129159 0.586562 0.203511 0.256527 12.4838 0.355808 11.7864 #> 8 8 0.833449 0.339117 0.583528 0.618458 6.25215 0.344700 5.57655 #> 9 9 0.468019 0.166883 0.804473 0.880744 4.21463 0.372003 3.48552 #> 10 10 0.549984 0.807410 0.264717 0.317747 15.5283 0.369999 14.8031 #> # i 390 more rows #> # i 1 more variable: .upper_ci "},{"path":"https://gavinsimpson.github.io/gratia/reference/fix_offset.html","id":null,"dir":"Reference","previous_headings":"","what":"Fix the names of a data frame containing an offset variable. — fix_offset","title":"Fix the names of a data frame containing an offset variable. — fix_offset","text":"Identifies variable, , model offset, fixed name offset(foo(var)) converted var, possibly sets values variable offset_val.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/fix_offset.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Fix the names of a data frame containing an offset variable. — fix_offset","text":"","code":"fix_offset(model, newdata, offset_val = NULL)"},{"path":"https://gavinsimpson.github.io/gratia/reference/fix_offset.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Fix the names of a data frame containing an offset variable. — fix_offset","text":"model fitted GAM. newdata data frame; new values predict . offset_val numeric, optional; provided, offset variable newdata set constant value returning newdata","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/fix_offset.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Fix the names of a data frame containing an offset variable. — fix_offset","text":"original newdata returned fixed names possibly modified offset variable.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/fix_offset.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Fix the names of a data frame containing an offset variable. — fix_offset","text":"Gavin L. Simpson","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/fix_offset.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Fix the names of a data frame containing an offset variable. — fix_offset","text":"","code":"load_mgcv() df <- data_sim(\"eg1\", n = 400, dist = \"normal\", seed = 2) m <- gam(y ~ s(x0) + s(x1) + offset(x2), data = df, method = \"REML\") names(model.frame(m)) #> [1] \"y\" \"offset(x2)\" \"x0\" \"x1\" names(fix_offset(m, model.frame(m), offset_val = 1L)) #> [1] \"y\" \"x2\" \"x0\" \"x1\""},{"path":"https://gavinsimpson.github.io/gratia/reference/fixef.gam.html","id":null,"dir":"Reference","previous_headings":"","what":"Extract fixed effects estimates from a fitted GAM — fixef.gam","title":"Extract fixed effects estimates from a fitted GAM — fixef.gam","text":"Extract fixed effects estimates fitted GAM","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/fixef.gam.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Extract fixed effects estimates from a fitted GAM — fixef.gam","text":"","code":"# S3 method for class 'gam' fixef(object, ...) # S3 method for class 'gamm' fixef(object, ...) # S3 method for class 'lm' fixef(object, ...) # S3 method for class 'glm' fixef(object, ...) fixed_effects(object, ...) # Default S3 method fixed_effects(object, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/fixef.gam.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Extract fixed effects estimates from a fitted GAM — fixef.gam","text":"object fitted GAM ... arguments passed methods","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/fixef.gam.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Extract fixed effects estimates from a fitted GAM — fixef.gam","text":"","code":"load_mgcv() # run example if lme4 is available if (require(\"lme4\")) { data(sleepstudy, package = \"lme4\") m <- gam( Reaction ~ Days + s(Subject, bs = \"re\") + s(Days, Subject, bs = \"re\"), data = sleepstudy, method = \"REML\" ) fixef(m) } #> Loading required package: lme4 #> Loading required package: Matrix #> (Intercept) Days #> 251.40510 10.46729"},{"path":"https://gavinsimpson.github.io/gratia/reference/fixef.html","id":null,"dir":"Reference","previous_headings":"","what":"Extract fixed effects estimates — fixef","title":"Extract fixed effects estimates — fixef","text":"Extract fixed effects estimates","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/fixef.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Extract fixed effects estimates — fixef","text":"object fitted GAM ... arguments passed methods","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/gaussian_draws.html","id":null,"dir":"Reference","previous_headings":"","what":"Posterior samples using a simple Metropolis Hastings sampler — gaussian_draws","title":"Posterior samples using a simple Metropolis Hastings sampler — gaussian_draws","text":"Posterior samples using simple Metropolis Hastings sampler","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/gaussian_draws.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Posterior samples using a simple Metropolis Hastings sampler — gaussian_draws","text":"","code":"gaussian_draws(model, ...) # S3 method for class 'gam' gaussian_draws( model, n, n_cores = 1L, index = NULL, frequentist = FALSE, unconditional = FALSE, mvn_method = \"mvnfast\", ... ) # S3 method for class 'scam' gaussian_draws( model, n, n_cores = 1L, index = NULL, frequentist = FALSE, parametrized = TRUE, mvn_method = \"mvnfast\", ... )"},{"path":"https://gavinsimpson.github.io/gratia/reference/gaussian_draws.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Posterior samples using a simple Metropolis Hastings sampler — gaussian_draws","text":"model fitted R model. Currently models fitted mgcv::gam() mgcv::bam(), return object inherits objects supported. , \"inherits\" used loose fashion; models fitted scam::scam() support even though models strictly inherit class \"gam\" far inherits() concerned. ... arguments passed methods. n numeric; number posterior draws take. n_cores integer; number CPU cores use generating multivariate normal distributed random values. used mvn_method = \"mvnfast\" method = \"gaussian\". index numeric; vector indices coefficients use. Can used subset mean vector covariance matrix extracted model. frequentist logical; TRUE, frequentist covariance matrix parameter estimates used. FALSE, Bayesian posterior covariance matrix parameters used. See mgcv::vcov.gam(). unconditional logical; TRUE Bayesian smoothing parameter uncertainty corrected covariance matrix used, available model. See mgcv::vcov.gam(). mvn_method character; one \"mvnfast\" \"mgcv\". default uses mvnfast::rmvn(), can considerably faster generate large numbers MVN random values mgcv::rmvn(), might work marginal fits, covariance matrix close singular. parametrized logical; use parametrized coefficients covariance matrix, respect linear inequality constraints model. scam::scam() model fits.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/get_by_smooth.html","id":null,"dir":"Reference","previous_headings":"","what":"Extract an factor-by smooth by name — get_by_smooth","title":"Extract an factor-by smooth by name — get_by_smooth","text":"Extract factor-smooth name","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/get_by_smooth.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Extract an factor-by smooth by name — get_by_smooth","text":"","code":"get_by_smooth(object, term, level)"},{"path":"https://gavinsimpson.github.io/gratia/reference/get_by_smooth.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Extract an factor-by smooth by name — get_by_smooth","text":"object fitted GAM model object. term character; name smooth term extract. level character; level factor exrtact smooth .","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/get_by_smooth.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Extract an factor-by smooth by name — get_by_smooth","text":"single smooth object, list smooths several match named term.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/get_smooth.html","id":null,"dir":"Reference","previous_headings":"","what":"Extract an mgcv smooth by name — get_smooth","title":"Extract an mgcv smooth by name — get_smooth","text":"Extract mgcv smooth name","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/get_smooth.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Extract an mgcv smooth by name — get_smooth","text":"","code":"get_smooth(object, term)"},{"path":"https://gavinsimpson.github.io/gratia/reference/get_smooth.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Extract an mgcv smooth by name — get_smooth","text":"object fitted GAM model object. term character; name smooth term extract","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/get_smooth.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Extract an mgcv smooth by name — get_smooth","text":"single smooth object, list smooths several match named term.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/get_smooths_by_id.html","id":null,"dir":"Reference","previous_headings":"","what":"Extract an mgcv smooth given its position in the model object — get_smooths_by_id","title":"Extract an mgcv smooth given its position in the model object — get_smooths_by_id","text":"Extract mgcv smooth given position model object","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/get_smooths_by_id.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Extract an mgcv smooth given its position in the model object — get_smooths_by_id","text":"","code":"get_smooths_by_id(object, id) # S3 method for class 'gam' get_smooths_by_id(object, id) # S3 method for class 'scam' get_smooths_by_id(object, id) # S3 method for class 'gamm' get_smooths_by_id(object, id) # S3 method for class 'gamm4' get_smooths_by_id(object, id) # S3 method for class 'list' get_smooths_by_id(object, id)"},{"path":"https://gavinsimpson.github.io/gratia/reference/get_smooths_by_id.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Extract an mgcv smooth given its position in the model object — get_smooths_by_id","text":"object fitted GAM model object. id numeric; position smooth model object.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/gratia-package.html","id":null,"dir":"Reference","previous_headings":"","what":"gratia: Graceful 'ggplot'-Based Graphics and Other Functions for GAMs Fitted Using 'mgcv' — gratia-package","title":"gratia: Graceful 'ggplot'-Based Graphics and Other Functions for GAMs Fitted Using 'mgcv' — gratia-package","text":"Graceful 'ggplot'-based graphics utility functions working generalized additive models (GAMs) fitted using 'mgcv' package. Provides reimplementation plot() method GAMs 'mgcv' provides, well 'tidyverse' compatible representations estimated smooths.","code":""},{"path":[]},{"path":"https://gavinsimpson.github.io/gratia/reference/gratia-package.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"gratia: Graceful 'ggplot'-Based Graphics and Other Functions for GAMs Fitted Using 'mgcv' — gratia-package","text":"Maintainer: Gavin L. Simpson ucfagls@gmail.com (ORCID) [copyright holder] contributors: Henrik Singmann (ORCID) [contributor]","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/gss_vocab.html","id":null,"dir":"Reference","previous_headings":"","what":"Data from the General Social Survey (GSS) from the National Opinion Research Center of the University of Chicago — gss_vocab","title":"Data from the General Social Survey (GSS) from the National Opinion Research Center of the University of Chicago — gss_vocab","text":"subset data carData::GSSvocab dataset carData package, containing observations 2016 .","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/gss_vocab.html","id":"format","dir":"Reference","previous_headings":"","what":"Format","title":"Data from the General Social Survey (GSS) from the National Opinion Research Center of the University of Chicago — gss_vocab","text":"data frame 1858 rows 3 variables: vocab: numeric; number words 10 correct vocabulary test. nativeBorn: factor; respondent born US? factor levels yes. ageGroup: factor; grouped age respondent levels 18-29 30-39, 40-49, 50-59, 60+.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/gw_functions.html","id":null,"dir":"Reference","previous_headings":"","what":"Gu and Wabha test functions — gw_f0","title":"Gu and Wabha test functions — gw_f0","text":"Gu Wabha test functions","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/gw_functions.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Gu and Wabha test functions — gw_f0","text":"","code":"gw_f0(x, ...) gw_f1(x, ...) gw_f2(x, ...) gw_f3(x, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/gw_functions.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Gu and Wabha test functions — gw_f0","text":"x numeric; vector points evaluate function , interval (0,1) ... arguments passed methods, ignored.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/gw_functions.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Gu and Wabha test functions — gw_f0","text":"","code":"x <- seq(0, 1, length = 6) gw_f0(x) #> [1] 0.000e+00 1.176e+00 1.902e+00 1.902e+00 1.176e+00 2.449e-16 gw_f1(x) #> [1] 1.000 1.492 2.226 3.320 4.953 7.389 gw_f2(x) #> [1] 0.000 8.591 4.261 3.199 1.100 0.000 gw_f3(x) # should be constant 0 #> [1] 0 0 0 0 0 0"},{"path":"https://gavinsimpson.github.io/gratia/reference/has_theta.html","id":null,"dir":"Reference","previous_headings":"","what":"Are additional parameters available for a GAM? — has_theta","title":"Are additional parameters available for a GAM? — has_theta","text":"additional parameters available GAM?","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/has_theta.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Are additional parameters available for a GAM? — has_theta","text":"","code":"has_theta(object)"},{"path":"https://gavinsimpson.github.io/gratia/reference/has_theta.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Are additional parameters available for a GAM? — has_theta","text":"object R object, either family() object object whose class family() method.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/has_theta.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Are additional parameters available for a GAM? — has_theta","text":"logical; TRUE additional parameters available, FALSE otherwise.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/has_theta.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Are additional parameters available for a GAM? — has_theta","text":"","code":"load_mgcv() df <- data_sim(\"eg1\", dist = \"poisson\", seed = 42, scale = 1 / 5) m <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = df, method = \"REML\", family = nb() ) has_theta(m) #> [1] TRUE p <- theta(m)"},{"path":"https://gavinsimpson.github.io/gratia/reference/is_by_smooth.html","id":null,"dir":"Reference","previous_headings":"","what":"Tests for by variable smooths — is_by_smooth","title":"Tests for by variable smooths — is_by_smooth","text":"Functions check smooth -variable one test type -variable smooth factor-smooth continous-smooth interaction.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/is_by_smooth.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Tests for by variable smooths — is_by_smooth","text":"","code":"is_by_smooth(smooth) is_factor_by_smooth(smooth) is_continuous_by_smooth(smooth) by_variable(smooth) by_level(smooth)"},{"path":"https://gavinsimpson.github.io/gratia/reference/is_by_smooth.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Tests for by variable smooths — is_by_smooth","text":"smooth object class \"mgcv.smooth\"","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/is_by_smooth.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Tests for by variable smooths — is_by_smooth","text":"logical vector.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/is_by_smooth.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Tests for by variable smooths — is_by_smooth","text":"Gavin L. Simpson","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/is_factor_term.html","id":null,"dir":"Reference","previous_headings":"","what":"Is a model term a factor (categorical)? — is_factor_term","title":"Is a model term a factor (categorical)? — is_factor_term","text":"Given name (term label) term model, identify term factor term numeric. useful considering interactions, terms like fac1:fac2 num1:fac1 may requested user. terms type fac1:fac2 function return TRUE.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/is_factor_term.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Is a model term a factor (categorical)? — is_factor_term","text":"","code":"is_factor_term(object, term, ...) # S3 method for class 'terms' is_factor_term(object, term, ...) # S3 method for class 'gam' is_factor_term(object, term, ...) # S3 method for class 'bam' is_factor_term(object, term, ...) # S3 method for class 'gamm' is_factor_term(object, term, ...) # S3 method for class 'list' is_factor_term(object, term, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/is_factor_term.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Is a model term a factor (categorical)? — is_factor_term","text":"object R object method dispatch performed term character; name model term, sense attr(terms(object), \"term.labels\"). Currently checked see term exists model. ... arguments passed methods.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/is_factor_term.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Is a model term a factor (categorical)? — is_factor_term","text":"logical: TRUE variables involved term factors, otherwise FALSE.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/is_mgcv_smooth.html","id":null,"dir":"Reference","previous_headings":"","what":"Check if objects are smooths or are a particular type of smooth — is_mgcv_smooth","title":"Check if objects are smooths or are a particular type of smooth — is_mgcv_smooth","text":"Check objects smooths particular type smooth","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/is_mgcv_smooth.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Check if objects are smooths or are a particular type of smooth — is_mgcv_smooth","text":"","code":"is_mgcv_smooth(smooth) stop_if_not_mgcv_smooth(smooth) check_is_mgcv_smooth(smooth) is_mrf_smooth(smooth)"},{"path":"https://gavinsimpson.github.io/gratia/reference/is_mgcv_smooth.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Check if objects are smooths or are a particular type of smooth — is_mgcv_smooth","text":"smooth R object, typically list","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/is_mgcv_smooth.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Check if objects are smooths or are a particular type of smooth — is_mgcv_smooth","text":"Check smooth inherits class \"mgcv.smooth\". stop_if_not_mgcv_smooth() wrapper around is_mgcv_smooth(), useful programming checking supplied object one mgcv's smooths, throwing consistent error . check_is_mgcv_smooth() similar stop_if_not_mgcv_smooth() returns result is_mgcv_smooth() invisibly.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/is_offset.html","id":null,"dir":"Reference","previous_headings":"","what":"Is a model term an offset? — is_offset","title":"Is a model term an offset? — is_offset","text":"Given character vector model terms, checks see , , model offset.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/is_offset.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Is a model term an offset? — is_offset","text":"","code":"is_offset(terms)"},{"path":"https://gavinsimpson.github.io/gratia/reference/is_offset.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Is a model term an offset? — is_offset","text":"terms character vector model terms.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/is_offset.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Is a model term an offset? — is_offset","text":"logical vector length terms.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/is_offset.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Is a model term an offset? — is_offset","text":"Gavin L. Simpson","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/is_offset.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Is a model term an offset? — is_offset","text":"","code":"load_mgcv() df <- data_sim(\"eg1\", n = 400, dist = \"normal\") m <- gam(y ~ s(x0) + s(x1) + offset(x0), data = df, method = \"REML\") nm <- names(model.frame(m)) nm #> [1] \"y\" \"offset(x0)\" \"x0\" \"x1\" is_offset(nm) #> [1] FALSE TRUE FALSE FALSE"},{"path":"https://gavinsimpson.github.io/gratia/reference/link.html","id":null,"dir":"Reference","previous_headings":"","what":"Extract link and inverse link functions from models — link","title":"Extract link and inverse link functions from models — link","text":"Returns link inverse estimated model, provides simple way extract functions complex models multiple links, location scale models.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/link.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Extract link and inverse link functions from models — link","text":"","code":"link(object, ...) # S3 method for class 'family' link(object, parameter = NULL, which_eta = NULL, ...) # S3 method for class 'gam' link(object, parameter = NULL, which_eta = NULL, ...) # S3 method for class 'bam' link(object, parameter = NULL, which_eta = NULL, ...) # S3 method for class 'gamm' link(object, ...) # S3 method for class 'glm' link(object, ...) # S3 method for class 'list' link(object, ...) inv_link(object, ...) # S3 method for class 'family' inv_link(object, parameter = NULL, which_eta = NULL, ...) # S3 method for class 'gam' inv_link(object, parameter = NULL, which_eta = NULL, ...) # S3 method for class 'bam' inv_link(object, parameter = NULL, which_eta = NULL, ...) # S3 method for class 'gamm' inv_link(object, ...) # S3 method for class 'list' inv_link(object, ...) # S3 method for class 'glm' inv_link(object, ...) extract_link(family, ...) # S3 method for class 'family' extract_link(family, inverse = FALSE, ...) # S3 method for class 'general.family' extract_link(family, parameter, inverse = FALSE, which_eta = NULL, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/link.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Extract link and inverse link functions from models — link","text":"object family object fitted model extract family object. Models fitted stats::glm(), mgcv::gam(), mgcv::bam(), mgcv::gamm(), gamm4::gamm4() currently supported. ... arguments passed methods. parameter character; parameter distribution. Usually \"location\" \"scale\" \"shape\" may provided location scale models. options include \"mu\" synonym \"location\", \"sigma\" scale parameter mgcv::gaulss(), \"pi\" zero-inflation term mgcv::ziplss(), \"power\" mgcv::twlss() power parameter, \"xi\", shape parameter mgcv::gevlss(), \"epsilon\" \"skewness\" skewness \"delta\" \"kurtosis\" kurtosis parameter mgcv::shash(), \"phi\" scale parameter mgcv::gammals() & mgcv::twlss(). which_eta numeric; linear predictor extract families mgcv::mvn() mgcv::multinom(). family family object, result call family(). inverse logical; return inverse link function?","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/link.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Extract link and inverse link functions from models — link","text":"Gavin L. Simpson","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/link.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Extract link and inverse link functions from models — link","text":"","code":"load_mgcv() link(gaussian()) #> function (mu) #> mu #> link(nb()) #> function (mu) #> log(mu) #> inv_link(nb()) #> function (eta) #> pmax(exp(eta), .Machine$double.eps) #> dat <- data_sim(\"eg1\", seed = 4234) mod <- gam(list(y ~ s(x0) + s(x1) + s(x2) + s(x3), ~1), data = dat, family = gaulss ) link(mod, parameter = \"scale\") #> function (mu) #> log(1/mu - 0.01) #> inv_link(mod, parameter = \"scale\") #> function (eta) #> 1/(exp(eta) + 0.01) #> ## Works with `family` objects too link(shash(), parameter = \"skewness\") #> function (mu) #> mu #> "},{"path":"https://gavinsimpson.github.io/gratia/reference/load_mgcv.html","id":null,"dir":"Reference","previous_headings":"","what":"Load mgcv quietly — load_mgcv","title":"Load mgcv quietly — load_mgcv","text":"Simple function loads mgcv package whilst suppressing startup messages prints console.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/load_mgcv.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Load mgcv quietly — load_mgcv","text":"","code":"load_mgcv()"},{"path":"https://gavinsimpson.github.io/gratia/reference/load_mgcv.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Load mgcv quietly — load_mgcv","text":"Returns logical vectors invisibly, indicating whether package loaded .","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/lp_matrix.html","id":null,"dir":"Reference","previous_headings":"","what":"Return the linear prediction matrix of a fitted GAM — lp_matrix","title":"Return the linear prediction matrix of a fitted GAM — lp_matrix","text":"lp_matrix() wrapper predict(..., type = \"lpmatrix\") returning linear predictor matrix model training data (data = NULL), user-specified data values supplied via data.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/lp_matrix.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Return the linear prediction matrix of a fitted GAM — lp_matrix","text":"","code":"lp_matrix(model, ...) # S3 method for class 'gam' lp_matrix(model, data = NULL, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/lp_matrix.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Return the linear prediction matrix of a fitted GAM — lp_matrix","text":"model fitted model ... arguments passed methods predict methods including mgcv::predict.gam() mgcv::predict.bam() data data frame values return linear prediction matrix.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/lp_matrix.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Return the linear prediction matrix of a fitted GAM — lp_matrix","text":"linear prediction matrix returned matrix. object returned class \"lp_matrix\", inherits classes \"matrix\" \"array\". special class allows printing matrix controlled, printing matrix tibble.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/lp_matrix.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Return the linear prediction matrix of a fitted GAM — lp_matrix","text":"linear prediction matrix \\(\\mathbf{X}_p\\) matrix maps values parameters \\(\\hat{\\mathbf{\\beta}}_p\\) values linear predictor model \\(\\hat{\\eta}_p = \\mathbf{X}_p \\hat{\\mathbf{\\beta}}_p\\). \\(\\mathbf{X}_p\\) model matrix spline covariates replaced values basis functions evaluated respective covariates. Parametric covariates also included.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/lp_matrix.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Return the linear prediction matrix of a fitted GAM — lp_matrix","text":"","code":"load_mgcv() df <- data_sim(\"eg1\", seed = 1) m <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = df) # linear prediction matrix for observed data xp <- lp_matrix(m) ## IGNORE_RDIFF_BEGIN xp #> Linear prediction matrix (400 x 37) #> `(Intercept)` `s(x0).1` `s(x0).2` `s(x0).3` `s(x0).4` `s(x0).5` `s(x0).6` #> #> 1 1 0.961 0.227 0.706 -0.135 0.457 -0.146 #> 2 1 0.651 -0.241 0.0684 -0.308 0.394 -0.00994 #> 3 1 -0.385 -0.549 0.0660 -0.204 -0.416 -0.247 #> 4 1 -1.27 0.156 -1.53 0.222 -1.60 0.198 #> 5 1 1.05 0.420 1.11 0.214 0.893 0.0351 #> # i 395 more rows ## IGNORE_RDIFF_END # the object `xp` *is* a matrix class(xp) #> [1] \"lp_matrix\" \"matrix\" \"array\" # but we print like a tibble to avoid spamming the R console # linear predictor matrix for new data set ds <- data_slice(m, x2 = evenly(x2)) xp <- lp_matrix(m, data = ds) ## IGNORE_RDIFF_BEGIN xp #> Linear prediction matrix (100 x 37) #> `(Intercept)` `s(x0).1` `s(x0).2` `s(x0).3` `s(x0).4` `s(x0).5` `s(x0).6` #> #> 1 1 0.170 -0.542 -0.0371 -0.0534 0.144 -0.353 #> 2 1 0.170 -0.542 -0.0371 -0.0534 0.144 -0.353 #> 3 1 0.170 -0.542 -0.0371 -0.0534 0.144 -0.353 #> 4 1 0.170 -0.542 -0.0371 -0.0534 0.144 -0.353 #> 5 1 0.170 -0.542 -0.0371 -0.0534 0.144 -0.353 #> # i 95 more rows ## IGNORE_RDIFF_END"},{"path":"https://gavinsimpson.github.io/gratia/reference/lss_parameters.html","id":null,"dir":"Reference","previous_headings":"","what":"General names of LSS parameters for each GAM family — lss_parameters","title":"General names of LSS parameters for each GAM family — lss_parameters","text":"General names LSS parameters GAM family","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/lss_parameters.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"General names of LSS parameters for each GAM family — lss_parameters","text":"","code":"lss_parameters(object)"},{"path":"https://gavinsimpson.github.io/gratia/reference/mh_draws.html","id":null,"dir":"Reference","previous_headings":"","what":"Posterior samples using a Gaussian approximation to the posterior distribution — mh_draws","title":"Posterior samples using a Gaussian approximation to the posterior distribution — mh_draws","text":"Posterior samples using Gaussian approximation posterior distribution","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/mh_draws.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Posterior samples using a Gaussian approximation to the posterior distribution — mh_draws","text":"","code":"mh_draws(model, ...) # S3 method for class 'gam' mh_draws( model, n, burnin = 1000, thin = 1, t_df = 40, rw_scale = 0.25, index = NULL, ... )"},{"path":"https://gavinsimpson.github.io/gratia/reference/mh_draws.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Posterior samples using a Gaussian approximation to the posterior distribution — mh_draws","text":"model fitted R model. Currently models fitted mgcv::gam() mgcv::bam(), return object inherits objects supported. , \"inherits\" used loose fashion; models fitted scam::scam() support even though models strictly inherit class \"gam\" far inherits() concerned. ... arguments passed methods. n numeric; number posterior draws take. burnin numeric; length initial burn period discard. See mgcv::gam.mh(). thin numeric; retain thin samples. See mgcv::gam.mh(). t_df numeric; degrees freedom static multivariate t proposal. See mgcv::gam.mh(). rw_scale numeric; factor scale posterior covariance matrix generating random walk proposals. See mgcv::gam.mh(). index numeric; vector indices coefficients use. Can used subset mean vector covariance matrix extracted model.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/model_concurvity.html","id":null,"dir":"Reference","previous_headings":"","what":"Concurvity of an estimated GAM — model_concurvity","title":"Concurvity of an estimated GAM — model_concurvity","text":"Concurvity estimated GAM","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/model_concurvity.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Concurvity of an estimated GAM — model_concurvity","text":"","code":"model_concurvity(model, ...) # S3 method for class 'gam' model_concurvity( model, terms = everything(), type = c(\"all\", \"estimate\", \"observed\", \"worst\"), pairwise = FALSE, ... ) concrvity( model, terms = everything(), type = c(\"all\", \"estimate\", \"observed\", \"worst\"), pairwise = FALSE, ... )"},{"path":"https://gavinsimpson.github.io/gratia/reference/model_concurvity.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Concurvity of an estimated GAM — model_concurvity","text":"model fitted GAM. Currently objects class \"gam\" supported ... arguents passed methods. terms currently ignored type character; pairwise logical; extract pairwise concurvity model terms?","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/model_concurvity.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Concurvity of an estimated GAM — model_concurvity","text":"","code":"## simulate data with concurvity... library(\"tibble\") load_mgcv() set.seed(8) n <- 200 df <- tibble( t = sort(runif(n)), x = gw_f2(t) + rnorm(n) * 3, y = sin(4 * pi * t) + exp(x / 20) + rnorm(n) * 0.3 ) ## fit model m <- gam(y ~ s(t, k = 15) + s(x, k = 15), data = df, method = \"REML\") ## overall concurvity o_conc <- concrvity(m) draw(o_conc) ## pairwise concurvity p_conc <- concrvity(m, pairwise = TRUE) draw(p_conc)"},{"path":"https://gavinsimpson.github.io/gratia/reference/model_constant.html","id":null,"dir":"Reference","previous_headings":"","what":"Extract the model constant term — model_constant","title":"Extract the model constant term — model_constant","text":"Extracts model constant term(s), model intercept, fitted model object.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/model_constant.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Extract the model constant term — model_constant","text":"","code":"model_constant(model, ...) # S3 method for class 'gam' model_constant(model, lp = NULL, ...) # S3 method for class 'gamlss' model_constant(model, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/model_constant.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Extract the model constant term — model_constant","text":"model fitted model coef() method exists. ... arguments passed methods. lp numeric; linear predictors extract constant terms .","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/model_constant.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Extract the model constant term — model_constant","text":"","code":"load_mgcv() # simulate a small example df <- data_sim(\"eg1\", seed = 42) # fit the GAM m <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = df, method = \"REML\") # extract the estimate of the constant term model_constant(m) #> [1] 7.495 #> attr(,\"par_names\") #> [1] \"location\" # same as coef(m)[1L] coef(m)[1L] #> (Intercept) #> 7.495"},{"path":"https://gavinsimpson.github.io/gratia/reference/model_vars.html","id":null,"dir":"Reference","previous_headings":"","what":"List the variables involved in a model fitted with a formula — model_vars","title":"List the variables involved in a model fitted with a formula — model_vars","text":"List variables involved model fitted formula","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/model_vars.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"List the variables involved in a model fitted with a formula — model_vars","text":"","code":"model_vars(model, ...) # S3 method for class 'gam' model_vars(model, ...) # Default S3 method model_vars(model, ...) # S3 method for class 'bam' model_vars(model, ...) # S3 method for class 'gamm' model_vars(model, ...) # S3 method for class 'gamm4' model_vars(model, ...) # S3 method for class 'list' model_vars(model, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/model_vars.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"List the variables involved in a model fitted with a formula — model_vars","text":"model fitted model object $pred.formula, $terms component \"terms\" attribute ... Arguments passed methods. Currently ignored.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/model_vars.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"List the variables involved in a model fitted with a formula — model_vars","text":"","code":"load_mgcv() # simulate some Gaussian data df <- data_sim(\"eg1\", n = 50, seed = 2) # fit a GAM with 1 smooth and 1 linear term m1 <- gam(y ~ s(x2, k = 7) + x1, data = df, method = \"REML\") model_vars(m1) #> [1] \"x1\" \"x2\" # fit a lm with two linear terms m2 <- lm(y ~ x2 + x1, data = df) model_vars(m2) #> [1] \"x2\" \"x1\""},{"path":"https://gavinsimpson.github.io/gratia/reference/n_eta.html","id":null,"dir":"Reference","previous_headings":"","what":"The Number of linear predictors in model — n_eta","title":"The Number of linear predictors in model — n_eta","text":"Extracts number linear predictors fitted model.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/n_eta.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"The Number of linear predictors in model — n_eta","text":"","code":"n_eta(model, ...) # S3 method for class 'gam' n_eta(model, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/n_eta.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"The Number of linear predictors in model — n_eta","text":"model fitted model. Currently, models inheriting class \"gam\" supported. ... arguments passed methods.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/n_eta.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"The Number of linear predictors in model — n_eta","text":"integer vector length 1 containing number linear predictors model.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/n_smooths.html","id":null,"dir":"Reference","previous_headings":"","what":"How many smooths in a fitted model — n_smooths","title":"How many smooths in a fitted model — n_smooths","text":"many smooths fitted model","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/n_smooths.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"How many smooths in a fitted model — n_smooths","text":"","code":"n_smooths(object) # Default S3 method n_smooths(object) # S3 method for class 'gam' n_smooths(object) # S3 method for class 'gamm' n_smooths(object) # S3 method for class 'bam' n_smooths(object)"},{"path":"https://gavinsimpson.github.io/gratia/reference/n_smooths.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"How many smooths in a fitted model — n_smooths","text":"object fitted GAM related model. Typically result call mgcv::gam(), mgcv::bam(), mgcv::gamm().","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/nb_theta.html","id":null,"dir":"Reference","previous_headings":"","what":"Negative binomial parameter theta — nb_theta","title":"Negative binomial parameter theta — nb_theta","text":"Negative binomial parameter theta","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/nb_theta.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Negative binomial parameter theta — nb_theta","text":"","code":"nb_theta(model) # S3 method for class 'gam' nb_theta(model)"},{"path":"https://gavinsimpson.github.io/gratia/reference/nb_theta.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Negative binomial parameter theta — nb_theta","text":"model fitted model.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/nb_theta.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Negative binomial parameter theta — nb_theta","text":"numeric vector length 1 containing estimated value theta.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/nb_theta.html","id":"methods-by-class-","dir":"Reference","previous_headings":"","what":"Methods (by class)","title":"Negative binomial parameter theta — nb_theta","text":"nb_theta(gam): Method class \"gam\"","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/nb_theta.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Negative binomial parameter theta — nb_theta","text":"","code":"load_mgcv() df <- data_sim(\"eg1\", n = 500, dist = \"poisson\", scale = 0.1, seed = 6) m <- gam(y ~ s(x0, bs = \"cr\") + s(x1, bs = \"cr\") + s(x2, bs = \"cr\") + s(x3, bs = \"cr\"), family = nb, data = df, method = \"REML\") ## IGNORE_RDIFF_BEGIN nb_theta(m) #> [1] 239333.8 ## IGNORE_RDIFF_END"},{"path":"https://gavinsimpson.github.io/gratia/reference/nested_partial_residuals.html","id":null,"dir":"Reference","previous_headings":"","what":"Partial residuals in nested form — nested_partial_residuals","title":"Partial residuals in nested form — nested_partial_residuals","text":"Computes partial residuals smooth terms, formats long/tidy format, nests partial_residual column result nested data frame one row per smooth.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/nested_partial_residuals.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Partial residuals in nested form — nested_partial_residuals","text":"","code":"nested_partial_residuals(object, terms = NULL, data = NULL)"},{"path":"https://gavinsimpson.github.io/gratia/reference/nested_partial_residuals.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Partial residuals in nested form — nested_partial_residuals","text":"object fitted GAM model terms vector terms include partial residuals . Passed argument terms mgcv::predict.gam()]. data optional data frame","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/nested_partial_residuals.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Partial residuals in nested form — nested_partial_residuals","text":"nested tibble (data frame) one row per smooth term. Contains two columns: smooth - label indicating smooth term partial_residual - list column containing tibble (data frame) 1 column partial_residual containing requested partial residuals indicated smooth.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/nested_rug_values.html","id":null,"dir":"Reference","previous_headings":"","what":"Values for rug plot in nested form — nested_rug_values","title":"Values for rug plot in nested form — nested_rug_values","text":"Extracts original data smooth terms, formats long/tidy format, nests data column(s) result nested data frame one row per smooth.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/nested_rug_values.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Values for rug plot in nested form — nested_rug_values","text":"","code":"nested_rug_values(object, terms = NULL, data = NULL)"},{"path":"https://gavinsimpson.github.io/gratia/reference/nested_rug_values.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Values for rug plot in nested form — nested_rug_values","text":"object fitted GAM model terms vector terms include original data . Passed argument terms mgcv::predict.gam()]. data optional data frame","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/nested_rug_values.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Values for rug plot in nested form — nested_rug_values","text":"nested tibble (data frame) one row per smooth term.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/null_deviance.html","id":null,"dir":"Reference","previous_headings":"","what":"Extract the null deviance of a fitted model — null_deviance","title":"Extract the null deviance of a fitted model — null_deviance","text":"Extract null deviance fitted model","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/null_deviance.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Extract the null deviance of a fitted model — null_deviance","text":"","code":"null_deviance(model, ...) # Default S3 method null_deviance(model, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/null_deviance.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Extract the null deviance of a fitted model — null_deviance","text":"model fitted model ... arguments passed methods","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/observed_fitted_plot.html","id":null,"dir":"Reference","previous_headings":"","what":"Plot of fitted against observed response values — observed_fitted_plot","title":"Plot of fitted against observed response values — observed_fitted_plot","text":"Plot fitted observed response values","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/observed_fitted_plot.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Plot of fitted against observed response values — observed_fitted_plot","text":"","code":"observed_fitted_plot( model, ylab = NULL, xlab = NULL, title = NULL, subtitle = NULL, caption = NULL, point_col = \"black\", point_alpha = 1 )"},{"path":"https://gavinsimpson.github.io/gratia/reference/observed_fitted_plot.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Plot of fitted against observed response values — observed_fitted_plot","text":"model fitted model. Currently class \"gam\". ylab character expression; label y axis. supplied, suitable label generated. xlab character expression; label y axis. supplied, suitable label generated. title character expression; title plot. See ggplot2::labs(). subtitle character expression; subtitle plot. See ggplot2::labs(). caption character expression; plot caption. See ggplot2::labs(). point_col colour used draw points plots. See graphics::par() section Color Specification. passed individual plotting functions, therefore affects points plots. point_alpha numeric; alpha transparency points plots.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/overview.html","id":null,"dir":"Reference","previous_headings":"","what":"Provides an overview of a model and the terms in that model — overview","title":"Provides an overview of a model and the terms in that model — overview","text":"Provides overview model terms model","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/overview.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Provides an overview of a model and the terms in that model — overview","text":"","code":"overview(model, ...) # S3 method for class 'gam' overview( model, parametric = TRUE, random_effects = TRUE, dispersion = NULL, frequentist = FALSE, accuracy = 0.001, stars = FALSE, ... )"},{"path":"https://gavinsimpson.github.io/gratia/reference/overview.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Provides an overview of a model and the terms in that model — overview","text":"model fitted model object overview. ... arguments passed methods. parametric logical; include model parametric terms overview? random_effects tests fully penalized smooth terms (zero-dimensional null space, e.g. random effects) computationally expensive large data sets producing p values can take long time. random_effects = FALSE, tests expensive terms skipped. dispersion numeric; known value dispersion parameter. default NULL implies estimated value default value (1 Poisson distribution example) specified used instead. frequentist logical; default Bayesian estimated covariance matrix parameter estimates used calculate p values parametric terms. frequentist = FALSE, frequentist covariance matrix parameter estimates used. accuracy numeric; accuracy report p values, p values value displayed \"< accuracy\". stars logical; significance stars added output?","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/overview.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Provides an overview of a model and the terms in that model — overview","text":"","code":"load_mgcv() df <- data_sim(n = 400, seed = 2) m <- gam(y ~ x3 + s(x0) + s(x1, bs = \"bs\") + s(x2, bs = \"ts\"), data = df, method = \"REML\" ) overview(m) #> #> Generalized Additive Model with 4 terms #> #> term type k edf statistic p.value #> #> 1 x3 parametric NA 1 4.28 0.03926 #> 2 s(x0) TPRS 9 3.02 6.25 < 0.001 #> 3 s(x1) B spline 9 2.81 71.0 < 0.001 #> 4 s(x2) TPRS (shrink) 9 7.91 83.8 < 0.001"},{"path":"https://gavinsimpson.github.io/gratia/reference/parametric_effects.html","id":null,"dir":"Reference","previous_headings":"","what":"Estimated values for parametric model terms — parametric_effects","title":"Estimated values for parametric model terms — parametric_effects","text":"Estimated values parametric model terms","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/parametric_effects.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Estimated values for parametric model terms — parametric_effects","text":"","code":"parametric_effects(object, ...) # S3 method for class 'gam' parametric_effects( object, terms = NULL, data = NULL, unconditional = FALSE, unnest = TRUE, ci_level = 0.95, envir = environment(formula(object)), transform = FALSE, ... )"},{"path":"https://gavinsimpson.github.io/gratia/reference/parametric_effects.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Estimated values for parametric model terms — parametric_effects","text":"object fitted model object. ... arguments passed methods. terms character; model parametric terms drawn? Default NULL plot parametric terms can drawn. data optional data frame may may used? FIXME! unconditional logical; confidence intervals include uncertainty due smoothness selection? TRUE, corrected Bayesian covariance matrix used. unnest logical; unnest parametric effect objects? ci_level numeric; coverage required confidence interval. Currently ignored. envir environment look data within. transform logical; TRUE, parametric effect plotted transformed scale result effect straight line. FALSE, effect plotted raw data (.e. log10(x), poly(z), x-axis plot x z respectively.)","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/parametric_terms.html","id":null,"dir":"Reference","previous_headings":"","what":"Names of any parametric terms in a GAM — parametric_terms","title":"Names of any parametric terms in a GAM — parametric_terms","text":"Names parametric terms GAM","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/parametric_terms.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Names of any parametric terms in a GAM — parametric_terms","text":"","code":"parametric_terms(model, ...) # Default S3 method parametric_terms(model, ...) # S3 method for class 'gam' parametric_terms(model, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/parametric_terms.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Names of any parametric terms in a GAM — parametric_terms","text":"model fitted model. ... arguments passed methods.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/partial_derivatives.html","id":null,"dir":"Reference","previous_headings":"","what":"Partial derivatives of estimated multivariate smooths via finite differences — partial_derivatives","title":"Partial derivatives of estimated multivariate smooths via finite differences — partial_derivatives","text":"Partial derivatives estimated multivariate smooths via finite differences","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/partial_derivatives.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Partial derivatives of estimated multivariate smooths via finite differences — partial_derivatives","text":"","code":"partial_derivatives(object, ...) # Default S3 method partial_derivatives(object, ...) # S3 method for class 'gamm' partial_derivatives(object, ...) # S3 method for class 'gam' partial_derivatives( object, select = NULL, term = deprecated(), focal = NULL, data = newdata, order = 1L, type = c(\"forward\", \"backward\", \"central\"), n = 100, eps = 1e-07, interval = c(\"confidence\", \"simultaneous\"), n_sim = 10000, level = 0.95, unconditional = FALSE, frequentist = FALSE, offset = NULL, ncores = 1, partial_match = FALSE, seed = NULL, ..., newdata = NULL )"},{"path":"https://gavinsimpson.github.io/gratia/reference/partial_derivatives.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Partial derivatives of estimated multivariate smooths via finite differences — partial_derivatives","text":"object R object compute derivatives . ... arguments passed methods. select character; vector one smooth terms derivatives required. missing, derivatives smooth terms returned. Can partial match smooth term; see argument partial_match . term Use select instead. focal character; name focal variable. partial derivative estimated smooth respect variable returned. variables involved smooth held constant. can missing supplying data, case, focal variable identified one variable constant. data data frame containing values model covariates evaluate first derivatives smooths. supplied, one variable must held constant value. order numeric; order derivative. type character; type finite difference used. One \"forward\", \"backward\", \"central\". n numeric; number points evaluate derivative . eps numeric; finite difference. interval character; type interval compute. One \"confidence\" point-wise intervals, \"simultaneous\" simultaneous intervals. n_sim integer; number simulations used computing simultaneous intervals. level numeric; 0 < level < 1; confidence level point-wise simultaneous interval. default 0.95 95% interval. unconditional logical; use smoothness selection-corrected Bayesian covariance matrix? frequentist logical; use frequentist covariance matrix? offset numeric; value use offset term ncores number cores generating random variables multivariate normal distribution. Passed mvnfast::rmvn(). Parallelization take place OpenMP supported (appears work Windows current R). partial_match logical; smooths selected partial matches term? TRUE, term can single string match . seed numeric; RNG seed use. newdata Deprecated: use data instead.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/partial_derivatives.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Partial derivatives of estimated multivariate smooths via finite differences — partial_derivatives","text":"tibble, currently following variables: .smooth: smooth row refers , .partial_deriv: estimated partial derivative, .se: standard error estimated partial derivative, .crit: critical value derivative ± (crit * se) gives upper lower bounds requested confidence simultaneous interval (given level), .lower_ci: lower bound confidence simultaneous interval, .upper_ci: upper bound confidence simultaneous interval.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/partial_derivatives.html","id":"note","dir":"Reference","previous_headings":"","what":"Note","title":"Partial derivatives of estimated multivariate smooths via finite differences — partial_derivatives","text":"partial_derivatives() ignore random effect smooths encounters object.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/partial_derivatives.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Partial derivatives of estimated multivariate smooths via finite differences — partial_derivatives","text":"Gavin L. Simpson","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/partial_derivatives.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Partial derivatives of estimated multivariate smooths via finite differences — partial_derivatives","text":"","code":"library(\"ggplot2\") library(\"patchwork\") load_mgcv() df <- data_sim(\"eg2\", n = 2000, dist = \"normal\", scale = 0.5, seed = 42) # fit the GAM (note: for execution time reasons, k is set articifially low) m <- gam(y ~ te(x, z, k = c(5, 5)), data = df, method = \"REML\") # data slice through te(x,z) holding z == 0.4 ds <- data_slice(m, x = evenly(x, n = 100), z = 0.4) # evaluate te(x,z) at values of x & z sm <- smooth_estimates(m, select = \"te(x,z)\", data = ds) |> add_confint() # partial derivatives pd_x <- partial_derivatives(m, data = ds, type = \"central\", focal = \"x\") # draw te(x,z) p1 <- draw(m, rug = FALSE) & geom_hline(yintercept = 0.4, linewidth = 1) p1 # draw te(x,z) along slice cap <- expression(z == 0.4) p2 <- sm |> ggplot(aes(x = x, y = .estimate)) + geom_ribbon(aes(ymin = .lower_ci, ymax = .upper_ci), alpha = 0.2) + geom_line() + labs( x = \"x\", y = \"Partial effect\", title = \"te(x,z)\", caption = cap ) p2 # draw partial derivs p3 <- pd_x |> draw() + labs(caption = cap) p3 # draw all three panels p1 + p2 + p3 + plot_layout(ncol = 3)"},{"path":"https://gavinsimpson.github.io/gratia/reference/partial_residuals.html","id":null,"dir":"Reference","previous_headings":"","what":"Partial residuals — partial_residuals","title":"Partial residuals — partial_residuals","text":"Partial residuals","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/partial_residuals.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Partial residuals — partial_residuals","text":"","code":"partial_residuals(object, ...) # S3 method for class 'gam' partial_residuals(object, select = NULL, partial_match = FALSE, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/partial_residuals.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Partial residuals — partial_residuals","text":"object R object, typically model. Currently objects class \"gam\" (inherit class) supported. ... arguments passed methods. select character, logical, numeric; smooths plot. NULL, default, model smooths drawn. Numeric select indexes smooths order specified formula stored object. Character select matches labels smooths shown example output summary(object). Logical select operates per numeric select order smooths stored. partial_match logical; smooths selected partial matches select? TRUE, select can single string match .","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/partial_residuals.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Partial residuals — partial_residuals","text":"","code":"## load mgcv load_mgcv() ## example data - Gu & Wabha four term model df <- data_sim(\"eg1\", n = 400, seed = 42) ## fit the model m <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = df, method = \"REML\") ## extract partial residuals partial_residuals(m) #> # A tibble: 400 x 4 #> `s(x0)` `s(x1)` `s(x2)` `s(x3)` #> #> 1 -0.3527 -1.321 -2.180 0.6077 #> 2 -0.1233 0.5013 -1.775 0.9613 #> 3 1.429 1.515 5.609 0.9910 #> 4 -1.110 -1.700 -0.8882 -0.6593 #> 5 -2.120 -0.01378 -2.733 -3.012 #> 6 1.254 -1.224 3.915 0.07275 #> 7 -0.5220 3.023 -0.8197 -1.019 #> 8 1.398 0.2184 7.055 1.897 #> 9 2.797 0.4969 7.329 2.498 #> 10 1.151 -0.2267 0.7202 0.7437 #> # i 390 more rows ## and for a select term partial_residuals(m, select = \"s(x2)\") #> # A tibble: 400 x 1 #> `s(x2)` #> #> 1 -2.180 #> 2 -1.775 #> 3 5.609 #> 4 -0.8882 #> 5 -2.733 #> 6 3.915 #> 7 -0.8197 #> 8 7.055 #> 9 7.329 #> 10 0.7202 #> # i 390 more rows ## or with partial matching partial_residuals(m, select = \"x\", partial_match = TRUE) # returns all #> # A tibble: 400 x 4 #> `s(x0)` `s(x1)` `s(x2)` `s(x3)` #> #> 1 -0.3527 -1.321 -2.180 0.6077 #> 2 -0.1233 0.5013 -1.775 0.9613 #> 3 1.429 1.515 5.609 0.9910 #> 4 -1.110 -1.700 -0.8882 -0.6593 #> 5 -2.120 -0.01378 -2.733 -3.012 #> 6 1.254 -1.224 3.915 0.07275 #> 7 -0.5220 3.023 -0.8197 -1.019 #> 8 1.398 0.2184 7.055 1.897 #> 9 2.797 0.4969 7.329 2.498 #> 10 1.151 -0.2267 0.7202 0.7437 #> # i 390 more rows"},{"path":"https://gavinsimpson.github.io/gratia/reference/penalty.html","id":null,"dir":"Reference","previous_headings":"","what":"Extract and tidy penalty matrices — penalty","title":"Extract and tidy penalty matrices — penalty","text":"Extract tidy penalty matrices","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/penalty.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Extract and tidy penalty matrices — penalty","text":"","code":"penalty(object, ...) # Default S3 method penalty( object, rescale = FALSE, data, knots = NULL, constraints = FALSE, diagonalize = FALSE, ... ) # S3 method for class 'gam' penalty( object, select = NULL, smooth = deprecated(), rescale = FALSE, partial_match = FALSE, ... ) # S3 method for class 'mgcv.smooth' penalty(object, rescale = FALSE, ...) # S3 method for class 'tensor.smooth' penalty(object, margins = FALSE, ...) # S3 method for class 't2.smooth' penalty(object, margins = FALSE, ...) # S3 method for class 're.smooth.spec' penalty(object, data, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/penalty.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Extract and tidy penalty matrices — penalty","text":"object fitted GAM smooth. ... additional arguments passed methods. rescale logical; default, mgcv scale penalty matrix better performance mgcv::gamm(). rescale TRUE, scaling undone put penalty matrix back original scale. data data frame; data frame values terms mentioned smooth specification. knots list data frame named components containing knots locations. Names must match covariates basis required. See mgcv::smoothCon(). constraints logical; identifiability constraints applied smooth basis. See argument absorb.cons mgcv::smoothCon(). diagonalize logical; TRUE, reparameterises smooth associated penalty identity matrix. effect turning last diagonal elements penalty zero, highlights penalty null space. select character, logical, numeric; smooths extract penalties . NULL, default, penalties model smooths drawn. Numeric select indexes smooths order specified formula stored object. Character select matches labels smooths shown example output summary(object). Logical select operates per numeric select order smooths stored. smooth Use select instead. partial_match logical; smooths selected partial matches select? TRUE, select can single string match . margins logical; extract penalty matrices tensor product marginal smooths tensor product?","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/penalty.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Extract and tidy penalty matrices — penalty","text":"'tibble' (data frame) class penalty_df inheriting tbl_df, following components: .smooth - character; label mgcv uses refer smooth, .type - character; type smooth, .penalty - character; label specific penalty. smooths multiple penalty matrices, penalty component identifies particular penalty matrix uses labelling mgcv uses internally, .row - character; label form fn n integer nth basis function, referencing columns penalty matrix, .col - character; label form fn n integer nth basis function, referencing columns penalty matrix, .value - double; value penalty matrix combination row col,","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/penalty.html","id":"note","dir":"Reference","previous_headings":"","what":"Note","title":"Extract and tidy penalty matrices — penalty","text":"print() method uses base::zapsmall() turn small numbers 0s display purposes ; underlying values penalty matrix matrices changed. smooths subject eigendecomposition (e.g. default thin plate regression splines, bs = \"tp\"), signs eigenvectors defined can expect differences across systems penalties smooths system-, OS-, CPU architecture- specific.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/penalty.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Extract and tidy penalty matrices — penalty","text":"Gavin L. Simpson","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/penalty.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Extract and tidy penalty matrices — penalty","text":"","code":"load_mgcv() dat <- data_sim(\"eg4\", n = 400, seed = 42) m <- gam( y ~ s(x0, bs = \"cr\") + s(x1, bs = \"cr\") + s(x2, by = fac, bs = \"cr\"), data = dat, method = \"REML\" ) # penalties for all smooths penalty(m) #> # A tibble: 405 x 6 #> .smooth .type .penalty .row .col .value #> #> 1 s(x0) CRS s(x0) F1 F1 0.783 #> 2 s(x0) CRS s(x0) F1 F2 -0.635 #> 3 s(x0) CRS s(x0) F1 F3 0.265 #> 4 s(x0) CRS s(x0) F1 F4 -0.0203 #> 5 s(x0) CRS s(x0) F1 F5 0.0441 #> 6 s(x0) CRS s(x0) F1 F6 0.0378 #> 7 s(x0) CRS s(x0) F1 F7 0.0482 #> 8 s(x0) CRS s(x0) F1 F8 0.0216 #> 9 s(x0) CRS s(x0) F1 F9 0.0247 #> 10 s(x0) CRS s(x0) F2 F1 -0.635 #> # i 395 more rows # for a specific smooth penalty(m, select = \"s(x2):fac1\") #> # A tibble: 81 x 6 #> .smooth .type .penalty .row .col .value #> #> 1 s(x2):fac1 CRS s(x2):fac1 F1 F1 1.66 #> 2 s(x2):fac1 CRS s(x2):fac1 F1 F2 -0.755 #> 3 s(x2):fac1 CRS s(x2):fac1 F1 F3 0.430 #> 4 s(x2):fac1 CRS s(x2):fac1 F1 F4 0.0846 #> 5 s(x2):fac1 CRS s(x2):fac1 F1 F5 0.192 #> 6 s(x2):fac1 CRS s(x2):fac1 F1 F6 0.152 #> 7 s(x2):fac1 CRS s(x2):fac1 F1 F7 0.188 #> 8 s(x2):fac1 CRS s(x2):fac1 F1 F8 0.164 #> 9 s(x2):fac1 CRS s(x2):fac1 F1 F9 0.0597 #> 10 s(x2):fac1 CRS s(x2):fac1 F2 F1 -0.755 #> # i 71 more rows"},{"path":"https://gavinsimpson.github.io/gratia/reference/post_draws.html","id":null,"dir":"Reference","previous_headings":"","what":"Low-level Functions to generate draws from the posterior distribution of model coefficients — post_draws","title":"Low-level Functions to generate draws from the posterior distribution of model coefficients — post_draws","text":"Low-level Functions generate draws posterior distribution model coefficients Generate posterior draws fitted model","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/post_draws.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Low-level Functions to generate draws from the posterior distribution of model coefficients — post_draws","text":"","code":"post_draws(model, ...) # Default S3 method post_draws( model, n, method = c(\"gaussian\", \"mh\", \"inla\", \"user\"), mu = NULL, sigma = NULL, n_cores = 1L, burnin = 1000, thin = 1, t_df = 40, rw_scale = 0.25, index = NULL, frequentist = FALSE, unconditional = FALSE, parametrized = TRUE, mvn_method = c(\"mvnfast\", \"mgcv\"), draws = NULL, seed = NULL, ... ) generate_draws(model, ...) # S3 method for class 'gam' generate_draws( model, n, method = c(\"gaussian\", \"mh\", \"inla\"), mu = NULL, sigma = NULL, n_cores = 1L, burnin = 1000, thin = 1, t_df = 40, rw_scale = 0.25, index = NULL, frequentist = FALSE, unconditional = FALSE, mvn_method = c(\"mvnfast\", \"mgcv\"), seed = NULL, ... )"},{"path":"https://gavinsimpson.github.io/gratia/reference/post_draws.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Low-level Functions to generate draws from the posterior distribution of model coefficients — post_draws","text":"model fitted R model. Currently models fitted mgcv::gam() mgcv::bam(), return object inherits objects supported. , \"inherits\" used loose fashion; models fitted scam::scam() support even though models strictly inherit class \"gam\" far inherits() concerned. ... arguments passed methods. n numeric; number posterior draws take. method character; algorithm use sample posterior. Currently implemented methods : \"gaussian\" \"mh\". \"gaussian\" calls gaussian_draws() uses Gaussian approximation posterior distribution. \"mh\" uses simple Metropolis Hasting sampler alternates static proposals based Gaussian approximation posterior, random walk proposals. Note, setting t_df low value result heavier-tailed statistic proposals. See mgcv::gam.mh() details. mu numeric; user-supplied mean vector (vector model coefficients). Currently ignored. sigma matrix; user-supplied covariance matrix mu. Currently ignored. n_cores integer; number CPU cores use generating multivariate normal distributed random values. used mvn_method = \"mvnfast\" method = \"gaussian\". burnin numeric; length initial burn period discard. See mgcv::gam.mh(). thin numeric; retain thin samples. See mgcv::gam.mh(). t_df numeric; degrees freedom static multivariate t proposal. See mgcv::gam.mh(). rw_scale numeric; factor scale posterior covariance matrix generating random walk proposals. See mgcv::gam.mh(). index numeric; vector indices coefficients use. Can used subset mean vector covariance matrix extracted model. frequentist logical; TRUE, frequentist covariance matrix parameter estimates used. FALSE, Bayesian posterior covariance matrix parameters used. See mgcv::vcov.gam(). unconditional logical; TRUE Bayesian smoothing parameter uncertainty corrected covariance matrix used, available model. See mgcv::vcov.gam(). parametrized logical; use parametrized coefficients covariance matrix, respect linear inequality constraints model. scam::scam() model fits. mvn_method character; one \"mvnfast\" \"mgcv\". default uses mvnfast::rmvn(), can considerably faster generate large numbers MVN random values mgcv::rmvn(), might work marginal fits, covariance matrix close singular. draws matrix; user supplied posterior draws used method = \"user\". seed numeric; random seed use. NULL, random seed generated without affecting current state R's RNG.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/post_link_funs.html","id":null,"dir":"Reference","previous_headings":"","what":"A list of transformation functions named for LSS parameters in a GAMLSS — post_link_funs","title":"A list of transformation functions named for LSS parameters in a GAMLSS — post_link_funs","text":"list transformation functions named LSS parameters GAMLSS","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/post_link_funs.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"A list of transformation functions named for LSS parameters in a GAMLSS — post_link_funs","text":"","code":"post_link_funs( location = identity_fun, scale = identity_fun, shape = identity_fun, skewness = identity_fun, kurtosis = identity_fun, power = identity_fun, pi = identity_fun )"},{"path":"https://gavinsimpson.github.io/gratia/reference/posterior_samples.html","id":null,"dir":"Reference","previous_headings":"","what":"Draw samples from the posterior distribution of an estimated model — posterior_samples","title":"Draw samples from the posterior distribution of an estimated model — posterior_samples","text":"Draw samples posterior distribution estimated model","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/posterior_samples.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Draw samples from the posterior distribution of an estimated model — posterior_samples","text":"","code":"posterior_samples(model, ...) # S3 method for class 'gam' posterior_samples( model, n = 1, data = newdata, seed = NULL, method = c(\"gaussian\", \"mh\", \"inla\", \"user\"), n_cores = 1, burnin = 1000, thin = 1, t_df = 40, rw_scale = 0.25, freq = FALSE, unconditional = FALSE, weights = NULL, draws = NULL, mvn_method = c(\"mvnfast\", \"mgcv\"), ..., newdata = NULL, ncores = NULL )"},{"path":"https://gavinsimpson.github.io/gratia/reference/posterior_samples.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Draw samples from the posterior distribution of an estimated model — posterior_samples","text":"model fitted model supported types ... arguments passed methods. fitted_samples(), passed mgcv::predict.gam(). posterior_samples() passed fitted_samples(). predicted_samples() passed relevant simulate() method. n numeric; number posterior samples return. data data frame; new observations posterior draws model evaluated. supplied, data used fit model used data, available model. seed numeric; random seed simulations. method character; method used draw samples posterior distribution. \"gaussian\" uses Gaussian (Laplace) approximation posterior. \"mh\" uses Metropolis Hastings sampler alternates t proposals proposals based shrunken version posterior covariance matrix. \"inla\" uses variant Integrated Nested Laplace Approximation due Wood (2019), (currently implemented). \"user\" allows user-supplied posterior draws (currently implemented). n_cores number cores generating random variables multivariate normal distribution. Passed mvnfast::rmvn(). Parallelization take place OpenMP supported (appears work Windows current R). burnin numeric; number samples discard burnin draws. used method = \"mh\". thin numeric; number samples skip taking n draws. Results thin * n draws posterior taken. used method = \"mh\". t_df numeric; degrees freedom t distribution proposals. used method = \"mh\". rw_scale numeric; Factor scale posterior covariance matrix generating random walk proposals. Negative non finite skip random walk step. used method = \"mh\". freq logical; TRUE use frequentist covariance matrix parameter estimators, FALSE use Bayesian posterior covariance matrix parameters. unconditional logical; TRUE (freq == FALSE) Bayesian smoothing parameter uncertainty corrected covariance matrix used, available. weights numeric; vector prior weights. data null defaults object[[\"prior.weights\"]], otherwise vector ones. draws matrix; user supplied posterior draws used method = \"user\". mvn_method character; one \"mvnfast\" \"mgcv\". default uses mvnfast::rmvn(), can considerably faster generate large numbers MVN random values mgcv::rmvn(), might work marginal fits, covariance matrix close singular. newdata Deprecated: use data instead. ncores Deprecated; use n_cores instead. number cores generating random variables multivariate normal distribution. Passed mvnfast::rmvn(). Parallelization take place OpenMP supported (appears work Windows current R).","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/posterior_samples.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Draw samples from the posterior distribution of an estimated model — posterior_samples","text":"tibble (data frame) 3 columns containing posterior predicted values long format. columns row (integer) row data posterior draw relates , draw (integer) index, range 1:n, indicating draw row relates , response (numeric) predicted response indicated row data.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/posterior_samples.html","id":"note","dir":"Reference","previous_headings":"","what":"Note","title":"Draw samples from the posterior distribution of an estimated model — posterior_samples","text":"Models offset terms supplied via offset argument mgcv::gam() etc. ignored mgcv::predict.gam(). , kind offset term also ignored posterior_samples(). Offset terms included model formula supplied mgcv::gam() etc ignored posterior samples produced reflect offset term values. side effect requiring new data values provided posterior_samples() via data argument must include offset variable.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/posterior_samples.html","id":"references","dir":"Reference","previous_headings":"","what":"References","title":"Draw samples from the posterior distribution of an estimated model — posterior_samples","text":"Wood, S.N., (2020). Simplified integrated nested Laplace approximation. Biometrika 107, 223–230. doi:10.1093/biomet/asz044","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/posterior_samples.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Draw samples from the posterior distribution of an estimated model — posterior_samples","text":"Gavin L. Simpson","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/predicted_samples.html","id":null,"dir":"Reference","previous_headings":"","what":"Draw new response values from the conditional distribution of the response — predicted_samples","title":"Draw new response values from the conditional distribution of the response — predicted_samples","text":"Predicted values response (new response data) drawn fitted model, created via simulate() (e.g. simulate.gam()) returned tidy, long, format. predicted values include uncertainty estimated model; simply draws conditional distribution response.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/predicted_samples.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Draw new response values from the conditional distribution of the response — predicted_samples","text":"","code":"predicted_samples(model, ...) # S3 method for class 'gam' predicted_samples( model, n = 1, data = newdata, seed = NULL, weights = NULL, ..., newdata = NULL )"},{"path":"https://gavinsimpson.github.io/gratia/reference/predicted_samples.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Draw new response values from the conditional distribution of the response — predicted_samples","text":"model fitted model supported types ... arguments passed methods. fitted_samples(), passed mgcv::predict.gam(). posterior_samples() passed fitted_samples(). predicted_samples() passed relevant simulate() method. n numeric; number posterior samples return. data data frame; new observations posterior draws model evaluated. supplied, data used fit model used data, available model. seed numeric; random seed simulations. weights numeric; vector prior weights. data null defaults object[[\"prior.weights\"]], otherwise vector ones. newdata Deprecated: use data instead.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/predicted_samples.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Draw new response values from the conditional distribution of the response — predicted_samples","text":"tibble (data frame) 3 columns containing posterior predicted values long format. columns row (integer) row data posterior draw relates , draw (integer) index, range 1:n, indicating draw row relates , response (numeric) predicted response indicated row data.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/predicted_samples.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Draw new response values from the conditional distribution of the response — predicted_samples","text":"Gavin L. Simpson","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/predicted_samples.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Draw new response values from the conditional distribution of the response — predicted_samples","text":"","code":"load_mgcv() dat <- data_sim(\"eg1\", n = 1000, dist = \"normal\", scale = 2, seed = 2) m <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = dat, method = \"REML\") predicted_samples(m, n = 5, seed = 42) #> # A tibble: 5,000 x 3 #> .row .draw .response #> #> 1 1 1 8.93 #> 2 2 1 4.23 #> 3 3 1 7.71 #> 4 4 1 8.51 #> 5 5 1 10.1 #> 6 6 1 8.20 #> 7 7 1 8.95 #> 8 8 1 7.20 #> 9 9 1 18.1 #> 10 10 1 12.7 #> # i 4,990 more rows ## Can pass arguments to predict.gam() newd <- data.frame( x0 = runif(10), x1 = runif(10), x2 = runif(10), x3 = runif(10) ) ## Exclude s(x2) predicted_samples(m, n = 5, newd, exclude = \"s(x2)\", seed = 25) #> # A tibble: 50 x 3 #> .row .draw .response #> #> 1 1 1 9.42 #> 2 2 1 6.97 #> 3 3 1 8.10 #> 4 4 1 9.95 #> 5 5 1 6.75 #> 6 6 1 10.3 #> 7 7 1 10.8 #> 8 8 1 10.5 #> 9 9 1 8.43 #> 10 10 1 12.2 #> # i 40 more rows ## Exclude s(x1) predicted_samples(m, n = 5, newd, exclude = \"s(x1)\", seed = 25) #> # A tibble: 50 x 3 #> .row .draw .response #> #> 1 1 1 6.05 #> 2 2 1 5.28 #> 3 3 1 5.96 #> 4 4 1 13.7 #> 5 5 1 4.36 #> 6 6 1 5.11 #> 7 7 1 12.5 #> 8 8 1 5.66 #> 9 9 1 12.6 #> 10 10 1 8.38 #> # i 40 more rows ## Select which terms --- result should be the same as previous ## but note that we have to include any parametric terms, including the ## constant term predicted_samples(m, n = 5, newd, seed = 25, terms = c(\"Intercept\", \"s(x0)\", \"s(x2)\", \"s(x3)\") ) #> # A tibble: 50 x 3 #> .row .draw .response #> #> 1 1 1 -1.94 #> 2 2 1 -2.71 #> 3 3 1 -2.03 #> 4 4 1 5.73 #> 5 5 1 -3.63 #> 6 6 1 -2.87 #> 7 7 1 4.48 #> 8 8 1 -2.33 #> 9 9 1 4.65 #> 10 10 1 0.395 #> # i 40 more rows"},{"path":"https://gavinsimpson.github.io/gratia/reference/qq_plot.html","id":null,"dir":"Reference","previous_headings":"","what":"Quantile-quantile plot of model residuals — qq_plot","title":"Quantile-quantile plot of model residuals — qq_plot","text":"Quantile-quantile plots (QQ-plots) GAMs using reference quantiles Augustin et al (2012).","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/qq_plot.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Quantile-quantile plot of model residuals — qq_plot","text":"","code":"qq_plot(model, ...) # Default S3 method qq_plot(model, ...) # S3 method for class 'gam' qq_plot( model, method = c(\"uniform\", \"simulate\", \"normal\", \"direct\"), type = c(\"deviance\", \"response\", \"pearson\"), n_uniform = 10, n_simulate = 50, seed = NULL, level = 0.9, ylab = NULL, xlab = NULL, title = NULL, subtitle = NULL, caption = NULL, ci_col = \"black\", ci_alpha = 0.2, point_col = \"black\", point_alpha = 1, line_col = \"red\", ... ) # S3 method for class 'glm' qq_plot(model, ...) # S3 method for class 'lm' qq_plot(model, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/qq_plot.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Quantile-quantile plot of model residuals — qq_plot","text":"model fitted model. Currently models inheriting class \"gam\", well classes \"glm\" \"lm\" calls stats::glm stats::lm supported. ... arguments passed ot methods. method character; method used generate theoretical quantiles. default \"uniform\", generates reference quantiles using random draws uniform distribution inverse cummulative distribution function (CDF) fitted values. reference quantiles averaged n_uniform draws. \"simulate\" generates reference quantiles simulating new response data model observed values covariates, residualised generate reference quantiles, using n_simulate simulated data sets. \"normal\" generates reference quantiles using standard normal distribution. \"uniform\" computationally efficient, \"simulate\" allows reference bands drawn QQ-plot. \"normal\" avoided used fall back random number generator (\"simulate\") inverse CDF available family used model fitting (`\"uniform\"“). Note method = \"direct\" deprecated favour method = \"uniform\". type character; type residuals use. \"deviance\", \"response\", \"pearson\" residuals allowed. n_uniform numeric; number times randomize uniform quantiles direct computation method (method = \"uniform\"). n_simulate numeric; number data sets simulate estimated model using simulation method (method = \"simulate\"). seed numeric; random number seed use method = \"simulate\" method = \"uniform\". level numeric; coverage level reference intervals. Must strictly 0 < level < 1. used method = \"simulate\". ylab character expression; label y axis. supplied, suitable label generated. xlab character expression; label y axis. supplied, suitable label generated. title character expression; title plot. See ggplot2::labs(). May vector, one per penalty. subtitle character expression; subtitle plot. See ggplot2::labs(). May vector, one per penalty. caption character expression; plot caption. See ggplot2::labs(). May vector, one per penalty. ci_col fill colour reference interval method = \"simulate\". ci_alpha alpha transparency reference interval method = \"simulate\". point_col colour points QQ plot. point_alpha alpha transparency points QQ plot. line_col colour used draw reference line.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/qq_plot.html","id":"note","dir":"Reference","previous_headings":"","what":"Note","title":"Quantile-quantile plot of model residuals — qq_plot","text":"wording used mgcv::qq.gam() uses direct reference simulated residuals method (method = \"simulated\"). avoid confusion, method = \"direct\" deprecated favour method = \"uniform\".","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/qq_plot.html","id":"references","dir":"Reference","previous_headings":"","what":"References","title":"Quantile-quantile plot of model residuals — qq_plot","text":"underlying methodology used method \"simulate\" \"uniform\" described Augustin et al (2012): Augustin, N.H., Sauleau, E.-., Wood, S.N., (2012) quantile quantile plots generalized linear models. Computational Statatistics Data Analysis 56, 2404-2409 doi:10.1016/j.csda.2012.01.026 .","code":""},{"path":[]},{"path":"https://gavinsimpson.github.io/gratia/reference/qq_plot.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Quantile-quantile plot of model residuals — qq_plot","text":"","code":"load_mgcv() ## simulate binomial data... dat <- data_sim(\"eg1\", n = 200, dist = \"binary\", scale = .33, seed = 0) p <- binomial()$linkinv(dat$f) # binomial p n <- sample(c(1, 3), 200, replace = TRUE) # binomial n dat <- transform(dat, y = rbinom(n, n, p), n = n) m <- gam(y / n ~ s(x0) + s(x1) + s(x2) + s(x3), family = binomial, data = dat, weights = n, method = \"REML\" ) ## Q-Q plot; default using direct randomization of uniform quantiles qq_plot(m) ## Alternatively use simulate new data from the model, which ## allows construction of reference intervals for the Q-Q plot qq_plot(m, method = \"simulate\", seed = 42, point_col = \"steelblue\", point_alpha = 0.4 ) ## ... or use the usual normality assumption qq_plot(m, method = \"normal\")"},{"path":"https://gavinsimpson.github.io/gratia/reference/ref_level.html","id":null,"dir":"Reference","previous_headings":"","what":"Return the reference or specific level of a factor — ref_level","title":"Return the reference or specific level of a factor — ref_level","text":"Extracts reference specific level supplied factor, returning factor levels one supplied.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/ref_level.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Return the reference or specific level of a factor — ref_level","text":"","code":"ref_level(fct) level(fct, level)"},{"path":"https://gavinsimpson.github.io/gratia/reference/ref_level.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Return the reference or specific level of a factor — ref_level","text":"fct factor; factor reference specific level extracted. level character; specific level extract case level().","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/ref_level.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Return the reference or specific level of a factor — ref_level","text":"length 1 factor levels supplied factor fct.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/ref_level.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Return the reference or specific level of a factor — ref_level","text":"","code":"f <- factor(sample(letters[1:5], 100, replace = TRUE)) # the reference level ref_level(f) #> [1] a #> Levels: a b c d e # a specific level level(f, level = \"b\") #> [1] b #> Levels: a b c d e # note that the levels will always match the input factor identical(levels(f), levels(ref_level(f))) #> [1] TRUE identical(levels(f), levels(level(f, \"c\"))) #> [1] TRUE"},{"path":"https://gavinsimpson.github.io/gratia/reference/ref_sims.html","id":null,"dir":"Reference","previous_headings":"","what":"Reference simulation data — ref_sims","title":"Reference simulation data — ref_sims","text":"set reference objects testing data_sim().","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/ref_sims.html","id":"format","dir":"Reference","previous_headings":"","what":"Format","title":"Reference simulation data — ref_sims","text":"named list simulated data sets created data_sim().","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/reorder_fs_smooth_terms.html","id":null,"dir":"Reference","previous_headings":"","what":"Reorder random factor smooth terms to place factor last — reorder_fs_smooth_terms","title":"Reorder random factor smooth terms to place factor last — reorder_fs_smooth_terms","text":"Reorder random factor smooth terms place factor last","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/reorder_fs_smooth_terms.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Reorder random factor smooth terms to place factor last — reorder_fs_smooth_terms","text":"","code":"reorder_fs_smooth_terms(smooth)"},{"path":"https://gavinsimpson.github.io/gratia/reference/reorder_fs_smooth_terms.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Reorder random factor smooth terms to place factor last — reorder_fs_smooth_terms","text":"smooth mgcv smooth object","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/reorder_tensor_smooth_terms.html","id":null,"dir":"Reference","previous_headings":"","what":"Reorder tensor product terms for nicer plotting — reorder_tensor_smooth_terms","title":"Reorder tensor product terms for nicer plotting — reorder_tensor_smooth_terms","text":"tensor product smooth 3 terms contains 2d marginal smooth, get nicer output smooth_estimates() hence nicer plot draw.smooth_estimates() method reorder terms smooth vary terms 2d marginal first, terms vary slowly generate data evaluate smooth . results automatically generated data focuses (first one) 2d marginal smooth, end result smooth_estimates() shows 2d smooth changes terms involved smooth.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/reorder_tensor_smooth_terms.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Reorder tensor product terms for nicer plotting — reorder_tensor_smooth_terms","text":"","code":"reorder_tensor_smooth_terms(smooth)"},{"path":"https://gavinsimpson.github.io/gratia/reference/reorder_tensor_smooth_terms.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Reorder tensor product terms for nicer plotting — reorder_tensor_smooth_terms","text":"smooth mgcv smooth object","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/rep_first_factor_value.html","id":null,"dir":"Reference","previous_headings":"","what":"Repeat the first level of a factor n times — rep_first_factor_value","title":"Repeat the first level of a factor n times — rep_first_factor_value","text":"Function repeat first level factor n times return vector factor original levels intact","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/rep_first_factor_value.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Repeat the first level of a factor n times — rep_first_factor_value","text":"","code":"rep_first_factor_value(f, n)"},{"path":"https://gavinsimpson.github.io/gratia/reference/rep_first_factor_value.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Repeat the first level of a factor n times — rep_first_factor_value","text":"f factor n numeric; number times repeat first level f","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/rep_first_factor_value.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Repeat the first level of a factor n times — rep_first_factor_value","text":"factor length n levels f, whose elements first level f.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/residuals_hist_plot.html","id":null,"dir":"Reference","previous_headings":"","what":"Histogram of model residuals — residuals_hist_plot","title":"Histogram of model residuals — residuals_hist_plot","text":"Histogram model residuals","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/residuals_hist_plot.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Histogram of model residuals — residuals_hist_plot","text":"","code":"residuals_hist_plot( model, type = c(\"deviance\", \"pearson\", \"response\"), n_bins = c(\"sturges\", \"scott\", \"fd\"), ylab = NULL, xlab = NULL, title = NULL, subtitle = NULL, caption = NULL )"},{"path":"https://gavinsimpson.github.io/gratia/reference/residuals_hist_plot.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Histogram of model residuals — residuals_hist_plot","text":"model fitted model. Currently class \"gam\". type character; type residuals use. \"deviance\", \"response\", \"pearson\" residuals allowed. n_bins character numeric; either number bins string indicating calculate number bins. ylab character expression; label y axis. supplied, suitable label generated. xlab character expression; label y axis. supplied, suitable label generated. title character expression; title plot. See ggplot2::labs(). subtitle character expression; subtitle plot. See ggplot2::labs(). caption character expression; plot caption. See ggplot2::labs().","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/residuals_linpred_plot.html","id":null,"dir":"Reference","previous_headings":"","what":"Plot of residuals versus linear predictor values — residuals_linpred_plot","title":"Plot of residuals versus linear predictor values — residuals_linpred_plot","text":"Plot residuals versus linear predictor values","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/residuals_linpred_plot.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Plot of residuals versus linear predictor values — residuals_linpred_plot","text":"","code":"residuals_linpred_plot( model, type = c(\"deviance\", \"pearson\", \"response\"), ylab = NULL, xlab = NULL, title = NULL, subtitle = NULL, caption = NULL, point_col = \"black\", point_alpha = 1, line_col = \"red\" )"},{"path":"https://gavinsimpson.github.io/gratia/reference/residuals_linpred_plot.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Plot of residuals versus linear predictor values — residuals_linpred_plot","text":"model fitted model. Currently class \"gam\". type character; type residuals use. \"deviance\", \"response\", \"pearson\" residuals allowed. ylab character expression; label y axis. supplied, suitable label generated. xlab character expression; label y axis. supplied, suitable label generated. title character expression; title plot. See ggplot2::labs(). subtitle character expression; subtitle plot. See ggplot2::labs(). caption character expression; plot caption. See ggplot2::labs(). point_col colour used draw points plots. See graphics::par() section Color Specification. passed individual plotting functions, therefore affects points plots. point_alpha numeric; alpha transparency points plots. line_col colour specification 1:1 line.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/response_derivatives.html","id":null,"dir":"Reference","previous_headings":"","what":"Derivatives on the response scale from an estimated GAM — response_derivatives","title":"Derivatives on the response scale from an estimated GAM — response_derivatives","text":"Derivatives response scale estimated GAM","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/response_derivatives.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Derivatives on the response scale from an estimated GAM — response_derivatives","text":"","code":"response_derivatives(object, ...) # Default S3 method response_derivatives(object, ...) # S3 method for class 'gamm' response_derivatives(object, ...) # S3 method for class 'gam' response_derivatives( object, focal = NULL, data = NULL, order = 1L, type = c(\"forward\", \"backward\", \"central\"), scale = c(\"response\", \"linear_predictor\"), method = c(\"gaussian\", \"mh\", \"inla\", \"user\"), n = 100, eps = 1e-07, n_sim = 10000, level = 0.95, seed = NULL, mvn_method = c(\"mvnfast\", \"mgcv\"), ... )"},{"path":"https://gavinsimpson.github.io/gratia/reference/response_derivatives.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Derivatives on the response scale from an estimated GAM — response_derivatives","text":"object R object compute derivatives . ... arguments passed methods fitted_samples() focal character; name focal variable. response derivative response respect variable returned. variables involved model held constant values. can missing supplying data, case, focal variable identified one variable constant. data data frame containing values model covariates evaluate first derivatives smooths. supplied, one variable must held constant value. order numeric; order derivative. type character; type finite difference used. One \"forward\", \"backward\", \"central\". scale character; derivative estimated response linear predictor (link) scale? One \"response\" (default), \"linear predictor\". method character; method used draw samples posterior distribution. \"gaussian\" uses Gaussian (Laplace) approximation posterior. \"mh\" uses Metropolis Hastings sample alternates t proposals proposals based shrunken version posterior covariance matrix. \"inla\" uses variant Integrated Nested Laplace Approximation due Wood (2019), (currently implemented). \"user\" allows user-supplied posterior draws (currently implemented). n numeric; number points evaluate derivative (data supplied). eps numeric; finite difference. n_sim integer; number simulations used computing simultaneous intervals. level numeric; 0 < level < 1; coverage level credible interval. default 0.95 95% interval. seed numeric; random seed simulations. mvn_method character; one \"mvnfast\" \"mgcv\". default uses mvnfast::rmvn(), can considerably faster generate large numbers MVN random values mgcv::rmvn(), might work marginal fits, covariance matrix close singular.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/response_derivatives.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Derivatives on the response scale from an estimated GAM — response_derivatives","text":"tibble, currently following variables: .row: integer, indexing row data row output represents .focal: name variable partial derivative evaluated, .derivative: estimated partial derivative, .lower_ci: lower bound confidence simultaneous interval, .upper_ci: upper bound confidence simultaneous interval, additional columns containing covariate values derivative evaluated.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/response_derivatives.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Derivatives on the response scale from an estimated GAM — response_derivatives","text":"Gavin L. Simpson","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/response_derivatives.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Derivatives on the response scale from an estimated GAM — response_derivatives","text":"","code":"library(\"ggplot2\") library(\"patchwork\") load_mgcv() df <- data_sim(\"eg1\", dist = \"negbin\", scale = 0.25, seed = 42) # fit the GAM (note: for execution time reasons using bam()) m <- bam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = df, family = nb(), method = \"fREML\" ) # data slice through data along x2 - all other covariates will be set to # typical values (value closest to median) ds <- data_slice(m, x2 = evenly(x2, n = 100)) # fitted values along x2 fv <- fitted_values(m, data = ds) # response derivatives - ideally n_sim = >10000 y_d <- response_derivatives(m, data = ds, type = \"central\", focal = \"x2\", eps = 0.01, seed = 21, n_sim = 1000 ) # draw fitted values along x2 p1 <- fv |> ggplot(aes(x = x2, y = .fitted)) + geom_ribbon(aes(ymin = .lower_ci, ymax = .upper_ci, y = NULL), alpha = 0.2 ) + geom_line() + labs( title = \"Estimated count as a function of x2\", y = \"Estimated count\" ) # draw response derivatives p2 <- y_d |> ggplot(aes(x = x2, y = .derivative)) + geom_ribbon(aes(ymin = .lower_ci, ymax = .upper_ci), alpha = 0.2) + geom_line() + labs( title = \"Estimated 1st derivative of estimated count\", y = \"First derivative\" ) # draw both panels p1 + p2 + plot_layout(nrow = 2)"},{"path":"https://gavinsimpson.github.io/gratia/reference/rootogram.html","id":null,"dir":"Reference","previous_headings":"","what":"Rootograms to assess goodness of model fit — rootogram","title":"Rootograms to assess goodness of model fit — rootogram","text":"rootogram model diagnostic tool assesses goodness fit statistical model. observed values response compared expected fitted model. discrete, count responses, frequency count (0, 1, 2, etc) observed data expected conditional distribution response implied model compared. continuous variables, observed expected frequencies obtained grouping data bins. rootogram drawn using ggplot2::ggplot() graphics. design closely follows Kleiber & Zeileis (2016).","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/rootogram.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Rootograms to assess goodness of model fit — rootogram","text":"","code":"rootogram(object, ...) # S3 method for class 'gam' rootogram(object, max_count = NULL, breaks = \"Sturges\", ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/rootogram.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Rootograms to assess goodness of model fit — rootogram","text":"object R object ... arguments passed methods max_count integer; largest count consider breaks continuous responses, group response. Can anything acceptable breaks argument graphics::hist.default()","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/rootogram.html","id":"references","dir":"Reference","previous_headings":"","what":"References","title":"Rootograms to assess goodness of model fit — rootogram","text":"Kleiber, C., Zeileis, ., (2016) Visualizing Count Data Regressions Using Rootograms. . Stat. 70, 296–303. doi:10.1080/00031305.2016.1173590","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/rootogram.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Rootograms to assess goodness of model fit — rootogram","text":"","code":"load_mgcv() df <- data_sim(\"eg1\", n = 1000, dist = \"poisson\", scale = 0.1, seed = 6) # A poisson example m <- gam(y ~ s(x0, bs = \"cr\") + s(x1, bs = \"cr\") + s(x2, bs = \"cr\") + s(x3, bs = \"cr\"), family = poisson(), data = df, method = \"REML\") rg <- rootogram(m) rg #> # A tibble: 21 x 3 #> .bin .observed .fitted #> #> 1 0 113 116.640 #> 2 1 236 227.869 #> 3 2 230 239.168 #> 4 3 200 181.679 #> 5 4 94 113.432 #> 6 5 68 62.4881 #> 7 6 27 31.6795 #> 8 7 22 15.1323 #> 9 8 4 6.88637 #> 10 9 3 2.99628 #> # i 11 more rows draw(rg) # plot the rootogram # A Gaussian example df <- data_sim(\"eg1\", dist = \"normal\", seed = 2) m <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = df, method = \"REML\") draw(rootogram(m, breaks = \"FD\"), type = \"suspended\")"},{"path":"https://gavinsimpson.github.io/gratia/reference/seq_min_max_eps.html","id":null,"dir":"Reference","previous_headings":"","what":"Create a sequence of evenly-spaced values adjusted to accommodate a small adjustment — seq_min_max_eps","title":"Create a sequence of evenly-spaced values adjusted to accommodate a small adjustment — seq_min_max_eps","text":"Creates sequence n evenly-spaced values range min(x) – max(x), minimum maximum adjusted always contained within range x x may shifted forwards backwards amount related eps. particularly useful computing derivatives via finite differences without adjustment may predicting values outside range data hence conmstraints penalty.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/seq_min_max_eps.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Create a sequence of evenly-spaced values adjusted to accommodate a small adjustment — seq_min_max_eps","text":"","code":"seq_min_max_eps(x, n, order, type = c(\"forward\", \"backward\", \"central\"), eps)"},{"path":"https://gavinsimpson.github.io/gratia/reference/seq_min_max_eps.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Create a sequence of evenly-spaced values adjusted to accommodate a small adjustment — seq_min_max_eps","text":"x numeric; vector evenly-spaced values returned n numeric; number evenly-spaced values return order integer; order derivative. Either 1 2 first second order derivatives type character; type finite difference used. One \"forward\", \"backward\", \"central\" eps numeric; finite difference","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/seq_min_max_eps.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Create a sequence of evenly-spaced values adjusted to accommodate a small adjustment — seq_min_max_eps","text":"numeric vector length n.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/shift_values.html","id":null,"dir":"Reference","previous_headings":"","what":"Shift numeric values in a data frame by an amount eps — shift_values","title":"Shift numeric values in a data frame by an amount eps — shift_values","text":"Shift numeric values data frame amount eps","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/shift_values.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Shift numeric values in a data frame by an amount eps — shift_values","text":"","code":"shift_values(df, h, i, FUN = `+`, focal = NULL)"},{"path":"https://gavinsimpson.github.io/gratia/reference/shift_values.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Shift numeric values in a data frame by an amount eps — shift_values","text":"df data frame tibble. h numeric; amount shift values df . logical; vector indexing columns df included shift. FUN function; function applut shift. Typically + -. focal character; focal variable computing partial derivatives. allows shifting focal variable eps.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/simulate.html","id":null,"dir":"Reference","previous_headings":"","what":"Simulate from the posterior distribution of a GAM — simulate.gam","title":"Simulate from the posterior distribution of a GAM — simulate.gam","text":"Simulations posterior distribution fitted GAM model involve computing predicted values observation data simulated data required, generating random draws probability distribution used fitting model.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/simulate.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Simulate from the posterior distribution of a GAM — simulate.gam","text":"","code":"# S3 method for class 'gam' simulate( object, nsim = 1, seed = NULL, data = newdata, weights = NULL, ..., newdata = NULL ) # S3 method for class 'gamm' simulate( object, nsim = 1, seed = NULL, data = newdata, weights = NULL, ..., newdata = NULL ) # S3 method for class 'scam' simulate( object, nsim = 1, seed = NULL, data = newdata, weights = NULL, ..., newdata = NULL )"},{"path":"https://gavinsimpson.github.io/gratia/reference/simulate.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Simulate from the posterior distribution of a GAM — simulate.gam","text":"object fitted GAM, typically result call mgcv::gam` mgcv::gamm(). nsim numeric; number posterior simulations return. seed numeric; random seed simulations. data data frame; new observations posterior draws model evaluated. supplied, data used fit model used newdata, available object. weights numeric; vector prior weights. newdata null defaults object[[\"prior.weights\"]], otherwise vector ones. ... arguments passed methods. simulate.gam() simulate.scam() pass ... predict.gam(). can pass additional arguments terms, exclude, select model terms included predictions. may useful, example, excluding effects random effect terms. newdata Deprecated. Use data instead.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/simulate.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Simulate from the posterior distribution of a GAM — simulate.gam","text":"(Currently) matrix nsim columns.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/simulate.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Simulate from the posterior distribution of a GAM — simulate.gam","text":"simulate.gam() function, family component fitted model must contain, updateable contain, required random number generator. See mgcv::fix.family.rd().","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/simulate.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Simulate from the posterior distribution of a GAM — simulate.gam","text":"Gavin L. Simpson","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/simulate.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Simulate from the posterior distribution of a GAM — simulate.gam","text":"","code":"load_mgcv() dat <- data_sim(\"eg1\", n = 400, dist = \"normal\", scale = 2, seed = 2) m1 <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = dat, method = \"REML\") sims <- simulate(m1, nsim = 5, seed = 42) head(sims) #> [,1] [,2] [,3] [,4] [,5] #> [1,] 11.445470 11.374304 10.098681 7.264881 8.796630 #> [2,] 6.510912 5.909584 9.057362 7.698084 11.444781 #> [3,] 3.837995 3.230610 3.550240 3.759380 4.774581 #> [4,] 12.361830 11.209226 10.714215 11.861957 10.746417 #> [5,] 14.851461 12.911440 11.356984 15.783913 15.106270 #> [6,] 5.921276 4.158963 5.520856 7.973614 9.654888"},{"path":"https://gavinsimpson.github.io/gratia/reference/smallAges.html","id":null,"dir":"Reference","previous_headings":"","what":"Lead-210 age-depth measurements for Small Water — smallAges","title":"Lead-210 age-depth measurements for Small Water — smallAges","text":"dataset containing lead-210 based age depth measurements SMALL1 core Small Water.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/smallAges.html","id":"format","dir":"Reference","previous_headings":"","what":"Format","title":"Lead-210 age-depth measurements for Small Water — smallAges","text":"data frame 12 rows 7 variables.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/smallAges.html","id":"source","dir":"Reference","previous_headings":"","what":"Source","title":"Lead-210 age-depth measurements for Small Water — smallAges","text":"Simpson, G.L. (Unpublished data).","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/smallAges.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Lead-210 age-depth measurements for Small Water — smallAges","text":"variables follows: Depth Drymass Date Age Error SedAccRate SedPerCentChange","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_coef_indices.html","id":null,"dir":"Reference","previous_headings":"","what":"Indices of the parametric terms for a particular smooth — smooth_coef_indices","title":"Indices of the parametric terms for a particular smooth — smooth_coef_indices","text":"Returns vector indices parametric terms represent supplied smooth. Useful extracting model coefficients columns covariance matrix.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_coef_indices.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Indices of the parametric terms for a particular smooth — smooth_coef_indices","text":"","code":"smooth_coef_indices(smooth)"},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_coef_indices.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Indices of the parametric terms for a particular smooth — smooth_coef_indices","text":"smooth object inherits class mgcv.smooth","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_coef_indices.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Indices of the parametric terms for a particular smooth — smooth_coef_indices","text":"numeric vector indices.","code":""},{"path":[]},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_coef_indices.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Indices of the parametric terms for a particular smooth — smooth_coef_indices","text":"Gavin L. Simpson","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_coefs.html","id":null,"dir":"Reference","previous_headings":"","what":"Coefficients for a particular smooth — smooth_coefs","title":"Coefficients for a particular smooth — smooth_coefs","text":"Returns vector model coefficients parametric terms represent supplied smooth.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_coefs.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Coefficients for a particular smooth — smooth_coefs","text":"","code":"smooth_coefs(object, ...) # S3 method for class 'gam' smooth_coefs(object, select, term = deprecated(), ...) # S3 method for class 'bam' smooth_coefs(object, select, term = deprecated(), ...) # S3 method for class 'gamm' smooth_coefs(object, select, term = deprecated(), ...) # S3 method for class 'gamm4' smooth_coefs(object, select, term = deprecated(), ...) # S3 method for class 'list' smooth_coefs(object, select, term = deprecated(), ...) # S3 method for class 'mgcv.smooth' smooth_coefs(object, model, ...) # S3 method for class 'scam' smooth_coefs(object, select, term = deprecated(), ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_coefs.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Coefficients for a particular smooth — smooth_coefs","text":"object fitted GAM(M) object, , \"mgcv.smooth\" method, object inherits class mgcv.smooth. ... arguments passed methods. select character; label smooth whose coefficients returned. term Use select instead. model fitted GAM(M) object.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_coefs.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Coefficients for a particular smooth — smooth_coefs","text":"numeric vector model coefficients.","code":""},{"path":[]},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_coefs.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Coefficients for a particular smooth — smooth_coefs","text":"Gavin L. Simpson","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_coefs.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Coefficients for a particular smooth — smooth_coefs","text":"","code":"load_mgcv() df <- data_sim(\"eg1\", seed = 2) m <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = df, method = \"REML\") ## IGNORE_RDIFF_BEGIN smooth_coefs(m, select = \"s(x2)\") #> s(x2).1 s(x2).2 s(x2).3 s(x2).4 s(x2).5 s(x2).6 s(x2).7 s(x2).8 #> -6.533373 9.694277 2.194078 -1.967280 -2.374874 1.207638 -1.572586 9.269744 #> s(x2).9 #> 5.622738 ## IGNORE_RDIFF_END"},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_data.html","id":null,"dir":"Reference","previous_headings":"","what":"Generate regular data over the covariates of a smooth — smooth_data","title":"Generate regular data over the covariates of a smooth — smooth_data","text":"Generate regular data covariates smooth","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_data.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Generate regular data over the covariates of a smooth — smooth_data","text":"","code":"smooth_data( model, id, n = 100, n_2d = NULL, n_3d = NULL, n_4d = NULL, offset = NULL, include_all = FALSE, var_order = NULL )"},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_data.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Generate regular data over the covariates of a smooth — smooth_data","text":"model fitted model id number ID smooth within model process. n numeric; number new observations generate. n_2d numeric; number new observations generate second dimension 2D smooth. Currently ignored. n_3d numeric; number new observations generate third dimension 3D smooth. n_4d numeric; number new observations generate dimensions higher 2 (!) kD smooth (k >= 4). example, smooth 4D smooth, dimensions 3 4 get n_4d new observations. offset numeric; value model offset use. include_all logical; include covariates involved smooth? FALSE, covariates involved smooth included returned data frame. TRUE, representative value included covariates model actually used smooth. can useful want pass returned data frame mgcv::PredictMat(). var_order character; order terms smooth processed. useful tensor products least one 2d marginal smooth.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_data.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Generate regular data over the covariates of a smooth — smooth_data","text":"","code":"load_mgcv() df <- data_sim(\"eg1\", seed = 42) m <- bam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = df) # generate data over range of x1 for smooth s(x1) smooth_data(m, id = 2) #> # A tibble: 100 x 1 #> x1 #> #> 1 0.0004050 #> 2 0.01046 #> 3 0.02052 #> 4 0.03057 #> 5 0.04063 #> 6 0.05069 #> 7 0.06074 #> 8 0.07080 #> 9 0.08086 #> 10 0.09091 #> # i 90 more rows # generate data over range of x1 for smooth s(x1), with typical value for # other covariates in the model smooth_data(m, id = 2, include_all = TRUE) #> # A tibble: 100 x 4 #> x1 x0 x2 x3 #> #> 1 0.0004050 0.4883 0.4708 0.4879 #> 2 0.01046 0.4883 0.4708 0.4879 #> 3 0.02052 0.4883 0.4708 0.4879 #> 4 0.03057 0.4883 0.4708 0.4879 #> 5 0.04063 0.4883 0.4708 0.4879 #> 6 0.05069 0.4883 0.4708 0.4879 #> 7 0.06074 0.4883 0.4708 0.4879 #> 8 0.07080 0.4883 0.4708 0.4879 #> 9 0.08086 0.4883 0.4708 0.4879 #> 10 0.09091 0.4883 0.4708 0.4879 #> # i 90 more rows"},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_dim.html","id":null,"dir":"Reference","previous_headings":"","what":"Dimension of a smooth — smooth_dim","title":"Dimension of a smooth — smooth_dim","text":"Extracts dimension estimated smooth.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_dim.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Dimension of a smooth — smooth_dim","text":"","code":"smooth_dim(object) # S3 method for class 'gam' smooth_dim(object) # S3 method for class 'gamm' smooth_dim(object) # S3 method for class 'mgcv.smooth' smooth_dim(object)"},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_dim.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Dimension of a smooth — smooth_dim","text":"object R object. See Details list supported objects.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_dim.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Dimension of a smooth — smooth_dim","text":"numeric vector dimensions smooth.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_dim.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Dimension of a smooth — smooth_dim","text":"generic function methods objects class \"gam\", \"gamm\", \"mgcv.smooth\".","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_dim.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Dimension of a smooth — smooth_dim","text":"Gavin L. Simpson","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_estimates.html","id":null,"dir":"Reference","previous_headings":"","what":"Evaluate smooths at covariate values — smooth_estimates","title":"Evaluate smooths at covariate values — smooth_estimates","text":"Evaluate smooth grid evenly spaced value range covariate associated smooth. Alternatively, set points smooth evaluated can supplied. smooth_estimates() new implementation evaluate_smooth(), replaces function, removed package.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_estimates.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Evaluate smooths at covariate values — smooth_estimates","text":"","code":"smooth_estimates(object, ...) # S3 method for class 'gam' smooth_estimates( object, select = NULL, smooth = deprecated(), n = 100, n_3d = 16, n_4d = 4, data = NULL, unconditional = FALSE, overall_uncertainty = TRUE, dist = NULL, unnest = TRUE, partial_match = FALSE, ... )"},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_estimates.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Evaluate smooths at covariate values — smooth_estimates","text":"object object class \"gam\" \"gamm\". ... arguments passed methods. select character; select smooth's posterior draw . default (NULL) means posteriors smooths model wil sampled . supplied, character vector requested terms. smooth Use select instead. n numeric; number points range covariate evaluate smooth. n_3d, n_4d numeric; number points range last covariate 3D 4D smooth. default NULL achieves standard behaviour using n points range covariate, resulting n^d evaluation points, d dimension smooth. d > 2 can result many evaluation points slow performance. smooths d > 4, value n_4d used dimensions > 4, unless NULL, case default behaviour (using n dimensions) observed. data data frame covariate values evaluate smooth. unconditional logical; confidence intervals include uncertainty due smoothness selection? TRUE, corrected Bayesian covariance matrix used. overall_uncertainty logical; uncertainty model constant term included standard error evaluate values smooth? dist numeric; greater 0, used determine location far data plotted plotting 2-D smooths. data scaled unit square deciding exclude, dist distance within unit square. See mgcv::exclude..far() details. unnest logical; unnest smooth objects? partial_match logical; case character select, select match partially smooths? partial_match = TRUE, select must single string, character vector length 1.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_estimates.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Evaluate smooths at covariate values — smooth_estimates","text":"data frame (tibble), class \"smooth_estimates\".","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_estimates.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Evaluate smooths at covariate values — smooth_estimates","text":"","code":"load_mgcv() dat <- data_sim(\"eg1\", n = 400, dist = \"normal\", scale = 2, seed = 2) m1 <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = dat, method = \"REML\") ## evaluate all smooths smooth_estimates(m1) #> # A tibble: 400 x 9 #> .smooth .type .by .estimate .se x0 x1 x2 x3 #> #> 1 s(x0) TPRS NA -0.966542 0.316118 0.00710904 NA NA NA #> 2 s(x0) TPRS NA -0.925391 0.297170 0.0171157 NA NA NA #> 3 s(x0) TPRS NA -0.884233 0.279256 0.0271224 NA NA NA #> 4 s(x0) TPRS NA -0.843050 0.262594 0.0371291 NA NA NA #> 5 s(x0) TPRS NA -0.801824 0.247376 0.0471358 NA NA NA #> 6 s(x0) TPRS NA -0.760536 0.233728 0.0571425 NA NA NA #> 7 s(x0) TPRS NA -0.719175 0.221701 0.0671492 NA NA NA #> 8 s(x0) TPRS NA -0.677736 0.211261 0.0771559 NA NA NA #> 9 s(x0) TPRS NA -0.636220 0.202303 0.0871626 NA NA NA #> 10 s(x0) TPRS NA -0.594641 0.194685 0.0971693 NA NA NA #> # i 390 more rows ## or selected smooths smooth_estimates(m1, select = c(\"s(x0)\", \"s(x1)\")) #> # A tibble: 200 x 7 #> .smooth .type .by .estimate .se x0 x1 #> #> 1 s(x0) TPRS NA -0.966542 0.316118 0.00710904 NA #> 2 s(x0) TPRS NA -0.925391 0.297170 0.0171157 NA #> 3 s(x0) TPRS NA -0.884233 0.279256 0.0271224 NA #> 4 s(x0) TPRS NA -0.843050 0.262594 0.0371291 NA #> 5 s(x0) TPRS NA -0.801824 0.247376 0.0471358 NA #> 6 s(x0) TPRS NA -0.760536 0.233728 0.0571425 NA #> 7 s(x0) TPRS NA -0.719175 0.221701 0.0671492 NA #> 8 s(x0) TPRS NA -0.677736 0.211261 0.0771559 NA #> 9 s(x0) TPRS NA -0.636220 0.202303 0.0871626 NA #> 10 s(x0) TPRS NA -0.594641 0.194685 0.0971693 NA #> # i 190 more rows"},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_label.html","id":null,"dir":"Reference","previous_headings":"","what":"Extract the label for a smooth used by 'mgcv' — smooth_label","title":"Extract the label for a smooth used by 'mgcv' — smooth_label","text":"label 'mgcv' uses smooths useful many contexts, including selecting smooths labelling plots. smooth_label() extracts label 'mgcv' smooth object, .e. object inherits class \"mgcv.smooth\". typically found $smooth component GAM fitted mgcv::gam() mgcv::bam(), related functions.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_label.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Extract the label for a smooth used by 'mgcv' — smooth_label","text":"","code":"smooth_label(object, ...) # S3 method for class 'gam' smooth_label(object, id, ...) # S3 method for class 'mgcv.smooth' smooth_label(object, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_label.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Extract the label for a smooth used by 'mgcv' — smooth_label","text":"object R object. Currently, methods class \"gam\" mgcv smooth objects inheriting class \"mgcv.smooth\" supported. ... arguments passed methods. id numeric; indices smooths whose labels extracted. missing, labels smooths model returned.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_label.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Extract the label for a smooth used by 'mgcv' — smooth_label","text":"character vector.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_label.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Extract the label for a smooth used by 'mgcv' — smooth_label","text":"","code":"load_mgcv() df <- data_sim(\"gwf2\", n = 100) m <- gam(y ~ s(x), data = df, method = \"REML\") # extract the smooth sm <- get_smooths_by_id(m, id = 1)[[1]] # extract the label smooth_label(sm) #> [1] \"s(x)\" # or directly on the fitted GAM smooth_label(m$smooth[[1]]) #> [1] \"s(x)\" # or extract labels by idex/position smooth_label(m, id = 1) #> [1] \"s(x)\""},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_samples.html","id":null,"dir":"Reference","previous_headings":"","what":"Posterior draws for individual smooths — smooth_samples","title":"Posterior draws for individual smooths — smooth_samples","text":"Returns draws posterior distributions smooth functions GAM. Useful, example, visualising uncertainty individual estimated functions.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_samples.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Posterior draws for individual smooths — smooth_samples","text":"","code":"smooth_samples(model, ...) # S3 method for class 'gam' smooth_samples( model, select = NULL, term = deprecated(), n = 1, data = newdata, method = c(\"gaussian\", \"mh\", \"inla\", \"user\"), seed = NULL, freq = FALSE, unconditional = FALSE, n_cores = 1L, n_vals = 200, burnin = 1000, thin = 1, t_df = 40, rw_scale = 0.25, rng_per_smooth = FALSE, draws = NULL, partial_match = NULL, mvn_method = c(\"mvnfast\", \"mgcv\"), ..., newdata = NULL, ncores = NULL )"},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_samples.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Posterior draws for individual smooths — smooth_samples","text":"model fitted model supported types ... arguments passed methods. fitted_samples(), passed mgcv::predict.gam(). posterior_samples() passed fitted_samples(). predicted_samples() passed relevant simulate() method. select character; select smooth's posterior draw . default (NULL) means posteriors smooths model wil sampled . supplied, character vector requested terms. term Use select instead. n numeric; number posterior samples return. data data frame; new observations posterior draws model evaluated. supplied, data used fit model used data, available model. method character; method used draw samples posterior distribution. \"gaussian\" uses Gaussian (Laplace) approximation posterior. \"mh\" uses Metropolis Hastings sampler alternates t proposals proposals based shrunken version posterior covariance matrix. \"inla\" uses variant Integrated Nested Laplace Approximation due Wood (2019), (currently implemented). \"user\" allows user-supplied posterior draws (currently implemented). seed numeric; random seed simulations. freq logical; TRUE use frequentist covariance matrix parameter estimators, FALSE use Bayesian posterior covariance matrix parameters. unconditional logical; TRUE (freq == FALSE) Bayesian smoothing parameter uncertainty corrected covariance matrix used, available. n_cores number cores generating random variables multivariate normal distribution. Passed mvnfast::rmvn(). Parallelization take place OpenMP supported (appears work Windows current R). n_vals numeric; many locations evaluate smooth data supplied burnin numeric; number samples discard burnin draws. used method = \"mh\". thin numeric; number samples skip taking n draws. Results thin * n draws posterior taken. used method = \"mh\". t_df numeric; degrees freedom t distribution proposals. used method = \"mh\". rw_scale numeric; Factor scale posterior covariance matrix generating random walk proposals. Negative non finite skip random walk step. used method = \"mh\". rng_per_smooth logical; TRUE, behaviour gratia version 0.8.1 earlier used, whereby separate call random number generator (RNG) performed smooth. FALSE, single call RNG performed model parameters draws matrix; user supplied posterior draws used method = \"user\". partial_match logical; smooths selected partial matches select? TRUE, select can single string match . mvn_method character; one \"mvnfast\" \"mgcv\". default uses mvnfast::rmvn(), can considerably faster generate large numbers MVN random values mgcv::rmvn(), might work marginal fits, covariance matrix close singular. newdata Deprecated: use data instead. ncores Deprecated; use n_cores instead. number cores generating random variables multivariate normal distribution. Passed mvnfast::rmvn(). Parallelization take place OpenMP supported (appears work Windows current R).","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_samples.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Posterior draws for individual smooths — smooth_samples","text":"tibble additional classes \"smooth_samples\" `\"posterior_samples\". \"gam\" method, columns currently returned (order) : .smooth; character vector. Indicates smooth function particular draw, .term; character vector. Similar smooth, contain full label smooth, differentiate factor-smooths example. .; character vector. smooth involves term, variable named , NA_character_ otherwise. .row; integer. vector values seq_len(n_vals), repeated n > 1L. Indexes row data particular draw. .draw; integer. vector integer values indexing particular posterior draw row belongs . .value; numeric. value smooth function posterior draw covariate combination. xxx; numeric. series one columns containing data required smooth, named per variables involved respective smooth. Additional columns present case factor smooths, contain level factor named by_variable particular posterior draw.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_samples.html","id":"warning","dir":"Reference","previous_headings":"","what":"Warning","title":"Posterior draws for individual smooths — smooth_samples","text":"set variables returned order tibble subject change future versions. rely position.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_samples.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Posterior draws for individual smooths — smooth_samples","text":"Gavin L. Simpson","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_samples.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Posterior draws for individual smooths — smooth_samples","text":"","code":"load_mgcv() dat <- data_sim(\"eg1\", n = 400, seed = 2) m1 <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = dat, method = \"REML\") sms <- smooth_samples(m1, select = \"s(x0)\", n = 5, seed = 42) # \\donttest{ sms #> # A tibble: 1,000 x 8 #> .smooth .term .type .by .row .draw .value x0 #> #> 1 s(x0) s(x0) TPRS NA 1 1 -0.357 0.00711 #> 2 s(x0) s(x0) TPRS NA 1 2 -0.465 0.00711 #> 3 s(x0) s(x0) TPRS NA 1 3 -0.720 0.00711 #> 4 s(x0) s(x0) TPRS NA 1 4 -1.27 0.00711 #> 5 s(x0) s(x0) TPRS NA 1 5 -1.18 0.00711 #> 6 s(x0) s(x0) TPRS NA 2 1 -0.365 0.0121 #> 7 s(x0) s(x0) TPRS NA 2 2 -0.464 0.0121 #> 8 s(x0) s(x0) TPRS NA 2 3 -0.708 0.0121 #> 9 s(x0) s(x0) TPRS NA 2 4 -1.24 0.0121 #> 10 s(x0) s(x0) TPRS NA 2 5 -1.16 0.0121 #> # i 990 more rows # } ## A factor by example (with a spurious covariate x0) dat <- data_sim(\"eg4\", n = 1000, seed = 2) ## fit model... m2 <- gam(y ~ fac + s(x2, by = fac) + s(x0), data = dat) sms <- smooth_samples(m2, n = 5, seed = 42) draw(sms)"},{"path":[]},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_terms.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"List the variables involved in smooths — smooth_terms","text":"","code":"smooth_terms(object, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_terms.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"List the variables involved in smooths — smooth_terms","text":"object R object result call mgcv::gam(), mgcv::bam(), mgcv::gamm(), inherits classes \"gam\" \"mgcv.smooth\", \"fs.interaction\". ... arguments passed methods. Currently unused.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_type.html","id":null,"dir":"Reference","previous_headings":"","what":"Determine the type of smooth and return it n a human readable form — smooth_type","title":"Determine the type of smooth and return it n a human readable form — smooth_type","text":"Determine type smooth return n human readable form","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_type.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Determine the type of smooth and return it n a human readable form — smooth_type","text":"","code":"smooth_type(smooth) # Default S3 method smooth_type(smooth) # S3 method for class 'tprs.smooth' smooth_type(smooth) # S3 method for class 'ts.smooth' smooth_type(smooth) # S3 method for class 'cr.smooth' smooth_type(smooth) # S3 method for class 'cs.smooth' smooth_type(smooth) # S3 method for class 'cyclic.smooth' smooth_type(smooth) # S3 method for class 'pspline.smooth' smooth_type(smooth) # S3 method for class 'cpspline.smooth' smooth_type(smooth) # S3 method for class 'Bspline.smooth' smooth_type(smooth) # S3 method for class 'duchon.spline' smooth_type(smooth) # S3 method for class 'fs.interaction' smooth_type(smooth) # S3 method for class 'sz.interaction' smooth_type(smooth) # S3 method for class 'gp.smooth' smooth_type(smooth) # S3 method for class 'mrf.smooth' smooth_type(smooth) # S3 method for class 'random.effect' smooth_type(smooth) # S3 method for class 'sw' smooth_type(smooth) # S3 method for class 'sf' smooth_type(smooth) # S3 method for class 'soap.film' smooth_type(smooth) # S3 method for class 't2.smooth' smooth_type(smooth) # S3 method for class 'sos.smooth' smooth_type(smooth) # S3 method for class 'tensor.smooth' smooth_type(smooth) # S3 method for class 'mpi.smooth' smooth_type(smooth) # S3 method for class 'mpd.smooth' smooth_type(smooth) # S3 method for class 'cx.smooth' smooth_type(smooth) # S3 method for class 'cv.smooth' smooth_type(smooth) # S3 method for class 'micx.smooth' smooth_type(smooth) # S3 method for class 'micv.smooth' smooth_type(smooth) # S3 method for class 'mdcx.smooth' smooth_type(smooth) # S3 method for class 'mdcv.smooth' smooth_type(smooth) # S3 method for class 'miso.smooth' smooth_type(smooth) # S3 method for class 'mifo.smooth' smooth_type(smooth)"},{"path":"https://gavinsimpson.github.io/gratia/reference/smooth_type.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Determine the type of smooth and return it n a human readable form — smooth_type","text":"smooth object inheriting class mgcv.smooth.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/smooths.html","id":null,"dir":"Reference","previous_headings":"","what":"Names of smooths in a GAM — smooths","title":"Names of smooths in a GAM — smooths","text":"Names smooths GAM","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/smooths.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Names of smooths in a GAM — smooths","text":"","code":"smooths(object) # Default S3 method smooths(object) # S3 method for class 'gamm' smooths(object)"},{"path":"https://gavinsimpson.github.io/gratia/reference/smooths.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Names of smooths in a GAM — smooths","text":"object fitted GAM related model. Typically result call mgcv::gam(), mgcv::bam(), mgcv::gamm().","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/spline_values.html","id":null,"dir":"Reference","previous_headings":"","what":"Evaluate a spline at provided covariate values — spline_values","title":"Evaluate a spline at provided covariate values — spline_values","text":"Evaluate spline provided covariate values","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/spline_values.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Evaluate a spline at provided covariate values — spline_values","text":"","code":"spline_values( smooth, data, model, unconditional, overall_uncertainty = TRUE, frequentist = FALSE )"},{"path":"https://gavinsimpson.github.io/gratia/reference/spline_values.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Evaluate a spline at provided covariate values — spline_values","text":"smooth currently object inherits class mgcv.smooth. data data frame values evaluate smooth . model fitted model; currently mgcv::gam() mgcv::bam() models suported. unconditional logical; confidence intervals include uncertainty due smoothness selection? TRUE, corrected Bayesian covariance matrix used. overall_uncertainty logical; uncertainty model constant term included standard error evaluate values smooth? frequentist logical; use frequentist covariance matrix?","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/spline_values2.html","id":null,"dir":"Reference","previous_headings":"","what":"Evaluate a spline at provided covariate values — spline_values2","title":"Evaluate a spline at provided covariate values — spline_values2","text":"function spline_values2() renamed spline_values() version 0.9.0. allowed following removal evaluate_smooth(), function using spline_values(). spline_values2() renamed spline_values().","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/spline_values2.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Evaluate a spline at provided covariate values — spline_values2","text":"","code":"spline_values2( smooth, data, model, unconditional, overall_uncertainty = TRUE, frequentist = FALSE )"},{"path":"https://gavinsimpson.github.io/gratia/reference/spline_values2.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Evaluate a spline at provided covariate values — spline_values2","text":"smooth currently object inherits class mgcv.smooth. data optional data frame values evaluate smooth . model fitted model; currently mgcv::gam() mgcv::bam() models suported. unconditional logical; confidence intervals include uncertainty due smoothness selection? TRUE, corrected Bayesian covariance matrix used. overall_uncertainty logical; uncertainty model constant term included standard error evaluate values smooth? frequentist logical; use frequentist covariance matrix?","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/term_names.html","id":null,"dir":"Reference","previous_headings":"","what":"Extract names of all variables needed to fit a GAM or a smooth — term_names","title":"Extract names of all variables needed to fit a GAM or a smooth — term_names","text":"Extract names variables needed fit GAM smooth","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/term_names.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Extract names of all variables needed to fit a GAM or a smooth — term_names","text":"","code":"term_names(object, ...) # S3 method for class 'gam' term_names(object, ...) # S3 method for class 'mgcv.smooth' term_names(object, ...) # S3 method for class 'gamm' term_names(object, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/term_names.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Extract names of all variables needed to fit a GAM or a smooth — term_names","text":"object fitted GAM object (inheriting class \"gam\" mgcv::smooth.construct smooth object, inheriting class \"mgcv.smooth\". ... arguments passed methods. currently used.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/term_names.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Extract names of all variables needed to fit a GAM or a smooth — term_names","text":"vector variable names required terms model","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/term_variables.html","id":null,"dir":"Reference","previous_headings":"","what":"Names of variables involved in a specified model term — term_variables","title":"Names of variables involved in a specified model term — term_variables","text":"Given name (term label) term model, returns names variables involved term.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/term_variables.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Names of variables involved in a specified model term — term_variables","text":"","code":"term_variables(object, term, ...) # S3 method for class 'terms' term_variables(object, term, ...) # S3 method for class 'gam' term_variables(object, term, ...) # S3 method for class 'bam' term_variables(object, term, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/term_variables.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Names of variables involved in a specified model term — term_variables","text":"object R object method dispatch performed term character; name model term, sense attr(terms(object), \"term.labels\"). Currently checked see term exists model. ... arguments passed methods.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/term_variables.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Names of variables involved in a specified model term — term_variables","text":"character vector variable names.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/theta.html","id":null,"dir":"Reference","previous_headings":"","what":"General extractor for additional parameters in mgcv models — theta","title":"General extractor for additional parameters in mgcv models — theta","text":"General extractor additional parameters mgcv models","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/theta.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"General extractor for additional parameters in mgcv models — theta","text":"","code":"theta(object, ...) # S3 method for class 'gam' theta(object, transform = TRUE, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/theta.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"General extractor for additional parameters in mgcv models — theta","text":"object fitted model ... arguments passed methods. transform logical; transform natural scale parameter","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/theta.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"General extractor for additional parameters in mgcv models — theta","text":"Returns numeric vector additional parameters","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/theta.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"General extractor for additional parameters in mgcv models — theta","text":"","code":"load_mgcv() df <- data_sim(\"eg1\", dist = \"poisson\", seed = 42, scale = 1 / 5) m <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = df, method = \"REML\", family = nb() ) p <- theta(m)"},{"path":"https://gavinsimpson.github.io/gratia/reference/tidy_basis.html","id":null,"dir":"Reference","previous_headings":"","what":"A tidy basis representation of a smooth object — tidy_basis","title":"A tidy basis representation of a smooth object — tidy_basis","text":"Takes object class mgcv.smooth returns tidy representation basis.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/tidy_basis.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"A tidy basis representation of a smooth object — tidy_basis","text":"","code":"tidy_basis(smooth, data = NULL, at = NULL, coefs = NULL, p_ident = NULL)"},{"path":"https://gavinsimpson.github.io/gratia/reference/tidy_basis.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"A tidy basis representation of a smooth object — tidy_basis","text":"smooth smooth object inheriting class \"mgcv.smooth\". Typically, objects returned part fitted GAM GAMM $smooth component model object $gam$smooth component model fitted mgcv::gamm() gamm4::gamm4(). data data frame containing variables used smooth. data frame containing values smooth covariate(s) basis evaluated. coefs numeric; optional vector coefficients smooth p_ident logical vector; used handling scam::scam() smooths.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/tidy_basis.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"A tidy basis representation of a smooth object — tidy_basis","text":"tibble.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/tidy_basis.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"A tidy basis representation of a smooth object — tidy_basis","text":"Gavin L. Simpson","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/tidy_basis.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"A tidy basis representation of a smooth object — tidy_basis","text":"","code":"load_mgcv() df <- data_sim(\"eg1\", n = 400, seed = 42) # fit model m <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = df, method = \"REML\") # tidy representaition of a basis for a smooth definition # extract the smooth sm <- get_smooth(m, \"s(x2)\") # get the tidy basis - need to pass where we want it to be evaluated bf <- tidy_basis(sm, at = df) # can weight the basis by the model coefficients for this smooth bf <- tidy_basis(sm, at = df, coefs = smooth_coefs(sm, model = m))"},{"path":"https://gavinsimpson.github.io/gratia/reference/to_na.html","id":null,"dir":"Reference","previous_headings":"","what":"Sets the elements of vector to NA — to_na","title":"Sets the elements of vector to NA — to_na","text":"Given vector indexing elements x, sets selected elements x NA.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/to_na.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Sets the elements of vector to NA — to_na","text":"","code":"to_na(x, i)"},{"path":"https://gavinsimpson.github.io/gratia/reference/to_na.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Sets the elements of vector to NA — to_na","text":"x vector values vector values used subset x","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/to_na.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Sets the elements of vector to NA — to_na","text":"Returns x possibly elements set NA","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/too_far.html","id":null,"dir":"Reference","previous_headings":"","what":"Exclude values that lie too far from the support of data — too_far","title":"Exclude values that lie too far from the support of data — too_far","text":"Identifies pairs covariate values lie far original data. function currently basic wrapper around mgcv::exclude..far().","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/too_far.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Exclude values that lie too far from the support of data — too_far","text":"","code":"too_far(x, y, ref_1, ref_2, dist = NULL)"},{"path":"https://gavinsimpson.github.io/gratia/reference/too_far.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Exclude values that lie too far from the support of data — too_far","text":"x, y numeric; vector values covariates compare observed data ref_1, ref_2 numeric; vectors covariate values represent reference x1 x2` compared dist supplied, numeric vector length 1 representing distance data beyond observation excluded. example, want exclude values lie observation 10% range observed data, use 0.1.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/too_far.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Exclude values that lie too far from the support of data — too_far","text":"Returns logical vector length x1.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/too_far_to_na.html","id":null,"dir":"Reference","previous_headings":"","what":"Set rows of data to NA if the lie too far from a reference set of values — too_far_to_na","title":"Set rows of data to NA if the lie too far from a reference set of values — too_far_to_na","text":"Set rows data NA lie far reference set values","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/too_far_to_na.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Set rows of data to NA if the lie too far from a reference set of values — too_far_to_na","text":"","code":"too_far_to_na(smooth, input, reference, cols, dist = NULL)"},{"path":"https://gavinsimpson.github.io/gratia/reference/too_far_to_na.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Set rows of data to NA if the lie too far from a reference set of values — too_far_to_na","text":"smooth mgcv smooth object input data frame containing input observations columns set NA reference data frame containing reference values cols character vector columns whose elements set NA data lies far reference set dist numeric, distance reference set beyond elements input set NA","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/transform_fun.html","id":null,"dir":"Reference","previous_headings":"","what":"Transform estimated values and confidence intervals by applying a function — transform_fun","title":"Transform estimated values and confidence intervals by applying a function — transform_fun","text":"Transform estimated values confidence intervals applying function","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/transform_fun.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Transform estimated values and confidence intervals by applying a function — transform_fun","text":"","code":"transform_fun(object, fun = NULL, ...) # S3 method for class 'smooth_estimates' transform_fun(object, fun = NULL, constant = NULL, ...) # S3 method for class 'smooth_samples' transform_fun(object, fun = NULL, constant = NULL, ...) # S3 method for class 'mgcv_smooth' transform_fun(object, fun = NULL, constant = NULL, ...) # S3 method for class 'evaluated_parametric_term' transform_fun(object, fun = NULL, constant = NULL, ...) # S3 method for class 'parametric_effects' transform_fun(object, fun = NULL, constant = NULL, ...) # S3 method for class 'tbl_df' transform_fun(object, fun = NULL, column = NULL, constant = NULL, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/transform_fun.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Transform estimated values and confidence intervals by applying a function — transform_fun","text":"object object apply transform function . fun function apply. ... additional arguments passed methods. constant numeric; constant apply transformation. column character; \"tbl_df\" method, column transform.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/transform_fun.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Transform estimated values and confidence intervals by applying a function — transform_fun","text":"Returns object estimate upper lower values confidence interval transformed via function.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/transform_fun.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Transform estimated values and confidence intervals by applying a function — transform_fun","text":"Gavin L. Simpson","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/typical_values.html","id":null,"dir":"Reference","previous_headings":"","what":"Typical values of model covariates — typical_values","title":"Typical values of model covariates — typical_values","text":"Typical values model covariates","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/typical_values.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Typical values of model covariates — typical_values","text":"","code":"typical_values(object, ...) # S3 method for class 'gam' typical_values( object, vars = everything(), envir = environment(formula(object)), data = NULL, ... ) # S3 method for class 'data.frame' typical_values(object, vars = everything(), ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/typical_values.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Typical values of model covariates — typical_values","text":"object fitted GAM(M) model. ... arguments passed methods. vars terms include exclude returned object. Uses tidyselect principles. envir environment within recreate data used fit object. data optional data frame data used fit model reconstruction data model work.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/user_draws.html","id":null,"dir":"Reference","previous_headings":"","what":"Handle user-supplied posterior draws — user_draws","title":"Handle user-supplied posterior draws — user_draws","text":"Handle user-supplied posterior draws","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/user_draws.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Handle user-supplied posterior draws — user_draws","text":"","code":"user_draws(model, draws, ...) # S3 method for class 'gam' user_draws(model, draws, index = NULL, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/user_draws.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Handle user-supplied posterior draws — user_draws","text":"model fitted R model. Currently models fitted mgcv::gam() mgcv::bam(), return object inherits objects supported. , \"inherits\" used loose fashion; models fitted scam::scam() support even though models strictly inherit class \"gam\" far inherits() concerned. draws matrix; user supplied posterior draws used method = \"user\". ... arguments passed methods. index vector index (subset) columns draws.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/user_draws.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Handle user-supplied posterior draws — user_draws","text":"supplied draws must matrix (currently), 1 column per model coefficient, 1 row per posterior draw. \"gam\" method argument index, can used subset (select) coefficients (columns) draws. index can valid way selecting (indexing) columns matrix. index useful set posterior draws entire model (say mgcv::gam.mh()) wish use draws individual smooth, via smooth_samples().","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/variance_comp.html","id":null,"dir":"Reference","previous_headings":"","what":"Variance components of smooths from smoothness estimates — variance_comp","title":"Variance components of smooths from smoothness estimates — variance_comp","text":"wrapper mgcv::gam.vcomp() returns smoothing parameters expressed variance components.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/variance_comp.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Variance components of smooths from smoothness estimates — variance_comp","text":"","code":"variance_comp(object, ...) # S3 method for class 'gam' variance_comp(object, rescale = TRUE, coverage = 0.95, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/variance_comp.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Variance components of smooths from smoothness estimates — variance_comp","text":"object R object. Currently models fitted mgcv::gam() mgcv::bam() supported. ... arguments passed methods rescale logical; numerical stability reasons penalty matrices smooths rescaled fitting. rescale = TRUE, rescaling undone, resulting variance components original scale. needed comparing mixed model software, lmer(). coverage numeric; value 0 1 indicating (approximate) coverage confidence interval returned.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/variance_comp.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Variance components of smooths from smoothness estimates — variance_comp","text":"function wrapper mgcv::gam.vcomp() performs three additional services suppresses annoying text output mgcv::gam.vcomp() prints terminal, returns variance smooth well standard deviation, returns variance components tibble.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/vars_from_label.html","id":null,"dir":"Reference","previous_headings":"","what":"Returns names of variables from a smooth label — vars_from_label","title":"Returns names of variables from a smooth label — vars_from_label","text":"Returns names variables smooth label","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/vars_from_label.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Returns names of variables from a smooth label — vars_from_label","text":"","code":"vars_from_label(label)"},{"path":"https://gavinsimpson.github.io/gratia/reference/vars_from_label.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Returns names of variables from a smooth label — vars_from_label","text":"label character; length 1 character vector containing label smooth.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/vars_from_label.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Returns names of variables from a smooth label — vars_from_label","text":"","code":"vars_from_label(\"s(x1)\") #> [1] \"x1\" vars_from_label(\"t2(x1,x2,x3)\") #> [1] \"x1\" \"x2\" \"x3\""},{"path":"https://gavinsimpson.github.io/gratia/reference/which_smooths.html","id":null,"dir":"Reference","previous_headings":"","what":"Identify a smooth term by its label — which_smooths","title":"Identify a smooth term by its label — which_smooths","text":"Identify smooth term label","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/which_smooths.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Identify a smooth term by its label — which_smooths","text":"","code":"which_smooths(object, ...) # Default S3 method which_smooths(object, ...) # S3 method for class 'gam' which_smooths(object, terms, ...) # S3 method for class 'bam' which_smooths(object, terms, ...) # S3 method for class 'gamm' which_smooths(object, terms, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/which_smooths.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Identify a smooth term by its label — which_smooths","text":"object fitted GAM. ... arguments passed methods. terms character; one (partial) term labels identify required smooths.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/worm_plot.html","id":null,"dir":"Reference","previous_headings":"","what":"Worm plot of model residuals — worm_plot","title":"Worm plot of model residuals — worm_plot","text":"Worm plot model residuals","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/worm_plot.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Worm plot of model residuals — worm_plot","text":"","code":"worm_plot(model, ...) # S3 method for class 'gam' worm_plot( model, method = c(\"uniform\", \"simulate\", \"normal\", \"direct\"), type = c(\"deviance\", \"response\", \"pearson\"), n_uniform = 10, n_simulate = 50, level = 0.9, ylab = NULL, xlab = NULL, title = NULL, subtitle = NULL, caption = NULL, ci_col = \"black\", ci_alpha = 0.2, point_col = \"black\", point_alpha = 1, line_col = \"red\", ... ) # S3 method for class 'glm' worm_plot(model, ...) # S3 method for class 'lm' worm_plot(model, ...)"},{"path":"https://gavinsimpson.github.io/gratia/reference/worm_plot.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Worm plot of model residuals — worm_plot","text":"model fitted model. Currently models inheriting class \"gam\", well classes \"glm\" \"lm\" calls stats::glm stats::lm supported. ... arguments passed ot methods. method character; method used generate theoretical quantiles. default \"uniform\", generates reference quantiles using random draws uniform distribution inverse cummulative distribution function (CDF) fitted values. reference quantiles averaged n_uniform draws. \"simulate\" generates reference quantiles simulating new response data model observed values covariates, residualised generate reference quantiles, using n_simulate simulated data sets. \"normal\" generates reference quantiles using standard normal distribution. \"uniform\" computationally efficient, \"simulate\" allows reference bands drawn QQ-plot. \"normal\" avoided used fall back random number generator (\"simulate\") inverse CDF available family used model fitting (`\"uniform\"“). Note method = \"direct\" deprecated favour method = \"uniform\". type character; type residuals use. \"deviance\", \"response\", \"pearson\" residuals allowed. n_uniform numeric; number times randomize uniform quantiles direct computation method (method = \"uniform\"). n_simulate numeric; number data sets simulate estimated model using simulation method (method = \"simulate\"). level numeric; coverage level reference intervals. Must strictly 0 < level < 1. used method = \"simulate\". ylab character expression; label y axis. supplied, suitable label generated. xlab character expression; label y axis. supplied, suitable label generated. title character expression; title plot. See ggplot2::labs(). May vector, one per penalty. subtitle character expression; subtitle plot. See ggplot2::labs(). May vector, one per penalty. caption character expression; plot caption. See ggplot2::labs(). May vector, one per penalty. ci_col fill colour reference interval method = \"simulate\". ci_alpha alpha transparency reference interval method = \"simulate\". point_col colour points QQ plot. point_alpha alpha transparency points QQ plot. line_col colour used draw reference line.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/worm_plot.html","id":"note","dir":"Reference","previous_headings":"","what":"Note","title":"Worm plot of model residuals — worm_plot","text":"wording used mgcv::qq.gam() uses direct reference simulated residuals method (method = \"simulated\"). avoid confusion, method = \"direct\" deprecated favour method = \"uniform\".","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/worm_plot.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Worm plot of model residuals — worm_plot","text":"","code":"load_mgcv() ## simulate binomial data... dat <- data_sim(\"eg1\", n = 200, dist = \"binary\", scale = .33, seed = 0) p <- binomial()$linkinv(dat$f) # binomial p n <- sample(c(1, 3), 200, replace = TRUE) # binomial n dat <- transform(dat, y = rbinom(n, n, p), n = n) m <- gam(y / n ~ s(x0) + s(x1) + s(x2) + s(x3), family = binomial, data = dat, weights = n, method = \"REML\" ) ## Worm plot; default using direct randomization of uniform quantiles ## Note no reference bands are drawn with this method. worm_plot(m) ## Alternatively use simulate new data from the model, which ## allows construction of reference intervals for the Q-Q plot worm_plot(m, method = \"simulate\", point_col = \"steelblue\", point_alpha = 0.4 ) ## ... or use the usual normality assumption worm_plot(m, method = \"normal\")"},{"path":"https://gavinsimpson.github.io/gratia/reference/zooplankton.html","id":null,"dir":"Reference","previous_headings":"","what":"Madison lakes zooplankton data — zooplankton","title":"Madison lakes zooplankton data — zooplankton","text":"Madison lake zooplankton data long-term study seasonal dynamics zooplankton, collected Richard Lathrop. data collected chain lakes Wisconsin (Mendota, Monona, Kegnonsa, Waubesa) approximately bi-weekly 1976 1994. consist samples zooplankton communities, taken deepest point lake via vertical tow. data provided Wisconsin Department Natural Resources collection processing fully described Lathrop (2000).","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/zooplankton.html","id":"format","dir":"Reference","previous_headings":"","what":"Format","title":"Madison lakes zooplankton data — zooplankton","text":"data frame","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/zooplankton.html","id":"source","dir":"Reference","previous_headings":"","what":"Source","title":"Madison lakes zooplankton data — zooplankton","text":"Pedersen EJ, Miller DL, Simpson GL, Ross N. 2018. Hierarchical generalized additive models: introduction mgcv. PeerJ Preprints 6:e27320v1 doi:10.7287/peerj.preprints.27320v1 .","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/zooplankton.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Madison lakes zooplankton data — zooplankton","text":"record consists counts given zooplankton taxon taken subsample single vertical net tow, scaled account relative volume subsample versus whole net sample area net tow rounded nearest 1000 give estimated population density per m2 taxon point time sampled lake.","code":""},{"path":"https://gavinsimpson.github.io/gratia/reference/zooplankton.html","id":"references","dir":"Reference","previous_headings":"","what":"References","title":"Madison lakes zooplankton data — zooplankton","text":"Lathrop RC. (2000). Madison Wisonsin Lakes Zooplankton 1976–1994. Environmental Data Initiative.","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"gratia-092","dir":"Changelog","previous_headings":"","what":"gratia 0.9.2","title":"gratia 0.9.2","text":"CRAN release: 2024-06-25","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"breaking-changes-0-9-2","dir":"Changelog","previous_headings":"","what":"Breaking changes","title":"gratia 0.9.2","text":"parametric_effects() slightly escaped great renaming happened 0.9.0. Columns type term gain prefix .. now rectified two columns now .type .term.","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"user-visible-changes-0-9-2","dir":"Changelog","previous_headings":"","what":"User visible changes","title":"gratia 0.9.2","text":"Plots random effects now labelled smooth label. Previously, title taken fro variable involved smooth, doesn’t work terms like s(subject, continuous_var, bs = \"re\") random slopes, previsouly title \"subject\". Now terms title \"s(subject,continuous_var)\". Simple random intercept terms, s(subject, bs = \"re\"), now titled \"s(subject)\". #287 vignettes custom-plotting.Rmd, posterior-simulation.Rmd moved vignettes/articles thus longer available package vignettes. Instead, accessible Articles package website: https://gavinsimpson.github.io/gratia/","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"new-features-0-9-2","dir":"Changelog","previous_headings":"","what":"New features","title":"gratia 0.9.2","text":"fitted_samples() now works gam() models multiple linear predictors, currently location parameter supported. parameter indicated new variable .parameter returned object.","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"bug-fixes-0-9-2","dir":"Changelog","previous_headings":"","what":"Bug fixes","title":"gratia 0.9.2","text":"partial_residuals() computing partial residuals deviance residuals. compatibility mgcv::plot.gam(), partial residuals now computed working residuals. Reported @wStockhausen #273 appraise() passing ci_col argument qq_plot() worm_plot(). Reported Sate Ahmed. Couldn’t pass mvn_method posterior sampling functions user facing functions fitted_samples(), posterior_samples(), smooth_samples(), derivative_samples(), repsonse_derivatives(). Reported @stefgehrig #279 fitted_values() works quantile GAMs fitted qgam(). confint.gam() applying shift estimate upper lower interval. #280 reported @TIMAVID & @rbentham parametric_effects() draw.parametric_effects() forget levels factors (intentionally), lead problems ordered factors ordering levels preserved. Now, parametric_effects() returns named list factor levels attribute \"factor_levels\" containing required information order levels preserved plotting. #284 Reported @mhpob parametric_effects() fail parametric terms model interaction terms (don’t currently handle). #282","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"gratia-090","dir":"Changelog","previous_headings":"","what":"gratia 0.9.0","title":"gratia 0.9.0","text":"CRAN release: 2024-03-27","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"breaking-changes-0-9-0","dir":"Changelog","previous_headings":"","what":"Breaking changes","title":"gratia 0.9.0","text":"Many functions now return objects different named variables. order avoid clashes variable names used user’s models data, period (.) now used prefix generated variable names. functions whose names changed : smooth_estimates(), fitted_values(), fitted_samples(), posterior_samples(), derivatives(), partial_derivatives(), derivative_samples(). addition, add_confint() also adds newly-named variables. derivatives() partial_derivatives() now work like smooth_estimates(); place var data columns, gratia now stores data variables derivatives evaluated columns object actual variable names. way spline---sphere (SOS) smooths (bs = \"sos\") plotted changed use ggplot2::coord_sf() instead previously-used ggplot2::coord_map(). changed made result coord_map() soft-deprecated (“superseded”) minor versions ggplot2 now already, changes guides system version 3.5.0 ggplot2. axes plots created coord_map() never really worked correctly changing angle tick labels never worked. coord_map() superseded, didn’t receive updates guides system side effect changes, code plotted SOS smooths producing warning release ggplot2 version 3.5.0. projection settings used draw SOS smooths previously controlled via arguments projection orientation. arguments affect ggplot2::coord_sf(), Instead projection used controlled new argument crs, takes PROJ string detailing projection use integer refers known coordinate reference system (CRS). default projection used +proj=ortho +lat_0=20 +lon_0=XX XX mean longitude coordinates data points.","code":"1. `est` is now `.estimate`, 2. `lower` and `upper` are now `.lower_ci` and `.upper_ci`, 3. `draw` and `row` and now `.draw` and `.row` respectively, 4. `fitted`, `se`, `crit` are now `.fitted`, `.se`, `.crit`, respectively 5. `smooth`, `by`, and `type` in `smooth_estimates()` are now `.smooth`, `.by`, `.type`, respectively."},{"path":[]},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"defunct-0-9-0","dir":"Changelog","previous_headings":"Breaking changes > Defunct and deprecated functions and arguments","what":"Defunct","title":"gratia 0.9.0","text":"evaluate_smooth() deprecated gratia version 0.7.0. function ’s methods removed package. Use smooth_estimates() instead.","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"deprecated-functions-0-9-0","dir":"Changelog","previous_headings":"Breaking changes > Defunct and deprecated functions and arguments","what":"Deprecated functions","title":"gratia 0.9.0","text":"following functions deprecated version 0.9.0 gratia. eventually removed package part clean ahead eventual 1.0.0 release. functions become defunct version 0.11.0 1.0.0, whichever released soonest. evaluate_parametric_term() deprecated. Use parametric_effects() instead. datagen() deprecated. never really originally designed , replaced data_slice().","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"deprecated-arguments-0-9-0","dir":"Changelog","previous_headings":"Breaking changes > Defunct and deprecated functions and arguments","what":"Deprecated arguments","title":"gratia 0.9.0","text":"make functions package consistent, arguments select, term, smooth used thing hence latter two deprecated favour select. deprecated argument used, warning issued value assigned argument assigned select function continue.","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"user-visible-changes-0-9-0","dir":"Changelog","previous_headings":"","what":"User visible changes","title":"gratia 0.9.0","text":"smooth_samples() now uses single call RNG generate draws posterior smooths. Previous version 0.9.0, smooth_samples() separate call mvnfast::rmvn() smooth. result, result call smooth_samples() model multiple smooths now produce different results generated previously. regain old behaviour, add rng_per_smooth = TRUE smooth_samples() call. Note, however, using per-smooth RNG calls method = \"mh\" inefficient , method, posterior draws coefficients model sampled . , use rng_per_smooth = TRUE method = \"gaussian\". output smooth_estimates() draw() method changed tensor product smooths involve one 2D marginal smooths. Now, covariate values supplied via data argument, smooth_estimates() identifies one marginals 2d surface allows covariates involved surface vary fastest, ahead terms marginals. change made provides better default nothing provided data. also affects draw.gam(). fitted_values() now level support location, scale, shape families. Supported families mgcv::gaulss(), mgcv::gammals(), mgcv::gumbls(), mgcv::gevlss(), mgcv::shash(), mgcv::twlss(), mgcv::ziplss(). gratia now requires dplyr versions >= 1.1.0 tidyselect >= 1.2.0. new vignette Posterior Simulation available, describes posterior simulation fitted GAMs using {gratia}.","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"new-features-0-9-0","dir":"Changelog","previous_headings":"","what":"New features","title":"gratia 0.9.0","text":"Soap film smooths using basis bs = \"\" now handled draw(), smooth_estimates() etc. #8 response_derivatives() new function computing derivatives response respect (continuous) focal variable. First second order derivatives can computed using forward, backward, central finite differences. uncertainty estimated derivative determined using posterior sampling via fitted_samples(), hence can derived Gaussian approximation posterior using Metropolis Hastings sampler (see .) derivative_samples() work horse function behind response_derivatives(), computes returns posterior draws derivatives additive combination model terms. Requested @jonathanmellor #237 data_sim() can now simulate response data gamma, Tweedie ordered categorical distributions. data_sim() gains two new example models \"gwf2\", simulating data Gu & Wabha’s f2 function, \"lwf6\", example function 6 Luo & Wabha (1997 JASA 92(437), 107-116). data_sim() can also simulate data use GAMs fitted using family = gfam() grouped families different types data response handled. #266 part #265 fitted_samples() smooth_samples() can now use Metropolis Hastings sampler mgcv::gam.mh(), instead Gaussian approximation, sample posterior distribution model specific smooths respectively. posterior_samples() new function family fitted_samples() smooth_samples(). posterior_samples() returns draws posterior distribution response, combining uncertainty estimated expected value response dispersion response distribution. difference posterior_samples() predicted_samples() latter includes variation due drawing samples conditional distribution response (uncertainty expected values ignored), former includes sources uncertainty. fitted_samples() can new use matrix user-supplied posterior draws. Related #120 add_fitted_samples(), add_predicted_samples(), add_posterior_samples(), add_smooth_samples() new utility functions add respective draws posterior distribution existing data object covariate values object: obj |> add_posterior_draws(model). #50 basis_size() new function extract basis dimension (number basis functions) smooths. Methods available objects inherit classes \"gam\", \"gamm\", \"mgcv.smooth\" (individual smooths). data_slice() gains method data frames tibbles. typical_values() gains method data frames tibbles. fitted_values() now works models fitted using mgcv::ocat() family. predicted probability category returned, alongside Wald interval created using standard error (SE) estimated probability. SE estimated probabilities transformed logit (linear predictor) scale, Wald credible interval formed, back-transformed response (probability) scale. fitted_values() now works GAMMs fitted using mgcv::gamm(). Fitted (predicted) values use GAM part model, thus exclude random effects. link() inv_link() work models fitted using cnorm() family. worm plot can now drawn place QQ plot appraise() via new argument use_worm = TRUE. #62 smooths() now works models fitted mgcv::gamm(). overview() now returns basis dimension smooth gains argument stars TRUE add significance stars output plus legend printed tibble footer. Part wish @noamross #214 New add_constant() transform_fun() methods smooth_samples(). evenly() gains arguments lower upper modify lower / upper bound interval evenly spaced values generated. add_sizer() new function add information whether derivative smooth significantly changing (credible interval excludes 0). Currently, methods derivatives() smooth_estimates() objects implemented. Part request @asanders11 #117 draw.derivatives() gains arguments add_change change_type allow derivatives smooths plotted indicators credible interval derivative excludes 0. Options allow periods decrease increase differentiated via change_type = \"sizer\" instead default change_type = \"change\", emphasises either type change way. Part wish @asanders11 #117 draw.gam() can now group factor smooths given factor single panel, rather plotting smooths level separate panels. achieved via new argument grouped_by. Requested @RPanczak #89 draw.smooth_estimates() can now also group factor smooths given factor single panel. underlying plotting code used draw_smooth_estimates() univariate smooths can now add change indicators plots smooths change indicators added object created smooth_estimates() using add_sizer(). See example ?draw.smooth_estimates. smooth_estimates() can, evaluating 3D 4D tensor product smooth, identify one 2D smooths marginal tensor product. users provide covariate values evaluate smooths, smooth_estimates() focus 2D marginal smooth (first one involved tensor product), instead following ordering terms definition tensor product. #191 example, te(z, x, y, bs = c(cr, ds), d = c(1, 2)), second marginal smooth 2D Duchon spline covariates x y. Previously, smooth_estimates() generated n values z x n_3d values y, evaluated tensor product combinations generated values. ignore structure implicit tensor product, likely want know surface estimated Duchon spline x y smoothly varies z. Previously smooth_estimates() generate surfaces z x, varying y. Now, smooth_estimates() correctly identifies one marginal smooths tensor product 2D surface focus surface varying terms tensor product. improved behaviour needed bam() models always possible obvious thing reorder smooths defining tensor product te(x, y, z, bs = c(ds, cr), d = c(2, 1)). discrete = TRUE used bam() terms tensor product may get rearranged model setup maximum efficiency (See Details ?mgcv::bam). Additionally, draw.gam() now also works way. New function null_deviance() extracts null deviance fitted model. draw(), smooth_estimates(), fitted_values(), data_slice(), smooth_samples() now work models fitted scam::scam(). matters, current support extends univariate smooths. generate_draws() new low-level function generating posterior draws fitted model coefficients. generate_daws() S3 generic function extensible users. Currently provides simple interface simple Gaussian approximation sampler (gaussian_draws()) simple Metropolis Hasting sample (mh_draws()) available via mgcv::gam.mh(). #211 smooth_label() new function extracting labels ‘mgcv’ creates smooths smooth object . penalty() default method works s(), te(), t2(), ti(), create smooth specification. transform_fun() gains argument constant allow addition constant value objects (e.g. estimate confidence interval). enables single obj |> transform_fun(fun = exp, constant = 5) instead separate calls add_constant() transform_fun(). Part discussion #79 model_constant() new function simply extracts first coefficient estimated model.","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"bug-fixes-0-9-0","dir":"Changelog","previous_headings":"","what":"Bug fixes","title":"gratia 0.9.0","text":"link(), inv_link(), related family functions ocat() weren’t correctly identifying family name result throw error even passed object correct family. link() inv_link() now work correctly betar() family fitted GAM. print() method lp_matrix() now converts matrix data frame conversion tibble. makes sense results typical behaviour columns printed object doubles. Constrained factor smooths (bs = \"sz\") factor first variable mentioned smooth (.e. s(x, f, bs = \"sz\") continuous x factor f) now plotable draw(). #208 parametric_effects() unable handle special parametric terms like poly(x) log(x) formulas. Reported @fhui28 #212 parametric_effects() now works better location, scale, shape models. Reported @pboesu #45 parametric_effects now works missing values one variables used fitted GAM. #219 response_derivatives() incorrectly using .data tidyselect selectors. typical_values() handle logical variables GAM fit mgcv stores numerics var.summary. affected evenly() data_slice(). #222 parametric_effects() fail two ordered factors model. Reported @dsmi31 #221 Continuous smooths evaluated median value variable instead value 1. #224 fitted_samples() (hence posterior_samples()) now handles models offset terms formula. Offset terms supplied via offset argument ignored mgcv:::predict.gam() hence ignored also gratia. Reported @jonathonmellor #231 #233 smooth_estimates() fail \"fs\" smooth multivariate base smoother used factor last variable specified definition smooth: s(x1, x2, f, bs = \"fs\", xt = list(bs = \"ds\")) work, s(f, x1, x2, bs = \"fs\", xt = list(bs = \"ds\")) (ordering variables places factor last) emit obscure error. ordering terms involved smooth now doesn’t matter. Reported @chrisaak #249. draw.gam() fail plotting multivariate base smoother used \"sz\" smooth. Now, use case identified message printed indicating (currently) gratia doesn’t know plot smooth. Reported @chrisaak #249. draw.gam() fail plotting multivariate base smoother used \"fs\" smooth. Now, use case identified message printed indicating (currently) gratia doesn’t know plot smooth. Reported @chrisaak #249. derivative_samples() fail order = 2 computing forward finite differences, regardless type order = 1. Partly reported @samlipworth #251. draw() method penalty() normalizing penalty range 0–1, claimed documented -1–1 argument normalize = TRUE. now fixed. smooth_samples() failing data supplied contained variables used smooth sampled. Hence generally fail unless single smooth sampled model contained single smooth. function never intended retain variables data written way fail relocating data columns end posterior sampling object. #255 draw.gam() draw.smooth_estimates() fail plotting univariate tensor product smooth (e.g. te(x), ti(x), t2()). Reported @wStockhausen #260 plot.smooth() printing factor level subtitles ordered factor smooths.","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"gratia-082","dir":"Changelog","previous_headings":"","what":"gratia 0.8.2","title":"gratia 0.8.2","text":"CRAN release: 2024-01-09 Small fixes CRAN.","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"gratia-081","dir":"Changelog","previous_headings":"","what":"gratia 0.8.1","title":"gratia 0.8.1","text":"CRAN release: 2023-02-02","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"user-visible-changes-0-8-1","dir":"Changelog","previous_headings":"","what":"User visible changes","title":"gratia 0.8.1","text":"smooth_samples() now returns objects variables involved smooths correct name. Previously variables named .x1, .x2, etc. Fixing #126 improving compatibility compare_smooths() smooth_estimates() allowed variables named correctly. gratia now depends version 1.8-41 later mgcv package.","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"new-features-0-8-1","dir":"Changelog","previous_headings":"","what":"New features","title":"gratia 0.8.1","text":"draw.gam() can now handle tensor products include marginal random effect smooth. Beware plotting smooths many levels, however, separate surface plot produced level.","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"bug-fixes-0-8-1","dir":"Changelog","previous_headings":"","what":"Bug fixes","title":"gratia 0.8.1","text":"Additional fixes changes dplyr 1.1.0. smooth_samples() now works sampling posteriors multiple smooths different dimension. #126 reported @Aariq","code":""},{"path":[]},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"user-visible-changes-0-8-0","dir":"Changelog","previous_headings":"","what":"User visible changes","title":"gratia 0.8.0","text":"{gratia} now depends R version 4.1 later. new vignette “Data slices” supplied {gratia}. Functions {gratia} harmonised use argument named data instead newdata passing new data evaluate features smooths. message printed newdata used now . Existing code need changed data takes value newdata. Note due way ... handled R, R script uses data argument, run versions gratia prior 8.0 (released; 0.7.3.8 using development version) user-supplied data silently ignored. , scripts using data check installed version gratia >= 0.8 package developers update depend versions >= 0.8 using gratia (>= 0.8) DESCRIPTION. order plots smooths changed draw.gam() match order smooths specified model formula. See Bug Fixes detail #154.","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"new-features-0-8-0","dir":"Changelog","previous_headings":"","what":"New features","title":"gratia 0.8.0","text":"Added basic support GAMLSS (distributional GAMs) fitted gamlss() function package GJRM. Support currently restricted draw() method. difference_smooths() can now include group means difference, many users expected. include group means use group_means = TRUE function call, e.g. difference_smooths(model, smooth = \"s(x)\", group_means = TRUE). Note: function still differs plot_diff() package itsadug, essentially computes differences model predictions. main practical difference effects beyond factor smooth, including random effects, may included plot_diff(). implements main wish #108 (@dinga92) #143 (@mbolyanatz) despite protestations complicated cases (isn’t; complexity just cancels .) data_slice() totally revised. Now, user provides values variables want slice variables model specified held typical values (.e. value observation closest median numeric variables, modal factor level.) Data slices now produced passing name = value pairs variables values want appear slice. example value pair can expression looked (evaluated) data argument model frame fitted model (default). example, resulting slice data frame 100 observations, comprising x1, vector 100 values spread evenly range x1, constant value mean x2 x2 variable, constant factor level, model class fac, fac variable model. partial_derivatives() new function computing partial derivatives multivariate smooths (e.g. s(x,z), te(x,z)) respect one margins smooth. Multivariate smooths dimension handled, one dimensions allowed vary. Partial derivatives estimated using method finite differences, forward, backward, central finite differences available. Requested @noamross #101 overview() provides simple overview model terms fitted GAMs. new bs = \"sz\" basis released mgcv version 1.18-41 now supported smooth_estimates(), draw.gam(), draw.smooth_estimates() basis unique plotting method. #202 basis() now method fitted GAM(M)s can extract estimated basis model plot , using estimated coefficients smooth weight basis. #137 also new draw.basis() method plotting results call basis(). method can now also handle bivariate bases. tidy_basis() lower level function heavy lifting basis(), now exported. tidy_basis() returns tidy representation basis supplied object inheriting class \"mgcv.smooth\". objects returned $smooth component fitted GAM(M) model. lp_matrix() new utility function quickly return linear predictor matrix estimated model. wrapper predict(..., type = \"lpmatrix\") evenly() synonym seq_min_max() preferred going forward. Gains argument produce sequences covariate increment units . ref_level() level() new utility functions extracting reference specific level factor respectively. useful specifying covariate values condition data slice. model_vars() new, public facing way returning vector variables used model. difference_smooths() now use user-supplied data points evaluate pair smooths. Also note argument newdata renamed data. #175 draw() method difference_smooths() now uses better labels plot titles avoid long labels even modest factor levels. derivatives() now works factor-smooth interaction (\"fs\") smooths. draw() methods now allow angle tick labels x axis plots rotated using argument angle. Requested @tamas-ferenci #87 draw.gam() related functions (draw.parametric_effects(), draw.smooth_estimates()) now add basis plot using caption. #155 smooth_coefs() new utility function extracting coefficients particular smooth fitted model. smooth_coef_indices() associated function returns indices (positions) vector model coefficients (returned coef(gam_model)) coefficients pertain stated smooth. draw.gam() now better handles patchworks plots one plots fixed aspect ratios. #190","code":"m <- gam(y ~ s(x1) + x2 + fac) data_slice(model, x1 = evenly(x1, n = 100), x2 = mean(x2))"},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"bug-fixes-0-8-0","dir":"Changelog","previous_headings":"","what":"Bug fixes","title":"gratia 0.8.0","text":"draw.posterior_smooths now plots posterior samples fixed aspect ratio smooth isotropic. #148 derivatives() now ignores random effect smooths (derivatives don’t make sense anyway). #168 confint.gam(...., method = \"simultaneous\") now works factor smooths parm passed full name specific smooth s(x)faclevel. order plots produced gratia::draw.gam() matches order smooths entered model formula. Recent changes internals gratia::draw.gam() switch smooth_estimates() undertaken lead change behaviour resulting use dplyr::group_split(), ’s coercion internally character vector factor. factor now created explicitly, levels set correct order. #154 Setting dist argument set response smooth values NA lay far support data multivariate smooths, lead incorrect scale response guide. now fixed. #193 Argument fun draw.gam() applied parametric terms. Reported @grasshoppermouse #195 draw.gam() adding uncertainty linear predictors smooths overall_uncertainty = TRUE used. Now draw.gam() includes uncertainty linear predictors smooth takes part. #158 partial_derivatives() works provided single data point evaluate derivative. #199 transform_fun.smooth_estimates() addressing wrong variable names trying transform confidence interval. #201 data_slice() doesn’t fail error used model contains offset term. #198 confint.gam() longer uses evaluate_smooth(), soft deprecated. #167 qq_plot() worm_plot() compute wrong deviance residuals used generate theoretical quantiles exotic families (distributions) available mgcv. also affected appraise() QQ plot; residuals shown plots deviance residuals shown y-axis QQ plot correct. generation reference intervals/quantiles affected.","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"gratia-073","dir":"Changelog","previous_headings":"","what":"gratia 0.7.3","title":"gratia 0.7.3","text":"CRAN release: 2022-05-09","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"user-visible-changes-0-7-3","dir":"Changelog","previous_headings":"","what":"User visible changes","title":"gratia 0.7.3","text":"Plots smooths now use “Partial effect” y-axis label place “Effect”, better indicate displayed.","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"new-features-0-7-3","dir":"Changelog","previous_headings":"","what":"New features","title":"gratia 0.7.3","text":"confint.fderiv() confint.gam() now return results tibble instead common--garden data frame. latter mostly already . Examples confint.fderiv() confint.gam() reworked, part remove inconsistent output examples run M1 macs.","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"bug-fixes-0-7-3","dir":"Changelog","previous_headings":"","what":"Bug fixes","title":"gratia 0.7.3","text":"compare_smooths() failed passed non-standard model “names” like compare_smooths(m_gam, m_gamm$gam) compare_smooths(l[[1]], l[[2]]) even evaluated objects valid GAM(M) models. Reported Andrew Irwin #150","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"gratia-072","dir":"Changelog","previous_headings":"","what":"gratia 0.7.2","title":"gratia 0.7.2","text":"CRAN release: 2022-03-17","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"new-features-0-7-2","dir":"Changelog","previous_headings":"","what":"New features","title":"gratia 0.7.2","text":"draw.gam() draw.smooth_estimates() can now handle splines sphere (s(lat, long, bs = \"sos\")) special plotting methods using ggplot2::coord_map() handle projection spherical coordinates. orthographic projection used default, essentially arbitrary (northern hemisphere-centric) default orientation view. fitted_values() insures data (hence returned object) tibble rather common garden data frame.","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"bug-fixes-0-7-2","dir":"Changelog","previous_headings":"","what":"Bug fixes","title":"gratia 0.7.2","text":"draw.posterior_smooths() redundantly plotting duplicate data rug plot. Now unique set covariate values used drawing rug. data_sim() passing scale argument bivariate example setting (\"eg2\"). draw() methods gamm() gamm4::gamm4() fits passing arguments draw.gam(). draw.smooth_estimates() produce subtitle data continuous smooth factor smooth. Now subtitle contains name continuous variable.","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"gratia-071","dir":"Changelog","previous_headings":"","what":"gratia 0.7.1","title":"gratia 0.7.1","text":"Due issue size package source tarball, wasn’t discovered submission CRAN, 0.7.1 never released.","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"new-features-0-7-1","dir":"Changelog","previous_headings":"","what":"New features","title":"gratia 0.7.1","text":"draw.gam() draw.smooth_estimates(): {gratia} can now handle smooths 3 4 covariates plotting. smooths 3 covariates, third covariate handled ggplot2::facet_wrap() set (default n = 16) small multiples drawn, 2d surface evaluated specified value third covariate. smooths 4 covariates, ggplot2::facet_grid() used draw small multiples, default producing 4 rows 4 columns plots specific values third fourth covariates. number small multiples produced controlled new arguments n_3d (default = n_3d = 16) n_4d (default n_4d = 4, yielding n_4d * n_4d = 16 facets) respectively. affects plotting; smooth_estimates() able handle smooths number covariates . handling higher-dimensional smooths, actually drawing plots default device can slow, especially default value n = 100 (3D 4D smooths result 160,000 data points plotted). recommended reduce n smaller value: n = 50 reasonable compromise resolution speed. model_concurvity() returns concurvity measures mgcv::concurvity() estimated GAMs tidy format. synonym concrvity() also provided. draw() method provided produces bar plot heatmap concurvity values depending whether overall concurvity smooth pairwise concurvity smooth model requested. draw.gam() gains argument resid_col = \"steelblue3\" allows colour partial residuals (plotted) changed.","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"bug-fixes-0-7-1","dir":"Changelog","previous_headings":"","what":"Bug fixes","title":"gratia 0.7.1","text":"model_edf() using type argument. result ever returned default EDF type. add_constant() methods weren’t applying constant required variables. draw.gam(), draw.parametric_effects() now actually work model parametric effects. #142 Reported @Nelson-Gon parametric_effects() fail model parametric terms predict.gam() returns empty arrays passed exclude = character(0).","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"gratia-070","dir":"Changelog","previous_headings":"","what":"gratia 0.7.0","title":"gratia 0.7.0","text":"CRAN release: 2022-02-07","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"major-changes-0-7-0","dir":"Changelog","previous_headings":"","what":"Major changes","title":"gratia 0.7.0","text":"draw.gam() now uses smooth_estimates() internally consequently uses draw() method underlying plotting code. simplified code compared evaluate_smooth() methods, allow future development addition features easily evaluate_smooth() retained. Similarly, evaluate_parametric_terms() now deprecated favour parametric_effects(), also used internally draw.gam() parametric terms present model (parametric = TRUE). lot code reused differences plots result change minimal, corner cases may missed. File Issue notice something changed think shouldn’t. draw.gam() now plots 2D isotropic smooths (TPRS Duchon splines) equally-scaled x y coordinates using coord_equal(ratio = 1). Alignment plots little different now plotting models multiple smooths. See Issue #81.","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"deprecated-functions-0-7-0","dir":"Changelog","previous_headings":"Major changes","what":"Deprecated functions","title":"gratia 0.7.0","text":"version 0.7.0, following functions considered deprecated use discouraged: fderiv() soft-deprecated favour derivatives(), evaluate_smooth() soft-deprecated favour smooth_estimates(), evaluate_parametric_term() soft-deprecated favour parametric_effects(). first call one functions generate warning, pointing newer, alternative, function. safe ignore warnings, deprecated functions longer receive updates thus risk removed package future date. newer alternatives can handle types models smooths, especially case smooth_estimates().","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"new-features-0-7-0","dir":"Changelog","previous_headings":"","what":"New features","title":"gratia 0.7.0","text":"fitted_values() provides tidy wrapper around predict.gam() generating fitted values model. New covariate values can provided via argument data. credible interval fitted values returned, values can link (linear predictor) response scale. Note function returns expected values response. Hence, “fitted values” used instead “predictions” case new covariate values differentiate values case generating new response values fitted model. rootogram() draw() method produce rootograms diagnostic plots fitted models. Currently models fitted poisson(), nb(), negbin(), gaussian() families. New helper functions typical_values(), factor_combos() data_combos() quickly creating data sets producing predictions fitted models covariatess fixed come typical representative values. typical_values() new helper function return typical values covariates fitted model. returns value observation closest median numerical covariates modal level factor preserving levels factor. typical_values() useful preparing data slices scenarios fitted values estimated model required. factor_combos() extracts returns combinations levels factors found data used fit model. Unlike typical_values(), factor_combos() returns combinations factor levels observed data, just modal level. Optionally, combinations factor levels can returned, just observed data. data_combos() combines returns factor data factor_combos() plus typical values numerical covariates. useful want generate predictions model combination factor terms holding continuous covariates median values. nb_theta() new extractor function returns theta parameter fitted negative binomial GAM (families nb() negbin()). Additionally, theta() has_theta() provide additional functionality. theta() experimental function extracting additional parameters model family. has_theta() useful checking additional parameters available family model. edf() extracts effective degrees freedom (EDF) fitted model specific smooth model. Various forms EDF can extracted. model_edf() returns EDF overall model. supplied multiple models, EDFs model returned comparison. draw.gam() can now show “rug” plot bivariate smooth drawing small points high transparency smooth surface data coordinates. addition, rugs plots factor smooths now show locations covariate values specific level factor levels. better reflects data used estimate smooth, even though basis smooth set using covariate locations. draw.gam() draw.smooth_estimates() now allow aspects plot changed: fill (colour) alpha attributes credible interval, line colour smooth can now specified using arguments ci_col, ci_alpha, smooth_col respectively. Partial residuals can now plotted factor smooths. allow , partial residuals filtered residuals associated particular level’s smooth drawn plot smooth. smooth_estimates() uses check_user_select_smooths() handle user-specified selection smooth terms. flexible previously, allows easier selection smooths evaluate. fixef() now imported (re-exported) nlme package, methods models fitted gam() gamm(), extract fixed effects estimates fitted models. fixed_effects() alias fixef(). draw() method smooth_samples() can now handle 2D smooths. Additionally, number posterior draws plot can now specified plotting using new argument n_samples, result n_samples draws selected random set draws plotting. New argument seed allows selection draws repeatable.","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"bug-fixes-0-7-0","dir":"Changelog","previous_headings":"","what":"Bug fixes","title":"gratia 0.7.0","text":"smooth_estimates() filtering user-supplied data level specific smooth used factor smooths. result smooth evaluated rows user-supplied data, therefore result nrow(user_data) * nlevels(by_variable) rows returned object instead nrow(user_data) rows. add_confint() method smooth_estimates() upper lower intervals reversed. #107 Reported @Aariq draw.gam() smooth_estimates() ignoring dist argument allows covariate values lie far support data excluded returning estimated values smooth plotting . #111 Reported @Aariq smooth_samples() factor GAM return samples first factor level . Reported @rroyaute discussion #121 smooth_samples() fail model contained random effect “smooths”. now ignored message running smooth_samples(). Reported @isabellaghement #121 link(), inv_link() failing models fitted family = scat(). Reported @Aariq #130","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"gratia-060","dir":"Changelog","previous_headings":"","what":"gratia 0.6.0","title":"gratia 0.6.0","text":"CRAN release: 2021-04-18","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"major-changes-0-6-0","dir":"Changelog","previous_headings":"","what":"Major changes","title":"gratia 0.6.0","text":"{cowplot} package replaced {patchwork} package producing multi-panel figures draw() appraise(). shouldn’t affect code used {gratia} , passed additional arguments cowplot::plot_grid() used align axis arguments draw() appraise(), ’ll need adapt code accordingly. Typically, can simply delete align axis arguments {patchwork} just work align plots nicely. arguments passed via ... cowplot::plot_grid() just ignored patchwork::wrap_plots() unless passed arguments match arguments patchwork::wrap_plots().","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"new-features-0-6-0","dir":"Changelog","previous_headings":"","what":"New features","title":"gratia 0.6.0","text":"{patchwork} package now used multi-panel figures. , {gratia} longer Imports {cowplot} package. Worm plot diagnostic plots available via new function worm_plot(). Worm plots detrended Q-Q plots, deviation Q-Q reference line emphasized deviations around line occupy full height plot. worm_plot() methods available models classes \"gam\", \"glm\", \"lm\". (#62) Smooths can now compared across models using compare_smooths(), comparisons visualised associated draw() method. (#85 @dill) feature bit experimental; returned object uses nested lists may change future users find confusing. reference line qq_plot() method = \"normal\" previously drawn line intercept 0 slope 1, match methods. inconsistent stats::qqplot() drew line 1st 3rd quartiles. qq_plot() method = \"normal\" now uses robust reference line. Reference lines methods remain drawn slope 1 intercept 0. qq_plot() method = \"normal\" now draws point-wise reference band using standard error order statistic. draw() method penalty() now plots penalty matrix heatmaps -logical orientation, match matrices might written printed R console. link(), inv_link() now work models fitted gumbls() shash() families. (#84) extract_link() lower level utility function related link() inv_link(), now exported.","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"user-visible-changes-0-6-0","dir":"Changelog","previous_headings":"","what":"User visible changes","title":"gratia 0.6.0","text":"default method name generating reference quantiles qq_plot() changed \"direct\" \"uniform\", avoid confusion mgcv::qq.gam() help page description methods. Accordingly using method = \"direct\" deprecated message effect displayed used. way smooths/terms selected derivatives() switched use mechanism draw.gam()’s select argument. get partial match term, now need also specify partial_match = TRUE call derivatives().","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"bug-fixes-0-6-0","dir":"Changelog","previous_headings":"","what":"Bug fixes","title":"gratia 0.6.0","text":"transform_fun() copy paste bug definition generic. (#96 @Aariq) derivatives() user-supplied newdata fail factor smooths interval = \"simultaneous\" introduce rows derivative == 0 interval = \"confidence\" didn’t subset rows newdata specific level factor computing derivatives. (#102 @sambweber) evaluate_smooth() can now handle random effect smooths defined using ordered factor. (#99 @StefanoMezzini)","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"gratia-051","dir":"Changelog","previous_headings":"","what":"gratia 0.5.1","title":"gratia 0.5.1","text":"CRAN release: 2021-01-23","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"new-features-0-5-1","dir":"Changelog","previous_headings":"","what":"New features","title":"gratia 0.5.1","text":"smooth_estimates() can now handle bivariate multivariate thinplate regression spline smooths, e.g.  s(x, z, ), tensor product smooths (te(), t2(), & ti()), e.g. te(x, z, ) factor smooth interactions, e.g. s(x, f, bs = \"fs\") random effect smooths, e.g. s(f, bs = \"re\") penalty() provides tidy representation penalty matrices smooths. tidy representation suitable plotting ggplot(). draw() method provided, represents penalty matrix heatmap.","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"user-visible-changes-0-5-1","dir":"Changelog","previous_headings":"","what":"User visible changes","title":"gratia 0.5.1","text":"newdata argument smooth_estimates() changed data originally intended.","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"gratia-050","dir":"Changelog","previous_headings":"","what":"gratia 0.5.0","title":"gratia 0.5.0","text":"CRAN release: 2021-01-10","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"new-features-0-5-0","dir":"Changelog","previous_headings":"","what":"New features","title":"gratia 0.5.0","text":"Partial residuals models can computed partial_residuals(). partial residuals weighted residuals model added contribution smooth term (returned predict(model, type = \"terms\"). Wish #76 (@noamross) Also, new function add_partial_residuals() can used add partial residuals data frames. Users can now control extent colour fill scales used plotting smooths draw() methods use . useful change fill scale plotting 2D smooths, change discrete colour scale used plotting random factor smooths (bs = \"fs\"). user can pass scales via arguments discrete_colour continuous_fill. effects certain smooths can excluded data simulated model using simulate.gam() predicted_samples() passing exclude terms predict.gam(). allows excluding random effects, example, model predicted values used simulate new data conditional distribution. See example predicted_samples(). Wish #74 (@hgoldspiel) draw.gam() related functions gain arguments constant fun allow user-defined constants transformations smooth estimates confidence intervals applied. Part wish Wish #79. confint.gam() now works 2D smooths also. smooth_estimates() early version code replace (likely supersede) evaluate_smooth(). smooth_estimates() can currently handle 1D smooths standard types.","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"user-visible-changes-0-5-0","dir":"Changelog","previous_headings":"","what":"User visible changes","title":"gratia 0.5.0","text":"meaning parm confint.gam changed. argument now requires smooth label match smooth. vector labels can provided, partial matching smooth label works single parm value. default behaviour remains unchanged however; parm NULL smooths evaluated returned confidence intervals. data_class() longer exported; ever intended internal function.","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"bug-fixes-0-5-0","dir":"Changelog","previous_headings":"","what":"Bug Fixes","title":"gratia 0.5.0","text":"confint.gam() failing tensor product smooth due matching issues. Reported @tamas-ferenci #88 also fixes #80 related issue selecting specific smooth. vdiffr package now used conditionally package tests. Reported Brian Ripley #93","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"gratia-041","dir":"Changelog","previous_headings":"","what":"gratia 0.4.1","title":"gratia 0.4.1","text":"CRAN release: 2020-05-30","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"user-visible-changes-0-4-1","dir":"Changelog","previous_headings":"","what":"User visible changes","title":"gratia 0.4.1","text":"draw.gam() scales = \"fixed\" now applies terms can plotted, including 2d smooths. Reported @StefanoMezzini #73","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"bug-fixes-0-4-1","dir":"Changelog","previous_headings":"","what":"Bug fixes","title":"gratia 0.4.1","text":"dplyr::combine() deprecated. Switch vctrs::vec_c(). draw.gam() scales = \"fixed\" wasn’t using fixed scales 2d smooths model. Reported @StefanoMezzini #73","code":""},{"path":[]},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"new-features-0-4-0","dir":"Changelog","previous_headings":"","what":"New features","title":"gratia 0.4.0","text":"draw.gam() can include partial residuals drawing univariate smooths. Use residuals = TRUE add partial residuals univariate smooth drawn. feature available smooths one variable, smooths, factor-smooth interactions (bs = \"fs\"). coverage credible confidence intervals drawn draw.gam() can specified via argument ci_level. default arbitrarily 0.95 reason (rough) compatibility plot.gam(). change effect making intervals slightly narrower previous versions gratia; intervals drawn ± 2 × standard error. default intervals now drawn ± ~1.96 × standard error. New function difference_smooths() computing differences factor smooth interactions. Methods available gam(), bam(), gamm() gamm4::gamm4(). Also draw() method, can handle differences 1D 2D smooths currently (handling 3D 4D smooths planned). New functions add_fitted() add_residuals() add fitted values (expectations) model residuals existing data frame. Currently methods available objects fitted gam() bam(). data_sim() tidy reimplementation mgcv::gamSim() added ability use sampling distributions Gaussian models implemented. Currently Gaussian, Poisson, Bernoulli sampling distributions available. smooth_samples() can handle continuous variable smooths varying coefficient models. link() inv_link() now work families available mgcv, including location, scale, shape families, specialised families described ?mgcv::family.mgcv. evaluate_smooth(), data_slice(), family(), link(), inv_link() methods models fitted using gamm4() gamm4 package. data_slice() can generate data 1-d slice (single variable varying). colour points, reference lines, simulation band appraise() can now specified via arguments point_col, point_alpha, ci_col ci_alpha line_col passed qq_plot(), observed_fitted_plot(), residuals_linpred_plot(), residuals_hist_plot(), also now take new arguments applicable. Added utility functions is_factor_term() term_variables() working models. is_factor_term() identifies named term factor using information terms() object fitted model. term_variables() returns character vector variable names involved model term. strictly working parametric terms models. appraise() now works models fitted glm() lm(), underlying functions calls, especially qq_plot. appraise() also works models fitted family gaulss(). location scale models models fitted extended family functions supported upcoming releases.","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"user-visible-changes-0-4-0","dir":"Changelog","previous_headings":"","what":"User visible changes","title":"gratia 0.4.0","text":"datagen() now internal function longer exported. Use data_slice() instead. evaluate_parametric_term() now much stricter can evaluate main effect terms, .e. whose order, stored terms object model 1.","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"bug-fixes-0-4-0","dir":"Changelog","previous_headings":"","what":"Bug fixes","title":"gratia 0.4.0","text":"draw() method derivatives() getting x-axis label factor smooths correctly, instead using NA second subsequent levels factor. datagen() method class \"gam\" couldn’t possibly worked anything simplest models fail even simple factor smooths. issues fixed, behaviour datagen() changed, function now intended use users. Fixed issue models terms form factor1:factor2 incorrectly identified numeric parametric terms. #68","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"gratia-031","dir":"Changelog","previous_headings":"","what":"gratia 0.3.1","title":"gratia 0.3.1","text":"CRAN release: 2020-03-29","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"new-features-0-3-1","dir":"Changelog","previous_headings":"","what":"New features","title":"gratia 0.3.1","text":"New functions link() inv_link() access link function inverse fitted models family functions. Methods classes: \"glm\", \"gam\", \"bam\", \"gamm\" currently. #58 Adds explicit family() methods objects classes \"gam\", \"bam\", \"gamm\". derivatives() now handles non-numeric creating shifted data finite differences. Fixes problem stringsAsFactors = FALSE default R-devel. #64","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"bug-fixes-0-3-1","dir":"Changelog","previous_headings":"","what":"Bug fixes","title":"gratia 0.3.1","text":"Updated gratia work tibble versions >= 3.0","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"gratia-030","dir":"Changelog","previous_headings":"","what":"gratia 0.3.0","title":"gratia 0.3.0","text":"CRAN release: 2020-01-19","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"new-features-0-3-0","dir":"Changelog","previous_headings":"","what":"New features","title":"gratia 0.3.0","text":"gratia now uses mvnfast package random draws multivariate normal distribution (mvnfast::rmvn()). Contributed Henrik Singmann #28 New function basis() generating tidy representations basis expansions mgcv-like definition smooth, e.g. s(), te(), ti(), t2(). basic smooth types also simple draw() method plotting basis. basis() simple wrapper around mgcv::smoothCon() post processing basis model matrix tidy format. #42 New function smooth_samples() draw samples entire smooth functions posterior distribution. Also draw() method plotting posterior samples.","code":""},{"path":"https://gavinsimpson.github.io/gratia/news/index.html","id":"bug-fixes-0-3-0","dir":"Changelog","previous_headings":"","what":"Bug fixes","title":"gratia 0.3.0","text":"draw.gam() produce empty plots panels parametric terms 2 parametric terms model. Reported @sklayn #39. derivatives() now works factor smooths, including ordered factor smooths. function also now works correctly complex models multiple covariates/smooths. #47 derivatives() also now handles 'fs' smooths. Reported @tomand-uio #57. evaluate_parametric_term() hence draw.gam() fail ziplss() model ) gratia didn’t handle parametric terms models multiple linear predictors correctly, ii) gratia didn’t convert naming convention mgcv terms higher linear predictors. Reported @pboesu #45","code":""}]