API Reference

Table of Contents

sleapyfaces.project.Project

proj = sleapyfaces.project.Project(
    DAQFile: str,
    BehFile: str,
    SLEAPFile: str,
    VideoFile: str,
    base: str,
    iterator: dict[str, str] | None, # Optional
    get_glob: bool = False, # Optional
    )
  • Project is the main class for the sleapyfaces package. 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 convention
    • e.g. DAQFile="*.csv" or SLEAPFile="*.h5"
  • Attributes:
    • exprs (list[Experiment]): List of the experiment objects
    • files (list[FileConstructor]): FileConstructor object

sleapyfaces.project.Project.buildColumns

proj.buildColumns(
    columns: list[str],
    values: list[str],
    )
  • Builds the custom columns for the project and builds the data for each experiment
  • Args:
    • columns (list[string]): the column titles
    • values (list[any]): the data for each column
  • Initializes attributes:
    • custom_columns (list[CustomColumn]): list of custom columns
    • all_data (pd.DataFrame): the data for all experiments concatenated together

sleapyfaces.project.Project.buildTrials

proj.buildTrials(
    TrackedData: list[str],
    Reduced: list[bool],
    start_buffer: int = 10000, # Optional
    end_buffer: int = 13000, # Optional
    )
  • Parses the data from each experiment into its individual trials
  • Args:
    • TrackedData (list[string]): The title of the columns from the DAQ data to be tracked
    • Reduced (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 experiment
    • exprs[i].trialData (list[pd.DataFrame]): the list of data frames containing the trial data for each trial for each experiment

sleapyfaces.project.Project.meanCenter

proj.meanCenter()
  • Recursively mean centers the data for each trial for each experiment
  • Initializes attributes:
    • all_data (pd.DataFrame): the mean centered data for all trials and experiments concatenated together

sleapyfaces.project.Project.zScore

proj.zScore()
  • Z scores the mean centered data for each experiment
  • Updates attributes:
    • all_data (pd.DataFrame): the z-scored data for all experiments concatenated together

sleapyfaces.project.Project.analyze

proj.analyze()
  • Runs the mean centering and z scoring functions

sleapyfaces.project.Project.visualize

proj.visualize()
  • Reduces all_data to 2 and 3 dimensions using PCA
  • Initializes attributes:
    • pcas (dictionary[string, pd.DataFrame]): a dictionary containing the 2 and 3 dimensional PCA data for each experiment
    • the dictionary keys are 'pca2d', 'pca3d'

sleapyfaces.experiment.Experiment

expr = 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): The FileConstructor object containing the paths to the experiment files.
  • Attributes:
    • name (string): The name of the experiment.
    • files (FileConstructor): The FileConstructor object containing the paths to the experiment files.
    • sleap (SLEAPanalysis): The SLEAPanalysis object containing the SLEAP data.
    • beh (BehMetadata): The BehMetadata object containing the behavior metadata.
    • video (VideoMetadata): The VideoMetadata object containing the video metadata.
    • daq (DAQData): The DAQData object containing the DAQ data.
    • numeric_columns (list[string]): A list of the titles of the numeric columns in the SLEAP data.

sleapyfaces.experiment.Experiment.buildData

expr.buildData(
    CustomColumns: list[sleapyfaces.structs.CustomColumn]
    )
  • Builds the data for the experiment.
  • Args:
    • CustomColumns (list[CustomColumn]): A list of the CustomColumn objects 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.append

