TacFigure
=========================================

.. py:class:: petpal.visualizations.tac_plots.TacFigure(figsize: tuple = (8, 4), xlabel: str = '$t$ [minutes]', ylabel: str = 'TAC [$\\mathrm{kBq/ml}$]', plot_type: str = 'both')

   A class for plotting Time Activity Curves (TACs) on linear and semi-logarithmic scales.

   This class simplifies the process of comparing TACs on different scales. It generates a
   side-by-side plot with a linear-linear scale for the first plot and a log-x scale for the
   second plot. Users can add TACs to the plots and optionally generate a legend.

   :ivar fig: The figure object that contains the plots.
   :vartype fig: matplotlib.figure.Figure
   :ivar axes: The axes objects where the TACs are plotted.
   :vartype axes: ndarray of Axes
   :ivar fax: The flattened list of axes objects for each subplot.

   :vartype fax: list

   Example:

   .. code-block:: python

       from petpal.visualizations.tac_plots import TacFigure
       from petpal.utils.time_activity_curve import TimeActivityCurve

       # Simple plot of the time-activity curve
       my_fig = tac_plots.TacFigure()

       ## Loading our TAC files
       my_tac = TimeActivityCurve.from_tsv("/path/to/tac.tsv")
       my_other_tac = TimeActivityCurve.from_tsv("/path/to/other_tac.tsv")

       ## Usual plt.plot kwargs can be used to modify styles
       my_fig.add_tac(*my_tac.tac, label="My TAC", marker='x', ls='--')
       my_fig.add_tac(*my_other_tac.tac, label="Other TAC", marker='s', ls='-')

       ## Saving the figure to disk my_fig.write_fig(out_fig_path="/path/to/plot.png")
       # plt.show() # Uncomment to see the figure
       plt.close()

       # Errorbar plot of the time-activity curve, assuming we have uncertainty
       my_tac = TimeActivityCurve.from_tsv("/path/to/tac_with_uncertainty.tsv")
       my_fig = tac_plots.TacFigure()

       ## Usual plt.errorbar kwargs can be used to modify styles
       my_fig.add_errorbar(*my_tac.tac_werr, label="My TAC", fmt='o-', capsize=2)

       ## Saving the figure to disk
       # my_fig.write_fig(out_fig_path="/path/to/plot.png") # Uncomment to save to disk

       plt.show() # Comment this out if you don't want to see the figure
       # plt.close() # Uncomment this if you don't want to see the figure


   Initialize the TacFigure with two subplots, one with a linear scale and the other with a
   semi-logarithmic scale.

   :param figsize: The total size of the figure. Defaults to an 8x4 inches figure.
   :type figsize: tuple
   :param xlabel: The label for the x-axis. Defaults to '$t$ [minutes]'.
   :type xlabel: str
   :param ylabel: The label for the y-axis. Defaults to 'TAC [$\mathrm{kBq/ml}$]'.
   :type ylabel: str
   :param plot_type: Type of plot, with options 'linear', 'log', or 'both'.
   :type plot_type: str


   .. py:method:: setup_linear_subplot(xlabel: str, ylabel: str, figsize: tuple)

      Get the figure and axes objects for a 1x1 MatPlotLib subplot.

      :param xlabel: The label for the x-axis.
      :type xlabel: str
      :param ylabel: The label for the y-axis.
      :type ylabel: str
      :param figsize: Size of the figure.
      :type figsize: tuple



   .. py:method:: setup_log_subplot(xlabel: str, ylabel: str, figsize: tuple)

      Get the figure and axes objects for a 1x1 MatPlotLib subplot.

      :param xlabel: The label for the x-axis.
      :type xlabel: str
      :param ylabel: The label for the y-axis.
      :type ylabel: str
      :param figsize: Size of the figure.
      :type figsize: tuple



   .. py:method:: setup_linear_and_log_subplot(xlabel: str, ylabel: str, figsize: tuple)

      Get the figure and axes objects for a 1x2 MatPlotLib subplot.

      :param xlabel: The label for the x-axis.
      :type xlabel: str
      :param ylabel: The label for the y-axis.
      :type ylabel: str
      :param figsize: Size of the figure.
      :type figsize: tuple



   .. py:method:: add_tac(tac_times: numpy.ndarray, tac_vals: numpy.ndarray, **kwargs)

      Add a TAC to both subplots.

      :param tac_times: The time points for the TAC.
      :type tac_times: np.ndarray
      :param tac_vals: The corresponding values for the TAC.
      :type tac_vals: np.ndarray
      :param kwargs: Additional keyword arguments for the plot() function.
      :type kwargs: dict



   .. py:method:: add_errorbar(tac_times: numpy.ndarray, tac_vals: numpy.ndarray, uncertainty: numpy.ndarray, **kwargs)

      Add a lineplot with errorbars to the figure.

      :param tac_times: Array containing times at which TAC is sampled.
      :type tac_times: np.ndarray
      :param tac_vals: Array containing TAC activity concentration.
      :type tac_vals: np.ndarray
      :param uncertainty: Array containing uncertainties in TAC measurements.
      :type uncertainty: np.ndarray
      :param kwargs: Additional keyword arguments for the plt.errorbar() function.
      :type kwargs: dict



   .. py:method:: set_ylim_min_to_zero(**kwargs)

      Set the y-axis lower limit to zero.

      :param kwargs: Additional keyword arguments for the set_ylim() function.
      :type kwargs: dict



   .. py:method:: gen_legend()

      Generate a legend using the labels provided in the add_tac() method.

      .. note:: It is recommended to add all TACs before generating the legend. Any TACs added after

      the legend is generated will not be included in the legend.




   .. py:method:: write_fig(out_fig_path: str, **kwargs)

      Write the figure to a common image file type, such as .png or .jpg. Applies
      :meth:`plt.savefig` to figure object.

      :param out_fig_path: Path to the file the figure will be written to.
      :type out_fig_path: str
      :param kwargs: Additional key word arguments passed to plt.savefig()
      :type kwargs: dict