[RF] Add documentation for RooKeysPdf, and to its Mirror option

[ynikitenko]

Explain what you would like to see improved

It would be great to add documentation for several RooKeysPdf parameters.
In particular, there is a parameter rho in two constructors, which has no explanation. Constructors descriptions are very unclear. However, rho is explained in the article.

There is a parameter Mirror, which I could not find in the article (it has more options than there). From the code it looks like usually it is just reflecting pdf around the border:

if (_mirrorLeft) {
    p.x = 2. * _lo - x;

But from the source code, line 261 I can't understand the meaning of _asymLeft option (the code is not simple or intuitive, and has no comments).

Additional context

Maybe it would be worth to give a link to RooNDKeysPdf as a closely related class?

[couet]

I see some parameters in these header files are commented but not in the doxygen format. I can improve that to make the comments appear in the reference guide. But when the documentation is completely missing, an expert for these classes is needed. I think @lmoneta should be able to add the missing doc or ask somebody who knows about it to improve the documentation.

[guitargeek]

Hi! It's a good suggestion to improve the documentation of the Roo(ND)KeysPdf. What keeps me from doing that so far is that I don't understand myself why it does what it does.

I compared the implementation with the formulae in the paper cited in the documentation, and there are some differences that I would like to understand before. In particular, the the bandwidth parameters are scaled by a "magic" factor of 2 * sqrt(3):
https://github.com/root-project/root/blob/master/roofit/roofit/src/RooKeysPdf.cxx#L229
This factor goes back to the very first commit that added the RooKeysPdf in Decamber 2001:
https://github.com/root-project/root/blame/39fee5b4e35c4bb4e2eb7b3ca609792627faba47/roofit/src/RooKeysPdf.cxx

I'll ask the original authors if they have any idea where this factor comes from. If nobody knows, I will go ahead writing the documentation anyway, even if the exact formula can't be motivated. At least I can describe exactly what is happening.

[ferdymercury]

by a "magic" factor of 2 * sqrt(3):

Maybe it's rho/sqrt(12) ie the stdev of a uniform distribution of width rho? @cranmer do you remember by chance if that was the assumption?

This factor is also present in the original Perl script of1999:

print OUTF "      hs(k) = (h*Sqrt(Sqrt(Sigma2)/g(EVENTS(K))))*\n";
print OUTF "     + Alpha/(2.0*Sqrt(3.0))\n";
print OUTF "      hsigma = h*Sqrt(Sigma2)\n"; 

from https://web.archive.org/web/20020705034344/https://www-wisconsin.cern.ch/~cranmer/keys.html