opynfield.readin package

Submodules

opynfield.readin.anymaze_tracker module

opynfield.readin.anymaze_tracker.convert_time_stamp(time_stamp, verbose)

This function converts the time column from the form 00:00:00.00 (or similar) to the form 0.00 Note: there seems to be some inconsistency with how the time stamp column is saved in the Anymaze format, please submit an error report if you encounter a new format that is not addressed in this function.

Parameters
Returns

the re-formatted time column

Return type

np.ndarray

opynfield.readin.anymaze_tracker.read_anymaze_center(groups_with_file_type: list[str], verbose: bool, arena_radius_cm: float, running_window_length: int, window_step_size: int, sample_freq: int, time_bin_size: int, trim, all_tracks: list[opynfield.readin.track.Track]) → list[opynfield.readin.track.Track]

This function reads in all the tracks from the Anymaze tracker format that recorded the center position of the animal subject (rather than the head position). The function extracts the x, y, and t information and smooths, centers, and converts the units of the track.

Parameters
Returns

a list of Track objects with a consistent format for x y and t tracking points

Return type

list[Track]

opynfield.readin.anymaze_tracker.read_anymaze_head(groups_with_file_type: list[str], verbose: bool, arena_radius_cm: float, running_window_length: int, window_step_size: int, sample_freq: int, time_bin_size: int, trim, all_tracks: list[opynfield.readin.track.Track]) → list[opynfield.readin.track.Track]

This function reads in all the tracks from the Anymaze tracker format that recorded the head position of the animal subject (rather than the body center point). The function extracts the x, y, and t information and smooths, centers, and converts the units of the track.

Parameters
Returns

a Track object with a consistent format for x y and t tracking points

Return type

list[Track]

opynfield.readin.buridian_tracker module

opynfield.readin.buridian_tracker.get_meta_info(file: str, arena_radius_cm: float) → pandas.core.series.Series

This function extracts center point information from the arena in which the animal was recorded

Parameters

  • file (str) – the path to the metadata file for this track

  • arena_radius_cm (float) – the radius of the arena in which the track was recorded, sourced from opynfield.config.user_input.UserInput object

Returns

the x and y coordinates of the center point in cm and the radius of the arena in pixels

Return type

pd.Series

opynfield.readin.buridian_tracker.read_buridian(groups_with_file_type: list[str], verbose: bool, arena_radius_cm: float, running_window_length: int, window_step_size: int, sample_freq: int, time_bin_size: int, all_tracks: list[opynfield.readin.track.Track]) → list[opynfield.readin.track.Track]

This function reads in all the tracks from the Buridian tracker format. The function extracts the x, y, and t information and smooths, centers, and converts the units of the track.

Parameters
Returns

a Track object with a consistent format for x y and t tracking points

Return type

list[Track]

opynfield.readin.etho_tracker module

opynfield.readin.etho_tracker.combine_arena_coords(tracks_by_arena: dict[str, list[opynfield.readin.track.Track]]) → dict[str, tuple[numpy.ndarray, numpy.ndarray]]

This function combines the coordinates of all the tracks that were recorded in the same arena so that the arena center point can be estimated

Parameters

tracks_by_arena (dict[str, list[Track]]) – the dict of tracks recorded in each arena

Returns

the combined x and y coordinates, indexed by arena

Return type

dict[str, tuple[np.ndarray, np.ndarray]]

opynfield.readin.etho_tracker.extract_arena_center_point(combined_coords_by_arena: dict[str, tuple[numpy.ndarray, numpy.ndarray]], verbose: bool) → dict[str, tuple[float, float]]

This function estimates the center point of the arena that tracks were recorded in

Parameters

  • combined_coords_by_arena (dict[str, tuple[np.ndarray, np.ndarray]]) – the combined x and y coordinates, indexed by arena

  • verbose (bool) – display progress update, sourced from opynfield.config.user_input.UserInput object

Returns

the center points of the arenas, indexed by arena name

Return type

dict[str, tuple[float, float]]

opynfield.readin.etho_tracker.read_etho_ml(groups_with_file_type: list[str], verbose: bool, sample_freq: int, time_bin_size: int, all_tracks: list[opynfield.readin.track.Track]) → list[opynfield.readin.track.Track]

This function reads in all the tracks from the Ethovision TextML Version tracker format. The function extracts the x, y, and t information and smooths, centers, and converts the units of the track.

