Neural Output Visualization and Analysis
A comprehensive R toolkit for analyzing and visualizing Multi-Electrode Array (MEA) neural data — from raw CSV discovery through PCA trajectory analysis, heatmap generation, and per-metric plotting — with publication-ready figures in a few lines of code.
- 🔍 Smart data discovery — automatically detects MEA folder structure and CSV metadata rows without manual configuration
- 🔥 Raw-data heatmaps — visualize un-normalized electrode activity directly alongside normalized views
- 📊 Per-metric plotting — bar, box, violin, or line plots for any single MEA variable with flexible faceting and filtering
- 🎯 PCA trajectory analysis — track how neural populations evolve over time with publication-ready trajectory and ellipse plots
- ⚡ Zero-code quickstart — one script (
Example/nova_quickstart.R) to change a single path and generate all figures automatically - 📖 Full user guide — illustrated HTML guide with step-by-step walkthroughs for every major function
Four treatment groups traced through PCA space over 7 timepoints (MEA Neuronal Agonists dataset).
PBS control remains near the origin; KA, Gabazine and NMDA each drive distinct network-level responses.
# Install from GitHub
remotes::install_github("atudoras/nova")
# Or using devtools
# install.packages("devtools")
devtools::install_github("atudoras/nova")
# Install from CRAN (coming soon)
install.packages("NOVA")library(NOVA)
# Step 1: Discover your MEA data directory structure
discovery <- discover_mea_structure("path/to/your/MEA_data")
# Step 2: Process MEA data across timepoints and grouping variables
processed <- process_mea_flexible(
main_dir = "path/to/your/MEA_data",
selected_timepoints = c("baseline", "0min", "15min", "30min", "1h", "2h"),
grouping_variables = c("Experiment", "Treatment", "Genotype", "Well"),
baseline_timepoint = "baseline"
)
# Step 3: Run enhanced PCA
pca_results <- pca_analysis_enhanced(processing_result = processed)
# Step 4: Generate PCA plots (scatter, ellipses, loadings)
pca_plots <- pca_plots_enhanced(
pca_output = pca_results,
color_variable = "Treatment",
shape_variable = "Genotype"
)
# Step 5: Plot PCA trajectories across timepoints
trajectories <- plot_pca_trajectories_general(
pca_results,
timepoint_order = c("baseline", "0min", "15min", "30min", "1h", "2h"),
trajectory_grouping = c("Genotype", "Treatment")
)
# Step 6: Create MEA heatmaps (split by genotype, filter to specific treatments)
heatmaps <- create_mea_heatmaps_enhanced(
processing_result = processed,
grouping_columns = c("Genotype", "Treatment"),
split_by = "Genotype",
filter_treatments = c("Vehicle", "Drug_A")
)
# Step 7: Plot a single metric across groups
plot_mea_metric(
data = processed$processed_data,
metric = "MeanFiringRate",
plot_type = "violin",
facet_by = "Timepoint"
)
| Feature | Description |
|---|---|
| Smart CSV row detection | find_mea_metadata_row() scans for the "Treatment" label instead of assuming a fixed row number — handles Axion software export variations automatically |
| Raw-data heatmaps | New use_raw = TRUE parameter in create_mea_heatmaps_enhanced() renders un-normalized electrode data directly |
| Per-metric plots | New plot_mea_metric() function generates bar, box, violin, or line plots for any single MEA variable with full faceting and error bar control |
| Heatmap filter and split | New filter_treatments, filter_genotypes, and split_by parameters in create_mea_heatmaps_enhanced() for focused, side-by-side comparisons |
| Zero-code quickstart script | Example/nova_quickstart.R — set DATA_DIR once, run the script, and all figures are saved automatically |
| Illustrated user guide | Full step-by-step HTML guide with figures available in docs/user-guide/ |
| Function | Description | Key Parameters |
|---|---|---|
discover_mea_structure |
Scans a directory and reports all detected MEA experiments and timepoints | main_dir, verbose |
process_mea_flexible |
Reads and merges CSVs across experiments and timepoints; normalizes to baseline | main_dir, selected_timepoints, grouping_variables, baseline_timepoint |
pca_analysis_enhanced |
Runs PCA on the processed feature matrix; returns scores, loadings, and variance explained | processing_result, scale, center |
pca_plots_enhanced |
Generates a suite of PCA visualizations (scatter, ellipses, loadings, variance) | pca_output, color_variable, shape_variable |
plot_pca_trajectories_general |
Draws mean PCA trajectories across timepoints for each experimental group | pca_output, timepoint_order, trajectory_grouping |
create_mea_heatmaps_enhanced |
Creates heatmaps of MEA metrics by treatment and/or genotype; supports raw or normalized data | processing_result, grouping_columns, split_by, filter_treatments, filter_genotypes, use_raw |
plot_mea_metric |
Bar, box, violin, or line plot for a single MEA variable with optional faceting and filtering | data, metric, plot_type, facet_by, filter_treatments, filter_genotypes, error_type |
NOVA expects a straightforward directory layout that mirrors how Axion BioSystems software exports data:
- Top-level folder: one directory per MEA plate, named
MEAfollowed by digits (e.g.,MEA001,MEA016a) - CSV files: one file per timepoint inside each folder, named
<plate>_<timepoint>.csv(e.g.,MEA001_baseline.csv,MEA001_1h.csv) - Metadata rows: well identifiers and experimental variables (Treatment, Genotype, etc.) are located starting from the row containing the label "Treatment" — NOVA finds this row automatically with
find_mea_metadata_row() - Timepoint names: any string after the underscore is accepted —
baseline,1h,DIV7, or any custom label
MEA_data/
├── MEA001/
│ ├── MEA001_baseline.csv
│ ├── MEA001_1h.csv
│ └── MEA001_24h.csv
├── MEA002/
│ ├── MEA002_baseline.csv
│ └── MEA002_1h.csv
For the fastest path to results, open Example/nova_quickstart.R. The only change required is setting DATA_DIR to your data folder path. Running the script end-to-end will:
- Discover all MEA experiments automatically
- Process and normalize the data
- Run PCA and trajectory analysis
- Generate and save all heatmaps and metric plots to an output folder
No other configuration is needed.
A full illustrated guide covering all functions, parameters, and interpretation of outputs is available at:
The guide includes example figures, annotated code, and recommendations for common experimental designs.
If you use NOVA in published research, please cite:
Escoubas CC, Guney E, Tudoras Miravet À, Magee N, Phua R, Ruggero D, Molofsky AV, Weiss WA (2025). NOVA: a novel R-package enabling multi-parameter analysis and visualization of neural activity in MEA recordings. bioRxiv. https://doi.org/10.1101/2025.10.01.679841
Bug reports and feature requests are welcome via GitHub Issues. Pull requests should follow standard R package conventions and include tests where applicable.
For questions, contact Alex Tudoras at alex.tudorasmiravet@ucsf.edu.
NOVA is released under the GPL-3 License.