swc.aeon.io.reader#

Module for reading data from raw files in an Aeon dataset.

class swc.aeon.io.reader.BitmaskEvent(pattern, value, tag)[source]#

Bases: Harp

Extracts event data matching a specific digital I/O bitmask.

Columns:

event (str): Unique identifier for the event code.

columns: SequenceNotStr[str]#: Column labels to use for the data.

extension: str#: Extension of data file pathnames.

pattern: str#: Pattern used to find raw files, usually in the format <Device>_<DataStream>.

read(path)[source]#

Reads a specific event code from digital data.

Each data value is matched against the unique event identifier.

Parameters:: path (Path) – Path to the Harp binary file.
Return type:: DataFrame
Returns:: A DataFrame representing the event data extracted from the Harp binary file.

tag: str#: A tag/label to assign to the event code for identification.

value: int#: The unique event code to match against the digital I/O data.

class swc.aeon.io.reader.Chunk(reader=None, pattern=None, extension=None)[source]#

Bases: Reader

Extracts path and epoch information from chunk files in the dataset.

columns: SequenceNotStr[str]#: Column labels to use for the data.

extension: str#: Extension of data file pathnames.

pattern: str#: Pattern used to find raw files, usually in the format <Device>_<DataStream>.

read(path)[source]#

Returns path and epoch information for the chunk associated with the specified file.

Parameters:: path (Path) – Path to the data file.
Return type:: DataFrame
Returns:: A DataFrame representing the path and epoch information for the specified file.

class swc.aeon.io.reader.Csv(pattern, columns, dtype=None, extension='csv')[source]#

Bases: Reader

Extracts data from comma-separated (CSV) text files.

The first column stores the Aeon timestamp, in seconds.

columns: SequenceNotStr[str]#: Column labels to use for the data.

extension: str#: Extension of data file pathnames.

pattern: str#: Pattern used to find raw files, usually in the format <Device>_<DataStream>.

read(path)[source]#

Reads data from the specified CSV text file.

If the file is non-empty, the first column is assumed to contain the Aeon timestamp and is set as the index of the DataFrame. If the file is empty, pandas defaults to using pandas.RangeIndex as the index.

Parameters:: path (Path) – Path to the CSV text file.
Return type:: DataFrame
Returns:: A DataFrame representing the data extracted from the CSV text file.

class swc.aeon.io.reader.DigitalBitmask(pattern, mask, columns)[source]#

Bases: Harp

Extracts event data matching a specific digital I/O bitmask.

Columns:

event (str): Unique identifier for the event code.

columns: SequenceNotStr[str]#: Column labels to use for the data.

extension: str#: Extension of data file pathnames.

mask: int#: The bitmask to match against changes in the digital I/O data.

pattern: str#: Pattern used to find raw files, usually in the format <Device>_<DataStream>.

read(path)[source]#

Reads a specific event code from digital data.

Each data value is checked against the specified bitmask.

Parameters:: path (Path) – Path to the Harp binary file.
Return type:: DataFrame
Returns:: A DataFrame representing the bitmask data extracted from the Harp binary file.

class swc.aeon.io.reader.Encoder(pattern)[source]#

Bases: Harp

Extract magnetic encoder data.

Columns:

angle (float): Absolute angular position, in radians, of the magnetic encoder.
intensity (float): Intensity of the magnetic field.

columns: SequenceNotStr[str]#: Column labels to use for the data.

extension: str#: Extension of data file pathnames.

pattern: str#: Pattern used to find raw files, usually in the format <Device>_<DataStream>.

read(path)#

Reads data from the specified Harp binary file.

Parameters:: path (Path) – Path to the Harp binary file.
Return type:: DataFrame
Returns:: A DataFrame representing the data extracted from the Harp binary file.

class swc.aeon.io.reader.Harp(pattern, columns, extension='bin')[source]#

Bases: Reader

Extracts data from raw binary files encoded using the Harp protocol.

columns: SequenceNotStr[str]#: Column labels to use for the data.

