Oct 20, 2025
Measuring shoal cohesion from video frames in ImageJ using the Interfish Distance plugin
- Matheus Gallas-Lopes1,
- Daniela Varisco Müller1,
- Amanda Patelli Alves1,
- Angelo Piato1,
- Ana P Herrmann1
- 1Universidade Federal do Rio Grande do Sul
- LAPCOM
Protocol Citation: Matheus Gallas-Lopes, Daniela Varisco Müller, Amanda Patelli Alves, Angelo Piato, Ana P Herrmann 2025. Measuring shoal cohesion from video frames in ImageJ using the Interfish Distance plugin. protocols.io https://dx.doi.org/10.17504/protocols.io.j8nlkwz7wl5r/v1
License: This is an open access protocol distributed under the terms of the Creative Commons Attribution License, which permits unrestricted use, distribution, and reproduction in any medium, provided the original author and source are credited
Protocol status: Working
We use this protocol and it's working
Created: May 23, 2023
Last Modified: October 20, 2025
Protocol Integer ID: 82349
Keywords: Shoal cohesion, Shoaling, Group behavior, zebrafish, Danio rerio, ImageJ, Interfish distance, Nearest-neighbor distance, Farthest-neighbor distance, Shoal area, Shoal perimeter, interfish distance, interfish distance plugin, position of each fish, shoal cohesion from video frame, adult zebrafish, fish, measuring shoal cohesion, cohesion measure, video summaries suitable for statistical testing, video frame, shoal cohesion in laboratory assay, based cohesion measure, quantifying shoal cohesion, video summary, measurement of shoal cohesion, frame, shoal cohesion, living species, distance, practical imagej workflow, scale calibration, spatial footprint, statistical testing
Abstract
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.
Troubleshooting
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:
- Interfish Distance plugin (IJM macro):
Interfish distance PLUGIN 4.2.ijm2KB
Installing ImageJ and the Interfish Distance plugin
To install the plugin, first download and install the ImageJ software, then download the Interfish Distance PLUGIN 4.2 (.ijm) file.
Plugin download: Interfish distance PLUGIN 4.2.ijm2KB
Interfish distance PLUGIN 4.2.ijm2KB 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.
After installing ImageJ, open the application. On the top menu bar, locate Plugins (between Analyze and Window; highlighted in the figure).
ImageJ main toolbar. The Plugins menu (red box) is where macros/plugins are installed.
In the Plugins menu, select Macros and then click in Install.
ImageJ menu path to install a macro — Plugins → Macros → Install… (highlighted).
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).
Install Macros dialog in ImageJ. Navigate to the macros folder and select Interfish distance PLUGIN 4.2.ijm to load the plugin.
Session setup: open file and calibrate scale
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.
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.
ImageJ menu path to open a pre-saved frame (File > Open…) and an example folder containing frames sampled at fixed intervals.
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.”
ImageJ toolbar with the Straight Line tool highlighted.
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.
A straight line (yellow) was drawn along the inner bottom edge of the tank, corresponding to a known distance, to be used for spatial calibration in image analysis.
With the calibration line active, go to Analyze → Set Scale….
ImageJ menu path to open the Set Scale dialog after drawing the calibration line.
Enter the Known distance (the real length of the line you drew) and the Unit of length (e.g., cm or mm).
Set Scale dialog showing fields for Known distance and Unit of length.
Running the Interfish Distance plugin
In this section you will measure shoal cohesion on the prepared frames using the Interfish Distance plugin.
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.
ImageJ toolbar with the Multi-point tool highlighted.
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.
Example frame showing one point placed at the center of each fish.
Important: to standardize the fish points, guide yourself using the graphical representation below.
Schematic guide to standardize marking. Place the point at the visual midpoint of body length and height (approximate geometric center).
After placing one point on each fish, run the plugin: go to Plugins → Macros → Interfish distance.
ImageJ menu path to execute the previously installed Interfish distance macro.
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.
The software calculated pairwise distances between all fish in the frame and reported the mean interfish distance (IFD), mean nearest-neighbor distance (NND), and mean farthest-neighbor distance (FND) in the Results window. The Log window displays individual distance values and a summary for each fish.
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.
Results window showing the three summary metrics to copy: Interfish distance, Nearest neighbor, and Farthest neighbor.
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.
Measuring area and perimeter
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.
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.
ImageJ toolbar with the Polygon Selections tool highlighted. Use this tool to trace the shoal boundary for area and perimeter measurements.
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).
Examples of convex (left) and concave (right) quadrilaterals.
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).
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.
Left: convex examples—trace a quadrilateral with non-crossing edges. Right: concave examples—trace the convex hull
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.
ImageJ menu path to record area and perimeter: Analyze → Measure (Ctrl+M).
After measuring, copy the Area and Perimeter values from the Results window and paste them into the spreadsheet row for this frame.
Example of a convex quadrilateral traced around the shoal. The Results window shows the corresponding Area and Perimeter values to copy.
Example of a convex hull traced around the shoal. The Results window shows the corresponding Area and Perimeter values to copy.
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.
Data entry and organization
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.
Social cohesion - results.xlsx12KB 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.
Spreadsheet header showing the three metadata columns—RESEARCHER, VIDEO, and TANK—to be completed for each analyzed frame/time point.
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.
Template layout indicating where to paste values per frame: FRAME, the three summary metrics (IFD, NND, FND).
Paste the extracted data from area and perimeter (two values) according to the screenshot analyzed.
In this example, it was analyzed 15 seconds screenshot.
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.
Spreadsheet “AVERAGE” row highlighted. This row auto-computes the mean of each metric across the filled frames; formulas should not be changed.
Analysing the data
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.