largescaledesigned.qmd

---
fig-width: 4
fig-height: 3
fig-dpi: 150
fig-format: png
engine: julia
julia:
  exeflags: ["--project"]
---

# A large-scale designed experiment {#sec-largescaledesigned}

Load the packages to be used

```{julia}
#| code-fold: true
#| output: false
#| label: packages04
using AlgebraOfGraphics
using Arrow
using CairoMakie
using Chain
using DataFrameMacros
using DataFrames
using Effects
using EmbraceUncertainty: dataset
using LinearAlgebra
using MixedModels
using MixedModelsMakie
using StandardizedPredictors
using StatsBase
```

and define some constants, if not already defined.

```{julia}
#| code-fold: true
#| output: false
#| label: constants04
@isdefined(contrasts) || const contrasts = Dict{Symbol,Any}()
@isdefined(progress) || const progress = false
```

As with many techniques in data science, the place where "the rubber meets the road", as they say in the automotive industry, for mixed-effects models is when working on large-scale studies.

One such study is the English Lexicon Project [@Balota_2007] --- a multicenter study incorporating both a lexical decision task and a word recognition task.
Different groups of subjects participated in the different tasks.

Compared to our previous examples, the data from these two tasks would be considered to be large data sets.
Data manipulation and model fitting in cases like these requires considerable care.

## Trial-level data from the LDT

In the lexical decision task the study participant is shown a character string, under carefully controlled conditions, and responds according to whether they identify the string as a word or not.
Two responses are recorded: whether the choice of word/non-word is correct and the time that elapsed between exposure to the string and registering a decision.

Several covariates, some relating to the subject and some relating to the target, were recorded.
Initially we consider only the trial-level data.

```{julia}
ldttrial = dataset(:ELP_ldt_trial)
```

Subject identifiers are coded in integers from 1 to 816. We prefer them as strings of the same length.
We prefix the subject number with 'S' and leftpad the number with zeros to three digits.

```{julia}
ldttrial = transform!(
  DataFrame(ldttrial),
  :subj => ByRow(s -> string('S', lpad(s, 3, '0'))) => :subj,
  :seq => ByRow(>(2000)) => :s2;
  renamecols=false,
)
describe(ldttrial)
```

There is one trial-level covariate, `seq`, the sequence number of the trial within subj.
Each subject participated in two sessions on different days, with 2000 trials recorded on the first day.
We add the `s2` column to the data frame using `@transform!`. The new variable `s2` is a Boolean value indicating if the trial is in the second session.

The two response variables are `acc` - the accuracy of the response - and `rt`, the response time in milliseconds. The target stimuli to be judged as word or nonword are stored in variable `item`.

## Initial data exploration {#sec-ldtinitialexplore}

From the basic summary of `ldttrial` we can see that there are some questionable response times --- such as negative values and values over 32 seconds.
Because of obvious outliers we will use the median response time, which is not strongly influenced by outliers, rather than the mean response time when summarizing by item or by subject.

Also, there are missing values of the accuracy.
We should check if these are associated with particular subjects or particular items.

### Summaries by item

To summarize by item we group the trials by item and use `combine` to produce the various summary statistics.
As we will create similar summaries by subject, we incorporate an 'i' in the names of these summaries (and an 's' in the name of the summaries by subject) to be able to identify the grouping used.

```{julia}
byitem = @chain ldttrial begin
  groupby(:item)
  @combine(
    :ni = length(:acc),               # no. of obs
    :imiss = count(ismissing, :acc),  # no. of missing acc
    :iacc = count(skipmissing(:acc)), # no. of accurate
    :imedianrt = median(:rt),
  )
  @transform!(
    :wrdlen = Int8(length(:item)),
    :ipropacc = :iacc / :ni
  )
end
```

It can be seen that the items occur in word/nonword pairs and the pairs are sorted alphabetically by the word in the pair (ignoring case).
We can add the word/nonword status for the items as

```{julia}
byitem.isword = isodd.(eachindex(byitem.item))
describe(byitem)
```

This table shows that some of the items were never identified correctly.
These are

```{julia}
filter(:iacc => iszero, byitem)
```

Notice that these are all words but somewhat obscure words such that none of the subjects exposed to the word identified it correctly.

We can incorporate characteristics like `wrdlen` and `isword` back into the original trial table with a "left join".
This operation joins two tables by values in a common column.
It is called a *left* join because the left (or first) table takes precedence, in the sense that every row in the left table is present in the result.
If there is no matching row in the second table then missing values are inserted for the columns from the right table in the result.

