Automatic Pre-Analysis of Behavioural Test Data

Reproducible R pipeline for SMART Video Tracking exports — Open Field (OF) & Elevated Plus Maze (EPM)
ProjetR — Kourrich Lab, Université du Québec à Montréal (UQAM)

Panlab SMART is a Video Tracking software used in psychopharmacology research labs to automate the evaluation of behavior.

This project automates the exploratory data analysis (EDA) of data produced with Panlab's SMART Video Tracking software. This solution sits between SMART and downstream analyses (e.g. GraphPad Prism):

• It replaces a manual workflow (hand-edited .xls exports + Prism) with a scripted pipeline that detects the assay protocol, performs data quality control, computes descriptive statistics, and generates publication-style figures and reports.
• It standardizes large datasets manipulations, produces first-pass descriptive statistics and figures, and exports .png, .xlsx, and .pdf deliverables—in about two minutes for cohort-scale datasets to increase reliability.

Note

Scope: descriptive statistics (mean, SD, SEM, n) and standardized visualizations. Inferential testing (ANOVA, post-hoc, etc.) remains a separate step to perform with tools such Prism if needed.

Table of contents

• Quick Start
  • Prerequisites
  • Installation
  • Run an analysis
  • Troubleshooting
• Features
• How it works
  • Workflow overview
  • Project structure
  • Supported protocols
• Rationale
  • The problem
  • The solution
  • Results - Before vs after
• Design Notes
• Limitations & Roadmap
• Skills Demonstrated
• Author & Context
• License

---

Quick Start

Prerequisites

• R 4.2.1 and RStudio (required)

• Internet connection for first-time package and TinyTeX installation only

• SMART Summary Report configured per test family before export to ensure reproductibility (with fixed output filetype (.xls), variable names and count)

• Open Projet_Automatisation_Analyse_R.Rproj — the portable project root (do not rename project subfolders; the pipeline expects fixed paths)

Installation

First-time setup follows the procedure in the user manual (Installation section; screenshots in Aide/).

1. Unzip Projet_Automatisation_Analyse_R V.x.y.zip.
2. Move the extracted folder anywhere on disk (desktop, lab share, etc.) — the project is portable.
3. Open the folder and confirm the project strurcture matches Project structure.

Caution

Do not rename project subfolders; the pipeline expects fixed paths

4. Double-click Projet_Automatisation_Analyse_R.Rproj - the portable project configuration - to open the project in RStudio.

Note

console pane fills most of the window

5. In Src/, select all .R scripts, right-click, and open them in RStudio so every script appears as a tab above the console.
6. Switch to the file Analyser.R's tab.

Warning

A yellow console message indicates the project is not synchronized — pinned packages are missing.

7. Run renv::restore() (confirm with y, then Enter). Installation is complete when an orange chevron appears in the console:

8. Run the full Analyser.R script: Ctrl+Shift+S, then select in the dialog, an .xls file ( exported by SMART ) to analyse.

9. If TinyTeX is not detected, the pipeline installs it automatically (requires internet).

10. Report files are generated under Figures/ and Data/Output/ — this confirms a successful install.

After setup

• Close RStudio and save the workspace when prompted. The .Rproj file remembers open scripts, command history, and figures for the next session.
• Repeat steps 7–10 only if the project folder is moved or libraries are reset.
• Internet is required only for renv::restore() and TinyTeX; offline use is fine afterward.
• Place SMART .xls exports in Data/Raw/ before each run (output names derive from the input file name).
• TinyTeX: the initial download is quick; the first PDF build (LaTeX pass on the temporary .md) is slow — subsequent runs are much faster and TinyTeX does not need reinstalling on the same machine.

Run an analysis

Tip

Two sample SMART export files for the supported protocols are included for desmonstration in Data/Raw/:

• Test_OF.xls (Open Field)
• Test_EPM_GROUPE_16-1.xls (Elevated Plus Maze)

