larvaworld.lib.reg.generators ============================= .. py:module:: larvaworld.lib.reg.generators .. autoapi-nested-parse:: Configuration and Generator classes for higher-order objects in the larvaworld package. Attributes ---------- .. autoapisummary:: larvaworld.lib.reg.generators.gen Classes ------- .. autoapisummary:: larvaworld.lib.reg.generators.SimConfiguration larvaworld.lib.reg.generators.SimConfigurationParams larvaworld.lib.reg.generators.FoodConf larvaworld.lib.reg.generators.EnvConf larvaworld.lib.reg.generators.LabFormat larvaworld.lib.reg.generators.ExpConf larvaworld.lib.reg.generators.ReplayConfGroup larvaworld.lib.reg.generators.ReplayConfUnit larvaworld.lib.reg.generators.ReplayConf Module Contents --------------- .. py:data:: gen .. py:class:: SimConfiguration(runtype: str, **kwargs: Any) Bases: :py:obj:`larvaworld.lib.param.RuntimeOps`, :py:obj:`larvaworld.lib.param.SimMetricOps`, :py:obj:`larvaworld.lib.param.SimOps` Base configuration for simulation runs. Combines runtime, metrics, and simulation operations with automatic ID generation and directory management for different simulation types. Attributes: runtype: Simulation mode (Exp, Batch, Ga, Eval, Replay) experiment: Name of the experiment configuration id: Unique identifier for the simulation run dir: Directory path for simulation output Example: >>> config = SimConfiguration(runtype='Exp', experiment='dish') >>> run_id = config.generate_id('Exp', 'dish') .. py:attribute:: runtype .. py:property:: path_to_runtype_data :type: str .. py:method:: generate_id(runtype: str, exp: str) -> str .. py:method:: exp_selector_param(runtype: str) -> param.Selector | param.Parameter .. py:class:: SimConfigurationParams(runtype: str = 'Exp', experiment: Optional[str] = None, parameters: Optional[larvaworld.lib.util.AttrDict] = None, N: Optional[int] = None, modelIDs: Optional[list[str]] = None, groupIDs: Optional[list[str]] = None, sample: Optional[str] = None, **kwargs: Any) Bases: :py:obj:`SimConfiguration` Simulation configuration with parameter loading and larva group management. Extends SimConfiguration with support for loading experiment parameters from configuration dictionaries and updating larva group compositions. Attributes: parameters: Experiment parameter dictionary (loaded or provided) Example: >>> config = SimConfigurationParams(runtype='Exp', experiment='dish', N=20) >>> params = config.parameters .. py:attribute:: parameters .. py:class:: FoodConf Bases: :py:obj:`larvaworld.lib.param.NestedConf` Configuration for food sources and odor landscapes in the arena. Manages food source groups, individual sources, and optional food grids. Provides factory methods for common arena layouts (patches, corners, etc.). Attributes: source_groups: Dictionary of food/odor source groups source_units: Dictionary of individual food/odor sources food_grid: Optional uniform food grid covering the arena Example: >>> food = FoodConf.double_patch(x=0.06, r=0.025) >>> food = FoodConf.foodNodor_4corners(d=0.05) .. py:attribute:: source_groups .. py:attribute:: source_units .. py:attribute:: food_grid .. py:method:: CS_UCS(grid: Any = None, sg: dict[str, Any] = {}, N: int = 1, x: float = 0.04, colors: list[str] = ['red', 'blue'], o: str = 'G', **kwargs: Any) -> FoodConf :classmethod: .. py:method:: double_patch(grid: Any = None, sg: dict[str, Any] = {}, type: str = 'standard', q: float = 1.0, c: str = 'green', x: float = 0.06, r: float = 0.025, a: float = 0.1, o: str = 'G', **kwargs: Any) -> FoodConf :classmethod: .. py:method:: patch(grid: Any = None, sg: dict[str, Any] = {}, id: str = 'Patch', type: str = 'standard', q: float = 1.0, c: str = 'green', r: float = 0.01, a: float = 0.1, **kwargs: Any) -> FoodConf :classmethod: .. py:method:: su(id: str = 'Source', grid: Any = None, sg: dict[str, Any] = {}, **kwargs: Any) -> FoodConf :classmethod: .. py:method:: sus(grid: Any = None, sg: dict[str, Any] = {}, **kwargs: Any) -> FoodConf :classmethod: .. py:method:: sg(id: str = 'SourceGroup', grid: Any = None, su: dict[str, Any] = {}, **kwargs: Any) -> FoodConf :classmethod: .. py:method:: sgs(grid: Any = None, su: dict[str, Any] = {}, **kwargs: Any) -> FoodConf :classmethod: .. py:method:: foodNodor_4corners(d: float = 0.05, colors: list[str] = ['blue', 'red', 'green', 'magenta'], grid: Any = None, sg: dict[str, Any] = {}, o: str = 'D', **kwargs: Any) -> FoodConf :classmethod: .. py:class:: EnvConf(odorscape: Any = None, **kwargs: Any) Bases: :py:obj:`larvaworld.lib.param.NestedConf` Configuration for the simulation's virtual environment. Defines arena geometry, food sources, obstacles, and sensory landscapes (odor, wind, thermal) for the simulated world. Attributes: arena: Arena configuration (shape, dimensions, torus) food_params: Food and odor source configuration border_list: Dictionary of obstacle borders in the arena odorscape: Optional odor landscape (Gaussian/Analytical/Diffusion) windscape: Optional wind landscape thermoscape: Optional thermal landscape Example: >>> env = EnvConf.dish(xy=0.1) >>> env = EnvConf.maze(n=15, h=0.1) .. py:attribute:: arena .. py:attribute:: food_params .. py:attribute:: border_list .. py:attribute:: odorscape .. py:attribute:: windscape .. py:attribute:: thermoscape .. py:method:: visualize(**kwargs: Any) -> None Visualize the environment by launching a simulation without agents .. py:method:: food_params_class() -> Any :classmethod: .. py:method:: arena_class() -> Any :classmethod: .. py:method:: maze(n: int = 15, h: float = 0.1, o: str = 'G', **kwargs: Any) -> EnvConf :classmethod: .. py:method:: game(dim: float = 0.1, x: float = 0.4, y: float = 0.0, o: str = 'G', **kwargs: Any) -> EnvConf :classmethod: .. py:method:: foodNodor_4corners(dim: float = 0.2, o: str = 'D', **kwargs: Any) -> EnvConf :classmethod: .. py:method:: CS_UCS(dim: float = 0.1, o: str = 'G', **kwargs: Any) -> EnvConf :classmethod: .. py:method:: double_patch(dim: float = 0.24, o: str = 'G', **kwargs: Any) -> EnvConf :classmethod: .. py:method:: odor_gradient(dim: tuple[float, float] = (0.1, 0.06), o: str = 'G', c: int = 1, **kwargs: Any) -> EnvConf :classmethod: .. py:method:: dish(xy: float = 0.1, **kwargs: Any) -> EnvConf :classmethod: .. py:method:: rect(xy: float | tuple[float, float] = 0.1, **kwargs: Any) -> EnvConf :classmethod: .. py:method:: scapes(o: Any = None, w: Optional[dict] = None, th: Optional[dict] = None, f: Any = None, bl: dict[str, Any] = {}, **kwargs: Any) -> EnvConf :classmethod: .. py:class:: LabFormat Bases: :py:obj:`larvaworld.lib.param.NestedConf` Configuration for lab-specific data import formats. Defines how experimental data from different labs is structured, tracked, and imported into the larvaworld system. Attributes: labID: Identifier of the laboratory tracker: Dataset tracking metadata filesystem: Lab-specific file structure and naming conventions env_params: Environment configuration for imported data preprocess: Preprocessing steps for raw data Example: >>> lab = LabFormat(labID='SchleyerGroup') >>> raw_path = lab.raw_folder .. py:attribute:: labID .. py:attribute:: tracker .. py:attribute:: filesystem .. py:attribute:: env_params .. py:attribute:: preprocess .. py:property:: path :type: str .. py:property:: raw_folder :type: str .. py:property:: processed_folder :type: str .. py:method:: get_source_dir(parent_dir: str, raw_folder: Optional[str] = None, merged: bool = False) -> str | list[str] .. py:method:: get_store_sequence(mode: str = 'semifull') -> list[str] .. py:property:: import_func :type: Any .. py:method:: import_data_to_dfs(parent_dir: str, raw_folder: Optional[str] = None, merged: bool = False, save_mode: str = 'semifull', **kwargs: Any) -> tuple[pandas.DataFrame | None, pandas.DataFrame | None] .. py:method:: build_dataset(step: pandas.DataFrame, end: pandas.DataFrame, parent_dir: str, proc_folder: Optional[str] = None, group_id: Optional[str] = None, id: Optional[str] = None, sample: Optional[str] = None, color: str = 'black', epochs: list[larvaworld.lib.param.Epoch] = [], age: float = 0.0, refID: Optional[str] = None) -> larvaworld.lib.process.LarvaDataset .. py:method:: import_dataset(parent_dir: str, raw_folder: Optional[str] = None, merged: bool = False, proc_folder: Optional[str] = None, group_id: Optional[str] = None, id: Optional[str] = None, sample: Optional[str] = None, color: str = 'black', epochs: list[larvaworld.lib.param.Epoch] = [], age: float = 0.0, refID: Optional[str] = None, enrich_conf: Optional[larvaworld.lib.util.AttrDict | dict[str, Any]] = None, save_dataset: bool = True, **kwargs: Any) -> larvaworld.lib.process.dataset.LarvaDataset | None Imports a single experimental dataset defined by their ID from a source folder. Parameters ---------- parent_dir: string The parent directory where the raw files are located. raw_folder: string, optional The directory where the raw files are located. If not provided it is set as the subfolder 'raw' under the lab-specific group directory. merged: boolean Whether to merge all raw datasets in the source folder in a single imported dataset. Defaults to False. proc_folder: string, optional The directory where the imported dataset will be placed. If not provided it is set as the subfolder 'processed' under the lab-specific group directory. group_id: string, optional The group ID of the dataset to be imported. If not provided it is set as the parent_dir argument. id: string, optional The ID under which to store the imported dataset. If not provided it is set by default. sample: string, optional The reference ID of the reference dataset from which the current is sampled. color: string The default color of the new dataset. Defaults to 'black'. epochs: dict Any discrete rearing epochs during the larvagroup's life history. Defaults to '{}'. age: float The post-hatch age of the larvae in hours. Defaults to '0.0'. refID: string, optional The reference IDs under which to store the imported dataset as reference dataset. If not provided the dataset is not stored in the reference database. save_dataset: boolean Whether to store the imported dataset to disc. Defaults to True. enrich_conf: dict, optional The configuration for enriching the imported dataset with secondary parameters. **kwargs: keyword arguments Additional keyword arguments to be passed to the lab_specific build-function. Returns ------- lib.process.dataset.LarvaDataset The imported dataset in the common larvaworld format. .. py:method:: import_datasets(source_ids: list[str], ids: Optional[list[str]] = None, colors: Optional[list[str]] = None, refIDs: Optional[list[Optional[str]]] = None, **kwargs: Any) -> list[larvaworld.lib.process.dataset.LarvaDataset | None] Imports multiple experimental datasets defined by their IDs. Parameters ---------- source_ids: list of strings The IDs of the datasets to be imported as appearing in the source files. ids: list of strings, optional The IDs under which to store the datasets to be imported. The source_ids are used if not provided. refIDs: list of strings, optional The reference IDs under which to store the imported datasets as reference datasets. If not provided the datasets are not stored in the reference database. colors: list of strings, optional The colors of the datasets to be imported. Randomly selected if not provided. **kwargs: keyword arguments Additional keyword arguments to be passed to the import_dataset function. Returns ------- list of lib.process.dataset.LarvaDataset The imported datasets in the common larvaworld format. .. py:method:: read_timeseries_from_raw_files_per_larva(files: list[str], read_sequence: list[str], store_sequence: list[str], inv_x: bool = False) -> list[pandas.DataFrame] Reads timeseries data stored in txt files of the lab-specific Jovanic format and returns them as a pd.Dataframe. Parameters ---------- files : list List of the absolute filepaths of the data files. read_sequence : list of strings The sequence of parameters found in each file store_sequence : list of strings The sequence of parameters to store inv_x : boolean Whether to invert x axis. Defaults to False Returns ------- list of pandas.DataFrame .. py:class:: ExpConf(id: Optional[str] = None, **kwargs: Any) Bases: :py:obj:`larvaworld.lib.param.SimOps` Configuration for experiment simulations. Defines complete experiment setup including environment, larva groups, temporal epochs, data collection, and post-processing enrichment. Attributes: env_params: Virtual environment configuration experiment: Experiment ID selector trials: Temporal epochs defining experiment phases collections: List of data types to collect larva_groups: Dictionary of larva group configurations parameter_dict: Parameters passed to all agents enrichment: Post-simulation data enrichment configuration Example: >>> exp = ExpConf.imitation_exp(refID='SchleyerGroup_dish_0') >>> agents = exp.agent_confs .. py:attribute:: env_params .. py:attribute:: experiment .. py:attribute:: trials .. py:attribute:: collections .. py:attribute:: larva_groups .. py:attribute:: parameter_dict .. py:attribute:: enrichment .. py:method:: imitation_exp(refID: str, mID: str = 'explorer', **kwargs: Any) -> ExpConf :classmethod: .. py:property:: agent_confs :type: list[Any] .. py:class:: ReplayConfGroup Bases: :py:obj:`larvaworld.lib.param.NestedConf` Population-level configuration for dataset replay. Controls group-wide replay settings including agent selection, spatial transposition, and environment configuration. Attributes: agent_ids: List of agent indices to display (empty = all agents) transposition: Coordinate transformation ('origin', 'arena', 'center') track_point: Midline point index for position tracking env_params: Environment configuration selector Example: >>> replay = ReplayConfGroup(agent_ids=[0,1,2], transposition='center') .. py:attribute:: agent_ids .. py:attribute:: transposition .. py:attribute:: track_point .. py:attribute:: env_params .. py:class:: ReplayConfUnit Bases: :py:obj:`larvaworld.lib.param.NestedConf` Individual-level configuration for dataset replay visualization. Controls single-larva view settings including camera fixation and close-up visualization modes. Attributes: close_view: Whether to show close-range zoomed view fix_segment: Optional body segment to fixate (rear/front) fix_point: Optional midline point to fixate at screen center Example: >>> replay = ReplayConfUnit(close_view=True, fix_point=6) .. py:attribute:: close_view .. py:attribute:: fix_segment .. py:attribute:: fix_point .. py:class:: ReplayConf Bases: :py:obj:`ReplayConfGroup`, :py:obj:`ReplayConfUnit` Complete configuration for replaying experimental datasets. Combines group and individual replay settings with reference dataset selection and temporal/spatial filtering options. Attributes: refID: Reference dataset ID selector refDir: Optional direct path to dataset directory time_range: Optional temporal slice to replay (start, end) in seconds overlap_mode: Whether to draw trajectory overlap image draw_Nsegs: Optional number of body segments to simplify to Example: >>> replay = ReplayConf(refID='dish_0', time_range=(0, 60)) >>> replay = ReplayConf(refDir='path/to/data', overlap_mode=True) .. py:attribute:: refID .. py:attribute:: refDir .. py:attribute:: time_range .. py:attribute:: overlap_mode .. py:attribute:: draw_Nsegs