```{julia}
describe(
  leftjoin!(
    ldttrial,
    select(byitem, :item, :wrdlen, :isword);
    on=:item,
  ),
)
```

Notice that the `wrdlen` and `isword` variables in this table allow for missing values, because they are derived from the second argument, but there are no missing values for these variables.
If there is no need to allow for missing values, there is a slight advantage in disallowing them in the element type, because the code to check for and handle missing values is not needed.

This could be done separately for each column or for the whole data frame, as in

```{julia}
describe(disallowmissing!(ldttrial; error=false))
```

::: {.callout-note collapse="true"}

### Named argument "error"

The named argument `error=false` is required because there is one column, `acc`, that does incorporate missing values.
If `error=false` were not given then the error thrown when trying to `disallowmissing` on the `acc` column would be propagated and the top-level call would fail.
:::

A barchart of the word length counts, @fig-ldtwrdlenhist, shows that the majority of the items are between 3 and 14 characters.

```{julia}
#| code-fold: true
#| fig-cap: "Histogram of word lengths in the items used in the lexical decision task."
#| label: fig-ldtwrdlenhist
#| warning: false
let wlen = 1:21
  draw(
    data((; wrdlen=wlen, count=counts(byitem.wrdlen, wlen))) *
    mapping(:wrdlen => "Length of word", :count) *
    visual(BarPlot);
    figure=(; size=(600, 450)),
  )
end
```

To examine trends in accuracy by word length we use a scatterplot smoother on the binary response, as described in @sec-plottingbinary.
The resulting plot, @fig-ldtaccsmooth, shows the accuracy of identifying words is more-or-less constant at around 84%,
but accuracy decreases with increasing word length for the nonwords.

```{julia}
#| code-fold: true
#| fig-cap: "Smoothed curves of accuracy versus word length in the lexical decision task."
#| label: fig-ldtaccsmooth
#| warning: false
draw(
  data(filter(:acc => !ismissing, ldttrial)) *
  mapping(
    :wrdlen => "Word length",
    :acc => "Accuracy";
    color=:isword,
  ) *
  smooth();
  figure=(; size=(600, 340)),
)
```

@fig-ldtaccsmooth may be a bit misleading because the largest discrepancies in proportion of accurate identifications of words and nonwords occur for the longest words, of which there are few.
Over 96% of the words are between 4 and 13 characters in length

```{julia}
count(x -> 4 ≤ x ≤ 13, byitem.wrdlen) / nrow(byitem)
```

If we restrict the smoother curves to this range, as in @fig-ldtaccsmoothrestrict,

```{julia}
#| code-fold: true
#| fig-cap: "Smoothed curves of accuracy versus word length in the range 4 to 13 characters in the lexical decision task."
#| label: fig-ldtaccsmoothrestrict
#| warning: false
draw(
  data(@subset(ldttrial, !ismissing(:acc), 4 ≤ :wrdlen ≤ 13)) *
  mapping(
    :wrdlen => "Word length",
    :acc => "Accuracy";
    color=:isword,
  ) *
  smooth();
  figure=(; size=(600, 340)),
)
```

the differences are less dramatic.

Another way to visualize these results is by plotting the proportion accurate versus word-length separately for words and non-words with the area of each marker proportional to the number of observations for that combinations (@fig-propvswrdlen).

```{julia}
#| code-fold: true
#| fig-cap: "Proportion of accurate trials in the LDT versus word length separately for words and non-words.  The area of the marker is proportional to the number of observations represented."
#| label: fig-propvswrdlen
#| warning: false
let
  itemsummry = combine(
    groupby(byitem, [:wrdlen, :isword]),
    :ni => sum,
    :imiss => sum,
    :iacc => sum,
  )
  @transform!(
    itemsummry,
    :iacc_mean = :iacc_sum / (:ni_sum - :imiss_sum)
  )
  @transform!(itemsummry, :msz = sqrt((:ni_sum - :imiss_sum) / 800))
  draw(
    data(itemsummry) * mapping(
      :wrdlen => "Word length",
      :iacc_mean => "Proportion accurate";
      color=:isword,
      markersize=:msz,
    );
    figure=(; size=(600, 340)),
  )
end
```

The pattern in the range of word lengths with non-negligible counts (there are points in the plot down to word lengths of 1 and up to word lengths of 21 but these points are very small) is that the accuracy for words is nearly constant at about 84% and the accuracy for nonwords is slightly higher until lengths of 13, at which point it falls off a bit.

