larvaworld.lib.reg.distro

Distribution database, registry and associated methods. This modules provides classes and methods for managing and generating distributions.

Attributes

distroDB

Classes

BoutGenerator

Generator for behavioral bout durations from statistical distributions.

Functions

get_dist(→ dict | tuple)

Retrieve a distribution from the database.

fit_bout_distros(→ larvaworld.lib.util.AttrDict)

Fit various distributions to data and evaluate goodness of fit.

Module Contents

larvaworld.lib.reg.distro.distroDB: larvaworld.lib.util.AttrDict
larvaworld.lib.reg.distro.get_dist(k: str, k0: str = 'intermitter', v: Any = None, return_tabrows: bool = False, return_all: bool = False) → dict | tuple

Retrieve a distribution from the database.

Args:

k: Key to identify the distribution k0: Module key for the distribution. Defaults to ‘intermitter’ v: An object containing distribution details. Defaults to None return_tabrows: If True, returns table rows. Defaults to False return_all: If True, returns all distribution details. Defaults to False

Returns:

dict: A dictionary containing distribution details if return_tabrows and return_all are False. tuple: Two lists of table rows if return_tabrows is True. tuple: Three dictionaries containing distribution details if return_all is True.

Example:
>>> dist_info = get_dist('pause_dist', k0='intermitter')
>>> table_rows = get_dist('pause_dist', return_tabrows=True)
larvaworld.lib.reg.distro.fit_bout_distros(x0: numpy.ndarray, xmin: float | None = None, xmax: float | None = None, discrete: bool = False, xmid: float = np.nan, overlap: float = 0.0, Nbins: int = 64, print_fits: bool = False, bout: str = 'pause', combine: bool = True, fit_by: str = 'pdf', eval_func_id: str = 'KS2') → larvaworld.lib.util.AttrDict

Fit various distributions to data and evaluate goodness of fit.

Fits multiple distribution types (powerlaw, exponential, lognormal, lognormal-powerlaw, levy, normal, uniform) to the given data and evaluates their goodness of fit using the specified evaluation function.

Args:

x0: The data to fit the distributions to xmin: Minimum value to consider for fitting. If None, set to minimum of x0 xmax: Maximum value to consider for fitting. If None, set to maximum of x0 discrete: Whether the data is discrete. Defaults to False xmid: Midpoint for lognormal-powerlaw distribution. If NaN, determined automatically overlap: Overlap parameter for lognormal-powerlaw distribution. Defaults to 0.0 Nbins: Number of bins to use for density computation. Defaults to 64 print_fits: Whether to print the fit results. Defaults to False bout: Label for the bout type. Defaults to ‘pause’ combine: Whether to combine distributions. Defaults to True fit_by: Criterion to fit by (‘pdf’ or ‘cdf’). Defaults to ‘pdf’ eval_func_id: Evaluation function identifier (‘MSE’, ‘KS’, ‘KS2’). Defaults to ‘KS2’

Returns:
util.AttrDict: Dictionary containing fit results, including:

  • values: Computed density values

  • pdfs: Probability density functions of the fitted distributions

  • cdfs: Cumulative density functions of the fitted distributions

  • Ks: Goodness of fit values

  • idx_Kmax: Index of the best fitting distribution

  • res: Rounded fit parameters

  • best: Dictionary of the best fitting distribution parameters

  • fits: Dictionary of all fit parameters

Note:

This function fits several distributions (powerlaw, exponential, lognormal, lognormal-powerlaw, levy, normal, uniform) to the given data and evaluates their goodness of fit using the specified evaluation function.

Example:
>>> data = np.random.exponential(2.0, 1000)
>>> results = fit_bout_distros(data, xmin=0.1, xmax=10.0, bout='pause')
>>> best_fit = results['best']
class larvaworld.lib.reg.distro.BoutGenerator(name: str, range: tuple[float, float], dt: float, **kwargs: Any)

Generator for behavioral bout durations from statistical distributions.

Creates random bout durations (pause, run, stridechain) based on specified distribution types from the distribution database. Supports powerlaw, exponential, lognormal, levy, and other distributions.

Attributes:

name: Distribution name from distroDB dt: Time step for converting to real time units range: Valid range as (xmin, xmax) tuple args: Distribution-specific arguments dist: Built scipy.stats distribution object

Example:
>>> gen = BoutGenerator('exponential', range=(0.1, 10.0), dt=0.1, beta=0.5)
>>> duration = gen.sample()  # Single bout duration
>>> durations = gen.sample(size=100)  # 100 bout durations
name
dt
range
args
dist
sample(size: int = 1)
build(**kwargs: Any)
get(x: numpy.ndarray, mode: str)