TITLE: Measuring shoal cohesion from video frames in ImageJ using the Interfish Distance plugin
AUTHORS: Matheus Gallas-Lopes, Daniela Varisco Müller, Amanda Patelli Alves, Angelo Piato, Ana P Herrmann

[DESCRIPTION]
This protocol presents a practical ImageJ workflow, built around the Interfish Distance plugin, for quantifying shoal cohesion in laboratory assays. It targets adult zebrafish (Danio rerio) and is readily adaptable to other developmental stages, small teleosts and, with minor adjustments, to additional group-living species. After scale calibration, frames are sampled at fixed intervals (e.g., every 15 s) and the position of each fish is recorded once per frame using a consistent marking rule. The plugin returns inter-individual distances along with nearest- and farthest-neighbor readouts. Results are transferred to a standardized spreadsheet to generate per-video summaries suitable for statistical testing. To capture the group’s spatial footprint, the protocol also details how to derive a group area and perimeter from the same points; perimeter is included as an optional, less commonly reported metric that can complement distance-based cohesion measures. Clear guidance is provided for calibration choices, frame cadence, and copy/export settings, and the protocol encourages good practice such as blinding and inter-rater checks. By consolidating setup, measurement, and basic analysis in one place, this method makes the measurement of shoal cohesion more transparent and reproducible across experiments and laboratories.

[BEFORE_START]
The analysis uses frames extracted from previously recorded videos. Each video should capture one group of fish for a defined observation window (for example, 10–15 minutes) under consistent conditions: same camera position and field of view, stable lighting, fixed frame rate and resolution, and the same tank/apparatus setup. Record control and treatment groups in the same way (timing, handling, acclimation). Avoid heavy compression and remove any on-screen overlays that could hide fish. After recording, choose a single sampling interval (for example, every 15 seconds) to apply to all videos. Export still frames at that interval in advance and organize them in a clear folder structure (one folder per video, group, or condition) with consistent, time-stamped filenames. These prepared images are what you will open in ImageJ to run the Interfish Distance plugin.

To execute the following protocol, ImageJ and the Interfish Distance plugin must be installed.

Required software & files:

ImageJ: download the latest release at https://imagej.net/ij/download.html
Interfish Distance plugin (IJM macro):   


[STEPS]
SECTION: Installing the plugin
2. To install the plugin, first you have to download the ImageJ software, and then the Inter sh distance PLUGIN.ijm archive 

ImageJ software download link: https://imagej.nih.gov/ij/download.html
Plugin download:   
Important: The inter sh distance plugin must be dowloaded in the ImageJ's macros paste. If you already downloaded the plugin in another paste, then copy and paste it in to the ImageJ's macros paste.

SECTION: Session setup: open file and calibrate scale
2. The plugin is used to evaluate shoal behavior from frames extracted from previously recorded videos within a predefined analysis window. First, define a fixed interval (for example, every 15 seconds) that will be applied to all videos. Then export the frames in advance at that interval and organize the images in a clear folder structure (one folder per video, group, or condition) with consistent filenames. These prepared images are the inputs you will open in ImageJ for the measurements that follow.
None. 
None. 
SECTION: Running the Interfish Distance plugin
3. In this section you will measure shoal cohesion on the prepared frames using the Interfish Distance plugin.
SECTION: Data entry and organization
5.  You can organize the analysis in any spreadsheet you prefer. The attached Social cohesion – results.xlsx is simply the template we use. It includes fields for metadata (group/video ID, frame) and cells to paste the three metrics from the plugin (Interfish distance, Nearest neighbor, Farthest neighbor) and Area and Perimeter. Feel free to adapt or build your own table with the same structure so per-video means can be calculated consistently.

  
SECTION: Analysing the data
6. The data analysis must be reviewed for each outcome and each experiment. Most of the time, analyses on the per-video means can use a t-test (two groups) or one-way ANOVA (≥3 groups). When comparing groups across time for the same shoal, use a mixed-effects ANOVA (time = within-subjects factor; group/condition = between-subjects factor). Choose an appropriate post hoc test and report effect sizes and 95% confidence intervals.

Avoid pseudoreplication
The shoal/tank is the experimental unit—not the individual frames. Do not use the number of frames as the sample size. Instead, compute one value per shoal per outcome by averaging across the sampled frames (e.g., the “AVERAGE” row), and use that value in statistical tests. Counting frames inflates N and constitutes pseudoreplication. If you analyze changes over time, treat time as a repeated factor within the same shoal (repeated-measures or mixed-effects models), not as independent samples.