expr.append(
    item: pd.Series | pd.DataFrame
    )
  • Appends a column to the SLEAP data.
  • Args:
    • item (pd.Series or pd.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.buildTrials

expr.buildTrials(
    TrackedData: list[str],
    Reduced: list[bool],
    start_buffer: int = 10000, # Optional
    end_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 number
    • trialData (list[pd.DataFrame]): a list of the dataframes with the individual trial data.

sleapyfaces.io.DAQData

daq = 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.append

daq.append(
    name: str,
    value: list[any]
    )
  • Takes in a list with a name and appends it to the cache as a column
  • Args:
    • 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.saveData

daq.saveData(
    filename: str | PathLike[str] | FileIO,
    )
  • saves the cached data to a csv file
  • Args:
    • filename (Text | PathLike[Text] | BufferedWriter): the path and name of the file to save the data to

sleapyfaces.io.SLEAPanalysis

sleap = sleapyfaces.io.SLEAPanalysis(
    path: str | PathLike[string]
    )
  • a class for reading and storing SLEAP analysis files
  • Args:
    • path (string or PathLike[string]): path to the directory containing the SLEAP analysis file
  • Attributes:
    • data (dictionary): dictionary of all the data from the SLEAP analysis file
    • track_names (list): list of the track names from the SLEAP analysis file
    • tracks (pd.DataFrame): a pandas DataFrame containing the tracks from the SLEAP analysis file (with missing frames filled in using a linear interpolation method)

sleapyfaces.io.SLEAPanalysis.getDatasets

sleap.getDatasets()
  • gets the datasets from the SLEAP analysis file
  • Initializes Attributes:
    • data (dictionary): dictionary of all the data from the SLEAP analysis file

sleapyfaces.io.SLEAPanalysis.getTracks

sleap.getTracks()
  • gets the tracks from the SLEAP analysis file
  • Initializes Attributes:
    • tracks (pd.DataFrame): a pandas DataFrame containing the tracks from the SLEAP analysis file (with missing frames filled in using a linear interpolation method)

sleapyfaces.io.SLEAPanalysis.getTrackNames

sleap.getTrackNames()
  • gets the track names from the SLEAP analysis file
  • Initializes Attributes:
    • track_names (List): list of the track names from the SLEAP analysis file

sleapyfaces.io.SLEAPanalysis.append

sleap.append(
    item: pd.Series | pd.DataFrame
)
  • Appends a column to the tracks DataFrame
  • Args:
    • item (pd.Series or pd.DataFrame): The column to append to the tracks DataFrame
  • Updates Attributes:
    • tracks (pd.DataFrame): a pandas DataFrame containing the tracks from the SLEAP analysis file

sleapyfaces.io.SLEAPanalysis.saveData

sleap.saveData(
    filename: str | PathLike[str],
    path: str="SLEAP" # Optional
)
  • saves the modified SLEAP analysis data to an HDF5 file
  • Args:
    • filename (string or PathLike[string]): the path and name of the file to save the data to
    • path (string, optional): the internal HDF5 path to save the data to. Defaults to "SLEAP".

sleapyfaces.io.BehMetadata

beh = sleapyfaces.io.BehMetadata(
    path: str | PathLike[string],
    MetaDataKey: str="beh_metadata", # Optional
    TrialArrayKey: str="trialArray", # Optional
    ITIArrayKey: 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 on bruker_control.
    • TrialArrayKey (string, optional): Key for the trial array in the JSON data. Defaults to "trialArray" based on bruker_control.
    • ITIArrayKey (string, optional): Key for the inter-trial interval array in the JSON data. Defaults to "ITIArray" based on bruker_control.
    • Bruker Control Repository:
      • Link: (https://github.com/Tyelab/bruker_control)[https://github.com/Tyelab/bruker_control]
      • Author: Jeremy Delahanty
  • Attributes:
    • cache (pd.DataFrame): Pandas DataFrame containing the JSON data.
    • columns (list): List of column names in the cache.

sleapyfaces.io.BehMetadata.saveData

beh.saveData(
    filename: str | PathLike[str] | FileIO,
    )
  • Saves the DAQ data to a CSV file.
  • Args:
    • filename (string or PathLike[string] or FileIO): The name and path of the file to save the data to.

sleapyfaces.io.VideoMetadata

video = 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.saveData

video.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_center

sleapyfaces.normalize.mean_center(
    data: pd.DataFrame,
    track_names: list[str]
    ) -> pd.DataFrame
  • Mean 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_score

sleapyfaces.normalize.z_score(
    data: pd.DataFrame,
    track_names: list[str]
    ) -> pd.DataFrame
  • Z-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.pca

sleapyfaces.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.File

file = 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 if get_glob is True.
    • get_glob (bool, optional): whether or not to get the glob pattern. Defaults to False.
  • Attributes:
    • file (string): the complete filepath
    • iPath(i) (string): the path to the ith file in the glob pattern.

sleapyfaces.structs.FileConstructor

files = 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.CustomColumn

column = 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.buildColumn

column.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.