Detecting trophallaxis

The trophallaxis_detector.jar program identifies bees that orally exchange liquid. It does this by processing the bCode dectections from observation hive images to find pairs of bees that are close and face each other. It then visually examines each pair with a convolutional neural network to estimate the probability that the two bees are indeed engaged in trophallaxis, and that the bee with the lower ID is the liquid donor. Details of this procedure are described here.

Detecting trophallaxis

To detect trophallaxis in the example image from the bCode detection tutorial, we first need to rename the file containing the bCode detections for this image to prevent it from being overwritten by the trophallaxis detector. On a Linux system, you can do this with the command

mv 2013-07-18-13-57-25-600.txt bcode_detections.txt

We then need to index the bCode detection file. This enables the trophallaxis detector to quickly find a particular bee in files that contain the dCode detections from multiple images. To create the index, run

java -jar indexer.jar file=bcode_detections.txt

This will create an index file named bcode_detections.idx. We can now use the indexed bCode detections to predict which bees are engaged in trophallaxis

java -jar trophallaxis_detector.jar distance.label.head=60 \
geometry.min.distance=30 geometry.max.distance=135 geometry.max.angle.sum=104 \
input.file=2013-07-18-13-57-25-600.jpg filtered.data.file=bcode_detections.txt

This will result in a file named 2013-07-18-13-57-25-600.txt that contains one line for each detected trophallaxis interaction in the format described on this page. How the parameter values for this call were determined is described in the Methods here and here.

Hints

Note that the trophallaxis detector expects filenames to encode the date and time when the image was captured. A valid file name has the format yyyy-MM-dd-HH-mm-ss-SSS, like in the example above. If you don't know what these letters mean, please look here.

To process more than one image, you can create a plain text file that lists one image on each line and then use this file as the input.file.

Since the trophallaxis detector reports the probability of liquid exchange and donation, users can decide how high these probabilities needs to be for the detection to be considered "real". For us, occurrence and donation probability cutoffs of 0.5 resulted in the detection performance reported in our methods paper.

Limitations

The trophallaxis detector was trained on images generated by the honey bee tracking rig described in this paper. If it applied to images from other recording setups, its detection performance will likely differ from the one we reported.