larvaworld.lib.plot.box
=======================

.. py:module:: larvaworld.lib.plot.box

.. autoapi-nested-parse::

   Boxplots



Functions
---------

.. autoapisummary::

   larvaworld.lib.plot.box.boxplot
   larvaworld.lib.plot.box.boxplot_PI
   larvaworld.lib.plot.box.PIboxplot
   larvaworld.lib.plot.box.boxplot_double_patch
   larvaworld.lib.plot.box.plot_foraging
   larvaworld.lib.plot.box.lineplot


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

.. py:function:: boxplot(ks: Sequence[str], sort_labels: bool = False, name: Optional[str] = None, xlabel: Optional[str] = None, pair_ids: Optional[Sequence[str]] = None, common_ids: Optional[Sequence[str]] = None, coupled_labels: Optional[bool] = None, **kwargs: Any) -> Any

   Create grouped boxplots comparing parameters across datasets.

   Generates boxplots using seaborn for specified parameters, with support
   for coupled group comparisons (e.g., experimental pairs).

   Args:
       ks: Parameter keys to plot
       sort_labels: Whether to sort group labels alphabetically. Defaults to False
       name: Plot name for saving. Auto-generated if None
       xlabel: Custom x-axis label. Defaults to None
       pair_ids: Identifiers for paired groups. Auto-extracted if None
       common_ids: Common identifiers across pairs. Auto-extracted if None
       coupled_labels: Whether labels are coupled. Auto-detected if None
       **kwargs: Additional arguments passed to AutoPlot

   Returns:
       Plot output (figure object or None based on return_fig setting)

   Example:
       >>> fig = boxplot(ks=['v', 'a'], datasets=[d1, d2], coupled_labels=True)


.. py:function:: boxplot_PI(sort_labels: bool = False, xlabel: str = 'Trials', **kwargs: Any) -> Any

   Create boxplot of preference indices across conditions.

   Generates boxplots showing preference index (PI) distributions for
   different experimental conditions with automatic color-coding.

   Args:
       sort_labels: Whether to sort labels alphabetically. Defaults to False
       xlabel: X-axis label. Defaults to 'Trials'
       **kwargs: Additional arguments passed to AutoPlot

   Returns:
       Plot output (figure object or None based on return_fig setting)

   Example:
       >>> fig = boxplot_PI(datasets=[d1, d2, d3], sort_labels=True)


.. py:function:: PIboxplot(df: Any, exp: str, save_to: str, ylabel: str, ylim: Optional[Sequence[float]] = None, show: bool = False, suf: str = '') -> None

   Create simple boxplot and save to file.

   Generates a basic matplotlib boxplot without AutoPlot infrastructure,
   useful for quick standalone visualizations.

   Args:
       df: Data to plot (array-like or DataFrame)
       exp: Experiment name for title
       save_to: Directory path for saving
       ylabel: Y-axis label
       ylim: Y-axis limits. Defaults to None
       show: Whether to display plot. Defaults to False
       suf: Filename suffix. Defaults to empty string

   Example:
       >>> PIboxplot(data, 'Exp1', './plots', 'Preference Index', ylim=[-1, 1])


.. py:function:: boxplot_double_patch(ks: Optional[Sequence[str]] = None, xlabel: str = 'substrate', show_ns: bool = False, stripplot: bool = False, title: bool = True, **kwargs: Any) -> Any

   Create boxplots for rover/sitter comparison in double-patch assay.

   Generates multi-panel boxplots comparing behavioral parameters between
   rover and sitter phenotypes across different substrate conditions,
   with on-food vs off-food comparisons.

   Args:
       ks: Parameter keys to plot. Defaults to ['v_mu', 'tur_N_mu', 'pau_tr',
           'tur_H', 'cum_d', 'on_food_tr']
       xlabel: X-axis label. Defaults to 'substrate'
       show_ns: Whether to show non-significant comparisons. Defaults to False
       stripplot: Whether to overlay strip plot. Defaults to False
       title: Whether to show plot title. Defaults to True
       **kwargs: Additional arguments passed to AutoPlot

   Returns:
       Plot output (figure object or None based on return_fig setting)

   Example:
       >>> fig = boxplot_double_patch(datasets=[d1, d2], stripplot=True)


.. py:function:: plot_foraging(**kwargs: Any) -> Any

   Create boxplots of foraging metrics by food type.

   Generates boxplots showing time on food and food amount consumed
   across different food types for each dataset group.

   Args:
       **kwargs: Arguments passed to AutoPlot

   Returns:
       Plot output (figure object or None based on return_fig setting)

   Example:
       >>> fig = plot_foraging(datasets=[d1, d2])


.. py:function:: lineplot(markers: Sequence[str], ks: Sequence[str] = ['f_am'], name: Optional[str] = None, coupled_labels: Optional[Sequence[str]] = None, xlabel: Optional[str] = None, ylabel: Optional[str] = None, leg_cols: Optional[Sequence[str]] = None, scale: float = 1.0, **kwargs: Any) -> Any

   Create line plots with error bars for parameter comparisons.

   Generates line plots showing parameter means with error bars across
   conditions, with support for statistical comparisons and custom markers.

   Args:
       markers: Marker styles for different groups
       ks: Parameter keys to plot. Defaults to ['f_am']
       name: Plot name for saving. Auto-generated if None
       coupled_labels: Labels for paired comparisons. If provided, data
           is grouped into pairs
       xlabel: Custom x-axis label. Defaults to None
       ylabel: Custom y-axis label. Defaults to None
       leg_cols: Legend colors. Auto-generated if None
       scale: Scaling factor for y-values. Defaults to 1.0
       **kwargs: Additional arguments passed to AutoPlot

   Returns:
       Plot output (figure object or None based on return_fig setting)

   Example:
       >>> fig = lineplot(markers=['o', 's'], ks=['v', 'a'], datasets=[d1, d2])