This library serves to load, parse, and serve the contents of H5 files from the lab's Arduino- and Voyeur-based behavior setups.
- Using PyPi: Simply run
pip install dewan_h5and the latest version will be pulled from PyPi - Local Installation
- Clone the repository using
git clone https://github.com/OlfactoryBehaviorLab/dewan_h5 - Navigate into the
dewan_h5directory - Execute
pip install .orpip install -e .if you want the repository to be editable
- Clone the repository using
Info: The DewanH5 class is intended to be used within a Python context manager.
Usage outside a context manager is not supported
from dewan_h5 import DewanH5
file_path = 'path/to/h5/file/file.h5'
with DewanH5(file_path) as dh5:
# Do things here
# When done, the file is automatically closed when the context is exited
print(dh5) # Print summary of contents of file
# Context is now exitedfile_path : None, Path, or strPath to the H5 file- None: If None is explicitly supplied, a file selector will open
- Path: pathlib.Path representing the location of the H5 file
- str: string containing raw path to H5 file; internally converted to a pathlib.Path
trim_trials : boolIndicates whether below trials are trimmed from the raw dataset- When set to
truethe following are trimmed:- The first 10 Go Trials
- If three Go trials are missed in a row, everything after (and including) the third missed trial are dropped
- When set to
suppress_errors : boolDetermines whether certain errors are suppressed and handled silently or allowed to propagate to the context manager
file_path : pathlib.PathSystem-agnostic path to the H5 filefile_name : strFilename with suffixsuppress_errors : boolDetermines whether errors are suppressed and handled silently or allowed to propagate to the context managertrim_trial : boolNormally, certain trials are trimmed from the raw dataset. This indicates whether those trials were trimmed or left in the dataset
date : strDate the H5 file was createdtime : strTime the H5 file was createdmouse : intID number of animal ran in experimentrig : strRig name experiment was ran in
odors : list[str]List of all odors present in H5 File- This includes blank
concentrations : list[str]List of all concentrations present in H5 file
All performance values are calculated after trimming (if applicable)
total_trials : intTotal number of trials in experimentgo_performance : floatPercentage of correct go trials vs total number of go trialsnogo_performance : floatPercentage of correct nogo trials vs total number of nogo trialstotal_performance : floatPercentage of correct go and nogo trials vs total number of trials- (correct go trials + correct nogo trials) / total number of trials
three_missed : boolIndicates whether the animal missed three go trials in a rowlast_good_trial : intIf three_missed is true, this is the last trial included in the datadid_cheat : boolIndicates whether cheating was detected- See description of cheating check below
cheat_check_tirals : list[int]List of cheating check trial indices
Note 1: If trimming the dataset, the below containers are also trimmed
Note 2: All the timestamps are offset by the FV on time. Negative values represent events before the FV turned on
trial_parameters : pd.DataFramePandas DataFrame containing the parameters recorded for each trial- See list of important parameters below
sniff : dict[int, pd.Series]Dictionary where each key is an int representing a trial number; each Pandas Series contains timestamped samples representing data recorded from the sniff sensorlick1 : dict[int, list]Dictionary where each key is an int representing a trial number; each list contains timestamps for licks of lick sensor 1lick2: dict[int, list]Dictionary where each key is an int representing a trial number; each list contains timestamps for licks of lick sensor 2
- Values:
N-> number of trialsn-> references any arbitrary trialx-> arbitrary number
- File Structure
/: Contains N number of Groups for each trial with an additional group containing the trial data matrixTrials: Matrix containing n rows with columns for multiple parameters captured for each trialTrial000n[type: group] (one group per trial): Holds samples for each trialEvents[type: dataset] (x number of tuples): (timestamp, number of sniff samples)lick1[type: dataset] (x number of arrays): each array contains a variable number of lick timestamps for the 'left' lick tubelick2[type: dataset] (x number of arrays): each array contains a variable number of lick timestamps for the 'right' lick tubesniff[type: dataset] (len(Events) number of arrays): each array contains samples recorded from the sniff sensor
Note: the column names are strings, but I have left the quotations off for clarity
Trial Type [Trialtype, int]: Value which encodes the trial type- 1: Go (no licking)
- 2: NoGo (licking)
Response [_result, int]: Value that represents the response of the animal- 1: Correct "Go" Response >>> The stimulus was a 'Go' stimulus and the animal correctly withheld licking
- 2: Correct "NoGo" Response >>> The stimulus was a 'NoGo' stimulus and the animal correctly licked
- 3: False Alarm / Incorrect "NoGo" Response >>> The stimulus was a "NoGo" stimulus and the animal incorrectly withheld licking
- 4: Unused
- 5: Missed "Go" Response >>> The stimulus was a 'Go' stimulus and the animal incorrectly licked
Note: Some trials are designated "cheating checks" to test whether the animal is utilizing a non-odor cue to get extra water rewards. A cheating check is identified by a trial type of
2with an odor ofblank.
- A response of2indicates CHEATING
- A response of3indicates NO CHEATING
Odor Name [Odor, str]: Name of odorant presented during the trialOdor Concentration [Odorconc, str]: Concentration of odorant presented during the trialOdor Vial Number [Odorvial, int]: Olfactometer vial used to deliver the odorant during the trialInter Trial Interval (ITI) [iti, str]: Time in milliseconds between current trial and next trialMouse ID [mouse, int]: ID number of animal ran in the experimentRig Name [rig, str]: Name of behavioral chamber
This project is licensed under GNU General Public License v3.0. You can find the included copy of the license here. For more information about the license and its terms, please visit SPDX