CORP decomposition wrapper

[nicholasloveday]

Currently we can use the scores package to calculate the CORP decomposition https://www.pnas.org/doi/10.1073/pnas.2016191118#sec-4

It would be nice to have a wrapper to do this for us to remove the manual steps.

One design choice that needs to be made is, do we:

• a) create one wrapper function where you pass in the scoring function, or
• b) create a wrapper function for every relevant scoring function?

[nikeethr]

Just checking, I assume you mean wrapper (as in a function transformer or higher order function) and not decorator? Decorators may cause forced nesting, whereas a wrapper on its own is okay.

If you're going the function wrapper route and CORP is fairly generic, I'd just have the one wrapper and cater to edge cases as needed. If you feel CORP is very metric dependent, then maybe have the one wrapper offload/route (e.g. using a dict -> score mapping or similar) to a more metric specific wrappers for each score. For an initial implementation this may be fine, but if it is potentially impacting a lot of the codebase then please consider some additional thoughts I had below:

---

Alternative design:

Its harder to track side-effects and structure that may be necessary when using wrappers (which store state internally) - classes however can dictate how much visibility an object should have based on its structure.

I'm not sure of the exact details but for example if CORP requires defining MSB, DSC and UNC for a particular score, that can be abstracted in the class definition, initialization and/or using builder patterns

e.g.

# more likely an internal structure to setup what needs to be done
(msb, dsc, unc) = CorpDecomposer(<init_options>)
                      .with_inputs(obs, fcst)
                      .with_score(mse)
                      .with_calibration_method(...)
                      .with_extra_options(...)
                      .decompose()
### AND/OR ### 

def mse_corp(...):
    # above stuff goes in here, and user can use this less verbose API instead.
    # in fact this could still be a convenient wrapper, but the internal logic is implemented in a decomposed/extensible way.

This allows you to:

• Apply methods (e.g. calibration) in a more extensible way
• morph the actual decomposer itself e.g. MoreCorpyDecomposer(CorpDecomposer) for tricky edge cases if you need to.
• be adaptable to non-trivial score apis
• do things like corp1 = CorpDecomposer(<defaults>); corp2 = corp1.with_calibration_method(blah2) and compare.

[nicholasloveday]

Just checking, I assume you mean wrapper (as in a function transformer or higher order function) and not decorator? Decorators may cause forced nesting, whereas a wrapper on its own is okay.

Yes, not a decorator.

If you're going the function wrapper route and CORP is fairly generic, I'd just have the one wrapper and cater to edge cases as needed.

Yes, it is fairly generic. I think the only thing which differs between them is what quantile or expectile is used when the isotonic regression function is called.

I guess the question is, for a CORP decomposition of MSE, does the user use

corp_mse(fcst, obs)

or

from scores.continuous import mse
corp_decomposition(fcst, obs, scoring_rule=mse)

The second option is quicker to build.

[nikeethr]

I prefer the second one. You can always have an "alias" if needed i.e. corp_mse = corp_decomposition(fcst, obs, scoring_rule=mse)

For aliases a decorator is fine imo. So if you really want to.

@corp_decomposition(scoring_rule=mse)
def corp_mse(...):
    """
    <docstring>
    """
    ...  # nothing here all logic handled by decorator

But I think letting the user do corp_decomposition(fcst, obs, scoring_rule=mse) is fine...