docs

src/pint/fitter.py

@@ -1165,7 +1165,11 @@ def _fit_toas(
         min_lambda=1e-3,
         debug=False,
     ):
-        "Downhill fit implementation. See documentation of the `fit_toas()` method for more details."
+        """Downhill fit implementation for fitting the timing model parameters.
+        The `fit_toas()` calls this method iteratively to fit the timing model parameters
+        while also fitting for white noise parameters.
+
+        See documentation of the `fit_toas()` method for more details."""
         # setup
         self.model.validate()
         self.model.validate_toas(self.toas)
@@ -1289,6 +1293,12 @@ def fit_toas(
         This function can also estimate white noise parameters (EFACs and EQUADs)
         and their uncertainties.
 
+        If there are no free white noise parameters, this function will do one
+        iteration of the downhill fit (implemented in the `_fit_toas()` method).
+        If free white noise parameters are present, it will fit for them by numerically
+        maximizing the likelihood function (implemented in the `_fit_noise()` method).
+        The timing model fit and the noise model fit are run iteratively in an alternating fashion.
+
         Parameters
         ==========
 
@@ -1315,7 +1325,7 @@ def fit_toas(
                 debug=debug,
             )
         else:
-            log.info("Will fit for noise parameters.")
+            log.debug("Will fit for noise parameters.")
             for _ in range(noise_fit_niter):
                 self._fit_toas(
                     maxiter=maxiter,
@@ -1355,7 +1365,10 @@ def _update_noise_params(self, values, errors):
             getattr(self.model, fp).uncertainty_value = err
 
     def _fit_noise(self):
-        """Estimate noise parameters and their uncertainties."""
+        """Estimate noise parameters and their uncertainties. Noise parameters
+        are estimated by numerically maximizing the log-likelihood function including
+        the normalization term. The uncertainties thereof are computed using the
+        numerically-evaluated Hessian."""
         free_noise_params = self._get_free_noise_params()
 
         xs0 = [getattr(self.model, fp).value for fp in free_noise_params]
@@ -1375,6 +1388,10 @@ def _mloglike(xs):
         result = opt.minimize(_mloglike, xs0, method="Nelder-Mead")
 
         def _like(xs):
+            """The likelihood function normalized by its maximum value.
+            Note that this function will give sensible results only in the
+            vicinity of the maximum-likelihood point and will overflow
+            otherwise due to the `exp()` function."""
             return np.exp(-_mloglike(xs) + result.fun)
 
         hess = Hessdiag(_like)

src/pint/models/noise_model.py

@@ -75,7 +75,7 @@ def __init__(
             maskParameter(
                 name="TNEQ",
                 units=u.LogUnit(physical_unit=u.second),
-                description="An error term added in quadrature to the scaled (by EFAC) TOA uncertainty in the unit of log10(second).",
+                description="An error term added in quadrature to the scaled (by EFAC) TOA uncertainty in units of log10(second).",
             )
         )
         self.covariance_matrix_funcs += [self.sigma_scaled_cov_matrix]

src/pint/residuals.py

@@ -503,7 +503,11 @@ def calc_time_resids(
     def _calc_gls_chi2(self, lognorm=False):
         """Compute the chi2 when correlated noise is present in the timing model.
         If the system is not singular, it uses Cholesky factorization to evaluate this.
-        If the system is singular, it uses singular value decomposition instead."""
+        If the system is singular, it uses singular value decomposition instead.
+
+        If `lognorm=True` is given, the log-normalization-factor of the likelihood
+        function will also be returned.
+        """
         self.update()
 
         residuals = self.time_resids.to(u.s).value
@@ -577,6 +581,18 @@ def calc_chi2(self, lognorm=False):
         Handling of problematic results - degenerate conditions explored by
         a minimizer for example - may need to be checked to confirm that they
         correctly return infinity.
+
+        If `lognorm=True` is given, the log-normalization-factor of the likelihood
+        function will also be returned.
+
+        Parameters
+        ----------
+        lognorm: bool
+            If True, return the the log-normalization-factor of the likelihood
+            function along with the chi2 value.
+
+        Returns
+
         """
         if self.model.has_correlated_errors:
             return self._calc_gls_chi2(lognorm=lognorm)