safe_load_tac
==============================================

.. py:function:: petpal.utils.time_activity_curve.safe_load_tac(filename: str, with_uncertainty: bool = False, **kwargs) -> numpy.ndarray

   Loads time-activity curves (TAC) from a file.

   Tries to read a TAC from specified file and raises an exception if unable to do so. We assume
   that the file has two columns, the first corresponding to time and second corresponding to
   activity.

   :param filename: The name of the file to be loaded.
   :type filename: str
   :param with_uncertainty: Load uncertainty of measured activity along with timing and
                            activity.
   :type with_uncertainty: bool
   :param \*\*kwargs: keyword arguments to pass to :func:`np.loadtxt`.
   :type \*\*kwargs: dict

   :returns: *np.ndarray* --

             A numpy array containing the loaded TAC. The first index corresponds to the
                 times, and the second corresponds to the activity. If with_uncertainty is True, the
                 third index corresponds to the uncertainty.

   :raises Exception: An error occurred loading the TAC.

   .. rubric:: Example

   .. code-block:: python

       import numpy as np
       from petpal.utils.time_activity_curve import safe_load_tac, safe_write_tac

       my_tac = safe_load_tac(filename='/path/to/tac.tsv')
       my_tac_modified = np.zeros_like(my_tac)
       my_tac_modified[0] = my_tac[0] / 60 # convert time units to hours
       my_tac_modified[1] = my_tac[1] / 37000 # convert activity units to mCi
       my_tac_modified[2] = my_tac[2] / 37000 # convert uncertainties like activity
       safe_write_tac(filename='/path/to/new_tac.tsv',
                      tac_data=my_tac_modified)