Merge pull request #140 from cyrraz/example-category-axis

Add example showing how to plot categorical data

docs/basics/1d_hist.rst

@@ -248,10 +248,47 @@ In this example, the data points and the error bars are the average value and th
 
 Note that most functions in ``plothist`` work only with counting histograms and will raise an error if you try to use them with a mean histogram.
 
+
 .. literalinclude:: ../examples/1d_hist/1d_profile.py
     :language: python
     :start-after: ###
 
 .. image:: ../img/1d_profile.svg
     :alt: Profile plot
     :width: 500
+
+Histogram with category axis
+============================
+
+The function :func:`make_hist() <plothist.histogramming.make_hist>` returns a a `boost_histogram.Histogram <https://boost-histogram.readthedocs.io/en/latest/user-guide/histogram.html>`_ with a regular or a variable axis, but the ``boost_histogram`` package also supports categorical axes.
+
+The examples below show how to create a histogram with a category axis in ``boost_histogram`` and plot it with ``plothist``.
+
+
+Integer category
+----------------
+
+.. literalinclude:: ../examples/1d_hist/1d_int_category.py
+    :language: python
+    :start-after: ###
+
+.. image:: ../img/1d_int_category.svg
+    :alt: Integer category plot
+    :width: 500
+
+.. note::
+    When we create the histograms in this example, we use the argument ``storage=bh.storage.Weight()``.
+    This is because the functions in ``plothist`` assume histograms with a storage that supports weighted data, where the variance of each bin is tracked (more details `here <https://boost-histogram.readthedocs.io/en/latest/user-guide/storage.html#weight>`_ and `there <https://boost-histogram.readthedocs.io/en/latest/api/boost_histogram.html#boost_histogram._internal.hist.Histogram.variances>`_).
+    When creating histograms with regular or variable axes with the function :func:`make_hist() <plothist.histogramming.make_hist>`, as in most of the previous examples, the storage is automatically set to ``bh.storage.Weight()``, so the user does not have to worry about it.
+
+
+String category
+---------------
+
+.. literalinclude:: ../examples/1d_hist/1d_str_category.py
+    :language: python
+    :start-after: ###
+
+.. image:: ../img/1d_str_category.svg
+    :alt: String category plot
+    :width: 500

docs/examples/1d_hist/1d_int_category.py

@@ -0,0 +1,41 @@
+"""
+1d integer category
+===================
+
+Plot a 1d histogram with integer categories.
+
+"""
+
+###
+import boost_histogram as bh
+from plothist import plot_hist
+import matplotlib.pyplot as plt
+
+# 3 integer categories
+int_categories = [-10, 5, 72]
+
+# Integer category axis with 3 bins
+axis = bh.axis.IntCategory(categories=int_categories)
+
+# 6 data points,
+data = [-10, -10, 5, 72, 72, 72]
+
+# Create and fill the histogram
+h = bh.Histogram(axis, storage=bh.storage.Weight())
+h.fill(data)
+
+# Plot the histogram
+fig, ax = plt.subplots()
+
+plot_hist(h, ax=ax)
+
+# Set the x-ticks to the middle of the bins and label them
+ax.set_xticks([i + 0.5 for i in range(len(int_categories))])
+ax.set_xticklabels(int_categories)
+ax.minorticks_off()
+
+ax.set_xlabel("Integer Category")
+ax.set_ylabel("Entries")
+ax.set_xlim(0, len(int_categories))
+
+fig.savefig("1d_int_category.svg", bbox_inches="tight")

docs/examples/1d_hist/1d_str_category.py

@@ -0,0 +1,41 @@
+"""
+1d string category
+==================
+
+Plot a 1d histogram with string categories.
+
+"""
+
+###
+import boost_histogram as bh
+from plothist import plot_hist
+import matplotlib.pyplot as plt
+
+# 3 str categories
+str_categories = ["a", "b", "c"]
+
+# String category axis with 3 bins
+axis = bh.axis.StrCategory(categories=str_categories)
+
+# 6 data points,
+data = ["a", "a", "a", "b", "b", "c"]
+
+# Create and fill the histogram
+h = bh.Histogram(axis, storage=bh.storage.Weight())
+h.fill(data)
+
+# Plot the histogram
+fig, ax = plt.subplots()
+
+plot_hist(h, ax=ax)
+
+# Set the x-ticks to the middle of the bins and label them
+ax.set_xticks([i + 0.5 for i in range(len(str_categories))])
+ax.set_xticklabels(str_categories)
+ax.minorticks_off()
+
+ax.set_xlabel("String Category")
+ax.set_ylabel("Entries")
+ax.set_xlim(0, len(str_categories))
+
+fig.savefig("1d_str_category.svg", bbox_inches="tight")