Relaxation

phyto_photo_utils._relaxation.fit_relaxation(flevel, seq_time, seq, datetime, blank=0, sat_len=100, rel_len=60, sat_flashlets=None, single_decay=False, bounds=True, single_lims=[100, 50000], tau1_lims=[100, 800], tau2_lims=[800, 2000], tau3_lims=[2000, 50000], method='trf', loss='soft_l1', f_scale=0.1, max_nfev=None, xtol=1e-09)

Process the raw transient data and perform the Kolber et al. 1998 relaxation model.

Parameters:
  • seq_time (np.array, dtype=float, shape=[n,]) – The sequence time of the flashlets in μs.
  • flevel (np.array, dtype=float, shape=[n,]) – The fluorescence yield of the instrument.
  • seq (np.array, dtype=int, shape=[n,]) – The measurement number.
  • datetime (np.array, dtype=datetime64, shape=[n,]) – The date & time of each measurement in the numpy datetime64 format.
  • blank (np.array, dtype=float, shape=[n,]) – The blank value, must be the same length as flevel.
  • sat_len (int, default=100) – The number of flashlets in the saturation sequence.
  • rel_len (int, default=60) – The number of flashlets in the relaxation sequence.
  • sat_flashlets (int, default=0) – The number of saturation flashlets to include at the start.
  • single_decay (bool, default=False) – If True, will fit a single decay relaxation.
  • bounds (bool, default=True) – If True, will set lower and upper limit bounds for the estimation, not suitable for methods ‘lm’.
  • single_lims ([int, int], default=[100, 50000]) – The lower and upper limit bounds for fitting τ, only required if single_decay is True.
  • tau1_lims ([int, int], default=[100, 800]) – The lower and upper limit bounds for fitting τ1.
  • tau2_lims ([int, int], default=[800, 2000]) – The lower and upper limit bounds for fitting τ2.
  • tau3_lims ([int, int], default=[2000, 50000]) – The lower and upper limit bounds for fitting τ3.
  • fit_method (str, default='trf') – The algorithm to perform minimization. See scipy.optimize.least_squares documentation for more information on non-linear least squares fitting options.
  • loss_method (str, default='soft_l1') – The loss function to be used. Note: Method ‘lm’ supports only ‘linear’ loss. See scipy.optimize.least_squares documentation for more information on non-linear least squares fitting options.
  • fscale (float, default=0.1) – The soft margin value between inlier and outlier residuals. See scipy.optimize.least_squares documentation for more information on non-linear least squares fitting options.
  • max_nfev (int, default=None) – The number of iterations to perform fitting routine. If None, the value is chosen automatically. See scipy.optimize.least_squares documentation for more information on non-linear least squares fitting options.
  • xtol (float, default=1e-9) – The tolerance for termination by the change of the independent variables. See scipy.optimize.least_squares documentation for more information on non-linear least squares fitting options.
Returns:

  • res (pandas.DataFrame) – The results of the fitting routine with columns as below:
  • fo_r (np.array, dtype=float, shape=[n,]) – The minimum fluorescence level of relaxation phase.
  • fm_r (np.array, dtype=float, shape=[n,]) – The maximum fluorescence level of relaxation phase
  • tau (np.array, dtype=float, shape=[n,]) – The rate of QA- reoxidation in μs, only returned if single_decay is True.
  • alpha1 (np.array, dtype=float, shape=[n,]) – The decay coefficient of τ1, only returned if single_decay is False.
  • tau1 (np.array, dtype=float, shape=[n,]) – The rate of QA- reoxidation in μs, only returned if single_decay is False.
  • alpha2 (np.array, dtype=float, shape=[n,]) – The decay coefficient of τ2.
  • tau2 (np.array, dtype=float, shape=[n,]) – The rate of QB- reoxidation in μs, only returned if single_decay is False.
  • alpha3 (np.array, dtype=float, shape=[n,]) – The decay coefficient of τ3, only returned if single_decay is False.
  • tau3 (np.array, dtype=float, shape=[n,]) – The rate of PQ reoxidation in μs, only returned if single_decay is False.
  • bias (np.array, dtype=float, shape=[n,]) – The bias of fit in %.
  • rmse (np.array, dtype=float, shape=[n,]) – The root mean squared error of the fit.
  • nrmse (np.array, dtype=float, shape=[n,]) – The root mean squared error of the fit normalised to the mean of the fluorescence level.
  • fo_err (np.array, dtype=float, shape=[n,]) – The fit error of Fo_relax in %.
  • fm_err (np.array, dtype=float, shape=[n,]) – The fit error of Fm_relax in %.
  • tau_err (np.array, dtype=float, shape=[n,]) – The fit error of τ, only returned if single_decay is True.
  • alpha1_err (np.array, dtype=float, shape=[n,]) – The fit error of α1, only returned if single_decay is False.
  • tau1_err (np.array, dtype=float, shape=[n,]) – The fit error of τ1, only returned if single_decay is False.
  • alpha2_err (np.array, dtype=float, shape=[n,]) – The fit error of α2, only returned if single_decay is False.
  • tau2_err (np.array, dtype=float, shape=[n,]) – The fit error of τ2, only returned if single_decay is False.
  • alpha3_err (np.array, dtype=float, shape=[n,]) – The fit error of α3, only returned if single_decay is False.
  • tau3_err (np.array, dtype=float, shape=[n,]) – The fit error of τ3, only returned if single_decay is False.
  • nfl (np.array, dtype=int, shape=[n,]) – The number of flashlets used for fitting.
  • niters (np.array, dype=int, shape=[n,]) – The number of functional evaluations done on the fitting routine.
  • flag (np.array, dtype=int, shape=[n,]) – The code associated with the fitting routine success, positive values = SUCCESS, negative values = FAILURE. -3 : Unable to calculate parameter errors -2 : Fo Relax > Fm Relax -1 : improper input parameters status returned from MINPACK. 0 : the maximum number of function evaluations is exceeded. 1 : gtol termination condition is satisfied. 2 : ftol termination condition is satisfied. 3 : xtol termination condition is satisfied. 4 : Both ftol and xtol termination conditions are satisfied.
  • success (np.array, dtype=bool, shape=[n,]) – A boolean array reporting whether fit was successful (TRUE) or if not successful (FALSE)
  • datetime (np.array, dtype=datetime64, shape=[n,]) – The date and time associated with the measurement.

Example

>>> rel = ppu.calculate_relaxation(flevel, seq_time, seq, datetime, blank=0, sat_len=100, rel_len=40, single_decay=True, bounds=True, tau_lims=[100, 50000])