opynfield.calculate_measures package

Submodules

opynfield.calculate_measures.calculate_measures module

opynfield.calculate_measures.calculate_measures.calculate_coverage(cov_bins: numpy.ndarray, num_bins: float, verbose: bool) → numpy.ndarray

This function is calls functions from the coverage_math module to calculate the animal’s coverage over time. See coverage types for comparison of (raw) coverage to other coverage measures. It is one step in the track standardization procedure orchestrated by opynfield.calculate_measures.calculate_measures.tracks_to_measures()

Parameters

  • cov_bins (np.ndarray) – which bin the animal is located in at each tracking point

  • num_bins (float) – the total number of bins the arena edge region is divided into

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

Returns

the coverage of the animal at each tracking point

Return type

np.ndarray

opynfield.calculate_measures.calculate_measures.calculate_group_coverage_asymptote(group_tracks: list[opynfield.calculate_measures.standard_track.StandardTrack], asymptote_info: opynfield.config.cov_asymptote.CoverageAsymptote) → float

This function calculates the coverage asymptote of a group based on the aggregated data from all individuals in the group.

Parameters

  • group_tracks (list[StandardTrack]) – a list of all standardized tracks belonging to the same analysis group

  • asymptote_info (CoverageAsymptote) – a custom dataclass that includes information needed to calculate the group’s coverage asymptote

Returns

the group’s coverage asymptote to be used in calculating the PGCA of individuals in that group

Return type

float

opynfield.calculate_measures.calculate_measures.calculate_percent_coverage(cov: numpy.ndarray, verbose: bool) → numpy.ndarray

This function normalizes an animal’s coverage by the maximum coverage the animal reaches to get its percent coverage. See coverage types for comparison of percent coverage to other coverage measures. It is one step in the track standardization procedure orchestrated by opynfield.calculate_measures.calculate_measures.tracks_to_measures()

Parameters
Returns

the percent coverage (normalized coverage) of the animal at each tracking point

Return type

np.ndarray

opynfield.calculate_measures.calculate_measures.calculate_pgca(s_track: opynfield.calculate_measures.standard_track.StandardTrack, asymptote_g: float, verbose: bool)

This function normalizes an animal’s coverage by its group’s predicted coverage asymptote from the time vs coverage model. It also sets the group asymptote as an attribute of the track. This must occur after all tracks are standardized and group coverage asymptotes are calculated. See coverage types for comparison of PGCA to other coverage measures.

Parameters

  • s_track (StandardTrack) – a standardized track

  • asymptote_g (float) – the group coverage asymptote for the group to which the s_track belongs coverage asymptote

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

Returns

the PGCA (Percent of Group Coverage Asymptote) of the animal at each tracking point

Return type

np.ndarray

opynfield.calculate_measures.calculate_measures.calculate_pica(cov: numpy.ndarray, asymptote_info: opynfield.config.cov_asymptote.CoverageAsymptote, verbose: bool) → tuple[numpy.ndarray, float]

This function normalizes an animal’s coverage by its predicted coverage asymptote from the time vs coverage model. See coverage types for comparison of PICA to other coverage measures. It is one step in the track standardization procedure orchestrated by opynfield.calculate_measures.calculate_measures.tracks_to_measures()

Parameters

  • cov (np.ndarray) – the coverage of the animal at each tracking point

  • asymptote_info (CoverageAsymptote) – a custom dataclass that includes information needed to calculate the animal’s coverage asymptote

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

Returns

the PICA (Percent of Individual Coverage Asymptote) of the animal at each tracking point

Return type

np.ndarray

opynfield.calculate_measures.calculate_measures.cartesian_to_polar(x: numpy.ndarray, y: numpy.ndarray, verbose: bool) → tuple[numpy.ndarray, numpy.ndarray]

This function converts an animal’s tracking coordinates from cartesian to polar coordinates. It is one step in the track standardization procedure orchestrated by opynfield.calculate_measures.calculate_measures.tracks_to_measures()

Parameters
Returns

a tuple of the r and theta coordinates of the opynfield.readin.track.Track

Return type

