Package: sleapyfaces
SLEAPyFacesA package for extracting facial expressions from SLEAP analyses with sensible assumptions.Based onthesescripts-DocumentationDescriptionSleapyfaces is a data analysis package for extracting facial expressions of mice from SLEAP analyses. It is designed to work with the SLEAP software package, which provides a graphical user interface for annotating animal behavioral videos. More information on SLEAP is available athttps://sleap.ai. This package also depends on many assumptions about the data format and structure of the SLEAP analyses. It is not intended to be a general tool for extracting facial expressions from SLEAP analyses, but rather a tool for extracting facial expressions from the specific data format and structure used in the lab of Dr. Kay Tye at The Salk Institute for Biological Studies.Table of ContentsSLEAPyFacesDescriptionTable of ContentsCiting:LicenseGetting Started:InstallationUsing pip:Using conda (coming soon):Basic Usage Step by StepImporting the packageCreating a projectBuilding the dataBuilding the trialsNormalizing the dataComplete ExampleProject StructureData Files FormatsDAQ fileBehavioral metadata fileSLEAP fileVideo fileProject Directory StructureAPI Documentationsleapyfaces.project.Projectsleapyfaces.project.Project.buildColumnssleapyfaces.project.Project.buildTrialssleapyfaces.project.Project.meanCentersleapyfaces.project.Project.zScoresleapyfaces.project.Project.analyzesleapyfaces.project.Project.visualizesleapyfaces.experiment.Experimentsleapyfaces.experiment.Experiment.buildDatasleapyfaces.experiment.Experiment.appendsleapyfaces.experiment.Experiment.buildTrialssleapyfaces.io.DAQDatasleapyfaces.io.DAQData.appendsleapyfaces.io.DAQData.saveDatasleapyfaces.io.SLEAPanalysissleapyfaces.io.SLEAPanalysis.getDatasetssleapyfaces.io.SLEAPanalysis.getTrackssleapyfaces.io.SLEAPanalysis.getTrackNamessleapyfaces.io.SLEAPanalysis.appendsleapyfaces.io.SLEAPanalysis.saveDatasleapyfaces.io.BehMetadatasleapyfaces.io.BehMetadata.saveDatasleapyfaces.io.VideoMetadatasleapyfaces.io.VideoMetadata.saveDatasleapyfaces.normalize.mean_centersleapyfaces.normalize.z_scoresleapyfaces.normalize.pcasleapyfaces.structs.Filesleapyfaces.structs.FileConstructorsleapyfaces.structs.CustomColumnsleapyfaces.structs.CustomColumn.buildColumnChangelog:Version 1.0.0 (2022-12-27)Version 1.0.1Version 1.1.0 (in progress)Citing:If you use SLEAPyFaces in your research, this does not fall understandard softwareaccording to thePublication Manualfor the APA, MLA, AMA, Turabian, IEEE, Vancouver style, Harvard style, or Chicago style guides.Please cite the following:A. Ehler,  J. Delahantey, A. Coley, D. LeDuke, L. Keyes, T.D. Pereira, and K. Tye. SLEAPyFaces: A package for extracting facial expressions from SLEAP analyses with sensible assumptions. SLEAPyFaces python package, v1.0.1, 2023. Retrieved fromhttps://github.com/annie444/sleapyfaces/BibTeX:@misc{Ehler2023sleapyfaces,title={SLEAPyFaces: A package for extracting facial expressions from SLEAP analyses with sensible assumptions.},author={Ehler, Analetta andDelahantey, Jeremey andColey, Austin andLeDuke, Deryn andKeyes, Laurel andPereira, Talmo D andTye, Kay},url={https://github.com/annie444/sleapyfaces/},journal={SLEAPyFaces python package},publisher={GitHub repository},volume={v1.0.1},year={2023},month={Dec},day={27}}Please also cite the original SLEAP paper:T.D. Pereira, N. Tabris, A. Matsliah, D. M. Turner, J. Li, S. Ravindranath, E. S. Papadoyannis, E. Normand, D. S. Deutsch, Z. Y. Wang, G. C. McKenzie-Smith, C. C. Mitelut, M. D. Castro, J. D’Uva, M. Kislin, D. H. Sanes, S. D. Kocher, S. S-H, A. L. Falkner, J. W. Shaevitz, and M. Murthy. Sleap: A deep learning system for multi-animal pose tracking. Nature Methods, 19(4), 2022BibTeX:@ARTICLE{Pereira2022sleap,title={SLEAP: A deep learning system for multi-animal pose tracking},author={Pereira, Talmo D andTabris, Nathaniel andMatsliah, Arie andTurner, David M andLi, Junyu andRavindranath, Shruthi andPapadoyannis, Eleni S andNormand, Edna andDeutsch, David S andWang, Z. Yan andMcKenzie-Smith, Grace C andMitelut, Catalin C andCastro, Marielisa Diez andD'Uva, John andKislin, Mikhail andSanes, Dan H andKocher, Sarah D andSamuel S-H andFalkner, Annegret L andShaevitz, Joshua W andMurthy, Mala},journal={Nature Methods},volume={19},number={4},year={2022},publisher={Nature Publishing Group}}}Licensesleapyfacesis distributed under the terms of theMITlicense. The full license text is available in theLICENSEfile.Getting Started:InstallationNote: this installation is not compatible with Windows systems at present.  Currently we have tested this on MacOS Ventura 13.1 and on a Linux server running Debian Buster v10.x.Build locallyClone the repositiory:git clone https://github.com/Tyelab/SLEAPyFaces.gitFrom within the git repository, build the environment locally using conda:conda env create -n sleapyfaces -f environment.yml python=3.10Using pip:pip install sleapyfacesUsing conda (coming soon):conda install -c conda-forge sleapyfacesBasic Usage Step by StepImporting the packageForbasicusage, the package can be imported with the following:fromsleapyfaces.projectimportProjectAlternatively, the package can be imported with the following:importsleapyfacesassfCreating a projectThe project object is the basis for the data analysis. It serves as a container for all of the data produced from a series of experiments, and allows a root object to be created for the data analysis. The project object is initialized with a series of file or file glob patterns, which are used to find the files associated with each experiment. The project object also requires a base path, which is the root directory for the project. The project object can be initialized with the optionalget_globargument set toTrue, which will automatically find the files associated with each experiment. Alternatively, theget_globargument can be set toFalse(default), which will allow the user to manually set the files associated with each experiment as the file arguments. Additionally, there is aniteratorsargument, which is a dictionary of iterators that can be used to iterate over the project structure. Theiteratorsargument is optional, and if not provided, the project object will assume that the project follows a specific structure.Without iterators + with glob:project=Project(DAQFile="*.csv",BehFile="*.json",SLEAPFile="*.h5",VideoFile="*.mp4",base="/base/path/to/project",get_glob=True)With iterators + without glob:project=Project(DAQFile="DAQOutput.csv",BehFile="ExperimentMetadata.json",SLEAPFile="SLEAPAnalysis.h5",VideoFile="FacialVideo.mp4",base="/base/path/to/project",iterators={"Label 1":"/relative/path/to/week1","Label 2":"/relative/path/to/week2","Label 3":"/relative/path/to/week3","Label 4":"/relative/path/to/week4",...}})Theiteratorspaths are relative to thebasepath. If no iterators are provided, the project object will assume that the project follows the default structure outlined below. The default labels then are"week 1", "week 2", "week 3", "week 4", ....Building the dataThe project object has abuildColumnsmethod, which is used to build the columns of the data. ThebuildColumnsmethod takes two arguments:columnsandvalues. Thecolumnsargument is a list of column titles, and thevaluesargument is a list of values for each column. ThebuildColumnsmethod will build the columns of the data, and will also build the iterators for each column. ThebuildColumnsmethod can be called multiple times, and each time it is called, it will add a new column to the data.project.buildColumns(columns=["Mouse"],values=["CSE008"])Building the trialsThe project object has abuildTrialsmethod, which is used to build the trials of the data. ThebuildTrialsmethod takes four arguments:TrackedData,Reduced,start_buffer, andend_buffer. TheTrackedDataargument is a list of the tracked data columns from the DAQ file that will be used to build the based on the DAQ timestamps. TheReducedargument is a list of boolean values, which indicate whether the tracked data should be reduced to a single value for each trial. This is used in this example for the"LED590_on"column, as the LED turns on and off multiple times during the experiment. To keep thetrialDatafrom intitializing a new trial for each timestamp in the"LED590_on"column, reduced is set to true. Thestart_bufferargument is thenumber of milliseconds beforethetrial start timethat should be included in the trial. Theend_bufferargument is thenumber of milliseconds afterthetrial start timethat should be included in the trial. ThebuildTrialsmethod will build the trials of the data, and will also build the iterators for each trial. ThebuildTrialsmethod can be called multiple times, and each time it is called, it will rebuild the trials of the data. This is useful if you want to build the trials based on different tracked data columns, or if you want to change the start and end buffers.project.buildTrials(TrackedData=["Speaker_on","LED590_on"],Reduced=[False,True],start_buffer=10000,end_buffer=13000)Normalizing the dataSo far there are two normalization methods available:Mean CenteringThemeanCentermethod will iterate recursively to the smallest data frame in the project, and then mean-center its way up the project tree. More precisely, themeanCentermethod first mean centers each trial from each experiment. Then, it willmeanCentereach experiment in the project. Finally, it willmeanCenteracross all the experiments in the project. This method will mean-center the data in place, and will not return anything. However, it does expose aall_dataattribute, which is apd.DataFrameof all the data in the project.project.meanCenter()Z-ScoringThezScoremethod assumes the data has already been mean-centered, and will further z-score the data across all the experiments in the project.ThezScoremethod will iterate recursively to the smallest data frame in the project, and then z-score its way up the project tree. This method will z-score the data in place, and will not return anything.project.zScore()For convenience, you can also normalize the data in one step:project.analyze()Complete ExampleThis implementation of the data objects is roughly 10x faster than the scripted version of the data analysis. The full example is shown below:fromsleapyfaces.projectimportProjectproject=Project(DAQFile="*.csv",BehFile="*.json",SLEAPFile="*.h5",VideoFile="*.mp4",base="/base/path/to/project",get_glob=True)project.buildColumns(columns=["Mouse"],values=["CSE008"])project.buildTrials(TrackedData=["Speaker_on","LED590_on"],Reduced=[False,True],start_buffer=10000,end_buffer=13000)project.analyze()project.visualize()data=project.pcas["pca3d"]Project StructureData Files FormatsDAQ fileThis file is the output of the DAQ collection, which is used to record the TTL pulses from all of the stimuli used in the experiment. The DAQ file is usually a CSV file, which contains the timestamps for each TTL pulse, and a column for each TTL pulse being tracked. These timestamps are all relative to the experiment start time and are in milliseconds. The TTL pulses are named according to the following convention:Stimuli_on- The TTL pulse for when the stimuli startsStimuli_on- The TTL pulse for when the stimuli endsBehavioral metadata fileThis file is the output of the experimental parameters output frombruker_controlas a JSON file. This file contains the experimental parameters for the experiment, including the trial types used, the number of trials, and the inter-trial interval.SLEAPyFacesassumed that the file follows the following structure:{"beh_metadata":{..."any_keys":"any_values",..."trialArray":[1,1,1,0,1,0,1,1,...],"ITIArray":[16848,23012,25678,19107,...],..."any_keys":"any_values",...}}Note that this is the default output frombruker_controland does not need to be modified.SLEAP fileTheSLEAPfile is the output of thesleap-convertcommand from theSLEAPsoftware package, which is used to track the facial expressions of the mice. TheSLEAPfile is a HDF5 file, which contains the tracking data for each frame of the video using a common skeleton across all experiments. TheSLEAPfile also contains the metadata for the experiment, which includes the tracking accuracy, the number of frames in the video, and the number of mice in the video. TheSLEAPanalysis file can be obtained from the following command:sleap-convert --format analysis -o /path/to/output.h5 /path/to/input.slporsleap-convert --format h5 -o /path/to/output.h5 /path/to/input.slpFurther documentation on this command is available onthisSLEAPdocumentation page.Video fileThe video file is the raw video file that was used to generate the facial trackings. The video file is used to extract the frame rate of the video, which is used to accurately calculate the timestamps and append them to theSLEAPdata. The video file can be any video format that is supported byffmpeg, which includes.mp4,.avi,.mov,.mkv, and many more.Project Directory Structure/base/path/to/project
    │
    └───20231208
    │   │   DAQOutput.csv
    │   │   ExperimentMetadata.json
    |   |   SLEAPAnalysis.h5
    |   |   FacialVideo.mp4
    │
    └───20231215
    |   │   DAQOutput.csv
    │   │   ExperimentMetadata.json
    |   |   SLEAPAnalysis.h5
    |   |   FacialVideo.mp4
    |
    └─── ...Note that the files do not have to be named as shown above, but the file extensions must be correct for the DAQ file as*.csv, the metadata file as*.json, and theSLEAPanalysis file as*.h5. The video file can be any video format that is supported byffmpeg.By default, the sub-directories can be named anything, as long as the date proceeds any other naming. The dates must be in the formatYYYYMMDD, so the experiments can be sorted by date.e.g.20231208_Exp1or20231208_Exp2are valid file names, butExp1_20231208is notHowever, this functionality can be disabled by specifying the sub-directory paths and their respective labels in theiteratorsargument of theProjectobject. For example, if the project directory structure is as follows:/base/path/to/project
    │
    └───Day1
    |   |
    |   └───Exp1
    │   │   |   DAQOutput.csv
    │   │   |   ExperimentMetadata.json
    |   |   |   SLEAPAnalysis.h5
    |   |   |   FacialVideo.mp4
    |   |
    |   └───Exp2
    │   │   |   DAQOutput.csv
    │   │   |   ExperimentMetadata.json
    |   |   |   SLEAPAnalysis.h5
    |   |   |   FacialVideo.mp4
    │
    └───Day2
    |   |
    |   └───Exp1
    │   │   |   DAQOutput.csv
    │   │   |   ExperimentMetadata.json
    |   |   |   SLEAPAnalysis.h5
    |   |   |   FacialVideo.mp4
    |   |
    |   └───Exp2
    │   │   |   DAQOutput.csv
    │   │   |   ExperimentMetadata.json
    |   |   |   SLEAPAnalysis.h5
    |   |   |   FacialVideo.mp4
    |
    └─── ...Then theProjectobject can be initialized as follows:proj=Project(DAQFile="DAQOutput.csv",BehFile="ExperimentMetadata.json",SLEAPFile="SLEAPAnalysis.h5",VideoFile="FacialVideo.mp4",base="/base/path/to/project",iterators={"Day1-Exp1":"/Day1/Exp1","Day1-Exp2":"/Day1/Exp2","Day2-Exp1":"/Day2/Exp1","Day2-Exp2":"/Day2/Exp2",...}})API Documentationsleapyfaces.project.Projectproj=sleapyfaces.project.Project(DAQFile:str,BehFile:str,SLEAPFile:str,VideoFile:str,base:str,iterator:dict[str,str]|None,# Optionalget_glob:bool=False,# Optional)Projectis the main class for thesleapyfacespackage. It is used to initialize the project and iterate over the project structure.Args:DAQFile(string): The naming convention for the DAQ files (e.g. "*_events.csv" or "DAQOutput.csv")ExprMetaFile(string): The naming convention for the experimental structure files (e.g. "*_config.json" or "BehMetadata.json")SLEAPFile(string): The naming convention for the SLEAP files (e.g. "*_sleap.h5" or "SLEAP.h5")VideoFile(string): The naming convention for the video files (e.g. "*.mp4" or "video.avi")base(string): Base path of the project (e.g. "/specialk_cs/2p/raw/CSE009")iterator(dictionary[string, string], optional): Iterator for the project files, with keys as the label and values as the folder name (e.g. {"week 1": "20211105", "week 2": "20211112"})get_glob(boolean, default =False): Whether to use glob to find the files (e.g. True or False). Default is False.NOTE: if glob is True, make sure to at least include the file extension with an asterisk in the naming conventione.g.DAQFile="*.csv"orSLEAPFile="*.h5"Attributes:exprs(list[Experiment]): List of the experiment objectsfiles(list[FileConstructor]):FileConstructorobjectsleapyfaces.project.Project.buildColumnsproj.buildColumns(columns:list[str],values:list[str],)Builds the custom columns for the project and builds the data for each experimentArgs:columns(list[string]): the column titlesvalues(list[any]): the data for each columnInitializes attributes:custom_columns(list[CustomColumn]): list of custom columnsall_data(pd.DataFrame): the data for all experiments concatenated togethersleapyfaces.project.Project.buildTrialsproj.buildTrials(TrackedData:list[str],Reduced:list[bool],start_buffer:int=10000,# Optionalend_buffer:int=13000,# Optional)Parses the data from each experiment into its individual trialsArgs:TrackedData(list[string]): The title of the columns from the DAQ data to be trackedReduced(list[boolean]): The corresponding boolean for whether the DAQ data is to be reduced (True) or not (False)start_buffer(integer, optional): The time in milliseconds before the trial start to capture. Defaults to 10000.end_buffer(integer, optional): The time in milliseconds after the trial start to capture. Defaults to 13000.Initializes attributes:exprs[i].trials(pd.DataFrame): the data frame containing the concatenated trial data for each experimentexprs[i].trialData(list[pd.DataFrame]): the list of data frames containing the trial data for each trial for each experimentsleapyfaces.project.Project.meanCenterproj.meanCenter()Recursively mean centers the data for each trial for each experimentInitializes attributes:all_data(pd.DataFrame): the mean centered data for all trials and experiments concatenated togethersleapyfaces.project.Project.zScoreproj.zScore()Z scores the mean centered data for each experimentUpdates attributes:all_data(pd.DataFrame): the z-scored data for all experiments concatenated togethersleapyfaces.project.Project.analyzeproj.analyze()Runs the mean centering and z scoring functionssleapyfaces.project.Project.visualizeproj.visualize()Reducesall_datato 2 and 3 dimensions using PCAInitializes attributes:pcas(dictionary[string,pd.DataFrame]): a dictionary containing the 2 and 3 dimensional PCA data for each experimentthe dictionary keys are'pca2d','pca3d'sleapyfaces.experiment.Experimentexpr=sleapyfaces.experiment.Experiment(name:str,files:sleapyfaces.structs.FileConstructor,)Class constructor for the Experiment object.Args:name(string): The name of the experiment.files(FileConstructor): TheFileConstructorobject containing the paths to the experiment files.Attributes:name(string): The name of the experiment.files(FileConstructor): TheFileConstructorobject containing the paths to the experiment files.sleap(SLEAPanalysis): TheSLEAPanalysisobject containing the SLEAP data.beh(BehMetadata): TheBehMetadataobject containing the behavior metadata.video(VideoMetadata): TheVideoMetadataobject containing the video metadata.daq(DAQData): TheDAQDataobject containing the DAQ data.numeric_columns(list[string]): A list of the titles of the numeric columns in the SLEAP data.sleapyfaces.experiment.Experiment.buildDataexpr.buildData(CustomColumns:list[sleapyfaces.structs.CustomColumn])Builds the data for the experiment.Args:CustomColumns(list[CustomColumn]): A list of theCustomColumnobjects to be added to the experiment.Initializes attributes:sleap.tracks(pd.DataFrame): The SLEAP data.custom_columns(pd.DataFrame): The non-numeric columns.sleapyfaces.experiment.Experiment.appendexpr.append(item:pd.Series|pd.DataFrame)Appends a column to the SLEAP data.Args:item(pd.Seriesorpd.DataFrame): A pandas series or dataframe to be appended to the SLEAP data.Updates attributes:sleap.tracks(pd.DataFrame): The SLEAP data.custom_columns(pd.DataFrame): The non-numeric columns.sleapyfaces.experiment.Experiment.buildTrialsexpr.buildTrials(TrackedData:list[str],Reduced:list[bool],start_buffer:int=10000,# Optionalend_buffer:int=13000,# Optional)Converts the data into trial by trial format.Args:TrackedData(list[string]): the list of columns from the DAQ data that signify the START of each trial.Reduced(list[boolean]): a boolean list with the same length as the TrackedData list that signifies the columns from the tracked data with quick TTL pulses that occur during the trial.(e.g. the LED TTL pulse may signify the beginning of a trial, but during the trial the LED turns on and off, so the LED TTL column should be marked as True)start_buffer(integer, optional): The time in miliseconds you want to capture before the trial starts. Defaults to 10000 (i.e. 10 seconds).end_buffer(integer, optional): The time in miliseconds you want to capture after the trial starts. Defaults to 13000 (i.e. 13 seconds).Initializes attributes:trials(pd.DataFrame): the dataframe with the data in trial by 	trial format, with a metaindex of trial number and frame numbertrialData(list[pd.DataFrame]): a list of the dataframes with the individual trial data.sleapyfaces.io.DAQDatadaq=sleapyfaces.io.DAQData(path:str|PathLike[string])Cache for DAQ data.Args:path(string or PathLike[string]): Path to the directory containing the DAQ data.Attrs:cache(pd.DataFrame): Pandas DataFrame containing the DAQ data.columns(list[string]): List of column names in the cache.sleapyfaces.io.DAQData.appenddaq.append(name:str,value:list[any])Takes in a list with a name and appends it to the cache as a columnArgs:name(string): The column name.value(list[any]): The column data.Updates attributes:cache(pd.DataFrame): Pandas DataFrame containing the DAQ data.columns(list[string]): List of column names in the cache.sleapyfaces.io.DAQData.saveDatadaq.saveData(filename:str|PathLike[str]|FileIO,)saves the cached data to a csv fileArgs:filename(Text | PathLike[Text] | BufferedWriter): the path and name of the file to save the data tosleapyfaces.io.SLEAPanalysissleap=sleapyfaces.io.SLEAPanalysis(path:str|PathLike[string])a class for reading and storingSLEAPanalysis filesArgs:path(string or PathLike[string]): path to the directory containing the SLEAP analysis fileAttributes:data(dictionary): dictionary of all the data from theSLEAPanalysis filetrack_names(list): list of the track names from theSLEAPanalysis filetracks(pd.DataFrame): a pandas DataFrame containing the tracks from theSLEAPanalysis file (with missing frames filled in using a linear interpolation method)sleapyfaces.io.SLEAPanalysis.getDatasetssleap.getDatasets()gets the datasets from theSLEAPanalysis fileInitializes Attributes:data(dictionary): dictionary of all the data from theSLEAPanalysis filesleapyfaces.io.SLEAPanalysis.getTrackssleap.getTracks()gets the tracks from theSLEAPanalysis fileInitializes Attributes:tracks(pd.DataFrame): a pandas DataFrame containing the tracks from theSLEAPanalysis file (with missing frames filled in using a linear interpolation method)sleapyfaces.io.SLEAPanalysis.getTrackNamessleap.getTrackNames()gets the track names from theSLEAPanalysis fileInitializes Attributes:track_names(List): list of the track names from theSLEAPanalysis filesleapyfaces.io.SLEAPanalysis.appendsleap.append(item:pd.Series|pd.DataFrame)Appends a column to the tracks DataFrameArgs:item(pd.Seriesorpd.DataFrame): The column to append to the tracks DataFrameUpdates Attributes:tracks(pd.DataFrame): a pandas DataFrame containing the tracks from theSLEAPanalysis filesleapyfaces.io.SLEAPanalysis.saveDatasleap.saveData(filename:str|PathLike[str],path:str="SLEAP"# Optional)saves the modifiedSLEAPanalysis data to an HDF5 fileArgs:filename(string or PathLike[string]): the path and name of the file to save the data topath (string, optional): the internal HDF5 path to save the data to. Defaults to "SLEAP".sleapyfaces.io.BehMetadatabeh=sleapyfaces.io.BehMetadata(path:str|PathLike[string],MetaDataKey:str="beh_metadata",# OptionalTrialArrayKey:str="trialArray",# OptionalITIArrayKey:str="ITIArray",# Optional)Cache for JSON data.Args:path(string of PathLike[string]): Path to the file containing the JSON data.MetaDataKey(string, optional): Key for the metadata in the JSON data. Defaults to"beh_metadata"based onbruker_control.TrialArrayKey(string, optional): Key for the trial array in the JSON data. Defaults to"trialArray"based onbruker_control.ITIArrayKey(string, optional): Key for the inter-trial interval array in the JSON data. Defaults to"ITIArray"based onbruker_control.Bruker Control Repository:Link: (https://github.com/Tyelab/bruker_control)[https://github.com/Tyelab/bruker_control]Author: Jeremy DelahantyAttributes:cache(pd.DataFrame): Pandas DataFrame containing the JSON data.columns(list): List of column names in the cache.sleapyfaces.io.BehMetadata.saveDatabeh.saveData(filename:str|PathLike[str]|FileIO,)Saves the DAQ data to aCSVfile.Args:filename(string or PathLike[string] or FileIO): The name and path of the file to save the data to.sleapyfaces.io.VideoMetadatavideo=sleapyfaces.io.VideoMetadata(path:str|PathLike[string],)A class for caching the video metadata.Args:path(string of PathLike[string]): Path to the directory containing the video metadata.Attributes:cache(dictionary): Dictionary containing the video metadata from ffmpeg.fps(float): The precise frames per second of the video.sleapyfaces.io.VideoMetadata.saveDatavideo.saveData(filename:str|PathLike[str]|FileIO,)Saves the video metadata to a json file.Args:filename(string or PathLike[string] or FileIO): the name and path of the file to save the data to.sleapyfaces.normalize.mean_centersleapyfaces.normalize.mean_center(data:pd.DataFrame,track_names:list[str])->pd.DataFrameMean centers the data for each track.Args:data(pd.DataFrame): The data to mean center.track_names(list[str]): The names of the tracks to mean center.Returns:pd.DataFrame: The mean centered data.sleapyfaces.normalize.z_scoresleapyfaces.normalize.z_score(data:pd.DataFrame,track_names:list[str])->pd.DataFrameZ-score the data.Args:data(pd.DataFrame): The data to z-score.track_names(list[str]): The names of the tracks to z-score.Returns:pd.DataFrame: The z-scored data.sleapyfaces.normalize.pcasleapyfaces.normalize.pca(data:pd.DataFrame,track_names:list[str])->dict[str,pd.DataFrame]Runs 2D and 3D PCA dimensionality reduction on the data.Args:data(pd.DataFrame): The data to be reduced.track_names(list[str]): The names of the tracks to be reduced.Returns:dictionary[string,pd.DataFrame]: The reduced data with keys "pca2d" and "pca3d".
-i.e.{"pca2d": pd.DataFrame, "pca3d": pd.DataFrame}sleapyfaces.structs.Filefile=sleapyfaces.structs.File(basepath:str|PathLike[str],filename:str,get_glob:bool=False,# Optional)A structured file object that contains the base path and filename of a file.Args:basepath(string): the path to the file.filename(string): the name of the file, or a glob pattern ifget_globisTrue.get_glob(bool, optional): whether or not to get the glob pattern. Defaults toFalse.Attributes:file(string): the complete filepathiPath(i)(string): the path to theith file in the glob pattern.sleapyfaces.structs.FileConstructorfiles=sleapyfaces.structs.FileConstructor(daq:File,sleap:File,beh:File,video:File)Takes in the base paths and filenames of the experimental data and returns them as a structured object.Args/Attributes:daq(File): The location of the DAQ data file.sleap(File): The location of the SLEAP analysis file.beh(File): The location of the behavioral metadata file.video(File): The location of the video file.sleapyfaces.structs.CustomColumncolumn=sleapyfaces.structs.CustomColumn(ColumnTitle:str,ColumnData:str|int|float|bool)Takes in the base paths and filenames of the experimental data and returns them as a structured object.Args:ColumnTitle(string): The title of the column.ColumnData(string or integer or float or boolean): The data to be added to the column.sleapyfaces.structs.CustomColumn.buildColumncolumn.buildColumn(length:int,)Initializes a column of a given length.Args:length(integer): The length of the column to be built.Initializes Attributes:Column(pd.DataFrame): The initialized column at a given length.Changelog:Version 1.0.0 (2022-12-27)iterate (repeatedly) over each mouse and each week (each mouse and each experiment)get project files (experimental) structureinitialize an iterator over the project structureget daq data from CSV fileread CSV filessave each column from CSV fileNote: CSV columns are of differing lengthsget “beh_metadata” from json metadataread JSON filegrab the values for key “beh_metadata”get the values of sub key “trialArray”get the values of sub-key “ITIArray”get video metadata from *.mp4 file (with ffmpeg.probe)read in the *.mp4 metadataselect the correct video streamget the average frames per secondget SLEAP data from *.h5 fileopen h5 fileget transposed values of key “tracks” (tracking_locations)fill missing locations (linear regress. fit)get transposed values of key “edge_inds”get values of key “edge_names”get transposed values of “instance_scores”get transposed values of “point_scores”get values of “track_occupancy”get transposed values of “tracking_scores”get decoded values of “node_names” (make sure there's no encoding issues)deconstruct SLEAP points into x and y points (across all frames)iterate over each nodebreakup the 4D array “tracks” into 1D array for x and y values respectivelyNote: [frame, node, x/y, color] for greyscale the color dimension is 1D (i.e. essentially the 4D array is 3D because the color dimension is constant)iterate over each frameassign mouse, week, frame #, and timestamp (using average frames per second)Split data into individual trials by trial type using the Speaker and LED data from the CSV daq datainitialize trial iterators for the consistently documented points from the daq CSViterate over each trial in “trialArray”get the index of 10sec before and 13sec after trial startfor each feature, grab the start and end indicesstore data from each trial in a pd.dataframeconcatenate all pd.dataframes together for each videoconcatenate the pd.dataframes from each video together for each mouse (base expr split)Prepare the data(opt.) mean center across all points for a single trialmean center across all trials for a single experimentmean center across all experiments for a single mousemean center across all mice(opt.) z-score mean-centered dataAnalyze the dataPerform 2D and 3D PCAs on all data (raw, centered, by trial, by week, by mouse, etc…)apply gaussian kernel to PCA outputsSave the datawrite everything to HDF5 file(s)Version 1.0.1add exhaustive documentationadd inline documentationstrengthen type hintsFix bug where theCustomColumnclass is not properly initializedFix bug where theCustomColumnclass is not properly builtFix bug where theCustomColumnclass is not properly appendedFix bug where thetrialsandtrialDataattributes were not properly initializedFix bug where thetrialsandtrialDataattributes were not properly builtFix bug where themeanCenterdid not properly mean center the data recursivelyVersion 1.1.0 (in progress)add support for multiple miceadd clustering/prediction algorithm(s)add velocity, acceleration, and jerk calculationsadd save option for all dataadd plotting functionsclustering featuresdistance to a pointvector to a point (theta, magnitude) or (angle, distance)velocity/accelerationdistance to centroiddistance between given points