The canonical location of this page is https://strawlab.org/schemas/tethered-h5/1.0.

tethered-h5 v1.0 schema

Description

This is an HDF5 file for saving tethered flight data. It allows recording left and right wingstroke amplitude responses to visual stimuli characterized by two parameters. Planned improvements allow more general response and stimulus specification.

These three datasets are in this file:

• /metadata - JSON-encoded string describing experimental conditions
• /response - data containing the behavioral response of the fly
• /stimulus - data containing information describing the visual stimulus

Metadata

Here is an example metadata section. It is a JSON string held in an HDF5 variable length string array.

{"timestamp": "2011-05-24 16:56:26+02:00",

 "experiment script": "hausen4.py",

 "experimenter": "Karin",

 "genotype": "R27BO3xTNTa"}

Response

The HDF5 description is:

 DATATYPE  H5T_COMPOUND {

   H5T_STD_I64LE "acquire_secs";

   H5T_STD_I64LE "acquire_nsecs";

   H5T_IEEE_F64LE "now_secs";

   H5T_IEEE_F64LE "right_radians";

   H5T_IEEE_F64LE "left_radians";

 }

Thus, the columns are:

• acquire_secs (int64) and
• acquire_nsecs (int64) specify the "acquisition time".
• now_secs (float64) specifies the "finished processing time".
• right_radians (float64) and
• left_radians (float64) specify the wingstroke amplitude.

The "acquisition time" is the time at which the image capturing the data was triggered. It can be used to calculate the earliest time the data could possibly reflect. It is held in two columns: acquire_secs, the number of seconds since January 1, 1970, and acquire_nsecs, the number of nanoseconds since the start of the current second.

The "finished processing time" is the time at which the response processing was finished, and can be used to calculate the last possible moment the data could possibly reflect. But because this time also is after the image processing time, this time minus the acquisition time could also reasonably be used to calculate processing latency. It is held in the now_secs column, which is the number of seconds since January 1, 1970.

Stimulus

The HDF5 description is:

DATATYPE  H5T_COMPOUND {

   H5T_STD_I64LE "stim_code";

   H5T_IEEE_F64LE "now_secs";

   H5T_IEEE_F64LE "freq_hz_or_sf";

   H5T_IEEE_F64LE "position_radians_or_tf";

}

Thus, the columns are:

• stim_code (int64) describes the stimulus class
• now_secs (float64) specifies the time at which the stimulus was determined
• freq_hz_or_sf (float64) stimulus parameter 1
• position_radians_or_tf (float64) stimulus parameter 2

Example: reading metadata from the command line

To dump the metadata dataset in the file tethered-h5-data-file.h5 using the h5dump command, use this:

h5dump -d /metadata tethered-h5-data-file.h5

Note about user block in .h5 format

The first bytes of the file are an HDF5 user block that describe the schema of the file. (In other words, it's a descriptor that points to this page.) By putting the first bytes in this file, the freedesktop.org file identification machinery can automatically identify this file.