DOI: 10.5061/dryad.83bk3jb01
title: Data from: Combining Unity with machine vision to create low latency, flexible, and simple virtual realities

description: In recent years, virtual reality arenas have become increasingly popular
 for quantifying visual behaviors. By using the actions of a constrained
 animal to control the visual scenery, the animal perceives that it is
 moving through a virtual world. Importantly, as the animal is constrained
 in space, behavioral quantification is facilitated. Furthermore, using
 computer-generated visual scenery allows for identification of visual
 triggers of behavior. We created a novel virtual reality arena combining
 machine vision with the gaming engine Unity. For tethered flight, we
 enhanced an existing multi-modal virtual reality arena, MultiMoVR (Kaushik
 et al., 2020), but tracked wing movements using DeepLabCut-live (DLC-live,
 Kane et al., 2020). For tethered walking animals, we used FicTrac (Moore
 et al., 2014) to track the motion of a trackball. In both cases, real-time
 tracking was interfaced with Unity to control the location and rotation of
 the tethered animal’s avatar in the virtual world. We developed a
 user-friendly Unity Editor interface, CAVE, to simplify experimental
 design and data storage without the need for coding. We show that both the
 DLC-live-Unity and the FicTrac-Unity configurations close the feedback
 loop effectively and quickly. We show that closed-loop feedback reduces
 behavioral artifacts exhibited by walking crabs in open-loop scenarios,
 and that flying Eristalis tenax hoverflies navigate towards
 virtual flowers in closed loop. We show examples of how the CAVE interface
 can enable experimental sequencing control including use of avatar
 proximity to virtual objects of interest. Our results show that combining
 Unity with machine vision tools provides an easy and flexible virtual
 reality environment that can be readily adjusted to new experiments and
 species. This can be implemented programmatically in Unity, or by using
 our new tool CAVE, which allows users to design new experiments without
 additional programming. We provide resources for replicating experiments
 and our interface CAVE via GitHub, together with user manuals and
 instruction videos, for sharing with the wider scientific community.
description: Please see attached ReadMe files, and the Methods section in the
 associated paper.
