mnreadR (version 2.1.7)

mnreadCurve: MNREAD curve plotting.

Description

This function plots individual MNREAD curves, while showing the estimated MNREAD parameters:

• Maximum Reading Speed (MRS)

• Critical Print Size (CPS)

• Reading Acuity (RA)

Usage

mnreadCurve(
  data,
  print_size,
  viewing_distance,
  reading_time,
  errors,
  ... = NULL
)

Value

The function returns a plot of reading speed (in words/min) as a function of print size (in logMAR). Reading Acuity is marked as a triangle, Maximum Reading Speed and Critical Print Size are shown with dashed lines. When using two grouping arguments, a colored diamond is added for clarification. Highlighted data points represent the range of print sizes included in the Reading Accessibility Index calculation.

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

...

Optional grouping arguments

Notes

This function can't take more that two grouping arguments. The first grouping argument is used to draw sub-plots (using facet_wrap from ggplot2). The second grouping argument is color-coded.

This function performs print size correction for non-standard testing viewing distance before plotting the curve.

This function uses the original algorithm described in Legge (2007) to estimate Maximum Reading Speed (MRS) and Critical Print Size (CPS). For more details on the parameters estimation, see curveParam_RT.

Warning

For the function to run properly, one needs to make sure that the variables are of the class:

• print_size -> numeric

• viewing_distance -> integer

• reading_time -> numeric

• errors -> integer

In cases where only 3 or less sentences were read during a test, MRS and CPS cannot be estimated and won't be displayed on the plot. In such cases, the Reading Accessibility Index (ACC) can be used to estimate the MNREAD score instead (cf. accIndex).

To ensure proper plotting, the data should be entered along certain rules:

• For the smallest print size that is presented but not read, right before the test is stopped: reading_time = NA, errors = 10

• For all the small sentences that are not presented because the test was stopped before them: reading_time = NA, errors = NA

• If a sentence is presented, and read, but the time was not recorded by the experimenter: reading_time = NA, errors = actual number of errors (cf. s5-regular in low vision data sample)

• If a large sentence was skipped to save time but would have been read well: reading_time = NA, errors = NA (cf. s1-regular in normal vision data sample)

• If a large sentence was skipped to save time because the subject cannot read large print: reading_time = NA, errors = 10 (cf. s7 in low vision data sample)

See Also

curveParam_RT for standard estimation of MRS and CPS using values of reading time (instead of reading speed)

readingAcuity for Reading Acuity calculation

Examples

# inspect the structure of the dataframe
head(data_low_vision, 10)

#------

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

# plot the MNREAD curve 
 mnreadCurve(data_s1_reg, ps, vd, rt, err)  

#------

# restrict dataset to one subject (s1) and plot the MNREAD curves using ONE GROUPING ARGUMENT 
# (ie. polarity) 
data_s1 <- data_low_vision %>%
   filter (subject == "s1")

# plot the MNREAD curve using ONE GROUPING ARGUMENT (ie. polarity)
  mnreadCurve(data_s1, ps, vd, rt, err, polarity)  

#------

# restrict dataset to two subject (s1 & s2) and plot the MNREAD curves using TWO GROUPING ARGUMENTS 
# (ie. subject and polarity) 
data_s2 <- data_low_vision %>%
   filter (subject == "s1" | subject == "s2")

  mnreadCurve(data_s2, ps, vd, rt, err, subject, polarity)  

#------

# Once created, the MNREAD curve can be customized as needed using ggplot2, 
# for ex., by adding the number of errors for each sentence on top of the curve

# plot the MNREAD curve 
my.plot <- mnreadCurve(data_s1, ps, vd, rt, err, polarity)

# display my.plot
print(my.plot)

# calculate reading speed and perform print size correction
data_s1_new <- as.data.frame(
data_s1 %>%
    filter (err != "NA" & rt > 0) %>%
    mutate (errors10 = replace (err, err > 10, 10) ) %>%
    mutate (rs = 60 * (10 - errors10) / rt ) %>%
    mutate (correct_ps = ps + round(log10(40/(vd)), 2)) ) 

# add the number of errors for each sentence 
my.new.plot <- my.plot + geom_text(aes(x = correct_ps, y = rs + 5, label = errors10),
                                   alpha = 0.5,
                                   data = data_s1_new %>% filter (errors10 != 0) )

# display my.new.plot                                                                        
print(my.new.plot)

#------

# MNREAD curves can also be saved in a pdf file, with each page showing a different subject
 
# count the number of subjects to define the number of pages
num_pages = length(unique(data_s2$subject))

# create a pdf file 
# \donttest{ 
pdf ("MNREAD_curves.pdf", width = 10.5, height = 8, paper = "special", useDingbats = TRUE)

# wrap the plots over several pages
for (i in seq(num_pages)){
    p <- mnreadCurve(data_s2 %>% filter (subject == sort(unique(data_s2$subject))[i]),
                     ps, vd, rt, err, subject, polarity) 
    print(p)
}

dev.off()  
# }