Implemented Miranda's final review on parmest.py, test_parmest.py, and covariance.rst

Author: slilonfe5

doc/OnlineDocs/explanation/analysis/parmest/covariance.rst

@@ -9,50 +9,60 @@ methods which have been implemented in parmest.
 
 1. Reduced Hessian Method
 
-    When the objective function is "SSE":
+    When the objective function is the sum of squared errors (SSE) between the
+    observed and predicted values of the measured variables, the covariance matrix is:
 
     .. math::
        V_{\boldsymbol{\theta}} = 2 \sigma^2 \left(\frac{\partial^2 \text{SSE}}
         {\partial \boldsymbol{\theta} \partial \boldsymbol{\theta}}\right)^{-1}_{\boldsymbol{\theta}
         = \boldsymbol{\theta}^*}
 
-    When the objective function is "SSE_weighted":
+    When the objective function is the weighted SSE (WSSE), the covariance matrix is:
 
     .. math::
-       V_{\boldsymbol{\theta}} = 2 \sigma^2 \left(\frac{\partial^2 \text{WSSE}}
+       V_{\boldsymbol{\theta}} = \left(\frac{\partial^2 \text{WSSE}}
         {\partial \boldsymbol{\theta} \partial \boldsymbol{\theta}}\right)^{-1}_{\boldsymbol{\theta}
         = \boldsymbol{\theta}^*}
 
-    Where SSE is the sum of squared errors between the observed (data) and predicted
-    values of the measured variables, WSSE is the weighted SSE,
-    :math:`\boldsymbol{\theta}` are the unknown parameters, :math:`\boldsymbol{\theta^*}`
-    are the estimate of the unknown parameters, and :math:`\sigma^2` is the variance of
-    the measurement error. When the standard deviation of the measurement error is not
-    supplied by the user, parmest approximates the variance of the measurement error as
+    Where :math:`V_{\boldsymbol{\theta}}` is the covariance matrix of the estimated
+    parameters, :math:`\boldsymbol{\theta}` are the unknown parameters,
+    :math:`\boldsymbol{\theta^*}` are the estimate of the unknown parameters, and
+    :math:`\sigma^2` is the variance of the measurement error. When the standard
+    deviation of the measurement error is not supplied by the user, parmest
+    approximates the variance of the measurement error as
     :math:`\sigma^2 = \frac{1}{n-l} \sum e_i^2` where :math:`n` is the number of data
-    points, :math:`l` is the number of fitted parameters, and :math:`e_i` is the residual
-    for experiment :math:`i`.
+    points, :math:`l` is the number of fitted parameters, and :math:`e_i` is the
+    residual for experiment :math:`i`.
 
 2. Finite Difference Method
 
+    In this method, the covariance matrix, :math:`V_{\boldsymbol{\theta}}`, is
+    calculated by applying the Gauss-Newton approximation to the Hessian,
+    :math:`\frac{\partial^2 \text{SSE}}{\partial \boldsymbol{\theta} \partial \boldsymbol{\theta}}`
+    or
+    :math:`\frac{\partial^2 \text{WSSE}}{\partial \boldsymbol{\theta} \partial \boldsymbol{\theta}}`,
+    leading to:
+
     .. math::
-       V_{\boldsymbol{\theta}} = \left( \sum_{r = 1}^n \mathbf{G}_{r}^{\mathrm{T}} \mathbf{W}
-        \mathbf{G}_{r} \right)^{-1}
+       V_{\boldsymbol{\theta}} = \left(\sum_{i = 1}^n \mathbf{G}_{i}^{\mathrm{T}} \mathbf{W}
+        \mathbf{G}_{i} \right)^{-1}
 
     This method uses central finite difference to compute the Jacobian matrix,
-    :math:`\mathbf{G}_{r}`, which is the sensitivity of the measured variables with
-    respect to the parameters, :math:`\boldsymbol{\theta}`. :math:`\mathbf{W}` is a diagonal
-    matrix containing the inverse of the variance of the measurement errors,
-    :math:`\sigma^2`.
+    :math:`\mathbf{G}_{i}`, for experiment :math:`i`, which is the sensitivity of
+    the measured variables with respect to the parameters, :math:`\boldsymbol{\theta}`.
+    :math:`\mathbf{W}` is a diagonal matrix containing the inverse of the variance
+    of the measurement errors, :math:`\sigma^2`.
 
 3. Automatic Differentiation Method
 
+    Similar to the finite difference method, the covariance matrix is calculated as:
+
     .. math::
-       V_{\boldsymbol{\theta}} = \left( \sum_{r = 1}^n \mathbf{G}_{\text{kaug},\, r}^{\mathrm{T}}
-        \mathbf{W} \mathbf{G}_{\text{kaug},\, r} \right)^{-1}
+       V_{\boldsymbol{\theta}} = \left( \sum_{i = 1}^n \mathbf{G}_{\text{kaug},\, i}^{\mathrm{T}}
+        \mathbf{W} \mathbf{G}_{\text{kaug},\, i} \right)^{-1}
 
-    This method uses the model optimality (KKT) condition to compute the Jacobian matrix,
-    :math:`\mathbf{G}_{\text{kaug},\, r}`.
+    However, this method uses the model optimality (KKT) condition to compute the
+    Jacobian matrix, :math:`\mathbf{G}_{\text{kaug},\, i}`, for experiment :math:`i`.
 
 In parmest, the covariance matrix can be calculated after defining the
 :class:`~pyomo.contrib.parmest.parmest.Estimator` object and estimating the unknown

pyomo/contrib/parmest/parmest.py

@@ -41,7 +41,6 @@
 import re
 import importlib as im
 import logging
-import warnings
 import types
 import json
 from collections.abc import Callable
@@ -1056,13 +1055,6 @@ def _Q_opt(
                         solver.options[key] = self.solver_options[key]
 
                 solve_result = solver.solve(self.ef_instance, tee=self.tee)
-
-                # The import error will be raised when we attempt to use
-                # inv_reduced_hessian_barrier below.
-                #
-                # elif not asl_available:
-                #    raise ImportError("parmest requires ASL to calculate the "
-                #                      "covariance matrix with solver 'ipopt'")
             elif kwargs and all(arg.value in kwargs for arg in UnsupportedArgsLib):
                 deprecation_warning(
                     "You're using a deprecated call to the `theta_est()` function "
@@ -1086,13 +1078,6 @@ def _Q_opt(
                             solver.options[key] = self.solver_options[key]
 
                     solve_result = solver.solve(self.ef_instance, tee=self.tee)
-
-                    # The import error will be raised when we attempt to use
-                    # inv_reduced_hessian_barrier below.
-                    #
-                    # elif not asl_available:
-                    #    raise ImportError("parmest requires ASL to calculate the "
-                    #                      "covariance matrix with solver 'ipopt'")
                 else:
                     # parmest makes the fitted parameters stage 1 variables
                     ind_vars = []

pyomo/contrib/parmest/tests/test_parmest.py

@@ -37,8 +37,9 @@
 
 
 # Test class for the built-in "SSE" and "SSE_weighted" objective functions
-# validated the results using the Rooney-Biegler paper example
-# Rooney-Biegler paper example is the case when the measurement error is None
+# validated the results using the Rooney-Biegler paper example linked below
+# https://doi.org/10.1002/aic.690470811
+# The Rooney-Biegler paper example is the case when the measurement error is None
 # we considered another case when the user supplies the value of the measurement error
 @unittest.skipIf(
     not parmest.parmest_available,