tuple[np.ndarray, np.ndarray]

opynfield.calculate_measures.calculate_measures.locate_bin(radius: numpy.ndarray, theta_angle: numpy.ndarray, node_size: float, edge_rad: float, verbose: bool) → tuple[numpy.ndarray, float]

This function assigns a bin number to each tracking point of an animal to facilitate the calculation of coverage. It is one step in the track standardization procedure orchestrated by opynfield.calculate_measures.calculate_measures.tracks_to_measures()

Parameters

  • radius (np.ndarray) – the radial position of the animal at each tracking point

  • theta_angle (np.ndarray) – the angular position of the animal at each tracking point

  • node_size (float) – the angle that (when combined with edge_rad) defines a bin - sourced from opynfield.config.user_input.UserInput

  • edge_rad (float) – at what radius do we consider the animal to be in the edge region, when combined with node_size this defines a bin - sourced from opynfield.config.user_input.UserInput

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

Returns

tuple of the bin assignment array and the total number of bins used to make the assignment

Return type

tuple[np.ndarray, float]

opynfield.calculate_measures.calculate_measures.motion_probabilities(radius: numpy.ndarray, act: numpy.ndarray, turn_angle: numpy.ndarray, inactivity_threshold: float, edge_rad: float, verbose: bool) → tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray]

This function calculates P++, P+-, P+0, P0+, and P00 (collectively ‘motion probabilities’) from an animal’s track trajectory. See motion probability types for more information. It is one step in the track standardization procedure orchestrated by opynfield.calculate_measures.calculate_measures.tracks_to_measures()

Parameters

  • radius (np.ndarray) – the radial position of the animal at each tracking point

  • act (np.ndarray) – the length of the step taken by the animal between two points

  • turn_angle (np.ndarray) – the angle the animal turned at each point between two steps

  • inactivity_threshold (np.ndarray) – to account for body wobble, how small of a step length do we consider to be negligible and set to zero - sourced from opynfield.config.user_input.UserInput object

  • edge_rad (np.ndarray) – to consider the motion probabilities only near the edge of the arena, at what radius do we consider the animal to be in the edge region - sourced from opynfield.config.user_input.UserInput object

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

Returns

tuple of the raw data for motion probabilities (P++, P+-, P+0, P0+, P00) - 1 where the action occurred and 0 elsewhere

Return type

tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray, np.ndarray]

opynfield.calculate_measures.calculate_measures.motion_probabilities_given_previous(ppp: numpy.ndarray, ppm: numpy.ndarray, ppz: numpy.ndarray, pzp: numpy.ndarray, pzz: numpy.ndarray) → tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray]

This function calculates P++Given+, P+-Given+, P+0Given+, P0+Given0, P00Given0, P++GivenAny, P+-GivenAny, P+0GivenAny, P0+GivenAny, and P00GivenAny (collectively ‘motion probabilities given previous’). See motion probability types for more information. It is one step in the track standardization procedure orchestrated by opynfield.calculate_measures.calculate_measures.tracks_to_measures()

Parameters
Returns

the motion probabilities given previous - 1 where the action occurred, 0 where it could have occurred but didn’t, and np.nan elsewhere.

Return type

tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray, np.ndarray, np.ndarray, np.ndarray, np.ndarray, np.ndarray, np.ndarray]

opynfield.calculate_measures.calculate_measures.step_distance(x: numpy.ndarray, y: numpy.ndarray, verbose: bool) → numpy.ndarray

This function calculates the distance between each consecutive pair of tracking coordinates of an animal. It is one step in the track standardization procedure orchestrated by opynfield.calculate_measures.calculate_measures.tracks_to_measures()

Parameters
Returns

the distance stepped between tracking points (also called ‘activity’)

Return type

np.ndarray

opynfield.calculate_measures.calculate_measures.tracks_to_measures(all_tracks: list[opynfield.readin.track.Track], user_config: opynfield.config.user_input.UserInput, default_settings: opynfield.config.defaults_settings.Defaults, coverage_settings: opynfield.config.cov_asymptote.CoverageAsymptote) → tuple[list[opynfield.calculate_measures.standard_track.StandardTrack], collections.defaultdict[str, list[opynfield.calculate_measures.standard_track.StandardTrack]]]