description: # Data from: Combining Unity with machine vision to create low latency,
 flexible, and simple virtual realities
 [https://doi.org/10.5061/dryad.83bk3jb01](https://doi.org/10.5061/dryad.83bk3jb01) ## Description of the data and file structure We have uploaded the data associated with testing our closed loop arena, and CAVE software. The data are also shown in figures 1, 4, 8 and 9 of the paper. We have submitted the following folders: #### Figure1DRawData.zip This folder contains raw latency data. This is described in more detail below. #### Figure4Data.zip This folder contains crab behavioral data. This is described in more detail below. We have uploaded a file entitled data_header.txt associated with this data set. #### Figure8RawData.zip This folder contains the hoverfly behavioral data. This is described in more detail below. #### Figure9RawData.zip This folder contains raw latency data for the hoverfly set-up. This is described in more detail below. #### Latency\_measurement\_data.zip This contains raw latency data for the crab set-up. This is described in more detail below. #### Prism\_files.zip This folder contains analyzed data (as shown in the associated paper in figures 1D, 8C-E, G, H, 9B-D), together with the statistical analysis. These can only be opened in Prism. #### csv\_files.zip These contains the same data as in Prism_files.zip. These are described in more detail below. ## Detailed description of the data and file structure #### Naming Convention Files and folders include the YYYYMMDD date and HHMMSS time formats in their naming conventions as noted. #### Figure1DRawData.zip We quantified the time between sequential unique frames analyzed by DLC-live reported in the “Time Frame was Captured” column in CAVE’s DLC-Data file, when using different temporal and spatial camera resolutions. The times were converted to temporal frequency. Note that this file uses several different delineators to separate the columns (e.g. both , and ; and # are used). The raw data can be found in the folder called Figure1DRawData, which contains five subfolders, one for each data set using different combinations of temporal and spatial frequencies shown in the figure. The subfolders are labelled in the following format: Latency_pixels_Hz. Each spatiotemporal combination was done 3 times, creating 3 input videos and data files. * The videos are labelled in the following format: WingsControl_Latency_pixels_Hz_YYYYMMDD_HHMMSS_YYYYMMDD_HHMMSS.decimals_1_VIDEO.avi * The YYYYMMDD_HHMMSS_DLC-Data.csv files contain the x-y-coordinates of the six points tracked in each frame captured in DeepLabCut-live. These points are colored in the videos. The time between each video frame update is the difference between sequential unique instances of “Time Frame was Captured”. #### Figure4Data.zip We recorded video and log files from both Fictrac and Unity while running experiments. These were used to calculate distances and paths fiddler crabs ran on the trackball in experiments and are found in the Figure4Data folder. The file entitled data_header.txt explains the format of the following data: The raw video data analysed by Fictrac can be found in the subfolder called data/fictrac_videos. Logs from Fictrac analysis during experiments are found in a folder called data/fictrac_logs. The config files used to run experiments and control Unity are found in the data/configs folder and datetime string along with positions and scale of objects each frame in experiments are found in the data/trial_logs folder. All data files are coded via date time strings in their naming structure, e.g. a trial_log from Unity of “20220923160050_0.csv” corresponds to an experiment that started on the 23/09/2022 and 4:00 pm. The positions of the following objects displayed by Unity in experiments were recorded in trial_logs log files: * crab.crab_x, crab.crab_y, crab.crab_z corresponding to the x, y and z positions of the virtual crab. * SphericalStimulusGenerator.SphereStimulus_x, SphericalStimulusGenerator.SphereStimulus_y, SphericalStimulusGenerator.SphereStimulus_z corresponding to the x, y and z positions of the virtual bird. * Animal_x, Animal_y, Animal_z corresponding to the x, y and z positions of the tethered crab. Data extracted from these raw data files ready for analysis in .rds format is located at data/data.rds. Raw data used for latency measurement data ready for analysis is found in .rds format at data/latency_millisecond_precision.rds. #### Figure8RawData.zip Briefly, we tested whether female *Eristalis tenax* hoverflies navigate in the CAVE controlled VR using a sparse scene as well as one with two OOIs, each a yellow dandelion plant. We extracted the resulting avatar yaw and position using the y-rotation and x-z coordinates reported in the Transform.csv file. We first analyzed proximity rate in a sparse scene, called ‘Control scene’ and in one with two yellow dandelion plants, called ‘Flower scene’. We quantified the path lengths from each trial as a function of trial duration. We also compared the path straightness when the proximity criterion was fulfilled with trials where it was not. In the uploaded data you will find the following folders: ##### Figure8RawData folder This contains the raw data from an individual hoverfly. Each subfolder in Figure8RawData is named as e.g., '20231922' indicating recording date, which is when the behavioral data were recorded. We call them Date folders. Within each Date folder you will find 2 sub folders: * “01_Female” folder, which contains the raw data used ‘Flower scene’ * “F1_6controls” folder, which contains the raw data used ‘Control scene’. We used six control trials for data analysis. * Within in “20231213” folder, you will find a sub folder “Figure8AB” containing example trials’ data shown in Figure8 AB. Within “01_Female” and “F1_6controls” folder you will find: * Each sequence data folder, which is e.g. named “134246_Dandelion_Sequence_Circle2Flowers” * 134246 is the time of the recording * *Dandelion_Sequence_Circle2Flowers* indicates Sequence Name using ‘Flower scene’ * Control scene sequence is named as *Dandelion_Sequence_Control* * Output mat file, which is e.g. named “OutputCircleFlowerYYYYMMDD.mat”, which contains processed data for Flower scene, or “OutputControlYYYYMMDD.mat”, which contains processed data for Control scene. The YYYYMMDD specify the recording date. Contents are listed below. * Result mat file, which is e.g. named “TestSceneRsltYYYYMMDD.mat”, which contains processed data for Flower scene, or “ControlRsltYYYYMMDD.mat”, which contains processed data for Control scene. The YYYYMMDD specify the recording date. Contents are listed below. - Within each sequence data folder you will find: * Each trial data folder, which is e.g. named “134246_DandelionTrial_Circle2Flowers” * 134246 is the time of the recording given in the hours minutes seconds format * *DandelionTrial_Circle2Flowers* indicates Trial Name using ‘Flower scene’ * Control scene trial is named as *DandelionTrialControl* * YYYYMMDD_HHMMSS_Dandelion_Sequence_Circle2Flowers.Sequence.csv, or YYYYMMDD_Dandelion_Sequence_Control.Sequence.csv, which contains sequence information for either Flower scene or Control scene, where YYYYMMDD specify the recording date and HHMMSS the recording time given in the hours minutes seconds format. This CSV file is produced and stored by CAVE. * SeqDataYYYYMMDD_HHMMSS.mat, which contains processed sequence data, where * specify the recording date, given in the YYYYMMDD format and HHMMSS the recording time given in the hours minutes seconds format. * TrialDataYYYYMMDD_HHMMSS.mat, which contains processed trial data, where * specify the recording date, given in the YYYYMMDD format and HHMMSS the recording time given in the hours minutes seconds format. * Within each trial data folder you will find CSV files produced by CAVE: * \YYYYMMDD_HHMMSS*DandelionTrial_Circle2Flowers.Trial.csv or *********######_DandelionTrialControl.Trial.csv, which contains trial information for either Flower scene or Control scene. The * specify the recording date, given in the YYYYMMDD format and # the recording time given in the hours minutes seconds format. * \YYYYMMDD_HHMMSS_DLC-Data.csv, which contains x-y-coordinates of the six points tracked in each frame captured in DeepLabCut-live. The time between each video frame update was defined as the difference between sequential unique instances of “Time Frame was Captured”. The time taken by DLC-live to perform its pose estimation is reported in the “DLC_Latency” column. The * specify the recording date, given in the YYYYMMDD format and # the recording time given in the hours minutes seconds format. * \YYYYMMDD_HHMMSS_TetheredAnimal_0.Transform.csv, which contains tethered hoverfly avatar’s x-z coordinates and y-rotation. The * specify the recording date, given in the YYYYMMDD format and # the recording time given in the hours minutes seconds format. * \YYYYMMDD_HHMMSS_World_14.Transform.csv, which contains virtual world’s x-z coordinates and y-rotation. The * specify the recording date, given in the YYYYMMDD format and # the recording time given in the hours minutes seconds format. * Within Flower Scene trial folder, YYYYMMDD_HHMMSS_Dandelion_Y2_22.Transform.csv, which contains a dandelion plant’s x-z coordinates and y-rotation. The * specify the recording date, given in the YYYYMMDD format and # the recording time given in the hours minutes seconds format. * Within Flower Scene trial folder, YYYYMMDD_HHMMSS_Dandelion_Y4_24.Transform.csv, which contains a dandelion plant’s x-z coordinates and y-rotation. The * specify the recording date, given in the YYYYMMDD format and # the recording time given in the hours minutes seconds format. * “Figure8Data” folder also contains “PositionAfter5sec_Cntl.mat” and “PositionAfter5sec_Test.mat”, which contain hoverfly x and z coordinates 5 sec into each trial * List of contents in each mat file: * OutputCircleFlowerYYYYMMDD.mat or “OutputControlYYYYMMDD.mat”, which contains data for all trials recorded in each animal. This file contains information below: * Date: Recorded date * Time: Recorded time * tetheredAnimal_x: Tethered Animal Avatar’s x position during the loop was closed * tetheredAnimal_z: Tethered Animal Avatar’s z position during the loop was closed * OOI_name: Names of Object of Interest (OOI) * OOIPos_x: OOI’s x position in Flower Scene * OOIPos_z: OOI’s z position in Flower Scene * FrameDuration: The time between each scene frame update during the loop was closed * EndTrial: Trial end, either Duration or Proximity. In case of Proximity, you will get triggered Dandelion’s ID too * EndOOI_name: Proximity triggered OOI name * GainMethod: Yaw and thrust gain setting method. LinearY_LinearT indicating linear gain setting for both yaw (Y) and thrust (T) * yaw_method: Yaw gain setting method * yaw_min: Minimum yaw * yaw_midpoint: Midpoint yaw * yaw_max: Maximum yaw * minWBAD: Minimum Wing Beat Amplitude Difference (WBAD) * midpointWBAD: Midpoint WBAD * maxWBAD: Maximum WBAD * thrust_method: Thrust gain setting method * thrust \_min: Minimum Thrust * thrust \_midpoint: Midpoint Thrust * thrust \_max: Maximum Thrust * minWBAS: Minimum Wing Beat Amplitude Sum (WBAS) * midpointWBAS: Midpoint WBAS * maxWBAS: Maximum WBAS * distance_path: Total path length quantified as the vector sum of the tethered hoverfly avatar’s location changes * distance_start2end: Distance between the start and end position of the hoverfly’s avatar * straightness_ind: Path straightness * “TestSceneRsltYYYYMMDD.mat” or ControlRsltYYYYMMDD.mat, which contains data for all trials using Flower Scene or Control Scene recorded in each animal. This file contains information below * YawMax: Maximum yaw * ThrustsMax: Maximum thrust * ProximityTriggers: Proximity triggered or not (1 or 0) * TrialDuration: Trial duration in seconds * distance_path: Total path length quantified as the vector sum of the tethered hoverfly avatar’s location changes * distance_start2end: Distance between the start and end position of the hoverfly’s avatar * straightness_ind: Path straightness * Time: Recorded time in hours minutes seconds format * Date: Recorded date in YYYYMMDD format * DateTime: Recorded date and time in YYYYMMDD\_ hours minutes seconds format * FrameDuration: The time between each scene frame update during the loop was closed * tetheredAnimal_x: Tethered Animal Avatar’s x position during the loop was closed * tetheredAnimal_z: Tethered Animal Avatar’s z position during the loop was closed * OOIPos_x: OOI’s x position in Flower Scene * OOIPos_z: OOI’s z position in Flower Scene * EndFrame: Frame number at the end of trial * SeqDataYYYYMMDD_######.mat, which contains data for each sequence. This file contains information below * yaw_method: Yaw gain setting method * yaw_min: Minimum yaw * yaw_midpoint: Midpoint yaw * yaw_max: Maximum yaw * minWBAD: Minimum Wing Beat Amplitude Difference (WBAD) * midpointWBAD: Midpoint WBAD * maxWBAD: Maximum WBAD * thrust_method: Thrust gain setting method * thrust \_min: Minimum Thrust * thrust \_midpoint: Midpoint Thrust * thrust \_max: Maximum Thrust * minWBAS: Minimum Wing Beat Amplitude Sum (WBAS) * midpointWBAS: Midpoint WBAS * maxWBAS: Maximum WBAS * YawThrustSetting: Yaw and thrust gain settings * TrialNames: Trial Names set in Cave * EndTrial: Trial end, either Duration or Proximity. In case of Proximity, you will get triggered Dandelion’s ID too * tetheredAnimal_x: Tethered Animal Avatar’s x position during the loop was closed * tetheredAnimal_z: Tethered Animal Avatar’s z position during the loop was closed * TDuration: Trial duration in seconds * Prestim: Pre-stimulation duration in seconds * Poststim: Post-stimulation duration in seconds * FrameDuration: The time between each scene frame update during the loop was closed * Intervention_parts: Intervention setting names * Intervention_parts_values: Intervention setting values * PrestimStart: Pre-stimulation start time in YYYYMMDD\_ hours minutes.milliseconds format * ClosedloopStart: Loop closed start time in YYYYMMDD\_ hours minutes.milliseconds format * PoststimStart: Post-stimulation start time in YYYYMMDD\_ hours minutes.milliseconds format * PoststimEnd: Post-stimulation end time in YYYYMMDD\_ hours minutes.milliseconds format * OOI_name: Names of Object of Interest (OOI) * OOIPos_x: OOI’s x position in Flower Scene * OOIPos_z: OOI’s z position in Flower Scene * EndOOI_xpos: Proximity triggered OOI’s x position * EndOOI_zpos: Proximity triggered OOI’s z position * EndOOI_name: Proximity triggered OOI name * EndOOI_col: Proximity triggered OOI’s color * EndOOI_x_transfrom: Proximity triggered OOI’s x position during the loop was closed * EndOOI_z_transfrom: Proximity triggered OOI’s z position during the loop was closed * EndOOI_x_transfrom: Proximity triggered OOI’s x position during the loop was closed * date: Recorded date in YYYYMMDD format * time: Recorded time in hours minutes seconds format * OOI_x_transfrom: OOIs’ x position during the loop was closed * OOI_z_transfrom: OOIs’ z position during the loop was closed * TrialDataYYYYMMDD_######.mat, which contains data for each trial. This file contains information below * PrestimStart: Pre-stimulation start time in YYYYMMDD\_ hours minutes.milliseconds format * ClosedloopStart: Loop closed start time in YYYYMMDD\_ hours minutes.milliseconds format * PoststimStart: Post-stimulation start time in YYYYMMDD\_ hours minutes.milliseconds format * PoststimEnd: Post-stimulation end time in YYYYMMDD\_ hours minutes.milliseconds format * Date: Recorded date in YYYYMMDD format * Time: Recorded time in hours minutes seconds format * TDuration: Trial duration in seconds * Prestim: Pre-stimulation duration in seconds * Poststim: Post-stimulation duration in seconds * EndTrial: Trial end, either Duration or Proximity. In case of Proximity, you will get triggered Dandelion’s ID too * YawThrustSetting: Yaw and thrust gain settings * OOI_name: Names of Object of Interest (OOI) * OOI_ID: OOI ID number in CAVE * OOIPos_x: OOI’s x position in Flower Scene * OOIPos_z: OOI’s z position in Flower Scene * OOIfile: OOI’s Transform CSV file names * TetheredAnimalPos: Tethered Animal Avatar’s position data before and after the loop was closed * LoopClosed: Frame number when the loop was closed * LoopOpened: Frame number when the loop was opened * PostStimFinished: Frame number when the trial ended * tetheredAnimal_x: Tethered Animal Avatar’s x position during the loop was closed * tetheredAnimal_y: Tethered Animal Avatar’s y position during the loop was closed * tetheredAnimal_z: Tethered Animal Avatar’s z position during the loop was closed * TrialName: Trial name * OOI_x_transfrom: OOIs’ x position during the loop was closed * OOI_z_transfrom: OOIs’ z position during the loop was closed * FrameDuration: The time between each scene frame update during the loop was closed * Intervention_parts: Intervention setting names * Intervention_parts_values: Intervention setting values * PositionAfter5sec_Cntl.mat, which contains hoverfly x and z coordinates 5 sec into each control trial. This file contains information below: * pos5secX_Cntl_Prox: The tethered Animal Avatar’s x position 5 sec into control trials that triggered the proximity criterion * pos5secX_Cntl_Dur: The tethered Animal Avatar’s x position 5 sec into control trials that did not trigger the proximity criterion * pos5secZ_Cntl_Prox: The tethered Animal Avatar’s z position 5 sec into control trials that triggered the proximity criterion * pos5secZ_Cntl_Dur: The tethered Animal Avatar’s z position 5 sec into control trials that did not trigger the proximity criterion * PositionAfter5sec_Test.mat, which contains hoverfly x and z coordinates 5 sec into each test trial. This file contains information below: * pos5secX_Test_Prox: The tethered Animal Avatar’s x position 5 sec into control trials that triggered the proximity criterion * pos5secX_Test_Dur: Tethered Animal Avatar’s x position 5 sec into control trials that did not trigger the proximity criterion * pos5secZ_Test_Prox: Tethered Animal Avatar’s z position 5 sec into control trials that triggered the proximity criterion * pos5secZ_Test_Dur: Tethered Animal Avatar’s z position 5 sec into control trials that did not trigger the proximity criterion #### Figure9RawData.zip We used photodiodes to determine the time for closing the loop, using a video with a square flickering between black and white, played on an iPhone placed in the hoverfly’s position. This resulted in a corresponding black-to-white change on the stimulus screens. The black-to-white change on both the iPhone and the stimulus screen were recorded with photodiodes at 10 kHz. This data can be found in Figure9RawData/ 20230508 photodiode/ PhotodiodeData. Under this there are 4 folders corresponding to the 4 measurements in Fig. 9D. Each one of these contains subfolders labeled after the data and time of recording. Inside each there is data_block file which contains the photodiode recording of the iPhone (row 2) and the AlienWare stimulus screen (row 1). This latency was compared to the data reported in CAVE’s DLC-Data.csv file. The time between each video frame update was defined as the difference between sequential unique instances of “Time Frame was Captured”. The time taken by DLC-live to perform its pose estimation is reported in the “DLC_Latency” column in the DLC-Data.csv file. To quantify the time taken by Unity to calculate the WBA and the requisite scene update, we used the following equations based on information from the DLC-Data.csv file: Unity_time = FrameCreated - Time Frame was Captured - DLC_Latency The DLC-Data.csv file can be found in Figure9RawData/ 20230508 photodiode/ DLC 4points_NA #### Latency\_measurement\_data.zip Additional raw data used for latency measurements is found in the folder latency_measurement_data/with_millisecond_precision/. These follow the same naming structure to Figure 4 data described above. Latency measurement data ready for analysis is found in .rds format at Figure4Data/latency_millisecond_precision.rds. #### Csv\_files.zip ##### Fig1D\_camera\_settings.CSV Each column shows one combination of spatial and temporal resolution for the camera. E.g. The column titled Latency_240_100_NA shows the time in ms between subsequent frame updates when the camera used a spatial resolution of 240x320 pixels filming at 100 Hz. ##### Fig8C\_proximity.csv The left-hand column shows proximity ratio when using the empty scene. The right-hand column shows the proximity ratio when using the flower scene. The ratio is given on a scale from 0 to 1. Each row shows data from an independent hoverfly. ##### Fig8D\_MinDistance.csv The right-hand column shows the minimum distance in meters to either flower when using the flower scene. The left-hand column shows the minimum distance to the corresponding positions when using the empty scene. ##### Fig8E\_pathlength.csv The left-hand column shows the duration (in ms) of each trial, and the right-hand column the corresponding path length (in m) for the same trial. ##### Fig8G\_weighted\_path\_sco.csv The left-hand column shows the weighted path score when using the empty scene, and the right-hand column the score when using the flower scene. The weighted path score is given on a scale from 0 to 8. ##### Fig8H\_flower\_straightness.csv The left-hand column shows the path straightness when the trials ended with the duration setting, and the right-hand column the path straightness when the trials ended with the proximity setting. Both columns come from the trials using the flower scene. The straightness is given on a scale from 0 to 1. ##### Fig9B\_latency.csv Column one shows the time taken to update each video frame. Column 2 shows the time taken by DLC to extract the tracked body positions. Column 3 shows the time taken by Unity to calculate the required scene changes (rotations and translations). The data in each row of these three columns come from the same frame update. The fourth column shows the time taken to close the loop, as measured with photodiodes. All units are given in ms. ##### Fig9C\_built\_vs\_editor.csv The data show the comparison of the time taken (in ms) to close the loop, as measured with photodiodes, when using a built version of Unity (left) or running it from the Editor (right). ##### Fig9D\_latency\_different\_setting.csv The data show the comparison of the time taken (in ms) to close the loop, as measured with photodiodes, when using DLC to track 4 points (column 1), 12 points (column 2), 12 points and recording the video (column 3), and 12 points and recording the video and showing the video live on the screen (column 4). ## Code/Software #### Figure 4 data analysis We have uploaded all R scripts associated with fiddlercrab Fictrac-Unity experiments in the paper. Briefly, to test the FicTrac-Unity closed loop integration, we used tethered fiddler crabs walking on a trackball and compared their responses to a virtual crab and bird in closed and open loop. We recorded the movement path of the animals and compared the distance they ran from virtual crabs and birds in each experiment. This README file explains the script folder structure, features of the data analysis and the steps to reproduce analysis and figures. ##### R folder structure All R scripts are located in the root directory along with helper code in the functions directory. * The individual scripts to reproduce analysis are named as step#_description, based on the run order and basic function. * The functions subfolder includes functions required by analysis scripts. * load_neve_logs.R finds log files produced by Unity experiments into R. * get_vars_at_stimulus_states.R loads variables in from log files produced by Unity experiments into R. * get_params_from_config_file.R loads parameters used to control the experiment into R. * add_fictrac_tracking_data.R loads log files from Fictrac into R. ##### Software and packages We used R 4.2.0 together with RStudio 2023.06.2 We used packages: av, imager, tidyverse, lubridate, dplyr, readr, progressr, ggpubr and lme4. ##### Data analysis and scripts used for each figure/result * Run linear mixed effects analysis and create the fiddlercrab fictrac-unity experiment figure (Figure 4). * Open the analysis.Rproj file with RStudio to start the RStudio project. * Run step1_create_dataset.R (although this can be skipped with output already existing in data/data.rds) * This loads log files found in data/configs, data/fictrac_logs and data/trial_logs directories. * It then reshapes the dataset into a format ready for analysis in step2, below. * Run step2_make_figures_and_analyse.R. * This calculates the distances ran and runs linear mixed effects models, calculates significance of variables and plots Figure 4. ##### Calculate latency estimates * Run step3_measure_latency.R. * This loads log files and videos used to calculate latency, found in latency_measurement_data/with_millisecond_timestamp/configs, latency_measurement_data/with_millisecond_timestamp/fictrac_logs, latency_measurement_data/with_millisecond_timestamp/fictrac_videos and latency_measurement_data/with_millisecond_timestamp/trial_logs. * It then runs a cross-correlation between pixel position of the vertical line on the screen in video recordings and the rotation of the ball in the x-axis from Fictrac. #### Figure 8 data analysis We have uploaded all Matlab and R scripts associated with the paper. Briefly, we tested whether female *Eristalis tenax* hoverflies navigate in the CAVE controlled VR using a sparse scene as well as one with two OOIs, each a yellow dandelion plant. We extracted the resulting avatar yaw and position using the y-rotation and x-z coordinates reported in the Transform.csv file. We first analyzed proximity rate in a sparse scene, called ‘Control scene’ and in one with two yellow dandelion plants, called ‘Flower scene’. We quantified the path lengths from each trial as a function of trial duration. We also compared the path straightness when the proximity criterion was fulfilled with trials where it was not. This read me file explains the script folder structure, common features of the data analysis, and the data analysis stages and scripts used for each figure. ##### Matlab folder structure All Matlab scripts are located in the folder called Matlab_scripts. There is the Figure8 subfolder, includes all scripts used for analysis in Figure 8. The individual scripts are named as step#_descriptions, based on the run order and basic function. There is the functions subfolder, incudes all functions and variables commonly used in analysis * othercolor.m is a function to return a matrix containing a colormap * colorData.mat contains supporting colormaps ##### Software and packages We used MATLAB Version: 9.11.0.2358333 (R2021b) together with the Data Visualization Toolbox 2.2 We used Rstudio Version 2023.09.1+494 ##### Data analysis and scripts used for each figure * Analyze Trial data produced by CAVE * Open Matlab and run the script named step1_VRTrialDataAna.m * This script loads '*.Sequence.csv file, which contains sequence setting information such as sequence name, Yaw and Thrust gain settings, and interpolation information * This script loads *Trial.csv file, which contains trial setting information such as time, trial name, information of OOIs in the scene, and end of trial (Proximity, Duration, or Skip) * This script loads \_TetheredAnimal_0.Transform.csv file, which contains tethered hoverfly avatar’s x-z coordinates and y-rotation. * This script produces TrialData***####.mat where **** is date and #### is time. It will be saved in each sequence folder. * Analyze Sequence data produced by CAVE * Open Matlab and run the script named step2\_ VRSequenceDataAna.m * This script loads TrialData****####.mat, which is produced in step1 * This script produces SeqData****_####.mat to store all trial data in each Sequence. The **** specify date and #### specify time. It will be saved in each sequence folder. * Analyze Control Scene data of each animal * Open Matlab and run the script named step3_VRControlSceneAna.m * This script loads each SeqData**_####.mat for all sequences recorded on each animal. * This script produces OutputControl**.mat to store all Control Scene data recorded on that date. The **** specify date. * Analyze Flower Scene data of each animal * Open Matlab and run the script named step3_VRFlowerSceneAna.m * This script loads each SeqData**_####.mat for all sequences recorded on each animal. * This script produces OutputCircleFlower**.mat to store all Flower Scene data recorded on that date. The **** specify date. * Analyze Control Scene data and plot an example path figure (Figure 8A) * Open Matlab and run the script named step4_Fig8A_VRControlSceneOutputAna.m * This script loads OutputControl****.mat stored in Figure8Data/20231213/Figure8AB * This script analyses control data separately based on Yaw and Thrust gain methods * This script performs Post analysis to identify whether each trial could fulfil the proximity criteria\ * This script produces ControlRslt****.mat which contains analyzed control data * Analyze Flower Scene data and plot an example path figure (Figure 8B) * Open Matlab and run the script named step4_Fig8A_VRFlowerSceneOutputAna.m * This script loads CircleFlower****.mat stored in Figure8Data/20231213/Figure8AB * This script analyses data separately based on Yaw and Thrust gain methods * This script produces TestSceneRslt****.mat which contains analyzed Flower Scene data * Analyze Control Scene data in all control folders * Open Matlab and run the script named step4_VRControlSceneOutputAnaAllData.m * This script loads OutputControl****.mat stored in control folder named e.g., F1_6controls located in each date folder * This script analyses control data separately based on Yaw and Thrust gain methods * This script performs Post analysis to identify whether each trial could fulfil the proximity criteria\ * This script produces ControlRslt****.mat which contains analyzed control data * Analyze Flower Scene data all flower scene data folders * Open Matlab and run the script named step4_VRFlowerSceneOutputAnaAllData.m * This script loads CircleFlower****.mat stored in flower scene data folder named e.g., 01_Female located in each date folder * This script analyses data separately based on Yaw and Thrust gain methods * This script produces TestSceneRslt****.mat which contains analyzed Flower Scene data * Quantify Proximity Rate, Trial Duration and Path Length in Control Scene (Figure 8CE) * Open Matlab and run the script named Step5_Fig8CE_VRControlRsltAna.m * This script loads ControlRslt****.mat stored in control folder named e.g., F1_6controls located in each date folder * This script analyses Proximity Rate by using information whether each trial could fulfil the proximity criteria * This script quantifies the trial duration and path length separately based on trial end (Proximity or Duration) * Copy Fig8C_ProximityRate_Control data straight into the Prism file named Figure8 * Copy Fig8D_TrialDurationPathLength_Control_Proximity data straight into the Prism file named Figure8 * Copy Fig8D_TrialDurationPathLength_Control_Duration data straight into the Prism file named Figure8 * Quantify Proximity Rate, Trial Duration and Path Length in Flower Scene (Figure 8CE) * Open Matlab and run the script named Step5_Fig8CE_VRFlowerSceneRsltAna.m * This script loads TestSceneRslt****.mat stored in flower scene data folder named e.g., 01_Female located in each date folder * This script analyses Proximity Rate by using information whether each trial could fulfil the proximity criteria\ * This script quantifies the trial duration and path length separately based on trial end (Proximity or Duration) * Copy Fig8C_ProximityRate_Test data straight into the Prism file named Figure8 * Copy Fig8D_TrialDurationPathLength_Test_Proximity data straight into the Prism file named Figure8 * Copy Fig8D_TrialDurationPathLength_Test_Duration data straight into the Prism file named Figure8 * Quantify Minimum distance to flower locations in Control Scene (Figure 8D) * Open Matlab and run the script named Step5_Fig8DF_VRMinDistance_5sPosControlScene.m * This script loads ControlRslt****.mat stored in control folder named e.g., F1_6controls located in each date folder * This script calculates the minimum distance to corresponding positions of either of the two dandelions in the empty scene. * This script also identifies the hoverfly position 5 seconds into each trial for control scenes and saves the data as positionAfter5sec_Cntl.mat in Outputpath specified as e.g., '/Users/#####/Documents/MATLAB/ClosedLoopData/ToUpload_MethodPaper/Figure8Data' * Copy Fig8D_minDistance_Control data straight into the Prism file named Figure8 * Copy Fig8G_statsCSVfile_Cntl data straight into CSV file named VRmethod_stats_minDistance.csv for statistical analysis in R * Quantify Minimum distance to flower locations in Flower Scene (Figure 8D) * Open Matlab and run the script named Step5_Fig8DF_VRMinDistance_5sPosFlowerScene.m * This script loads TestSceneRslt****.mat stored in flower scene data folder named e.g., 01_Female located in each date folder * This script calculates the minimum distance to either of the two dandelions in the flower scene. * This script also identifies hoverfly position 5 seconds into each trial for flower scenes and saves the data as PositionAfter5sec_Test.mat in Outputpath specified as e.g.,'/Users/#####/Documents/MATLAB/ClosedLoopData/ToUpload_MethodPaper/Figure8Data' * Copy Fig8D_minDistance_Flower data straight into the Prism file named Figure8 * Copy Fig8G_statsCSVfile_Flower data straight into CSV file named VRmethod_stats_minDistance.csv for statistical analysis in R * Plot a location map showing the hoverflies’ position 5 s into each trial (Figure 8F) * Open Matlab and run the script named Step6_Fig8F_VRHoverflyPositionAfter5sec.m * This script loads PositionAfter5sec_Cntl.mat and PositionAfter5sec_Test.mat produced in Step5, and stored in a folder named Figure8Data * This script plots the position of the hoverflies 5 s into each trial, color coded into experiments in the empty scene (green) and trials with the two flowers (pink). The concentric circles around each flower have increasing diameter of 0.2 m. * Quantify the Weighted Path Score in the Control Scene (Figure 8G) * Open Matlab and run the script named Step5_Fig8G_VRWeightedPathScoreControlScene.m * This script loads ControlRslt****.mat stored in control folder named e.g., F1_6controls located in each date folder * This script calculates the Weighted Path Score in control scene * We score each frame linearly between 0 (outside the largest circle) and 7 (inside the smallest circle) and define the weighted path score as the average across frames * Copy Fig8G_WeightedPath_Cntl data straight into the Prism file named Figure8 * Copy Fig8G_statsCSVfile_Cntl data straight into CSV file named VRmethod_stats_weightedpathscore.csv for statistical analysis in R * Quantify Path straightness in the Flower Scene (Figure 8H) * Open Matlab and run the script named Step5_Fig8H_VRPathStraightnessFlowerScene.m * This script loads TestSceneRslt****.mat stored in the flower scene data folder named e.g., 01_Female located in each date folder * This script recalculates Path Straightness for Duration ended trials in Flower Scenes. As 36 dandelion trials triggered the proximity criterion, we randomly selected 36 out of the remaining 77 dandelion trials. We then cropped these to the same durations. * Copy Fig8H_PathStraightness_Flower data straight into the Prism file named Figure8 * Copy Fig8H_statsCSVfile_Flower data straight into CSV file named VRmethod_stats_straightness.csv for statistical analysis in R * Statistical analysis and scripts used for Figure 8DGH * Open Rstudio and run the script named VRmethod_HoverflyNavigationData_stats.R * This script loads VRmethod_stats_minDistance.csv, VRmethod_stats_weightedpathscore.csv, VRmethod_stats_straightness.csv produced in Matlab Step5 scripts and stored in a folder named VRmethod_R * For statistical analysis of minimum distance to flowers, Weighted Path Scores, and path straightness in flower scene, we used linear mixed effects models using the nlme package to calculate the statistical significance of flower presence or proximity criterion being triggered. Animal ID was included as a random effect. Since the residuals were not normally distributed, we then used a permutation approach to evaluate significance by randomly permuting flower presence or proximity criterion 5,000 times. ## Additional Software The FicTrac-Unity interface can be found here: [https://github.com/jakemanger/fiddlercrabvr](https://github.com/jakemanger/fiddlercrabvr) The CAVE interface, user manuals, user videos and other documentation is available here: [https://github.com/HoverflyLab/CAVE_TetheredFlightArena](https://github.com/HoverflyLab/CAVE_TetheredFlightArena)