schooling_fish

This repository contains codes and data used for analysis in the article "Noise-Induced Schooling of Fish". The first release is archived at

Citation

Jhawar, Jitesh, Richard G. Morris, U. R. Amith-Kumar, M. Danny Raj, Tim Rogers, Harikrishnan Rajendran, and Vishwesha Guttal. "Noise-induced schooling of fish." Nature Physics 16, no. 4 (2020): 488-493. https://www.nature.com/articles/s41567-020-0787-y

Note: Codes have been tested in a Linux and Windows 10 machine. A few adjustments may be required for Mac users. For all the inputs set the working directory in MATLAB to where the input files are saved.

Codes for detection and tracking

1. Detection: Detection of fish from a video can be done using the MATLAB code detection.m in /tracking/detections.m.

   1. Run the file detections.m which will prompt you to select the video for detection.
   2. Use sample video sample_vid.avi in the folder /sample as input for the code.
   3. A figure pops up displaying a frame of the video. Click and drag to select the region where you want the fish to be detected, right click and select copy position, minimize the window and hit ENTER on the MATLAB console to begin tracking.

   -- Note: It could be the entire arena where the fish swim or a small region where they are isolated or is of interest, also make sure not to close the window after selecting the region, just minimize it.
   -- The time to run this code would depend on the length of the video and your system. For the sample video provided by us it would take approximately 40 mins.

   4. Individual fish are detected and their coordinates at every frame is stored in the folder /sample as detected_sample_vid.mat and detected_sample_vid.csv.

   Note: Change 'steps' in the code to steps > 1 for skipping frames between detection.

2. Tracking: A MATLAB code /tracking/loop_track.m can be used for tracking individuals between frames. This code uses the Kalman-filter code which we downloaded from Mr Student Dave’s website tutorial. Compared to /tracking/detections.m this code can be expected to take substantially less time.

   1. Use detected_sample_vid.mat as the input when prompted.
   2. The output is a set of files with name as in tracked_sample_vid_###to###.mat, where ### is the start-frame number and end-frame number respectively in the .mat file. These files are also stored in the folder /sample.

3. Stitching different output files: A MATLAB code /tracking/meta_analysis.m can be used to stitch the output data from above code loop_track.m into one single file called rawdata_track.csv. This output will be stored in the folder /sample.

   Note: Owing to size of video files, we have provided only a sample video for group size (N) 60.

Codes for Figure 2

1. Generate polarization time-series for sample video: The MATLAB code /data_analysis/op_calculate.m can be used to compute the polarization/order parameter.
   1. The input for this code is rawdata_track.csv in the /sample. For the data used in the paper select the ones provided in /data/raw_data/. For e.g,/data/raw_data/15/raw_data15tr1.csv as input file.
   2. The output vel_x, vel_y are saved as <file_name>_vel_x_y.mat for further analysis by the users.

To generate Fig 2, we used different N and multiple trials for each N. To reproduce these plots, one must first generate the corresponding complete-time series (i.e. each trial of around 50 minutes at ~8 fps). To do this, run the rawdata files /data/raw_data for different N. The time series and histogram plots are generated using vel_x and vel_y for various group size and trials.

Codes for Figure 3

1. Drift and Diffusion functions can be computed by running the MATLAB code /data_analysis/vector_drift_diff.m

Input required: (vel_x.mat and vel_y.mat) computed from vel_x, vel_y computed as explained in section ‘Codes for Figure 2’ or synthetically generated using /simulations/interact.m as explained in next section, ‘Codes for Figure 4’.

Codes for Figure 4

1. A MATLAB code /simulations/interact.m used for simulating the pairwise and ternary interaction models.
   1. For pairwise set the parameter controlling ternary interaction rate (h) = 0 in the code with s = 0.25 and p = 4 in line 11 and sigma=3 in line 12.
      1. The outputs (polarization vectors) vel_x.mat and vel_y.mat are saved when required.
      2. The saved output can be used to plot drift and diffusion functions using the codes in /data_analysis/vector_drift_diff.m
   2. For Ternary set the parameter controlling ternary rate (h)=0.3 in the code with s = 0.25 and p = 0.01 in line 11 and sigma=3 in line 12.(line 11).
      1. The outputs (polarization vectors) vel_x.mat and vel_y.mat are saved when required.
      2. The saved output can be used to plot drift and diffusion functions using the codes in /data_analysis/vector_drift_diff.m

GA simulations

1. In the folder /Simulations/GA you will find the codes to run Genetic algorithm optimization for identifying rates of interaction between fish and the order of alignment interactions.
   1. In the sub-folder, /Copyinginteractions the alignment model is based on a hierarchy of models where the fish copy the direction from another fish from a set k other fish.
   2. In the sub-folder, /averaginginteractions the alignment model is based on a hierarchy of models where the fish choose the average direction of k other fish.

For both the cases, Run the MainFile.m to begin the optimization. For standalone codes of just the model (copying and averaging type), refer to the folder /GA/standalone.

Known Issues

Time series of Mx and My

• Tracking code is prone to errors due to the quality of videos and detection algorithm limitations. For example, we noticed sudden jumps in the estimation direction vectors of fish, but at a sufficiently low frequency. To ensure these errors do not affect our conclusions, we used a number of different approaches which includes, for example, discarding such individuals from the calculations of the order parameter for that instant. We found that the main conclusions (based on Fig 2 and 3 of the main text) do not change.

• We show first and second jump moments for one such re-analysis below (this was not a part of the manuscript); we have removed individuals whose direction of motion across 0.12 seconds changed by more than 20 degrees.

Note:

These codes have been tested on the MATLAB version R2018a running on Ubuntu Linux Machine 18.04 LTS. The codes may not run on other versions of MATLAB or OS and some modifications (and configuration) may be required.

We recommend the users to use their own tracking code.