larvaworld.lib.reg.parFunc

Parameter-computing functions. Contains functions that compute/derive higher-order parameters from the existing ones in the dataset.

Functions

`track_par_func`(→ Callable[[Any], None])	Create a parameter tracking function for a specific chunk.
`chunk_func`(→ larvaworld.lib.util.AttrDict)	Create chunk annotation function with required parameters.
`dsp_func`(→ Callable[[Any], None])	Create dispersal computation function for a time range.
`tor_func`(→ Callable[[Any], None])	Create tortuosity computation function for a time window.
`mean_func`(→ Callable[[Any], None])	Create function to compute per-agent mean of a parameter.
`std_func`(→ Callable[[Any], None])	Create function to compute per-agent standard deviation of a parameter.
`var_func`(→ Callable[[Any], None])	Create function to compute per-agent coefficient of variation.
`min_func`(→ Callable[[Any], None])	Create function to compute per-agent minimum of a parameter.
`max_func`(→ Callable[[Any], None])	Create function to compute per-agent maximum of a parameter.
`fin_func`(→ Callable[[Any], None])	Create function to extract final value of a parameter per agent.
`init_func`(→ Callable[[Any], None])	Create function to extract initial value of a parameter per agent.
`cum_func`(→ Callable[[Any], None])	Create function to compute per-agent cumulative sum of a parameter.
`freq_func`(→ Callable[[Any], None])	Create function to compute frequency spectrum of a parameter.
`tr_func`(→ Callable[[Any], None])	Create function to compute time ratio for a behavioral chunk.
`unwrap_func`(→ Callable[[Any], None])	Create function to unwrap angular parameter discontinuities.
`dst_func`(→ Callable[[Any], None])	Create function to compute distance from a reference point.
`func_v_spatial`(→ Callable[[Any], None])	Create function to compute velocity from displacement.

Module Contents

larvaworld.lib.reg.parFunc.track_par_func(chunk: str, par: str) → Callable[[Any], None]

Create a parameter tracking function for a specific chunk.

Factory function that generates a callable to track parameters within behavioral chunks (e.g., strides, pauses, runs).

Args:

chunk: Name of the behavioral chunk (e.g., ‘str’, ‘pau’, ‘run’) par: Parameter name to track within the chunk

Returns:

Callable that accepts a dataset and tracks the parameter in the chunk

Example:

>>> tracker = track_par_func('str', 'velocity')
>>> tracker(dataset)  # Tracks velocity in stride chunks

larvaworld.lib.reg.parFunc.chunk_func(kc: str) → larvaworld.lib.util.AttrDict

Create chunk annotation function with required parameters.

Factory function that generates annotation functions for behavioral chunks (crawl or turn events) along with their required parameter keys.

Args:

kc: Chunk key - one of:

Crawl chunks: ‘str’, ‘pau’, ‘exec’, ‘str_c’, ‘run’
Turn chunks: ‘tur’, ‘Ltur’, ‘Rtur’

Returns:

AttrDict with:

func: Annotation function (or None for unknown chunks)
required_ks: List of required parameter keys

Example:

>>> result = chunk_func('str')
>>> result.func(dataset)  # Performs crawl annotation
>>> print(result.required_ks)  # ['a', 'sa', 'ba', 'foa', 'fv']

larvaworld.lib.reg.parFunc.dsp_func(range: tuple[int, int]) → Callable[[Any], None]

Create dispersal computation function for a time range.

Factory function that generates a callable to compute agent dispersal (spatial spread) between two time points.

Args:

range: Time range as (start_index, end_index) tuple

Returns:

Callable that accepts a dataset and computes dispersal

Example:

>>> dispersal_fn = dsp_func((0, 100))
>>> dispersal_fn(dataset)  # Computes dispersal from t=0 to t=100

larvaworld.lib.reg.parFunc.tor_func(dur: int) → Callable[[Any], None]

Create tortuosity computation function for a time window.

Factory function that generates a callable to compute path tortuosity (straightness) over a specified duration.

Args:

dur: Duration window for tortuosity calculation (in time steps)

Returns:

Callable that accepts a dataset and computes tortuosity

Example:

>>> tortuosity_fn = tor_func(10)
>>> tortuosity_fn(dataset)  # Computes tortuosity over 10-step windows

larvaworld.lib.reg.parFunc.mean_func(par: str) → Callable[[Any], None]

Create function to compute per-agent mean of a parameter.

Factory function that generates a callable to calculate mean values per agent and store in the endpoint dataset.

Args:

par: Parameter name to compute mean for

Returns:

Callable that accepts a dataset and computes per-agent means

Example:

>>> mean_vel = mean_func('velocity')
>>> mean_vel(dataset)  # Adds 'velocity_mean' to endpoint data

larvaworld.lib.reg.parFunc.std_func(par: str) → Callable[[Any], None]

Create function to compute per-agent standard deviation of a parameter.

Factory function that generates a callable to calculate standard deviation per agent and store in the endpoint dataset.

Args:

par: Parameter name to compute standard deviation for

Returns:

Callable that accepts a dataset and computes per-agent standard deviations

Example:

>>> std_vel = std_func('velocity')
>>> std_vel(dataset)  # Adds 'velocity_std' to endpoint data

larvaworld.lib.reg.parFunc.var_func(par: str) → Callable[[Any], None]

Create function to compute per-agent coefficient of variation.

Factory function that generates a callable to calculate coefficient of variation (mean/std) per agent and store in the endpoint dataset.

