Dataset DOI: 10.5061/dryad.69p8cz9bw

Associated publication

Cribellier A., Poda B.S., Dabiré R.K., Diabaté A., Roux O., Muijres F.T. The complex swarming dynamics of malaria mosquitoes emerge from simple minimally-interactive behavioral rules. Submitted to PLOS Computational Biology.

Corresponding author: Antoine Cribellier, Experimental Zoology Group, Wageningen University, Wageningen, The Netherlands (antoine.cribellier@wur.nl).

Description of the data and file structure

Aim and scope of the dataset

Male malaria mosquitoes (Anopheles coluzzii) aggregate at dusk in station-keeping swarms above a visually contrasting ground object (the swarm marker), where females come to mate. This deposit contains the two datasets that underlie the study: (i) the measured three-dimensional flight tracks of An. coluzzii males swarming above a 40 x 40 cm black marker in a laboratory arena under simulated-sunset conditions (Data S1), and (ii) the simulated three-dimensional flight tracks produced by the agent-based model (ABM) that reproduces the observed swarming dynamics from a minimal set of individual behavioral rules (Data S2).

The central hypothesis tested with these data is that swarm-level structure and dynamics do not require rich mosquito-to-mosquito interactions, but emerge from two simple, mostly non-social rules: (1) individuals perform saccadic turns triggered by the apparent size of the marker in their visual field (the marker viewing angle, α), and (2) individuals avoid collisions with nearby conspecifics at short range. Data S1 provides the empirical flight kinematics and the empirical turn-angle distributions used to parameterise the model; Data S2 provides the model output for the two key model variants (with and without the collision-avoidance rule) that are compared against the measurements in the manuscript.

Overview of the deposited files

Conventions shared by all .mat files

File format. All .mat files are MATLAB v7.3 files, i.e., HDF5 containers. They open natively in MATLAB (load('filename.mat')) and can also be read in Python with h5py, or in R with rhdf5. They cannot be read with scipy.io.loadmat, which supports only MATLAB v5-v7.2 files. Note that HDF5 stores MATLAB arrays in transposed order, so an N x 1 MATLAB column vector appears as shape (N, 1) in h5py but character arrays appear as arrays of uint16 character codes that must be converted back to text.

Top-level structure. Each .mat file contains a single MATLAB structure named all_data with two branches:

• all_data.cst — constants that apply to the whole dataset (frame rate; for Data S2, all model parameters).
• all_data.exp — one sub-structure per experiment (Data S1) or per simulation replicate (Data S2), each holding metadata and tracks.

Coordinate system. All positions are in metres, in the world reference frame defined in Figure 1 of the manuscript: the origin is at the centre of the swarm marker on the ground, z points vertically upwards, y points horizontally towards the simulated sun / sunset horizon, and x is horizontal and parallel to the sunset horizon, completing a right-handed frame. Velocities are in m s⁻¹ in the same frame. Angles are in degrees unless stated otherwise.

Time base. Tracks were sampled at 50 Hz (all_data.cst.fps = 50). frames is the video frame index and time = frames / fps is the elapsed time in seconds from the start of the recording session (Data S1) or from the start of the simulation (Data S2).

Missing values. Missing samples are encoded as NaN. In Data S1, NaN marks frames within an individual's tracked interval in which the mosquito was not detected in enough camera views to be reconstructed in 3D (typically short gaps between stitched track segments). Data S2 contains no missing values.

---

Data S1 (Data_S1.zip): measured flight tracks of swarming Anopheles coluzzii males

The archive contains a single file:

all_data-exp1-coluzzii_males-selection_swarming.mat — 3D flight tracks of male An. coluzzii mosquitoes swarming above a 40 x 40 cm black marker in a climate-controlled laboratory arena (2.0 x 0.7 x 1.8 m) under simulated-sunset lighting. Trajectories were reconstructed from synchronised multi-camera video as described in the Materials and Methods of the manuscript. As the file name indicates, the deposit contains a selection of the recorded swarming episodes: the swarm onset, plus fixed time windows sampling the build-up, plateau and decay phases of each swarm (see dynamic below).

Structure