This function runs the entire standardization procedure to transform a Track to a StandardTrack. It runs the procedure for a list of all tracks in the analysis.

Parameters

  • all_tracks (list[Track]) – list of all the tracks read in for analysis

  • user_config (UserInput) – a custom dataclass that contains user inputs for analysis

  • default_settings (Defaults) – a custom dataclass that contains default settings for analysis

  • coverage_settings (CoverageAsymptote) – a custom class that contains settings for the calculation of coverage asymptotes

Returns

tuple of a list of all standardized tracks and a dictionary of group names to a list of all standardized tracks belonging to that group

Return type

tuple[list[StandardTrack], defaultdict[str, list[StandardTrack]]]

opynfield.calculate_measures.calculate_measures.turning_angle(x: numpy.ndarray, y: numpy.ndarray, verbose: bool) → numpy.ndarray

This function calculates the angle that the animal turned between two consecutive steps, using the law of cosines. It is one step in the track standardization procedure orchestrated by opynfield.calculate_measures.calculate_measures.tracks_to_measures()

Parameters
Returns

the magnitude of the angle (in degrees) from a straight heading that the animal turned between each consecutive set of steps.

Return type

np.ndarray

opynfield.calculate_measures.coverage_math module

opynfield.calculate_measures.coverage_math.bins_traversed(past_fly_bin: int, n_steps: int, step_direction: int, m) → numpy.ndarray

Identifies which bins were visited along a path of n_steps from the current bin in the step_direction.

Parameters

  • past_fly_bin (int) – the bin the animal was in at the previous tracking point

  • n_steps (int) – the number of bins the animal traversed

  • step_direction (int) – the direction the animal is traveling (1 if counterclockwise, -1 if clockwise)

  • m (int) – number of total bins

Returns

which bins were visited along the path

Return type

np.ndarray

opynfield.calculate_measures.coverage_math.fly_coverage(visits: numpy.ndarray, m: int) → numpy.ndarray
Calculates the coverage of a tracking point from a bin visit array and assigns the coverage value to the coverage

array at that index.

Parameters

  • visits (np.ndarray) – bin visit array at a tracking point

  • m (int) – number of total bins

Returns

an array of coverage at each tracking point, updated up to the current tracking point

Return type

np.ndarray

opynfield.calculate_measures.coverage_math.path_coverage(cov_bins: numpy.ndarray, num_bins: float) → numpy.ndarray

This function formats inputs and calls _path_coverage to calculate the animal’s coverage over time.

Parameters

  • cov_bins (np.ndarray) – which bin the animal is located in at each tracking point

  • num_bins (float) – the total number of bins the arena edge region is divided into

Returns

the coverage of the animal at each tracking point

Return type

np.ndarray

opynfield.calculate_measures.coverage_math.sign_to_step(past_fly_bin: int, current_fly_bin: int, num_bins: int) → tuple[int, int]

Identifies the direction of travel and the number of bins traversed in that direction.

Parameters

  • past_fly_bin (int) – the bin the animal was in at the previous tracking point

  • current_fly_bin (int) – the bin that the animal is in at the current tracking point

  • num_bins (int) – number of total bins

Returns

tuple of the direction the animal is traveling (1 if counterclockwise, -1 if clockwise), and the number of bins the animal traversed in that direction of travel

Return type

tuple[int, int]

opynfield.calculate_measures.coverage_math.update_first_visit(visits: numpy.ndarray, first_vis: int) → numpy.ndarray

Creates a bin visit array for the initial time point.

Parameters

  • visits (np.ndarray) – bin visit array initialized with 0s

  • first_vis (int) – bin the animal was in for the first tracking point

Returns

bin visit array updated with the first bin

Return type

np.ndarray

opynfield.calculate_measures.coverage_math.update_visits(past_fly_bin: int, current_fly_bin: int, past_visits: numpy.ndarray, m: int) → numpy.ndarray

