diff --git a/.Rbuildignore b/.Rbuildignore index f725f03c..37cfb740 100644 --- a/.Rbuildignore +++ b/.Rbuildignore @@ -12,10 +12,7 @@ ^docs$ ^pkgdown$ ^cran-comments\.md$ -^news\.md$ ^codemeta\.json$ -^CODE_OF_CONDUCT\.md$ -^CODE_OF_CONDUCT\.html$ rebuild-long-running-vignettes.R update_autodiff.sh diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 547231d1..916f29c3 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -18,7 +18,7 @@ See our guide on [how to create a great issue](https://code-review.tidyverse.org ### Pull request process -* Fork the package and clone onto your computer. If you haven't done this before, we recommend using `usethis::create_from_github("LCBC-UiO/galamm", fork = TRUE)`. +* Fork the package and clone onto your computer. If you haven't done this before, we recommend using `usethis::create_from_github("ropensci/galamm", fork = TRUE)`. * Install all development dependencies with `devtools::install_dev_deps()`, and then make sure the package passes R CMD check by running `devtools::check()`. If R CMD check doesn't pass cleanly, it's a good idea to ask for help before continuing. @@ -43,8 +43,8 @@ See our guide on [how to create a great issue](https://code-review.tidyverse.org ## Code of Conduct Please note that the galamm project is released with a -[Contributor Code of Conduct](CODE_OF_CONDUCT.md). By contributing to this -project you agree to abide by its terms. +[Contributor Code of Conduct](https://ropensci.org/code-of-conduct/). By +contributing to this project you agree to abide by its terms. ## Roadmap diff --git a/.github/workflows/pkgdown.yaml b/.github/workflows/pkgdown.yaml deleted file mode 100644 index 0b260216..00000000 --- a/.github/workflows/pkgdown.yaml +++ /dev/null @@ -1,46 +0,0 @@ -# Workflow derived from https://github.com/r-lib/actions/tree/v2/examples -# Need help debugging build failures? Start at https://github.com/r-lib/actions#where-to-find-help -on: - push: - branches: [main, master] - pull_request: - branches: [main, master] - release: - types: [published] - workflow_dispatch: - -name: pkgdown - -jobs: - pkgdown: - runs-on: ubuntu-latest - # Only restrict concurrency for non-PR jobs - concurrency: - group: pkgdown-${{ github.event_name != 'pull_request' || github.run_id }} - env: - GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }} - steps: - - uses: actions/checkout@v2 - - - uses: r-lib/actions/setup-pandoc@v2 - - - uses: r-lib/actions/setup-r@v2 - with: - use-public-rspm: true - - - uses: r-lib/actions/setup-r-dependencies@v2 - with: - extra-packages: any::pkgdown, local::. - needs: website - - - name: Build site - run: pkgdown::build_site_github_pages(new_process = FALSE, install = FALSE) - shell: Rscript {0} - - - name: Deploy to GitHub pages 🚀 - if: github.event_name != 'pull_request' - uses: JamesIves/github-pages-deploy-action@4.1.4 - with: - clean: false - branch: gh-pages - folder: docs diff --git a/.github/workflows/test-docs.yaml b/.github/workflows/test-docs.yaml new file mode 100644 index 00000000..30936078 --- /dev/null +++ b/.github/workflows/test-docs.yaml @@ -0,0 +1,21 @@ +# The pkgdown website for galamm is built centrally by rOpenSci and published +# at https://docs.ropensci.org/galamm/, so this package no longer deploys a +# site of its own. This workflow runs the very same build script that rOpenSci +# uses, so that problems with the documentation are caught here rather than +# after merging. The rendered site is stored as a build artifact. +# +# See https://github.com/ropensci-org/rotemplate/ for details. +on: + push: + branches: [main] + pull_request: + branches: [main] + workflow_dispatch: + +name: Test-docs + +jobs: + Test-docs: + runs-on: ubuntu-latest + steps: + - uses: ropensci-org/rotemplate@main diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md deleted file mode 100644 index f56d558f..00000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,126 +0,0 @@ -# Contributor Covenant Code of Conduct - -## Our Pledge - -We as members, contributors, and leaders pledge to make participation in our -community a harassment-free experience for everyone, regardless of age, body -size, visible or invisible disability, ethnicity, sex characteristics, gender -identity and expression, level of experience, education, socioeconomic status, -nationality, personal appearance, race, caste, color, religion, or sexual -identity and orientation. - -We pledge to act and interact in ways that contribute to an open, welcoming, -diverse, inclusive, and healthy community. - -## Our Standards - -Examples of behavior that contributes to a positive environment for our -community include: - -* Demonstrating empathy and kindness toward other people -* Being respectful of differing opinions, viewpoints, and experiences -* Giving and gracefully accepting constructive feedback -* Accepting responsibility and apologizing to those affected by our mistakes, - and learning from the experience -* Focusing on what is best not just for us as individuals, but for the overall - community - -Examples of unacceptable behavior include: - -* The use of sexualized language or imagery, and sexual attention or advances of - any kind -* Trolling, insulting or derogatory comments, and personal or political attacks -* Public or private harassment -* Publishing others' private information, such as a physical or email address, - without their explicit permission -* Other conduct which could reasonably be considered inappropriate in a - professional setting - -## Enforcement Responsibilities - -Community leaders are responsible for clarifying and enforcing our standards of -acceptable behavior and will take appropriate and fair corrective action in -response to any behavior that they deem inappropriate, threatening, offensive, -or harmful. - -Community leaders have the right and responsibility to remove, edit, or reject -comments, commits, code, wiki edits, issues, and other contributions that are -not aligned to this Code of Conduct, and will communicate reasons for moderation -decisions when appropriate. - -## Scope - -This Code of Conduct applies within all community spaces, and also applies when -an individual is officially representing the community in public spaces. -Examples of representing our community include using an official e-mail address, -posting via an official social media account, or acting as an appointed -representative at an online or offline event. - -## Enforcement - -Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported to the community leaders responsible for enforcement at oystein.sorensen.1985@gmail.com. -All complaints will be reviewed and investigated promptly and fairly. - -All community leaders are obligated to respect the privacy and security of the -reporter of any incident. - -## Enforcement Guidelines - -Community leaders will follow these Community Impact Guidelines in determining -the consequences for any action they deem in violation of this Code of Conduct: - -### 1. Correction - -**Community Impact**: Use of inappropriate language or other behavior deemed -unprofessional or unwelcome in the community. - -**Consequence**: A private, written warning from community leaders, providing -clarity around the nature of the violation and an explanation of why the -behavior was inappropriate. A public apology may be requested. - -### 2. Warning - -**Community Impact**: A violation through a single incident or series of -actions. - -**Consequence**: A warning with consequences for continued behavior. No -interaction with the people involved, including unsolicited interaction with -those enforcing the Code of Conduct, for a specified period of time. This -includes avoiding interactions in community spaces as well as external channels -like social media. Violating these terms may lead to a temporary or permanent -ban. - -### 3. Temporary Ban - -**Community Impact**: A serious violation of community standards, including -sustained inappropriate behavior. - -**Consequence**: A temporary ban from any sort of interaction or public -communication with the community for a specified period of time. No public or -private interaction with the people involved, including unsolicited interaction -with those enforcing the Code of Conduct, is allowed during this period. -Violating these terms may lead to a permanent ban. - -### 4. Permanent Ban - -**Community Impact**: Demonstrating a pattern of violation of community -standards, including sustained inappropriate behavior, harassment of an -individual, or aggression toward or disparagement of classes of individuals. - -**Consequence**: A permanent ban from any sort of public interaction within the -community. - -## Attribution - -This Code of Conduct is adapted from the [Contributor Covenant][homepage], -version 2.1, available at -. - -Community Impact Guidelines were inspired by -[Mozilla's code of conduct enforcement ladder][https://github.com/mozilla/inclusion]. - -For answers to common questions about this code of conduct, see the FAQ at -. Translations are available at . - -[homepage]: https://www.contributor-covenant.org diff --git a/DESCRIPTION b/DESCRIPTION index 6351469d..24b2c1dd 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,6 +1,6 @@ Package: galamm Title: Generalized Additive Latent and Mixed Models -Version: 0.4.0 +Version: 0.4.1 Authors@R: c( person(given = "Øystein", family = "Sørensen", @@ -29,8 +29,8 @@ Description: Estimates generalized additive latent and ) and 'PLmixed' (Rockwood and Jeon (2019) ). License: GPL (>= 3) -URL: https://github.com/LCBC-UiO/galamm, https://lcbc-uio.github.io/galamm/ -BugReports: https://github.com/LCBC-UiO/galamm/issues +URL: https://docs.ropensci.org/galamm/, https://github.com/ropensci/galamm +BugReports: https://github.com/ropensci/galamm/issues Encoding: UTF-8 Imports: gratia, diff --git a/news.md b/NEWS.md similarity index 73% rename from news.md rename to NEWS.md index 6c234ebf..64b1a5fe 100644 --- a/news.md +++ b/NEWS.md @@ -1,4 +1,25 @@ -# galamm 0.3.0 (development versions) +# galamm 0.4.1 + +galamm has been peer reviewed and accepted by rOpenSci, and the repository has +moved to https://github.com/ropensci/galamm. This release contains the changes +made during and after that review. There are no changes to the user-facing +model fitting functions. + +- All links to the source repository, including the continuous integration and + test coverage badges, now point to the repository under the rOpenSci + organization. +- The package website has moved to https://docs.ropensci.org/galamm/, and is + now built centrally by rOpenSci. All documentation links have been updated + accordingly, and the package no longer deploys a website of its own. +- The pkgdown configuration now requests MathJax explicitly, so that the + mathematical notation in the vignettes renders reliably on the new website. +- The bundled code of conduct has been removed, since rOpenSci's code of + conduct at https://ropensci.org/code-of-conduct/ now applies. The + contributing guidelines link to it instead. +- The README describes how to install development versions from the rOpenSci + R-universe. + +# galamm 0.4.0 - Vignettes are updated to better demonstrate model checking possibilities. - A qqmath() function has now been added, which makes quantile-quantile plots. diff --git a/README.Rmd b/README.Rmd index a7068562..853ed606 100644 --- a/README.Rmd +++ b/README.Rmd @@ -18,14 +18,14 @@ knitr::opts_chunk$set( ) ``` -# Generalized Additive Latent and Mixed Models galamm website +# Generalized Additive Latent and Mixed Models galamm website [![CRAN status](https://www.r-pkg.org/badges/version/galamm)](https://cran.r-project.org/package=galamm) [![Status at rOpenSci Software Peer Review](https://badges.ropensci.org/615_status.svg)](https://github.com/ropensci/software-review/issues/615) [![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active) -[![R-CMD-check](https://github.com/LCBC-UiO/galamm/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/LCBC-UiO/galamm/actions/workflows/R-CMD-check.yaml) -[![Codecov test coverage](https://codecov.io/gh/LCBC-UiO/galamm/branch/main/graph/badge.svg)](https://app.codecov.io/gh/LCBC-UiO/galamm?branch=main) +[![R-CMD-check](https://github.com/ropensci/galamm/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/ropensci/galamm/actions/workflows/R-CMD-check.yaml) +[![Codecov test coverage](https://codecov.io/gh/ropensci/galamm/branch/main/graph/badge.svg)](https://app.codecov.io/gh/ropensci/galamm?branch=main) ```{r srr-tags1, eval = FALSE, echo = FALSE} @@ -47,7 +47,7 @@ Some typical usage examples include: - Analyzing data with mixed response types, e.g., when a latent trait is measured with a combination of continuous and binary responses. - Avoiding measurement error bias by utilizing replicate measurements of covariates of interest. -To get started, take a look at the [introductory vignette](https://lcbc-uio.github.io/galamm/articles/galamm.html). +To get started, take a look at the [introductory vignette](https://docs.ropensci.org/galamm/articles/galamm.html). ## What Can the Package Do? @@ -55,12 +55,12 @@ Many applications, particularly in the social sciences, require modeling capabil The goal of galamm is to enable estimation of models with an arbitrary number of grouping levels, both crossed and hierarchical, and any combination of the following features (click the links to go to the relevant vignette): -- [Linear mixed models with factor structures](https://lcbc-uio.github.io/galamm/articles/lmm_factor.html). -- [Generalized linear mixed models with factor structures](https://lcbc-uio.github.io/galamm/articles/glmm_factor.html). -- [Linear mixed models with heteroscedastic residuals](https://lcbc-uio.github.io/galamm/articles/lmm_heteroscedastic.html). -- [Mixed models with mixed response types](https://lcbc-uio.github.io/galamm/articles/mixed_response.html). -- [Generalized additive mixed models with factor structures](https://lcbc-uio.github.io/galamm/articles/semiparametric.html). -- [Interactions between latent and observed covariates](https://lcbc-uio.github.io/galamm/articles/latent_observed_interaction.html). +- [Linear mixed models with factor structures](https://docs.ropensci.org/galamm/articles/lmm_factor.html). +- [Generalized linear mixed models with factor structures](https://docs.ropensci.org/galamm/articles/glmm_factor.html). +- [Linear mixed models with heteroscedastic residuals](https://docs.ropensci.org/galamm/articles/lmm_heteroscedastic.html). +- [Mixed models with mixed response types](https://docs.ropensci.org/galamm/articles/mixed_response.html). +- [Generalized additive mixed models with factor structures](https://docs.ropensci.org/galamm/articles/semiparametric.html). +- [Interactions between latent and observed covariates](https://docs.ropensci.org/galamm/articles/latent_observed_interaction.html). ```{r srr-tags2, eval = FALSE, echo = FALSE} #' @srrstats {G1.6} Code for comparing the performance of galamm to the of PLmixed for example models is provided in the vignette on linear mixed models with factor structures. @@ -69,7 +69,7 @@ The goal of galamm is to enable estimation of models with an arbitrary number of Random effects are defined using [lme4](https://cran.r-project.org/package=lme4) syntax, and the syntax for factor structures are close to that of [PLmixed](https://cran.r-project.org/package=PLmixed) [@rockwoodEstimatingComplexMeasurement2019]. However, for the types of models supported by both PLmixed and galamm, galamm is usually considerably faster. Smooth terms, as in generalized additive mixed models, use the same syntax as [mgcv](https://cran.r-project.org/package=mgcv). -For most users, it should not be necessary to think about how the actual computations are performed, although they are detailed in the [optimization vignette](https://lcbc-uio.github.io/galamm/articles/optimization.html). In short, the core computations are done using sparse matrix methods supported by [RcppEigen](https://cran.r-project.org/package=RcppEigen) [@batesFastElegantNumerical2013] and automatic differentiation using the C++ library [autodiff](https://autodiff.github.io/) [@lealAutodiffModernFast2018]. Scaling of the algorithm is investigated further in [the vignette on computational scaling](https://lcbc-uio.github.io/galamm/articles/scaling.html). +For most users, it should not be necessary to think about how the actual computations are performed, although they are detailed in the [optimization vignette](https://docs.ropensci.org/galamm/articles/optimization.html). In short, the core computations are done using sparse matrix methods supported by [RcppEigen](https://cran.r-project.org/package=RcppEigen) [@batesFastElegantNumerical2013] and automatic differentiation using the C++ library [autodiff](https://autodiff.github.io/) [@lealAutodiffModernFast2018]. Scaling of the algorithm is investigated further in [the vignette on computational scaling](https://docs.ropensci.org/galamm/articles/scaling.html). ## Installation @@ -79,11 +79,17 @@ Install the package from CRAN using install.packages("galamm") ``` -You can install the development version of galamm from [GitHub](https://github.com/) with: +You can install the development version of galamm from the [rOpenSci R-universe](https://ropensci.r-universe.dev/galamm) using + +``` r +install.packages("galamm", repos = c("https://ropensci.r-universe.dev", "https://cloud.r-project.org")) +``` + +or from [GitHub](https://github.com/) with: ``` r # install.packages("remotes") -remotes::install_github("LCBC-UiO/galamm") +remotes::install_github("ropensci/galamm") ``` ## Examples @@ -171,6 +177,6 @@ Some parts of the code base for galamm has been derived from internal functions ## Contributing -Contributions are very welcome, see [CONTRIBUTING.md](https://github.com/LCBC-UiO/galamm/blob/main/.github/CONTRIBUTING.md) for general guidelines. +Contributions are very welcome, see [CONTRIBUTING.md](https://github.com/ropensci/galamm/blob/main/.github/CONTRIBUTING.md) for general guidelines. ## References diff --git a/README.md b/README.md index b5c76271..3732355d 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ -# Generalized Additive Latent and Mixed Models galamm website +# Generalized Additive Latent and Mixed Models galamm website @@ -12,17 +12,17 @@ Review](https://badges.ropensci.org/615_status.svg)](https://github.com/ropensci [![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active) -[![R-CMD-check](https://github.com/LCBC-UiO/galamm/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/LCBC-UiO/galamm/actions/workflows/R-CMD-check.yaml) +[![R-CMD-check](https://github.com/ropensci/galamm/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/ropensci/galamm/actions/workflows/R-CMD-check.yaml) [![Codecov test -coverage](https://codecov.io/gh/LCBC-UiO/galamm/branch/main/graph/badge.svg)](https://app.codecov.io/gh/LCBC-UiO/galamm?branch=main) +coverage](https://codecov.io/gh/ropensci/galamm/branch/main/graph/badge.svg)](https://app.codecov.io/gh/ropensci/galamm?branch=main) galamm estimates generalized additive latent and mixed models (GALAMMs). This is the first package implementing the model framework and the -computational algorithms introduced in Sørensen, Fjell, and Walhovd +computational algorithms introduced in Sørensen et al. ([2023](#ref-sorensenLongitudinalModelingAgeDependent2023)). It is an extension of the GLLAMM framework for multilevel latent variable -modeling detailed in Rabe-Hesketh, Skrondal, and Pickles +modeling detailed in Rabe-Hesketh et al. ([2004](#ref-rabe-heskethGeneralizedMultilevelStructural2004)) and Skrondal and Rabe-Hesketh ([2004](#ref-skrondalGeneralizedLatentVariable2004)), in particular by @@ -41,7 +41,7 @@ Some typical usage examples include: covariates of interest. To get started, take a look at the [introductory -vignette](https://lcbc-uio.github.io/galamm/articles/galamm.html). +vignette](https://docs.ropensci.org/galamm/articles/galamm.html). ## What Can the Package Do? @@ -56,8 +56,7 @@ feasible with popular R packages like 2015](#ref-batesFittingLinearMixedEffects2015)), and [OpenMx](https://openmx.ssri.psu.edu/) ([Neale et al. 2016](#ref-nealeOpenMxExtendedStructural2016)), as well as the Stata -based [GLLAMM](http://www.gllamm.org/) software ([Rabe-Hesketh, -Skrondal, and Pickles +based [GLLAMM](http://www.gllamm.org/) software ([Rabe-Hesketh et al. 2004](#ref-rabe-heskethGeneralizedMultilevelStructural2004), [2005](#ref-rabe-heskethMaximumLikelihoodEstimation2005)). In particular, to maximally utilize large datasets available today, it is @@ -73,17 +72,17 @@ combination of the following features (click the links to go to the relevant vignette): - [Linear mixed models with factor - structures](https://lcbc-uio.github.io/galamm/articles/lmm_factor.html). + structures](https://docs.ropensci.org/galamm/articles/lmm_factor.html). - [Generalized linear mixed models with factor - structures](https://lcbc-uio.github.io/galamm/articles/glmm_factor.html). + structures](https://docs.ropensci.org/galamm/articles/glmm_factor.html). - [Linear mixed models with heteroscedastic - residuals](https://lcbc-uio.github.io/galamm/articles/lmm_heteroscedastic.html). + residuals](https://docs.ropensci.org/galamm/articles/lmm_heteroscedastic.html). - [Mixed models with mixed response - types](https://lcbc-uio.github.io/galamm/articles/mixed_response.html). + types](https://docs.ropensci.org/galamm/articles/mixed_response.html). - [Generalized additive mixed models with factor - structures](https://lcbc-uio.github.io/galamm/articles/semiparametric.html). + structures](https://docs.ropensci.org/galamm/articles/semiparametric.html). - [Interactions between latent and observed - covariates](https://lcbc-uio.github.io/galamm/articles/latent_observed_interaction.html). + covariates](https://docs.ropensci.org/galamm/articles/latent_observed_interaction.html). Random effects are defined using [lme4](https://cran.r-project.org/package=lme4) syntax, and the syntax @@ -98,7 +97,7 @@ mixed models, use the same syntax as For most users, it should not be necessary to think about how the actual computations are performed, although they are detailed in the [optimization -vignette](https://lcbc-uio.github.io/galamm/articles/optimization.html). +vignette](https://docs.ropensci.org/galamm/articles/optimization.html). In short, the core computations are done using sparse matrix methods supported by [RcppEigen](https://cran.r-project.org/package=RcppEigen) ([Bates and Eddelbuettel 2013](#ref-batesFastElegantNumerical2013)) and @@ -106,7 +105,7 @@ automatic differentiation using the C++ library [autodiff](https://autodiff.github.io/) ([Leal 2018](#ref-lealAutodiffModernFast2018)). Scaling of the algorithm is investigated further in [the vignette on computational -scaling](https://lcbc-uio.github.io/galamm/articles/scaling.html). +scaling](https://docs.ropensci.org/galamm/articles/scaling.html). ## Installation @@ -116,12 +115,18 @@ Install the package from CRAN using install.packages("galamm") ``` -You can install the development version of galamm from -[GitHub](https://github.com/) with: +You can install the development version of galamm from the [rOpenSci +R-universe](https://ropensci.r-universe.dev/galamm) using + +``` r +install.packages("galamm", repos = c("https://ropensci.r-universe.dev", "https://cloud.r-project.org")) +``` + +or from [GitHub](https://github.com/) with: ``` r # install.packages("remotes") -remotes::install_github("LCBC-UiO/galamm") +remotes::install_github("ropensci/galamm") ``` ## Examples @@ -230,7 +235,7 @@ We finally plot the estimated smooth term. plot_smooth(mod) ``` - + ## How to cite this package @@ -273,13 +278,12 @@ contributor to this package, please let me know, and I will remove you. ## Contributing Contributions are very welcome, see -[CONTRIBUTING.md](https://github.com/LCBC-UiO/galamm/blob/main/.github/CONTRIBUTING.md) +[CONTRIBUTING.md](https://github.com/ropensci/galamm/blob/main/.github/CONTRIBUTING.md) for general guidelines. ## References -
+
@@ -301,18 +305,17 @@ Statistical Software* 67 (1): 1–48.
-Leal, Allan M. M. 2018. “Autodiff, a Modern, Fast and Expressive C++ -Library for Automatic Differentiation.” +Leal, Allan M. M. 2018. *Autodiff, a Modern, Fast and Expressive C++ +Library for Automatic Differentiation*.
-Neale, Michael C., Michael D. Hunter, Joshua N. Pritikin, Mahsa Zahery, -Timothy R. Brick, Robert M. Kirkpatrick, Ryne Estabrook, Timothy C. -Bates, Hermine H. Maes, and Steven M. Boker. 2016. “OpenMx 2.0: Extended -Structural Equation and Statistical Modeling.” *Psychometrika* 81 (2): -535–49. . +Neale, Michael C., Michael D. Hunter, Joshua N. Pritikin, et al. 2016. +“OpenMx 2.0: Extended Structural Equation and Statistical Modeling.” +*Psychometrika* 81 (2): 535–49. +.
@@ -328,10 +331,10 @@ Rabe-Hesketh, Sophia, Anders Skrondal, and Andrew Pickles. 2004.
-———. 2005. “Maximum Likelihood Estimation of Limited and Discrete -Dependent Variable Models with Nested Random Effects.” *Journal of -Econometrics* 128 (2): 301–23. -. +Rabe-Hesketh, Sophia, Anders Skrondal, and Andrew Pickles. 2005. +“Maximum Likelihood Estimation of Limited and Discrete Dependent +Variable Models with Nested Random Effects.” *Journal of Econometrics* +128 (2): 301–23. .
@@ -356,8 +359,8 @@ Modeling.” *Journal of Statistical Software* 48 (May): 1–36.
Skrondal, Anders, and Sophia Rabe-Hesketh. 2004. *Generalized Latent -Variable Modeling*. Interdisciplinary Statistics Series. Boca Raton, -Florida: Chapman and Hall/CRC. +Variable Modeling*. Interdisciplinary Statistics Series. Chapman and +Hall/CRC.
diff --git a/_pkgdown.yml b/_pkgdown.yml index d0ef12d1..8a0d704e 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -1,6 +1,11 @@ -url: https://lcbc-uio.github.io/galamm/ +url: https://docs.ropensci.org/galamm/ + +# Styling is provided centrally by rOpenSci's rotemplate package, so no +# template customisation is set here. MathJax is requested explicitly because +# the vignettes rely heavily on LaTeX maths, which pkgdown's default MathML +# rendering does not display reliably across browsers. template: - bootstrap: 5 + math-rendering: mathjax articles: - title: Get started diff --git a/codemeta.json b/codemeta.json index f3be4079..c1dfa385 100644 --- a/codemeta.json +++ b/codemeta.json @@ -4,11 +4,11 @@ "identifier": "galamm", "description": "Estimates generalized additive latent and mixed models using maximum marginal likelihood, as defined in Sorensen et al. (2023) , which is an extension of Rabe-Hesketh and Skrondal (2004)'s unifying framework for multilevel latent variable modeling . Efficient computation is done using sparse matrix methods, Laplace approximation, and automatic differentiation. The framework includes generalized multilevel models with heteroscedastic residuals, mixed response types, factor loadings, smoothing splines, crossed random effects, and combinations thereof. Syntax for model formulation is close to 'lme4' (Bates et al. (2015) ) and 'PLmixed' (Rockwood and Jeon (2019) ).", "name": "galamm: Generalized Additive Latent and Mixed Models", - "relatedLink": ["https://lcbc-uio.github.io/galamm/", "https://CRAN.R-project.org/package=galamm"], - "codeRepository": "https://github.com/LCBC-UiO/galamm", - "issueTracker": "https://github.com/LCBC-UiO/galamm/issues", + "relatedLink": ["https://docs.ropensci.org/galamm/", "https://CRAN.R-project.org/package=galamm"], + "codeRepository": "https://github.com/ropensci/galamm", + "issueTracker": "https://github.com/ropensci/galamm/issues", "license": "https://spdx.org/licenses/GPL-3.0", - "version": "0.4.0", + "version": "0.4.1", "programmingLanguage": { "@type": "ComputerLanguage", "name": "R", @@ -364,9 +364,9 @@ } } ], - "releaseNotes": "https://github.com/LCBC-UiO/galamm/blob/main/NEWS.md", - "readme": "https://github.com/LCBC-UiO/galamm/blob/main/README.md", - "contIntegration": ["https://github.com/LCBC-UiO/galamm/actions/workflows/R-CMD-check.yaml", "https://app.codecov.io/gh/LCBC-UiO/galamm?branch=main"], + "releaseNotes": "https://github.com/ropensci/galamm/blob/main/NEWS.md", + "readme": "https://github.com/ropensci/galamm/blob/main/README.md", + "contIntegration": ["https://github.com/ropensci/galamm/actions/workflows/R-CMD-check.yaml", "https://app.codecov.io/gh/ropensci/galamm?branch=main"], "developmentStatus": "https://www.repostatus.org/#active", "review": { "@type": "Review", diff --git a/man/figures/README-unnamed-chunk-9-1.png b/man/figures/README-unnamed-chunk-9-1.png index ea4ae432..a8039549 100644 Binary files a/man/figures/README-unnamed-chunk-9-1.png and b/man/figures/README-unnamed-chunk-9-1.png differ diff --git a/man/galamm-package.Rd b/man/galamm-package.Rd index 7f678fe3..f7b46736 100644 --- a/man/galamm-package.Rd +++ b/man/galamm-package.Rd @@ -15,9 +15,9 @@ Estimates generalized additive latent and mixed models using maximum marginal li \seealso{ Useful links: \itemize{ - \item \url{https://github.com/LCBC-UiO/galamm} - \item \url{https://lcbc-uio.github.io/galamm/} - \item Report bugs at \url{https://github.com/LCBC-UiO/galamm/issues} + \item \url{https://docs.ropensci.org/galamm/} + \item \url{https://github.com/ropensci/galamm} + \item Report bugs at \url{https://github.com/ropensci/galamm/issues} } } diff --git a/vignettes-raw/glmm_factor.Rmd b/vignettes-raw/glmm_factor.Rmd index a7a19d92..91613ba9 100644 --- a/vignettes-raw/glmm_factor.Rmd +++ b/vignettes-raw/glmm_factor.Rmd @@ -38,7 +38,7 @@ library(PLmixed) head(IRTsim) ``` -Each student is identified by a student id `sid`, and each school with a school id given by the `school` variable. For each student, five item measurements have been made. We assume that the student's performance depends both on the students ability as well as on the school the student attends. Having the outline of GALAMMs from the [introductory vignette](https://lcbc-uio.github.io/galamm/articles/galamm.html) in mind, we assume a binomial response model with a logit link, yielding for the $i$th measurement of the $j$th student in the $k$th school, +Each student is identified by a student id `sid`, and each school with a school id given by the `school` variable. For each student, five item measurements have been made. We assume that the student's performance depends both on the students ability as well as on the school the student attends. Having the outline of GALAMMs from the [introductory vignette](https://docs.ropensci.org/galamm/articles/galamm.html) in mind, we assume a binomial response model with a logit link, yielding for the $i$th measurement of the $j$th student in the $k$th school, $$ \text{P}(y_{ijk} = 1 | \mathbf{x}_{ijk}, \boldsymbol{\eta}_{jk}) = \frac{\exp(\nu_{ijk})}{1 + \exp(\nu_{ijk})} diff --git a/vignettes-raw/latent_observed_interaction.Rmd b/vignettes-raw/latent_observed_interaction.Rmd index ba433d6f..6b5cb8cb 100644 --- a/vignettes-raw/latent_observed_interaction.Rmd +++ b/vignettes-raw/latent_observed_interaction.Rmd @@ -25,7 +25,7 @@ knitr::opts_chunk$set( library(galamm) ``` -This vignette describes how `galamm` can be used to model interactions between latent and observed variables. The models described here can be considered extensions of the covariate measurement error model described in the [vignette on mixed response types](https://lcbc-uio.github.io/galamm/articles/mixed_response.html#covariate-measurement-error-model), by allowing the latent variables to interaction with observed variables. +This vignette describes how `galamm` can be used to model interactions between latent and observed variables. The models described here can be considered extensions of the covariate measurement error model described in the [vignette on mixed response types](https://docs.ropensci.org/galamm/articles/mixed_response.html#covariate-measurement-error-model), by allowing the latent variables to interaction with observed variables. ## Linear Mixed Model with Latent Covariates @@ -68,7 +68,7 @@ x \beta + \boldsymbol{\epsilon}. $$ -In this equation $\boldsymbol{\beta}_{0} \in \mathbb{R}^{3}$ is a vector of intercepts, $\eta$ is a latent variable, the loading of the latent variable onto the first measurement $y_{1}$ is fixed to 1 for identifiability, $\lambda_{2}$ is the loading of the latent variable onto the second measurement $y_{2}$, $\lambda_{3}$ is the main effect of the latent variable on the response of interest $y_{3}$, $\beta$ is the effect of the observed covariate $x$ on $y_{3}$, and $\lambda_{4}$ is the interaction effect of $x$ and $\eta$ on $y_{3}$. We assume that the residuals $\boldsymbol{\epsilon}$ are independently and identically normally distributed; this assumption is valid in this simulated case, but note that since the response $y_{3}$ is qualitatively different from the measurements $y_{1}$ and $y_{2}$, this assumption will in general not hold, and a [heteroscedastic measurement model](https://lcbc-uio.github.io/galamm/articles/lmm_heteroscedastic.html) should be used, or a [model with mixed response types](https://lcbc-uio.github.io/galamm/articles/mixed_response.html). For a more detailed explanation of this way of formulating latent variable models in matrix form we refer to the first four pages of @rockwoodEstimatingComplexMeasurement2019. +In this equation $\boldsymbol{\beta}_{0} \in \mathbb{R}^{3}$ is a vector of intercepts, $\eta$ is a latent variable, the loading of the latent variable onto the first measurement $y_{1}$ is fixed to 1 for identifiability, $\lambda_{2}$ is the loading of the latent variable onto the second measurement $y_{2}$, $\lambda_{3}$ is the main effect of the latent variable on the response of interest $y_{3}$, $\beta$ is the effect of the observed covariate $x$ on $y_{3}$, and $\lambda_{4}$ is the interaction effect of $x$ and $\eta$ on $y_{3}$. We assume that the residuals $\boldsymbol{\epsilon}$ are independently and identically normally distributed; this assumption is valid in this simulated case, but note that since the response $y_{3}$ is qualitatively different from the measurements $y_{1}$ and $y_{2}$, this assumption will in general not hold, and a [heteroscedastic measurement model](https://docs.ropensci.org/galamm/articles/lmm_heteroscedastic.html) should be used, or a [model with mixed response types](https://docs.ropensci.org/galamm/articles/mixed_response.html). For a more detailed explanation of this way of formulating latent variable models in matrix form we refer to the first four pages of @rockwoodEstimatingComplexMeasurement2019. The structural model is simply $\eta = \zeta \sim N(0, \psi)$, where $\psi$ is its variance. diff --git a/vignettes-raw/lmm_heteroscedastic.Rmd b/vignettes-raw/lmm_heteroscedastic.Rmd index fefbc643..b161dbe7 100644 --- a/vignettes-raw/lmm_heteroscedastic.Rmd +++ b/vignettes-raw/lmm_heteroscedastic.Rmd @@ -25,7 +25,7 @@ knitr::opts_chunk$set( library(galamm) ``` -At the moment, galamm supports group-wise heteroscedasticity in Gaussian response models. Referring to the model formulation outlined in the [introductory vignette](https://lcbc-uio.github.io/galamm/articles/galamm.html), the response model and nonlinear predictor can be easily combined in this particular case, to give +At the moment, galamm supports group-wise heteroscedasticity in Gaussian response models. Referring to the model formulation outlined in the [introductory vignette](https://docs.ropensci.org/galamm/articles/galamm.html), the response model and nonlinear predictor can be easily combined in this particular case, to give $$ y_{i} = \sum_{s=1}^{S} f_{s}\left(\mathbf{x}_{i}\right) + \sum_{l=2}^{L}\sum_{m=1}^{M_{l}} \eta_{m}^{(l)} \mathbf{z}^{(l)}_{im}{}^{'}\boldsymbol{\lambda}_{m}^{(l)} + \epsilon_{g(i)}, @@ -33,7 +33,7 @@ $$ where subscript $i$ refers to the $i$th elementary unit of observation, i.e., the $i$th row in the dataframe. $g(i)$ refers to the group to which the $i$th observation belongs, with each grouping having a separately estimated residual variance, $\epsilon_{g} \sim N(0, \sigma_{g}^{2})$. -In the future, we plan to also support other types of residual terms, including autocorrelation and residuals that depend on continuous variables. Such features are currently supported by the R packages [nlme](https://cran.r-project.org/package=nlme) [@pinheiroMixedEffectsModelsSPLUS2000], [mgcv](https://cran.r-project.org/package=mgcv) [@woodGeneralizedAdditiveModels2017], and [gamlss](https://cran.r-project.org/package=gamlss) [@rigbyGeneralizedAdditiveModels2005], however, of these only nlme provides computationally efficient estimation of mixed effects models with a large number of grouping levels, and only with strictly nested groups. If you are aware of other packages implementing such functionality, please [let us know](https://github.com/LCBC-UiO/galamm/issues). +In the future, we plan to also support other types of residual terms, including autocorrelation and residuals that depend on continuous variables. Such features are currently supported by the R packages [nlme](https://cran.r-project.org/package=nlme) [@pinheiroMixedEffectsModelsSPLUS2000], [mgcv](https://cran.r-project.org/package=mgcv) [@woodGeneralizedAdditiveModels2017], and [gamlss](https://cran.r-project.org/package=gamlss) [@rigbyGeneralizedAdditiveModels2005], however, of these only nlme provides computationally efficient estimation of mixed effects models with a large number of grouping levels, and only with strictly nested groups. If you are aware of other packages implementing such functionality, please [let us know](https://github.com/ropensci/galamm/issues). ## Group-Wise Heteroscedasticity diff --git a/vignettes-raw/mixed_response.Rmd b/vignettes-raw/mixed_response.Rmd index d02f6c8a..52004e76 100644 --- a/vignettes-raw/mixed_response.Rmd +++ b/vignettes-raw/mixed_response.Rmd @@ -36,7 +36,7 @@ We start with the `mresp` dataset, which comes with the package. The variable "i head(mresp) ``` -In terms of the GALAMM defined in the [introductory vignette](https://lcbc-uio.github.io/galamm/articles/galamm.html), and for simplicity assuming we use canonical link functions, we have the response model +In terms of the GALAMM defined in the [introductory vignette](https://docs.ropensci.org/galamm/articles/galamm.html), and for simplicity assuming we use canonical link functions, we have the response model $$ f\left(y_{ij} | \nu_{ij}, \phi\right) = \exp \left( \frac{y_{ij}\nu_{ij} - b\left(\nu_{ij}\right)}{\phi} + c\left(y_{ij}, \phi\right) \right) @@ -101,7 +101,7 @@ summary(mixed_resp) ### Mixed Response and Heteroscedastic Residuals -Mixed response models can be combined with heteroscedastic residuals, which are described in the vignette on [linear mixed models with heteroscedastic residuals](https://lcbc-uio.github.io/galamm/articles/lmm_heteroscedastic.html). However, some care is needed in this case. We illustrate with the dataset `mresp_hsced`, whose first few lines are shown below: +Mixed response models can be combined with heteroscedastic residuals, which are described in the vignette on [linear mixed models with heteroscedastic residuals](https://docs.ropensci.org/galamm/articles/lmm_heteroscedastic.html). However, some care is needed in this case. We illustrate with the dataset `mresp_hsced`, whose first few lines are shown below: ```{r} head(mresp_hsced) diff --git a/vignettes-raw/optimization.Rmd b/vignettes-raw/optimization.Rmd index aa6f7eb8..4d502f5a 100644 --- a/vignettes-raw/optimization.Rmd +++ b/vignettes-raw/optimization.Rmd @@ -39,7 +39,7 @@ At convergence, the Hessian matrix of second derivatives is computed exactly, ag ## Modifying the L-BFGS-B algorithm -We will illustrate some ways of modifying the optimization procedure with the covariate measurement model example shown in the [vignette on models with mixed response types](https://lcbc-uio.github.io/galamm/articles/mixed_response.html). Here we start by simply setting up what we need to fit the model. +We will illustrate some ways of modifying the optimization procedure with the covariate measurement model example shown in the [vignette on models with mixed response types](https://docs.ropensci.org/galamm/articles/mixed_response.html). Here we start by simply setting up what we need to fit the model. ```{r} loading_matrix <- matrix(c(1, 1, NA), ncol = 1) diff --git a/vignettes-raw/posterior_sampling.Rmd b/vignettes-raw/posterior_sampling.Rmd index 127eeffc..592b5613 100644 --- a/vignettes-raw/posterior_sampling.Rmd +++ b/vignettes-raw/posterior_sampling.Rmd @@ -27,7 +27,7 @@ library(galamm) Sampling from the empirical Bayes posterior distribution can be a convenient way of obtaining confidence bands for nonlinear functions of the estimated parameters. More background can be found in [this blog post by Gavin Simpson](https://fromthebottomoftheheap.net/2016/12/15/simultaneous-interval-revisited/) and in Section 6.10 of @woodGeneralizedAdditiveModels2017. -We start by fitting a semiparametric modeling with factor structures described in the vignette on [semiparametric latent variable modeling](https://lcbc-uio.github.io/galamm/articles/mixed_response.html). To make it more interesting we only keep the first 10 subjects. +We start by fitting a semiparametric modeling with factor structures described in the vignette on [semiparametric latent variable modeling](https://docs.ropensci.org/galamm/articles/mixed_response.html). To make it more interesting we only keep the first 10 subjects. ```{r} dat <- subset(cognition, domain == 1 & id <= 10) diff --git a/vignettes-raw/scaling.Rmd b/vignettes-raw/scaling.Rmd index 82fa6696..c02e77e0 100644 --- a/vignettes-raw/scaling.Rmd +++ b/vignettes-raw/scaling.Rmd @@ -36,7 +36,7 @@ n_replicates <- 20 ## Linear Mixed Models with Factor Structures -We start with the linear mixed model with factor structures described in [another vignette](https://lcbc-uio.github.io/galamm/articles/lmm_factor.html). Our goal here is to study how the computing time scales with the number of observations. +We start with the linear mixed model with factor structures described in [another vignette](https://docs.ropensci.org/galamm/articles/lmm_factor.html). Our goal here is to study how the computing time scales with the number of observations. ```{r} data(KYPSsim, package = "PLmixed") @@ -124,7 +124,7 @@ rm(all_sids, sim_params) ## Model with Group-Wise Heteroscedasticity -We now consider the model with group-wise heteroscedasticity consider in [the vignette on heteroscedastic linear mixed models](https://lcbc-uio.github.io/galamm/articles/lmm_heteroscedastic.html). +We now consider the model with group-wise heteroscedasticity consider in [the vignette on heteroscedastic linear mixed models](https://docs.ropensci.org/galamm/articles/lmm_heteroscedastic.html). There 1200 rows and 200 unique IDs in the dataset. We take subset of IDs, while keeping the remaining model structure unchanged. @@ -184,7 +184,7 @@ rm(all_ids, sim_params) ## Generalized Linear Mixed Models with Factor Structures -We now consider an example described in the [vignette on generalized linear mixed models with factor structures](https://lcbc-uio.github.io/galamm/articles/glmm_factor.html). +We now consider an example described in the [vignette on generalized linear mixed models with factor structures](https://docs.ropensci.org/galamm/articles/glmm_factor.html). ```{r} data(IRTsim, package = "PLmixed") @@ -255,7 +255,7 @@ rm(all_sids, sim_params) ## Semiparametric Model with Gaussian Responses -We can study the scaling issue further in semiparametric models with factor structures, which are described in [a separate vignette](https://lcbc-uio.github.io/galamm/articles/semiparametric.html). +We can study the scaling issue further in semiparametric models with factor structures, which are described in [a separate vignette](https://docs.ropensci.org/galamm/articles/semiparametric.html). The data for domain 1 has 4,800 rows and 200 unique IDs. diff --git a/vignettes-raw/semiparametric.Rmd b/vignettes-raw/semiparametric.Rmd index e888c6fb..a4743860 100644 --- a/vignettes-raw/semiparametric.Rmd +++ b/vignettes-raw/semiparametric.Rmd @@ -26,7 +26,7 @@ library(galamm) library(gamm4) ``` -This vignette describes how to use `galamm` to estimate latent variable models with smooth terms, or equivalently, generalized additive mixed models with factor structures. The examples are based on Section 4 and 5 in @sorensenLongitudinalModelingAgeDependent2023, but as we cannot share the data, we have instead simulated somewhat simpler datasets that will be used. We will gradually add complexity, starting with a simple generalized additive mixed model. Please refer to the [introductory vignette](https://lcbc-uio.github.io/galamm/articles/galamm.html) for an overview of the statistical models. +This vignette describes how to use `galamm` to estimate latent variable models with smooth terms, or equivalently, generalized additive mixed models with factor structures. The examples are based on Section 4 and 5 in @sorensenLongitudinalModelingAgeDependent2023, but as we cannot share the data, we have instead simulated somewhat simpler datasets that will be used. We will gradually add complexity, starting with a simple generalized additive mixed model. Please refer to the [introductory vignette](https://docs.ropensci.org/galamm/articles/galamm.html) for an overview of the statistical models. ## Generalized Additive Mixed Models @@ -58,7 +58,7 @@ for(i in unique(dat$id)) { points(dat$x, dat$y, pch = 20, lwd = .05) ``` -We use a generalized additive mixed model with random intercepts per subject to estimate the function relating $x$ to $y$. In terms of the model framework outlined in the [introductory vignette](https://lcbc-uio.github.io/galamm/articles/galamm.html), we model the $i$th response from the $j$th subject with +We use a generalized additive mixed model with random intercepts per subject to estimate the function relating $x$ to $y$. In terms of the model framework outlined in the [introductory vignette](https://docs.ropensci.org/galamm/articles/galamm.html), we model the $i$th response from the $j$th subject with $$ y_{ij} = f(x_{ij}) + \eta_{j} + \epsilon_{ij} diff --git a/vignettes/galamm.Rmd b/vignettes/galamm.Rmd index d95baa58..98bfff82 100644 --- a/vignettes/galamm.Rmd +++ b/vignettes/galamm.Rmd @@ -37,7 +37,7 @@ $$ f\left(y | \theta, \phi\right) = \exp \left( \frac{y\theta(\mu) - b\left(\theta(\mu)\right)}{\phi} + c\left(y, \phi\right) \right) $$ -here $\mu = g^{-1}(\nu)$ is the mean, $g^{-1}(\cdot)$ is the inverse of link function $g(\cdot)$, $\nu$ is a "nonlinear predictor", $\phi$ is a dispersion parameter, and $b(\cdot)$ and $c(\cdot)$ are known functions. In contrast to what is assumed, e.g., by [lme4](https://cran.r-project.org/package=lme4) [@batesFittingLinearMixedEffects2015], the functions $b(\cdot)$, $c(\cdot)$, and $g(\cdot)$ are allowed to vary between observations. That is, the observations can come from different members of the exponential family. The vignette on [models with mixed response types](https://lcbc-uio.github.io/galamm/articles/mixed_response.html) describes this in detail. +here $\mu = g^{-1}(\nu)$ is the mean, $g^{-1}(\cdot)$ is the inverse of link function $g(\cdot)$, $\nu$ is a "nonlinear predictor", $\phi$ is a dispersion parameter, and $b(\cdot)$ and $c(\cdot)$ are known functions. In contrast to what is assumed, e.g., by [lme4](https://cran.r-project.org/package=lme4) [@batesFittingLinearMixedEffects2015], the functions $b(\cdot)$, $c(\cdot)$, and $g(\cdot)$ are allowed to vary between observations. That is, the observations can come from different members of the exponential family. The vignette on [models with mixed response types](https://docs.ropensci.org/galamm/articles/mixed_response.html) describes this in detail. Using canonical link functions, the response model simplifies to @@ -113,12 +113,12 @@ We obtain maximum marginal likelihood estimates by maximizing $L\left(\boldsymbo To see how galamm is used in practice, take a look at the vignettes describing models with different components. -- [Linear mixed models with factor structures](https://lcbc-uio.github.io/galamm/articles/lmm_factor.html). -- [Generalized linear mixed models with factor structures](https://lcbc-uio.github.io/galamm/articles/glmm_factor.html). -- [Linear mixed models with heteroscedastic residuals](https://lcbc-uio.github.io/galamm/articles/lmm_heteroscedastic.html). -- [Models with interactions between latent and observed covariates](https://lcbc-uio.github.io/galamm/articles/latent_observed_interaction.html). -- [Mixed models with mixed response types](https://lcbc-uio.github.io/galamm/articles/mixed_response.html). -- [Generalized additive mixed models with factor structures](https://lcbc-uio.github.io/galamm/articles/semiparametric.html). +- [Linear mixed models with factor structures](https://docs.ropensci.org/galamm/articles/lmm_factor.html). +- [Generalized linear mixed models with factor structures](https://docs.ropensci.org/galamm/articles/glmm_factor.html). +- [Linear mixed models with heteroscedastic residuals](https://docs.ropensci.org/galamm/articles/lmm_heteroscedastic.html). +- [Models with interactions between latent and observed covariates](https://docs.ropensci.org/galamm/articles/latent_observed_interaction.html). +- [Mixed models with mixed response types](https://docs.ropensci.org/galamm/articles/mixed_response.html). +- [Generalized additive mixed models with factor structures](https://docs.ropensci.org/galamm/articles/semiparametric.html). # References diff --git a/vignettes/glmm_factor.Rmd b/vignettes/glmm_factor.Rmd index de179719..e67e19a9 100644 --- a/vignettes/glmm_factor.Rmd +++ b/vignettes/glmm_factor.Rmd @@ -40,7 +40,7 @@ head(IRTsim) #> 2.1 2 1 1 1 ``` -Each student is identified by a student id `sid`, and each school with a school id given by the `school` variable. For each student, five item measurements have been made. We assume that the student's performance depends both on the students ability as well as on the school the student attends. Having the outline of GALAMMs from the [introductory vignette](https://lcbc-uio.github.io/galamm/articles/galamm.html) in mind, we assume a binomial response model with a logit link, yielding for the $i$th measurement of the $j$th student in the $k$th school, +Each student is identified by a student id `sid`, and each school with a school id given by the `school` variable. For each student, five item measurements have been made. We assume that the student's performance depends both on the students ability as well as on the school the student attends. Having the outline of GALAMMs from the [introductory vignette](https://docs.ropensci.org/galamm/articles/galamm.html) in mind, we assume a binomial response model with a logit link, yielding for the $i$th measurement of the $j$th student in the $k$th school, $$ \text{P}(y_{ijk} = 1 | \mathbf{x}_{ijk}, \boldsymbol{\eta}_{jk}) = \frac{\exp(\nu_{ijk})}{1 + \exp(\nu_{ijk})} diff --git a/vignettes/latent_observed_interaction.Rmd b/vignettes/latent_observed_interaction.Rmd index e538b539..e26270e1 100644 --- a/vignettes/latent_observed_interaction.Rmd +++ b/vignettes/latent_observed_interaction.Rmd @@ -19,7 +19,7 @@ vignette: > library(galamm) ``` -This vignette describes how `galamm` can be used to model interactions between latent and observed variables. The models described here can be considered extensions of the covariate measurement error model described in the [vignette on mixed response types](https://lcbc-uio.github.io/galamm/articles/mixed_response.html#covariate-measurement-error-model), by allowing the latent variables to interaction with observed variables. +This vignette describes how `galamm` can be used to model interactions between latent and observed variables. The models described here can be considered extensions of the covariate measurement error model described in the [vignette on mixed response types](https://docs.ropensci.org/galamm/articles/mixed_response.html#covariate-measurement-error-model), by allowing the latent variables to interaction with observed variables. ## Linear Mixed Model with Latent Covariates @@ -70,7 +70,7 @@ x \beta + \boldsymbol{\epsilon}. $$ -In this equation $\boldsymbol{\beta}_{0} \in \mathbb{R}^{3}$ is a vector of intercepts, $\eta$ is a latent variable, the loading of the latent variable onto the first measurement $y_{1}$ is fixed to 1 for identifiability, $\lambda_{2}$ is the loading of the latent variable onto the second measurement $y_{2}$, $\lambda_{3}$ is the main effect of the latent variable on the response of interest $y_{3}$, $\beta$ is the effect of the observed covariate $x$ on $y_{3}$, and $\lambda_{4}$ is the interaction effect of $x$ and $\eta$ on $y_{3}$. We assume that the residuals $\boldsymbol{\epsilon}$ are independently and identically normally distributed; this assumption is valid in this simulated case, but note that since the response $y_{3}$ is qualitatively different from the measurements $y_{1}$ and $y_{2}$, this assumption will in general not hold, and a [heteroscedastic measurement model](https://lcbc-uio.github.io/galamm/articles/lmm_heteroscedastic.html) should be used, or a [model with mixed response types](https://lcbc-uio.github.io/galamm/articles/mixed_response.html). For a more detailed explanation of this way of formulating latent variable models in matrix form we refer to the first four pages of @rockwoodEstimatingComplexMeasurement2019. +In this equation $\boldsymbol{\beta}_{0} \in \mathbb{R}^{3}$ is a vector of intercepts, $\eta$ is a latent variable, the loading of the latent variable onto the first measurement $y_{1}$ is fixed to 1 for identifiability, $\lambda_{2}$ is the loading of the latent variable onto the second measurement $y_{2}$, $\lambda_{3}$ is the main effect of the latent variable on the response of interest $y_{3}$, $\beta$ is the effect of the observed covariate $x$ on $y_{3}$, and $\lambda_{4}$ is the interaction effect of $x$ and $\eta$ on $y_{3}$. We assume that the residuals $\boldsymbol{\epsilon}$ are independently and identically normally distributed; this assumption is valid in this simulated case, but note that since the response $y_{3}$ is qualitatively different from the measurements $y_{1}$ and $y_{2}$, this assumption will in general not hold, and a [heteroscedastic measurement model](https://docs.ropensci.org/galamm/articles/lmm_heteroscedastic.html) should be used, or a [model with mixed response types](https://docs.ropensci.org/galamm/articles/mixed_response.html). For a more detailed explanation of this way of formulating latent variable models in matrix form we refer to the first four pages of @rockwoodEstimatingComplexMeasurement2019. The structural model is simply $\eta = \zeta \sim N(0, \psi)$, where $\psi$ is its variance. diff --git a/vignettes/lmm_heteroscedastic.Rmd b/vignettes/lmm_heteroscedastic.Rmd index a34cf9fe..27c00b0e 100644 --- a/vignettes/lmm_heteroscedastic.Rmd +++ b/vignettes/lmm_heteroscedastic.Rmd @@ -19,7 +19,7 @@ vignette: > library(galamm) ``` -At the moment, galamm supports group-wise heteroscedasticity in Gaussian response models. Referring to the model formulation outlined in the [introductory vignette](https://lcbc-uio.github.io/galamm/articles/galamm.html), the response model and nonlinear predictor can be easily combined in this particular case, to give +At the moment, galamm supports group-wise heteroscedasticity in Gaussian response models. Referring to the model formulation outlined in the [introductory vignette](https://docs.ropensci.org/galamm/articles/galamm.html), the response model and nonlinear predictor can be easily combined in this particular case, to give $$ y_{i} = \sum_{s=1}^{S} f_{s}\left(\mathbf{x}_{i}\right) + \sum_{l=2}^{L}\sum_{m=1}^{M_{l}} \eta_{m}^{(l)} \mathbf{z}^{(l)}_{im}{}^{'}\boldsymbol{\lambda}_{m}^{(l)} + \epsilon_{g(i)}, @@ -27,7 +27,7 @@ $$ where subscript $i$ refers to the $i$th elementary unit of observation, i.e., the $i$th row in the dataframe. $g(i)$ refers to the group to which the $i$th observation belongs, with each grouping having a separately estimated residual variance, $\epsilon_{g} \sim N(0, \sigma_{g}^{2})$. -In the future, we plan to also support other types of residual terms, including autocorrelation and residuals that depend on continuous variables. Such features are currently supported by the R packages [nlme](https://cran.r-project.org/package=nlme) [@pinheiroMixedEffectsModelsSPLUS2000], [mgcv](https://cran.r-project.org/package=mgcv) [@woodGeneralizedAdditiveModels2017], and [gamlss](https://cran.r-project.org/package=gamlss) [@rigbyGeneralizedAdditiveModels2005], however, of these only nlme provides computationally efficient estimation of mixed effects models with a large number of grouping levels, and only with strictly nested groups. If you are aware of other packages implementing such functionality, please [let us know](https://github.com/LCBC-UiO/galamm/issues). +In the future, we plan to also support other types of residual terms, including autocorrelation and residuals that depend on continuous variables. Such features are currently supported by the R packages [nlme](https://cran.r-project.org/package=nlme) [@pinheiroMixedEffectsModelsSPLUS2000], [mgcv](https://cran.r-project.org/package=mgcv) [@woodGeneralizedAdditiveModels2017], and [gamlss](https://cran.r-project.org/package=gamlss) [@rigbyGeneralizedAdditiveModels2005], however, of these only nlme provides computationally efficient estimation of mixed effects models with a large number of grouping levels, and only with strictly nested groups. If you are aware of other packages implementing such functionality, please [let us know](https://github.com/ropensci/galamm/issues). ## Group-Wise Heteroscedasticity diff --git a/vignettes/mixed_response.Rmd b/vignettes/mixed_response.Rmd index 3d02ccce..cce9ebe0 100644 --- a/vignettes/mixed_response.Rmd +++ b/vignettes/mixed_response.Rmd @@ -38,7 +38,7 @@ head(mresp) #> 6 2 0.6924851 1.1750286 1.0000000 a ``` -In terms of the GALAMM defined in the [introductory vignette](https://lcbc-uio.github.io/galamm/articles/galamm.html), and for simplicity assuming we use canonical link functions, we have the response model +In terms of the GALAMM defined in the [introductory vignette](https://docs.ropensci.org/galamm/articles/galamm.html), and for simplicity assuming we use canonical link functions, we have the response model $$ f\left(y_{ij} | \nu_{ij}, \phi\right) = \exp \left( \frac{y_{ij}\nu_{ij} - b\left(\nu_{ij}\right)}{\phi} + c\left(y_{ij}, \phi\right) \right) @@ -139,7 +139,7 @@ summary(mixed_resp) ### Mixed Response and Heteroscedastic Residuals -Mixed response models can be combined with heteroscedastic residuals, which are described in the vignette on [linear mixed models with heteroscedastic residuals](https://lcbc-uio.github.io/galamm/articles/lmm_heteroscedastic.html). However, some care is needed in this case. We illustrate with the dataset `mresp_hsced`, whose first few lines are shown below: +Mixed response models can be combined with heteroscedastic residuals, which are described in the vignette on [linear mixed models with heteroscedastic residuals](https://docs.ropensci.org/galamm/articles/lmm_heteroscedastic.html). However, some care is needed in this case. We illustrate with the dataset `mresp_hsced`, whose first few lines are shown below: ``` r diff --git a/vignettes/optimization.Rmd b/vignettes/optimization.Rmd index 9304bbac..5494a96f 100644 --- a/vignettes/optimization.Rmd +++ b/vignettes/optimization.Rmd @@ -33,7 +33,7 @@ At convergence, the Hessian matrix of second derivatives is computed exactly, ag ## Modifying the L-BFGS-B algorithm -We will illustrate some ways of modifying the optimization procedure with the covariate measurement model example shown in the [vignette on models with mixed response types](https://lcbc-uio.github.io/galamm/articles/mixed_response.html). Here we start by simply setting up what we need to fit the model. +We will illustrate some ways of modifying the optimization procedure with the covariate measurement model example shown in the [vignette on models with mixed response types](https://docs.ropensci.org/galamm/articles/mixed_response.html). Here we start by simply setting up what we need to fit the model. ``` r diff --git a/vignettes/posterior_sampling.Rmd b/vignettes/posterior_sampling.Rmd index 9b2ee5f0..e049284f 100644 --- a/vignettes/posterior_sampling.Rmd +++ b/vignettes/posterior_sampling.Rmd @@ -21,7 +21,7 @@ library(galamm) Sampling from the empirical Bayes posterior distribution can be a convenient way of obtaining confidence bands for nonlinear functions of the estimated parameters. More background can be found in [this blog post by Gavin Simpson](https://fromthebottomoftheheap.net/2016/12/15/simultaneous-interval-revisited/) and in Section 6.10 of @woodGeneralizedAdditiveModels2017. -We start by fitting a semiparametric modeling with factor structures described in the vignette on [semiparametric latent variable modeling](https://lcbc-uio.github.io/galamm/articles/mixed_response.html). To make it more interesting we only keep the first 10 subjects. +We start by fitting a semiparametric modeling with factor structures described in the vignette on [semiparametric latent variable modeling](https://docs.ropensci.org/galamm/articles/mixed_response.html). To make it more interesting we only keep the first 10 subjects. ``` r diff --git a/vignettes/scaling.Rmd b/vignettes/scaling.Rmd index c4c3966c..c1a296ae 100644 --- a/vignettes/scaling.Rmd +++ b/vignettes/scaling.Rmd @@ -31,7 +31,7 @@ n_replicates <- 20 ## Linear Mixed Models with Factor Structures -We start with the linear mixed model with factor structures described in [another vignette](https://lcbc-uio.github.io/galamm/articles/lmm_factor.html). Our goal here is to study how the computing time scales with the number of observations. +We start with the linear mixed model with factor structures described in [another vignette](https://docs.ropensci.org/galamm/articles/lmm_factor.html). Our goal here is to study how the computing time scales with the number of observations. ``` r @@ -128,7 +128,7 @@ abline(fit) ## Model with Group-Wise Heteroscedasticity -We now consider the model with group-wise heteroscedasticity consider in [the vignette on heteroscedastic linear mixed models](https://lcbc-uio.github.io/galamm/articles/lmm_heteroscedastic.html). +We now consider the model with group-wise heteroscedasticity consider in [the vignette on heteroscedastic linear mixed models](https://docs.ropensci.org/galamm/articles/lmm_heteroscedastic.html). There 1200 rows and 200 unique IDs in the dataset. We take subset of IDs, while keeping the remaining model structure unchanged. @@ -194,7 +194,7 @@ abline(fit) ## Generalized Linear Mixed Models with Factor Structures -We now consider an example described in the [vignette on generalized linear mixed models with factor structures](https://lcbc-uio.github.io/galamm/articles/glmm_factor.html). +We now consider an example described in the [vignette on generalized linear mixed models with factor structures](https://docs.ropensci.org/galamm/articles/glmm_factor.html). ``` r @@ -272,7 +272,7 @@ We speculate that this is caused by the fact that for non-Gaussian models, a pen ## Semiparametric Model with Gaussian Responses -We can study the scaling issue further in semiparametric models with factor structures, which are described in [a separate vignette](https://lcbc-uio.github.io/galamm/articles/semiparametric.html). +We can study the scaling issue further in semiparametric models with factor structures, which are described in [a separate vignette](https://docs.ropensci.org/galamm/articles/semiparametric.html). The data for domain 1 has 4,800 rows and 200 unique IDs. diff --git a/vignettes/semiparametric.Rmd b/vignettes/semiparametric.Rmd index ef40b457..c0eb2acc 100644 --- a/vignettes/semiparametric.Rmd +++ b/vignettes/semiparametric.Rmd @@ -20,7 +20,7 @@ library(galamm) library(gamm4) ``` -This vignette describes how to use `galamm` to estimate latent variable models with smooth terms, or equivalently, generalized additive mixed models with factor structures. The examples are based on Section 4 and 5 in @sorensenLongitudinalModelingAgeDependent2023, but as we cannot share the data, we have instead simulated somewhat simpler datasets that will be used. We will gradually add complexity, starting with a simple generalized additive mixed model. Please refer to the [introductory vignette](https://lcbc-uio.github.io/galamm/articles/galamm.html) for an overview of the statistical models. +This vignette describes how to use `galamm` to estimate latent variable models with smooth terms, or equivalently, generalized additive mixed models with factor structures. The examples are based on Section 4 and 5 in @sorensenLongitudinalModelingAgeDependent2023, but as we cannot share the data, we have instead simulated somewhat simpler datasets that will be used. We will gradually add complexity, starting with a simple generalized additive mixed model. Please refer to the [introductory vignette](https://docs.ropensci.org/galamm/articles/galamm.html) for an overview of the statistical models. ## Generalized Additive Mixed Models @@ -64,7 +64,7 @@ points(dat$x, dat$y, pch = 20, lwd = .05) ![Plot of data for domain 1 and item 11.](semiparametric-spaghetti-plot-1.png) -We use a generalized additive mixed model with random intercepts per subject to estimate the function relating $x$ to $y$. In terms of the model framework outlined in the [introductory vignette](https://lcbc-uio.github.io/galamm/articles/galamm.html), we model the $i$th response from the $j$th subject with +We use a generalized additive mixed model with random intercepts per subject to estimate the function relating $x$ to $y$. In terms of the model framework outlined in the [introductory vignette](https://docs.ropensci.org/galamm/articles/galamm.html), we model the $i$th response from the $j$th subject with $$ y_{ij} = f(x_{ij}) + \eta_{j} + \epsilon_{ij}