Use them for a first test run after installation or as reference templates for SMART Summary Report settings. See Supported protocols for required SMART export settings (Exps_mastertable) for more information.

1. Place SMART exports (.xls) in Data/Raw/ (or use the samples already there).
2. In RStudio, open Src/Analyser.R

Important

This is the only script end users should run.

3. Run the full script with Ctrl+Shift+S.
4. Select the .xls file to analyze in the dialog.
5. Confirm assay detection in the console (Test detecté OF / Test detecté Elevated Plus Maze).
6. Collect outputs under Figures/ and Data/Output/.

Troubleshooting

Issue	Action
no package named 'XXX'	Run renv::restore() in the R console
pdf latex not found	tinytex::uninstall_tinytex() then tinytex::install_tinytex()
Persistent library issues	Run Src/Packages_reset.R, then reinstall via renv::restore()

See the user manual for screenshots and extended troubleshooting.

Note

User manual: see Aide/Manuel utilisateur Projet R.pdf for full installation, usage, extension procedures and extended troubleshooting.

---

Features

Quality control — Protocol auto-detection (Open Field (OF) vs Elevated Plus Maze (EPM)) by matching the SMART export against Exps_mastertable (test name, protocol acronym, acquisition duration, split interval, apparatus dimensions).

Open Field (OF, 5 figures) — Total distance by genotype and sex; cumulative distance over time; zone-specific trajectories (including centre vs periphery).

Elevated Plus Maze (EPM, 10 figures) — Locomotion, open-arm time and entries; stratification by age class (Juvenile → Aged) and sex (faceted plots).

Exports per run (from a SMART .xls input)

The program generates figures and reports each time it is run with new input data.

Output	Location	Naming pattern
.png	Figures/Graphs/	{input_filename}_{GraphXX}.png
.xlsx	Data/Output/	Rapport_{input_filename}.xlsx
.pdf	Figures/PDFs/	Rapport_PDF_Analyse_{input_filename}.pdf

(Spaces in the input filename are replaced with _.)

---

How it works

Workflow overview

From SMART acquisition to report files: legacy manual path, automated path, then the R orchestrator in detail.

Before — manual (several hours · ~10 observations)

After — automated (~2 minutes · hundreds of observations)

Diagram legend: #4b5563 cylinder = SMART · #2268BC cylinder = R pipeline · #BDBFC2 border / #f9fafb text on software nodes · green = spreadsheet (.xls / .xlsx) · blue = .png · red = .pdf

R pipeline — orchestrator (Analyser.R)

Analyser.R phases: (1) load packages & TinyTeX check, (2) import and type .xls data, (3) QC + HUB → Test_*.R, (4) export via Mes_Fonctions.R + Rapport_PDF_Analyser.Rmd.

Project structure

Fixed layout — renaming folders breaks path resolution (see user manual).

Projet_Automatisation_Analyse_R/
  docs/                              # Workflow diagrams (.mmd / .svg); see docs/diagrams.md
  Aide/                              # User manual & illustrative figures
    Manuel utilisateur Projet R.pdf
  Data/
    Raw/                             # Input .xls files (SMART exports)
    Output/                          # Generated .xlsx workbooks
  Figures/
    Graphs/                          # .png figures
    PDFs/                            # .pdf reports
  Src/
    Analyser.R                       # Main script — run this only (QC, HUB, export)
    Test_OpenField.R                 # OF-specific graphs & tables
    Test_ElevatedPlusMaze.R          # EPM-specific graphs & tables
    Mes_Fonctions.R                  # Custom export helpers (Excel, PNG)
    Rapport_PDF_Analyser.Rmd         # PDF report template
    Aide_gestion_packages.R          # Package management cheat sheet
    Packages_reset.R                 # Reset libraries / TinyTeX (troubleshooting)
  renv/                              # Pinned package environment (renv)
  Projet_Automatisation_Analyse_R.Rproj