### Summaries by subject {#sec-elpsumrysubj}

A summary of accuracy and median response time by subject

```{julia}
bysubj = @chain ldttrial begin
  groupby(:subj)
  @combine(
    :ns = length(:acc),               # no. of obs
    :smiss = count(ismissing, :acc),  # no. of missing acc
    :sacc = count(skipmissing(:acc)), # no. of accurate
    :smedianrt = median(:rt),
  )
  @transform!(:spropacc = :sacc / :ns)
end
```

shows some anomalies

```{julia}
describe(bysubj)
```

First, some subjects are accurate on only about half of their trials, which is the proportion that would be expected from random guessing.
A plot of the median response time versus proportion accurate, @fig-ldtmedianrtvspropacc, shows that the subjects with lower accuracy are some of the fastest responders, further indicating that these subjects are sacrificing accuracy for speed.

```{julia}
#| code-fold: true
#| fig-cap: "Median response time versus proportion accurate by subject in the LDT."
#| label: fig-ldtmedianrtvspropacc
#| warning: false
draw(
  data(bysubj) *
  mapping(
    :spropacc => "Proportion accurate",
    :smedianrt => "Median response time (ms)",
  ) *
  (smooth() + visual(Scatter));
  figure=(; size=(600, 450)),
)
```

As described in @Balota_2007, the participants performed the trials in blocks of 250 followed by a short break.
During the break they were given feedback concerning accuracy and response latency in the previous block of trials.
If the accuracy was less than 80% the participant was encouraged to improve their accuracy.
Similarly, if the mean response latency was greater than 1000 ms, the participant was encouraged to decrease their response time.
During the trials immediate feedback was given if the response was incorrect.

Nevertheless, approximately 15% of the subjects were unable to maintain 80% accuracy on their trials

```{julia}
count(<(0.8), bysubj.spropacc) / nrow(bysubj)
```

and there is some association of faster response times with low accuracy.
The majority of the subjects whose median response time is less than 500 ms are accurate on less than 75% of their trials.
Another way of characterizing the relationship is that none of the subjects with 90% accuracy or greater had a median response time less than 500 ms.

```{julia}
minimum(filter(:spropacc => >(0.9), bysubj).smedianrt)
```

It is common in analyses of response latency in a lexical discrimination task to consider only the latencies on correct identifications and to trim outliers.
In @Balota_2007 a two-stage outlier removal strategy was used; first removing responses less than 200 ms or greater than 3000 ms then removing responses more than three standard deviations from the participant's mean response.

As described in @sec-ldtrtscale we will analyze these data on a speed scale (the inverse of response time) using only the first-stage outlier removal of response latencies less than 200 ms or greater than 3000 ms.
On the speed scale the limits are 0.333 per second up to 5 per second.

To examine the effects of the fast but inaccurate responders we will fit models to the data from all the participants and to the data from the 85% of participants who maintained an overall accuracy of 80% or greater.

```{julia}
pruned = @chain ldttrial begin
  @subset(!ismissing(:acc), 200 ≤ :rt ≤ 3000,)
  leftjoin!(select(bysubj, :subj, :spropacc); on=:subj)
  dropmissing!
end
size(pruned)
```

```{julia}
describe(pruned)
```

### Choice of response scale {#sec-ldtrtscale}

As we have indicated, generally the response times are analyzed for the correct identifications only.
Furthermore, unrealistically large or small response times are eliminated.
For this example we only use the responses between 200 and 3000 ms.

A density plot of the pruned response times, @fig-elpldtrtdens, shows they are skewed to the right.

```{julia}
#| code-fold: true
#| fig-cap: Kernel density plot of the pruned response times (ms.) in the LDT.
#| label: fig-elpldtrtdens
#| warning: false
draw(
  data(pruned) *
  mapping(:rt => "Response time (ms.) for correct responses") *
  AlgebraOfGraphics.density();
  figure=(; size=(600, 340)),
)
```

In such cases it is common to transform the response to a scale such as the logarithm of the response time or to the speed of the response, which is the inverse of the response time.

The density of the response speed, in responses per second, is shown in @fig-elpldtspeeddens.

```{julia}
#| code-fold: true
#| fig-cap: Kernel density plot of the pruned response speed in the LDT.
#| label: fig-elpldtspeeddens
#| warning: false
draw(
  data(pruned) *
  mapping(
    :rt =>
      (
        x -> 1000 / x
      ) => "Response speed (s⁻¹) for correct responses",
  ) *
  AlgebraOfGraphics.density();
  figure=(; size=(600, 340)),
)
```

