pdstools.decision_analyzer.plots
================================

.. py:module:: pdstools.decision_analyzer.plots


Classes
-------

.. autoapisummary::

   pdstools.decision_analyzer.plots.Plot


Functions
---------

.. autoapisummary::

   pdstools.decision_analyzer.plots.offer_quality_piecharts
   pdstools.decision_analyzer.plots.getTrendChart
   pdstools.decision_analyzer.plots.plot_priority_component_distribution
   pdstools.decision_analyzer.plots.create_win_distribution_plot
   pdstools.decision_analyzer.plots.create_parameter_distribution_boxplots


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

.. py:class:: Plot(decision_data)

   .. py:attribute:: _decision_data


   .. py:method:: threshold_deciles(thresholding_on, thresholding_name, return_df=False)


   .. py:method:: distribution_as_treemap(df: polars.LazyFrame, stage: str, scope_options: List[str])


   .. py:method:: sensitivity(win_rank: int = 1, hide_priority=True, limit_xaxis_range=True, return_df=False, reference_group=None)


   .. py:method:: global_winloss_distribution(level, win_rank, return_df=False)


   .. py:method:: propensity_vs_optionality(stage='Arbitration', df=None, return_df=False)


   .. py:method:: optionality_funnel(df)


   .. py:method:: action_variation(stage='Final', return_df=False)


   .. py:method:: trend_chart(stage: str, scope: str, return_df=False) -> Tuple[plotly.graph_objects.Figure, Optional[str]]


   .. py:method:: decision_funnel(scope: str, additional_filters: Optional[Union[polars.Expr, List[polars.Expr]]] = None, return_df=False)


   .. py:method:: filtering_components(stages: List[str], top_n, AvailableNBADStages, additional_filters: Optional[Union[polars.Expr, List[polars.Expr]]] = None, return_df=False)


   .. py:method:: distribution(df: polars.LazyFrame, scope: str, breakdown: str, metric: str = 'Decisions', horizontal=False)


   .. py:method:: prio_factor_boxplots(reference: Optional[Union[polars.Expr, List[polars.Expr]]] = None, return_df=False) -> Tuple[plotly.graph_objects.Figure, Optional[str]]


   .. py:method:: rank_boxplot(reference: Optional[Union[polars.Expr, List[polars.Expr]]] = None, return_df=False)


   .. py:method:: optionality_per_stage(return_df=False)


   .. py:method:: optionality_trend(df: polars.LazyFrame, return_df=False)


.. py:function:: offer_quality_piecharts(df: polars.LazyFrame, propensityTH, AvailableNBADStages, return_df=False, level='StageGroup')

.. py:function:: getTrendChart(df: polars.LazyFrame, stage: str = 'Output', return_df=False, level='StageGroup')

.. py:function:: plot_priority_component_distribution(value_data: polars.LazyFrame, component: str, granularity: str)

.. py:function:: create_win_distribution_plot(data: polars.DataFrame, win_count_col: str, scope_config: Dict[str, Union[str, List[str]]], title_suffix: str, y_axis_title: str) -> Tuple[plotly.graph_objects.Figure, polars.DataFrame]

   Create a win distribution bar chart with highlighted selected items.

   This function creates a bar chart showing win counts across actions, groups, or issues
   based on the scope configuration. It automatically aggregates data appropriately and
   highlights the selected item in red while showing others in grey.

   :param data: DataFrame containing win distribution data with action identifiers and win counts
   :type data: pl.DataFrame
   :param win_count_col: Column name containing win counts to plot (e.g., "original_win_count", "new_win_count")
   :type win_count_col: str
   :param scope_config: Configuration dictionary from get_scope_config() containing:
                        - level: "Action", "Group", or "Issue"
                        - group_cols: List of columns for grouping
                        - x_col: Column name for x-axis
                        - selected_value: Value to highlight in red
                        - plot_title_prefix: Prefix for plot title
   :type scope_config: Dict[str, Union[str, List[str]]]
   :param title_suffix: Suffix to add to plot title (e.g., "Current Performance", "After Lever Adjustment")
   :type title_suffix: str
   :param y_axis_title: Title for y-axis (e.g., "Current Win Count", "New Win Count")
   :type y_axis_title: str

   :returns:

             - Plotly figure with bar chart
             - Processed plot data (aggregated if needed)
   :rtype: Tuple[go.Figure, pl.DataFrame]

   .. rubric:: Notes

   - For Action level: Shows individual actions
   - For Group/Issue level: Automatically aggregates data by summing win counts
   - Selected item is highlighted in red (#FF0000), others in grey
   - "No Winner" bar (if present in data) is shown in orange (#FFA500) to highlight interactions without winners
   - If selected item not found, uses light blue as fallback color
   - X-axis labels are hidden to avoid clutter, scope level shown as x-axis title
   - "No Winner" data is calculated and added by get_win_distribution_data() when all_interactions parameter is provided

   .. rubric:: Examples

   >>> scope_config = get_scope_config("Service", "Cards", "MyAction")
   >>> fig, plot_data = create_win_distribution_plot(
   ...     distribution_data,
   ...     "new_win_count",
   ...     scope_config,
   ...     "After Lever Adjustment",
   ...     "New Win Count"
   ... )


.. py:function:: create_parameter_distribution_boxplots(segmented_df: polars.DataFrame, parameters: List[str] = ['Propensity', 'Value', 'Context Weight', 'Levers'], title: str = 'Parameter Distributions: Selected Actions vs Competitors') -> plotly.graph_objects.Figure

   Create box plots comparing parameter distributions between selected actions and others.

   :param segmented_df: DataFrame with columns for parameters and a 'segment' column
                        containing "Selected Actions" or "Others"
   :type segmented_df: pl.DataFrame
   :param parameters: List of parameter column names to plot
   :type parameters: List[str], optional
   :param title: Title for the plot
   :type title: str, optional

   :returns: Plotly figure with box plots
   :rtype: go.Figure