Key packages: tidyverse (tidyr, dplyr, ggplot2, forcats, …), readxl, openxlsx, chron, rmarkdown, knitr, kableExtra, tinytex, renv.

Supported protocols

Settings must match Exps_mastertable and the SMART Summary Report export:

Assay	SMART acronym (VarExm2)	Acquisition (VarExm3)	Split interval (VarExm4)	Apparatus (V×H cm)
Open Field (OF)	OF	30:00	05:00	72 × 65
Elevated Plus Maze (EPM)	EPM	05:00	00:00	72 × 65

Other protocols trigger an explicit stop: protocol not recognized.

---

Rationale

The problem

Previously, the research team had to:

1. Manually extract data from SMART
2. Edit .xls exports by hand (column selection, grouping, ad hoc calculations)
3. Build graphs and tables in GraphPad Prism, step by step

For roughly 10 observations and a few figures, this took several hours. Scaling to hundreds of observations with consistent plots across genotypes, sex, and age was impractical. Outputs varied between experimenters, limiting reproducibility.

The solution

Two complementary layers:

Layer	Role
SMART configuration	Standardized Summary Report → .xls exports per test family (constant variable names and count; only values change)
ProjetR (this repo)	Import .xls → QC / HUB routing → assay-specific scripts → .png, .xlsx, .pdf

Results - Before vs after

	Manual (Prism)	Automated (this project)
Typical scale	~10 subjects, few graphs	Hundreds of observations
Deliverables	Hand-built Prism figures	Dozens of plots, descriptive tables, .pdf report
Time	Several hours	~2 minutes
Reproducibility	Operator-dependent	Same SMART config + same scripts

Workflow diagrams: see Workflow overview.

---

Design Notes

Conventions enforced by ProjetR (details in the user manual):

• SMART column names use dots (e.g. Subject.Genotype) — required for parsing.
• Plot objects: Graph01, Graph02, … (GraphXY, X = tens, Y = units).
• Summary tables: suffix _stats in the dataframe name (e.g. SousDF_*_stats).
• Link plots to tables: comment() tag Df.GraphXX on every dataframe used for export (missing tag → export error).
• SMART exports are read as .xls; the analysis workbook is written as .xlsx (openxlsx).
• Wild-type (WT) genotypes are ordered first for consistent comparison plots.
• Error bars show SEM; individual data points are overlaid on bar charts.
• Adding a new assay: create Src/Test_Nomdutest.R, extend Exps_mastertable, add an else if branch in the Analyser.R HUB.

---

Limitations & Roadmap

Current limit	Possible extension
Two assays (OF, EPM)	New Test_*.R + Exps_mastertable row (see user manual)
Interactive file picker (file.choose())	Default path from Data/Raw/ or batch mode
Descriptive stats only	Integrated inferential tests
Requires SMART Summary Report .xls exports	Documented SMART templates per assay

Prism (or R) may still be used for confirmatory statistics or custom models; this tool targets repetitive pre-analysis and reporting.

---

Skills Demonstrated

• R / tidyverse — Data wrangling (dplyr, tidyr), visualization (ggplot2), modular design
• Lab process improvement — Mapped SMART → .xls → Prism bottleneck; paired tool configuration with code
• Data QA — Protocol signature matching before analysis
• Automated reporting — rmarkdown, kableExtra, tinytex (.pdf output)
• Reproducibility — renv for pinned dependencies
• Domain — Preclinical behavioural neuroscience (Open Field, EPM; genotype, sex, age)

---

Author & Context

Wissem Ben Romdhane — ProjetR v1.0, Kourrich Lab (UQAM). Built to bridge SMART → .xls → automated pre-analysis, replacing manual Prism pre-processing and delivering cohort-scale .png, .xlsx, and .pdf outputs in minutes instead of hours.

---

License

Specify a license before public portfolio use (e.g. MIT). Until then, contact the author for reuse terms.