Rodent Open field tracker

Warning: Very early working prototype as a proof of concept. No warranty.

Install dependencies: pip install opencv-python opencv-contrib-python numpy pandas numexpr

Analysis:

1. Run Deeplabcut model on video of choice. Copy results (.h5 -file) to same folder as video.
2. Run configurer python config_video.py video.mp4. Also copy and modify EXAMPLE_project_config.ini. Rename it to VIDEOFILENAME_project_config.ini.
   • (optional) run config editor to edit coordinates python config_editor.py video.mp4
3. Run analysis python analyze_video.py video.mp4.
4. (optional) Plot results to video python video_plotter.py video.mp4 or just preview results python video_plotter.py video.mp4 --preview

Input parameters:

VIDEOFILENAME_project_config.ini parameters:
deeplabcut_name = Ending of deeplabcut's result file like "DeepCut_resnet50_Gradu2Jan8shuffle1_100000".
angle_th = If angle is higher and distance is lower than distance_th1, the animal is exploring item (deg).
distance_th1 = First distance threshold to use with angle threshold. Distance is from 'explore_part' to edge of an item (cm).
distance_th2 = Second distance threshold. If animal is closer that this, it is count as exploring.
save_parts = List of part coordinates to be stored. Numpy arrays follows this order.
angle_parts = Parts that are used to calculate angles with items.
sector_parts = Parts that are used to calculate if the animal is in side of an sector.
sectors_criteria = Integer threshold for detecting animal being inside of the an sector.
track_part = Used for plotting trace.
base_part = Used for calculating speed and moved distance.
explore_part = Used to calculate distance from items.
likelihood_limit = Likelihood value of DeepLabCut prediction. If prediction is lower for given coordinate, the coordinates are interpolated with closest good ones.
still_limit = Below this value animal is considered to be still (cm, default 0.1).
visit_gap = Visits that have gap smaller than this are joined.
visit_length = Visits that are shorter are discarded.

VIDEOFILENAME_config.ini parameters:
These parameters are generated by config_video.py.

video_file = Video filename.
video_frame_count = Total frame count of video.
video_fps = Frames per second.
video_length_ms = Video duration in ms.
video_original_size = Original dimensions of video.
video_corrected_size = Dimensions of video after perspective correction.
analysis_start_frame = Frame where analysis is to be started.
analysis_end_frame = End frame of the analysis.
experiment = Experiment name.
experiment_phase = Experiment phase/etc.
field_width = Field width in cm.
field_height = Field height in cm.
field_shape = Field shape.
corners = Coordinates of the corners of the field.
objects = Coordinates and parameters of items.
sectors = Coordinates and parameters of sectors.
transformation_matrix = Transformation matrix for perspective correction.

VLC addon for get video position in frames https://addons.videolan.org/p/1154032/ (press 'e' to jump one frame in VLC).

Output files:
Outputs are stored as NPY -file format (Numpy-arrays). To open NPY -files in Matlab use NPY-Matlab (https://github.com/kwikteam/npy-matlab).

VIDEOFILENAME_intersection.npy = Intersection coordinates of lines from bodyparts to centroid of items and edge of items.
VIDEOFILENAME_intersection_cm.npy = Same as above, but in cm.
VIDEOFILENAME_centroid_distance.npy = Bodypart distance from items centroid.
VIDEOFILENAME_edge_distance.npy = Bodypart distance from items edge.
VIDEOFILENAME_items_point_inside.npy = Boolean array of bodypart points in related to items. '1' if point inside of an item.
VIDEOFILENAME_items_explore.npy = Boolean array of animal exploring items. '1' if all criterias are met.
VIDEOFILENAME_intersection_sector_cm.npy = Same as for items, but for sectors.
VIDEOFILENAME_intersection_sector.npy = Same as for items, but for sectors.
VIDEOFILENAME_centroid_distance_sector.npy = Same as for items, but for sectors.
VIDEOFILENAME_edge_distance_sector.npy = Same as for items, but for sectors.
VIDEOFILENAME_sectors_point_inside.npy = Same as for items, but for sectors.
VIDEOFILENAME_sectors_inside.npy = Boolean array of animal inside of an sector. '1' if all criterias are met.
VIDEOFILENAME_bodyparts.npy = Bodypart coordinates in px.
VIDEOFILENAME_bodyparts_cm.npy = Bodypart coordinates in cm.
VIDEOFILENAME_angle.npy = Animals angle to items.
VIDEOFILENAME_norm_angle.npy= Normalized animals angle to items. 0-180 degrees. 0 degrees means that the animal is looking opposite direction than item.
VIDEOFILENAME_angle_sector.npy = Same as for items, but for sectors.
VIDEOFILENAME_norm_angle_sector.npy = Same as for items, but for sectors.
VIDEOFILENAME_animal_distance.npy = Animals moved distance (cm) between each frame. Total distance is sum of array.
VIDEOFILENAME_animal_speed.npy = Animals speed between each frame (cm/s).
VIDEOFILENAME_results.txt = Analysis results printout.

Troubleshoot:

• Program doesn't work with some of the videos. If extension (container) is AVI and video codec is H264. Convert video to MP4 container with FFMPEG. ffmpeg -i input.avi -c copy output.mp4