Reorganizing ParmEst and Pyomo.DoE Documentation Pages#3904
Conversation
|
@mrmundt @blnicho @jsiirola @adowling2, This PR is ready for review. As mentioned in the description, we want to reorganize the documentation webpages of ParmEst and Pyomo.DoE into a structure that is informative, capturing the most up-to-date capabilities, ahead of the ACC Pyomo workshop in May. This PR is meant to create background documentation files and structures for @sscini and @smondal13 to quickly update after their PRs get merged. A major question is whether we should remove the other existing ParmEst documentation pages (e.g., data reconciliation, scenario creation). Thank you. |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #3904 +/- ##
==========================================
- Coverage 89.93% 89.93% -0.01%
==========================================
Files 902 902
Lines 106393 106393
==========================================
- Hits 95683 95680 -3
- Misses 10710 10713 +3
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
jsiirola
left a comment
There was a problem hiding this comment.
Overall this is pretty straightforward, but I have a number of suggested changes.
| A confidence ellipse is a geometric representation of the uncertainty in parameter | ||
| estimates. It is derived from the covariance matrix :math:`\mathbf{V}`. | ||
|
|
||
| In order to solve problems of the above, Pyomo.DoE implements the 2-stage stochastic program. Please see Wang and Dowling (2022) for details. No newline at end of file |
There was a problem hiding this comment.
Consider adding this citation to reference/bibliography.rst and referencing it here.
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | ||
|
|
||
| After creating the subclass of the ``Experiment`` class, exploratory analysis is | ||
| suggested to enumerate the design space to check if the problem is identifiable, |
There was a problem hiding this comment.
The discussion of identifiability appears overly binary. A near-singular or approximately zero Fisher Information Matrix is not the only scenario implying practical non-identifiability. Even when the FIM non-singular, a very large condition number may indicate that certain parameter directions are only weakly informed by the data, corresponding to extremely small eigenvalues and unstable parameter estimates (practical identifiability issues). In such cases, uncertainty remains high and estimates may be highly sensitive to noise, limiting the extent to which experimental design alone can improve parameter estimation. Consider distinguishing more clearly between structural identifiability and practical identifiability arising from ill-conditioning of the FIM.
There was a problem hiding this comment.
@snarasi2 This PR is only meant to organize the order of the documentation pages into the format outlined in the summary. The contents in guide.rst and overview.rst (for DoE) are what currently exist in the documentation page. This PR does not make any changes to the contents but establishes a general structure for the ParmEst and Pyomo.DoE documentation webpages, which will be later updated by @sscini, @smondal13, and @snarasi2. I will save these comments for @smondal13 and @snarasi2 to work on them during their future PRs to update the contents of the Pyomo.DoE documentation webpage.
Co-authored-by: John Siirola <jsiirola@users.noreply.github.com>
Co-authored-by: John Siirola <jsiirola@users.noreply.github.com>
Co-authored-by: John Siirola <jsiirola@users.noreply.github.com>
Co-authored-by: John Siirola <jsiirola@users.noreply.github.com>
Co-authored-by: John Siirola <jsiirola@users.noreply.github.com>
Co-authored-by: John Siirola <jsiirola@users.noreply.github.com>
Co-authored-by: John Siirola <jsiirola@users.noreply.github.com>
Co-authored-by: John Siirola <jsiirola@users.noreply.github.com>
Co-authored-by: John Siirola <jsiirola@users.noreply.github.com>
Co-authored-by: John Siirola <jsiirola@users.noreply.github.com>
Co-authored-by: John Siirola <jsiirola@users.noreply.github.com>
Fixes # .
Summary/Motivation:
The ParmEst and Pyomo.DoE documentation webpages need a major reorganization ahead of the American Control Conference Workshop in May. This update will enable new/existing users to access recent/forthcoming capabilities in ParmEst and Pyomo.DoE
Changes proposed in this PR:
Proposed ParmEst documentation page:
- Overview
- Installation Instructions
- Quick Start Guide
- Objective Options
- Uncertainty Quantification
- Estimability Analysis
Proposed Pyomo.DoE documentation page:
- Overview
- Quick Start Guide
- Experiment Abstraction
- Objective Options
- Multiple Experiments
- Parameter Uncertainty
Legal Acknowledgement
By contributing to this software project, I have read the contribution guide and agree to the following terms and conditions for my contribution: