From d8f3af24190ce99c2e83dd4525d83d196c310ea8 Mon Sep 17 00:00:00 2001 From: Henry Schreiner Date: Wed, 15 Sep 2021 11:32:19 -0400 Subject: [PATCH] docs: mention stacked setting for histograms --- docs/usage/accumulators.rst | 6 +++++- docs/usage/histogram.rst | 14 +++++++++++++- 2 files changed, 18 insertions(+), 2 deletions(-) diff --git a/docs/usage/accumulators.rst b/docs/usage/accumulators.rst index 69a1b3bd..98e3b676 100644 --- a/docs/usage/accumulators.rst +++ b/docs/usage/accumulators.rst @@ -159,4 +159,8 @@ Most of the accumulators (except Sum) support a View. This is what is returned f a histogram when ``.view()`` is requested. This is a structured NumPy ndarray, with a few small additions to make them easier to work with. Like a NumPy recarray, you can access the fields with attributes; you can even access (but not set) computed attributes like ``.variance``. A view will -also return an accumulator instance if you select a single item. +also return an accumulator instance if you select a single item. You can set a view's contents +with a stacked array, and each item in the stack will be used for the (computed) values that a +normal constructor would take. For example, WeighedMean can take an array with a final +dimension four long, with ``sum_of_weights``, ``sum_of_weights_squared``, ``value``, and ``variance`` +elements, even though several of these values are computed from the internal representation. diff --git a/docs/usage/histogram.rst b/docs/usage/histogram.rst index f3a9b4f2..ed7d6e6a 100644 --- a/docs/usage/histogram.rst +++ b/docs/usage/histogram.rst @@ -24,8 +24,20 @@ The primary values from a histogram are always available as ``.values()``. The v Views ^^^^^ -While Histograms do conform to the Python buffer protocol, the best way to get access to the raw contents of a histogram as a NumPy array is with ``.view()``. This way you can optionally pass ``flow=True`` to get the flow bins, and if you have an accumulator storage, you will get a View, which is a slightly augmented ndarrray subclass (see :ref:`usage-accumulators`). +While Histograms do conform to the Python buffer protocol, the best way to get access to the raw contents of a histogram as a NumPy array is with ``.view()``. This way you can optionally pass ``flow=True`` to get the flow bins, and if you have an accumulator storage, you will get a View, which is a slightly augmented ndarrray subclass (see :ref:`usage-accumulators`). Views support setting as well for non-computed properties; you can use an expression like this to set the values of an accumulator storage: +.. code:: python3 + + h.view().value = values + + +You can also used stacked arrays (N+1 dimensional) to set a histogram's contents. This is especially useful if you need to set a computed value, like variance on a Mean/WeightedMean storage, which cannot be set using the above method: + +.. code:: python3 + + h[...] = np.stack([values, variances], axis=-1) + +If you leave endpoints off (such as with ``...`` above), then you can match the size with or without flow bins. Operations ^^^^^^^^^^