larvaworld.lib.reg.parFunc ========================== .. py:module:: larvaworld.lib.reg.parFunc .. autoapi-nested-parse:: Parameter-computing functions. Contains functions that compute/derive higher-order parameters from the existing ones in the dataset. Functions --------- .. autoapisummary:: larvaworld.lib.reg.parFunc.track_par_func larvaworld.lib.reg.parFunc.chunk_func larvaworld.lib.reg.parFunc.dsp_func larvaworld.lib.reg.parFunc.tor_func larvaworld.lib.reg.parFunc.mean_func larvaworld.lib.reg.parFunc.std_func larvaworld.lib.reg.parFunc.var_func larvaworld.lib.reg.parFunc.min_func larvaworld.lib.reg.parFunc.max_func larvaworld.lib.reg.parFunc.fin_func larvaworld.lib.reg.parFunc.init_func larvaworld.lib.reg.parFunc.cum_func larvaworld.lib.reg.parFunc.freq_func larvaworld.lib.reg.parFunc.tr_func larvaworld.lib.reg.parFunc.unwrap_func larvaworld.lib.reg.parFunc.dst_func larvaworld.lib.reg.parFunc.func_v_spatial Module Contents --------------- .. py:function:: 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 .. py:function:: 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'] .. py:function:: 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 .. py:function:: 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 .. py:function:: 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 .. py:function:: 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 .. py:function:: 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 .. py:function:: 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 .. py:function:: 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 .. py:function:: 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 .. py:function:: 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 .. py:function:: 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 .. py:function:: 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 .. py:function:: 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 .. py:function:: 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 .. py:function:: 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 .. py:function:: 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