larvaworld.lib.param.nested_parameter_group
===========================================

.. py:module:: larvaworld.lib.param.nested_parameter_group


Classes
-------

.. autoapisummary::

   larvaworld.lib.param.nested_parameter_group.NestedConf


Functions
---------

.. autoapisummary::

   larvaworld.lib.param.nested_parameter_group.class_generator
   larvaworld.lib.param.nested_parameter_group.expand_kws_shortcuts
   larvaworld.lib.param.nested_parameter_group.class_defaults
   larvaworld.lib.param.nested_parameter_group.class_objs


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

.. py:class:: NestedConf(**kwargs: Any)

   Bases: :py:obj:`param.Parameterized`


   Base class for managing nested configuration parameters.

   Extends param.Parameterized with automatic nested object initialization
   from dict configs, supporting ClassAttr and ClassDict automatic instantiation.
   Provides methods for config export, validation, and parameter introspection.

   Attributes:
       nestedConf: Nested configuration dict (property)
       param_keys: List of parameter keys excluding 'name' (property)

   Args:
       **kwargs: Configuration keyword arguments. ClassAttr and ClassDict
                 parameters are auto-instantiated from dict configs.

   Example:
       >>> class MyConfig(NestedConf):
       ...     value = param.Number(default=1.0)
       ...     nested = ClassAttr(class_=SomeClass)
       >>> conf = MyConfig(value=2.0, nested={'param': 10})
       >>> conf.nested  # SomeClass instance (auto-instantiated)


   .. py:property:: nestedConf
      :type: larvaworld.lib.util.AttrDict


      Generates a nested configuration dictionary.

      :return: A nested configuration dictionary.



   .. py:method:: entry(id: Optional[str] = None) -> Dict[str, Any]

      Creates an entry in the configuration.

      :param id: The identifier for the entry.
      :return: A dictionary containing the configuration entry.



   .. py:property:: param_keys
      :type: larvaworld.lib.util.SuperList


      Retrieves a list of parameter keys.

      :return: A list of parameter keys excluding 'name'.



   .. py:method:: params_missing(d: Dict[str, Any]) -> larvaworld.lib.util.SuperList

      Checks for missing parameters in the configuration.

      :param d: The configuration dictionary to compare against.
      :return: A list of missing parameter keys.



.. py:function:: class_generator(A0: Any, mode: str = 'Unit')

   Generate parameterized class with distribution and shortcut support.

   Factory function creating NestedConf subclass with automatic
   distribution initialization, keyword shortcuts, and entry generation.

   Args:
       A0: Base class to extend
       mode: Generation mode (default: 'Unit')

   Returns:
       Generated class with enhanced initialization

   Example:
       >>> MyClass = class_generator(BaseClass, mode='Group')


.. py:function:: expand_kws_shortcuts(kwargs: Dict[str, Any]) -> Dict[str, Any]

   Expand keyword argument shortcuts to full parameter names.

   Converts abbreviated configuration keys to full names:
   - 'life' → 'life_history' (age, epochs)
   - 'o' → 'odor' (id, intensity, spread)
   - 'sub' → 'substrate' (quality, type)

   Args:
       kwargs: Configuration dict with potential shortcuts

   Returns:
       Expanded configuration dict with full parameter names

   Example:
       >>> kws = {'life': [0, 10], 'o': ['odorA', 0.5, 2.0]}
       >>> expand_kws_shortcuts(kws)
       >>> # {'life_history': {'age': 0, 'epochs': 10}, 'odor': {...}}


.. py:function:: class_defaults(A: Any, excluded: Sequence[Any] = [], included: Dict[str, Any] = {}, **kwargs: Any) -> larvaworld.lib.util.AttrDict

   Generate default configuration for class with exclusions/inclusions.

   Creates nested config dict from class, optionally excluding parameters
   from other classes and including/overriding specific values.

   Args:
       A: Target class to generate defaults for
       excluded: Classes/keys whose parameters to exclude (default: [])
       included: Dict of parameters to include/override (default: {})
       **kwargs: Additional parameters to update in existing keys

   Returns:
       AttrDict with filtered and merged default configuration

   Example:
       >>> defaults = class_defaults(MyClass, excluded=[BaseClass], value=10)


.. py:function:: class_objs(A: Any, excluded: Sequence[Any] = []) -> larvaworld.lib.util.AttrDict

   Get parameter objects from class with optional exclusions.

   Retrieves param objects dict from class, optionally filtering out
   parameters from excluded classes or by explicit key names.

   Args:
       A: Target class to get parameter objects from
       excluded: Classes or parameter keys to exclude (default: [])

   Returns:
       AttrDict of parameter name → parameter object mappings

   Example:
       >>> objs = class_objs(MyClass, excluded=[BaseClass, 'internal_param'])
       >>> objs.keys()  # Only MyClass-specific params