@fig-elpldtrtdens and @fig-elpldtspeeddens indicate that it may be more reasonable to establish a lower bound of 1/3 second (333 ms) on the response latency, corresponding to an upper bound of 3 per second on the response speed.
However, only about one half of one percent of the correct responses have latencies in the range of 200 ms. to 333 ms.

```{julia}
count(
  r -> !ismissing(r.acc) && 200 < r.rt < 333,
  eachrow(ldttrial),
) / count(!ismissing, ldttrial.acc)
```

so the exact position of the lower cut-off point on the response latencies is unlikely to be very important.

As noted in @Box1964, a transformation of the response that produces a more Gaussian distribution often will also produce a simpler model structure.
For example, @fig-ldtrtvswrdlen shows the smoothed relationship between word length and response time for words and non-words separately,

```{julia}
#| code-fold: true
#| fig-cap: "Scatterplot smooths of response time versus word length in the LDT."
#| label: fig-ldtrtvswrdlen
#| warning: false
draw(
  data(pruned) *
  mapping(
    :wrdlen => "Word length",
    :rt => "Response time (ms)";
    :color => :isword,
  ) *
  smooth();
  figure=(; size=(600, 450)),
)
```

and @fig-ldtspeedvswrdlen shows the similar relationships for speed

```{julia}
#| code-fold: true
#| fig-cap: "Scatterplot smooths of response speed versus word length in the LDT."
#| label: fig-ldtspeedvswrdlen
#| warning: false
draw(
  data(pruned) *
  mapping(
    :wrdlen => "Word length",
    :rt => (x -> 1000 / x) => "Speed of response (s⁻¹)";
    :color => :isword,
  ) *
  smooth();
  figure=(; size=(600, 450)),
)
```

For the most part the smoother lines in @fig-ldtspeedvswrdlen are reasonably straight.
The small amount of curvature is associated with short word lengths, say less than 4 characters, of which there are comparatively few in the study.

@fig-speedviolin shows a "violin plot" - the empirical density of the response speed by word length separately for words and nonwords.  The lines on the plot are fit by linear regression.

```{julia}
#| code-fold: true
#| fig-cap: "Empirical density of response speed versus word length by word/non-word status, with lines fit by linear regression to each group."
#| label: fig-speedviolin
#| warning: false
let
  plt = data(@subset(pruned, :wrdlen > 3, :wrdlen < 14))
  plt *= mapping(
    :wrdlen => "Word length",
    :rt => (x -> 1000 / x) => "Speed of response (s⁻¹)",
    color=:isword,
    side=:isword,
  )
  plt *= (visual(Violin) + linear(; interval=:confidence))
  draw(
    plt,
    axis=(; limits=(nothing, (0.0, 2.8)));
    figure=(; size=(600, 450)),
  )
end
```

## Models with scalar random effects {#sec-ldtinitialmodel}

A major purpose of the English Lexicon Project is to characterize the items (words or nonwords) according to the observed accuracy of identification and to response latency, taking into account subject-to-subject variability, and to relate these to lexical characteristics of the items.

In @Balota_2007 the item response latency is characterized by the average  response latency from the correct trials after outlier removal.

Mixed-effects models allow us greater flexibility and, we hope, precision in characterizing the items by controlling for subject-to-subject variability and for item characteristics such as word/nonword and item length.

We begin with a model that has scalar random effects for item and for subject and incorporates fixed-effects for word/nonword and for item length and for the interaction of these terms.

### Establish the contrasts

Because there are a large number of items in the data set it is important to assign a `Grouping()` contrast to `item` (and, less importantly, to `subj`).
For the `isword` factor we will use an `EffectsCoding` contrast with the base level as `false`.
The non-words are assigned -1 in this contrast and the words are assigned +1.
The `wrdlen` covariate is on its original scale but centered at 8 characters.

Thus the `(Intercept)` coefficient is the predicted speed of response for a typical subject and typical item (without regard to word/non-word status) of 8 characters.

Set these contrasts

```{julia}
contrasts[:isword] = EffectsCoding(; base=false);
contrasts[:wrdlen] = Center(8);
```

and fit a first model with simple, scalar, random effects for `subj` and `item`.

