eye

Tjebo Heeren

2020-06-25

See more with eye

library(eye)

Introduction

eye is dedicated to facilitate ophthalmic research, providing convenient application programming interfaces (API) for common tasks:

Further, it provides tools for easy data summaries and calculations:

eye includes the real life data set amd, of people who received intravitreal anti-VEGF injections for treatment naive neovascular age-related macular degeneration in Moorfields Eye Hospital. (Fasler et al. 2019)

eye includes a visual acuity conversion chart.

AMD data set

amd is an anonymised real life data set from a large cohort of patients with treatment-naive neovascular age-related macular degeneration (AMD) who received intravitreal anti-VEGF therapy in Moorfields Eye Hospital, London, UK. Data was accessed on the 25th May 2020 from the source
Kindly reference this data by citing the corresponding publication. (Fasler et al. 2019)

There are erroneous visual acuity entries in this data set which I noticed during the work on this package. The data set curator investigated and concluded that these were erroneous entries in the original medical health records. I decided to keep the values in the data set and wait for the final decision how to proceed from the data set curator (if they are going to replace it with missing values or not). I believe this is a great example for the challenges of real life data and a reminder to remain vigilant when doing data analysis.

Visual acuity conversion

Easy conversion from visual acuity notations in a single call to va():

va() cleans and converts visual acuity notations (classes) between Snellen (decimal, meter and feet), ETDRS, and logMAR. Each class can be converted from one to another, but va() converts to logMAR by default. va() will detect the class automatically based on specific rules detailed below.

It takes an (atomic) vector with visual acuity entries as the only required argument. The user can specify the original VA notation, but va will check that and ignore the argument if implausible.

Conversion steps

va() basically runs three main steps:

  1. Entry cleaning with clean_va()
  2. Notation detection with which_va()
  3. Conversion with the S3 generic convertVA()

Cleaning

  1. NA are assigned to missing entries or strings representing such entries (“.”, "“,”{any number of spaces}“,”N/A“,”NA“,”NULL")
  2. Notation for qualitative entries is simplified (NPL becomes NLP, PL becomes LP).
  3. “plus” and “minus” from Snellen entries are converted:
    • if entry -1 to +3 : take same Snellen value
    • if <= -2 : take Snellen value one line below
    • if >+3 (unlikely, but unfortunately not impossible): Snellen value one line above

Snellen are unfortunately often entered with “+/-”, which is a violation of psychophysical methods designed to assign one (!) unambiguous value to visual acuity, with non-arbitrary thresholds based on psychometric functions. Therefore, transforming “+/-” notation to actual results is in itself problematic and the below suggestion to convert it will remain an approximation to the most likely “true” result. Even more so, as the given conditions should work for charts with 4 or 5 optotypes in a line, and visual acuity is not always tested on such charts. Yet, I believe that the approach is still better than just omitting the letters or (worse) assigning a missing value to those entries.

If the argument logmarstep = TRUE, the entries will be converted to logmar values or or ETDRS letters (0.02 logmar or 1 letter for each optotype). This is based on the assumption of 5 optotypes in a row. The argument should not be set TRUE when conversion to Snellen is desired - this does not make sense. However, if you still decide to do that, you will get the values just without +/- entries.

Detection

Accepted VA formats

  • Snellen fractions (meter/ feet) need to be entered as fraction with “/”.
  • converting Snellen to ETDRS or logMAR: any fraction is allowed , e.g. 3/60 and 2/200 will also be recognized.
  • converting between Snellen fractions: has to be either 6/ or 20/. Other fractions will not be recognized. See also “Examples”
  • ETDRS must be integer-equivalent between 0 and 100 (integer equivalent means, it can also be a character vector)
  • logMAR must be between -0.3 and 3.0
  • Qualitative must be either of PL, LP, NLP, NPL, HM, CF (any case allowed)
  • Any element which is not recognized will be converted to NA

Conversion

Detection and conversion is on a vector as a whole by which_va(). If a “mixed” VA notation is found, which_va_dissect() and va_dissect() will be called instead for each VA vector element individually.

Problematic cases:

