This website provides access to the data sets and software described in the paper "Automated monitoring of behavior reveals bursty interaction patterns and rapid spreading dynamics in honey bee social networks". It also includes a simple workflow that describes how to use our software.
For the latest version of our bee tracking and behavior monitoring software, please visit our GitHub repository.
This section provides links to our data sets and describes their file format.
Below are links to our temporal network data sets. Each data set corresponds to one trial and contains all trophallaxis interactions that were detected during that trial. Our paper describes in detail how these data sets were generated.
Trial 1
Trial 2
Trial 3
Trial 4
Trial 5
Each data set is stored as comma-separated text file. The first line in the file is a header. The remaining lines describe one trophallaxis interaction, each. For each trophallaxis interaction we provide the following information:
Begin and end times are Unix time in millisecond precision.
This section describes how our software can be obtained and under which conditions it may be used. It also explains how to install and use our software, and how its output files are formatted.
We distribute our software under the GNU Affero General Public License v3 license. This means it is free and open source. If you would like to use our software under a different license, please contact us.
Below are links to software for generating "bCode" barcodes, detecting bCodes in digital images, and detecting liquid food exchange (trophallaxis) between honey bees. If you want the latest version of this software, please visit our GitHub repository.
bcode_maker.jar - draws a set of 2048 unique bCodes
bcode_detector.jar - detects bCodes in a digital images
converter.jar - converts bCode detection results to human-readable plain text
indexer.jar - indexes bCode detection results
trophallaxis_detector.jar - detects liquid food exchange among bees
Our programs require Java version 1.7 or higher. On many computers Java is already installed. If it isn't installed on your computer, you can obtain it here. Other than that, you only need to download our software.
Our programs need to be invoked on the command line. A typical invocation consists of a call to the Java interpreter, followed by the name of the program, followed by a series of assignments of values to parameters. Parameters have no default values, so for each invocation all parameters except the show.credits parameter need to be set. Reading the Supplementary Methods section of our paper will help you choosing parameter values that work well in your particular case.
Usage: java -jar bcode_maker.jar PARAMETER=VALUE...
Parameters:
| bcode.file | name of the output image file |
| padding | amount of extra space (in pixels) between the cutting guides and the (invisible) bCode border |
| show.credits | set to 1 to display credits and exit |
| square.side.length | size (in pixels) of the squares are that make up a bCode |
Usage: java -jar bcode_detector.jar PARAMETER=VALUE...
Parameters:
| conserve.margin | whether the bCode border is considered to be part of the bCode template |
| detected.bCodes.filename | name of the output file containing the bCode detection results |
| image.filename | name of the input image file |
| image.list.filename | plain text file listing on each line one input image file |
| intensity.step.size | increment when going from the lowest to the highest intensity threshold |
| max.intensity.threshold | highest intensity threshold for converting to a binary image |
min.intensity.threshold | lowest intensity threshold for converting to a binary image |
| min.template.conservation | fraction of bCode modules that need to match the bCode template |
| show.credits | set to 1 to display credits and exit |
Notes:
Input image filenames need to be a valid date in the format yyyy-MM-dd-HH-mm-ss-SSS.
Parameters image.filename and detected.bCodes.filename cannot be specified in conjunction with the image.list.filename parameter.
If the image.list.filename parameter is given, bCode detection output file names are constructed by replacing the input image file extension with "txt". Input image file name and extension must be separated by a dot.
Usage: java -jar converter.jar PARAMETER=VALUE...
Parameters:
| human.readable.file | name of the human-readable output file |
| raw.bCode.file | name of the bCode detection input file |
Usage: java -jar indexer.jar PARAMETER=VALUE...
Parameters:
| eol.byte.count | length of the sequence of characters signifying the end of a line of text in the file to be indexed |
| file | name of the file to be indexed |
Usage: java -jar trophallaxis_detector.jar PARAMETER=VALUE...
Parameters:
| contrast.threshold | contrast threshold used during local thresholding |
| distance.label.head | average distance between the center of a bee's bCode and the center of her head |
| filtered.data.file | name of the file containing the bCode detection results for the file named by the image.filename parameter. Must be sorted by timestamp column |
| geometry.max.angle.sum | maximum sum of the angles between a line drawn between the geometrically predicted centers of the head of two potential interaction partners and the orientation vector of their labels |
| geometry.max.distance | maximum distance between the geometrically predicted centers of the head of two potential interaction partners |
| geometry.min.distance | minimum distance between the geometrically predicted centers of the head of two potential interaction partners |
| image.filename | name of the input image file |
| leveling.threshold | maximum allowed intensity of any pixel in the image. Pixels with a higher intensity will be set to this threshold |
| max.path.thickness | maximum thickness of a path connecting the heads of putative interaction partners |
| max.thick.segment.length | maximum length of the segments that may be thicker than max.path.thickness at the beginning and at the end of a path |
| mean.head.pixel.intensity | average expected intensity of bee head pixels |
| show.credits | set to 1 to display credits and exit |
| trophallaxis.file | name of the output file containing the trophallaxis detections |
| thresholding.method | name of the local thresholding method used for converting grayscale images to binary images. Must be "Bernsen" |
| thresholding.radius | radius of the neighborhood over which the local threshold will be computed |
| vision.max.angle.sum | maximum sum of the angles between a line connecting the computer-vision-predicted centers of the heads of two potential interaction partners and the orientation vectors of their heads |
| vision.max.distance | maximum distance between the computer-vision-predicted centers of the heads of two potential interaction partners |
| vision.min.distance | minimum distance between the computer-vision-predicted centers of the heads of two potential interaction partners |
Notes:
Input image filenames need to be a valid date in the format yyyy-MM-dd-HH-mm-ss-SSS.
Parameters image.filename and trophallaxis.file cannot be specified in conjunction with the image.list.filename parameter.
If the image.list.filename parameter is given, trophallaxis output file names are constructed by replacing the input image file extension with "txt". Input image file name and extension must be separated by a dot.
Converted bCode detections are stored as comma-separated text files without a header. Each line describes one detection and provides the following information:
Begin and end times are Unix time in millisecond precision.
Trophallaxis detections are stored as as comma-separated text files without a header. Each line describes one detection and provides the following information:
Begin and end times are Unix time in millisecond precision.
This section outlines the steps that necessary are to make bCodes, and to detect bCodes and trophallaxis in digital images. It assumes that any downloaded programs and additional files you'll work with are in the current working directory. If that is not the case, you need to use absolute file names.
Making bCodes involves first creating and then printing bCode images. The size of the printed bCodes depends on the bcode_maker.jar parameter settings and the resolution of your printer. The formula for calculating the bCode side length in mm is (square.side.length * 12 + padding * 2) / printer_resolution * 25.4.
For example, if your printer has a resolution of 800 dpi and you use a square.side.length of 5 pixels and a padding of 2 pixels, your bCodes will have a side length of 2.032 mm. To make such bCodes, run
java -jar bcode_maker.jar square.side.length=5 padding=2 bcode.file=bcodes.png
This will create an image named "bcodes.png". Printing this image will result in a sheet of bCodes, which can be cut out and attached to bees, ants, or other small insects.
Before we try to detect bCodes, lets download an example image. This image shows a lot of bees with a bCode attached to their thorax inside an observation hive.
To detect bCodes in the example image at 8 equally spaced intensity thresholds between 40 and 110, and to only report a detected bCode if at least 85% of its template (excluding the border) are preserved, run
java -jar bcode_detector.jar min.intensity.threshold=40 max.intensity.threshold=110 intensity.step.size=10 min.template.conservation=0.85 conserve.margin=0 image.filename=2013-07-18-13-57-25-600.jpg detected.bCodes.filename=detected_bcodes.txt
This will result in a file named "detected_bcodes.txt" that contains the detection results. You will notice that this file lists fewer bCodes than can be seen in the image. To improve the detection rate, we highly recommend to sharpen the image before performing bCode detection (e.g. with unsharp masking). If the bCodes are very small, you might also want to magnify the image.
If you want to examine the bCode detection results or want to process them with another program, you should probably convert them to a more convenient format (not required for this workflow):
java -jar converter.jar raw.bCode.file=detected_bcodes.txt human.readable.file=converted_bcode_detections.txt
Converting detection results will produce a file named "converted_bcode_detections.txt" in the format described above.
To prepare for detecting trophallaxis, you need to index the file that contains the original bCode detection results. If your operating system uses a single character to signify the end of a line of text (e.g. Linux), you can do this by running
java -jar indexer.jar eol.byte.count=1 file=detected_bcodes.txt
This will create an index file named "detected_bCodes.idx". Indexing makes the most sense if bCode detection results of multiple images are stored in the same file, but it is also necessary for files containing the detection result of a single image.
We can now use the bCode detection results to predict which bees in the example image are engaged in trophallaxis:
java -jar trophallaxis_detector.jar distance.label.head=60 geometry.min.distance=61 geometry.max.distance=123 geometry.max.angle.sum=90 leveling.threshold=140 mean.head.pixel.intensity=25 vision.min.distance=85 vision.max.distance=117 vision.max.angle.sum=90 thresholding.method=Bernsen thresholding.radius=5 contrast.threshold=30 max.path.thickness=12 max.thick.segment.length=20 image.filename=2013-07-18-13-57-25-600.jpg filtered.data.file=detected_bcodes.txt trophallaxis.file=trophallaxis_contacts.txt
This will result in a file named "trophallaxis_contacts.txt" that describes all detected instances of trophallaxis (how the parameter values for this command line were obtained is described in the Supplementary Methods of our paper).
If you use the data sets or software available from this website in a scientific publication, please cite the following paper:
Tim Gernat, Vikyath D. Rao, Martin Middendorf, Harry Dankowicz, Nigel Goldenfeld, Gene E. Robinson, "Automated monitoring of behavior reveals bursty interaction patterns and rapid spreading dynamics in honey bee social networks." Proceedings of the National Academy of Sciences of the United States of America, 2018, 201713568; DOI: 10.1073/pnas.1713568115.
This material is based upon work supported by the U.S. National Science Foundation under grant No. BCS-1246920, a grant from the Christopher Family Foundation, the National Academies Keck Futures Initiative grant NAKFI CB4, and the U.S. National Institutes of Health grant R01GM117467.
Any opinions, findings, and conclusions or recommendations expressed here are those of the authors and do not necessarily reflect the views of the National Science Foundation.
gernat [at] illinois [dot] edu
