feat: Add setup for custom modifiers

[lukasheinrich]

Description

Closes #1188

a cleaner version of PR #1188 on the way to addressing Issue #850

Before Merging

For the PR Assignees:

• Summarize commit messages into a comprehensive review of the PR

* This API breaking change allows for the start of addition of custom
modifiers.
* `pyhf.workspace.Workspace.parameters` are fully removed from the
API through removal from `pyhf.mixins`. Instead, parameters is added
as an attribute to the model config.
* Remove the modifier registry and in place add {modifier}_builder
classes for the modifiers. Additionally add
pyhf.modifiers.histfactory_set which is the map of all the
predefined modifiers that HistFactory specifies.
* All workspace parameters related tests are removed and tests are
added for the change to model.config
* The change from workspace.parameters to model.config.parameters
is made in all affected example notebooks.
* Apply a tiny relative tolerance change in the regression tests to
increase to rel=1.5e-5. The resulting tolerance is on the order of 1e-7
and so the change is inconsequential.

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[matthewfeickert]

Thanks for this PR @lukasheinrich — it is obviously quite important.

This is big enough that I think I'm going to need some help understanding it all, so take most of this review as questions rather than request. But I think a lot of that can be simplified if I understand if my suggestion of a modifier_builder class makes sense here or not.

Also, I think that all of the notebook changes can get removed here, right? I don't think that anything in this PR is actually showing up as new information/content there and that all the changes are just from you re-running the notebooks. Can you confirm that? ReviewNB isn't showing changes in its visualized diff.

[kratsg]

I have to say I'm pretty impressed. I'd consider this an impactful change that doesn't require a major (or minor) breaking version of pyhf at all.

I can already see how we plan to pull in new modifiers on top of this. I have a few comments overall that I'll mention here:

• required_parset has bothered me on some level, because we do need it to have the same signature across all modifiers, even if the arguments are not being used. I see why it's done this way (so we don't need to handle if/else statements...) but I truly wonder if there's a better way to co-locate/define these "defaults" in an easy way for users to look up.
• the builder/combined classes are great, do we want to do something similar to how our optimizer works, where users can inherit from a base class and provide the necessary functions in order to inject their custom mod in? This would also align similar to how coffea/uproot does things as well. I'm happy to add on top of this if we merge into master as is. (On some level, the way we had a modifier registry allowed users to inject their own modifiers using the decorators, but I guess we're moving away from decorators?)
• in some places, you use mega_mods, in some places, mega_samples, builder_data, and in some places, "modifiers". it's not clear to me which is what or if they are all meant to be the same.
• why do we drop workspace.parameters and model.parameters entirely? Is this seen as duplicated by the similar modifiers attribute?

[alexander-held]

This looks very promising, thanks for all the work! I noticed one thing when testing the downstream effects: the order of model parameters can change. While this may not be a breaking change for many users (the order is something that should probably not be relied on anyway), it may cause some unexpected effects. I think it would be useful to highlight this change (assuming it is an intended side-effect of this PR).

[lukasheinrich]

Hi @alexander-held: yes - while @kratsg is right that in principle this could be sold as a pure refactoring i'd vote for a minor version since this is a pretty big change

[matthewfeickert]

Thanks for all of this @lukasheinrich. 🚀

If people are happy with the docstring changes I made, then this all LGTM.