Getting Started
Table of Contents
Installation
Using pip:
pip install sleapyfaces
Using conda (coming soon):
conda install -c conda-forge sleapyfaces
Basic Usage Step by Step
Importing the package
For basic usage, the package can be imported with the following:
from sleapyfaces.project import Project
Alternatively, the package can be imported with the following:
import sleapyfaces as sf
Creating a project
The 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 optional get_glob
argument set to True
, which will automatically find the files associated with each experiment. Alternatively, the get_glob
argument can be set to False
(default), which will allow the user to manually set the files associated with each experiment as the file arguments. Additionally, there is an iterators
argument, which is a dictionary of iterators that can be used to iterate over the project structure. The iterators
argument 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",
...
}
}
)
The
iterators
paths are relative to thebase
path. 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 data
The project object has a buildColumns
method, which is used to build the columns of the data. The buildColumns
method takes two arguments: columns
and values
. The columns
argument is a list of column titles, and the values
argument is a list of values for each column. The buildColumns
method will build the columns of the data, and will also build the iterators for each column. The buildColumns
method 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 trials
The project object has a buildTrials
method, which is used to build the trials of the data. The buildTrials
method takes four arguments: TrackedData
, Reduced
, start_buffer
, and end_buffer
. The TrackedData
argument is a list of the tracked data columns from the DAQ file that will be used to build the based on the DAQ timestamps. The Reduced
argument 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 the trialData
from intitializing a new trial for each timestamp in the "LED590_on"
column, reduced is set to true. The start_buffer
argument is the number of milliseconds before the trial start time that should be included in the trial. The end_buffer
argument is the number of milliseconds after the trial start time that should be included in the trial. The buildTrials
method will build the trials of the data, and will also build the iterators for each trial. The buildTrials
method 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 data
So far there are two normalization methods available:
- Mean Centering
The meanCenter
method will iterate recursively to the smallest data frame in the project, and then mean-center its way up the project tree. More precisely, the meanCenter
method first mean centers each trial from each experiment. Then, it will meanCenter
each experiment in the project. Finally, it will meanCenter
across all the experiments in the project. This method will mean-center the data in place, and will not return anything. However, it does expose a all_data
attribute, which is a pd.DataFrame
of all the data in the project.
project.meanCenter()
- Z-Scoring
The zScore
method assumes the data has already been mean-centered, and will further z-score the data across all the experiments in the project.
The zScore
method 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 Example
This implementation of the data objects is roughly 10x faster than the scripted version of the data analysis. The full example is shown below:
from sleapyfaces.project import Project
project = 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"]