[RelNotes] Write about storing global observables in RooFit datasets

README/ReleaseNotes/v626/index.md

@@ -96,6 +96,48 @@ RooFit now contains two RDataFrame action helpers, `RooDataSetHelper` and `RooDa
 ```
 For more details, consult the tutorial [rf408_RDataFrameToRooFit](https://root.cern/doc/v626/rf408__RDataFrameToRooFit_8C.html).
 
+### Storing global observables in RooFit datasets
+
+RooFit groups model variables into *observables* and *parameters*, depending on if their values are stored in the dataset.
+For fits with parameter constraints, there is a third kind of variables, called *global observables*.
+These represent the results of auxiliary measurements that constrain the nuisance parameters.
+In the RooFit implementation, a likelihood is generally the sum of two terms:
+  * the likelihood of the data given the parameters, where the normalization set is the set of observables (implemented by `RooNLLVar`)
+  * the constraint term, where the normalization set is the set of *global observables* (implemented by `RooConstraintSum`)
+
+Before this release, the global observable values were always taken from the model/pdf.
+With this release, a mechanism is added to store a snapshot of global observables in any `RooDataSet` or `RooDataHist`.
+For toy studies where the global observables assume a different values for each toy, the bookkeeping of the set of global observables and in particular their values is much easier with this change.
+
+Usage example for a model with global observables `g1` and `g2`:
+```C++
+auto data = model.generate(x, 1000); // data has only the single observables x
+data->setGlobalObservables(g1, g2); // now, data also stores a snapshot of g1 and g2
+
+// If you fit the model to the data, the global observables and their values
+// are taken from the dataset:
+model.fitTo(*data);
+
+// You can still define the set of global observables yourself, but the values
+// will be takes from the dataset if available:
+model.fitTo(*data, GlobalObservables(g1, g2));
+
+// To force `fitTo` to take the global observable values from the model even
+// though they are in the dataset, you can use the new `GlobalObservablesSource`
+// command argument:
+model.fitTo(*data, GlobalObservables(g1, g2), GlobalObservablesSource("model"));
+// The only other allowed value for `GlobalObservablesSource` is "data", which
+// corresponds to the new default behavior explained above.
+```
+
+In case you create a RooFit dataset directly by calling its constructor, you can also pass the global observables in a command argument instead of calling `setGlobalObservables()` later:
+```C++
+RooDataSet data{"dataset", "dataset", x, RooFit::GlobalObservables(g1, g2)};
+```
+
+To access the set of global observables stored in a `RooAbsData`, call `RooAbsData::getGlobalObservables()`.
+It returns a `nullptr` if no global observable snapshots are stored in the dataset.
+
 ### Changes in `RooAbsPdf::fitTo` behaviour for multi-range fits
 
 The `RooAbsPdf::fitTo` and `RooAbsPdf::createNLL` functions accept a command argument to specify the fit range.
@@ -106,7 +148,7 @@ From now on, the likelihoods are normalized by the sum of integrals in each rang
 
 ### Deprecation of the `RooMinuit` class
 
-The `RooMinuit` class was the old interface between RooFit and minuit. With ROOT version 5.24, a the more general `RooMinimizer` adapter was introduced, which became the default with ROOT 6.08. 
+The `RooMinuit` class was the old interface between RooFit and minuit. With ROOT version 5.24, a the more general `RooMinimizer` adapter was introduced, which became the default with ROOT 6.08.
 
 Before 6.26, it was possible to still use the `RooMinuit` by passing the `Minimizer("OldMinuit", "minimizer")` command argument to `RooAbsPdf::fitTo()`. This option is now removed.