larvaworld.lib.reg.distro
=========================

.. py:module:: larvaworld.lib.reg.distro

.. autoapi-nested-parse::

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



Attributes
----------

.. autoapisummary::

   larvaworld.lib.reg.distro.distroDB


Classes
-------

.. autoapisummary::

   larvaworld.lib.reg.distro.BoutGenerator


Functions
---------

.. autoapisummary::

   larvaworld.lib.reg.distro.get_dist
   larvaworld.lib.reg.distro.fit_bout_distros


Module Contents
---------------

.. py:data:: distroDB
   :type:  larvaworld.lib.util.AttrDict

.. py:function:: 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)


.. py:function:: fit_bout_distros(x0: numpy.ndarray, xmin: Optional[float] = None, xmax: Optional[float] = 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']


.. py:class:: 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


   .. py:attribute:: name


   .. py:attribute:: dt


   .. py:attribute:: range


   .. py:attribute:: args


   .. py:attribute:: dist


   .. py:method:: sample(size: int = 1)


   .. py:method:: build(**kwargs: Any)


   .. py:method:: get(x: numpy.ndarray, mode: str)