Merge branch '59-add-imm-vignette' of https://github.com/venpopov/bmm …

…into 59-add-imm-vignette

.Rbuildignore

@@ -9,3 +9,6 @@
 ^_pkgdown\.yml$
 ^docs$
 ^pkgdown$
+^vignettes/articles$
+^doc$
+^Meta$

.github/workflows/R-CMD-check.yaml

@@ -0,0 +1,47 @@
+# 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: [master, develop]
+  pull_request:
+    branches: [master, develop]
+
+name: R-CMD-check
+
+jobs:
+  R-CMD-check:
+    runs-on: ${{ matrix.config.os }}
+
+    name: ${{ matrix.config.os }} (${{ matrix.config.r }})
+
+    strategy:
+      fail-fast: false
+      matrix:
+        config:
+          - {os: macos-latest,   r: 'release'}
+          - {os: windows-latest, r: 'release'}
+          - {os: ubuntu-latest,   r: 'release'}
+
+    env:
+      GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
+      R_KEEP_PKG_SOURCE: yes
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: r-lib/actions/setup-pandoc@v2
+
+      - uses: r-lib/actions/setup-r@v2
+        with:
+          r-version: ${{ matrix.config.r }}
+          http-user-agent: ${{ matrix.config.http-user-agent }}
+          use-public-rspm: true
+
+      - uses: r-lib/actions/setup-r-dependencies@v2
+        with:
+          extra-packages: any::rcmdcheck
+          needs: check
+
+      - uses: r-lib/actions/check-r-package@v2
+        with:
+          upload-snapshots: true

.github/workflows/pkgdown.yaml

@@ -2,9 +2,9 @@
 # Need help debugging build failures? Start at https://github.com/r-lib/actions#where-to-find-help
 on:
   push:
-    branches: [main, master]
+    branches: [master, develop]
   pull_request:
-    branches: [main, master]
+    branches: [master]
   release:
     types: [published]
   workflow_dispatch:

.github/workflows/test-coverage.yaml

@@ -0,0 +1,50 @@
+# 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: [master, develop]
+  pull_request:
+    branches: [master, develop]
+
+name: test-coverage
+
+jobs:
+  test-coverage:
+    runs-on: ubuntu-latest
+    env:
+      GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: r-lib/actions/setup-r@v2
+        with:
+          use-public-rspm: true
+
+      - uses: r-lib/actions/setup-r-dependencies@v2
+        with:
+          extra-packages: any::covr
+          needs: coverage
+
+      - name: Test coverage
+        run: |
+          covr::codecov(
+            quiet = FALSE,
+            clean = FALSE,
+            install_path = file.path(normalizePath(Sys.getenv("RUNNER_TEMP"), winslash = "/"), "package")
+          )
+        shell: Rscript {0}
+
+      - name: Show testthat output
+        if: always()
+        run: |
+          ## --------------------------------------------------------------------
+          find ${{ runner.temp }}/package -name 'testthat.Rout*' -exec cat '{}' \; || true
+        shell: bash
+
+      - name: Upload test results
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-test-failures
+          path: ${{ runner.temp }}/package

.gitignore

@@ -6,3 +6,5 @@
 local/
 docs
 inst/doc
+/doc/
+/Meta/

DESCRIPTION

@@ -21,7 +21,10 @@ Suggests:
     rmarkdown,
     bookdown,
     tidybayes,
-    ggplot2
+    ggplot2,
+    mixtur,
+    ggthemes,
+    cowplot
 Config/testthat/edition: 3
 Imports: 
     brms,

R/bmm_model_sdmSimple.R

@@ -28,7 +28,9 @@
 # automatically based on the information in the .model_sdmSimple()$info
 #' @title `r .model_sdmSimple()$info$name`
 #' @name SDM
-#' @details `r model_info(sdmSimple())`
+#' @details
+#' see `vignette("sdm-simple")` for a detailed description of the model and how to use it.
+#' `r model_info(sdmSimple())`
 #' @param ... used internally for testing, ignore it
 #' @return An object of class `bmmmodel`
 #' @export

R/distributions.R

@@ -16,7 +16,7 @@
 #' @param kappa Vector of precision values
 #' @param log Logical; if `TRUE`, values are returned on the log scale.
 #' @param parametrization Character; either `"bessel"` or `"sqrtexp"`
-#'   (default). See `vignette("bmm_models")` for details on the
+#'   (default). See `vignette("sdm-simple")` for details on the
 #'   parameterization.
 #' @param log.p Logical; if `TRUE`, probabilities are returned on the log
 #'   scale.

R/helpers-parameters.R