There can be ambiguous cases for detection (detection defaults to logmar):

Snellen decimals are a particular challenge and va may wrongly assign logMAR - this could happen if there are unusual snellen decimal values in the data which are not part of the VA conversion chart.

E.g., check the values with unique(x).

Examples

recodeye

Makes recoding eye variables very easy.

If you have different codes, you can change the recognized strings with the eyecodes argument, which needs to be a list. But remember to put the strings for right eyes first!

x <- c("r", "re", "od", "right", "l", "le", "os", "left")
recodeye(x)
#> [1] "r" "r" "r" "r" "l" "l" "l" "l"

## chose the resulting codes
recodeye(x, to = c("right", "left"))
#> [1] "right" "right" "right" "right" "left"  "left"  "left"  "left"

## Or if you have weird codes for eyes
x <- c("alright", "righton", "lefty","leftover")
recodeye(x, eyecodes = list(c("alright","righton"), c("lefty","leftover")))
#> [1] "r" "r" "l" "l"

## Numeric codes 0:1/ 1:2 are recognized 
x <- 1:2
recodeye(x)
#> Eyes coded 1:2. Interpreting r = 1
#> [1] "r" "l"

## chose the resulting codes
recodeye(x, to = c("right", "left"))
#> Eyes coded 1:2. Interpreting r = 1
#> [1] "right" "left"

## or, if right is coded with 2)
recodeye(x, numcode = 2:1)
#> Eyes coded 2:1 with r = 2
#> [1] "l" "r"

Counting patients and eyes

eyes offers a very simple tool for counting patients and eyes.

An important step in eyes is the guessing of the columns that identify patients and eyes. As for myop and of course blink, a specific column naming is required for a reliable automatic detection of patient and eye column(s) ( see Names and codes)

The arguments id and eye arguments overrule the name guessing for the respective columns.

Guessing

patient ID columns:

  • names can be in any case.
  • First, eyes is looking for names that contain both strings “pat” and “id” (the order doesn’t matter)
  • Next, it will look for columns that are plainly called “ID”
  • Last, it will search for all names that contain either “pat” or “id”

eye variable column:

  • names can be in any case.
  • eyes looks for columns called either “eye” or “eyes”

Counting

For counting eyes, eyes need to be coded in commonly used ways. You can use recodeye for very convenient recoding.

Report:

eyes also include a convenience function to turn the count into a text. This is intended for integration into rmarkdown reports, or for easy copy / pasting. eyes_to_string() parses the output of eyes into text under the hood. Arguments to eyes_to_string are passed via …:

eyestr is a shorthand for eyes(x, report = TRUE). The name was chosen because it’s a contraction of “eyes” and “strings” and it’s a tiny bit easier to type than “eyetxt”.

Use in rmarkdown

eyestr was designed with the use in rmarkdown in mind, most explicitly for the use inline:

We analysed `r eyestr(amd)`

will give:

We analysed 3357 eyes of 3357 patients.

The beauty of this report is of course that the numbers will always update with new data.

Examples

Reshape eye data

Out of convenience, data is often entered in a “wide” format: In eye research, there will be often two columns for the same variable, one column for each eye.

This may be a necessary data formal for specific questions.

However, “eye” is also variable (a dimension of your observation), and it can also be stored in a separate column. Indeed, in my experience R often needs eyes to be in a single column, with each other variable having their own dedicated column.

myop

Reshaping many such columns can be a daunting task, and myop() makes this easier. It will remove duplicate rows, and pivot the eye variable to one column and generate a single column for each variable, thus shaping the data for specific types of analysis. For example, eight columns that store data of four variables for right and left eyes will be pivoted to 5 columns (one eye column and four further variable columns)). See also Examples.

As with eyes(), myop() requires a specific data format. See names and codes If there is already a column called “eye” or “eyes”, myop will not make any changes - because the data is then already assumed to be in long format.

If there still are variables spread over two columns for right and left eyes, then this is an example of messy data. A solution would be to remove or simply rename the “eye” column and then let myop do the work. However, you need to be very careful in those cases if resulting data frame is plausible.

Learn about tidy data.

Make myop work