Determines if the bin visit array needs to be updated with information from the current bin location, or if the bin visit counts remain unchanged. Calls update_visits_for_steps_between_bins() the bin visit array needs multiple updates.

Parameters

  • past_fly_bin (int) – the bin the animal was in at the previous tracking point

  • current_fly_bin (int) – the bin that the animal is in at the current tracking point

  • past_visits (np.ndarray) – the bin visit array at the previous tracking point

  • m (int) – number of total bins

Returns

the bin visit array at the current tracking point

Return type

np.ndarray

opynfield.calculate_measures.coverage_math.update_visits_for_steps_between_bins(past_fly_bin: int, current_fly_bin: int, past_visits: numpy.ndarray, m: int) → numpy.ndarray

Updates the bin visit array in cases where the animal has traversed across multiple bins in a single step by identifying the direction of travel, the number of bins traversed, and the specific bins that were visited during the travel between bins

Parameters

  • past_fly_bin (int) – the bin the animal was in at the previous tracking point

  • current_fly_bin (int) – the bin that the animal is in at the current tracking point

  • past_visits (np.ndarray) – the bin visit array at the previous tracking point

  • m (int) – number of total bins

Returns

the bin visit array at the current tracking point

Return type

np.ndarray

opynfield.calculate_measures.standard_track module

class opynfield.calculate_measures.standard_track.StandardTrack(group: str, x: numpy.ndarray, y: numpy.ndarray, t: numpy.ndarray, r: numpy.ndarray, theta: numpy.ndarray, activity: numpy.ndarray, turn: numpy.ndarray, p_plus_plus: numpy.ndarray, p_plus_minus: numpy.ndarray, p_plus_zero: numpy.ndarray, p_zero_plus: numpy.ndarray, p_zero_zero: numpy.ndarray, coverage_bins: numpy.ndarray, n_bins: float, coverage: numpy.ndarray, percent_coverage: numpy.ndarray, pica: numpy.ndarray, pica_asymptote: float, pgca: numpy.ndarray, pgca_asymptote: float, p_plus_plus_given_plus: numpy.ndarray, p_plus_minus_given_plus: numpy.ndarray, p_plus_zero_given_plus: numpy.ndarray, p_zero_plus_given_zero: numpy.ndarray, p_zero_zero_given_zero: numpy.ndarray, p_plus_plus_given_any: numpy.ndarray, p_plus_minus_given_any: numpy.ndarray, p_plus_zero_given_any: numpy.ndarray, p_zero_plus_given_any: numpy.ndarray, p_zero_zero_given_any: numpy.ndarray)

Bases: object

This dataclass stores all relevant original and derived measures associated with an animal’s track. It is produced after the track standardization procedure from tracks_to_measures() is completed.

group

group to which the track belongs

Type

str

x

the track’s x coordinates

Type

np.ndarray

y

the track’s y coordinates

Type

np.ndarray

t

the time the track’s coordinates were recorded

Type

np.ndarray

r

the track’s radial coordinates

Type

np.ndarray

theta

the track’s angular coordinates

Type

np.ndarray

activity

the track’s activity (step length between two consecutive points)

Type

np.ndarray

turn

the track’s turn angle (the angle in degrees that the animal turned between two consecutive steps)

Type

np.ndarray

p_plus_plus

the raw P++ of the track. See motion probability types for more information.

Type

np.ndarray

p_plus_minus

the raw P+- of the track. See motion probability types for more information.

Type

np.ndarray

p_plus_zero

the raw P+0 of the track. See motion probability types for more information.

Type

np.ndarray

p_zero_plus

the raw P0+ of the track. See motion probability types for more information.

Type

np.ndarray

p_zero_zero

the raw P00 of the track. See motion probability types for more information.

Type

np.ndarray

coverage_bins

the bin the animal was in at each tracking point

Type

np.ndarray

n_bins

the total number of bins the arena edge is divided into

Type

float

coverage

the raw coverage of the track. See coverage types for more information.

Type

np.ndarray

percent_coverage

the percent coverage of the track. See coverage types for more information.

Type

