Publication

This repository was developed for the analysis of the data generated during the making of the following paper (please cite when using any tools derived from this repository):

• J. Xu, M. Girardi-Schappo, J.-C. Béïque, A. Longtin, L. Maler (2024): Shortcutting from self-motion signals: quantifying trajectories and active sensing in an open maze eLife 13: RP95764

Definitions

• Track file: the MATLAB file generated by the function modules.process_mouse_trials_lib.ethovision_to_track_matfile; please, refer to this function for a detailed description of the data in the track file

Description of this application MODULES

All these modules are under the modules folder

• modules.edge_detector lib containing functions to detect arena edges and holes, used to extract the proper coordinates from the arena pictures in the crop_arena_pictures.ipynb notebook

• modules.helper_func_class lib containig miscellaneous auxiliary functions for all the other libs

• modules.io lib containg I/O functions for most of this applications; a few exceptions happen in the modules.process_mouse_trials_lib lib

• modules.plot_func auxiliary plot functions for all the other scripts

• modules.process_mouse_trials_lib used to convert the Ethovision excel files into track files, and to extract metadata from track files

• modules.traj_analysis a set of functions that are used to calculate all the kinetic, geometric and uncertainty properties of the mouse trajectories

• modules.traj_to_step_matrix lib used to calculate the step probability matrices from the track files.

Description of the folders

• arena_picture contains all the PNG arena pictures for the plot_mouse_trial.py script

• example_fig some example figures from the mouse_deviation_velocity_threshold_example.ipynb notebook

• experiments the preprocessed experimental data... these are track files (under their respective experiment folder), generated by the preprocess_mice_trials.py script; and self-intersection files (generated by the calc_self_intersections.py script)

• figs preliminary figures and analyses generated by the trajectory_analysis_*.ipynb notebooks

• modules where the magic happens

• spatial_distributions scripts that plot distributions of the positions and velocities of the mice; developed by another student

• step_prob_matrices contains the step probability matrices generated by the calc_step_probability_matrix.py script

• step_prob_matrices_view MATLAB plotting of the step probability matrices generated by the calc_step_probability_matrix.py script

Description of the scripts

• calc_self_intersections.py calculates the self-crossings of the track files in the experiments subfolder

• calc_step_probability_matrix.py overlays a square lattice on the arena, and calculates the probability matrices of the mouse steps in between the lattice squares (outputs to step_prob_matrices folder)

• crop_arena_pictures.ipynb this jupyter notebook is used to crop the PNG arena pictures for each experiment, and outputs: arena radius, the hole coordinates, the entrance coordinates in text files under the folder arena_picture

• export_tracks_to_txt.py deprecated... saves the track data to txt files (not useful for anything at the moment)

• mouse_deviation_velocity_threshold_example.ipynb jupyter notebook illustrating some features of this application

• plot_mouse_trial.py a script that can be called from the terminal and used to plot a track MATLAB file under the experiments folder

• preprocess_mice_trials.py batch process Excel Ethovision files into track files and saves them in subfolders of the experiments folder

• test_mouse_trials_lib.py tests many of the functionalities of this application... not all tests are guaranteed to work, since I'm constantly updating some functions, and these updates might not be backwards compatible to the time when I wrote the tests :)

• trajectory_analysis_*.ipynb preliminary statistical trajectory analysis for the paper experiments

Requirements

• python==3.8.2
• numpy==1.24.1
• matplotlib==3.6.2
• scipy==1.8.0
• numba==0.58.1
• networkx==3.1
• pandas==1.2.0
• PIL==9.1.0
• wxPython==4.1.0 (optional)
• zlib==1.0 (optional)