opynfield.config package

Submodules

opynfield.config.cov_asymptote module

class opynfield.config.cov_asymptote.CoverageAsymptote(f_name: typing.Callable = <function fixed_exponential>, asymptote_param: int = 0, asymptote_sign: int = -1, initial_parameters: tuple[float] = (-0.01, -0.01), parameter_bounds: tuple[list[int], list[int]] = ([-10, -10], [0, 0]), max_f_eval: int = 4000)

Bases: object

This dataclass associates relevant information for the model fits needed to calculate a coverage asymptote (for PICA and PGCA)

f_name

the function to use in the model fit - be a function that approaches an asymptote as x approaches infinity, defaults to fixed_exponential()

Type

Callable

asymptote_param

which parameter indicates the asymptote magnitude, defaults to 0

Type

int

asymptote_sign

is the asymptote parameter positive or negative, defaults to -1 (negative)

Type

int

initial_parameters

what p0 to use in curve fitting to find the asymptote, defaults to (-0.1, -0.1)

Type

tuple[float]

parameter_bounds

what bounds to use in curve fitting to find the asymptote, defaults to ([-10, -10], [0, 0])

Type

tuple[list[int]]

max_f_eval

max number of iterations the curve fitting process can take to find the asymptote, defaults to 4000

Type

int

asymptote_param: int = 0
asymptote_sign: int = -1
f_name(a, b)

Fits a ‘fixed exponential’ model to the data which anchors the curve at (0, 0)

Parameters

  • x (np.ndarray) – independent data

  • a (float) – scaling parameter

  • b (float) – growth parameter

Returns

dependent data

Return type

np.ndarray

initial_parameters: tuple[float] = (-0.01, -0.01)
max_f_eval: int = 4000
parameter_bounds: tuple[list[int], list[int]] = ([-10, -10], [0, 0])
opynfield.config.cov_asymptote.exponential(x, a, b, c)

Fits an exponential model to the data

Parameters

  • x (np.ndarray) – independent data

  • a (float) – scaling parameter

  • b (float) – decay parameter

  • c (float) – constant parameter

Returns

dependent data

Return type

np.ndarray

opynfield.config.cov_asymptote.fixed_exponential(x, a, b)

Fits a ‘fixed exponential’ model to the data which anchors the curve at (0, 0)

Parameters

  • x (np.ndarray) – independent data

  • a (float) – scaling parameter

  • b (float) – growth parameter

Returns

dependent data

Return type

np.ndarray

opynfield.config.cov_asymptote.linear(x, a, b)

Fits a linear model to the data

Parameters

  • x (np.ndarray) – independent data

  • a (float) – slope

  • b (float) – intercept

Returns

dependent data

Return type

np.ndarray

opynfield.config.defaults_settings module

class opynfield.config.defaults_settings.Defaults(node_size: float = 0.1, save_group_csvs: bool = True, save_all_group_csvs: bool = True, save_group_model_csvs: bool = True, save_all_group_model_csvs: bool = True, n_points_coverage: int = 36, n_points_pica: int = 36, n_points_pgca: int = 36, n_bins_percent_coverage: int = 10)

Bases: object

This dataclass defines many default values that are used across the package.

node_size

the angle that (when combined with a radial bound) defines a bin for coverage calculations, defaults to 0.1

Type

float

save_group_csvs

whether to save a separate .csv file of the component measures for each group, defaults to True

Type

bool

save_all_group_csvs

whether to save a combined .csv file of the component measures of each group, defaults to True

Type

bool

save_group_model_csvs

whether to save a separate .csv file of the model parameters for each group, defaults to True

Type

bool

save_all_group_model_csvs

whether to save a combined .csv file of the model parameters of each group, defaults to True

Type

bool

n_points_coverage

the number of points to group together in an average for the coverage domain, defaults to 36

Type

int

n_points_pica

the number of points to group together in an average for the pica domain, defaults to 36

Type

int

n_points_pgca

the number of points to group together in an average for the pgca domain, defaults to 36

Type

int

n_bins_percent_coverage

the number of points to group together in an average for the percent coverage domain, defaults to 10

Type

int

time_averaged_measures