all_data
├── cst
│   └── fps                        50 (Hz), frame rate of all tracks
└── exp
    ├── exp20221007_183000         one field per experiment (6 in total)
    │   ├── metadata
    │   │   ├── species            'coluzzii'
    │   │   ├── sex                'male'
    │   │   ├── age                age of the mosquitoes at the time of the experiment (days)
    │   │   ├── nb                 number of mosquitoes released in the arena
    │   │   ├── date               date and time of the experiment (MATLAB datetime)
    │   │   └── marker             x, y, z: position of the marker centre in the raw
    │   │                          tracking frame of the arena (m); tracks are already
    │   │                          expressed relative to this point
    │   └── tracks
    │       └── object
    │           ├── obj1           one field per tracked individual
    │           ├── obj2
    │           └── ...
    ├── exp20221010_183000
    └── ...

Experiment fields are named expYYYYMMDD_HHMMSS after the date and start time of the recording session (all sessions started at 18:30 local time).

Per-experiment metadata

Together the six experiments contain 938 individual trajectories, 1,816 raw track segments and 709,920 valid 3D position samples (≈ 3.9 h of tracked flight at 50 Hz).

Variables inside each obj<n>

Each obj<n> is one tracked individual mosquito over one continuous tracked interval. objN (together with the experiment name) is the unique identifier of a trajectory in this dataset. The time-series fields below are all N x 1 column vectors of the same length N, aligned sample by sample.

Scalars inside each obj<n>.scalars (constant for that individual)

Derived quantities. The kinematic and visual variables analysed in the manuscript — accelerations, jerk, flight speed, angular speed, cylindrical coordinates (r, θ), the marker viewing angles α_x and α_y, saccade detection and saccade properties, swarm-level metrics and heat maps — are not stored in this file. They are recomputed from the raw positions above by the analysis code (see Code/software); main.m and gen_all_data_tracks.m list them explicitly.

---

Data S2 (Data_S2.zip): simulated flight tracks from the agent-based model

The archive contains two files, one per model variant. Both were produced with the same behavioral rules and the same parameter values (Table S1); they differ only in whether the short-range collision-avoidance rule was active:

The file names encode the model configuration as <saccade_type>-<acceleration_type>-<start_saccade_type>-<start_saccade_combination_type>-<start_saccade_field_names>-<threshold flags>; each of these components is a field of all_data.cst and is defined in Table_S1.xlsx.

Each file contains 20 independent replicate simulations of 10 agents flying for 120 s at 50 Hz (6,000 frames), i.e. 200 simulated trajectories and 1,200,000 position samples per file.

Structure

all_data
├── cst                            all model parameters (see Table_S1.xlsx)
└── exp
    ├── rep1                       one field per replicate simulation (20 in total)
    │   ├── metadata
    │   │   ├── species            'boid'
    │   │   └── sex                'male'
    │   └── tracks
    │       └── object
    │           ├── boid1          one field per simulated agent (10 per replicate)
    │           ├── boid2
    │           └── ...
    ├── rep2
    └── ...

all_data.cst: model parameters

Table_S1.xlsx is the authoritative, annotated description of these parameters: it gives, for every parameter, the symbol used in the manuscript, the name used in the MATLAB code (which is the field name used here), a description, the default value, the units, the source or justification, the submodel in which it is used, and whether it is stochastic. Users should consult Table_S1.xlsx for the definition of every field of all_data.cst. For orientation, the fields present are:

all_data.cst.dist holds the empirical distributions measured in Data S1 and used to draw stochastic quantities in the model. dist.linear contains the fitted/interpolated distributions actually sampled by the model — angle_v_pks_theta_after_linear (azimuth of flight direction after a saccadic turn, degrees) and angle_v_pks_phi_after_linear (climb angle after a saccadic turn, degrees), both shown in Figure S2, plus r_acc. dist.raw contains the corresponding raw measured distributions of a broader set of kinematic variables (flight speed vel, acceleration acc, angular speed angle_v, the velocity and acceleration components x_vel…z_acc, phi_vel, phi_acc, saccade speed angle_v_pks_vel, and the cumulative trigger variables cumsum_alpha_x_percent, cumsum_time_pks, cumsum_distance_pks), retained for reference.

Variables inside each boid<n>

Each boid<n> is one simulated agent over the full 120 s simulation. All time-series fields are 6000 x 1 column vectors with no missing values.

Scalars inside each boid<n>.scalars

---

Table_S1.xlsx