extension: str#: Extension of data file pathnames.

pattern: str#: Pattern used to find raw files, usually in the format <Device>_<DataStream>.

read(path)[source]#

Reads data from the specified Harp binary file.

Parameters:: path (Path) – Path to the Harp binary file.
Return type:: DataFrame
Returns:: A DataFrame representing the data extracted from the Harp binary file.

class swc.aeon.io.reader.Heartbeat(pattern)[source]#

Bases: Harp

Extract periodic heartbeat event data.

Columns:

second (int): The whole second corresponding to the heartbeat, in seconds.

columns: SequenceNotStr[str]#: Column labels to use for the data.

extension: str#: Extension of data file pathnames.

pattern: str#: Pattern used to find raw files, usually in the format <Device>_<DataStream>.

read(path)#

Reads data from the specified Harp binary file.

Parameters:: path (Path) – Path to the Harp binary file.
Return type:: DataFrame
Returns:: A DataFrame representing the data extracted from the Harp binary file.

class swc.aeon.io.reader.JsonList(pattern, columns=(), root_key='value', extension='jsonl')[source]#

Bases: Reader

Extracts data from .jsonl files, where the key “seconds” stores the Aeon timestamp.

columns: SequenceNotStr[str]#: Column labels to extract from the dictionary stored in the root_key of the JSON object. Each column name must correspond to a key in the dictionary stored in the root_key. Defaults to an empty tuple, i.e. the JSON objects are read as-is.

extension: str#: Extension of data file pathnames.

pattern: str#: Pattern used to find raw files, usually in the format <Device>_<DataStream>.

read(path)[source]#

Reads data from the specified jsonl file.

Parameters:: path (Path) – Path to the jsonl file to read. The file must contain a “seconds” key that stores the Aeon timestamp, and the root_key must contain a dictionary with keys corresponding to the specified columns.
Return type:: DataFrame
Returns:: A DataFrame with “seconds” as the index, other keys as columns, and the specified columns extracted from the root_key dictionary (if any).

root_key: str#: The key in the JSON object that contains the data. Defaults to “value”.

class swc.aeon.io.reader.Log(pattern)[source]#

Bases: Csv

Extracts message log data.

Columns:

priority (str): Priority level of the message.
type (str): Type of the log message.
message (str): Log message data. Can be structured using tab separated values.

columns: SequenceNotStr[str]#: Column labels to use for the data.

extension: str#: Extension of data file pathnames.

pattern: str#: Pattern used to find raw files, usually in the format <Device>_<DataStream>.

read(path)#

Reads data from the specified CSV text file.

If the file is non-empty, the first column is assumed to contain the Aeon timestamp and is set as the index of the DataFrame. If the file is empty, pandas defaults to using pandas.RangeIndex as the index.

Parameters:: path (Path) – Path to the CSV text file.
Return type:: DataFrame
Returns:: A DataFrame representing the data extracted from the CSV text file.

class swc.aeon.io.reader.Metadata(pattern='Metadata')[source]#

Bases: Reader

Extracts metadata information from all epochs in the dataset.

columns: SequenceNotStr[str]#: Column labels to use for the data.

extension: str#: Extension of data file pathnames.

pattern: str#: Pattern used to find raw files, usually in the format <Device>_<DataStream>.

read(path)[source]#

Returns epoch metadata stored in the specified file.

Parameters:: path (Path) – Path to the data file.
Return type:: DataFrame
Returns:: A DataFrame representing the epoch metadata stored in the specified file.

class swc.aeon.io.reader.Pose(pattern, model_root=None)[source]#

Bases: Harp

Reader for Harp-binarized tracking data given a model that outputs id, parts, and likelihoods.

Columns:

class (int): Int ID of a subject in the environment.
class_likelihood (float): Likelihood of the subject’s identity.
part (str): Bodypart on the subject.
part_likelihood (float): Likelihood of the specified bodypart.
x (float): X-coordinate of the bodypart.
y (float): Y-coordinate of the bodypart.