which measures should be averaged in the time domain, defaults to [“r”, “activity”, “p_plus_plus”, “p_plus_minus”, “p_plus_zero”, “p_zero_plus”, “p_zero_zero”, “coverage”, “percent_coverage”, “pica”, “pgca”, “p_plus_plus_given_plus”, “p_plus_minus_given_plus”, “p_plus_zero_given_plus”, “p_zero_plus_given_zero”, “p_zero_zero_given_zero”, “p_plus_plus_given_any”, “p_plus_minus_given_any”, “p_plus_zero_given_any”, “p_zero_plus_given_any”, “p_zero_zero_given_any”]

Type

list[str]

coverage_averaged_measures

which measures should be averages in the coverage, percent coverage, pica, and pgca domains, defaults to [“activity”, “p_plus_plus”, “p_plus_minus”, “p_plus_zero”, “p_zero_plus”, “p_zero_zero”, “p_plus_plus_given_plus”, “p_plus_minus_given_plus”, “p_plus_zero_given_plus”, “p_zero_plus_given_zero”, “p_zero_zero_given_zero”, “p_plus_plus_given_any”, “p_plus_minus_given_any”, “p_plus_zero_given_any”, “p_zero_plus_given_any”, “p_zero_zero_given_any”]

Type

list[str]

coverage_averaged_measures = ['activity', 'p_plus_plus', 'p_plus_minus', 'p_plus_zero', 'p_zero_plus', 'p_zero_zero', 'p_plus_plus_given_plus', 'p_plus_minus_given_plus', 'p_plus_zero_given_plus', 'p_zero_plus_given_zero', 'p_zero_zero_given_zero', 'p_plus_plus_given_any', 'p_plus_minus_given_any', 'p_plus_zero_given_any', 'p_zero_plus_given_any', 'p_zero_zero_given_any']
create_pairs()

Create a list of strings that indicate which measure combinations should be modeled and tested

Returns

list of strings that indicate xy pairs

Return type

list[str]

n_bins_percent_coverage: int = 10
n_points_coverage: int = 36
n_points_pgca: int = 36
n_points_pica: int = 36
node_size: float = 0.1
save_all_group_csvs: bool = True
save_all_group_model_csvs: bool = True
save_group_csvs: bool = True
save_group_model_csvs: bool = True
time_averaged_measures = ['r', 'activity', 'p_plus_plus', 'p_plus_minus', 'p_plus_zero', 'p_zero_plus', 'p_zero_zero', 'coverage', 'percent_coverage', 'pica', 'pgca', 'p_plus_plus_given_plus', 'p_plus_minus_given_plus', 'p_plus_zero_given_plus', 'p_zero_plus_given_zero', 'p_zero_zero_given_zero', 'p_plus_plus_given_any', 'p_plus_minus_given_any', 'p_plus_zero_given_any', 'p_zero_plus_given_any', 'p_zero_zero_given_any']

opynfield.config.model_settings module

class opynfield.config.model_settings.ExponentialModel(initial_params: tuple[float, float, float] = (0.1, - 0.1, 0.01), bounds: tuple[tuple[float, float, float], tuple[float, float, float]] = ((0, - 10, 0), (10, 0, 10)), max_eval: int = 4000, display_parts: tuple[str] = ('y = ', ' * e ^ (', ' * x) + '))

Bases: object

This dataclass groups together relevant information for exponential model fits

initial_params

what p0 to use in curve fitting, defaults to (0.1, -0.1, 0.01)

Type

