Adding regularization objective option to parmest

[sscini]

Fixes # .

Summary/Motivation:

Currently, the only default objective is the standard SSE objective. This edit provides the capability to add a
regularization term to the SSE objective with a prior FIM and reference parameter values.

Changes proposed in this PR:

• Added prior_FIM and theta_ref as keyword arguments for Estimator
• Added options within Estimator to apply the regularization term to SSE if the new arguments were defined

TODO before converting from draft

• Receive feedback from collaborators on logical setup
• Finish edits and debug
• Confirm functionality with examples

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:

1. I agree my contributions are submitted under the BSD license.
2. I represent I am authorized to make the contributions and grant the license. If my employer has rights to intellectual property that includes these contributions, I represent that I have received permission to make contributions and grant the required license on behalf of that employer.

[sscini]

@djlaky @adowling2 Please provide early feedback

[adowling2]

@sscini See my early feedback.

[sscini]

UPDATE (07/15/25); Intended to be added AFTER Shammah's weighted SSE PR (#3535) and follow a similar format, adding another option for available objectives using Enums.

Currently preparing for next stage of review

[sscini]

@adowling2 @djlaky Made some edits to this finally. Meant to follow Shammah's layout in PR #3535, waiting to merge, currently some conflicts I cannot resolve on my end.

Made it's own full objective instead of a term to add. Also added weighting term.

Ready for next round of review.

[sscini]

Will not be actively worked on before finalization of _Q_opt_blocks. Closing for now to resume in the future.

[sscini]

@blnicho Thanks for clarifying! I started working on tests but still need to finalize. Away from computer but should be online have them in by early afternoon in MT.

[sscini]

@slilonfe5 @adowling2 @blnicho One small design question I wanted to clarify. In this implementation it was assuming the theta and cov were returned as pd.Series and pd.DataFrames, respectively. We changed in _Q_opt to where theta is now a dictionary.

Should this support: a) current pd Series and DataFrames, b) Dictionary and DataFrames, c) Both dictionaries, or d) both dictionaries and pd objects for either?

The other option is to convert the output back to pd.Series for theta, but converting dict to a series can be shown in an example if that is the stronger long term design choice.

All of this can also be decided in a future PR if this is not a large issue.

[slilonfe5]

@slilonfe5 @adowling2 @blnicho One small design question I wanted to clarify. In this implementation it was assuming the theta and cov were returned as pd.Series and pd.DataFrames, respectively. We changed in _Q_opt to where theta is now a dictionary.

Should this support: a) current pd Series and DataFrames, b) Dictionary and DataFrames, c) Both dictionaries, or d) both dictionaries and pd objects for either?

The other option is to convert the output back to pd.Series for theta, but converting dict to a series can be shown in an example if that is the stronger long term design choice.

All of this can also be decided in a future PR if this is not a large issue.

@sscini, I think the design decision (dictionary for theta and pd.DataFrame for cov) from the merged Q_opt PR is better. These should already reflect on this branch after updating it with the Pyomo main.

[blnicho]

I agree with @slilonfe5, let's stick with the design from the Q_opt PR for now.

[sscini]

@blnicho With the reviewer approval, when I make new changes will the coverage test rerun each time, or once I am finished do I request the new coverage test?

[blnicho]

The coverage will be updated every time you make changes to this PR

[sscini]

@blnicho @mrmundt Please review final version when available. There was one more small change required if you could please add the pre-test inspected label once more. Otherwise all tests passing. Thanks!

[slilonfe5]

@blnicho @mrmundt Please review final version when available. There was one more small change required if you could please add the pre-test inspected label once more. Otherwise all tests passing. Thanks!

@blnicho @mrmundt Most of the code is now covered. I think this is ready to be merged