Single sheet ("Table S1") listing all 24 parameters of the agent-based model, one per row, with the columns: Parameter name, Symbol, Name in Matlab code, Description, Default value, Units, Range / values explored, Source / Justification, Used in submodel(s) and Stochastic?. The model description follows a simplified form of the ODD protocol (Grimm et al., 2020, JASSS 23(2):7). This table is the reference documentation for every field of all_data.cst in the Data S2 files and for every parameter of the simulation code.

---

Videos

All videos are MPEG-4 (H.264) renderings generated from the datasets above with gen_video_tracks.m and gen_video_tracks_vel_acc.m.

Video_S1.mp4: swarming flight of an initiator mosquito. Three-dimensional and two-dimensional views of the flight of the initiator — the first An. coluzzii male to start swarming — recorded above a 40 x 40 cm black swarm marker. Source data: the individual with was_initiator = true in Data S1.

Video_S2.mp4: flight kinematics of a single swarming mosquito. Three-dimensional position, flight speed, acceleration and angular speed of one swarming An. coluzzii male recorded above the same marker. This individual was swarming together with conspecifics. Source data: Data S1.

Video_S3.mp4: swarming flight of multiple mosquitoes. Three-dimensional and two-dimensional views of the simultaneous flight of multiple An. coluzzii males recorded above the same marker. Source data: Data S1.

Video_S4.mp4: swarming flight of ten simulated mosquitoes. Three-dimensional and two-dimensional views of ten agents simulated with the agent-based model including collision avoidance, above a virtual 40 x 40 cm marker. Source data: one replicate of all_data-abm-along_y_rand-null-threshold-any-alpha_x_percent-threshold_alpha_x-avoid_collisions.mat in Data S2.

---

Code/software

Code is hosted on Zenodo, in the compressed file Code_S1.zip.

Reading the data. The .mat files are MATLAB v7.3 (HDF5). In MATLAB (R2022b or later recommended): load('all_data-exp1-coluzzii_males-selection_swarming.mat') returns the structure all_data. In Python, use h5py (not scipy.io.loadmat), remembering that HDF5 transposes MATLAB arrays and stores MATLAB character arrays as uint16 character codes:

import h5py, numpy as np
f = h5py.File('all_data-exp1-coluzzii_males-selection_swarming.mat', 'r')
track = f['all_data/exp/exp20221007_183000/tracks/object/obj1']
x, y, z = (np.array(track[k]).ravel() for k in ('x', 'y', 'z'))
t = np.array(track['time']).ravel()

Analysis and model code (S1 Code). All original MATLAB code written to run the agent-based model, analyse both datasets and generate the figures of the manuscript is provided as S1 Code with the article. It was developed and run in MATLAB R2022b. Its main entry points are:

• _Code/main.m — full analysis pipeline for a dataset: loads an all_data file, computes the derived kinematic and visual variables (gen_all_data_tracks.m), the swarm-level metrics (gen_all_data_swarms.m) and the spatial heat maps (gen_all_data_heatmaps.m), and produces the corresponding figures (gen_all_fig_swarms.m, gen_all_fig_heatmaps.m). Set exp_num = 1 to analyse Data S1, or exp_num = 0 together with the appropriate sim_name to analyse one of the Data S2 files.
• _Code/Agent based model/main_all_abm.m — runs the agent-based model for the listed configurations (20 replicates x 10 agents x 120 s each) and writes the all_data-abm-*.mat files deposited as Data S2. main_abm.m runs a single simulation, and boids/swarming_saccades/update_boids.m implements the behavioural rules themselves (saccade triggering, turn-angle sampling, collision avoidance).
• _Code/get_alpha_xy.m and _Code/Agent based model/get_alpha_x.m — compute the marker viewing angles α_x and α_y from a 3D position, assuming coordinates centred on the marker.
• _Code/gen_video_tracks.m, _Code/gen_video_tracks_vel_acc.m — generate Videos S1-S4.

To reproduce the analysis: unzip the data, place the .mat file in the _Data folder, set data_path at the top of main.m to that location, and run main.m; figures are written to the _Figures folder.

Note that main.m also calls a small number of general-purpose helper functions from the authors' shared MATLAB library (e.g. derivative, save_figures, gen_all_data_split_tracks, gen_all_data_tracks_subset, angle_btw_vectors), which are not part of S1 Code; these can be obtained from the corresponding author.