From bb65332f45d29bdada9723fde85505889a953981 Mon Sep 17 00:00:00 2001 From: nckw Date: Wed, 20 Mar 2024 19:42:00 +0000 Subject: [PATCH 1/7] Add instructions example for FC 2D --- docs/part3/commonstatsmethods.md | 175 +++++++++++++++++++++---------- docs/part3/images/2D_FC.png | Bin 0 -> 12358 bytes docs/part3/images/2D_LHScan.png | Bin 0 -> 11029 bytes 3 files changed, 119 insertions(+), 56 deletions(-) create mode 100644 docs/part3/images/2D_FC.png create mode 100644 docs/part3/images/2D_LHScan.png diff --git a/docs/part3/commonstatsmethods.md b/docs/part3/commonstatsmethods.md index 060c776143f..fdec21507e0 100644 --- a/docs/part3/commonstatsmethods.md +++ b/docs/part3/commonstatsmethods.md @@ -358,7 +358,8 @@ combine realistic-counting-experiment.txt -M HybridNew --LHCmode LHC-limits /// details | **Show output** -
 <<< Combine >>>
+

+<<< Combine >>>
 >>> including systematics
 >>> using the Profile Likelihood test statistics modified for upper limits (Q_LHC)
 >>> method used is HybridNew
@@ -850,66 +851,57 @@ As usual, any *floating* nuisance parameters will be *profiled*. This behaviour
 
 For most of the methods, for lower-precision results you can turn off the profiling of the nuisance parameters by using the option `--fastScan`, which for complex models speeds up the process by several orders of magnitude. **All** nuisance parameters will be kept fixed at the value corresponding to the best fit point.
 
-As an example, let's produce the $-2\Delta\ln{\mathcal{L}}$ scan as a function of **`r_ggH`** and **`r_qqH`** from the toy H→γγ datacard, with the nuisance parameters *fixed* to their global best fit values.
+As an example, let's produce the $-2\Delta\ln{\mathcal{L}}$ scan as a function of **`r_ggH`** and **`r_qqH`** from the toy $H\rightarrow\gamma\gamma$ datacard.
 
 ```sh
-combine toy-hgg-125.root -M MultiDimFit --algo grid --points 2000 --setParameterRanges r_qqH=0,10:r_ggH=0,4 -m 125 --fastScan
+combine toy-hgg-125.root -M MultiDimFit --algo grid --points 2000 --setParameterRanges r_qqH=0,12:r_ggH=-1,4 -m 125
 ```
 
-/// details | **Show output**
-

- <<< Combine >>>
->>> including systematics
->>> method used is MultiDimFit
->>> random number generator seed is 123456
-ModelConfig 'ModelConfig' defines more than one parameter of interest. This is not supported in some statistical methods.
-Set Range of Parameter r_qqH To : (0,10)
-Set Range of Parameter r_ggH To : (0,4)
-Computing results starting from observation (a-posteriori)
- POI: r_ggH= 0.88152 -> [0,4]
- POI: r_qqH= 4.68297 -> [0,10]
-Point 0/2025, (i,j) = (0,0), r_ggH = 0.044444, r_qqH = 0.111111
-Point 11/2025, (i,j) = (0,11), r_ggH = 0.044444, r_qqH = 2.555556
-Point 22/2025, (i,j) = (0,22), r_ggH = 0.044444, r_qqH = 5.000000
-Point 33/2025, (i,j) = (0,33), r_ggH = 0.044444, r_qqH = 7.444444
-Point 55/2025, (i,j) = (1,10), r_ggH = 0.133333, r_qqH = 2.333333
-Point 66/2025, (i,j) = (1,21), r_ggH = 0.133333, r_qqH = 4.777778
-Point 77/2025, (i,j) = (1,32), r_ggH = 0.133333, r_qqH = 7.222222
-Point 88/2025, (i,j) = (1,43), r_ggH = 0.133333, r_qqH = 9.666667
-Point 99/2025, (i,j) = (2,9), r_ggH = 0.222222, r_qqH = 2.111111
-Point 110/2025, (i,j) = (2,20), r_ggH = 0.222222, r_qqH = 4.555556
-Point 121/2025, (i,j) = (2,31), r_ggH = 0.222222, r_qqH = 7.000000
-Point 132/2025, (i,j) = (2,42), r_ggH = 0.222222, r_qqH = 9.444444
-Point 143/2025, (i,j) = (3,8), r_ggH = 0.311111, r_qqH = 1.888889
-Point 154/2025, (i,j) = (3,19), r_ggH = 0.311111, r_qqH = 4.333333
-Point 165/2025, (i,j) = (3,30), r_ggH = 0.311111, r_qqH = 6.777778
-Point 176/2025, (i,j) = (3,41), r_ggH = 0.311111, r_qqH = 9.222222
-Point 187/2025, (i,j) = (4,7), r_ggH = 0.400000, r_qqH = 1.666667
-Point 198/2025, (i,j) = (4,18), r_ggH = 0.400000, r_qqH = 4.111111
-Point 209/2025, (i,j) = (4,29), r_ggH = 0.400000, r_qqH = 6.555556
-Point 220/2025, (i,j) = (4,40), r_ggH = 0.400000, r_qqH = 9.000000
-[...]
+The scan, along with the best fit point can be drawn using ROOT using something like the script below,
 
-Done in 0.00 min (cpu), 0.02 min (real)
-

-///
+/// details | **Show script**
+

+void plot2D_LHScan(){
 
-The scan, along with the best fit point can be drawn using root,
+  TFile *_file0 = TFile::Open("higgsCombineTest.MultiDimFit.mH125.root");
+  TTree *limit = (TTree*) _file0->Get("limit");
 
-```c++
-$ root -l higgsCombineTest.MultiDimFit.mH125.root
+  // create histogram representing -2Delta Log(L)
+  TCanvas *can = new TCanvas("c","c",600,540);
+  limit->Draw("2*deltaNLL:r_qqH:r_ggH>>h(44,-1,4,44,0,12)","2*deltaNLL<50","prof colz");
+  TH2F *g2NLL = (TH2F*)gROOT->FindObject("h");
 
-limit->Draw("2*deltaNLL:r_ggH:r_qqH>>h(44,0,10,44,0,4)","2*deltaNLL<10","prof colz")
+  g2NLL->SetName("g2NLL");
+  g2NLL->SetTitle("");
+  g2NLL->GetXaxis()->SetTitle("r_{ggH}");
+  g2NLL->GetYaxis()->SetTitle("r_{qqH}");
 
-limit->Draw("r_ggH:r_qqH","quantileExpected == -1","P same")
-TGraph *best_fit = (TGraph*)gROOT->FindObject("Graph")
+  // Get best fit point
+  limit->Draw("r_qqH:r_ggH","quantileExpected == -1","P same");
+  TGraph *best_fit = (TGraph*)gROOT->FindObject("Graph");
 
-best_fit->SetMarkerSize(3); best_fit->SetMarkerStyle(34); best_fit->Draw("p same")
-```
+  best_fit->SetMarkerSize(3);
+  best_fit->SetMarkerStyle(34);
+  best_fit->Draw("p same");
+
+  // get 1-sigma contour
+  TH2F *h68 = (TH2F*)g2NLL->Clone();
+  h68->SetContour(2);
+  h68->SetContourLevel(1,2.3);
+  h68->SetLineWidth(3);
+  h68->SetLineColor(1);
+  h68->Draw("CONT3same");
 
-![](images/nll2D.png)
+  gStyle->SetOptStat(0);
+  can->SaveAs("2D_LHScan.png");
 
-To make the full profiled scan, just remove the `--fastScan` option from the Combine command.
+ }
+

