larvaworld.lib.reg.data_aux
===========================

.. py:module:: larvaworld.lib.reg.data_aux

.. autoapi-nested-parse::

   Larvaworld parameter class and associated methods



Attributes
----------

.. autoapisummary::

   larvaworld.lib.reg.data_aux.SAMPLING_PARS


Functions
---------

.. autoapisummary::

   larvaworld.lib.reg.data_aux.get_LarvaworldParam
   larvaworld.lib.reg.data_aux.sample_ps
   larvaworld.lib.reg.data_aux.prepare_LarvaworldParam
   larvaworld.lib.reg.data_aux.build_LarvaworldParam


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

.. py:function:: get_LarvaworldParam(vparfunc: Any, v0: Any = None, dv: Any = None, **kws: Any) -> LarvaworldParam

   Create a LarvaworldParam instance with custom parameter function.

   Dynamically creates a LarvaworldParam subclass with specified parameter
   function and default values, then instantiates it.

   Args:
       vparfunc: Parameter function (e.g., param.Number, param.Range)
       v0: Default value for parameter
       dv: Delta/range value for parameter
       **kws: Additional keyword arguments for LarvaworldParam

   Returns:
       Configured LarvaworldParam instance

   Example:
       >>> par = get_LarvaworldParam(param.Number, v0=0.5, doc="Speed parameter")


.. py:data:: SAMPLING_PARS
   :type:  larvaworld.lib.util.bidict

.. py:function:: sample_ps(ps: list[str], e: Optional[Any] = None) -> list[str]

   Filter parameters to those that exist in SAMPLING_PARS mapping.

   Gets parameters from list that exist in the inverse SAMPLING_PARS dictionary
   (i.e., parameters that have configuration paths defined). Optionally filters
   to parameters that also exist in endpoint DataFrame.

   Args:
       ps: List of parameter names to filter
       e: Endpoint DataFrame to further filter parameters

   Returns:
       list: List of parameters filtered to exist in the default SAMPLING_PARS dictionary and potentially filtered to exist in e

   Example:
       >>> sample_ps(['length', 'velocity', 'unknown_param'])
       ['length', 'velocity']  # Only those in SAMPLING_PARS


.. py:function:: prepare_LarvaworldParam(p: str, k: Optional[str] = None, dtype: Any = float, d: Optional[str] = None, disp: Optional[str] = None, sym: Optional[str] = None, codename: Optional[str] = None, lab: Optional[str] = None, doc: Optional[str] = None, flatname: Optional[str] = None, required_ks: list[str] = [], u: Any = reg.units.dimensionless, v0: Any = None, v: Any = None, lim: Any = None, dv: Any = None, vs: Any = None, vfunc: Any = None, vparfunc: Any = None, func: Any = None, **kwargs: Any) -> larvaworld.lib.util.AttrDict

   Format parameter attributes dictionary for LarvaworldParam creation.

   Prepares a comprehensive dictionary of parameter attributes including
   display properties, units, bounds, functions, and documentation. Handles
   defaults and infers missing attributes from provided values.

   Args:
       p: Primary parameter name
       k: Parameter key identifier. Defaults to d if not provided
       dtype: Data type (int, float, list, tuple, etc.). Defaults to float
       d: Code-related name. Defaults to p if not provided
       disp: Display name for UI. Defaults to d if not provided
       sym: LaTeX symbol representation. Defaults to k if not provided
       codename: Internal code name. Defaults to p if not provided
       lab: Label for plots. Auto-generated if not provided
       doc: Documentation string for parameter
       flatname: Flattened configuration path. Looked up in SAMPLING_PARS if not provided
       required_ks: List of required parameter keys that must be present
       u: Physical unit from reg.units. Defaults to dimensionless
       v0: Initial/default value. Uses v if not provided
       v: Current parameter value. Used as v0 if v0 not provided
       lim: Parameter bounds as (min, max) tuple
       dv: Step/delta value for parameter. Auto-inferred from dtype if not provided
       vs: Value set for Selector parameters (list of valid options)
       vfunc: Value function for parameter validation
       vparfunc: param.Parameterized function type (Number, Range, Selector, etc.)
       func: Computing function for derived parameters
       **kwargs: Additional parameter attributes

   Returns:
       util.AttrDict: Dictionary of formatted attributes for creating a LarvaworldParam instance

   Example:
       >>> attrs = prepare_LarvaworldParam('speed', k='v', dtype=float, v0=1.0, lim=(0, 10))
       >>> attrs['k']
       'v'


.. py:function:: build_LarvaworldParam(p: str, **kwargs: Any) -> LarvaworldParam

   Constructs a Larvaworld parameter object.

   This function prepares the input attributes using the `prepare_LarvaworldParam` function
   and then generates the Larvaworld parameter object using the `get_LarvaworldParam` function.

   Args:
       p: The primary parameter required for building the Larvaworld parameter object.
       **kwargs: Additional keyword arguments that are passed to the `prepare_LarvaworldParam` function.

   Returns:
       The constructed Larvaworld parameter object.