Dataset DOI: https://doi.org/10.5061/dryad.v15dv4290

Objective of the study

The objective is to understand the long-term association between bib size and age with dominance in sociable weavers (Philetairus socius).

The project is organised into two parts: the statistical analysis with the datasets and the scripts (more details in the publication), and the deep learning model developed for phenotypic trait segmentation based on pictures. See also README.html.

The folder contains four directories (more details below and available in data_scripts_and_results.zip):

• Data
• Documents
• Results
• Scripts

Documents

Contains the link to the publication related to this Git.

Data

Two sub-directories inside:

• database_manuscript_analysis
• pictures_bib_to_train_segmentation_model

Database manuscript analysis

Four files are listed inside.

The first one "dataset_to_test_factors_influencing_bibSize_2024.02.13.csv". This dataset is used to understand the factors influencing bib size in this species. The file is organised as follows:

• The ID of the individuals (Ring; from ID1 to ID1863)
• The year the picture aux taken (Season; from season 2013 to season 2024)
• Which colony do the bird belong to (Colony; from ID1 to ID19)
• Who took the picture (Scorer; from ID1 to ID7)
• The size (cm²) of the bib averaged on three consecutive pictures (BibSize)
• The sex of the individual (Sex; Male or Female)
• The age (days) of the individual (MinimumAge)
• The tarsus length (mm) of the individual (Tarsus)
• The ID of the camera used to take the pictures (Camera; from ID1 to ID3)

Three other files contain the three types of dominance hierarchies used in the analysis: both-sexes dominance hierarchies (all interactions), between-females dominance hierarchies (only female-female interactions), and between-males dominance hierarchies (only male-male interactions). The files are organised in the same way as the previous one, except with the addition of:

• The dominance score standardised within year and colony (DSs)
• The body index at capture (BodyIndex). Body index was based on a scaled mass index (Peig & Green, 2009) that uses mass and a body size metric of an individual, with its arithmetic mean value for the studied population (see more details in the publication)
• The ratio of the number of interactions to the number of individuals within the year and colony (RatioDyads)

Raw data to compute average bib size, body index, and normalised dominance scores are available in a folder “Raw” placed within the “database_manuscript_analysis” folder. The files contain the variables: Season, Colony, Ring (individual IDs), BibSize (hte size of the bib on the individuals pictures), AverageBibSize (the average bib size obtain from the pictures per individual, colony and year), the colony sizes and the total number of interactions within season (Number_interaction) and the raw dominance scores (David scores) before normalisation.

Pictures of the bib to train a segmentation model

There are not all the pictures used in our publication to train the final model of bib segmentation. However, we provide a small dataset to illustrate the method and allow future user to use this method on their own pictures.

The directory contains:

• A train and validation directories (respectively composed of 30 and 10 pictures). Inside both there are the pictures in a sub-directory "images", and the label and coordinates of the annotated object (here the bib) in a sub-directory "labels". All annotations need to be in the YOLO format.
• A test directory (composed of 30 pictures). These pictures will be used to predict bib size on an independent dataset.
• A file "data.yml" that will be used by YOLO during the training to locate the pictures and their annotation. NOTA BENE: YOLO needs an absolute path and will not work with a relative path.

Scripts

Two sub-directories inside:

• scripts_manuscript_analysis
• scripts_model_bib_segmentation

Bib segmentation model

Scripts used to set up the Conda environment, train a segmentation model using YOLOv8, evaluate the model, and predict segmentation on pictures. "yolov8l-seg.pt" and "yolov8n.pt" are the initial weights of YOLO that will be fine-tuned during custom training.

Conda working environment

The environment will mainly vary in relation to the graphics card used and the CUDA version. We train our model on Ubuntu 20.04.5, with a PU Nvidia GeForce RTX 3090 (Driver version 470.223.02). To create the appropriate environment on a similar setup, execute the following command lines (in addition, "bib_segmentation_yolov8.yml" contains the list of all packages in the environment and their version):

$ conda create --n ENVIRONMENT_NAME PYTHON=3.9

$ conda activate ENVIRONMENT_NAME

$ pip install torch torchvision --index-url https://download.pythorch.org/whl/cu117

$ pip install ultralytics==8.0.132

The environment is ready to be used.

Train a model

To train the model, the file "1.train_bib_segmentation.py" needs to be used. Several adjustments can be performed:

• Line 10, "image_size". It is the size the pictures will be resized to before passing into the YOLO training steps.
• Lines 11 and 12, "learning_rate_value" and "learning_rate_value_final". Allow to change the initial and final learning rates.
• Line 13, "patience". Allow to set the number of iterations (epochs) without model improvement before stopping the training process.
• Line 14, "batch_size". The size of the batch of pictures analysed by the model before updating its weights.
• Line 15, "epochs". The number of times the model will train on the whole training dataset.
• Line 16, "iou". The Intersection over Union ratio value (higher IoU means higher segmentation precision) will be used as a threshold to measure the mean average precision during the validation steps.
• Line 20. Set the path to the "data.yml" file, which contains the path to the training and validation dataset directories.
• Line 29, "project". The output directory to save the trained model.
• Line 30, "name". The name of the task.

To begin training the YOLO model, run: python 1.train_bib_segmentation.py

Evaluate a model

To train the model, the file "2.evaluate_bib_segmentation.py" needs to be used. The script will output the mean average precision with an IoU of 0.5, an IoU of 0.75, and an average between IoU 0.5 to IoU 0.95. A high mean average precision at high IoU indicates good segmentation. Several adjustments can be performed:

• Lines 6 to 8. Choose the same hyperparameters as the ones selected during the training process.
• Line 10. The path to the trained model to test (from YOLO output is "best.pt")
• Line 11. Set the path to the "data.yml" file, which contains the path to the training and validation dataset directories.
• Line 15, "project". The output directory to save the trained model.
• Line 16, "name". The name of the task.

To begin training the YOLO model, run: python 2.evaluate_bib_segmentation.py

Predict segmentation on pictures

To train the model, the file "3.predict_bib_segmentation.py" needs to be used. The prediction will infer the size of the segmented object. Modification can be performed in case other information needs to be extracted (e.g., coordinates). The script will also give the time needed to perform the segmentations. Several adjustments can be performed:

• Lines 11. The path to the trained model to test (from YOLO output is "best.pt")
• Line 14. Set the image size input.
• Line 17, "images_path". Path to the directory that contains the pictures to analyse. For this example, we set it to the "test" directory (see "data" section).
• Line 22. Will detect all pictures with the "JPG" extension. adapt if needed.* Line 38, "project". The output directory to save the trained model.
• Line 39, "name". The name of the task.
• Line 61. Adapt the output path to save the dataframe containing the name of the picture and the size of the segmented object.

To begin training the YOLO model, run: python 3.predict_bib_segmentation.py

Analysis in the manuscript

See publication for details about the analysis performed to understand the factors influencing bib size and the factors influencing dominance in sociable weavers.

Results

Two sub-directories inside:

• results_manuscript_analysis
• results_model_bib_segmentation

Results of the bib segmentation model

This directory contains two parts.

training_model_bib_segmentation_manuscript

It contains training output and the model trained to detect bib size in sociable weavers.

custom_train

It contains the training, validation, and test output of the scripts used to train, validate, and predict segmentation on pictures.

Results of analyses in the manuscript

For the figures, see the associated publication in Behavioural Ecology.