Parameters
Returns

a Track object with a consistent format for x y and t tracking points

Return type

list[Track]

opynfield.readin.etho_tracker.read_etho_txt(groups_with_file_type: list[str], verbose: bool, sample_freq: int, time_bin_size: int, all_tracks: list[opynfield.readin.track.Track]) → list[opynfield.readin.track.Track]

This function reads in all the tracks from the Ethovision Text Version tracker format. The function extracts the x, y, and t information and smooths, centers, and converts the units of the track.

Parameters
Returns

a Track object with a consistent format for x y and t tracking points

Return type

list[Track]

opynfield.readin.etho_tracker.read_etho_v1(groups_with_file_type: list[str], verbose: bool, sample_freq: int, time_bin_size: int, all_tracks: list[opynfield.readin.track.Track]) → list[opynfield.readin.track.Track]

This function reads in all the tracks from the Ethovision Version 1 tracker format. The function extracts the x, y, and t information and smooths, centers, and converts the units of the track.

Parameters
Returns

a Track object with a consistent format for x y and t tracking points

Return type

list[Track]

opynfield.readin.etho_tracker.read_etho_v2(groups_with_file_type: list[str], verbose: bool, sample_freq: int, time_bin_size: int, all_tracks: list[opynfield.readin.track.Track]) → list[opynfield.readin.track.Track]

This function reads in all the tracks from the Ethovision Version 2 tracker format. The function extracts the x, y, and t information and smooths, centers, and converts the units of the track.

Parameters
Returns

a Track object with a consistent format for x y and t tracking points

Return type

list[Track]

opynfield.readin.etho_tracker.sort_tracks_by_arena(list_of_etho_tracks: list[opynfield.readin.track.Track]) → dict[str, list[opynfield.readin.track.Track]]

This function creates a dictionary of Track objects indexed by which ethovision arena they were recorded in

Parameters

list_of_etho_tracks (list[Track]) – the Tracks to sort by arena

Returns

the dictionary of tracks by arena

Return type

dict[str, list[Track]]

opynfield.readin.multi_tracker module

opynfield.readin.multi_tracker.calc_center(combined_x: numpy.ndarray, combined_y: numpy.ndarray, verbose: bool, trim: int = 0) → tuple[float, float]

This function estimates the center point of an arena from tracking coordinates

Parameters

  • combined_x – the x coordinates to estimate from

  • combined_y – the y coordinates the estimate from

  • verbose – display progress update, sourced from opynfield.config.user_input.UserInput object

  • trim (int, defaults to 0) – how many points are recorded before the animal enters the arena (maximum of all animals in this track type)

Returns

the center point of the arena

Return type

tuple[float, float]

opynfield.readin.multi_tracker.fill_missing_data(coord: numpy.ndarray, time: numpy.ndarray) → numpy.ndarray

This function identified missing data points and interpolated the animals position at that point

Parameters

  • coord (np.ndarray) – the coordinates

  • time (np.ndarray) – the time coordinate

Returns

the interpolated coordinates

Return type

np.ndarray

opynfield.readin.multi_tracker.running_line(y_array: numpy.ndarray, n: int, dn: int) → numpy.ndarray

This function smooths the tracking data in the same way that ethovision automatically smooths tracking data in order to minimize the impact of body wobble

Parameters

  • y_array (np.ndarray) – the input coordinates

  • n (int) – the running window length

  • dn (int) – the window step size

Returns

the smoothed coordinates

Return type

np.ndarray

opynfield.readin.multi_tracker.subsample(coord, sample_freq: int, sample_interval: int) → numpy.ndarray

This function sub-samples the recorded coordinates to the desired data density

Parameters

  • coord (np.ndarray) – the full-density coordinates

  • sample_freq (int) – the sampling frequency with which the data was recorded

  • sample_interval (int) – the desired density

Returns

the sub-sampled coordinates

Return type

np.ndarray

opynfield.readin.read_in module

opynfield.readin.read_in.read_track_types(file_type: str, groups_with_file_type: list[str], verbose: bool, arena_radius_cm: float, running_window_length: int, window_step_size: int, sample_freq: int, time_bin_size: int, trim, all_tracks: list[opynfield.readin.track.Track]) → list[opynfield.readin.track.Track]

This function coordinates reading in all the data from each track type

Parameters
Returns

a list of Track objects with a consistent format for x y and t tracking points