myop will work reliably if you adhere to the following:

  1. Common codes for eyes:
    • Right eyes: “r”, “re”, “od”, “right”
    • Left eyes: “l”, “le”, “os”, “left”
  2. strings for eyes need to be separated by period or underscores. (Periods will be replaced by underscores).
  3. Any order of substrings is allowed:
    • Will work: “va_r”, “right_morningpressure”, “night_iop.le”, “gat_os_postop”
    • Will fail: “VAr”, “rightmorningPressure”, “night_IOPle”, “gatOSpostop”

An exception is when there is only one column for each eye. Then the column names can consist of “eye strings” only. In this case, the argument var will be used to name the resulting variable.

If there are only eye columns in your data (should actually not happen), myop will create identifiers by row position.

Please always check the result for plausibility. Depending a lot on how the data was entered, the results could become quite surprising. There is basically a nearly infinite amount of possible combinations of how to enter data, and it is likely that myop will not be able to deal with all of them.

myop under the hood

myop() basically runs three main steps:

  1. Removing duplicates
  2. Rename data names with myop_rename() and sort_substr():
    • Replacing “.” by "_"
    • Re-arranging and recoding substrings in a way that strings for eyes always appear at first position. They will be recoded to “r” and “l”
  3. Myopization: The actual work is done with myopizer() and myop_pivot() and itself consists of three steps.
    • All columns with an eye string at first position will be selected pivoted to two long colums (key and value) using tidyr::pivot_longer.
    • The key column will be split by position into an eye column and a variable column.
    • The variable and value columns will be pivoted wide again with tidyr::pivot_wider.

hyperop

Basically the opposite of myop() - a slightly intelligent wrapper around tidyr::pivot_longer() and tidyr::pivot_wider(). Will find the eye column, unify the codes for the eyes (all to “r” and “l”) and pivot the columns wide, that have been specified in “cols”. Again, good names and tidy data always help!

The cols argument takes a tidyselection. Read about tidyselection

Names and codes

eye works smoother with tidy data, and with good names (any package does, really!)

Tidy data

The basic principle of tidy data is: one column for each dimension and one row for each observation.

Learn more about tidy data.

This chapter explains how you can improve names and codes so that eye will work like a charm.

How do I rename columns in R?

When I started with R, I found it challenging to rename columns and I found the following methods very helpful:

I’ve got a data frame with unfortunate names:

I can rename all names easily:

To rename only specific columns, even if you are not sure about their exact position:

For even more methods, I found those two threads on Stackoverflow very helpful:

Tips and rules for naming:

  1. Don’t be too creative with your names!
  2. Use common coding:
    • eyes: “r”, “re”, “od”, “right” - or numeric coding r:l = 0:1 or 1:2
    • Visual acuity: “VA”, “BCVA”, “Acuity”
    • Intraocular pressure: “IOP”, “GAT”, “NCT”, “pressure”
    • Patient identifier: “pat”, “patient”, “ID” (ideally both: “patientID” or “patID”)
  3. Column names:
    • No spaces!
    • Do not use numeric coding for eyes in column names
    • Separate eye and VA and IOP codes with underscores (“bcva_l_preop”, “VA_r”, “left_va”, “IOP_re”)
    • Keep names short
    • Don’t use underscores when you don’t need to: Consider each section divided by an underscore as a relevant characteristic of your variable. E.g., “preop” instead of “pre_op”, or simply “VA” instead of “VA_ETDRS_Letters”

Name examples

Good names (eye will work nicely)

OK names (eye will work)

Bad names (eye will fail)

Reveal common statistics

reveal() offers a simple API to show common summary statistics for all numeric columns of your data frame. reveal() is basically a slightly complicated wrapper around mean(), sd(), length(), min() and max() (with na.rm = TRUE and length() counting only non-NA values).

It is not really intended to replace other awesome data exploration packages / functions such as skimr::skim, and it will likely remain focussed on summarizing numerical data only.

It uses an S3 generic under the hood with methods for atomic vectors, data frames, and lists of either atomic vectors or data frames. Character vectors will be omitted (and it should give a warning that it has done so).

