larvaworld.lib.reg.larvagroup
=============================

.. py:module:: larvaworld.lib.reg.larvagroup

.. autoapi-nested-parse::

   Configuration and Generator classes for virtual larva groups.



Classes
-------

.. autoapisummary::

   larvaworld.lib.reg.larvagroup.LarvaGroupMutator
   larvaworld.lib.reg.larvagroup.LarvaGroup


Functions
---------

.. autoapisummary::

   larvaworld.lib.reg.larvagroup.update_larva_groups
   larvaworld.lib.reg.larvagroup.GTRvsS


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

.. py:function:: update_larva_groups(lgs: larvaworld.lib.util.AttrDict, **kwargs: Any) -> larvaworld.lib.util.AttrDict

   Modifies the experiment's configuration larvagroups.

   Args:
       lgs (dict): The existing larvagroups in the experiment configuration.
       N (int):: Overwrite the number of agents per larva group.
       models (list): Overwrite the larva models used in the experiment. If not None, a larva group per model ID will be simulated.
       groupIDs (list): The displayed IDs of the groups. If None, the model IDs (mIDs) are used.
       sample: The reference dataset.

   Returns:
       The experiment's configuration larvagroups.



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

   Bases: :py:obj:`larvaworld.lib.param.NestedConf`


   Configuration for generating multiple larva groups from model IDs.

   Utility class for creating multiple larva groups by specifying
   model IDs, group IDs, and number of agents per group.

   Attributes:
       modelIDs: List of model IDs to instantiate
       groupIDs: Optional custom IDs for the groups
       N: Number of agents per group

   Example:
       >>> mutator = LarvaGroupMutator(modelIDs=['rover', 'sitter'], N=10)


   .. py:attribute:: modelIDs


   .. py:attribute:: groupIDs


   .. py:attribute:: N


.. py:class:: LarvaGroup(model: Optional[str | dict] = None, group_id: Optional[str] = None, **kwargs: Any)

   Bases: :py:obj:`larvaworld.lib.param.NestedConf`


   Configuration for a group of larvae with shared properties.

   Defines a collection of larvae sharing the same behavioral model,
   spatial distribution, life history, and optional reference dataset.

   Attributes:
       group_id: Unique identifier for the group
       model: Behavioral model ID or configuration dict
       color: Display color for the group
       odor: Odor signature of the agents
       distribution: Spatial distribution configuration
       life_history: Life history and energetics configuration
       sample: Optional reference dataset to sample from
       imitation: Whether to imitate reference dataset trajectories

   Example:
       >>> group = LarvaGroup(model='rover', group_id='rovers', N=20)
       >>> agents = group(parameter_dict={})


   .. py:attribute:: group_id


   .. py:attribute:: model


   .. py:attribute:: color


   .. py:attribute:: odor


   .. py:attribute:: distribution


   .. py:attribute:: life_history


   .. py:attribute:: sample


   .. py:attribute:: imitation


   .. py:method:: entry(expand: bool = False, as_entry: bool = True) -> larvaworld.lib.util.AttrDict


   .. py:property:: expanded_model
      :type: dict



   .. py:method:: generate_agent_attrs(parameter_dict: dict[str, Any] = {}) -> tuple[list[str], list, list, list]


   .. py:method:: generate_agent_confs(ids: list[str], ps: list, ors: list, all_pars: list[dict[str, Any]]) -> list[dict]


   .. py:method:: new_group(N: Optional[int] = None, model: Optional[str] = None, group_id: Optional[str] = None, color: Optional[str] = None, **kwargs: Any) -> LarvaGroup


   .. py:method:: new_groups(as_dict: bool = False, **kwargs: Any) -> larvaworld.lib.util.ItemList | larvaworld.lib.util.AttrDict


.. py:function:: GTRvsS(N: int = 1, age: float = 72.0, q: float = 1.0, h_starved: float = 0.0, substrate_type: str = 'standard', expand: bool = False) -> larvaworld.lib.util.AttrDict

   Create two larva-groups, 'rover' and 'sitter', based on the respective larva-models, with defined life-history to be used in simulations involving energetics.

   Args:
   - N (int): The number of agents in each group.
   - age (float): The age of the larvae in hours.
   - q (float): The rearing quality of the larvae.
   - h_starved (float): The hours the larvae have been starved just before their current age.
   - substrate_type (str): The type of the rearing substrate.
   - expand (bool): Whether to expand the model configuration.

   Returns:
   - dict: A dictionary of the larva-groups.