Return type

list[Track]

opynfield.readin.run_all module

opynfield.readin.run_all.groups_to_types(groups_and_types: dict[str, list[str]]) → list[str]

This function makes a list of which file types are used in the run

Parameters

groups_and_types (dict[str, list[str]]) – the input information of which groups were recorded with which filetypes

Returns

the filetypes included in the run

Return type

list[str]

opynfield.readin.run_all.run_all_track_types(groups_and_types: dict[str, list[str]], verbose: bool, arena_radius_cm: float, running_window_length: int, window_step_size: int, sample_freq: int, time_bin_size: int, trim: int) → list[opynfield.readin.track.Track]

This function coordinates the entire read-in process

Parameters
Returns

all the Tracks that were read in

Return type

list[opynfield.readin.track.Track]

opynfield.readin.run_all.types_to_groups(file_types_included: list[str], groups_and_types: dict[str, list[str]]) → dict[str, list[str]]

This function creates a list for each filetype of which groups were recorded in that filetype

Parameters

  • file_types_included (list[str]) – which filetypes were included in the run

  • groups_and_types (dict[str, list[str]]) – the input information of which groups were recorded with which filetypes

Returns

which groups were recorded in which filetypes

Return type

dict[str, list[str]]

opynfield.readin.summary_file module

opynfield.readin.summary_file.summarize(tracks_by_group: collections.defaultdict[str, list[opynfield.calculate_measures.standard_track.StandardTrack]], test_cov_asymptote: opynfield.config.cov_asymptote.CoverageAsymptote, user_defaults: opynfield.config.defaults_settings.Defaults, model_settings: dict[str, dict[str, opynfield.config.model_settings.ModelSpecification]], plot_settings: opynfield.config.plot_settings.PlotSettings, user_config: opynfield.config.user_input.UserInput)

This function summarizes information about the kinds of tracks read in after the read-in process is complete. It generates a text file of information about the tracks and parameters used on them

Parameters

  • tracks_by_group (defaultdict[str, list[StandardTrack]]) – the tracks to summarize

  • test_cov_asymptote (CoverageAsymptote) – the coverage asymptote information that was used

  • user_defaults (Defaults) – the default settings that were used

  • model_settings (dict[str, dict[str, ModelSpecification]]) – the model settings that were used

  • plot_settings (PlotSettings) – the plot settings that were used

  • user_config (UserInput) – the user inputs that were used

opynfield.readin.summary_file.summary_file(tracks_by_group: collections.defaultdict[str, list[opynfield.calculate_measures.standard_track.StandardTrack]], test_cov_asymptote: opynfield.config.cov_asymptote.CoverageAsymptote, user_defaults: opynfield.config.defaults_settings.Defaults, model_settings: dict[str, dict[str, opynfield.config.model_settings.ModelSpecification]], plot_settings: opynfield.config.plot_settings.PlotSettings, user_config: opynfield.config.user_input.UserInput)

This function calls the summary information function and creates the text file output

Parameters

  • tracks_by_group (defaultdict[str, list[StandardTrack]]) – the tracks to summarize

  • test_cov_asymptote (CoverageAsymptote) – the coverage asymptote information that was used

  • user_defaults (Defaults) – the default settings that were used

  • model_settings (dict[str, dict[str, ModelSpecification]]) – the model settings that were used

  • plot_settings (PlotSettings) – the plot settings that were used

  • user_config (UserInput) – the user inputs that were used

opynfield.readin.track module

class opynfield.readin.track.Track(group: str, x: numpy.ndarray, y: numpy.ndarray, t: numpy.ndarray, track_type: str, options: list, standardized: bool)

Bases: object

This dataclass aggregates information from a single track once the coordinates are standardized, but before other measures are calculated

group

the group to which the track belongs

Type

str

x

the x coordinates of the track

Type

np.ndarray

y

the y coordinates of the track

Type

np.ndarray

t

the time coordinates of the track

Type

np.ndarray

track_type

the recording type of the track

Type

str

options

additional information depending on the track type

Type

list

standardized

has the track finished its standardization process?

Type

bool

