weighted_series_sum
=================================================

.. py:function:: petpal.utils.useful_functions.weighted_series_sum(input_image_path: str, out_image_path: str, half_life: float, verbose: bool = False, start_time: float = 0, end_time: float = -1) -> numpy.ndarray

   Sum a 4D image series weighted based on time and re-corrected for decay correction.

   First, a scaled image is produced by multiplying each frame by its length in seconds,
   and dividing by the decay correction applied:

   .. math::

       f_i'=f_i\times \frac{t_i}{d_i}

   Where :math:`f_i,t_i,d_i` are the i-th frame, frame duration, and decay correction factor of
   the PET series. This scaled image is summed over the time axis. Then, to get the output, we
   multiply by a factor called ``total decay`` and divide by the full length of the image:

   .. math::

       d_{S} = \frac{\lambda*t_{S}}{(1-\exp(-\lambda*t_{S}))(\exp(\lambda*t_{0}))}

   .. math::

       S(f) = \sum(f_i') * d_{S} / t_{S}

   where :math:`\lambda=\log(2)/T_{1/2}` is the decay constant of the radio isotope,
   :math:`t_0` is the start time of the first frame in the PET series, the subscript :math:`S`
   indicates the total quantity computed over all frames, and :math:`S(f)` is the final weighted
   sum image.

   # TODO: Determine half_life from .json rather than passing as argument.

   :param input_image_path: Path to a .nii or .nii.gz file containing a 4D
                            PET image on which the weighted sum is calculated. Assume a metadata
                            file exists with the same path and file name, but with extension .json,
                            and follows BIDS standard.
   :type input_image_path: str
   :param out_image_path: Path to a .nii or .nii.gz file to which the weighted
                          sum is written. If none, will not write output to a file.
   :type out_image_path: str
   :param half_life: Half life of the PET radioisotope in seconds.
   :type half_life: float
   :param verbose: Set to ``True`` to output processing information. Default is False.
   :type verbose: bool
   :param start_time: Time, relative to scan start in seconds, at which
                      calculation begins. Must be used with ``end_time``. Default value 0.
   :type start_time: float
   :param end_time: Time, relative to scan start in seconds, at which
                    calculation ends. Use value ``-1`` to use all frames in image series.
                    If equal to ``start_time``, one frame at start_time is used. Default value -1.
   :type end_time: float

   :returns: *np.ndarray* --

             3D image array, in the same space as the input, with the weighted sum
                 calculation applied.

   :raises ValueError: If ``half_life`` is zero or negative.