Skip to content

Commit

Permalink
[RF] Improve documentation for RooFit global functions
Browse files Browse the repository at this point in the history 
The pythonizaiton of some RooFit global functions merited their own
documentations, which are added in this commit.

To make these documentations accessible from doxygen, the following
changes were made in addition:

  * the `print_roofit_pyz_doctrings.py` script now also considers free
    functions

  * the global functions are correctly linked to in the documentation of
    `RooAbsData::plotOn`
  • Loading branch information
@guitargeek
guitargeek committed Feb 2, 2022
1 parent 9cf1aae commit caa0870
Show file tree
Hide file tree
Showing 5 changed files with 125 additions and 60 deletions.
75 changes: 56 additions & 19 deletions bindings/pyroot/pythonizations/python/ROOT/_pythonization/_roofit/_rooglobalfunc.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,7 @@


@cpp_signature(
"FitOptions(const RooCmdArg& arg1, const RooCmdArg& arg2=RooCmdArg::none(),"
"RooFit::FitOptions(const RooCmdArg& arg1, const RooCmdArg& arg2=RooCmdArg::none(),"
"const RooCmdArg& arg3=RooCmdArg::none(),const RooCmdArg& arg4=RooCmdArg::none(),"
"const RooCmdArg& arg5=RooCmdArg::none(),const RooCmdArg& arg6=RooCmdArg::none()) ;"
)
Expand All @@ -71,7 +71,7 @@ def FitOptions(*args, **kwargs):


