Improved Parameter Documentation for Johnson and CBShape Classes with Added Images

roofit/roofit/src/RooCBShape.cxx

@@ -14,11 +14,75 @@
  * listed in LICENSE (http://roofit.sourceforge.net/license.txt)             *
  *****************************************************************************/
 
-/** \class RooCBShape
-    \ingroup Roofit
+/** 
+ * \class RooCBShape
+ * \ingroup Roofit
+ * 
+ * \brief The RooCBShape class represents the Crystal Ball distribution.
+ * 
+ * This class implements the Crystal Ball distribution, which is widely used in high-energy physics for fitting 
+ * asymmetric distributions. The Crystal Ball function consists of a Gaussian core and a power-law tail on the left side.
+ * 
+ * \section CrystalBallDistribution Crystal Ball Distribution
+ * 
+ * The general equation for the Crystal Ball distribution is:
+ * 
+ * \f[
+ * f(x; \alpha, \beta, \mu, \sigma) = 
+ * \begin{cases} 
+ * \exp\left(-\frac{(x-\mu)^2}{2\sigma^2}\right) & \text{for} \quad \frac{x-\mu}{\sigma} > -\alpha, \\
+ * A \left(B - \frac{x-\mu}{\sigma}\right)^{-n} & \text{for} \quad \frac{x-\mu}{\sigma} \leq -\alpha 
+ * \end{cases} 
+ * \f]
+ * 
+ * where:
+ * 
+ * \f[
+ * \begin{aligned}
+ * n &= \frac{\alpha^2}{\beta}, \\
+ * A &= \left(\frac{n}{|\alpha|}\right)^n \exp\left(-\frac{\alpha^2}{2}\right), \\
+ * B &= \frac{n}{|\alpha|} - |\alpha| 
+ * \end{aligned}
+ * \f]
+ * 
+ * In this equation:
+ * - \f$\mu\f$: The mean or peak of the distribution.
+ * - \f$\sigma\f$: The standard deviation, which determines the width of the Gaussian core.
+ * - \f$\alpha\f$: Controls the transition between the Gaussian core and the power-law tail.
+ * - \f$\beta\f$: Controls the slope of the power-law tail.
+ * 
+ * The parameters and their effects on the distribution's shape are discussed in detail below.
+ * 
+ * \subsection ParameterDescriptions Parameter Descriptions
+ * 
+ * \paragraph{Sigma (\f$\sigma\f$)}
+ * The parameter \f$\sigma\f$ determines the scale of the Crystal Ball distribution:
+ * 
+ * \image html combined_sigmas.png "Effect of varying sigma on the Crystal Ball distribution."
+ * 
+ * As \f$\sigma\f$ increases, the distribution becomes wider and more spread out, indicating greater variability. 
+ * Conversely, as \f$\sigma\f$ decreases, the distribution becomes narrower and more concentrated around the mean \f$\mu\f$.
+ * 
+ * \paragraph{Alpha (\f$\alpha\f$)}
+ * The parameter \f$\alpha\f$ controls the transition point between the Gaussian core and the power-law tail:
+ * 
+ * \image html combined_alphas.png "Effect of varying alpha on the Crystal Ball distribution."
+ * 
+ * Higher values of \f$\alpha\f$ result in a steeper left tail, while lower values of \f$\alpha\f$ create a smoother transition.
+ * This parameter significantly influences the steepness and shape of the left tail of the distribution.
+ * 
+ * \paragraph{Beta (\f$\beta\f$)}
+ * The parameter \f$\beta\f$ determines the power of the tail:
+ * 
+ * \image html combined_betas.png "Effect of varying beta on the Crystal Ball distribution."
+ * 
+ * Higher values of \f$\beta\f$ lead to a fatter tail, indicating a higher probability of extreme values. Lower values 
+ * of \f$\beta\f$ result in a thinner tail. This parameter affects the thickness and extent of the tail on the left 
+ * side of the distribution.
+ * 
+ * \note The figures included in this documentation visually represent the effects of varying \f$\sigma\f$, \f$\alpha\f$, and \f$\beta\f$ on the shape of the Crystal Ball distribution.
+ */
 
-PDF implementing the Crystal Ball line shape.
-**/
 
 #include "RooCBShape.h"
 

roofit/roofit/src/RooJohnson.cxx

@@ -13,31 +13,70 @@
  * listed in LICENSE (http://roofit.sourceforge.net/license.txt)             *
  *****************************************************************************/
 
-/** \class RooJohnson
-    \ingroup Roofit
-
-Johnson's \f$ S_{U} \f$ distribution.
-
-This PDF results from transforming a normally distributed variable \f$ x \f$ to this form:
-\f[
-  z = \gamma + \delta \sinh^{-1}\left( \frac{x - \mu}{\lambda} \right)
-\f]
-The resulting PDF is
-\f[
-  \mathrm{PDF}[\mathrm{Johnson}\ S_U] = \frac{\delta}{\lambda\sqrt{2\pi}}
-  \frac{1}{\sqrt{1 + \left( \frac{x-\mu}{\lambda} \right)^2}}
-  \;\exp\left[-\frac{1}{2} \left(\gamma + \delta \sinh^{-1}\left(\frac{x-\mu}{\lambda}\right) \right)^2\right].
-\f]
-
-It is often used to fit a mass difference for charm decays, and therefore the variable \f$ x \f$ is called
-"mass" in the implementation. A mass threshold allows to set the PDF to zero to the left of the threshold.
-
-###References:
-Johnson, N. L. (1949). *Systems of Frequency Curves Generated by Methods of Translation*. Biometrika **36(1/2)**, 149–176. [doi:10.2307/2332539](https://doi.org/10.2307%2F2332539)
-
-\image html RooJohnson_plot.png
-
-**/
+/** 
+ * \class RooJohnson
+ * \ingroup Roofit
+ * 
+ * \brief The RooJohnson class represents Johnson's SU distribution.
+ * 
+ * This class implements Johnson's SU distribution, which is derived by transforming a normally distributed 
+ * variable \( x \) as follows:
+ * 
+ * \section JohnsonDistribution Johnson's SU Distribution
+ * 
+ * The transformation to obtain Johnson's SU distribution is:
+ * 
+ * \f[
+ *   z = \gamma + \delta \sinh^{-1}\left( \frac{x - \mu}{\lambda} \right)
+ * \f]
+ * 
+ * The resulting Probability Density Function (PDF) is given by:
+ * 
+ * \f[
+ *   \mathrm{PDF}[\mathrm{Johnson}\ S_U] = \frac{\delta}{\lambda\sqrt{2\pi}}
+ *   \frac{1}{\sqrt{1 + \left( \frac{x-\mu}{\lambda} \right)^2}}
+ *   \;\exp\left[-\frac{1}{2} \left(\gamma + \delta \sinh^{-1}\left(\frac{x-\mu}{\lambda}\right) \right)^2\right].
+ * \f]
+ * 
+ * Johnson's SU distribution is often employed to fit mass differences in charm decays. Consequently, 
+ * the variable \( x \) is referred to as "mass" within this implementation. A mass threshold can also be set, 
+ * causing the PDF to evaluate to zero for values of \( x \) below this threshold.
+ * 
+ * \subsection ParameterDescriptions Parameter Descriptions
+ * 
+ * \paragraph{Mu (\(\mu\))}
+ * The parameter \(\mu\) represents the mean of the distribution, shifting its center along the x-axis.
+ * 
+ * \paragraph{Sigma (\(\sigma\))}
+ * The parameter \(\sigma\) is the scale parameter, analogous to the standard deviation in a normal distribution:
+ * 
+ * \image html combined_lambdas.png "Figure 1: Effect of varying sigma on Johnson's SU distribution."
+ * 
+ * As \(\sigma\) increases, the distribution broadens, indicating greater variability.
+ * 
+ * \paragraph{Gamma (\(\gamma\))}
+ * The parameter \(\gamma\) is the skewness parameter, controlling the asymmetry of the distribution:
+ * 
+ * \image html combined_gammas.png "Figure 2: Effect of varying gamma on Johnson's SU distribution."
+ * 
+ * Positive \(\gamma\) results in negative skewness (left tail), while negative \(\gamma\) produces positive skewness (right tail).
+ * 
+ * \paragraph{Delta (\(\delta\))}
+ * The parameter \(\delta\) is the kurtosis parameter, influencing the 'tailedness' of the distribution:
+ * 
+ * \image html combined_deltas.png "Figure 3: Effect of varying delta on Johnson's SU distribution."
+ * 
+ * Lower \(\delta\) values result in a less steep tail, while higher \(\delta\) values lead to a rapidly diminishing 
+ * tail as one moves away from the mean.
+ * 
+ * \note The figures included in this documentation visually represent the effects of varying \(\sigma\), \(\gamma\), 
+ * and \(\delta\) on the shape of Johnson's SU distribution.
+ * 
+ * \section References References
+ * 
+ * Johnson, N. L. (1949). *Systems of Frequency Curves Generated by Methods of Translation*. Biometrika **36(1/2)**, 149–176. 
+ * [doi:10.2307/2332539](https://doi.org/10.2307%2F2332539)
+ */
 
 #include "RooJohnson.h"