larvaworld.lib.reg.generators

Configuration and Generator classes for higher-order objects in the larvaworld package.

Attributes

gen

Classes

`SimConfiguration`	Base configuration for simulation runs.
`SimConfigurationParams`	Simulation configuration with parameter loading and larva group management.
`FoodConf`	Configuration for food sources and odor landscapes in the arena.
`EnvConf`	Configuration for the simulation's virtual environment.
`LabFormat`	Configuration for lab-specific data import formats.
`ExpConf`	Configuration for experiment simulations.
`ReplayConfGroup`	Population-level configuration for dataset replay.
`ReplayConfUnit`	Individual-level configuration for dataset replay visualization.
`ReplayConf`	Complete configuration for replaying experimental datasets.

Module Contents

larvaworld.lib.reg.generators.gen

class larvaworld.lib.reg.generators.SimConfiguration(runtype: str, **kwargs: Any)

Bases: larvaworld.lib.param.RuntimeOps, larvaworld.lib.param.SimMetricOps, 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')

runtype

property path_to_runtype_data: str

generate_id(runtype: str, exp: str) → str

exp_selector_param(runtype: str) → param.Selector | param.Parameter

class larvaworld.lib.reg.generators.SimConfigurationParams(runtype: str = 'Exp', experiment: str | None = None, parameters: larvaworld.lib.util.AttrDict | None = None, N: int | None = None, modelIDs: list[str] | None = None, groupIDs: list[str] | None = None, sample: str | None = None, **kwargs: Any)

Bases: 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

parameters

class larvaworld.lib.reg.generators.FoodConf

Bases: 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)

source_groups

source_units

food_grid

classmethod 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 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 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 su(id: str = 'Source', grid: Any = None, sg: dict[str, Any] = {}, **kwargs: Any) → FoodConf

classmethod sus(grid: Any = None, sg: dict[str, Any] = {}, **kwargs: Any) → FoodConf

classmethod sg(id: str = 'SourceGroup', grid: Any = None, su: dict[str, Any] = {}, **kwargs: Any) → FoodConf

classmethod sgs(grid: Any = None, su: dict[str, Any] = {}, **kwargs: Any) → FoodConf

classmethod 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

class larvaworld.lib.reg.generators.EnvConf(odorscape: Any = None, **kwargs: Any)

Bases: 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)

arena

food_params

border_list

odorscape

windscape

thermoscape

visualize(**kwargs: Any) → None: Visualize the environment by launching a simulation without agents

classmethod food_params_class() → Any

classmethod arena_class() → Any

classmethod maze(n: int = 15, h: float = 0.1, o: str = 'G', **kwargs: Any) → EnvConf

classmethod game(dim: float = 0.1, x: float = 0.4, y: float = 0.0, o: str = 'G', **kwargs: Any) → EnvConf

classmethod foodNodor_4corners(dim: float = 0.2, o: str = 'D', **kwargs: Any) → EnvConf

classmethod CS_UCS(dim: float = 0.1, o: str = 'G', **kwargs: Any) → EnvConf

classmethod double_patch(dim: float = 0.24, o: str = 'G', **kwargs: Any) → EnvConf

classmethod odor_gradient(dim: tuple[float, float] = (0.1, 0.06), o: str = 'G', c: int = 1, **kwargs: Any) → EnvConf

classmethod dish(xy: float = 0.1, **kwargs: Any) → EnvConf

classmethod rect(xy: float | tuple[float, float] = 0.1, **kwargs: Any) → EnvConf

classmethod scapes(o: Any = None, w: dict | None = None, th: dict | None = None, f: Any = None, bl: dict[str, Any] = {}, **kwargs: Any) → EnvConf

class larvaworld.lib.reg.generators.LabFormat

Bases: 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

labID

tracker

filesystem

env_params

preprocess

property path: str

property raw_folder: str

property processed_folder: str

get_source_dir(parent_dir: str, raw_folder: str | None = None, merged: bool = False) → str | list[str]

get_store_sequence(mode: str = 'semifull') → list[str]

property import_func: Any

import_data_to_dfs(parent_dir: str, raw_folder: str | None = None, merged: bool = False, save_mode: str = 'semifull', **kwargs: Any) → tuple[pandas.DataFrame | None, pandas.DataFrame | None]

build_dataset(step: pandas.DataFrame, end: pandas.DataFrame, parent_dir: str, proc_folder: str | None = None, group_id: str | None = None, id: str | None = None, sample: str | None = None, color: str = 'black', epochs: list[larvaworld.lib.param.Epoch] = [], age: float = 0.0, refID: str | None = None) → larvaworld.lib.process.LarvaDataset

import_dataset(parent_dir: str, raw_folder: str | None = None, merged: bool = False, proc_folder: str | None = None, group_id: str | None = None, id: str | None = None, sample: str | None = None, color: str = 'black', epochs: list[larvaworld.lib.param.Epoch] = [], age: float = 0.0, refID: str | None = None, enrich_conf: larvaworld.lib.util.AttrDict | dict[str, Any] | None = 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.

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.

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

fileslist: List of the absolute filepaths of the data files.
read_sequencelist of strings: The sequence of parameters found in each file
store_sequencelist of strings: The sequence of parameters to store
inv_xboolean: Whether to invert x axis. Defaults to False

Returns

list of pandas.DataFrame

class larvaworld.lib.reg.generators.ExpConf(id: str | None = None, **kwargs: Any)

Bases: 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

env_params

experiment

trials

collections

larva_groups

parameter_dict

enrichment

classmethod imitation_exp(refID: str, mID: str = 'explorer', **kwargs: Any) → ExpConf

property agent_confs: list[Any]

class larvaworld.lib.reg.generators.ReplayConfGroup

Bases: 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')

agent_ids

transposition

track_point

env_params

class larvaworld.lib.reg.generators.ReplayConfUnit

Bases: 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)

close_view

fix_segment

fix_point

class larvaworld.lib.reg.generators.ReplayConf

Bases: ReplayConfGroup, 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)

refID

refDir

time_range

overlap_mode

draw_Nsegs