@cpp_signature(
"Format(const char* what, const RooCmdArg& arg1=RooCmdArg::none(), const RooCmdArg& arg2=RooCmdArg::none(),"
"RooFit::Format(const char* what, const RooCmdArg& arg1=RooCmdArg::none(), const RooCmdArg& arg2=RooCmdArg::none(),"
"const RooCmdArg& arg3=RooCmdArg::none(),const RooCmdArg& arg4=RooCmdArg::none(),"
"const RooCmdArg& arg5=RooCmdArg::none(),const RooCmdArg& arg6=RooCmdArg::none(),"
"const RooCmdArg& arg7=RooCmdArg::none(),const RooCmdArg& arg8=RooCmdArg::none()) ;"
Expand All @@ -91,7 +91,7 @@ def Format(*args, **kwargs):


@cpp_signature(
"Frame(const RooCmdArg& arg1, const RooCmdArg& arg2=RooCmdArg::none(),"
"RooFit::Frame(const RooCmdArg& arg1, const RooCmdArg& arg2=RooCmdArg::none(),"
"const RooCmdArg& arg3=RooCmdArg::none(), const RooCmdArg& arg4=RooCmdArg::none(),"
"const RooCmdArg& arg5=RooCmdArg::none(), const RooCmdArg& arg6=RooCmdArg::none()) ;"
)
Expand All @@ -107,7 +107,7 @@ def Frame(*args, **kwargs):


@cpp_signature(
"MultiArg(const RooCmdArg& arg1, const RooCmdArg& arg2,"
"RooFit::MultiArg(const RooCmdArg& arg1, const RooCmdArg& arg2,"
"const RooCmdArg& arg3=RooCmdArg::none(),const RooCmdArg& arg4=RooCmdArg::none(),"
"const RooCmdArg& arg5=RooCmdArg::none(),const RooCmdArg& arg6=RooCmdArg::none(),"
"const RooCmdArg& arg7=RooCmdArg::none(),const RooCmdArg& arg8=RooCmdArg::none()) ;"
Expand All @@ -123,7 +123,7 @@ def MultiArg(*args, **kwargs):
return RooFit._MultiArg(*args, **kwargs)


@cpp_signature("YVar(const RooAbsRealLValue& var, const RooCmdArg& arg=RooCmdArg::none()) ;")
@cpp_signature("RooFit::YVar(const RooAbsRealLValue& var, const RooCmdArg& arg=RooCmdArg::none()) ;")
def YVar(*args, **kwargs):
r"""The YVar() function is pythonized with the command argument pythonization.
The keywords must correspond to the CmdArg of the function.
Expand All @@ -138,7 +138,7 @@ def YVar(*args, **kwargs):
return RooFit._YVar(*args, **kwargs)


@cpp_signature("ZVar(const RooAbsRealLValue& var, const RooCmdArg& arg=RooCmdArg::none()) ;")
@cpp_signature("RooFit::ZVar(const RooAbsRealLValue& var, const RooCmdArg& arg=RooCmdArg::none()) ;")
def ZVar(*args, **kwargs):
r"""The ZVar() function is pythonized with the command argument pythonization.
The keywords must correspond to the CmdArg of the function.
Expand All @@ -153,7 +153,7 @@ def ZVar(*args, **kwargs):
return RooFit._ZVar(*args, **kwargs)


@cpp_signature("Slice(std::map<RooCategory*, std::string> const&) ;")
@cpp_signature("RooFit::Slice(std::map<RooCategory*, std::string> const&) ;")
def Slice(*args, **kwargs):
r"""The Slice function is pythonized for converting python dict to std::map.
The keywords must correspond to the CmdArg of the function.
Expand All @@ -172,9 +172,9 @@ def Slice(*args, **kwargs):

@cpp_signature(
[
"Import(const std::map<std::string,RooDataSet*>& ) ;",
"Import(const std::map<std::string,TH1*>&) ;",
"Import(const std::map<std::string,RooDataHist*>&) ;",
"RooFit::Import(const std::map<std::string,RooDataSet*>& ) ;",
"RooFit::Import(const std::map<std::string,TH1*>&) ;",
"RooFit::Import(const std::map<std::string,RooDataHist*>&) ;",
]
)
def Import(*args, **kwargs):
Expand All @@ -193,7 +193,7 @@ def Import(*args, **kwargs):
return RooFit._Import(*args, **kwargs)


@cpp_signature("Link(const std::map<std::string,RooAbsData*>&) ;")
@cpp_signature("RooFit::Link(const std::map<std::string,RooAbsData*>&) ;")
def Link(*args, **kwargs):
r"""The Link function is pythonized for converting python dict to std::map.
The keywords must correspond to the CmdArg of the function.
Expand All @@ -210,56 +210,93 @@ def Link(*args, **kwargs):
return RooFit._Link(*args, **kwargs)


@cpp_signature("LineColor(Color_t color) ;")
@cpp_signature("RooFit::LineColor(Color_t color) ;")
def LineColor(color):
# Redefinition of `LineColor` for matplotlib conventions and string arguments.
r"""The `color` argument doesn't necessarily have to be a ROOT color enum value, like `ROOT.kRed`.
Here is what you can also do in PyROOT:
1. Pass a string with the enum value name instead, e.g.:
~~~ {.py}
pdf.plotOn(frame, LineColor="kRed")
~~~
2. Pass a string with the corresponding single-character color code following the matplotlib convention:
~~~ {.py}
pdf.plotOn(frame, LineColor="r")
~~~
3. Pass a string with the enum value name instead followed by some manipulation of the enum value:
~~~ {.py}
pdf.plotOn(frame, LineColor="kRed+1")
~~~
"""
from cppyy.gbl import RooFit

return RooFit._LineColor(_string_to_root_attribute(color, _color_map))


@cpp_signature("FillColor(Color_t color) ;")
@cpp_signature("RooFit::FillColor(Color_t color) ;")
def FillColor(color):
# Redefinition of `FillColor` for matplotlib conventions and string arguments.
from cppyy.gbl import RooFit

return RooFit._FillColor(_string_to_root_attribute(color, _color_map))

# Copy the docstring from LineColor.
FillColor.__doc__ = LineColor.__doc__


@cpp_signature("MarkerColor(Color_t color) ;")
@cpp_signature("RooFit::MarkerColor(Color_t color) ;")
def MarkerColor(color):
# Redefinition of `MarkerColor` for matplotlib conventions and string arguments.
from cppyy.gbl import RooFit

return RooFit._MarkerColor(_string_to_root_attribute(color, _color_map))

# Copy the docstring from LineColor.
MarkerColor.__doc__ = LineColor.__doc__

@cpp_signature("LineStyle(Style_t style) ;")

@cpp_signature("RooFit::LineStyle(Style_t style) ;")
def LineStyle(style):
# Redefinition of `LineStyle` for matplotlib conventions and string arguments.
from cppyy.gbl import RooFit

return RooFit._LineStyle(_string_to_root_attribute(style, _style_map))


@cpp_signature("FillStyle(Style_t style) ;")
@cpp_signature("RooFit::FillStyle(Style_t style) ;")
def FillStyle(style):
# Redefinition of `FillStyle` for matplotlib conventions and string arguments.
from cppyy.gbl import RooFit

return RooFit._FillStyle(_string_to_root_attribute(style, {}))


@cpp_signature("MarkerStyle(Style_t style) ;")
@cpp_signature("RooFit::MarkerStyle(Style_t style) ;")
def MarkerStyle(style):
# Redefinition of `MarkerStyle` for matplotlib conventions and string arguments.
from cppyy.gbl import RooFit

return RooFit._MarkerStyle(_string_to_root_attribute(style, {}))


@cpp_signature("DataError(Int_t) ;")
@cpp_signature("RooFit::DataError(Int_t) ;")
def DataError(etype):
r"""Instead of passing an enum value to this function, you can pass a
string with the name of that enum value, for example:
~~~ {.py}
data.plotOn(frame, DataError="SumW2")
# instead of DataError=ROOT.RooAbsData.SumW2
~~~
If you want to use the `"None"` enum value to disable error plotting, you
can also pass `None` directly instead of passing a string:
~~~ {.py}
data.plotOn(frame, DataError=None)
# instead of DataError="None"
~~~
"""
# Redefinition of `DataError` to also accept `str` or `NoneType` to get the
# corresponding enum values from RooAbsData.DataError.
from cppyy.gbl import RooFit
Expand Down
7 changes: 5 additions & 2 deletions documentation/doxygen/print_roofit_pyz_doctrings.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,7 @@ def write_pyroot_block_for_class(klass):
print("")


def write_pyroot_block_for_member_func(func):
def write_pyroot_block_for_function(func):

if func.__doc__ is None or not hasattr(func, "_cpp_signature"):
return
Expand Down Expand Up @@ -180,7 +180,10 @@ def print_pyroot_blocks_for_cpp_docs():

for func_name in func_names:
func = getattr(python_klass, func_name)
write_pyroot_block_for_member_func(func)
write_pyroot_block_for_function(func)

for python_function in _roofit.python_roofit_functions:
write_pyroot_block_for_function(python_function)


if __name__ == "__main__":
Expand Down
2 changes: 1 addition & 1 deletion roofit/roofitcore/inc/RooGlobalFunc.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -126,7 +126,7 @@ RooCmdArg Cut(const char* cutSpec) ;
RooCmdArg Cut(const RooFormulaVar& cutVar) ;
RooCmdArg Binning(const RooAbsBinning& binning) ;
RooCmdArg Binning(const char* binningName) ;
RooCmdArg Binning(Int_t nBins, Double_t xlo=0., Double_t xhi=0.) ;
RooCmdArg Binning(int nBins, double xlo=0., double xhi=0.) ;
RooCmdArg MarkerStyle(Style_t style) ;
RooCmdArg MarkerSize(Size_t size) ;
RooCmdArg MarkerColor(Color_t color) ;
Expand Down
98 changes: 62 additions & 36 deletions roofit/roofitcore/src/RooAbsData.cxx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1724,60 +1724,86 @@ TList* RooAbsData::split(const RooSimultaneous& simpdf, Bool_t createEmptyDataSe
/// - A binned dataset will retain its intrinsic binning.
///
/// The following optional named arguments can be used to modify the behaviour:
/// \note Please follow the function links in the left column to learn about PyROOT specifics for a given option.
///
/// <table>
///
/// <tr><th> <th> Data representation options
/// <tr><td> `Asymmetry(const RooCategory& c)` <td> Show the asymmetry of the data in given two-state category [F(+)-F(-)] / [F(+)+F(-)].
/// <tr><td> RooFit::Asymmetry(const RooCategory& c)
/// <td> Show the asymmetry of the data in given two-state category [F(+)-F(-)] / [F(+)+F(-)].
/// Category must have two states with indices -1 and +1 or three states with indices -1,0 and +1.
/// <tr><td> `Efficiency(const RooCategory& c)` <td> Show the efficiency F(acc)/[F(acc)+F(rej)]. Category must have two states with indices 0 and 1
/// <tr><td> `DataError(RooAbsData::EType)` <td> Select the type of error drawn:
/// <tr><td> RooFit::Efficiency(const RooCategory& c)
/// <td> Show the efficiency F(acc)/[F(acc)+F(rej)]. Category must have two states with indices 0 and 1
/// <tr><td> RooFit::DataError(Int_t)
/// <td> Select the type of error drawn:
/// - `Auto(default)` results in Poisson for unweighted data and SumW2 for weighted data
/// - `Poisson` draws asymmetric Poisson confidence intervals.
/// - `SumW2` draws symmetric sum-of-weights error ( \f$ \left( \sum w \right)^2 / \sum\left(w^2\right) \f$ )
/// - `None` draws no error bars
/// <tr><td> `Binning(int nbins, double xlo, double xhi)` <td> Use specified binning to draw dataset
/// <tr><td> `Binning(const RooAbsBinning&)` <td> Use specified binning to draw dataset
/// <tr><td> `Binning(const char* name)` <td> Use binning with specified name to draw dataset
/// <tr><td> `RefreshNorm(Bool_t flag)` <td> Force refreshing for PDF normalization information in frame.
/// <tr><td> RooFit::Binning(int nbins, double xlo, double xhi)
/// <td> Use specified binning to draw dataset
/// <tr><td> RooFit::Binning(const RooAbsBinning&)
/// <td> Use specified binning to draw dataset
/// <tr><td> RooFit::Binning(const char* name)
/// <td> Use binning with specified name to draw dataset
/// <tr><td> RooFit::RefreshNorm()
/// <td> Force refreshing for PDF normalization information in frame.
/// If set, any subsequent PDF will normalize to this dataset, even if it is
/// not the first one added to the frame. By default only the 1st dataset
/// added to a frame will update the normalization information
/// <tr><td> `Rescale(Double_t f)` <td> Rescale drawn histogram by given factor.
/// <tr><td> `Cut(const char*)` <td> Only plot entries that pass the given cut.
/// Apart from cutting in continuous variables `Cut("x>5")`, this can also be used to plot a specific
/// category state. Use something like `Cut("myCategory == myCategory::stateA")`, where
/// `myCategory` resolves to the state number for a given entry and
/// `myCategory::stateA` resolves to the state number of the state named "stateA".
/// <tr><td> RooFit::Rescale(Double_t f)
/// <td> Rescale drawn histogram by given factor.
/// <tr><td> RooFit::Cut(const char*)
/// <td> Only plot entries that pass the given cut.
/// Apart from cutting in continuous variables `Cut("x>5")`, this can also be used to plot a specific
/// category state. Use something like `Cut("myCategory == myCategory::stateA")`, where
/// `myCategory` resolves to the state number for a given entry and
/// `myCategory::stateA` resolves to the state number of the state named "stateA".
///
/// <tr><td> `CutRange(const char*)` <td> Only plot data from given range. Separate multiple ranges with ",".
/// \note This often requires passing the normalisation when plotting the PDF because RooFit does not save
/// how many events were being plotted (it will only work for cutting slices out of uniformly distributed variables).
/// <tr><td> RooFit::CutRange(const char*)
/// <td> Only plot data from given range. Separate multiple ranges with ",".
/// \note This often requires passing the normalisation when plotting the PDF because RooFit does not save
/// how many events were being plotted (it will only work for cutting slices out of uniformly distributed
/// variables).
/// ```
/// data->plotOn(frame01, CutRange("SB1"));
/// const double nData = data->sumEntries("", "SB1");
/// // Make clear that the target normalisation is nData. The enumerator NumEvent
/// // is needed to switch between relative and absolute scaling.
/// model.plotOn(frame01, Normalization(nData, RooAbsReal::NumEvent),
/// ProjectionRange("SB1"));
/// data->plotOn(frame01, CutRange("SB1"));
/// const double nData = data->sumEntries("", "SB1");
/// // Make clear that the target normalisation is nData. The enumerator NumEvent
/// // is needed to switch between relative and absolute scaling.
/// model.plotOn(frame01, Normalization(nData, RooAbsReal::NumEvent),
/// ProjectionRange("SB1"));
/// ```
///
/// <tr><th> <th> Histogram drawing options
/// <tr><td> `DrawOption(const char* opt)` <td> Select ROOT draw option for resulting TGraph object
/// <tr><td> `LineStyle(Int_t style)` <td> Select line style by ROOT line style code, default is solid
/// <tr><td> `LineColor(Int_t color)` <td> Select line color by ROOT color code, default is black
/// <tr><td> `LineWidth(Int_t width)` <td> Select line with in pixels, default is 3
/// <tr><td> `MarkerStyle(Int_t style)` <td> Select the ROOT marker style, default is 21
/// <tr><td> `MarkerColor(Int_t color)` <td> Select the ROOT marker color, default is black
/// <tr><td> `MarkerSize(Double_t size)` <td> Select the ROOT marker size
/// <tr><td> `FillStyle(Int_t style)` <td> Select fill style, default is filled.
/// <tr><td> `FillColor(Int_t color)` <td> Select fill color by ROOT color code
/// <tr><td> `XErrorSize(Double_t frac)` <td> Select size of X error bar as fraction of the bin width, default is 1
///
/// <tr><td> RooFit::DrawOption(const char* opt)
/// <td> Select ROOT draw option for resulting TGraph object
/// <tr><td> RooFit::LineStyle(Style_t style)
/// <td> Select line style by ROOT line style code, default is solid
/// <tr><td> RooFit::LineColor(Color_t color)
/// <td> Select line color by ROOT color code, default is black
/// <tr><td> RooFit::LineWidth(Width_t width)
/// <td> Select line with in pixels, default is 3
/// <tr><td> RooFit::MarkerStyle(Style_t style)
/// <td> Select the ROOT marker style, default is 21
/// <tr><td> RooFit::MarkerColor(Color_t color)
/// <td> Select the ROOT marker color, default is black
/// <tr><td> RooFit::MarkerSize(Size_t size)
/// <td> Select the ROOT marker size
/// <tr><td> RooFit::FillStyle(Style_t style)
/// <td> Select fill style, default is filled.
/// <tr><td> RooFit::FillColor(Color_t color)
/// <td> Select fill color by ROOT color code
/// <tr><td> RooFit::XErrorSize(Double_t frac)
/// <td> Select size of X error bar as fraction of the bin width, default is 1
///
/// <tr><th> <th> Misc. other options
/// <tr><td> `Name(const chat* name)` <td> Give curve specified name in frame. Useful if curve is to be referenced later
/// <tr><td> `Invisible()` <td> Add curve to frame, but do not display. Useful in combination AddTo()
/// <tr><td> `AddTo(const char* name, double_t wgtSelf, double_t wgtOther)` <td> Add constructed histogram to already existing histogram with given name and relative weight factors
/// <tr><td> RooFit::Name(const char* name)
/// <td> Give curve specified name in frame. Useful if curve is to be referenced later
/// <tr><td> RooFit::Invisible()
/// <td> Add curve to frame, but do not display. Useful in combination AddTo()
/// <tr><td> RooFit::AddTo(const char* name, double wgtSel, double wgtOther)
/// <td> Add constructed histogram to already existing histogram with given name and relative weight factors
///
/// </table>

RooPlot* RooAbsData::plotOn(RooPlot* frame, const RooLinkedList& argList) const
Expand Down
3 changes: 1 addition & 2 deletions roofit/roofitcore/src/RooGlobalFunc.cxx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -124,12 +124,11 @@ namespace RooFit {
RooCmdArg Cut(const RooFormulaVar& cutVar) { return RooCmdArg("CutVar",0,0,0,0,0,0,&cutVar,0) ; }
RooCmdArg Binning(const RooAbsBinning& binning) { return RooCmdArg("Binning",0,0,0,0,0,0,&binning,0) ;}
RooCmdArg Binning(const char* binningName) { return RooCmdArg("BinningName",0,0,0,0,binningName,0,0,0) ;}
RooCmdArg Binning(Int_t nBins, Double_t xlo, Double_t xhi) { return RooCmdArg("BinningSpec",nBins,0,xlo,xhi,0,0,0,0) ;}
RooCmdArg Binning(int nBins, double xlo, double xhi) { return RooCmdArg("BinningSpec",nBins,0,xlo,xhi,0,0,0,0) ;}
RooCmdArg MarkerStyle(Style_t style) { return RooCmdArg("MarkerStyle",style,0,0,0,0,0,0,0) ; }
RooCmdArg MarkerSize(Size_t size) { return RooCmdArg("MarkerSize",0,0,size,0,0,0,0,0) ; }
RooCmdArg MarkerColor(Color_t color) { return RooCmdArg("MarkerColor",color,0,0,0,0,0,0,0) ; }
RooCmdArg CutRange(const char* rangeName) { return RooCmdArg("CutRange",0,0,0,0,rangeName,0,0,0) ; }
RooCmdArg AddTo(const char* name) { return RooCmdArg("AddTo",0,0,0,0,name,0,0,0) ; }
RooCmdArg XErrorSize(Double_t width) { return RooCmdArg("XErrorSize",0,0,width,0,0,0,0,0) ; }
RooCmdArg RefreshNorm() { return RooCmdArg("RefreshNorm",1,0,0,0,0,0,0,0) ; }
RooCmdArg Efficiency(const RooCategory& cat) { return RooCmdArg("Efficiency",0,0,0,0,0,0,&cat,0) ; }
Expand Down

0 comments on commit caa0870

Please sign in to comment.