docs / naming: test statistics

[lukasheinrich]

Description

somewhat connected also to #520. Perhaps confusingly qmu(..) in pyhf.utils actually computed q_mu tilde in its default behavior because the poi is bounded from below at 0, so naturally implements the conditions of qmu tilde. This is a bit non-obvious and docs could be improved.

[matthewfeickert]

Given some very thoughtful and helpful feedback that we've recently been given by @alexander-held on the notebook that's introduced in PR #790, we should probably try to address this sometime in the near future. I think we all agree with Alex's points about the API here being confusing, but we'll need to introduce an API breaking change to do anything about them.

I see two ways of changing the API:

1. Renaming to test_stat and then adding options for qtilde vs q if you want the POI to be bounded at 0 on not
2. Adding a second, complimentary function to the API qtildemu and changing the default behaviour of qmu

Option 1 has a problem though that the calculator class API already has a teststatistic method and so having both test_stat and teststatistic in the API is probably confusing and bad design. Option 2 is much more explicit, and in my view the way to go. Though we then have to add checks that the value of the POI is properly bounded in each case.