Adding documentation for Data/MC Plots

changelog.md

@@ -2,6 +2,7 @@
 
 ### [Latest]
 
+- Adding documentation for Data/MC plots [!211](https://github.com/umami-hep/puma/pull/211)
 - Update linters [!210](https://github.com/umami-hep/puma/pull/210)
 - Fix tagger discriminant bug, add future imports [!209](https://github.com/umami-hep/puma/pull/209)
 - Add weight support for efficiency calculation [!206](https://github.com/umami-hep/puma/pull/206)

docs/source/examples/histograms.md

@@ -56,4 +56,20 @@ underflow/overflow bins.
 
 ```py
 §§§examples/plot_histogram_underoverflow.py§§§
+```
+
+## Data/MC histograms
+
+To visualize the agreement of the Monte-Carlo with data, `puma` is also able to produce
+so-called Data/MC histograms. They show the data as a dot histogram while the MC is still
+a stacked histogram. An example of this plot can be seen here:
+
+<img src=https://github.com/umami-hep/puma/raw/examples-material/data_mc_example.png width=500>
+
+The code to create this example can be found in the `examples` folder in the `plot_data_mc.py`.
+Similar to the rest of the `Puma.HistogramPlot` examples shown here, a lot of more optional
+argument can be passed.
+
+```py
+§§§examples/plot_data_mc.py§§§
 ```

examples/plot_data_mc.py

@@ -5,20 +5,33 @@
 
 from puma import Histogram, HistogramPlot
 
+# Generate two MC contributions and data
 rng = np.random.default_rng(42)
 mc1 = rng.normal(size=10_000)
 mc2 = rng.normal(size=20_000)
 data = rng.normal(size=30_000)
 
+# Set up the real plot
 data_mc_plot = HistogramPlot(
     bins_range=[-2, 2],
     n_ratio_panels=1,
     stacked=True,
     norm=False,
 )
+
+# Set the plot title
 data_mc_plot.title = "Test Data/MC Plot"
-data_mc_plot.add(Histogram(mc1, label="MC Process 1", colour="b"))
-data_mc_plot.add(Histogram(mc2, label="MC Process 2", colour="r"))
-data_mc_plot.add(Histogram(data, label="MC Process 2", is_data=True, colour="k"))
+
+# Add the different MC contributions to the plot
+data_mc_plot.add(Histogram(mc1, label="MC Process 1"))
+data_mc_plot.add(Histogram(mc2, label="MC Process 2"))
+
+# Add the data
+data_mc_plot.add(Histogram(data, label="Data", is_data=True, colour="k"))
+
+# Draw the plot
 data_mc_plot.draw()
+
+# Add the bin width to the y-axis label
+data_mc_plot.add_bin_width_to_ylabel()
 data_mc_plot.savefig("data_mc_example.png")