larvaworld.lib.plot.scape
=========================

.. py:module:: larvaworld.lib.plot.scape

.. autoapi-nested-parse::

   Sensory landscape plotting



Functions
---------

.. autoapisummary::

   larvaworld.lib.plot.scape.plot_odorscape
   larvaworld.lib.plot.scape.odorscape_isocontours
   larvaworld.lib.plot.scape.odorscape_with_sample_tracks
   larvaworld.lib.plot.scape.plot_3pars
   larvaworld.lib.plot.scape.plot_heatmap_PI
   larvaworld.lib.plot.scape.plot_2d


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

.. py:function:: plot_odorscape(odor_layers: dict, scale: float = 1.0, idx: int = 0, **kwargs: Any) -> None

   Plot 3D odorscape surfaces for multiple odor layers.

   Creates 3D surface plots showing spatial distribution of odor
   concentrations across the environment arena.

   Args:
       odor_layers: Dictionary of odor layer objects with grid and meshgrid
       scale: Spatial scale factor. Defaults to 1.0
       idx: Index for file naming. Defaults to 0
       **kwargs: Additional arguments passed to plot_surface

   Example:
       >>> plot_odorscape(odor_layers={'odor1': layer1}, scale=1.0, idx=0)


.. py:function:: odorscape_isocontours(intensity: float = 2, spread: float = 0.0002, radius: float = 0.05) -> None

   Plot odorscape as filled contour isocontours.

   Creates 2D contour plot showing odor concentration gradients
   from a point source using multivariate normal distribution.

   Args:
       intensity: Peak odor intensity. Defaults to 2
       spread: Odor spread parameter. Defaults to 0.0002
       radius: Plot radius in meters. Defaults to 0.05

   Example:
       >>> odorscape_isocontours(intensity=2, spread=0.0002, radius=0.05)


.. py:function:: odorscape_with_sample_tracks(datasets: Sequence[Any], unit: str = 'mm', fig: Any = None, axs: Any = None, show: bool = False, save_to: Optional[str] = None, **kwargs: Any) -> Any

   Plot odorscape with sample trajectory tracks overlaid.

   Creates 2D odorscape visualization with individual trajectory tracks
   from multiple datasets shown as colored paths.

   Args:
       datasets: List of datasets containing trajectory data
       unit: Distance unit ('mm' or 'm'). Defaults to 'mm'
       fig: Matplotlib figure. Creates new if None
       axs: Matplotlib axes. Creates new if None
       show: Whether to display plot. Defaults to False
       save_to: Directory to save plot. Defaults to None
       **kwargs: Additional arguments passed to odorscape_from_config

   Returns:
       Matplotlib figure object

   Example:
       >>> fig = odorscape_with_sample_tracks(datasets=[d1, d2], unit='mm', show=True)


.. py:function:: plot_3pars(df: pandas.DataFrame, vars: Sequence[str], target: str, z0: Optional[float] = None, **kwargs: Any) -> dict

   Create multiple plots for 3-parameter relationships.

   Generates 3D plot, heatmap, and surface plot showing relationship
   between two independent variables and a target variable.

   Args:
       df: DataFrame containing parameter data
       vars: List of 2 independent variable names
       target: Target variable name
       z0: Reference z-value for horizontal plane. Defaults to None
       **kwargs: Additional arguments passed to plotting functions

   Returns:
       Dictionary of figure objects keyed by plot type

   Example:
       >>> figs = plot_3pars(df, vars=['param1', 'param2'], target='result')


.. py:function:: plot_heatmap_PI(z: Optional[pandas.DataFrame] = None, csv_filepath: str = 'PIs.csv', save_as: str = 'PI_heatmap.pdf', **kwargs: Any) -> Any

   Create heatmap of Preference Index (PI) values.

   Generates color-coded heatmap showing PI values across left and right
   odor gain combinations, with red-yellow-green colormap.

   Args:
       z: DataFrame with PI values. Loads from csv_filepath if None
       csv_filepath: Path to CSV file with PI data. Defaults to 'PIs.csv'
       save_as: Filename for saved plot. Defaults to 'PI_heatmap.pdf'
       **kwargs: Additional arguments passed to plot_heatmap

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

   Example:
       >>> fig = plot_heatmap_PI(z=pi_data, save_as='preference_heatmap.pdf')


.. py:function:: plot_2d(df: pandas.DataFrame, labels: Sequence[str], **kwargs: Any) -> Any

   Create 2D scatter plot of parameter vs result.

   Simple scatter plot showing relationship between a parameter
   and a result variable.

   Args:
       df: DataFrame containing data
       labels: List of 2 labels [parameter, result]
       **kwargs: Additional arguments passed to AutoBasePlot

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

   Example:
       >>> fig = plot_2d(df, labels=['temperature', 'velocity'])