static class_int2str(data, classes)[source]#

Converts a class integer in a tracking data dataframe to its associated string (subject id).

Parameters:

data (DataFrame) – DataFrame containing a column named “identity” with integer class identifiers.
classes (list[str]) – List of class names corresponding to the integer identifiers in the “identity” column.

Return type:

DataFrame

Returns:

DataFrame with the “identity” column converted to string class names.

columns: SequenceNotStr[str]#: Column labels to use for the data.

extension: str#: Extension of data file pathnames.

static get_bodyparts(config_file_path)[source]#

Returns a list of bodyparts from a model’s config file.

Return type:: list[str]

static get_class_names(config_file_path)[source]#

Returns a list of classes from a model’s config file.

Return type:: list[str]

classmethod get_config_file(config_file_dir, config_file_names=None)[source]#

Returns the config file from a model’s config directory.

Return type:: Path

pattern: str#: Pattern used to find raw files, usually in the format <Device>_<DataStream>.

read(path, include_model=False)[source]#

Reads data from the Harp-binarized tracking file.

Parameters:

path (Path) – Path to the Harp binary file.
include_model (bool) – Specifies whether to include the path to the pose tracking model.

Return type:

DataFrame

Returns:

A DataFrame representing the data extracted from the Harp binary file.

class swc.aeon.io.reader.Position(pattern)[source]#

Bases: Harp

Extract 2D position tracking data for a specific camera.

Columns:

x (float): x-coordinate of the object center of mass.
y (float): y-coordinate of the object center of mass.
angle (float): angle, in radians, of the ellipse fit to the object.
major (float): length, in pixels, of the major axis of the ellipse fit to the object.
minor (float): length, in pixels, of the minor axis of the ellipse fit to the object.
area (float): number of pixels in the object mass.
id (float): unique tracking ID of the object in a frame.

columns: SequenceNotStr[str]#: Column labels to use for the data.

extension: str#: Extension of data file pathnames.

pattern: str#: Pattern used to find raw files, usually in the format <Device>_<DataStream>.

read(path)#

Reads data from the specified Harp binary file.

Parameters:: path (Path) – Path to the Harp binary file.
Return type:: DataFrame
Returns:: A DataFrame representing the data extracted from the Harp binary file.

class swc.aeon.io.reader.Subject(pattern)[source]#

Bases: Csv

Extracts metadata for subjects entering and exiting the environment.

Columns:

id (str): Unique identifier of a subject in the environment.
weight (float): Weight measurement of the subject on entering or exiting the environment.
event (str): Event type. Can be one of Enter, Exit or Remain.

columns: SequenceNotStr[str]#: Column labels to use for the data.

extension: str#: Extension of data file pathnames.

pattern: str#: Pattern used to find raw files, usually in the format <Device>_<DataStream>.

read(path)#

Reads data from the specified CSV text file.

If the file is non-empty, the first column is assumed to contain the Aeon timestamp and is set as the index of the DataFrame. If the file is empty, pandas defaults to using pandas.RangeIndex as the index.

Parameters:: path (Path) – Path to the CSV text file.
Return type:: DataFrame
Returns:: A DataFrame representing the data extracted from the CSV text file.

class swc.aeon.io.reader.Video(pattern)[source]#

Bases: Csv

Extracts video frame metadata.

Columns:

hw_counter (int): Hardware frame counter value for the current frame.
hw_timestamp (int): Internal camera timestamp for the current frame.
_frame (int): Frame index in the video file.
_path (str): Path to the video file.
_epoch (str): Epoch name associated with the video file.

columns: SequenceNotStr[str]#: Column labels to use for the data.

extension: str#: Extension of data file pathnames.

pattern: str#: Pattern used to find raw files, usually in the format <Device>_<DataStream>.

read(path)[source]#

Reads video metadata from the specified file.

Parameters:: path (Path) – Path to the video metadata CSV file.
Return type:: DataFrame
Returns:: A DataFrame containing the video metadata.