A MATLAB and Python toolkit for loading and analyzing behavioral data from MotoTrak systems. This repository includes GUI analysis tools, file conversion utilities, and standalone data-loader scripts you can call from your own custom code.
Disclaimer: This README file was AI-generated, but checked for accuracy by a human.
MotoTrak Analysis is designed to process MotoTrak behavioral training data for devices such as pull, knob, and lever modules. You can use it in two common ways:
- Run the MATLAB GUI/analysis workflow
- Call the reader scripts directly from your own MATLAB or Python analysis pipeline
If you are writing your own analysis scripts, start with these readers:
- MATLAB: MATLAB/MotoTrakFileRead.m
- MATLAB: MATLAB/ArdyMotorFileRead.m
- Python: Python/MotoTrakFileRead.py
- Python: Python/ArdyMotorFileRead.py
Binary format details are documented in:
session = MotoTrakFileRead('D:\Data\Animal01\session02.MotoTrak');
% Example custom analysis
trial_count = numel(session.trial);
mean_hits_per_trial = mean(arrayfun(@(t) numel(t.hit_times), session.trial));
fprintf('Trials: %d, Mean hits/trial: %.2f\n', trial_count, mean_hits_per_trial);% Returns data struct and file format version
[data, version] = ArdyMotorFileRead('D:\Data\Animal01\session01.ArdyMotor');
% Example custom analysis
n_trials = numel(data.trial);
hit_trials = sum(arrayfun(@(t) strcmpi(char(t.outcome), 'H'), data.trial));
fprintf('Trials: %d, Hits: %d\n', n_trials, hit_trials);You can import the Python reader modules directly in your scripts.
from MotoTrakFileRead import MotoTrakFileRead
session = MotoTrakFileRead(r"D:\Data\Animal01\session02.MotoTrak")
print("version:", session.get("version"))
print("subject:", session.get("subject"))
print("trials:", len(session.get("trial", [])))from ArdyMotorFileRead import ArdyMotorFileRead
data, version = ArdyMotorFileRead(r"D:\Data\Animal01\session01.ArdyMotor")
print("version:", version)
print("subject:", data.get("subject"))
print("trials:", len(data.get("trial", [])))python Python/example_usage.py --ardymotor "D:/Data/session01.ArdyMotor"
python Python/example_usage.py --mototrak "D:/Data/session02.MotoTrak"
python Python/example_usage.py --ardymotor "D:/Data/a.ArdyMotor" --mototrak "D:/Data/b.MotoTrak"Supported session-file formats:
.MOTOTRAK(MotoTrak 2.x data files).ArdyMotor(legacy format)
- Graphical Analysis - Interactive visualization of behavioral session data across multiple files
- Session Trace - Detailed trace viewing of individual training sessions
- Daily Reports - Generate comprehensive daily performance summaries across animals
- File Editor - Edit metadata (subject, booth, stage) in existing MotoTrak files
- Knob Viewer - Analyze rotational knob task data
- Lever Viewer - Examine lever press task performance
- Pull Viewer - Review pull task sessions
- Session Data to TSV - Export session data to tab-separated values for Excel/statistical software
- PopData to TSV - Convert population data to tabular format
- ArdyMotor Format Conversion - Convert between legacy ArdyMotor and MotoTrak file formats
For users without MATLAB, install the standalone application:
- Download and run
mototrak_analysis_v1p20_installer_win64.exefrom compiled/installers/ - Follow the installation wizard (MATLAB Runtime will be installed automatically if needed)
- Launch "MotoTrak Analysis" from your Start Menu or desktop shortcut
System Requirements:
- Windows 10 or later (64-bit)
- ~1 GB disk space for MATLAB Runtime
- See compiled/redistribution_files_only/readme.txt for details
For users with MATLAB who want to modify or extend functionality:
- Clone or download this repository
- Add the repository folder to your MATLAB path
- Run
MotoTrak_Analysisin MATLAB to launch the main interface
Requirements:
- MATLAB R2019b or later (recommended)
- Required MATLAB toolboxes are listed in [MATLAB/src/Required Toolbox Functions/required_matlab_products.txt](MATLAB/src/Required Toolbox Functions/required_matlab_products.txt)
Note: the collated entry-point script is MATLAB/MotoTrak_Analysis.m.
% Launch the main analysis interface
MotoTrak_Analysis
% Or run specific tools directly:
MotoTrak_Graphical_Analysis % Interactive data visualization
MotoTrak_Daily_Report % Generate daily summary reports
MotoTrak_File_Editor % Edit file metadata
MotoTrak_SessionData_to_TSV % Export session data to TSVOn first launch, the program creates a configuration file at:
- Windows:
%LOCALAPPDATA%\Vulintus\MotoTrak Analysis\
You can customize default paths and settings through the configuration interface or by editing the config file directly.
MotoTrak_Analysis/
├── MATLAB/
│ ├── MotoTrak_Analysis.m # Main MATLAB entry point
│ ├── ArdyMotorFileRead.m # MATLAB legacy-file reader
│ ├── MotoTrakFileRead.m # MATLAB MotoTrak-file reader
│ └── src/ # MATLAB analysis modules
├── Python/
│ ├── ArdyMotorFileRead.py # Python legacy-file reader
│ ├── MotoTrakFileRead.py # Python MotoTrak-file reader
│ └── example_usage.py # Python usage example
├── MotoTrak_File_Structure.md # Binary-format field layout
├── compiled/ # Compiled standalone version
└── README.md
- MATLAB file reading: MATLAB/MotoTrakFileRead.m, MATLAB/ArdyMotorFileRead.m
- Python file reading: Python/MotoTrakFileRead.py, Python/ArdyMotorFileRead.py
- MATLAB utilities and GUI modules: MATLAB/src/
Copyright © Vulintus, Inc. All rights reserved.
For questions or issues, please contact Vulintus, Inc.
If you use this toolbox in your research, please cite:
MotoTrak Analysis Toolbox, Vulintus, Inc., https://github.com/Vulintus/MotoTrak_Analysis
- 2025-06-26 - Latest collation with inter-press interval analysis
- 2019-09-26 - Added lever module press-time outputs
- 2016-08-08 - Combined analysis GUI integration
- 2015-07-06 - Initial TSV export functionality created