📝 Update README

.Rbuildignore

@@ -6,3 +6,4 @@
 ^README\.Rmd$
 ^vignettes/articles$
 ^\.github$
+^LATER\.bib$

LATER.bib

@@ -0,0 +1,64 @@
+
+@article{noorani_later_2016,
+	title = {The {LATER} model of reaction time and decision},
+	volume = {64},
+	issn = {0149-7634},
+	url = {https://www.sciencedirect.com/science/article/pii/S0149763415301226},
+	doi = {10.1016/j.neubiorev.2016.02.018},
+	abstract = {How do we choose one option rather than another when faced with uncertainty about the information we receive, and the consequences of what we decide? The LATER (Linear Approach to Threshold with Ergodic Rate) model has proved to be remarkably accurate in predicting how we respond in such situations. Given its conceptual simplicity, its grounding in fundamental Bayesian principles and its very few free parameters, it is being increasingly adopted for a wider range of choice tasks, helping us to understand the underlying neural mechanisms, and in applying this to clinical disorders. Here, we provide a thorough discussion of the history behind this model, and how it can be applied to more complex decisions, including anti-saccades, Go-NoGo, countermanding and other situations where newly-arriving information means that ongoing decisions must be modified. The neuroscience of decision-making is progressing rapidly, and we anticipate that wider understanding and application of this model will help simplify the interpretation of increasingly advanced decision behaviour both in the laboratory and clinic.},
+	urldate = {2024-03-01},
+	journal = {Neuroscience \& Biobehavioral Reviews},
+	author = {Noorani, Imran and Carpenter, R. H. S.},
+	month = may,
+	year = {2016},
+	keywords = {Bayes, Decision, Latency, LATER, Reaction time, Saccade, Wheeless},
+	pages = {229--251},
+	file = {ScienceDirect Snapshot:C\:\\Users\\mquiroga\\Zotero\\storage\\6SZPY38U\\S0149763415301226.html:text/html},
+}
+
+@article{carpenter_eye_1981,
+	title = {Eye movements: {Cognition} and visual perception},
+	volume = {237},
+	journal = {Oculomotor procrastination (Fisher DF, Monty RA, Senders JW, eds) pp},
+	author = {Carpenter, RHS},
+	year = {1981},
+	pages = {246},
+}
+
+@article{carpenter_neural_1995,
+	title = {Neural computation of log likelihood in control of saccadic eye movements},
+	volume = {377},
+	copyright = {1995 Springer Nature Limited},
+	issn = {1476-4687},
+	url = {https://www.nature.com/articles/377059a0},
+	doi = {10.1038/377059a0},
+	abstract = {THE latency between the appearance of a visual target and the start of the saccadic eye movement made to look at it varies from trial to trial to an extent that is inexplicable in terms of ordinary 'physiological' processes such as synaptic delays and conduction velocities. An alternative interpretation is that it represents the time needed to decide whether a target is in fact present: decision processes are necessarily stochastic, because they depend on extracting information from noisy sensory signals1. In one such model2, the presence of a target causes a signal in a decision unit to rise linearly at a rate r from its initial value s0 until it reaches a fixed threshold 0, when a saccade is initiated. One can regard this decision signal as a neural estimate of the log likelihood of the hypothesis that the target is present, the threshold being the significance criterion or likelihood level at which the target is presumed to be present. Experiments manipulating the prior probability of the target's appearing confirm this notion: the latency distribution then changes in the way expected if s0 simply reflects the prior log likelihood of the stimulus.},
+	language = {en},
+	number = {6544},
+	urldate = {2024-03-01},
+	journal = {Nature},
+	author = {Carpenter, R. H. S. and Williams, M. L. L.},
+	month = sep,
+	year = {1995},
+	note = {Publisher: Nature Publishing Group},
+	keywords = {Humanities and Social Sciences, multidisciplinary, Science},
+	pages = {59--62},
+	file = {Full Text PDF:C\:\\Users\\mquiroga\\Zotero\\storage\\225ED29B\\Carpenter and Williams - 1995 - Neural computation of log likelihood in control of.pdf:application/pdf},
+}
+
+@article{reddi_accuracy_2003,
+	title = {Accuracy, information, and response time in a saccadic decision task},
+	volume = {90},
+	issn = {0022-3077},
+	doi = {10.1152/jn.00689.2002},
+	abstract = {Reaction times generally follow a simple law economically described by the LATER model, in which a decision signal rises linearly in response to information about a target to a threshold at which a response is initiated, at a rate that varies from trial to trial with a Gaussian distribution. Functionally, LATER may be regarded as an ideal decision mechanism incorporating prior probability, information, and criterion level or urgency; this can be tested quantitatively by seeing whether LATER accurately predicts the effects on latency distributions of manipulating these variables: in this case, information and urgency. We presented subjects with random-dot kinematograms while fixating a central LED. The information content of the display was varied by altering the proportion of the dots moving coherently together either left or right rather than randomly. As soon as subjects detected the direction of coherent movement, they made a saccade in the same direction to one of a pair of LEDs on each side of the fixation target. Subjects responded either carefully, taking time to ensure an accurate judgement, or more hastily and with less regard for accuracy. The distributions of latencies under the different combinations of conditions were found to conform to LATER's predictions. Providing more information or increasing urgency both reduce latency; but they alter the observed distributions in different ways, equivalent to increasing the mean rate of rise on the one hand or reducing the criterion level on the other. Making only simple assumptions about the underlying mechanisms, the observed changes can be accounted for quantitatively.},
+	language = {eng},
+	number = {5},
+	journal = {Journal of Neurophysiology},
+	author = {Reddi, B. a. J. and Asrress, K. N. and Carpenter, R. H. S.},
+	month = nov,
+	year = {2003},
+	pmid = {12815017},
+	keywords = {Decision Making, Humans, Reaction Time, Saccades, Statistics, Nonparametric},
+	pages = {3538--3546},
+}

README.Rmd

@@ -1,5 +1,6 @@
 ---
 output: github_document
+bibliography: LATER.bib
 ---
 
 <!-- README.md is generated from README.Rmd. Please edit that file -->
@@ -19,7 +20,16 @@ knitr::opts_chunk$set(
 [![R-CMD-check](https://github.com/unimelbmdap/LATERmodel/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/unimelbmdap/LATERmodel/actions/workflows/R-CMD-check.yaml)
 <!-- badges: end -->
 
-The goal of LATERmodel is to make the 
+The LATERmodel R package is an open-source implementation of Roger Carpenter's 
+Linear Approach to Threshold with Ergodic Rate (LATER) model 
+(@carpenter_eye_1981, @noorani_later_2016). This package enables the easy 
+visualisation of reaction time data in LATER's signature reciprobit space, as 
+well as estimating parameters to fit the model to datasets, comparing raw 
+datasets, comparing fits (i.e., is the dataset better explained by a shift or a 
+swivel?), adding an early component, etc.
+
+This package also includes two canonical datasets digitised from 
+@carpenter_neural_1995 and @reddi_accuracy_2003.
 
 ## Installation
 
@@ -32,22 +42,39 @@ devtools::install_github("unimelbmdap/LATERmodel")
 
 ## Example
 
-Load digitised data from Figure 1 in Carpenter and Williams (1995)
+Load digitised data from Figure 1 in Carpenter and Williams (1995):
 
 ```{r example}
 library(LATERmodel)
 
 data(carpenter_williams_1995)
 ```
 
-Figure 1a
-```{r fig1a}
-a <- prepare_data(dplyr::filter(carpenter_williams_1995, participant == "a"))
-reciprobit_plot(a)
+Extract data corresponding only to participant `a` (Figure 1.a):
+
+```{r}
+raw_data <- subset(carpenter_williams_1995, participant == "a")
+```
+
+The data analysis functions within this package require the raw data to first 
+undergo pre-processing using the `prepare_data` function.
+We pass our `raw_data` variable as the argument to the `raw_data` parameter 
+of `prepare_data` to perform such pre-processing:
+
+```{r}
+data <- prepare_data(raw_data = raw_data)
+```
+
+
+Fit each condition individually (no shared parameters between them), and 
+include an early component for all of them:
+
+```{r}
+data_fit <- individual_later_fit(data, with_early_component = TRUE)
 ```
 
-Figure 1b
-```{r fig1b}
-b <- prepare_data(dplyr::filter(carpenter_williams_1995, participant == "b"))
-reciprobit_plot(b)
+Visualise the raw data and the best individual fits:
+
+```{r}
+reciprobit_plot(data, data_fit)
 ```

README.md

@@ -4,9 +4,22 @@
 # LATERmodel
 
 <!-- badges: start -->
+
+[![R-CMD-check](https://github.com/unimelbmdap/LATERmodel/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/unimelbmdap/LATERmodel/actions/workflows/R-CMD-check.yaml)
 <!-- badges: end -->
 
-The goal of LATERmodel is to make the
+The LATERmodel R package is an open-source implementation of Roger
+Carpenter’s Linear Approach to Threshold with Ergodic Rate (LATER) model
+(R. Carpenter (1981), Noorani and Carpenter (2016)). This package
+enables the easy visualisation of reaction time data in LATER’s
+signature reciprobit space, as well as estimating parameters to fit the
+model to datasets, comparing raw datasets, comparing fits (i.e., is the
+dataset better explained by a shift or a swivel?), adding an early
+component, etc.
+
+This package also includes two canonical datasets digitised from R. H.
+S. Carpenter and Williams (1995) and Reddi, Asrress, and Carpenter
+(2003).
 
 ## Installation
 
@@ -20,28 +33,77 @@ devtools::install_github("unimelbmdap/LATERmodel")
 
 ## Example
 
-Load digitised data from Figure 1 in Carpenter and Williams (1995)
+Load digitised data from Figure 1 in Carpenter and Williams (1995):
 
 ``` r
 library(LATERmodel)
 
 data(carpenter_williams_1995)
 ```
 
-Figure 1a
+Extract data corresponding only to participant `a` (Figure 1.a):
+
+``` r
+raw_data <- subset(carpenter_williams_1995, participant == "a")
+```
+
+The data analysis functions within this package require the raw data to
+first undergo pre-processing using the `prepare_data` function. We pass
+our `raw_data` variable as the argument to the `raw_data` parameter of
+`prepare_data` to perform such pre-processing:
 
 ``` r
-a <- prepare_data(dplyr::filter(carpenter_williams_1995, participant == "a"))
-reciprobit_plot(a)
+data <- prepare_data(raw_data = raw_data)
 ```
 
-<img src="man/figures/README-fig1a-1.png" width="100%" />
+Fit each condition individually (no shared parameters between them), and
+include an early component for all of them:
 
-Figure 1b
+``` r
+data_fit <- individual_later_fit(data, with_early_component = TRUE)
+```
+
+Visualise the raw data and the best individual fits:
 
 ``` r
-b <- prepare_data(dplyr::filter(carpenter_williams_1995, participant == "b"))
-reciprobit_plot(b)
+reciprobit_plot(data, data_fit)
 ```
 
-<img src="man/figures/README-fig1b-1.png" width="100%" />
+<img src="man/figures/README-unnamed-chunk-5-1.png" width="100%" />
+
+<div id="refs" class="references csl-bib-body hanging-indent">
+
+<div id="ref-carpenter_neural_1995" class="csl-entry">
+
+Carpenter, R. H. S., and M. L. L. Williams. 1995. “Neural Computation of
+Log Likelihood in Control of Saccadic Eye Movements.” *Nature* 377
+(6544): 59–62. <https://doi.org/10.1038/377059a0>.
+
+</div>
+
+<div id="ref-carpenter_eye_1981" class="csl-entry">
+
+Carpenter, RHS. 1981. “Eye Movements: Cognition and Visual Perception.”
+*Oculomotor Procrastination (Fisher DF, Monty RA, Senders JW, Eds) Pp*
+237: 246.
+
+</div>
+
+<div id="ref-noorani_later_2016" class="csl-entry">
+
+Noorani, Imran, and R. H. S. Carpenter. 2016. “The LATER Model of
+Reaction Time and Decision.” *Neuroscience & Biobehavioral Reviews* 64
+(May): 229–51. <https://doi.org/10.1016/j.neubiorev.2016.02.018>.
+
+</div>
+
+<div id="ref-reddi_accuracy_2003" class="csl-entry">
+
+Reddi, B. a. J., K. N. Asrress, and R. H. S. Carpenter. 2003. “Accuracy,
+Information, and Response Time in a Saccadic Decision Task.” *Journal of
+Neurophysiology* 90 (5): 3538–46.
+<https://doi.org/10.1152/jn.00689.2002>.
+
+</div>
+
+</div>