SECTION: Installing the plugin
None. 
SECTION: Installing the plugin
None. 
SECTION: Running the Interfish Distance plugin
3.1. After setting the scale, select the Multi-point tool. For the current frame, place one point at the body center of each fish using the same marking rule for all frames. These points will be used by the Interfish Distance plugin to calculate inter-fish distances.

 

SECTION: Running the Interfish Distance plugin
3.2. Use the figures below as a reference to standardize marking. For each frame, place one point per fish at the visual midpoint of the body (approximately the intersection of mid-length and mid-height). Keep the same rule for all frames and groups.

 


Important: to standardize the fish points, guide yourself using the graphical representation below.
 

SECTION: Running the Interfish Distance plugin
3.3. After placing one point on each fish, run the plugin: go to Plugins → Macros → Interfish distance.

 

Log window 
• For each fish (listed as “Point j”), shows the distances from that point to every other point in the frame.
• For each point, prints “min” (nearest-neighbor distance for that fish) and “max” (farthest-neighbor distance for that fish), followed by a separator line.
• Lists “1. Pairwise distances (unique combinations)”, i.e., all unique pairwise distances among the fish (six values when there are four fish).
• Prints “2. Interfish distance | Nearest neighbor | Farthest neighbor” on three lines:
mean of all pairwise distances (interfish distance IFD)
mean of the per-fish minima (nearest-neighbor mean NND)
mean of the per-fish maxima (farthest-neighbor mean FND)

Results window
• Displays a single row with three columns: Interfish distance, Nearest neighbor, and Farthest neighbor.

 

SECTION: Running the Interfish Distance plugin
3.4. In the Results window, go to Results → Options…. For clean exports, uncheck Copy column headers, Copy row numbers, Save column headers and Save row numbers.

 
Copy the three summary values from the Results window: Interfish distance, Nearest neighbor, and Farthest neighbor. Paste them into the spreadsheet row for the current frame/time point.

 

SECTION: Data entry and organization
5.1. Begin by entering the metadata for each row (frame/time point):

RESEARCHER: who is performing this analysis for the current frame. Use initials or an ID. We recommend duplicate, blinded scoring (two independent raters) and recording each rater’s ID.
VIDEO: the identifier of the source video file. In this dataset, one video may contain multiple tanks; use the exact filename or a consistent code.
TANK: the tank or group ID from which this frame was extracted (e.g., T3, Group_B), matching the coding used during recording.

 

SECTION: Data entry and organization
5.2. For each frame/time point, paste the measurements into the spreadsheet:

FRAME: timestamp of the frame (e.g., 0:15, 0:30, …).
IFD, NND, FND: from the plugin’s Results row (Interfish distance, Nearest neighbor, Farthest neighbor).
AREA and PERIMETER: from Analyze → Measure.
In the example shown, frames were sampled every 15 seconds.

 

SECTION: Installing the plugin
2.1. Once the download is completed, run the ImageJ software and look for "plugins" as demonstrated below.

 

SECTION: Installing the plugin
2.2. In the "Plugins" section, select "Macros" and then click in "Install"
 

SECTION: Installing the plugin
2.3. After the window below opens, select the "macros" file and select the plugin added before.

 

SECTION: Installing ImageJ and the Interfish Distance plugin
1. To install the plugin, first download and install the ImageJ software, then download the Interfish Distance PLUGIN 4.2 (.ijm) file.

ImageJ software download link: https://imagej.net/ij/download.html 

Plugin download:   

Important: It’s advisable to keep the Interfish Distance plugin in the ImageJ macros folder. If you downloaded it to another folder, copy it to ImageJ/macros for easy access and consistent loading.
SECTION: Installing the plugin
1. 
SECTION: Measuring area and perimeter
4. If you are working on the same frame, no recalibration is needed. Whenever you move to a different frame, change the apparatus/camera setup, or suspect the reference line may need adjustment, return to step 2 (open the file and set the scale) and recalibrate.

SECTION: Measuring area and perimeter
4.1. Use the Polygon Selections tool to outline the shoal and measure area and perimeter. Ensure each fish has one center-of-body point (as defined in Step 3) before drawing the boundary. Follow the rules below (convex outline vs. convex hull) for how to connect the group.

 