Args:

par: Parameter name to compute coefficient of variation for

Returns:

Callable that accepts a dataset and computes per-agent coefficients

Example:

>>> var_vel = var_func('velocity')
>>> var_vel(dataset)  # Adds 'velocity_var' to endpoint data

larvaworld.lib.reg.parFunc.min_func(par: str) → Callable[[Any], None]

Create function to compute per-agent minimum of a parameter.

Factory function that generates a callable to calculate minimum values per agent and store in the endpoint dataset.

Args:

par: Parameter name to compute minimum for

Returns:

Callable that accepts a dataset and computes per-agent minimums

Example:

>>> min_vel = min_func('velocity')
>>> min_vel(dataset)  # Adds 'velocity_min' to endpoint data

larvaworld.lib.reg.parFunc.max_func(par: str) → Callable[[Any], None]

Create function to compute per-agent maximum of a parameter.

Factory function that generates a callable to calculate maximum values per agent and store in the endpoint dataset.

Args:

par: Parameter name to compute maximum for

Returns:

Callable that accepts a dataset and computes per-agent maximums

Example:

>>> max_vel = max_func('velocity')
>>> max_vel(dataset)  # Adds 'velocity_max' to endpoint data

larvaworld.lib.reg.parFunc.fin_func(par: str) → Callable[[Any], None]

Create function to extract final value of a parameter per agent.

Factory function that generates a callable to get the last (final) value per agent and store in the endpoint dataset.

Args:

par: Parameter name to extract final value for

Returns:

Callable that accepts a dataset and extracts final values

Example:

>>> final_pos = fin_func('position')
>>> final_pos(dataset)  # Adds 'position_final' to endpoint data

larvaworld.lib.reg.parFunc.init_func(par: str) → Callable[[Any], None]

Create function to extract initial value of a parameter per agent.

Factory function that generates a callable to get the first (initial) value per agent and store in the endpoint dataset.

Args:

par: Parameter name to extract initial value for

Returns:

Callable that accepts a dataset and extracts initial values

Example:

>>> initial_pos = init_func('position')
>>> initial_pos(dataset)  # Adds 'position_initial' to endpoint data

larvaworld.lib.reg.parFunc.cum_func(par: str) → Callable[[Any], None]

Create function to compute per-agent cumulative sum of a parameter.

Factory function that generates a callable to calculate cumulative (total) sum per agent and store in the endpoint dataset.

Args:

par: Parameter name to compute cumulative sum for

Returns:

Callable that accepts a dataset and computes per-agent cumulative sums

Example:

>>> cum_dist = cum_func('distance')
>>> cum_dist(dataset)  # Adds 'distance_cum' to endpoint data

larvaworld.lib.reg.parFunc.freq_func(par: str) → Callable[[Any], None]

Create function to compute frequency spectrum of a parameter.

Factory function that generates a callable to calculate frequency domain representation (FFT) of a time series parameter.

Args:

par: Parameter name to compute frequency spectrum for

Returns:

Callable that accepts a dataset and computes frequency spectrum

Example:

>>> freq_vel = freq_func('velocity')
>>> freq_vel(dataset)  # Computes FFT of velocity time series

larvaworld.lib.reg.parFunc.tr_func(pc: str) → Callable[[Any], None]

Create function to compute time ratio for a behavioral chunk.

Factory function that generates a callable to calculate the ratio of time spent in a specific chunk relative to total time.

Args:

pc: Chunk name (e.g., ‘pau’ for pause, ‘run’ for run)

Returns:

Callable that accepts a dataset and computes time ratio

Example:

>>> pause_ratio = tr_func('pau')
>>> pause_ratio(dataset)  # Adds 'pau_dur_ratio' to endpoint data

larvaworld.lib.reg.parFunc.unwrap_func(par: str, in_deg: bool) → Callable[[Any], None]

Create function to unwrap angular parameter discontinuities.

Factory function that generates a callable to remove 360° discontinuities from angular time series data.

Args:

par: Angular parameter name to unwrap in_deg: Whether the parameter is in degrees (vs radians)

Returns:

Callable that accepts a dataset and unwraps the angular parameter

Example:

>>> unwrap_orient = unwrap_func('orientation', in_deg=True)
>>> unwrap_orient(dataset)  # Adds 'orientation_unwrap' column

larvaworld.lib.reg.parFunc.dst_func(point: str = '') → Callable[[Any], None]

Create function to compute distance from a reference point.

Factory function that generates a callable to calculate distances from agents to a specified reference point or body segment.

Args:

point: Reference point name (e.g., ‘centroid’, ‘head’).: Empty string uses default reference point.

Returns:

Callable that accepts a dataset and computes distances

Example:

>>> dist_to_head = dst_func('head')
>>> dist_to_head(dataset)  # Computes distances from head point

larvaworld.lib.reg.parFunc.func_v_spatial(p_d: str, p_v: str) → Callable[[Any], None]

Create function to compute velocity from displacement.

Factory function that generates a callable to calculate velocity by dividing displacement by time step.

Args:

p_d: Displacement parameter name (e.g., ‘distance’) p_v: Velocity parameter name to create (e.g., ‘velocity’)

Returns:

Callable that accepts a dataset and computes velocity

Example:

>>> vel_calc = func_v_spatial('linear_displacement', 'lin_velocity')
>>> vel_calc(dataset)  # Adds 'lin_velocity' column