buri_convert_units()
buri_convert_to_center()
buri_running_line()
buri_subsample()
buri_fill_missing()
etho_v1_numeric()
etho_v1_subsample()
etho_v1_fill_missing()
etho_v1_convert_to_center()
etho_v2_numeric()
etho_v2_subsample()
etho_v2_fill_missing()
etho_v2_convert_to_center()
etho_txt_numeric()
etho_txt_subsample()
etho_txt_fill_missing()
etho_txt_convert_to_center()
etho_ml_numeric()
etho_ml_subsample()
etho_ml_fill_missing()
etho_ml_convert_to_center()
anymaze_center_numeric()
anymaze_center_running_line()
anymaze_center_subsample()
anymaze_center_fill_missing()
anymaze_center_convert_to_center()
anymaze_center_convert_units()
anymaze_head_numeric()
anymaze_head_running_line()
anymaze_head_subsample()
anymaze_head_fill_missing()
anymaze_head_convert_to_center()
anymaze_head_convert_units()
anymaze_center_convert_to_center(track_center, verbose)

Centers the coordinates based on the arena center point

anymaze_center_convert_units(arena_radius_cm, trim)

Converts the units of the track

anymaze_center_fill_missing(verbose: bool)

Fills in the missing coordinates

anymaze_center_numeric(verbose: bool)

Changes datatype to numeric

anymaze_center_running_line(running_window_length: int, window_step_size: int, verbose: bool)

Smooths the coordinates using the running line formula

anymaze_center_subsample(sample_freq: int, time_bin_size: int, verbose: bool)

Sub-samples the coordinates to the desired density

anymaze_head_convert_to_center(track_center, verbose)

Centers the coordinates based on the arena center point

anymaze_head_convert_units(arena_radius_cm, trim)

Converts the units of the track

anymaze_head_fill_missing(verbose: bool)

Fills in the missing coordinates

anymaze_head_numeric(verbose: bool)

Changes datatype to numeric

anymaze_head_running_line(running_window_length: int, window_step_size: int, verbose: bool)

Smooths the coordinates using the running line formula

anymaze_head_subsample(sample_freq: int, time_bin_size: int, verbose: bool)

Sub-samples the coordinates to the desired density

buri_convert_to_center(center_point_x: float, center_point_y: float, verbose: bool)

Centers the coordinates based on the arena center point

buri_convert_units(arena_radius_cm: float, arena_radius_px: int, verbose: bool)

Converts the units of the track

buri_fill_missing(verbose: bool)

Fills in the missing coordinates

buri_running_line(running_window_length: int, window_step_size: int, verbose: bool)

Smooths the coordinates using the running line formula

buri_subsample(sample_freq: int, time_bin_size: int, verbose: bool)

Sub-samples the coordinates to the desired density

etho_ml_convert_to_center(track_center: tuple[float, float], verbose: bool)

Centers the coordinates based on the arena center point

etho_ml_fill_missing(verbose: bool)

Fills in the missing coordinates

etho_ml_numeric(verbose: bool)

Changes datatype to numeric

etho_ml_subsample(sample_freq: int, time_bin_size: int, verbose: bool)

Sub-samples the coordinates to the desired density

etho_txt_convert_to_center(center_points_by_area: dict[str, tuple[float, float]], verbose: bool)

Centers the coordinates based on the arena center point

etho_txt_fill_missing(verbose: bool)

Fills in the missing coordinates

etho_txt_numeric(verbose: bool)

Changes datatype to numeric

etho_txt_subsample(sample_freq: int, time_bin_size: int, verbose: bool)

Sub-samples the coordinates to the desired density

etho_v1_convert_to_center(center_points_by_area: dict[str, tuple[float, float]], verbose: bool)

Centers the coordinates based on the arena center point

etho_v1_fill_missing(verbose: bool)

Fills in the missing coordinates

etho_v1_numeric(verbose: bool)

Changes datatype to numeric

etho_v1_subsample(sample_freq: int, time_bin_size: int, verbose: bool)

Sub-samples the coordinates to the desired density

etho_v2_convert_to_center(center_points_by_area: dict[str, tuple[float, float]], verbose: bool)

Centers the coordinates based on the arena center point

etho_v2_fill_missing(verbose: bool)

Fills in the missing coordinates

etho_v2_numeric(verbose)

Changes datatype to numeric

etho_v2_subsample(sample_freq: int, time_bin_size: int, verbose: bool)

Sub-samples the coordinates to the desired density

group: str
options: list
standardized: bool
t: numpy.ndarray
track_type: str
x: numpy.ndarray
y: numpy.ndarray

Module contents