ACE Analytics

We have built a package for R called aceR. This package will read in raw data generated by ACE Explorer and process the data to generate summary statistics for each participant. This page provides resources for using R and this package

• Troubleshooting
• FAQ

Program Requirements

Our analyses scripts use a free program called R. We recommend using R Studio as a free helper program to interact with R

• R
• R Studio

Processing Template

We provide a processing template for use with Ace Explorer data to help get you started.
Please read the notes included in the template to determine if the defaults for the many functions to clean and process the data are appropriate to answer your research question or if modifications should be made.
Last updated 04/23/2021
For more instructions for using the aceR and then template, please see this video walkthrough and accompanying slide deck. 

Data Dictionaries

• ACE trial level column explanation – Description of the column names generated by load_ace_bulk function for ACE modules
• ACE data column explanation – Description of the column names generated by proc_by_module function for ACE modules

Last updated 04/21/2022

Task Metrics

Which metrics should you use to analyze ACE data?

That’s up to you! We strived to include as much information as possible so that you can analyze the metric you are most interested in, including mean accuracy, mean response time, standard deviation of response time, d’, and more. Below, you can find our suggested metrics for each task, but different metrics may be appropriate depending on the research question or population.

• BRT: mean RT (dominant/non-dominant hand)
• Stroop/ Color Tricker: overall Rate Correct Score
• Flanker: overall Rate Correct Score
• Boxed: overall Rate Correct Score
• Task Switch/ Sun & Moon: overall Rate Correct Score
• Forward Span/ Gem Chaser: Max object span
• Backward Span/ Gem Chaser: Max object span
• Filter: K (per condition)
• TNT/ Triangle Trace: mean RT
• Compass: overall Rate Correct Score
• Mars UFO (Impulsive): mean RT
• Venus UFO (Sustained): mean RT
• Color Swatch: max delay time
• Face Switch: overall Rate Correct Score

*Rate Correct Score is based on formula by Woltz & Was (2006) and adapted as described by Vandierendonck (2016):

• N correct trials/(mean RT * total number of trials)

This score can be interpreted as the number of correct responses per second of activity.
*K is a measure of working memory capacity as described by Luck and Vogel (1997):

• K=S(H – F)

where K is the memory capacity, S is the size of the array, H is the observed hit rate, and F is the false alarm rate.

Cost vs Overall Task Performance

For many tasks, the RT cost between conditions is traditionally used as the metric of interest (e.g., in Stroop, the difference between the congruent and incongruent condition). Condition cost is calculated for most tasks in the aceR processing code for analysis. However, there is some evidence cost scores may have lower test-retest reliability than overall performance scores (see Enkavi et al., 2019). Particularly in tasks in which conditions are intermixed (vs blocked), overall task performance (particularly Rate Correct Score) may be a better representation of an individuals’ performance.

Additional Resources

New to R? Swirl is a great way to learn the basics

• Click here to see the swirl website
• Click here to download a quick Rscript to help you get set up with swirl

Got the basics, but want to know more?

We recommend R for Data Science by Garrett Grolemund and Hadley Wickham. R for Data Science is a free, online textbook that will guide you through using tidyverse to analyze data and includes walkthroughs that use sample data so you can follow along. A basic understanding of R will be needed to follow along this book.

Visualizing Data in R

We recommend the ggplot package in R. Here is a handy cheatsheet to see ggplot’s capabilities and the basics for different plot types.
See the Guides page for more helpful information.

Troubleshooting

Here are some common errors people run into and their solution. We will add to this as we notice common issues.

A note on updating packages and R:
As with all software tools, there are often version updates of both R and the individual packages that can be used with R. We do our best to specify/notify you of the minimum version requirements to run aceR. However, there may be instances where a new update (either in packages or R) has been made available, but the aceR package or the packages/tools called on in the templates are not yet updated to be compatible with these changes. If you get errors or warnings related to packages not being available for a certain R version, it might be advisable to install an older version of R or the package to ensure compatibility. You can find links to older versions of R here, and can use google to find instructions for downloading older versions of specific packages.

Package installation:

devtools::install_github("joaquinanguera/aceR")
Downloading GitHub repo joaquinanguera/aceR@master
These packages have more recent versions available.
Which would you like to update?
1: BH (1.66.0-1 -> 1.69.0-1) [CRAN]
2: clipr (0.4.1 -> 0.5.0 ) [CRAN]
3: colorspace (1.3-2 -> 1.4-0 ) [CRAN]
4: data.table (1.11.8 -> 1.12.0 ) [CRAN]
5: pillar (1.3.0 -> 1.3.1 ) [CRAN]
6: purrr (0.2.5 -> 0.3.0 ) [CRAN]
7: readr (1.1.1 -> 1.3.1 ) [CRAN]
8: rlang (0.3.0.1 -> 0.3.1 ) [CRAN]
9: tibble (1.4.2 -> 2.0.1 ) [CRAN]
10: CRAN packages only
11: All
12: None


