larvaworld.lib.process.evaluation

Methods for dataset evaluation/comparison

Classes

`Evaluation`	Configuration for dataset evaluation against reference data.
`DataEvaluation`	Data evaluation with normalization and multi-mode comparison.

Functions

`eval_end_fast`(→ dict)	Fast evaluation of endpoint data against reference.
`eval_distro_fast`(→ dict)	Fast evaluation of step/distribution data against reference.
`eval_fast`(→ larvaworld.lib.util.AttrDict)	Fast evaluation of datasets against reference data.
`RSS`(→ float)	Root sum of squares (normalized RMSE).
`RSS_dic`(→ float)	Calculate RSS for pooled cycle curves between datasets.
`eval_RSS`(→ dict)	Evaluate RSS metrics for multiple datasets.
`col_df`(→ Any)	Create DataFrame for coloring evaluation metrics by category.
`get_target_data`(→ larvaworld.lib.util.AttrDict)	Extract target data from reference dataset for evaluation.
`arrange_evaluation`(→ Dict[str, Any])	Arrange evaluation data into categorized color DataFrames.

Module Contents

larvaworld.lib.process.evaluation.eval_end_fast(ee: larvaworld.lib.param.EndpointDataFrame, e_data: pandas.DataFrame, e_sym: Dict[str, str], mode: str = 'pooled') → dict

Fast evaluation of endpoint data against reference.

Compares endpoint metrics using Kolmogorov-Smirnov test (pooled mode) or RMSE (1:1 mode) for statistical comparison.

Args:

ee: Endpoint DataFrame with simulation results. e_data: Reference endpoint DataFrame. e_sym: Dict mapping parameter names to display symbols. mode: ‘pooled’ (KS test) or ‘1:1’ (RMSE).

Returns:

Dict with evaluation scores per symbol.

Example:

>>> scores = eval_end_fast(
...     ee=sim_endpoint,
...     e_data=ref_endpoint,
...     e_sym={'cum_d': 'distance'},
...     mode='pooled'
... )

larvaworld.lib.process.evaluation.eval_distro_fast(ss: larvaworld.lib.param.StepDataFrame, s_data: pandas.DataFrame, s_sym: Dict[str, str], mode: str = 'pooled', min_size: int = 10) → dict

Fast evaluation of step/distribution data against reference.

Compares step-wise parameter distributions using Kolmogorov-Smirnov tests with different comparison modes.

Args:

ss: Step DataFrame with simulation timeseries data. s_data: Reference step DataFrame. s_sym: Dict mapping parameter names to display symbols. mode: ‘pooled’, ‘1:1’, or ‘1:pooled’ comparison mode. min_size: Minimum sample size for valid comparison.

Returns:

Dict with evaluation scores (structure depends on mode).

Example:

>>> scores = eval_distro_fast(
...     ss=sim_step,
...     s_data=ref_step,
...     s_sym={'v': 'velocity'},
...     mode='pooled',
...     min_size=20
... )

larvaworld.lib.process.evaluation.eval_fast(datasets: List[larvaworld.lib.process.dataset.LarvaDataset], data: larvaworld.lib.util.AttrDict, symbols: larvaworld.lib.util.AttrDict, mode='pooled', min_size=20) → larvaworld.lib.util.AttrDict

Fast evaluation of datasets against reference data.

Combines endpoint and distribution evaluations using Kolmogorov-Smirnov tests for comprehensive statistical comparison.

Args:

datasets: List of LarvaDataset instances to evaluate. data: AttrDict with ‘end’ and ‘distro’ reference DataFrames. symbols: AttrDict with ‘end’ and ‘distro’ parameter symbols. mode: Evaluation mode (‘pooled’, ‘1:1’, or ‘1:pooled’). min_size: Minimum sample size for valid comparison.

Returns:

AttrDict with evaluation results per dataset.

Example:

>>> results = eval_fast(
...     datasets=[d1, d2],
...     data=AttrDict(end=ref_end, distro=ref_distro),
...     symbols=AttrDict(end={'cum_d': 'dist'}, distro={'v': 'vel'})
... )

larvaworld.lib.process.evaluation.RSS(vs0: numpy.array, vs: numpy.array) → float

Root sum of squares (normalized RMSE).

Computes normalized root mean squared error between reference and comparison arrays, scaling by reference range.

Args:

vs0: Reference array values. vs: Comparison array values (same shape as vs0).

Returns:

Normalized RMSE value (rounded to 2 decimals).

Example:

>>> ref = np.array([1, 2, 3, 4, 5])
>>> comp = np.array([1.1, 2.2, 2.9, 4.1, 5.0])
>>> rss = RSS(ref, comp)

larvaworld.lib.process.evaluation.RSS_dic(dd: larvaworld.lib.process.dataset.LarvaDataset, d: larvaworld.lib.process.dataset.LarvaDataset) → float

Calculate RSS for pooled cycle curves between datasets.

Computes normalized RMSE across all stride cycle curves, comparing simulation dataset against reference dataset.

Args:

dd: Simulation LarvaDataset with pooled_cycle_curves. d: Reference LarvaDataset with pooled_cycle_curves.

