plot_timeline
=============

.. py:module:: plot_timeline

.. autoapi-nested-parse::

   Timeline analysis plotting module for ML results analysis.
   Focuses on temporal trends and run-to-run comparisons with outcome stratification.



Attributes
----------

.. autoapisummary::

   plot_timeline.MAX_OUTCOMES_FOR_STRATIFIED_PLOT


Classes
-------

.. autoapisummary::

   plot_timeline.TimelineAnalysisPlotter


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

.. py:data:: MAX_OUTCOMES_FOR_STRATIFIED_PLOT
   :value: 8


.. py:class:: TimelineAnalysisPlotter(data: pandas.DataFrame)

   Initializes the timeline analysis plotter.

   :param data: Results DataFrame, which must contain a
                'run_timestamp' column.
   :type data: pd.DataFrame

   :raises ValueError: If the 'run_timestamp' column is not found in the data.


   .. py:attribute:: data


   .. py:attribute:: clean_data


   .. py:method:: plot_performance_timeline(metric: str = 'auc', algorithms_to_plot: Optional[List[str]] = None, stratify_by_outcome: bool = False, outcomes_to_plot: Optional[List[str]] = None, aggregation: str = 'mean', figsize: Tuple[int, int] = (14, 6)) -> None

      Plots performance metrics over time (across runs).

      :param metric: The performance metric to plot.
                     Defaults to 'auc'.
      :type metric: str, optional
      :param algorithms_to_plot: A list of
                                 specific algorithms to include. Defaults to None.
      :type algorithms_to_plot: Optional[List[str]], optional
      :param stratify_by_outcome: If True, creates separate
                                  plots for each outcome. Defaults to False.
      :type stratify_by_outcome: bool, optional
      :param outcomes_to_plot: A list of specific
                               outcomes to plot. Defaults to None.
      :type outcomes_to_plot: Optional[List[str]], optional
      :param aggregation: How to aggregate within runs ('mean',
                          'best', 'median'). Defaults to 'mean'.
      :type aggregation: str, optional
      :param figsize: The figure size.
                      Defaults to (14, 6).
      :type figsize: Tuple[int, int], optional



   .. py:method:: plot_improvement_trends(metric: str = 'auc', algorithms_to_plot: Optional[List[str]] = None, stratify_by_outcome: bool = False, outcomes_to_plot: Optional[List[str]] = None, figsize: Tuple[int, int] = (14, 7)) -> None

      Plots the optimization progress within each run.

      This helps visualize how quickly the optimization finds better models within each batch/run.

      :param metric: The performance metric to analyze.
                     Defaults to 'auc'.
      :type metric: str, optional
      :param algorithms_to_plot: A list of
                                 specific algorithms to include. If None, all are used.
                                 Defaults to None.
      :type algorithms_to_plot: Optional[List[str]], optional
      :param stratify_by_outcome: If True, creates separate
                                  plots for each outcome. Defaults to False.
      :type stratify_by_outcome: bool, optional
      :param outcomes_to_plot: A list of specific
                               outcomes to plot if stratified. Defaults to None.
      :type outcomes_to_plot: Optional[List[str]], optional
      :param figsize: The figure size.
                      Defaults to (14, 7).
      :type figsize: Tuple[int, int], optional



   .. py:method:: plot_computational_cost_timeline(algorithms_to_plot: Optional[List[str]] = None, stratify_by_outcome: bool = False, outcomes_to_plot: Optional[List[str]] = None, aggregation: str = 'mean', figsize: Tuple[int, int] = (14, 6)) -> None

      Plots the computational cost (run_time) over time (across runs).

      :param algorithms_to_plot: A list of
                                 specific algorithms to include. Defaults to None.
      :type algorithms_to_plot: Optional[List[str]], optional
      :param stratify_by_outcome: If True, creates separate
                                  plots for each outcome. Defaults to False.
      :type stratify_by_outcome: bool, optional
      :param outcomes_to_plot: A list of specific
                               outcomes to plot if stratified. Defaults to None.
      :type outcomes_to_plot: Optional[List[str]], optional
      :param aggregation: How to aggregate within runs ('mean',
                          'sum', 'median'). Defaults to 'mean'.
      :type aggregation: str, optional
      :param figsize: The figure size for the plot.
                      Defaults to (14, 6).
      :type figsize: Tuple[int, int], optional