BATD is an R package for extracting, analyzing, and visualizing vibrotactile data from Cortical Metrics Brain Gauge devices. It provides comprehensive tools for processing data from both newer Brain Gauge devices (NF format) and older Research Edition devices (OF format).
- Automatic Format Detection: Intelligently detects NF vs OF formats
- Unified API: Single
BATD_extract()function handles both formats - Modular Architecture: Clean separation of concerns with helper functions
- Configuration System: YAML-based site protocol configuration
- Comprehensive Testing: 57+ passing tests for reliability
- Better Documentation: Improved function documentation and examples
- Data Extraction: Parse raw Brain Gauge output files into structured dataframes
- Protocol Recognition: Automatically label protocols by site-specific configurations
- Performance Analysis: Calculate thresholds, accuracy, reaction times, and reversals
- Visualization: Generate publication-ready plots for individual or batch analysis
- Multi-Session Support: Handle participants with multiple testing sessions
- Run Detection: Identify repeated protocol runs within sessions
# Install devtools if needed
if (!require("devtools")) install.packages("devtools")
# Install BATD
devtools::install_github("HeJasonL/BATD")# Clone the repository
git clone https://github.com/HeJasonL/BATD.git
# Install in R
R CMD INSTALL BATDlibrary(BATD)
# Extract data from mixed or unknown formats
files <- list.files(pattern = "\\.txt$")
data <- BATD_extract(files, site = "UCLA")
# Analyze all participants
results <- BATD_analyze_all(data)
# Generate plots for all participants
BATD_plot_all(data)# For newer Brain Gauge devices (NF format)
data_nf <- BATD_extract_NF(list_of_filenames, site = "KKI")
# For older Research Edition devices (OF format)
data_of <- BATD_extract_OF(list_of_folders, Site = "JHU")
# Explicitly specify format if auto-detection fails
data <- BATD_extract(files, site = "UCLA", format = "NF")# Analyze single participant
participant_data <- data[data$id == "001", ]
analysis <- BATD_analyze(participant_data)
# Analyze all participants
all_analysis <- BATD_analyze_all(data)
# Plot single participant
plot <- BATD_plot(participant_data)
# Batch plot all participants (saves PDFs)
BATD_plot_all(data)BATD includes protocol configurations for the following research sites:
- KKI: Kennedy Krieger Institute
- CCH: Cincinnati Children's Hospital
- UCLA: University of California, Los Angeles
- JHU: Johns Hopkins University
- EU-AIMS: European Autism Interventions
- SPIN: Social Pediatric Innovation Network
- CARE: CARE Network
- STES: STES Study
- ARBA1-4: ARBA Study Sites
Don't see your site? Use site = "NA" for generic protocol labeling or contact the maintainer to add your site.
| Function | Description |
|---|---|
BATD_extract() |
Recommended: Unified extraction with automatic format detection |
BATD_extract_NF() |
Extract data from newer Brain Gauge format (NF) |
BATD_extract_OF() |
Extract data from older Research Edition format (OF) |
detect_file_format() |
Detect whether file is NF or OF format |
| Function | Description |
|---|---|
BATD_analyze() |
Analyze single participant data |
BATD_analyze_all() |
Batch analyze multiple participants |
| Function | Description |
|---|---|
BATD_plot() |
Generate plots for single participant |
BATD_plot_all() |
Generate plots for all participants (saves PDFs) |
| Function | Description |
|---|---|
load_config() |
Load YAML configuration files |
get_site_protocols() |
Get protocol configurations for a site |
get_protocol_name() |
Look up protocol name by ID and site |
get_defaults() |
Access default analysis parameters |
BATD returns dataframes with the following key columns:
id: Participant identifierrace,gender,handedness,birthYear: Demographics
date,time: When protocol was completedsession: Session number (multiple testing dates)run: Run number (repeated protocols within session)site: Data collection site
protocol: Protocol number (e.g., 100, 900)protocolName: Human-readable protocol namenumberofPracticeTrials,numberofTestTrials: Trial countsISI: Inter-stimulus interval
stim1amplitude,stim2amplitude: Stimulus amplitudesstim1frequency,stim2frequency: Stimulus frequenciesstim1duration,stim2duration: Stimulus durationsastim*: Adapting stimulus parameters (for adaptation protocols)
trialNumber: Trial indexvalue: Stimulus value on this trialresponse: Participant's responsecorrectResponse: Whether response was correct (0/1)responseTime: Reaction time in milliseconds
format: "NF" or "OF"extractedBy: BATD version used for extractionoriginalFilename: Source filename
BATD recognizes and analyzes the following protocol types:
- Simple Reaction Time (SRT)
- Choice Reaction Time (CRT)
- Static Detection Threshold (SDT)
- Dynamic Detection Threshold (DDT)
- Static Detection with Adaptation (ISI 30, ISI 100)
- Simultaneous Amplitude Discrimination (SMAD)
- Sequential Amplitude Discrimination (SQAD)
- Amplitude Discrimination without Adaptation (ADT)
- Amplitude Discrimination with Single Site Adaptation (ADTssa)
- Amplitude Discrimination with Dual Site Adaptation (ADTdsa)
- Dual Staircase Amplitude Discrimination (up/down)
- Simultaneous Frequency Discrimination (SMFD)
- Sequential Frequency Discrimination (SQFD)
- Temporal Order Judgement (TOJ)
- Temporal Order Judgement with Carrier (TOJwc)
- Duration Discrimination (DD)
Add your own site protocols by editing config/site_protocols.yaml:
sites:
YOUR_SITE:
name: Your Site Name
location: City, State
protocols:
- id: 100
name: Static Detection Threshold
parameters:
num_test_trials: 20# Check file format before extraction
detection <- detect_file_format("path/to/file.txt")
cat("Format:", detection$format,
"\nConfidence:", detection$confidence,
"\nReason:", detection$reasoning)
# Validate format matches expectation
validate_file_format("path/to/file.txt", expected_format = "NF")# Filter by protocol
sdt_data <- data[data$protocolName == "Static Detection Threshold", ]
# Calculate group statistics
library(dplyr)
group_stats <- all_analysis %>%
group_by(site) %>%
summarise(
mean_threshold_SDT = mean(threshold_SDT, na.rm = TRUE),
mean_accuracy_SDT = mean(accuracy_SDT, na.rm = TRUE)
)
# Export results
write.csv(all_analysis, "batd_results.csv", row.names = FALSE)- Single
.txtfile per participant - Colon-delimited key-value pairs
- Used by current Brain Gauge devices
- Example:
participant_001.txt
- Nested folder structure
- Tab-delimited files
- Used by Brain Gauge Research Edition
- Structure:
ParticipantID/YYYY-MM-DD/ProtocolNumber/
BATD requires the following R packages:
dplyr: Data manipulationstringr: String operationsggplot2: Plottingggpubr: Plot arrangementdata.table: Efficient data bindingplyr: Data splitting and combiningyaml: Configuration file parsing
These will be automatically installed when you install BATD.
If you use BATD in your research, please cite:
He, J. L. (2026). BATD: Batch Analysis of Tactile Data (Version 1.5.0)
[Computer software]. GitHub. https://github.com/HeJasonL/BATD
- v1.5.0 (2026-02): Major refactoring - modular architecture, automatic format detection, comprehensive testing
- v1.4.0: Previous stable release
- Earlier versions: Initial development and site-specific customizations
Contributions are welcome! Please feel free to:
- Report bugs via GitHub Issues
- Suggest new features
- Submit pull requests
- Add support for additional research sites
For questions, issues, or site-specific protocol configurations, please contact:
- Jason L. He: jasonhe93@gmail.com
- GitHub Issues: https://github.com/HeJasonL/BATD/issues
License information to be determined. Please contact the maintainer for usage permissions.
Maintainer: Jason L. He (jasonhe93@gmail.com)
Repository: https://github.com/HeJasonL/BATD