SECTION: Measuring area and perimeter
4.2. Evaluate whether the four fish form a convex or concave quadrilateral before tracing the boundary.

Convex: all interior angles are < 180°, and any line segment connecting two points inside the shape lies entirely inside the quadrilateral. In this case, draw a quadrilateral by connecting the four fish so that no edges cross.

Concave: at least one interior angle is > 180°, meaning there exists a pair of interior points whose connecting line segment falls outside the quadrilateral. In this case, a simple “connect-the-dots” quadrilateral can be ambiguous (see note below).

 

Note on concave layouts:
When the four fish form a concave quadrilateral, the polygon you draw depends on the order in which you connect the fish. Different connection orders can produce different shapes—and therefore different area and perimeter values. To avoid this ambiguity, prefer drawing the convex hull (the smallest convex polygon that contains all fish). The convex hull yields a single, reproducible boundary for area/perimeter (see next section).
SECTION: Measuring area and perimeter
4.3. Decide how to trace the boundary based on the group layout.

Convex layout: connect the four center points to form a simple quadrilateral without crossing edges. This quadrilateral defines the boundary for area and perimeter.

Concave layout: use the convex hull—draw a polygon that encloses all outermost fish. With four fish, the hull is usually a triangle. This avoids ambiguous concave quadrilaterals and yields a single, reproducible area/perimeter. Ensure no peripheral fish lies outside the boundary.

 

SECTION: Measuring area and perimeter
4.4. With the shoal boundary selected (quadrilateral or convex hull), go to Analyze → Measure (Ctrl+M) to record Area and Perimeter in the Results window. Ensure Analyze → Set Measurements… has Area and Perimeter checked; values are reported in the calibrated units.

 

SECTION: Measuring area and perimeter
4.5. After measuring, copy the Area and Perimeter values from the Results window and paste them into the spreadsheet row for this frame.

 

 

SECTION: Data entry and organization
5.3. Paste the extracted data from area and perimeter (two values) according to the screenshot analyzed.

 

SECTION: Data entry and organization
5.4. At the bottom of the sheet, there is a row where the FRAME column reads AVERAGE. Do not edit the formulas in this row. After you paste the per-frame values above, this row automatically calculates the mean for each outcome (IFD, NND, FND, and—if used—Area and Perimeter). If you see #DIV/0!, it means there are no valid values in that column yet; complete the entries above or remove empty rows.

 

SECTION: Installing ImageJ and the Interfish Distance plugin
1.1. After installing ImageJ, open the application. On the top menu bar, locate Plugins (between Analyze and Window; highlighted in the figure).

 

SECTION: Installing ImageJ and the Interfish Distance plugin
1.2. In the Plugins menu, select Macros and then click in Install.

 

SECTION: Installing ImageJ and the Interfish Distance plugin
1.3. In the “Install Macros” window, open the macros folder (or to the folder where you saved the plugin), select Interfish Distance PLUGIN 4.2.ijm, and click Open (macOS: Choose).

 

SECTION: Session setup: open file and calibrate scale
2.1. Once the plugin is installed, open ImageJ and go to File > Open…. Navigate to the folder with your pre-exported frames, select the desired time point (for example, the first frame), and click Open.

 

SECTION: Session setup: open file and calibrate scale
2.2. Select the Straight Line tool on the ImageJ toolbar (the diagonal line icon).
Tip: if another shape is showing, long-click the icon to reveal and choose “Straight Line.”

 

SECTION: Session setup: open file and calibrate scale
2.3. Draw a line along a known distance on the apparatus using the Straight Line tool (for example, 24 cm on a ruler or the calibrated inner tank edge). Make sure the line sits on the same plane as the fish, snaps exactly to the endpoints, and follows the apparatus edge to avoid perspective error.

 

SECTION: Session setup: open file and calibrate scale
2.5. Enter the Known distance (the real length of the line you drew) and the Unit of length (e.g., cm or mm).

 

SECTION: Session setup: open file and calibrate scale
2.4. With the calibration line active, go to Analyze → Set Scale….

 

SECTION: Running the Interfish Distance plugin
3.5. To remove the point markings and proceed with other measurements (e.g., area or perimeter) on the same frame, press Shift + A to clear the selection.
SECTION: Measuring area and perimeter
4.6. To remove the point markings and proceed with other measurements (e.g., area or perimeter) on the same frame, press Shift + A to clear the selection.