Skip to main content

ZebraZoom's new output data format: hdf5 file

Configuration file​

If you created a configuration file with the version of ZebraZoom 1.34.00 or above, the parameter:

"storeH5": 1

should have been placed in any configuration file you've created (unless you've specifically asked to use the legacy .json format on the last page of the configuration file creation pipeline), in which case the output of ZebraZoom's tracking will be an hdf5 file.

General structure of the hdf5 file​

The general structure of this output file is as follows:

Attributes: ['videoFPS', 'videoPixelSize', 'numberOfFrames', 'pathToRawVideo', 'ZebraZoomVersionUsed', 'trackingStartTime', 'trackingEndTime', 'timeSpentOnWellDetection', 'timeSpentOnBackgroundExtraction', 'timeSpentOnTracking', 'timeSpentOnParametersExtraction']

//configurationFileUsed/
    Attributes: ['configFileParam1', 'configFileParam2', 'configFileParam3', etc...]
    
//wellPositions/
               /well0/
                   Attributes: ['topLeftX', 'topLeftY', 'lengthX', 'lengthY']
               /well1/
                   Attributes: ['topLeftX', 'topLeftY', 'lengthX', 'lengthY']

//dataForWell0/
              /dataForAnimal0/
                             /dataPerFrame/
                                          /HeadPos
                                             Attributes: column_names = ['X' 'Y']
                                          /Heading
                                          /TailAngle
                                          /BoutNumber
                                          /tailPositionX
                                             Attributes: Columns = ['TailPosX0' 'TailPosX1' 'TailPosX2' 'TailPosX3' 'TailPosX4' 'TailPosX5' 'TailPosX6' 'TailPosX7' 'TailPosX8' 'TailPosX9']
                                          /tailPositionY
                                             Attributes: Columns = ['TailPosY0' 'TailPosY1' 'TailPosY2' 'TailPosY3' 'TailPosY4' 'TailPosY5' 'TailPosY6' 'TailPosY7' 'TailPosY8' 'TailPosY9']                     
                                          /curvature
                                             Attributes = [parametersUsedForCalculation]
                                             Attributes: Columns = ['Pos1' 'Pos2' 'Pos3' 'Pos4' 'Pos5' 'Pos6' 'Pos7' 'Pos8']
                                          /tailAngleHeatMap
                                             Attributes = [parametersUsedForCalculation]
                                             Attribute: column_names = ['Pos0' 'Pos1' 'Pos2' 'Pos3' 'Pos4' 'Pos5' 'Pos6' 'Pos7' 'Pos8' 'Pos9']
                                             
                             /listOfBouts/
                                 Attributes: ['numberOfBouts']
                                         /bout0/
                                               /bendAmplitude
                                               /bendTiming
                                         /bout1/
                                               /bendAmplitude
                                               /bendTiming
                             /kinematicParametersPerBout/
                                 Attributes: ['boutStart', 'boutEnd', 'Mean TBF', 'Mean absolute TBA', 'Number of Oscillations', etc...]

Reading an hdf5 output file directly with Python​

Here is an example of how an hdf5 output file can be read:

import h5py
filename = "./zebrazoom/ZZoutput/headEmbeddedZebrafishLarva_2023_05_22-14_06_24.h5"
f = h5py.File(filename, "r")
print(f.keys())
print(f["dataForWell0/dataForAnimal0/dataPerFrame"].keys())
print(f["dataForWell0/dataForAnimal0/dataPerFrame/HeadPos"][:])

The most recommended way of reading this hdf5 file however is to use the ZebraZoom Data API. This data API allows to easily retrieve data from the hdf5 with code as simple as:

import zebrazoom.dataAPI as dataAPI
videoName = "headEmbeddedZebrafishLarva"
[videoFPS, videoPixelSize] = dataAPI.getFPSandPixelSize(videoName)
[curvatureValues, xTimeValues, yDistanceAlongTheTail] = dataAPI.getCurvaturePerBout(videoName, numWell, numAnimal, numBout)
dataAPI.plotCurvatureYaxisApproximate(curvatureValues, xTimeValues, yDistanceAlongTheTail, videoFPS, videoPixelSize)