Returns:

Mean RSS statistic across all normalized cycle curves.

Side Effects:

Sets dd.pooled_cycle_curves_errors attribute.

Example:

>>> rss_stat = RSS_dic(sim_dataset, ref_dataset)

larvaworld.lib.process.evaluation.eval_RSS(rss: Dict[str, Any], rss_target: Dict[str, Any], rss_sym: Dict[str, str], mode: str = '1:pooled') → dict

Evaluate RSS metrics for multiple datasets.

Computes normalized RMSE for each parameter across multiple dataset IDs against reference targets.

Args:

rss: Dict of {dataset_id: {param: array}} with comparison data. rss_target: Dict of {param: array} with reference targets. rss_sym: Dict mapping parameter names to display symbols. mode: Evaluation mode (currently only ‘1:pooled’ supported).

Returns:

Dict with structure {dataset_id: {symbol: RSS_value}}.

Example:

>>> rss_scores = eval_RSS(
...     rss={'d1': {'v': arr1}, 'd2': {'v': arr2}},
...     rss_target={'v': ref_arr},
...     rss_sym={'v': 'velocity'}
... )

larvaworld.lib.process.evaluation.col_df(shorts: Sequence[str], groups: Sequence[str]) → Any

Create DataFrame for coloring evaluation metrics by category.

Generates color mapping for visualization of evaluation metrics grouped by category (angular, spatial, temporal, etc.).

Args:

shorts: List of parameter short names. groups: List of category groups for each parameter.

Returns:

DataFrame with group colors, symbols, and parameter info.

Example:

>>> df = col_df(
...     shorts=['b', 'fov', 'cum_d'],
...     groups=['angular kinematics', 'angular kinematics', 'spatial displacement']
... )

larvaworld.lib.process.evaluation.get_target_data(d: larvaworld.lib.process.dataset.LarvaDataset, eval_metrics: Any) → larvaworld.lib.util.AttrDict

Extract target data from reference dataset for evaluation.

Separates endpoint and step parameters based on evaluation metrics configuration and data availability.

Args:

d: Reference LarvaDataset with step and endpoint data. eval_metrics: Dict of {category: [param_names]} to evaluate.

Returns:

AttrDict with ‘step’ and ‘end’ keys containing parameter dicts.

Example:

>>> ref_data = get_target_data(
...     d=ref_dataset,
...     eval_metrics={'spatial': ['cum_d', 'v'], 'angular': ['b']}
... )

larvaworld.lib.process.evaluation.arrange_evaluation(data: larvaworld.lib.util.AttrDict, eval_metrics: Any) → Dict[str, Any]

Arrange evaluation data into categorized color DataFrames.

Organizes endpoint and step parameters by evaluation metric categories and generates color mapping DataFrames.

Args:

data: AttrDict with ‘end’ and ‘step’ parameter dicts. eval_metrics: Dict of {category: [param_names]}.

Returns:

AttrDict with ‘end’ and ‘step’ color DataFrames.

Example:

>>> arranged = arrange_evaluation(
...     data=AttrDict(end={'cum_d': arr}, step={'v': arr}),
...     eval_metrics={'spatial': ['cum_d', 'v']}
... )

class larvaworld.lib.process.evaluation.Evaluation(dataset: Any | None = None, **kwargs: Any)

Bases: larvaworld.lib.param.NestedConf

Configuration for dataset evaluation against reference data.

Defines evaluation criteria, target metrics, and comparison methods for assessing simulation quality against experimental datasets.

Attributes:

refID: Reference dataset identifier. refDir: Directory containing the reference dataset. eval_metrics: Dict of metrics to evaluate, grouped by category. minimization: If True, minimize fitness; if False, maximize. metric_categories: Categories for organizing evaluation metrics.

Example:

>>> eval_conf = Evaluation(
...     refID='exploration',
...     eval_metrics={'angular kinematics': ['b', 'fov']}
... )

refID

refDir

eval_metrics

cycle_curve_metrics

target

build(d: larvaworld.lib.process.dataset.LarvaDataset) → None

property s_pars

property e_pars

property s_symbols

property e_symbols

property func_eval_metric_solo

property func_eval_metric_multi

property func_cycle_curve_solo

property func_cycle_curve_multi

property fit_func_multi

property fit_func_solo

eval_datasets(ds, mode, min_size=20)

class larvaworld.lib.process.evaluation.DataEvaluation(**kwargs: Any)

Bases: Evaluation

Data evaluation with normalization and multi-mode comparison.

Extends Evaluation to support multiple normalization modes (raw, minmax, standardized) and evaluation modes for flexible dataset comparison strategies.

Attributes:

norm_modes: List of normalization modes (‘raw’, ‘minmax’, ‘std’). eval_modes: List of evaluation modes (‘pooled’, ‘1:1’, ‘1:pooled’). error_dicts: AttrDict storing evaluation error results.

Example:

>>> data_eval = DataEvaluation(
...     refID='exploration',
...     norm_modes=['raw', 'minmax'],
...     eval_modes=['pooled', '1:1']
... )

norm_modes

eval_modes

error_dicts

norm_error_dict(error_dict, mode='raw')