The above text is indicating that certain packages have an update available. You don’t usually have to update any packages, but you can choose to update some or all of your packages if you wish. Follow the prompt to make any updates you choose. Note the list of packages you see may differ depending on which packages need updated.

library(aceR)
Error: package or namespace load failed for ‘aceR’ in loadNamespace(i, c(lib.loc, .libPaths()),
versionCheck = vI[[i]]):namespace ‘rlang’ 0.2.2 is already loaded, but >= 0.3.0 is required


If you get something like this, you may need to update a certain package. In this case, the error is pointing to the ‘rlang’ package. Re-installing/updating the rlang package solved the issue. Note you may need to re-start your R session to have package updates take effect.

Processing:

Error in is_character(x) : object 'module' not found

This may be an indication that you updated the aceR package, but didn’t reset your R workspace or other dependent packages have not been updated. First, make sure the devtools package is up to date. Then try starting a new R session by going to ‘session’ -> ‘restart session’ or closing R, being sure to NOT SAVE your workspace and re-opening.

Error in mutate_impl(.data, dots) :
Evaluation error: Column `pid` can't be converted from integer to character.

This error is commonly found when trying to use the proc_by_module function, particularly when processing data from a csv file (rather than using the load_ace_bulk function). The proc_by_module function requires all data to be of type character and must be nested by module. Using the following code should resolve the problem
data=read.csv(file="~/path/to/data.csv")'
data[] <- lapply(data, as.character)
data=data %>%
group_by(module) %>%
nest()
data_averages=proc_by_module(data, rm_outlier_rts_range=c(200,NA),verbose=TRUE)

data=load_ace_bulk(path, pulvinar =TRUE)
Error: No common type for `x$condition` <character> and `y$condition` <logical>.

This error has most often occurred when processing legacy ACE Classroom data downloaded from the UCSF pulvinar server If you get an error related to no common type for condition, this is likely due to the condition column being empty for a module. SpatialSpan and BackwardSpatialSpan are the most likely culprits, but it could be any module. Check the individual module files and enter a character string into the condition module for all lines with data (e.g., you might enter ‘forward’ for the condition in SpatialSpan and ‘backward’ for BackwardSpatialSpan). It must be a character string and not a number. Once the files have been updated, the code should work.

data_averages = proc_by_module(data, verbose=TRUE, app_type = 'explorer')
Error: Problem with `mutate()` column `demos`.
ℹ `demos = map(1:n(), ~df$data[df$module == DEMOS][[1]])`.
x subscript out of bounds

This error occurs if the demographics module wasn’t loaded in the load_ace_bulk step. Please ensure that the demographics file is located in the path directory you specified in the load_ace_bulk step. For more information on organizing files, please see our Organizing Files Guide.

FAQ

Why are you using R?

R is a free, open source programming environment that allows individuals to share code via packages. There are thousands of packages available with more being added every day. The R community is a vibrant one, and if you are looking for a package (or function) to process your data, it’s likely already there.

Can I use SPSS, JMP, (other statistical analysis software) to analyze the data?

We provide trial level data in a csv format that can be imported and used in other analysis software. The processing scripts to get summarized data for each participant is only available in R. However, the processing template includes code to write out the processed data that you can analyze with your program of choice.

What if I’d like something added to the processing output?

Unfortunately, we can’t accommodate all requests at this time.

Will you be adding new features?

Probably! Our goal is for the package to meet all of your processing needs. We are working to incorporate additional information that we find useful for analysis (for example, previous trial accuracy). Additionally, as new functions are created for data analysis, we aim to incorporate them into the main aceR package so that you don’t need to download and run additional files or scripts.

How will I know if something new is added?

We endeavor to report the date of the latest update to both the aceR package and processing template. Check this website occasionally to see if a new update is available.

What if I have a problem with the package?

We can offer limited support for troubleshooting if you encounter a problem. Please see trouble shooting tips page for some common issues and solutions.

If the package is running slower than expected, say, or something working but not being defined in the way you think would be best, you should consult someone. If you don’t know anyone who can look over your code and see if it can be sped up, or if another function would suit your needs better, a useful place to ask for help is The R section of StackOverflow.