Up docs

Author: Descanonge

docs/source/accessor.rst

@@ -6,9 +6,9 @@ Accessor
 
 An :external+xarray:doc:`accessor <internals/extending-xarray>` is provided to
 ease manipulation and analysis of the histogram outputs. Simply import
-:mod:`xarray_histogram.accessor` to register it. It will then be available for
-all DataArrays that meet some conditions (see below), under the ``hist``
-attribute. It gives access to a number of methods. ::
+:mod:`xarray_histogram.accessor` to register it. It will then be available under
+the ``hist`` attribute for all DataArrays that meet some conditions (see below).
+It gives access to a number of methods. ::
 
     import xarray_histogram as xh
     import xarray_histogram.accessor
@@ -17,15 +17,17 @@ attribute. It gives access to a number of methods. ::
 
     h.hist.median()
 
-Operations are vectorized [#vector]_, so that you can apply them to entire
+Operations are vectorized so that you can apply them to entire
 arrays of histograms. For instance for data defined along time, latitude and
 longitude, we can compute one histogram per time-step::
 
     >>> h = xh.histogram(data, dims=["lon", "lat"])
     >>> h.hist.median()
     will be of dimensions ("time",)
 
-.. [#vector] Computations are automatically vectorized in Python with
+.. note::
+
+   Computations are automatically vectorized in Python with
    :func:`xarray.apply_ufunc`, which is not efficient for a large number of
    histograms.
 
@@ -56,7 +58,7 @@ Each bins coordinate may contain attributes:
 
 Those conventions are coherent with the output of
 ``xarray_histogram.histogram*``, so if you use this package functions you
-should not have to worry. The names of the array and coordinates is also
+should not have to worry. The names of the array and coordinates are also
 consistent with that of :external+xhistogram:doc:`xhistogram <index>`
 (although coordinates attributes will be missing).
 
@@ -85,11 +87,11 @@ excluded by passing ``flow=False``.
   bins. The overflow bins centers are the same as their position (``np.inf`` for
   instance).
 
-* :meth:`~.HistDataArrayAccessor.areas` returns the areas of multidimensional
-  bins. This is the product of the widths of all bins. Only some variable can be
-  specified. The areas of points that correspond to a flow bin in at least one
-  dimension is equal to one. For instance for a 2D-histogram with underflow and
-  overflow bins, all the borders of the 2D array for areas will be equal to 1.
+* :meth:`~.HistDataArrayAccessor.areas` returns the areas corresponding to each
+  histogram point. This is the outer product of the widths of all bins. The
+  areas of points that correspond to a flow bin in at least one dimension is
+  equal to one. For instance for a 2D-histogram with underflow and overflow
+  bins, all the borders of the 2D array for areas will be equal to 1.
 
 To remove flow bins, :meth:`~.HistDataArrayAccessor.remove_flow` will returns a
 new histogram DataArray without the flow bins of the given variables (by default
@@ -102,9 +104,9 @@ Bins transform
 
 Arbitrary functions can be applied to bins with
 :meth:`~.HistDataArrayAccessor.apply_func`. The result is equivalent to
-computing an histogram of ``func(data["variable"])``. The function must
+computing the histogram of ``func(data["variable"])``. The function must
 transform the N+1 edges given as a DataArray. There is no need to account for
-the *right_edge* attribute.
+the *right_edge* attribute or flow bins.
 
 For instance, :meth:`~.HistDataArrayAccessor.scale` scales bins by a given
 factor. It essential does ``hist.apply_func(lambda edges: edges * factor)``
@@ -115,7 +117,7 @@ Normalization
 
 The histogram can be normalized to a probability density function if not
 already, using :meth:`~.HistDataArrayAccessor.normalize`. Note that for a
-N-dimensional histogram, this function can normalize only along some variables.
+N-dimensional histogram, this function can normalize along only some variables.
 
 The accessor considers the histogram normalized or not given the name of its
 DataArray: normalized if named ``<variables>_pdf`` and non-normalized

docs/source/usage.rst

@@ -50,18 +50,21 @@ supported. Instead, use a
    </user-guide/axes.rst#regular-axis-transforms>` applied) is more efficient:
    it avoids having to use binary search to find in which bin a value falls.
 
-Some basic examples of axis include::
+Some examples of axis include::
 
    import boost_histogram.axis as bha
 
    # regular width bins
    bha.Regular(200, 0., 10.)
+
    # logarithmically spaced bins (without performance loss)
    bha.Regular(200, 1e-3, 10., transform=bha.transform.log)
+
    # integer bins
    bha.Integer(0, 20)
+
    # boolean
-   bha.Integer(0, 2, underflow=False, overflow=True)
+   bha.Integer(0, 2, underflow=False, overflow=False)
 
 Over/underflow
 ==============
@@ -81,7 +84,7 @@ coordinates values for the underflow and overflow bins will be set to
 Output
 ======
 
-All three functions return a simple :class:`xarray.DataArray`. Its name is
+All three functions return a single :class:`xarray.DataArray`. Its name is
 ``<variable names separated by underscores>_histogram`` (so for instance
 ``x_y_histogram``). The bins edges are contained in coordinates named
 ``<variable>_bins``. The right edge of the last bin is stored in a coordinate

src/xarray_histogram/accessor.py

@@ -24,19 +24,20 @@ class HistDataArrayAccessor:
     .. rubric:: Validity
 
     * The coordinates of the bins must be named ``<variable>_bins``.
-    * The array must be named as ``<variable(s)_name>_<histogram or pdf>``. histogram*
-    *if it is not normalized, and *pdf* if it is normalized as a probability density
-    *function. If the histogram is multi-dimensional, the variables names must be
-    *separated by underscores. For instance: ``Temp_Sal_histogram``.
+    * The array must be named as ``<variable(s)_name>_<histogram or pdf>``. *histogram*
+      if it is not normalized, and *pdf* if it is normalized as a probability density
+      function. If the histogram is multi-dimensional, the variables names must be
+      separated by underscores. For instance: ``Temp_Sal_histogram``.
 
     Each bins coordinate may contain attributes:
 
     * ``bin_type``: the class name of the Boost axis type that was used. If not present,
-    the accessor will assume the bins are regularly spaced and will try to infer the
-    rightmost edge. * ``right_edge``: the rightmost edge position, only necessary for
-    Regular and Variable bins. * ``underflow`` and ``overflow``: booleans that indicate
-    if the corresponding flow bins are present. If not present, will assume no flow
-    bins.
+      the accessor will assume the bins are regularly spaced and will try to infer the
+      rightmost edge.
+    * ``right_edge``: the rightmost edge position, only necessary for Regular and
+       Variable bins.
+    * ``underflow`` and ``overflow``: booleans that indicate if the corresponding flow
+      bins are present. If not present, will assume no flow bins.
 
     .. rubric:: Backend for computations
 
@@ -572,10 +573,11 @@ def interval(self, confidence: float, variable: str | None = None) -> xr.Dataset
         return output
 
 
-def remove_flow(x: xr.DataArray) -> xr.DataArray:
-    overflow = x.attrs.get("overflow", False)
-    underflow = x.attrs.get("underflow", False)
-    out = x[slice(1 if underflow else 0, -1 if overflow else None)]
+def remove_flow(coord: xr.DataArray) -> xr.DataArray:
+    """Remove flow bins from a coordinate."""
+    overflow = coord.attrs.get("overflow", False)
+    underflow = coord.attrs.get("underflow", False)
+    out = coord[slice(1 if underflow else 0, -1 if overflow else None)]
     out.attrs["underflow"] = False
     out.attrs["overflow"] = True
     return out