larvaworld.lib.process.evaluation
=================================

.. py:module:: larvaworld.lib.process.evaluation

.. autoapi-nested-parse::

   Methods for dataset evaluation/comparison



Classes
-------

.. autoapisummary::

   larvaworld.lib.process.evaluation.Evaluation
   larvaworld.lib.process.evaluation.DataEvaluation


Functions
---------

.. autoapisummary::

   larvaworld.lib.process.evaluation.eval_end_fast
   larvaworld.lib.process.evaluation.eval_distro_fast
   larvaworld.lib.process.evaluation.eval_fast
   larvaworld.lib.process.evaluation.RSS
   larvaworld.lib.process.evaluation.RSS_dic
   larvaworld.lib.process.evaluation.eval_RSS
   larvaworld.lib.process.evaluation.col_df
   larvaworld.lib.process.evaluation.get_target_data
   larvaworld.lib.process.evaluation.arrange_evaluation


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

.. py:function:: 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'
       ... )


.. py:function:: 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
       ... )


.. py:function:: 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'})
       ... )


.. py:function:: 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)


.. py:function:: 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)


.. py:function:: 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'}
       ... )


.. py:function:: 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']
       ... )


.. py:function:: 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']}
       ... )


.. py:function:: 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']}
       ... )


.. py:class:: Evaluation(dataset: Optional[Any] = None, **kwargs: Any)

   Bases: :py:obj:`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']}
       ... )


   .. py:attribute:: refID


   .. py:attribute:: refDir


   .. py:attribute:: eval_metrics


   .. py:attribute:: cycle_curve_metrics


   .. py:attribute:: target


   .. py:method:: build(d: larvaworld.lib.process.dataset.LarvaDataset) -> None


   .. py:property:: s_pars


   .. py:property:: e_pars


   .. py:property:: s_symbols


   .. py:property:: e_symbols


   .. py:property:: func_eval_metric_solo


   .. py:property:: func_eval_metric_multi


   .. py:property:: func_cycle_curve_solo


   .. py:property:: func_cycle_curve_multi


   .. py:property:: fit_func_multi


   .. py:property:: fit_func_solo


   .. py:method:: eval_datasets(ds, mode, min_size=20)


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

   Bases: :py:obj:`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']
       ... )


   .. py:attribute:: norm_modes


   .. py:attribute:: eval_modes


   .. py:attribute:: error_dicts


   .. py:method:: norm_error_dict(error_dict, mode='raw')