+///
+
+This will produce a plot like the one below,
+
+![](images/2D_LHScan.png)
 
 Similarly, 1D scans can be drawn directly from the tree, however for 1D likelihood scans, there is a python script from the [`CombineHarvester/CombineTools`](http://cms-analysis.github.io/HiggsAnalysis-CombinedLimit/#combine-tool) package [plot1DScan.py](https://github.com/cms-analysis/CombineHarvester/blob/113x/CombineTools/scripts/plot1DScan.py) that can be used to make plots and extract the crossings of the `2*deltaNLL` - e.g the 1σ/2σ boundaries.
 
@@ -1015,11 +1007,15 @@ Imposing physical boundaries (such as requiring $\mu>0$ for a signal strength) i
 
 The boundary is imposed by **restricting the parameter range(s)** to those set by the user, in the fits. Note that this is a trick! The actual fitted value, as one of an ensemble of outcomes, can fall outside of the allowed region, while the boundary should be imposed on the physical parameter. The effect of restricting the parameter value in the fit is such that the test statistic is modified as follows ;
 
-$q(x) = - 2 \ln \mathcal{L}(x,\hat{\hat{\theta}}(x))/\mathcal{L}(\hat{x},\hat{\nu})$, if $\hat{x}$ in contained in the bounded range
+$$q(x) = - 2 \ln \mathcal{L}(x,\hat{\hat{\theta}}(x))/\mathcal{L}(\hat{x},\hat{\nu}),$$
+
+if $\hat{x}$ in contained in the bounded range
 
 and,
 
-$q(x) = - 2 \ln \mathcal{L}(x,\hat{\hat{\nu}}(x))/\mathcal{L}(x_{B},\hat{\hat{\nu}}(x_{B}))$, if $\hat{x}$ is outside of the bounded range. Here $x_{B}$ and $\hat{\hat{\nu}}(x_{B})$ are the values of $x$ and $\nu$ which maximise the likelihood *excluding values outside of the bounded region* for $x$ - typically, $x_{B}$ will be found at one of the boundaries which is imposed. For example, if the boundary $x>0$ is imposed, you will typically expect $x_{B}=0$, when $\hat{x}\leq 0$, and $x_{B}=\hat{x}$ otherewise.
+$$q(x) = - 2 \ln \mathcal{L}(x,\hat{\hat{\nu}}(x))/\mathcal{L}(x_{B},\hat{\hat{\nu}}(x_{B})),$$
+
+if $\hat{x}$ is outside of the bounded range. Here $x_{B}$ and $\hat{\hat{\nu}}(x_{B})$ are the values of $x$ and $\nu$ which maximise the likelihood *excluding values outside of the bounded region* for $x$ - typically, $x_{B}$ will be found at one of the boundaries which is imposed. For example, if the boundary $x>0$ is imposed, you will typically expect $x_{B}=0$, when $\hat{x}\leq 0$, and $x_{B}=\hat{x}$ otherewise.
 
 This can sometimes be an issue as Minuit may not know if has successfully converged when the minimum lies outside of that range. If there is no upper/lower boundary, just set that value to something far from the region of interest.
 
@@ -1043,14 +1039,81 @@ The output tree will contain the values of the POI that crosses the critical val
 
 You can produce a plot of the value of $p_{x}$ vs the parameter of interest $x$ by adding the option `--plot `.
 
-#### Extracting 2D contours
+#### Extracting 2D contours / general intervals
 
-There is a tool for extracting *2D contours* from the output of `HybridNew` located in `test/makeFCcontour.py`. This can be used provided the option `--saveHybridResult` was included when running `HybridNew`. It can be run with the usual Combine output files (or several of them) as input,
+For *two-dimensional* models, or if the parameter does not behave like a cross section, you will need to extract the contours from the output of `HybridNew` and plot them yourself. We will use the `toy-hgg-125.txt` datacard in the example below to demonstrate how this can be done.
+
+First, we use `combineTool.py` to create jobs for each point in our parameter scan. We want to impose the boundaries that $r_{ggH}>0$, $r_{qqH}>0$.
+In the example below, we will run in interactive mode so this can take a little while. You can instead run in batch or grid submission mode to submit jobs for each point. We configure the tool by specifying the grid of points in `grid.json` as below. Here we want 5000 toys for each point.
+
+```
+{
+  "verbose" : true,
+  "opts" : " --LHCmode LHC-feldman-cousins --saveHybridResult --clsAcc 0 ",
+  "POIs" : ["r_ggH", "r_qqH"],
+  "grids" : [
+    ["0:4|.2","0:10|.5",""]
+  ],
+  "toys_per_cycle"  : 5000,
+  "FC" : true,
+  "min_toys": 5000,
+  "max_toys": 50000,
+  "output_incomplete" : true,
+  "contours":["obs"],
+  "make_plots": true,
+  "CL": 0.95,
+  "output": "FeldmanCousins.root",
+  "zipfile"         : "collected.zip",
+  "statusfile"      : "status.json"
+ }
+```
+
+The command will look like
 
 ```sh
-./test/makeFCcontour.py  toysfile1.root toysfile2.root .... [options] -out outputfile.root
+combineTool.py -M HybridNewGrid  ./grid.json -d toy-hgg-125.root --task-name fc2d --job-mode 'interactive' --cycles 1
 ```
 
-To extract 2D contours, the names of each parameter must be given `--xvar poi_x --yvar poi_y`. The output will be a ROOT file containing a 2D histogram of value of $p_{x,y}$ for each point $(x,y)$ which can be used to draw 2D contours. There will also be a histogram containing the number of toys found for each point.
+Once this is done, we extract the contours using
+```sh
+combineTool.py -M HybridNewGrid  ./grid.json -d toy-hgg-125.root --task-name fc2d --job-mode 'interactive' --cycles 0 --output
+```
+
+which will produce a file `FeldmanCousins.root` that contains a `TGraph2D` which stores the calculated value of $p_{x}$ for each point in the grid. The script below can be used to draw these values and extract the contour corresponding to 68% CL ($\alpha=0.32$).
+
+/// details | **Show script**
+

+void plot_2DFC(){
+
+  TFile *_file0 = TFile::Open("FeldmanCousins.root");
+
+  TCanvas *can = new TCanvas("c","c",600,540);
+
+  // Draw p_x
+  TGraph2D *gpX = (TGraph2D*)_file0->Get("obs");
+  gpX->Draw("colz");
+
+  // Draw 68% contour
+  TH2F *h68 = (TH2F*)gpX->GetHistogram()->Clone("h68");
+  h68->SetContour(2);
+  h68->SetContourLevel(1,0.32);
+  h68->SetLineWidth(3);
+  h68->SetLineColor(1);
+  h68->Draw("CONT3same");
+
+  gpX->SetTitle("");
+  gpX->GetXaxis()->SetTitle("r_{ggH}");
+  gpX->GetYaxis()->SetTitle("r_{qqH}");
+
+
+  gStyle->SetOptStat(0);
+  can->SaveAs("2D_FC.png");
+ }
+ 

+ ///
+
+It will produce the plot below.
+
+![](images/2D_FC.png)
 
-There are several options for reducing the running time, such as setting limits on the region of interest or the minimum number of toys required for a point to be included. Finally, adding the option `--storeToys` in this script will add histograms for each point to the output file of the test statistic distribution. This will increase the memory usage, as all of the toys will be kept in memory.
+There are several options for reducing the running time, such as setting limits on the region of interest or the minimum number of toys required for a point to be included.
diff --git a/docs/part3/images/2D_FC.png b/docs/part3/images/2D_FC.png
new file mode 100644
index 0000000000000000000000000000000000000000..e5e951c37e11872065e84ed7bb5beebb188c0b9b
GIT binary patch
literal 12358
zcmdUWc{r4B`}aL4vU`ZKBvB|b$xenegk<0MWE)!yNf=YMzJx3xYsfP8CHop*lr=GS
zA^ScV%M4?@x1R6wzQ5;>_pkS_*Ks&F-1l7fbzj$Yp66#d{iX9*je(Yv761SS^@k7i
z0D!^({03+!z`yh^*=K@3&OgyqdjS3fzlbW0K>%sOiKvD_XV>z?suV8Z3IP<-Q10&@k
z6g`aK};^zfJoWjzWuSGA&M0Y?R4STCtQUZ@A9NM)t
zghPZPvJV1M^5D9QepZS0aRR1^cc`cUdUwis!Q8hCbsqwhnV*^_3jD=<|D5gqDL9@J
zcqK%rw^F2c5|4P7AE*6Sc7Y^61Xx{ok8N=sa{YA0vS_I6yPPCvSk?)a5p`r7spzw|
zPSoJp``KAlGSp)1r_gseDH|a5)hDd-bT3}Z7xL_DH!tZyl;dOVGDiO;7$JCJ`JprO
ztuSjzE=;>{#I=3f%KuLOqv3_F#R`Zeq
z82yrk)9+Bbhl|KAxM2VRE@{l-xN0~x+2GhdK{Xx#aH;&2lG(CUDHL(D;-!0UtX`O{
ziDi=6eG=(iegy*$^XDf7Vds>Z0lz}gkGHHx3Dx1SV|Tpz0C-Jg
zpB5&$g1I4BRGG$4KlxP_P~x@CywC>?SnD<4`2nqi(nrlp8|)`mHCHK@-c8wB*cxgX
z(|P|SpqN4>ltXF7E;NZRMouT36_^XP8qQFU3$aZW_-nG@+Xn>z&G9k{d`-j10G?E9
z0C=WV7MqD`w+vD+sMZF6(X6qr+8U-j9%H9LqIelG*STSJ
z??`o&j-&s}?MCLWDc01Zq$9h2rtMUG3NM${(KV7BGYZ|i%#BjH;-yv_U+cj&wb^nw
zFBAwtoAQ%JJ8!ISwnpesp&=|N6*Ey>Vzan14RDVIMQL&q&kj#Ifz#XvR-IG0thy%p
zp0FAlUr|_}2w(Bt8JDQi{vzuUaT(bW$spC)7ATeaWE>|>*VVVd`y#S*lqICln4Svq
zDD~zwH)K!K@og2Wu-TQh!xU{sFLIW-?TGYZ|cabi88K+o-+lKGFjsy`JoteJT0Qm4>TB1NC(I2R9%TwN?at{kUwSOQxf5OMPcAsTSi`Fz=kHnXbIqIQ
zjt7$a*AFbxE|o5F#~%EBZ?3Q+%B7nR-G3zLOHK`3(A4ff{Y!LhO0pGkM;jh2*O#yO
zJ`a;n*%P@=^U(~i8TZN0a%F&sk%aB@8@jxIDHtxdGRBFjHYk^EQ$!Hb>2Z;UJnWl_
ztxivoR`06NGcqgT&ICemW`XY-{`5pUym|Ll5Si=bBuF=uV;|fAkI|Rx-#c-`$2{=Z
z$-%pi36e}wlf(ximZ;I~p^e550O5|kk)H1kBc?k0}C8r;sRmkN`L+B?yE4EBf3
zOfE2aK?;aWuNVKDiVsLGD+GMJQpCmb2luFJyteZUor>-yfOXk|a1ow0aA4TclFN8d
zX0!aw*ts7Do=pK+=`9SSfDzov%y*6c&Ejx%VwkMo@j;(8J21RpLAb!zQ#t+6P5bAs
zi$)O0qYUJHzIXRe9qB6U>@PpZF|bZR-J-*+Yn9y{dJ%~%DoTLI_2U72j2~bFwkv_v0B}BDD>L0~<%Sp?2xsGS%qzYlh1B$y;2(QS
zHAnqHH#JaaS2>^GijND(!8DKb1yMX3mgtDN(|tZR2$)`3O0hnaZJl(yd=RyxVRsT!
zq6(z_vL{Sr;`xbEq2Qz|FITj60mJ37)jFK&9W3p#NHL1y(`0kh?kiqc_(2
zu<7#QI?`y1)PZmGHAy*VqfMjB7Wy(xKs_a|%R!lW(eHLhLG^F1#eDaioKuhCd#^>i
zf&ioVJZD`tzlDE9$PHZD-`id#$5_8PD1Rxx~ja|Vn(hW-GHD|M0(={
zbnRp$mtA;>7{Q{fpV>q6Z0$@x`A&girOf6>aSt-5T-|cczb;Ag^6uC6sg>27`n!Bk
zzk0uQ!M}F1XcU4QD?0rZREjf9Otl!%(bl*eX3GXwW-bu^?r@i*LyW#--IEP|0J}@N
zPlnvxTRJ7I97MUOV`AQfFq&P
zBDSPJxiZc@v)
zO4ih0X4L6K2x)5|Cq#=j(s(aTDJTZ@k1u;flSjsvH#_b3KN>YEod!FseDL#pc|4xi
z_Thuph0nV$lEs~a6O^iyFGv()&k$C#ZqUus{&HjTFrn3$)m=nkkDl&7O0*9=z_+PQli1rD>Mx=Y_8?Tl
zanX~PF^NIkC;%$5(ymRDg=iFV_4yzQe(*@9c1nNEYS1;E+RmJ`HzF0JM`CT$;bv%c
zUz`qj7X(7WUffg*DZBBN)_$UNZ40!f0`t>r;g_ae>d-VzUpjH`N6|7JgMOQU%;b!8
z?H$Q+_i2*tQY$K~kb<(!cc6p_(b_zvf{L^=p{||+^lxy%(%>Gd@R8&_XmOEx47W$6rvgx
zMfv>F=asAO?mW>4&1r=ccAd*H*CKC1V?;H!##ie!O30dn|AHzrkB^}1%boPEq*{L*
z4lbHuc+S`_8Rp9UpC}Cu5bK+m|1fVn$@7*p*SyRLHCKXogSF!vh-ULRM7?wkdlgyWdPo4D;cp;ES%(z#g&3
zX9DcMy*hfyrCFPuspi)7yHTz;tHwXej$g@p93HFX7y6~A--I;37o0xJIYqijs8Vhi
zHaiENVXxhTt+s27wJ~mprsPonl`bhMLmQx&k{{Mb1CGijriRKqSq<+Ov_9<=lOE!z
z+wSS@gvkH!ACIX*SWrycjj>e+Z!%+SKm9$rd`pTt6h-YW`ZNBR*w=
zSL-~TWUczhp=z_siqrisCR5G0+jD-uy4oRxcliy8vMJu)G)@3?{}uBNWmx#N8soh&iu2^1$r>UHvn-5$&VQ^?@03-!|L$0m
zp~VlkV13e=EhVjj{8quW(vfhxv1ZuJzt`5W!(v(8>2|Gye&qJ=QldXkdU9)$UgNxV
z|3n5cyjB?f{I@ImhkZWvGB0A~*{5HA=%M^1E6a`j+yp~f4dEOivk`Hv;pjm*9+W4y
z7-t11Q~hbx4k>fro0j#<07siV!atw04>P1&EtCktAU$4@i}0a4D{JnA%WA~{+En)f
zM_AU8jy0RUsY$g&q7qV?^p@Y~qu}`09)`Dh0-J*q5Z&IUdAO|)rm&PTR#Ue=oNW6^K_OK&*?Fc+nU5NobEXV)quL!~~Fv6W&Y11vHObw(K&AWO;R4Rz7Du%D>J#9Vt
zxY&cx_bxDk6Y=doWtPflshd7(s*2Cdr#6mqd(NnK#PD}t;LC3ogl{ZwN$Ak&NAkc4
z3rdOO2JDskwKEB0VJU@og#^73eGkNJXCV!s6_XFB`b>zFH^Tl=HcW=7gFuAs_E`)7
zxz(Q!g>mGhnum8u8J*Lp30sSairla>d{yCOr+==i=R^HpTIw{ZK{{NmjD7E2YQ$Pi
z2pH;^jM?U#E4;If*r2JE8qAl_PI!+UzHCj$&?dUH)z-D@bdS}J%Vyyc5!6(=dt<>_
zl?xkx{=(}>M*mh94!+8Kf6sO8&kUg||09mwZk*{1N6aqL^dcqRKCrA$ka{?N;Wv9M0@qPf;(xP`08lVNW9_g
zvy+XG0uSS-gh)M}aS_@UfGcaz>V~?W)~odt=P}Ofw@X0=nqqIdZ)=*!wZ#b7Ku_n7
zVdnEio89-}x({>>N*Gmj7uCS%uM*MUh(`?R-5d9AMJGKgqPCGdT{_8}lrFuVtGLU0
zf3-s(y{A=S5PM{ODXd>P0Xdw3$kICrx&H<>wNm|6ryxzhS!Z~H;u&kHgU&iI^ziZrv1>xsl_bmLMZ@0+lnO0_v
zkLYq$QB6i6k$zQzS@m*BQ71F}cBwh>wk;e`744pV@=8t@61y<^E;75ohyPKO`Fws@
zg(r8>#N%r6*z|$3!XkO+fb7+O?;OSXptj_ZiI#PNU^)C5zj1!g=A6>ynU;q^V0fdx
zgXLC3a#BCt>hq@yKr++&XGcvR6={oA{Sj3U6YUM38(hX9-8(dqutB|4i&wFp%S@M|
z62u3QhKq3CK6T;!lQfXM*_&3oT8eqQEE>bpGgf+U`%nORJ&KGC=5o@z;0z1L^F~Ro
z2U`Hw-+H`rJhiGQYZzwf&ppa7se
zrAcz{&Q3TOZ8?G~)Ll|TxvgBeVz2CVFLEtaFOWGdz-I5(T&|++i)xil3aKMTbkfz?
zyYCW6l6I*lmiR+N32W8K+z<#`M;1T?zteOaTd$%*b2t#?)?*iG?08jeY!+HG5p?to
z6dTyR+-n5^U_+Gv39bjZxJka^__tSo3=-5Y&z8!IvE_ShGw_UhIHT?1L*+J}eiqAu>&T&ZFy352#!3tY($+KGGS%ZCv_88hDpD-U&6TX|;m*T3rSS8f
zcumFcz0Rfeik7XV#jU9$6XrHm=FkQ{|s1JDWVzopi?;|&onXDd9sf#)lZiL6g^G3DpYkxSatyPhwuDa
z4CEBI!lsAA1~e5y=Pc=4M~S936bNeaKUJmc0MAS62Fv*bpU$N)M0uT)4@k!&vz>;U
z0id`uCTO4IPa$Vo2w^VaZ=DRtLX6VGR-~HP;CvzP^lBb2Q?v{x9f6|Bq?0u;xSCZi
zbQLj?b;TdLt50e8er5eMRsUm2__Q?w*B_iq{@Y1Tp%LMV+|op*rf&=$dD~5vZYB5r
zH9=AtPf+szS4tWFpS|z9K5>?G_b{wmzt^y34Y$3T+(@cY?aiQivHQa1-A<^ie*k$h
zrBs1XqXxbOBY~kofm=Z(Rl!PPAo_a=lG&GiHQH?%36&aO;4V)Q
z@x9sn=!+|PAa5B_D^`zl{VWdvf~!;Vxe0JxgA4gm&y7U)`O(;+Hjx>ioC2m2}X
z&e7&MNf?C7IYm|XQy%4lOz8m0(A4B!bhc2m9ab+r(!;91#97>3nLv!7IvAk`{)%dOy!0+iEy$
zo(_a&GG|ZX+g$|#8=f>eSg!nmnPBAG6<%O$q%i#sfl_tBiQw}mtX^D3sY)512jMda
zJbUL(8GdAfB2Fm$wn(YImHd@Yu%EKyQb}Kldn7}<)YL4Zoc3$VvowG-Ovz!z!(O`K
z#=L8M9hzQiF(gMix*K}PHju+A`pLuEs%vx(J^M&hTfnn9rb`U}m;>X`z)ZSem<{)T
z;s-CY2)ymdnJ&nTv>(0BfL4Zpo6krJ6!;v5XJGBeUO
z#P~J~6DroKRu{5b(9y3-vaN452S?hKu;+L50%#Uw8fWztFZcGR&=;5^l{7Qf=JI93l4r#Kv|=*-`0x{D6N0OUE|=b^YLyZ
zJX7v+t)Mb<$QgoP`aKFJ#?k25Gn1r=n^^5m<(Nkk?;Wr+`m>SOt%0L$1l*NHZlEtd
zL7awyFC_4IwCj;S#qI1k%I^XpZ$JxT0ZKnCQSCZ=B%BXMEav_duu?jwu)||l{7e(o
zkWd9qOa#fvx`DH!G&W9E#hnOZ_SI=IC8cKLmKS;FKWfMIrZk%_7<{1YgWdl@n^p}21nl~5?#E}>PV!zNag
zfwAl_iOnQa7GTUJ&mp*RqvwMRx&icG>ca*am@fEDx_#ZbN@}WU+Sbv(EE!3*HP2^{
z-`(NW!StZ8UbaJ
wDEA1ZkM{}Tmrmn&ep2pZ}@7rPkBF2tBFpODhrJ4W$N|CRI
ziv0Z8W4rk{RuTUVyt({M(tNkNB50ggg;`Sv;(QN&c^MA};;|VC%X;^uZwETNBA+41
z4r6^u7oKY|-0mAgm$AQhhfT@fMU`k>kQn>l6gX$^9IM2VB<$b~C19o{OG00mQ?+c9
zdjuuzT~t0F1fcUSfOQ9$$-9i|V}k&4V7W#P$+nJmMIL+w@oH}`ZXt~q_!#5-*niYP
zapHgi_^u@d#+}LEz0TU2Gl%!({#>GIRL7{nt4#ncMbwn(Si3a{|hy8Kn1Kiu%OVb$wkzllEEN0)jc)C
z@VE?By{fM{vpD~o=mJismNClB-QwuS`10I{g=g1l3h~&)@YUsr3IQ!5GF)TM+bE2(u@5w=3;tS0X-Bxn|n$cu)Ubo<(#Fae~v{}%c%
zdD6Ff#c5v4M5p$HB}FDWM@TPy0N*4O5&eQ1=mSF;#PBS!J)xuCUn@l-vJrC$0_q!J
z^?{wNu-t#3D=|mPSHu%1Vo)+8_7H&o`wB(8fN(_i#En5@DqlRZ@g81bET}14hHV-HR-YlHeWs`*Y;D%e*$&>go?a@&&pv~c-aFM{>=yO>2
zBnd6Bfc6W^H7w`9Hrw(84Nm$FTd`6m>de{ZyPKU5Ah>FlXiW!~^c{bsvC>{P3TFq8
zV#F0@y`E9b7jP9L?fW;u()lT&gj)PONKXM$_P_zA8zHE9(aSl-=r@>5Ti6RSJi;=~
zT~LN%hE1Bn*uSE*4(Wh$Tg0J5HM0?@-c^>rwNUPy4%avAlWdXR^$+mKP_RT#u0Pp4ocjusc_SB~6lE`TDOHvO
z)g$vEpNR|r_<68G%abO2Q?)snPOG2nvRciR$!dXTo@wW-7a&8RtsFdQSg(QeL~38C
zD5N+hY2NXvK5lKN%*u!f%q}|Crhcfy$NR-Bn!|J~gQ5jrU^ru`BFmx^q{S_)q~OxQ
zyjG&ZiPe6V)j{sElkY5{`N~epF%r4)ecI_=t06ZixEp@3e-Ja+f89U&ao_1GSoC`&
zAKxK6p1bsKWZxQEn%g=Ad&5%&KgJz|q%K-zB(P)kG?4KiLrZL?fV#aU
z8D))4t_(h>50%xnk+6y;Nxc{-yBN+3w26VK?>w@!@^E)ikQk1IA^}&b;f$i98K(r_
zJAjF_aBf0nkfvIPHp*_8=Z@1dFAI(T2%akO+W&zPTTbj@w!WGi9cAmE*AMd=?Y;*L
zUONSBp8YqdkW-4&1LHzK-4rCKAW4|~QIBK2Po?}3)l?~B$nM^te}0kI2uIpZU%%6#
z*amhu2&fyV7JRYTcvpHLe9`|(NT!DC{=zxscLLw?{GXoLZ?dP1fQunKSR*`J$ZTqy
zDjdv2IYR5n-+Z_agV5K*0+UMyhj&VFh6mSThGH7Hn(FsMe_#8PP+O`P#toBr&`-L1=3AJjB+
z{`z;oMrhqNlame85#X0mq@C+*hJ}BtEcThw6s4P?g<*a89+b?I86n?btLxV-!zMT>
z`d(|)AqI0$LXYjUewx5P4g}*|o=?u=T>4?pYX@2NXO*D*WazXI>oS89je1gB^{`bphTvx^@q|89s()kMSGz
zix6jR!2*9W_UFA1=k_1s1!f2Ck{2kZmzIJud4q8A%kifK>yt69J^P2%`pmQ}tBM2V
zls|uqlWx32MoKWX-&+5$MI9qGBKCO!99dYb!(*2nJ_l+gudmkKr;_{Vqno%$8So{H
z!*{FY&~_sg6QShV173cp*yfApAx?}G%G`r;9GmE0OzwHSAY=1BsNdHdxy9Z{dqe8|
z6AL>$a$>dg=MPSQ>z#Fr7Q(lK-_L!6BON;o96X~c9%nWrtemES
zu^`)L9+YiJFtZeUm8xur2zB!vt&Xerws9u^ORR(G;$tet&~ZwKP+Tg-welEvh1xQN
zRh6LCz3tEIZjBlWxFtwoerJSo`7JJ$^P*SewRdcr(aj)I@Zt5MhB6G(!%~k}{>VgU
zI@4%Iy?DEC^k5@b+E(BR)8tDbE6mR$`7UW~K~8{YN~Tq@8Q0iG(ze(A(D~!)Ig7AD
zj4ghO@llsV2a|>x)w((~+*I-LCgi){WmFp8Tw|Z?{z%#WiRr^lh|{h(>1#cA`EKRiZXuIM@LIgvYlXv;IpgO>jvLd=kf#^r8L)5MZY
zA2|?PoTX3YT{n$PnN9rlz<1Bv1TZpR@fI|(XSQKv7hF%{j6m@igIcSBlSczb0ha({
zID8U8)?Fus;Lw%7XGh@IR6O*y;$%
z55vML*s4pP^xjrb^`XNGZ`{orDlDZB1y`|mu9dHq_rQx&^}m}PyZ=~)pp@~S37*k`
z|MW^qhmFEDl0fLOoYz?Xxg#^sci7S-#kZ`=xAmLi!9*jYKj@SETU5O9El>P)1#MsQ
zIc4tRL~*mE^8x8InE5AouDTX4uC}lL!!7`Y(tm3Qe`wgGYZ7Nw6hrC;iM&$lFIDbp
z*Wr-=E7{GJe!p4OKRx_NRm!c4q;>GSRnd-XM^3>j(-IVhnor5cJFTbWJbwuAEHXh)
zW8zc}>~CWJRZ{!&Z9)8QEiAfrsf0@9dn+e>-QlPh`yq1JH%a9xD}0_eye
zAMUi`2juA?5a7Qtgd@$W1)&+dbhtBnN=fP(;*oYG97)eLzIY4T}@AT+J(r0hg#=rQi*=XIrf|7NKH%fQ`(-
z4!+1zb`XD+W+W{?`*}z)xAg4{ygo7`LXp-0w3~6pnTO8;7X?FfH0_E!Jty^N=iAc+
z0i_||x;+KloDpHoP7wgu0{f(CKzU$D%^$8S;iw1!?iz3r_tnF{S6}}up#IZug$G-7
zI2&|&wjcyt7AH#~uRo5&8=-ZWvf%9)#EmtVZXBDrBWAT&7@u*_pTjZnC0c7|>q%OY
zoYt^NuYue{;RTrie89d(!>-YXeGHF}li~*u5*?d3PTUi-3c4O~joR8VHM;)vTI2M+
z-WFN%wW9P_?}Z|yW^z0x4*P#|m`YDZD%dc~93d0~2s$v_$C}SZ)WXU=!*u&@@KzApnZEN4
z1P38UTA0(`jA&2CiubmF!xuevFf~g3x*tkCzp@Eys&qYUhxS#vfF2NG($-dsBE4z%Zrg9Bf=k2PzT`|_rF+BJ|8mo(sq!Q5!D=7L
z^r}Gf8asC~*i|5`XSAAH1&jQ(>z^JtoAxr+MKi9LSP~k%ppd>W6YR35{N5!AXev8wqbQ@#5LC`Bc_l4|JzLvqJCfd
z*&Y~mXG+gRKL4{HkB2433SzCx_*WLD_P!5CD8`PbIZW3@Z(mo}>pwrjsEc8e9V_Z7MYH_s6d;3w3&t88Shv~}5E!S@|##LRzv|`oP6O(Vg
zV`$1e@jmWb$!cP|*|MctheZ;9j^-?_7^?ZJ+?drGXj!kC&zmx!mx}(d`?+os?D7DTF@7Ky_^$?Wz#NhK2u?GO9iSDpxQ7{7zB{b+r#F5kIjSe*wp)H1Plc

literal 0
HcmV?d00001

diff --git a/docs/part3/images/2D_LHScan.png b/docs/part3/images/2D_LHScan.png
new file mode 100644
index 0000000000000000000000000000000000000000..7f2b018ebe20c071144395e794f98072e4e6be4b
GIT binary patch
literal 11029
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
Date: Thu, 21 Mar 2024 11:12:17 +0000
Subject: [PATCH 2/7] nicer figure for LH Scan

---
 docs/part3/commonstatsmethods.md |   8 ++++----
 docs/part3/images/2D_LHScan.png  | Bin 11029 -> 11118 bytes
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/part3/commonstatsmethods.md b/docs/part3/commonstatsmethods.md
index fdec21507e0..e0fef2dfe84 100644
--- a/docs/part3/commonstatsmethods.md
+++ b/docs/part3/commonstatsmethods.md
@@ -851,13 +851,13 @@ As usual, any *floating* nuisance parameters will be *profiled*. This behaviour
 
 For most of the methods, for lower-precision results you can turn off the profiling of the nuisance parameters by using the option `--fastScan`, which for complex models speeds up the process by several orders of magnitude. **All** nuisance parameters will be kept fixed at the value corresponding to the best fit point.
 
-As an example, let's produce the $-2\Delta\ln{\mathcal{L}}$ scan as a function of **`r_ggH`** and **`r_qqH`** from the toy $H\rightarrow\gamma\gamma$ datacard.
+As an example, let's produce the $-2\Delta\ln{\mathcal{L}}$ scan as a function of **`r_ggH`** and **`r_qqH`** from the toy $H\rightarrow\gamma\gamma$ datacard. The command below should be pretty fast, as the statistical model is quite simple,
 
 ```sh
-combine toy-hgg-125.root -M MultiDimFit --algo grid --points 2000 --setParameterRanges r_qqH=0,12:r_ggH=-1,4 -m 125
+combine toy-hgg-125.root -M MultiDimFit --algo grid --points 2500 --setParameterRanges r_qqH=0,12:r_ggH=-1,4 -m 125
 ```
 
-The scan, along with the best fit point can be drawn using ROOT using something like the script below,
+The scan, along with the best fit point and $1\sigma$ CL contour can be drawn using ROOT using something like the script below,
 
 /// details | **Show script**
 

@@ -868,7 +868,7 @@ void plot2D_LHScan(){
 
   // create histogram representing -2Delta Log(L)
   TCanvas *can = new TCanvas("c","c",600,540);
-  limit->Draw("2*deltaNLL:r_qqH:r_ggH>>h(44,-1,4,44,0,12)","2*deltaNLL<50","prof colz");
+  limit->Draw("2*deltaNLL:r_qqH:r_ggH>>h(50,-1,4,50,0,12)","2*deltaNLL<50","prof colz");
   TH2F *g2NLL = (TH2F*)gROOT->FindObject("h");
 
   g2NLL->SetName("g2NLL");
diff --git a/docs/part3/images/2D_LHScan.png b/docs/part3/images/2D_LHScan.png
index 7f2b018ebe20c071144395e794f98072e4e6be4b..c2f98f83990e275223a97751053895431c0091de 100644
GIT binary patch
literal 11118
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

literal 11029
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
Date: Thu, 21 Mar 2024 15:26:51 +0000
Subject: [PATCH 3/7]  fix notation for FC

---
 docs/part3/commonstatsmethods.md | 33 +++++++++++++++++---------------
 1 file changed, 18 insertions(+), 15 deletions(-)

diff --git a/docs/part3/commonstatsmethods.md b/docs/part3/commonstatsmethods.md
index e0fef2dfe84..caaa2c9a445 100644
--- a/docs/part3/commonstatsmethods.md
+++ b/docs/part3/commonstatsmethods.md
@@ -978,11 +978,11 @@ combine -m 123 -M MultiDimFit -d higgsCombineteststep1.MultiDimFit.mH123.root -w
 
 The Feldman-Cousins (FC) procedure for computing confidence intervals for a generic model is,
 
--   use the profile likelihood ratio as the test statistic, $q(x) = - 2 \ln \mathcal{L}(x,\hat{\hat{\nu}}(x))/\mathcal{L}(\hat{x},\hat{\nu})$ where $x$ is a point in the (N-dimensional) parameter space, and $\hat{x}$ is the point corresponding to the best fit. In this test statistic, the nuisance parameters are profiled, both in the numerator and denominator.
--   for each point $x$:
-    -   compute the observed test statistic $q_{\mathrm{obs}}(x)$
-    -   compute the expected distribution of $q(x)$ under the hypothesis of $x$ as the true value.
-    -   accept the point in the region if $p_{x}=P\left[q(x) > q_{\mathrm{obs}}(x)| x\right] > \alpha$
+-   use the profile likelihood ratio as the test statistic, $q(\vec{\mu}) = - 2 \ln \mathcal{L}(\vec{\mu},\hat{\hat{\vec{\nu}}}(\vec{\mu}))/\mathcal{L}(\hat{\vec{\mu}},\hat{\vec{\nu}})$ where $\vec{\mu}$ is a point in the (N-dimensional) parameter space, and $\hat{\vec{\mu}}$ is the point corresponding to the best fit. In this test statistic, the nuisance parameters are profiled, both in the numerator and denominator.
+-   for each point $\vec{\mu}$:
+    -   compute the observed test statistic $q_{\mathrm{obs}}(\vec{\mu})$
+    -   compute the expected distribution of $q(\vec{\mu})$ under the hypothesis of $\vec{\mu}$ as the true value.
+    -   accept the point in the region if $p_{\vec{\mu}}=P\left[q(\vec{\mu}) > q_{\mathrm{obs}}(\vec{\mu})| \vec{\mu}\right] > \alpha$
 
 With a critical value $\alpha$.
 
@@ -992,14 +992,14 @@ In Combine, you can perform this t
 combine workspace.root -M HybridNew --LHCmode LHC-feldman-cousins --clsAcc 0 --singlePoint  param1=value1,param2=value2,param3=value3,... --saveHybridResult [Other options for toys, iterations etc as with limits]
 ```
 
-The point belongs to your confidence region if $p_{x}$ is larger than $\alpha$ (e.g. 0.3173 for a 1σ region, $1-\alpha=0.6827$).
+The point belongs to your confidence region if $p_{\vec{\mu}}$ is larger than $\alpha$ (e.g. 0.3173 for a 1σ region, $1-\alpha=0.6827$).
 
 !!! warning
     You should not use this method without the option `--singlePoint`. Although Combine will not complain, the algorithm to find the crossing will only find a single crossing and therefore not find the correct interval. Instead you should calculate the Feldman-Cousins intervals as described above.
 
 ### Physical boundaries
 
-Imposing physical boundaries (such as requiring $\mu>0$ for a signal strength) is achieved by setting the ranges of the physics model parameters using
+Imposing physical boundaries (such as requiring $r>0$ for a signal strength $r$ ) is achieved by setting the ranges of the physics model parameters using
 
 ```sh
 --setParameterRanges param1=param1_min,param1_max:param2=param2_min,param2_max ....
@@ -1007,15 +1007,15 @@ Imposing physical boundaries (such as requiring $\mu>0$ for a signal strength) i
 
 The boundary is imposed by **restricting the parameter range(s)** to those set by the user, in the fits. Note that this is a trick! The actual fitted value, as one of an ensemble of outcomes, can fall outside of the allowed region, while the boundary should be imposed on the physical parameter. The effect of restricting the parameter value in the fit is such that the test statistic is modified as follows ;
 
-$$q(x) = - 2 \ln \mathcal{L}(x,\hat{\hat{\theta}}(x))/\mathcal{L}(\hat{x},\hat{\nu}),$$
+$$q(\vec{\mu}) = - 2 \ln \mathcal{L}(\vec{\mu},\hat{\hat{\vec{\nu}}}(\vec{\mu}))/\mathcal{L}(\hat{\vec{\mu}},\hat{\vec{\nu}}),$$
 
-if $\hat{x}$ in contained in the bounded range
+if $\hat{\vec{\mu}}$ in contained in the bounded range
 
 and,
 
-$$q(x) = - 2 \ln \mathcal{L}(x,\hat{\hat{\nu}}(x))/\mathcal{L}(x_{B},\hat{\hat{\nu}}(x_{B})),$$
+$$q(\vec{\mu}) = - 2 \ln \mathcal{L}(\vec{\mu},\hat{\hat{\vec{\nu}}}(\vec{\mu}))/\mathcal{L}(\vec{\mu}_{B},\hat{\hat{\vec{\nu}}}(\vec{\mu}_{B})),$$
 
-if $\hat{x}$ is outside of the bounded range. Here $x_{B}$ and $\hat{\hat{\nu}}(x_{B})$ are the values of $x$ and $\nu$ which maximise the likelihood *excluding values outside of the bounded region* for $x$ - typically, $x_{B}$ will be found at one of the boundaries which is imposed. For example, if the boundary $x>0$ is imposed, you will typically expect $x_{B}=0$, when $\hat{x}\leq 0$, and $x_{B}=\hat{x}$ otherewise.
+if $\hat{\vec{\mu}}$ is outside of the bounded range. Here $\vec{\mu}_{B}$ and $\hat{\hat{\vec{\nu}}}(\vec{\mu}_{B})$ are the values of $\vec{\mu}$ and $\vec{\nu}$ which maximise the likelihood *excluding values outside of the bounded region* for $\vec{\mu}$ - typically, $\vec{\mu}_{B}$ will be found at one of the boundaries which is imposed. For example if there is one parameter of interest $\mu$ , if the boundary $\mu>0$ is imposed, you will typically expect $\mu_{B}=0$, when $\hat{\mu}\leq 0$, and $\mu_{B}=\hat{\mu}$ otherewise.
 
 This can sometimes be an issue as Minuit may not know if has successfully converged when the minimum lies outside of that range. If there is no upper/lower boundary, just set that value to something far from the region of interest.
 
@@ -1037,11 +1037,15 @@ combine workspace.root -M HybridNew --LHCmode LHC-feldman-cousins --readHybridRe
 
 The output tree will contain the values of the POI that crosses the critical value ($\alpha$) - i.e, the boundaries of the confidence intervals.
 
-You can produce a plot of the value of $p_{x}$ vs the parameter of interest $x$ by adding the option `--plot `.
+You can produce a plot of the value of $p_{\vec{\mu}}$ vs the parameter of interest $\vec{\mu}$ by adding the option `--plot `.
 
 #### Extracting 2D contours / general intervals
 
-For *two-dimensional* models, or if the parameter does not behave like a cross section, you will need to extract the contours from the output of `HybridNew` and plot them yourself. We will use the `toy-hgg-125.txt` datacard in the example below to demonstrate how this can be done.
+For *two-dimensional* models, or if the parameter does not behave like a cross section, you will need to extract the contours from the output of `HybridNew` and plot them yourself. We will use the `data/tutorials/multiDim/toy-hgg-125.txt` datacard in the example below to demonstrate how this can be done. Let's build the model again as we did in the MultiDimFit section.
+
+```sh
+text2workspace.py -m 125 -P HiggsAnalysis.CombinedLimit.PhysicsModel:floatingXSHiggs --PO modes=ggH,qqH toy-hgg-125.txt -o toy-hgg-125.root
+```
 
 First, we use `combineTool.py` to create jobs for each point in our parameter scan. We want to impose the boundaries that $r_{ggH}>0$, $r_{qqH}>0$.
 In the example below, we will run in interactive mode so this can take a little while. You can instead run in batch or grid submission mode to submit jobs for each point. We configure the tool by specifying the grid of points in `grid.json` as below. Here we want 5000 toys for each point.
@@ -1060,7 +1064,6 @@ In the example below, we will run in interactive mode so this can take a little
   "max_toys": 50000,
   "output_incomplete" : true,
   "contours":["obs"],
-  "make_plots": true,
   "CL": 0.95,
   "output": "FeldmanCousins.root",
   "zipfile"         : "collected.zip",
@@ -1079,7 +1082,7 @@ Once this is done, we extract the contours using
 combineTool.py -M HybridNewGrid  ./grid.json -d toy-hgg-125.root --task-name fc2d --job-mode 'interactive' --cycles 0 --output
 ```
 
-which will produce a file `FeldmanCousins.root` that contains a `TGraph2D` which stores the calculated value of $p_{x}$ for each point in the grid. The script below can be used to draw these values and extract the contour corresponding to 68% CL ($\alpha=0.32$).
+which will produce a file `FeldmanCousins.root` that contains a `TGraph2D` which stores the calculated value of $p_{\vec{\mu}}$ for each point in the grid. The script below can be used to draw these values and extract the contour corresponding to 68% CL ($\alpha=0.32$).
 
 /// details | **Show script**
 


From 28848e202e6833687fa13324c31aeb7908f9c393 Mon Sep 17 00:00:00 2001
From: nckw 
Date: Thu, 21 Mar 2024 15:29:32 +0000
Subject: [PATCH 4/7]  fix notation for FC

---
 docs/part3/commonstatsmethods.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/part3/commonstatsmethods.md b/docs/part3/commonstatsmethods.md
index caaa2c9a445..94ece963648 100644
--- a/docs/part3/commonstatsmethods.md
+++ b/docs/part3/commonstatsmethods.md
@@ -1064,7 +1064,7 @@ In the example below, we will run in interactive mode so this can take a little
   "max_toys": 50000,
   "output_incomplete" : true,
   "contours":["obs"],
-  "CL": 0.95,
+  "CL": 0.68,
   "output": "FeldmanCousins.root",
   "zipfile"         : "collected.zip",
   "statusfile"      : "status.json"

From 49306a0998a2e0f7a40a8be76a946cf6b4ea6b32 Mon Sep 17 00:00:00 2001
From: nckw 
Date: Thu, 21 Mar 2024 15:31:51 +0000
Subject: [PATCH 5/7]  small fix in description

---
 docs/part3/commonstatsmethods.md | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/docs/part3/commonstatsmethods.md b/docs/part3/commonstatsmethods.md
index 94ece963648..103929357df 100644
--- a/docs/part3/commonstatsmethods.md
+++ b/docs/part3/commonstatsmethods.md
@@ -1048,7 +1048,7 @@ text2workspace.py -m 125 -P HiggsAnalysis.CombinedLimit.PhysicsModel:floatingXSH
 ```
 
 First, we use `combineTool.py` to create jobs for each point in our parameter scan. We want to impose the boundaries that $r_{ggH}>0$, $r_{qqH}>0$.
-In the example below, we will run in interactive mode so this can take a little while. You can instead run in batch or grid submission mode to submit jobs for each point. We configure the tool by specifying the grid of points in `grid.json` as below. Here we want 5000 toys for each point.
+In the example below, we will run in interactive mode so this can take a little while. You can instead run in batch or grid submission mode to submit jobs for each point. We configure the tool by specifying the grid of points in `grid.json` as below. Here we want 5000 toys for each point, and we choose a grid of $r_{ggH}\in [0,4]$ in steps of 0.2, and $r_{qqH}\in[0,10]$ in steps of 0.5.
 
 ```
 {
@@ -1077,7 +1077,8 @@ The command will look like
 combineTool.py -M HybridNewGrid  ./grid.json -d toy-hgg-125.root --task-name fc2d --job-mode 'interactive' --cycles 1
 ```
 
-Once this is done, we extract the contours using
+Once this is done, we extract the values of $p_{\vec{\mu}}$ for each point in our parameter space using
+
 ```sh
 combineTool.py -M HybridNewGrid  ./grid.json -d toy-hgg-125.root --task-name fc2d --job-mode 'interactive' --cycles 0 --output
 ```

From 456b0f9dc5ca98ae74c6aead36821136f0ce2fd2 Mon Sep 17 00:00:00 2001
From: nucleosynthesis 
Date: Tue, 26 Mar 2024 17:12:54 +0000
Subject: [PATCH 6/7]  few more details for 2D FC

---
 docs/part3/commonstatsmethods.md | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/docs/part3/commonstatsmethods.md b/docs/part3/commonstatsmethods.md
index 103929357df..743cb312022 100644
--- a/docs/part3/commonstatsmethods.md
+++ b/docs/part3/commonstatsmethods.md
@@ -1048,7 +1048,7 @@ text2workspace.py -m 125 -P HiggsAnalysis.CombinedLimit.PhysicsModel:floatingXSH
 ```
 
 First, we use `combineTool.py` to create jobs for each point in our parameter scan. We want to impose the boundaries that $r_{ggH}>0$, $r_{qqH}>0$.
-In the example below, we will run in interactive mode so this can take a little while. You can instead run in batch or grid submission mode to submit jobs for each point. We configure the tool by specifying the grid of points in `grid.json` as below. Here we want 5000 toys for each point, and we choose a grid of $r_{ggH}\in [0,4]$ in steps of 0.2, and $r_{qqH}\in[0,10]$ in steps of 0.5.
+In the example below, we will run in interactive mode so this can take a little while. You can instead run using a batch cluster (eg `condor`) or the grid (`grid`) to submit sepaerate jobs for each point / set of points. We configure the tool by specifying the grid of points in `poi_grid_configuration.json` as below. Here we want 5000 toys for each point, and we choose a grid of $r_{ggH}\in [0,4]$ in steps of 0.2, and $r_{qqH}\in[0,10]$ in steps of 0.5.
 
 ```
 {
@@ -1071,16 +1071,17 @@ In the example below, we will run in interactive mode so this can take a little
  }
 ```
 
-The command will look like
+The command will look like,
 
 ```sh
-combineTool.py -M HybridNewGrid  ./grid.json -d toy-hgg-125.root --task-name fc2d --job-mode 'interactive' --cycles 1
+combineTool.py -M HybridNewGrid  ./poi_grid_configuration.json -d toy-hgg-125.root --task-name fc2d --job-mode 'interactive' --cycles 1
 ```
 
-Once this is done, we extract the values of $p_{\vec{\mu}}$ for each point in our parameter space using
+As mentioned, this will take a while to run so you should consider going to make a cup of coffee at this point and reading through the [HybridNewGrid documentation](http://cms-analysis.github.io/CombineHarvester/md_docs__hybrid_new_grid.html) to learn more about this tool.
+Once this is done, we extract the values of $p_{\vec{\mu}}$ for each point in our parameter space using the same command, but this time setting `--cycles 0` and adding the option `--output`,
 
 ```sh
-combineTool.py -M HybridNewGrid  ./grid.json -d toy-hgg-125.root --task-name fc2d --job-mode 'interactive' --cycles 0 --output
+combineTool.py -M HybridNewGrid  ./poi_grid_configuration.json -d toy-hgg-125.root --task-name fc2d --job-mode 'interactive' --cycles 0 --output
 ```
 
 which will produce a file `FeldmanCousins.root` that contains a `TGraph2D` which stores the calculated value of $p_{\vec{\mu}}$ for each point in the grid. The script below can be used to draw these values and extract the contour corresponding to 68% CL ($\alpha=0.32$).

From 887d6e6994332ab01292fc4b075115b334f54da4 Mon Sep 17 00:00:00 2001
From: nucleosynthesis 
Date: Tue, 26 Mar 2024 17:23:49 +0000
Subject: [PATCH 7/7]  need to specify make_plots false!

---
 docs/part3/commonstatsmethods.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/docs/part3/commonstatsmethods.md b/docs/part3/commonstatsmethods.md
index 743cb312022..44fd3d6c927 100644
--- a/docs/part3/commonstatsmethods.md
+++ b/docs/part3/commonstatsmethods.md
@@ -1063,6 +1063,7 @@ In the example below, we will run in interactive mode so this can take a little
   "min_toys": 5000,
   "max_toys": 50000,
   "output_incomplete" : true,
+  "make_plots": false,
   "contours":["obs"],
   "CL": 0.68,
   "output": "FeldmanCousins.root",
@@ -1084,7 +1085,7 @@ Once this is done, we extract the values of $p_{\vec{\mu}}$ for each point in ou
 combineTool.py -M HybridNewGrid  ./poi_grid_configuration.json -d toy-hgg-125.root --task-name fc2d --job-mode 'interactive' --cycles 0 --output
 ```
 
-which will produce a file `FeldmanCousins.root` that contains a `TGraph2D` which stores the calculated value of $p_{\vec{\mu}}$ for each point in the grid. The script below can be used to draw these values and extract the contour corresponding to 68% CL ($\alpha=0.32$).
+which will produce a file `FeldmanCousins.root` (as defined in the `"output"` field of `poi_grid_configuration.json`) that contains a `TGraph2D` which stores the calculated value of $p_{\vec{\mu}}$ for each point in the grid. Using something like the macro below, these values can be plotted along with a contour corresponding to 68% CL ($\alpha=0.32$).
 
 /// details | **Show script**