@@ -42,7 +42,7 @@ k2sd <- function (K) {
 #'   `c_sqrtexp2bessel` converts from the sqrtexp parametrization to the
 #'   bessel parametrization.
 #' @keywords transform
-#' @details See `vignette("bmm_models")` for details on the
+#' @details See `vignette("sdm-simple")` for details on the
 #'   parameterization. The sqrtexp parametrization is the default in the
 #'   `bmm` package.
 #' @export

README.Rmd

@@ -10,7 +10,10 @@ knitr::opts_chunk$set(
   out.width = "100%"
 )
 ```
-# bmm <!-- badges: start --> <!-- badges: end --> 
+# bmm   <!-- badges: start -->
+  [![R-CMD-check](https://github.com/venpopov/bmm/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/venpopov/bmm/actions/workflows/R-CMD-check.yaml)
+  [![test-coverage](https://github.com/venpopov/bmm/actions/workflows/test-coverage.yaml/badge.svg)](https://github.com/venpopov/bmm/actions/workflows/test-coverage.yaml)
+<!-- badges: end -->
 
 The goal of bmm (Bayesian Measurement Models) is to make it easier to estimate 
 common measurement models for behavioral research using Bayesian hierarhical 

README.md

@@ -1,7 +1,11 @@
 
 <!-- README.md is generated from README.Rmd. Please edit that file -->
 
-# bmm <!-- badges: start --> <!-- badges: end -->
+# bmm <!-- badges: start -->
+
+[![R-CMD-check](https://github.com/venpopov/bmm/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/venpopov/bmm/actions/workflows/R-CMD-check.yaml)
+[![test-coverage](https://github.com/venpopov/bmm/actions/workflows/test-coverage.yaml/badge.svg)](https://github.com/venpopov/bmm/actions/workflows/test-coverage.yaml)
+<!-- badges: end -->
 
 The goal of bmm (Bayesian Measurement Models) is to make it easier to
 estimate common measurement models for behavioral research using
@@ -76,13 +80,13 @@ library(bmm)
 library(tidyverse)
 dat <- gen_3p_data(N=2000, pmem=0.6, pnt=0.3, kappa=10, setsize=4, relative_resp=T)
 head(dat)
-#>              y    nt1_loc    nt2_loc   nt3_loc
-#> 1 -0.142526610  2.1500293 -0.6441928 0.9517516
-#> 2  0.007518355 -3.0287546 -2.9828635 2.0714670
-#> 3  0.018662539 -1.3783199  1.0946707 1.2723605
-#> 4 -0.004285611  1.7142538 -1.8425466 0.7009981
-#> 5  0.396037655 -0.7615063  1.6378873 2.8464744
-#> 6 -0.411727832 -0.9225579  2.5400559 3.0250659
+#>             y    nt1_loc     nt2_loc    nt3_loc
+#> 1  0.51775824  1.0020511  0.76339413 -1.2897954
+#> 2  0.03960327 -0.6206519  1.09208784 -0.8679937
+#> 3 -0.48213423  1.1447270  2.81885045 -1.4363374
+#> 4 -0.34510101  2.7482095 -0.06612305  2.0340003
+#> 5  0.09348744 -1.3952246  2.17738363  0.7796131
+#> 6  0.39001975 -0.8049496  2.07371921 -1.1887811
 ```
 
 We have a dataset of 2000 observations of response error, of which 60%

vignettes/REFERENCES.bib

@@ -1,10 +1,75 @@
- @article{Oberauer_2023, address={US}, title={Measurement models for visual working memory—A factorial model comparison}, volume={130}, ISSN={1939-1471}, DOI={10.1037/rev0000328}, number={3}, journal={Psychological Review}, publisher={American Psychological Association}, author={Oberauer, Klaus}, year={2023}, pages={841–852} }
-
+@article{Oberauer_2023,
+	title        = {Measurement models for visual working memory—A factorial model comparison},
+	author       = {Oberauer, Klaus},
+	year         = 2023,
+	journal      = {Psychological Review},
+	publisher    = {American Psychological Association},
+	address      = {US},
+	volume       = 130,
+	number       = 3,
+	pages        = {841–852},
+	doi          = {10.1037/rev0000328},
+	issn         = {1939-1471}
+}
 @misc{abramowitz1988handbook,
-  title={Handbook of mathematical functions with formulas, graphs, and mathematical tables},
-  author={Abramowitz, Milton and Stegun, Irene A and Romer, Robert H},
-  year={1988},
-  publisher={American Association of Physics Teachers}
+	title        = {Handbook of mathematical functions with formulas, graphs, and mathematical tables},
+	author       = {Abramowitz, Milton and Stegun, Irene A and Romer, Robert H},
+	year         = 1988,
+	publisher    = {American Association of Physics Teachers}
+}
+@article{Zhang_Luck_2008,
+	title        = {Discrete fixed-resolution representations in visual working memory},
+	author       = {Zhang, Weiwei and Luck, Steven J.},
+	year         = 2008,
+	journal      = {Nature},
+	volume       = 453,
+	number       = 7192,
+	pages        = {233–235},
+	doi          = {10.1038/nature06860},
+	issn         = {0028-0836},
+	rights       = {© 2008 Nature Publishing Group},
+	language     = {en}
+}
+@article{Bays_Catalao_Husain_2009,
+	title        = {The precision of visual working memory is set by allocation of a shared resource},
+	author       = {Bays, Paul M. and Catalao, Raquel F. G. and Husain, Masud},
+	year         = 2009,
+	journal      = {Journal of Vision},
+	volume       = 9,
+	number       = 10,
+	pages        = {7–7},
+	doi          = {10.1167/9.10.7},
+	issn         = {1534-7362},
+	language     = {en}
+}
+@article{Wilken_Ma_2004,
+	title        = {A detection theory account of change detection},
+	author       = {Wilken, Patrick and Ma, Wei Ji},
+	year         = 2004,
+	journal      = {Journal of vision},
+	volume       = 4,
+	number       = 12,
+	pages        = {11–11}
+}
+@article{Bays_Gorgoraptis_Wee_Marshall_Husain_2011,
+	title        = {Temporal dynamics of encoding, storage, and reallocation of visual working memory},
+	author       = {Bays, Paul M. and Gorgoraptis, Nikos and Wee, Natalie and Marshall, Louise and Husain, Masud},
+	year         = 2011,
+	journal      = {Journal of vision},
+	volume       = 11,
+	number       = 10,
+	pages        = {6–6}
+}
+@article{Oberauer_Lin_2017,
+	title        = {An interference model of visual working memory.},
+	author       = {Oberauer, Klaus and Lin, Hsuan-Yu},
+	year         = 2017,
+	journal      = {Psychological Review},
+	volume       = 124,
+	number       = 1,
+	pages        = {21–59},
+	doi          = {10.1037/rev0000044},
+	language     = {en}
 }
 
 @article{oberauerHierarchicalBayesianMeasurement2017,

vignettes/articles/vwm-crt.Rmd

@@ -0,0 +1,70 @@
+---
+title: "Continuous reproduction tasks (CRT)"
+output: 
+  bookdown::html_document2:
+    keep_md: true
+bibliography: ../REFERENCES.bib
+pkgdown:
+  as_is: true
+---
+
+```{=html}
+<style type="text/css">
+  div.main-container {
+    max-width: 800px !important;
+  }
+  
+  p {
+    margin-top: 1.5em ;
+    margin-bottom: 1.5em ;
+  }
+</style>
+```
+```{r, include = FALSE}
+knitr::opts_chunk$set(
+  collapse = TRUE,
+  comment = "#>"
+)
+```
+
+# Task description
+
+In research on visual working memory participants are often asked to remember and reproduce continuous features of visual objects such as their color or orientation. In the continuous reproduction task (sometimes also called delayed estimation task), participants encode a set of visual objects into visual working memory and are then asked to reproduce a specific feature of one cued object on a continuous scale at test (see Figure \@ref(fig:vwmcrt) for an illustration). 
+
+Most often the features used in these tasks are colors sampled from a color wheel [@Wilken_Ma_2004] or continuous orientations of a bar or a triangle [@Bays_Gorgoraptis_Wee_Marshall_Husain_2011]. The set of to-be-remembered objects typically consists of one up to eight objects spatially distributed over the screen. Thus, participants must associate the to-be-remembered features (e.g. color or orientation) with the spatial locations they are presented at. The precision of the representation of an object’s feature in visual working memory is measured as the angular deviation from the true feature presented at encoding.
+
+```{r vwmcrt, echo=F, fig.cap="A typical continuous reproduction task", out.width=450}
+knitr::include_graphics("vwm-crt.png")
+```
+
+# The role of measurement models
+
+In these continuous reproduction tasks, the simplest measure of performance is the average angle deviation of the response from the true feature value. In many studies, this average recall error has been the main dependent variable for evaluating the effect of experimental manipulations. Yet, the average recall error confounds different properties of memory representations and does not sufficiently represent the theoretical processes assumed by current models of visual working memory. Therefore, different measurement models have been proposed to formalize distinct aspects of visual working memory models and how they translate into observed behavior.
+
+A measurement model is a statistical model that describes the relationship between latent cognitive processes and observed behavior. For continuous reproduction tasks, measurement models provide a more refined representation of memory processes because they decompose the average recall error into several theoretically meaningful parameters.
+
+At the core of these models is the assumption that responses in continuous reproduction tasks can stem from different distributions depending on the continuous activation of different memory representation or the cognitive state a person is in at recall.
+
+# CRT Models in the `bmm` package
+
+The `bmm` package implements several measurement models for analyzing continuous reproduction data:
+
+#### The two-parameter mixture model [@Zhang_Luck_2008] {.unnumbered}
+
+  - see `?mixture2p` and `vignette("mixture_models")`
+
+#### The three-parameter mixture model [@Bays_Catalao_Husain_2009] {.unnumbered}
+
+  - see `?mixture3p` and `vignette("mixture_models")`
+
+#### The Interference Measurement Model [@Oberauer_Lin_2017]  {.unnumbered}
+
+  - see `?IMM` and `vignette("imm")`
+
+#### The Signal Discrimination Model (SDM) by [@Oberauer_2023]  {.unnumbered}
+
+  - see `?sdmSimple` and `vignette("sdm-simple")`
+
+
+# References
+