reveal() takes the grouping argument by and it returns vector for atomic vectors or a data frame for lists.

Examples

Calculate age

This is a simple function and should not require much explanation. However, it may be noteworthy to mention the subtle distinction of periods and durations, which are an idiosyncrasy of time measurements and well explained in this thread.

Examples

Important notes

I do not assume responsability for your data or analysis. Please always keep a critical mind when working with data - if you do get results that seem implausible, there may be a chance that the data is in an unfortunate shape for which eye may not be suitable.

VA conversion chart

This chart is included in the package as va_chart

Snellen feet Snellen meter Snellen decimal logMAR ETDRS Categories
20/20000 6/6000 0.001 3 0 NLP
20/10000 6/3000 0.002 2.7 0 LP
20/4000 6/1200 0.005 2.3 0 HM
20/2000 6/600 0.01 1.9 2 CF
20/800 6/240 0.025 1.6 5 NA
20/630 6/190 0.032 1.5 10 NA
20/500 6/150 0.04 1.4 15 NA
20/400 6/120 0.05 1.3 20 NA
20/320 6/96 0.062 1.2 25 NA
20/300 6/90 0.067 1.18 26 NA
20/250 6/75 0.08 1.1 30 NA
20/200 6/60 0.1 1.0 35 NA
20/160 6/48 0.125 0.9 40 NA
20/125 6/38 0.16 0.8 45 NA
20/120 6/36 0.167 0.78 46 NA
20/100 6/30 0.2 0.7 50 NA
20/80 6/24 0.25 0.6 55 NA
20/70 6/21 0.29 0.54 58 NA
20/63 6/19 0.32 0.5 60 NA
20/60 6/18 0.33 0.48 61 NA
20/50 6/15 0.4 0.4 65 NA
20/40 6/12 0.5 0.3 70 NA
20/32 6/9.6 0.625 0.2 75 NA
20/30 6/9 0.66 0.18 76 NA
20/25 6/7.5 0.8 0.1 80 NA
20/20 6/6 1.0 0.0 85 NA
20/16 6/5 1.25 -0.1 90 NA
20/15 6/4.5 1.33 -0.12 91 NA
20/13 6/4 1.5 -0.2 95 NA
20/10 6/3 2.0 -0.3 100 NA

Acknowledgements

Resources

References

Beck, Roy W, Pamela S Moke, Andrew H Turpin, Frederick L Ferris, John Paul SanGiovanni, Chris A Johnson, Eileen E Birch, et al. 2003. “A Computerized Method of Visual Acuity Testing.” American Journal of Ophthalmology 135 (2). Elsevier BV: 194–205. https://doi.org/10.1016/s0002-9394(02)01825-1.

Fasler, Katrin, Gabriella Moraes, Siegfried Wagner, Karsten U Kortuem, Reena Chopra, Livia Faes, Gabriella Preston, et al. 2019. “One- and Two-Year Visual Outcomes from the Moorfields Age-Related Macular Degeneration Database: A Retrospective Cohort Study and an Open Science Resource.” BMJ Open 9 (6). British Medical Journal Publishing Group. https://doi.org/10.1136/bmjopen-2018-027441.

Gregori, Ninel Z, William Feuer, and Philip J Rosenfeld. 2010. “Novel Method for Analyzing Snellen Visual Acuity Measurements.” Retina 30 (7). Ovid Technologies (Wolters Kluwer Health): 1046–50. https://doi.org/10.1097/iae.0b013e3181d87e04.

Holladay, Jack T. 2004. “Visual Acuity Measurements.” Journal of Cataract and Refractive Surgery 30 (2): 287–90. https://doi.org/10.1016/j.jcrs.2004.01.014.

Schulze-Bonsel, Kilian, Nicolas Feltgen, Hermann Burau, Lutz Hansen, and Michael Bach. 2006. “Visual Acuities ‘Hand Motion’ and ‘Counting Fingers’ Can Be Quantified with the Freiburg Visual Acuity Test.” Investigative Ophthalmology & Visual Science 47 (3): 1236–40. https://doi.org/10.1167/iovs.05-0981.