np.ndarray

pica

the PICA (Percent of Individual Coverage Asymptote) of the track. See coverage types for more information.

Type

np.ndarray

pica_asymptote

the asymptote of the animals time vs coverage model

Type

float

pgca

the PGCA (Percent of Group Coverage Asymptote) of the group the track belongs to. Or an initialized dummy value of all ones. See coverage types for more information.

Type

np.ndarray

pgca_asymptote

the asymptote of the time vs coverage model for the group the track belongs to. Or an initialized dummy value of np.nan

Type

float

p_plus_plus_given_plus

the P++Given+ of the track. See motion probability types for more information.

Type

np.ndarray

p_plus_minus_given_plus

the P+-Given+ of the track. See motion probability types for more information.

Type

np.ndarray

p_plus_zero_given_plus

the P+0Given+ of the track. See motion probability types for more information.

Type

np.ndarray

p_zero_plus_given_zero

the P0+Given0 of the track. See motion probability types for more information.

Type

np.ndarray

p_zero_zero_given_zero

the P00Given0 of the track. See motion probability types for more information.

Type

np.ndarray

p_plus_plus_given_any

the P++GivenAny of the track. See motion probability types for more information.

Type

np.ndarray

p_plus_minus_given_any

the P+-GivenAny of the track. See motion probability types for more information.

Type

np.ndarray

p_plus_zero_given_any

the P+0GivenAny of the track. See motion probability types for more information.

Type

np.ndarray

p_zero_plus_given_any

the P0+GivenAny of the track. See motion probability types for more information.

Type

np.ndarray

p_zero_zero_given_any

the P00GivenAny of the track. See motion probability types for more information.

Type

np.ndarray

activity: numpy.ndarray
coverage: numpy.ndarray
coverage_bins: numpy.ndarray
group: str
n_bins: float
p_plus_minus: numpy.ndarray
p_plus_minus_given_any: numpy.ndarray
p_plus_minus_given_plus: numpy.ndarray
p_plus_plus: numpy.ndarray
p_plus_plus_given_any: numpy.ndarray
p_plus_plus_given_plus: numpy.ndarray
p_plus_zero: numpy.ndarray
p_plus_zero_given_any: numpy.ndarray
p_plus_zero_given_plus: numpy.ndarray
p_zero_plus: numpy.ndarray
p_zero_plus_given_any: numpy.ndarray
p_zero_plus_given_zero: numpy.ndarray
p_zero_zero: numpy.ndarray
p_zero_zero_given_any: numpy.ndarray
p_zero_zero_given_zero: numpy.ndarray
percent_coverage: numpy.ndarray
pgca: numpy.ndarray
pgca_asymptote: float
pica: numpy.ndarray
pica_asymptote: float
r: numpy.ndarray
set_pgca(input_pgca: numpy.ndarray, input_pgca_a: float)

This is a method that re-sets the pgca and pgca_asymptote values from their dummy initialization values to their true values calculated during the track standardization procedure.

Parameters

  • input_pgca (np.ndarray) – the PGCA (Percent of Group Coverage Asymptote) of the group the track belongs to. See coverage types for more information.

  • input_pgca_a (float) – the asymptote of the time vs coverage model for the group the track belongs to

t: numpy.ndarray
theta: numpy.ndarray
classmethod to_dataframes(instances: list['StandardTrack'], extra_fields_by_name: list[str]) → tuple[dict[str, pandas.core.frame.DataFrame], list[str]]

This class method, called in individual_measures_to_dfs(), will create a dataframe for each dataclass attribute that is either an array or is included in the ‘extra_fields_by_name’ argument.

Parameters

  • instances (list[StandardTrack]) – list of the standard tracks to be summarized together (usually all tracks belonging to the same group)

  • extra_fields_by_name (list[str]) – which non-array fields also need to be stored in dataframes

Returns

a tuple of a dictionary of field names to dataframes and a list of all the field names

Return type

tuple[dict[str, pd.DataFrame], list[str]]

turn: numpy.ndarray
x: numpy.ndarray
y: numpy.ndarray

Module contents