nlmeModel: MNREAD data fitting using a nonlinear mixed-effect (NLME)...

Description Usage Arguments Value Notes Warning See Also Examples

View source: R/nlme_model.R

Description

This function uses a nonlinear mixed effects model (NLME), as described in Cheung et al. 2008, where variations across individuals are modeled as random effects. This function estimates and returns the NLME model while performing print size correction for non-standard testing viewing distance (ie. different than 40 cm).

Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
nlmeModel(
  data,
  print_size,
  viewing_distance,
  reading_time,
  errors,
  subjectID,
  nested = NULL,
  group = NULL
)

Arguments

data

The name of your dataframe

print_size

The variable that contains print size values for each sentence (print size uncorrected for viewing distance)

viewing_distance

The variable that contains the viewing distance value used for testing

reading_time

The variable that contains the reading time for each sentence

errors

The variable that contains the number of errors for each sentence

subjectID

The variable that contains the subject identifiers

nested

Optional argument to build a model with a nested structure. 'nested' specifies which variable should be nested within subject. Default is NULL.

group

Optional argument to build a model with a grouped structure. 'group' specifies which variable should be used as grouping argument. Default is NULL

Value

The function returns a list of two objects:

Notes

For subjects with incomplete data, warning messages might appear in the console. However, the NLME model will run, using supporting data from the rest of the population.

This functions supports nested, grouped and nested + grouped structures.

If needed, the nlme object returned can be further explored using generic functions from the nlme package.

This function implements several functions from the nlme package to build the NLME model:

For more details on the nlme fit, see:\ Cheung SH, Kallie CS, Legge GE, Cheong AM. Nonlinear mixed-effects modeling of MNREAD data. Invest Ophthalmol Vis Sci. 2008;49:828–835. doi: 10.1167/iovs.07-0555.

Warning

For the function to run properly, please make sure that variables are of the following classes:

The optional arguments "nested" and "group" should only be specified when they are needed. In case they are called and set to NULL, the function will not run and will return an error.

See Also

nlmeParam to estimate Maximum Reading Speed (MRS) and Critical Print Size (CPS) from the NLME model

nlmeCurve to plot the individual MNREAD curves estimated from the NLME model

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
# inspect the structure of the dataframe
head(data_low_vision, 10)

#------

# restrict dataset to one MNREAD test per subject (regular polarity only)
data_regular <- data_low_vision %>%
    filter (polarity == "regular")

# run the NLME model for data grouped by subject
## Not run:  model_simple <- nlmeModel(data_regular, ps, vd, rt, err, subject) 

# to print the model summary
## Not run:  summary(model_simple[[2]]) 

# to print the first 3 rows of the cleaned dataset containing the raw data and used to run the model
## Not run:  head(model_simple[[1]], 3) 

#------

# run the NLME model on the whole dataset with polarity nested within subject
## Not run:  model_nested <- lmeModel(data_low_vision, ps, vd, rt, err, subject,
                                   nested = polarity) 
## End(Not run)

#------

# run theNLME model on the whole dataset with polarity nested within subject 
# and grouped based on treatment
## Not run:  model_nested_grouped <- nlmeModel(data_low_vision, ps, vd, rt, err, subject,
                                            nested = polarity, group = treatment) 
## End(Not run)

mnreadR documentation built on June 25, 2021, 1:07 a.m.

Related to nlmeModel in mnreadR...