tuple[float, float, float

bounds

what bounds to use in curve fitting, defaults to ((0, -10, 0), (10, 0, 10))

Type

tuple[tuple[float, float, float], tuple[float, float, float]]

max_eval

max number of iterations the curve fitting process can take, defaults to 4000

Type

int

display_parts

strings that when combined with parameter fit values will show the equation of the best fit model, defaults to (“y = “, ” * e ^ (”, ” * x) + “)

Type

tuple[str]

model_function()

the exponential model function

bounds: tuple[tuple[float, float, float], tuple[float, float, float]] = ((0, -10, 0), (10, 0, 10))
display_parts: tuple[str] = ('y = ', ' * e ^ (', ' * x) + ')
initial_params: tuple[float, float, float] = (0.1, -0.1, 0.01)
max_eval: int = 4000
static model_function(x, a, b, c)
class opynfield.config.model_settings.FixedExponentialModel(initial_params: tuple[float, float] = (- 0.1, - 0.1), bounds: tuple[tuple[float, float], tuple[float, float]] = ((- 10, - 10), (0, 0)), max_eval: int = 4000, display_parts: tuple[str] = ('y = ', ' * (e ^ (', ' * x) - 1)'))

Bases: object

This dataclass groups together relevant information for fixed exponential model fits

initial_params

what p0 to use in curve fitting, defaults to (-0.1, -0.1)

Type

tuple[float, float

bounds

what bounds to use in curve fitting, defaults to ((-10, -10), (0, 0))

Type

tuple[tuple[float, float], tuple[float, float]]

max_eval

max number of iterations the curve fitting process can take, defaults to 4000

Type

int

display_parts

strings that when combined with parameter fit values will show the equation of the best fit model, defaults to (“y = “, ” * (e ^ (”, ” * x) - 1)”)

Type

tuple[str]

model_function()

the fixed exponential model function

bounds: tuple[tuple[float, float], tuple[float, float]] = ((-10, -10), (0, 0))
display_parts: tuple[str] = ('y = ', ' * (e ^ (', ' * x) - 1)')
initial_params: tuple[float, float] = (-0.1, -0.1)
max_eval: int = 4000
static model_function(x, a, b)
class opynfield.config.model_settings.LinearDecreaseModel(initial_params: tuple[float, float] = (- 0.1, 0.1), bounds: tuple[tuple[float, float], tuple[float, float]] = ((- 10, 0), (0, 10)), max_eval: int = 4000, display_parts: tuple[str] = ('y = ', ' * x + '))

Bases: object

This dataclass groups together relevant information for linear decrease model fits

initial_params

what p0 to use in curve fitting, defaults to (-0.1, 0.1)

Type

tuple[float, float

bounds

what bounds to use in curve fitting, defaults to ((-10, 0), (0, 10))

Type

tuple[tuple[float, float], tuple[float, float]]

max_eval

max number of iterations the curve fitting process can take, defaults to 4000

Type

int

display_parts

strings that when combined with parameter fit values will show the equation of the best fit model, defaults to (“y = “, ” * x + “)

Type

tuple[str]

model_function()

the linear decrease model function

bounds: tuple[tuple[float, float], tuple[float, float]] = ((-10, 0), (0, 10))
display_parts: tuple[str] = ('y = ', ' * x + ')
initial_params: tuple[float, float] = (-0.1, 0.1)
max_eval: int = 4000
static model_function(x, a, b)
class opynfield.config.model_settings.LinearIncreaseModel(initial_params: tuple[float, float] = (0.1, 0.1), bounds: tuple[tuple[float, float], tuple[float, float]] = ((0, 0), (10, 10)), max_eval: int = 4000, display_parts: tuple[str] = ('y = ', ' * x + '))

Bases: object

This dataclass groups together relevant information for linear increase model fits

initial_params

what p0 to use in curve fitting, defaults to (0.1, 0.1)

Type

tuple[float, float

bounds

what bounds to use in curve fitting, defaults to ((0, 0), (10, 10))

Type

tuple[tuple[float, float], tuple[float, float]]

max_eval

max number of iterations the curve fitting process can take, defaults to 4000

Type

int

display_parts

strings that when combined with parameter fit values will show the equation of the best fit model, defaults to (“y = “, ” * x + “)

Type

tuple[str]

model_function()

the linear increase model function

bounds: tuple[tuple[float, float], tuple[float, float]] = ((0, 0), (10, 10))
display_parts: tuple[str] = ('y = ', ' * x + ')
initial_params: tuple[float, float] = (0.1, 0.1)
max_eval: int = 4000
static model_function(x, a, b)
class opynfield.config.model_settings.ModelSpecification(axes: tuple[str, str], model: Union[opynfield.config.model_settings.ExponentialModel, opynfield.config.model_settings.FixedExponentialModel, opynfield.config.model_settings.LinearIncreaseModel, opynfield.config.model_settings.LinearDecreaseModel])

Bases: object

This dataclass groups together a set of x and y axes to model the relationship between and the model (with associated model information) to use for that relationship

axes

the x and y variables to model against each other

Type

tuple[str, str]

model

the model to use to model the axes

Type

Union[ExponentialModel, FixedExponentialModel, LinearIncreaseModel, LinearDecreaseModel]

get_x()

isolate the x-axis from the axes

get_y()

isolate the y-axis from the axes

axes: tuple[str, str]
get_x()
get_y()
model: Union[opynfield.config.model_settings.ExponentialModel, opynfield.config.model_settings.FixedExponentialModel, opynfield.config.model_settings.LinearIncreaseModel, opynfield.config.model_settings.LinearDecreaseModel]
opynfield.config.model_settings.mapper(y: str, map_exponential: tuple[str], map_fixed: tuple[str], map_linear_increase: tuple[str], map_linear_decrease: tuple[str]) → Union[opynfield.config.model_settings.ExponentialModel, opynfield.config.model_settings.FixedExponentialModel, opynfield.config.model_settings.LinearIncreaseModel, opynfield.config.model_settings.LinearDecreaseModel]

This function maps a y-axis variable to the model type that should be used in modeling its relationships

Parameters

  • y (str) – the y-axis variable to map to a model type

  • map_exponential (tuple[str]) – which y-axis variables should be mapped to an exponential model

  • map_fixed (tuple[str]) – which y-axis variables should be mapped to a fixed exponential model

  • map_linear_increase (tuple[str]) – which y-axis variables should be mapped to a linear increase model

  • map_linear_decrease (tuple[str]) – which y-axis variables should be mapped to a linear decrease model

Returns

the model to use

Return type

Union[ExponentialModel, FixedExponentialModel, LinearIncreaseModel, LinearDecreaseModel]

opynfield.config.model_settings.set_up_fits(x_list: tuple[str] = ('time', 'coverage', 'pica', 'pgca', 'percent_coverage'), y_time_list: tuple[str] = ('activity', 'coverage', 'percent_coverage', 'pica', 'pgca', 'p_plus_plus', 'p_plus_minus', 'p_plus_zero', 'p_zero_plus', 'p_zero_zero', 'coverage', 'percent_coverage', 'pica', 'pgca', 'p_plus_plus_given_plus', 'p_plus_minus_given_plus', 'p_plus_zero_given_plus', 'p_zero_plus_given_zero', 'p_zero_zero_given_zero', 'p_plus_plus_given_any', 'p_plus_minus_given_any', 'p_plus_zero_given_any', 'p_zero_plus_given_any', 'p_zero_zero_given_any'), y_other_list: tuple[str] = ('activity', 'p_plus_plus', 'p_plus_minus', 'p_plus_zero', 'p_zero_plus', 'p_zero_zero', 'p_plus_plus_given_plus', 'p_plus_minus_given_plus', 'p_plus_zero_given_plus', 'p_zero_plus_given_zero', 'p_zero_zero_given_zero', 'p_plus_plus_given_any', 'p_plus_minus_given_any', 'p_plus_zero_given_any', 'p_zero_plus_given_any', 'p_zero_zero_given_any'), map_exponential: tuple[str] = ('activity', 'p_plus_plus', 'p_plus_plus_given_plus', 'p_plus_plus_given_any', 'p_zero_plus', 'p_zero_plus_given_zero', 'p_zero_plus_given_any'), map_fixed: tuple[str] = ('p_plus_minus', 'p_plus_minus_given_plus', 'p_plus_minus_given_any', 'p_plus_zero', 'p_plus_zero_given_plus', 'p_plus_zero_given_any', 'p_zero_zero', 'p_zero_zero_given_zero', 'p_zero_zero_given_any', 'coverage', 'percent_coverage', 'pica', 'pgca'), map_linear_increase: tuple[str] = (), map_linear_decrease: tuple[str] = ()) → dict[str, dict[str, opynfield.config.model_settings.ModelSpecification]]

This function

Parameters

  • x_list (tuple[str]) – the x-axis variables, defaults to (“time”, “coverage”, “pica”, “pgca”, “percent_coverage”)

  • y_time_list (tuple[str]) – the y-axis variables that can be mapped against time, defaults to (“activity”, “coverage”, “percent_coverage”, “pica”, “pgca”, “p_plus_plus”, “p_plus_minus”, “p_plus_zero”, “p_zero_plus”, “p_zero_zero”, “coverage”, “percent_coverage”, “pica”, “pgca”, “p_plus_plus_given_plus”, “p_plus_minus_given_plus”, “p_plus_zero_given_plus”, “p_zero_plus_given_zero”, “p_zero_zero_given_zero”, “p_plus_plus_given_any”, “p_plus_minus_given_any”, “p_plus_zero_given_any”, “p_zero_plus_given_any”, “p_zero_zero_given_any”)

  • y_other_list (tuple[str]) – the y-axis variables that can be mapped against coverage measures, defaults to (“activity”, “p_plus_plus”, “p_plus_minus”, “p_plus_zero”, “p_zero_plus”, “p_zero_zero”, “p_plus_plus_given_plus”, “p_plus_minus_given_plus”, “p_plus_zero_given_plus”, “p_zero_plus_given_zero”, “p_zero_zero_given_zero”, “p_plus_plus_given_any”, “p_plus_minus_given_any”, “p_plus_zero_given_any”, “p_zero_plus_given_any”, “p_zero_zero_given_any”)

  • map_exponential (tuple[str]) – the y-axis variables that should be modeled with an exponential model, defaults to (“activity”, “p_plus_plus”, “p_plus_plus_given_plus”, “p_plus_plus_given_any”, “p_zero_plus”, “p_zero_plus_given_zero”, “p_zero_plus_given_any”,)

  • map_fixed (tuple[str]) – the y-axis variables that should be modeled with a fixed exponential model, defaults to (“p_plus_minus”, “p_plus_minus_given_plus”, “p_plus_minus_given_any”, “p_plus_zero”, “p_plus_zero_given_plus”, “p_plus_zero_given_any”, “p_zero_zero”, “p_zero_zero_given_zero”, “p_zero_zero_given_any”, “coverage”, “percent_coverage”, “pica”, “pgca”,)

  • map_linear_increase (tuple[str]) – the y-axis variables that should be modeled with a linear increase model, defaults to ()

  • map_linear_decrease (tuple[str]) – the y-axis variables that should be modeled with a linear decrease model, defaults to ()

Returns

a dictionary of x-axis to a dictionary of y-axis to a model type to use

Return type

dict[str, dict[str, ModelSpecification]]

opynfield.config.plot_settings module

class opynfield.config.plot_settings.PlotSettings(group_colors: dict[str, str], marker_size: int = 2, marker_color: str = 'b', individual_model_fit: bool = True, fit_color: str = 'k', alpha: float = 0.3, group_error_bars: bool = True, error_color: str = 'b', n_between_error: int = 1, group_model_fit: bool = True, equation: bool = True, display_individual_figures: bool = False, save_individual_figures: bool = True, display_solo_group_figures: bool = False, save_solo_group_figures: bool = True, save_combined_view_figures: bool = True, fig_extension: str = '.png', colormap_name: str = 'gist_rainbow', edge_color: str = 'k', error_width: float = 0.5, save_group__comparison_figures: bool = True)

Bases: object

This dataclass defines many settings that govern the design of the output plots

group_colors

what colors to use for each group in group comparison plots - must have one color per group

Type

dict[str, str]

marker_size

what size to plot the markers, defaults to 2

Type

int

marker_color

what color to plot the data (for single animals or single groups), defaults to ‘b’ (blue)

Type

str

individual_model_fit

whether to plot the models on single animal plots, defaults to True

Type

bool

fit_color

what color to plot the model (for single animals or single groups), defaults to ‘k’ (black)

Type

str

alpha

transparency to plot the model, defaults to 0.3

Type

float

group_error_bars

whether to plot the error bars for group averages, defaults to True

Type

bool

error_color

what color to plot the error bars for group averages, defaults to ‘b’ (blue)

Type

str

n_between_error

n to plot error bars on every nth data point, defaults to 1

Type

int

group_model_fit

whether to plot the models on group plots, defaults to True

Type

bool

equation

whether to display the model equation on single animal or single group plots, defaults to True

Type

bool

display_individual_figures

whether to render the single animal plots, defaults to False

Type

bool

save_individual_figures

whether to save out the single animal plots, defaults to True

Type

bool

display_solo_group_figures

whether to render the group plots, defaults to False

Type

bool

save_solo_group_figures

whether to save out the single group plots, defaults to True

Type

bool

save_combined_view_figures

whether to save out single group plots that show component individuals, defaults to True

Type

bool

fig_extension

what file format to save plots in, defaults to ‘.png’

Type

str

colormap_name

what color map to use for the trajectory plot time bar, defaults to ‘gist_rainbow’

Type

str

edge_color

what color to plot the arena boundary for thr trajectory plot time bar, defaults to ‘k’ (black)

Type

str

error_width

what width to plot the error bars, defaults to 0.5

Type

float

save_group__comparison_figures

whether to save out the the group comparison plots, defaults to True

Type

bool

alpha: float = 0.3
colormap_name: str = 'gist_rainbow'
display_individual_figures: bool = False
display_solo_group_figures: bool = False
edge_color: str = 'k'
equation: bool = True
error_color: str = 'b'
error_width: float = 0.5
fig_extension: str = '.png'
fit_color: str = 'k'
group_colors: dict[str, str]
group_error_bars: bool = True
group_model_fit: bool = True
individual_model_fit: bool = True
marker_color: str = 'b'
marker_size: int = 2
n_between_error: int = 1
save_combined_view_figures: bool = True
save_group__comparison_figures: bool = True
save_individual_figures: bool = True
save_solo_group_figures: bool = True

opynfield.config.user_input module

class opynfield.config.user_input.UserInput(groups_and_types: dict[str, list[str]], groups_to_paths: dict[str, str], arena_radius_cm: float, sample_freq: int, edge_dist_cm: float, time_bin_size: int, inactivity_threshold: float, verbose: bool, result_path: str, running_window_length: int = 5, window_step_size: int = 1, trim: int = 0, bound_level: float = 2)

Bases: object

This dataclass defines many user inputs that are needed to properly read in and analyze the data

groups_and_types

dictionary of group names to a list of filetypes that include tracks from that group

Type

dict[str, list[str]

groups_to_paths

if the group names include non-standard characters (e.g. ‘/’), how to display the group names without those nonstandard characters

Type

dict[str, str]

arena_radius_cm

radius of the arena the tracks were recorded in (in cm)

Type

dict[str, str]

sample_freq

the frame rate that tracking points were recorded with

Type

int

edge_dist_cm

how far into the arena is considered the edge region

Type

float

time_bin_size

how many seconds should be binned together in the aggregation

Type

int

inactivity_threshold

how small of a step should be considered body wobble rather than activity

Type

float

verbose

whether to display progress updates

Type

bool

result_path

path to folder where you want to store results

Type

str

running_window_length

smoothing function parameter set to match ethovision smoothing, defaults to 5

Type

int

window_step_size

smoothing function parameter set to match ethovision smoothing, defaults to 1

Type

int

trim

for recordings that start before the animal is in the arena, how many points to trim off the beginning so that the arena boundary is identified correctly, defaults to 0

Type

int

bound_level

how many standard deviations to use when bounding the parameters fits, defaults to 2

Type

float

arena_radius_cm: float
bound_level: float = 2
change_running_window_length(new_window_length)

This method allows the running window length to be changed

change_trim(new_trim)

This method allows the trim parameter to be changed

change_window_step_size(new_window_step_size)

This method allows the window step size to be changed

edge_dist_cm: float
groups_and_types: dict[str, list[str]]
groups_to_paths: dict[str, str]
inactivity_threshold: float
prep_directory()

This method creates the folder in which the results will be saved

result_path: str
running_window_length: int = 5
sample_freq: int
set_edge_radius()

This method takes the arena radius and the edge distance to calculate the edge radiusd

Returns

the radius at which the arena edge region begins

Return type

float

time_bin_size: int
trim: int = 0
verbose: bool
window_step_size: int = 1

Module contents