```{julia}
elm01 =
  let f = @formula 1000 / rt ~
      1 + isword * wrdlen + (1 | item) + (1 | subj)
    fit(MixedModel, f, pruned; contrasts, progress)
  end
```

The predicted response speed by word length and word/nonword status can be summarized as

```{julia}
effects(Dict(:isword => [false, true], :wrdlen => 4:2:12), elm01)
```

If we restrict to only those subjects with 80% accuracy or greater the model becomes

```{julia}
elm02 =
  let f = @formula 1000 / rt ~
      1 + isword * wrdlen + (1 | item) + (1 | subj)
    dat = filter(:spropacc => >(0.8), pruned)
    fit(MixedModel, f, dat; contrasts, progress)
  end
```

```{julia}
effects(Dict(:isword => [false, true], :wrdlen => 4:2:12), elm02)
```

To compare the conditional means of the random effects for item in these two models we incorporate them into the `byitem` table.

```{julia}
#| code-fold: true
#| fig-cap: "Conditional means of scalar random effects for item in model elm01, fit to the pruned data, versus those for model elm02, fit to the pruned data with inaccurate subjects removed."
#| label: fig-itemreelm01vselm02
#| warning: false

CairoMakie.activate!(; type="png")
condmeans = leftjoin!(
  leftjoin!(
    rename!(DataFrame(raneftables(elm01)[:item]), [:item, :elm01]),
    rename!(DataFrame(raneftables(elm02)[:item]), [:item, :elm02]);
    on=:item,
  ),
  select(byitem, :item, :isword; copycols=false);
  on=:item,
)
draw(
  data(condmeans) * mapping(
    :elm01 => "Conditional means of item random effects for model elm01",
    :elm02 => "Conditional means of item random effects for model elm02";
    color=:isword,
  );
  figure=(; size=(600, 400)),
)
```

::: {.callout-note}
Adjust the alpha on @fig-itemreelm01vselm02.
:::

@fig-itemreelm01vselm02 is exactly of the form that would be expected in a sample from a correlated multivariate Gaussian distribution.
The correlation of the two sets of conditional means is about 96%.

```{julia}
cor(Matrix(select(condmeans, :elm01, :elm02)))
```

These models take only a few seconds to fit on a modern laptop computer, which is quite remarkable given the size of the data set and the number of random effects.

The amount of time to fit more complex models will be much greater so we may want to move those fits to more powerful server computers.
We can split the tasks of fitting and analyzing a model between computers by saving the optimization summary after the model fit and later creating the `MixedModel` object followed by restoring the `optsum` object.

```{julia}
saveoptsum("./optsums/elm01.json", elm01);
```

```{julia}
elm01a = restoreoptsum!(
  let f = @formula 1000 / rt ~
      1 + isword * wrdlen + (1 | item) + (1 | subj)
    MixedModel(f, pruned; contrasts)
  end,
  "./optsums/elm01.json",
)
```

Other covariates associated with the item are available as

```{julia}
elpldtitem = DataFrame(dataset(:ELP_ldt_item))
describe(elpldtitem)
```

and those associated with the subject are

```{julia}
elpldtsubj = DataFrame(dataset(:ELP_ldt_subj))
elpldtsubj = transform!(
  elpldtsubj,
  :subj => ByRow(s -> string('S', lpad(s, 3, '0'))) => :subj,
)

describe(elpldtsubj)
```

For the simple model `elm01` the estimated standard deviation of the random effects for subject is greater than that of the random effects for item, a common occurrence.
A caterpillar plot, @fig-elm01caterpillarsubj,

```{julia}
#| code-fold: true
#| fig-cap: Conditional means and 95% prediction intervals for subject random effects in elm01.
#| label: fig-elm01caterpillarsubj
#| warning: false
qqcaterpillar!(Figure(; size=(600, 450)), ranefinfo(elm01, :subj))
```

shows definite distinctions between subjects because the widths of the prediction intervals are small compared to the range of the conditional modes.
Also, there is at least one outlier with a conditional mode over 1.0.

@fig-elm02caterpillarsubj is the corresponding caterpillar plot for model `elm02` fit to the data with inaccurate responders eliminated.

```{julia}
#| code-fold: true
#| fig-cap: Conditional means and 95% prediction intervals for subject random effects in elm02.
#| label: fig-elm02caterpillarsubj
#| warning: false
qqcaterpillar!(Figure(; size=(600, 450)), ranefinfo(elm02, :subj))
```

*This page was rendered from git revision {{< git-rev short=true >}}.*