Replace hist normed arg with density arg in a backward-compatible way.

chelseatroy · dstansby · commit 138239de8828 · 2017-08-05T18:28:49.000+01:00
Update documentation to reflect addition of density arg to hist

Adjust documentation and test formatting

Raise if density and normed are both set in hist

Update documentation to match pep8 guidelines
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -5851,10 +5851,10 @@ def table(self, **kwargs):
     #### Data analysis
 
     @_preprocess_data(replace_names=["x", 'weights'], label_namer="x")
-    def hist(self, x, bins=None, range=None, density=None, normed=None,
-             weights=None, cumulative=False, bottom=None, histtype='bar',
-             align='mid', orientation='vertical', rwidth=None, log=False,
-             color=None, label=None, stacked=False,
+    def hist(self, x, bins=None, range=None, density=None, weights=None,
+             cumulative=False, bottom=None, histtype='bar', align='mid',
+             orientation='vertical', rwidth=None, log=False,
+             color=None, label=None, stacked=False, normed=None,
              **kwargs):
         """
         Plot a histogram.
@@ -5899,7 +5899,10 @@ def hist(self, x, bins=None, range=None, density=None, normed=None,
 
             Default is ``None``
 
-        density : boolean, optional
+        normed, density : boolean, optional
+            Either the 'normed' or the 'density' arg can be set to
+            accomplish this behavior:
+
             If `True`, the first element of the return tuple will
             be the counts normalized to form a probability density, i.e.,
             the area (or integral) under the histogram will sum to 1.
@@ -5908,28 +5911,31 @@ def hist(self, x, bins=None, range=None, density=None, normed=None,
             of observations. If `stacked` is also `True`, the sum of the
             histograms is normalized to 1.
 
-            Default is ``None``, behaves as ``False``.
+            Default is ``None`` for both 'normed' and 'density.' If either is
+            set, then that value will be used. If neither are set, then the args
+            will be treated as 'False.'
 
-        normed : boolean, optional
-            Will be deprecated, same role as density. For consistency
-            with NumPy 2.0.0 keyword density has been introduced.
+            If both are set to different things, the hist function raises an
+            error.
 
         weights : (n, ) array_like or None, optional
             An array of weights, of the same shape as `x`.  Each value in `x`
             only contributes its associated weight towards the bin count
-            (instead of 1).  If `normed` is True, the weights are normalized,
-            so that the integral of the density over the range remains 1.
+            (instead of 1).  If `normed` or 'density' is True,
+            the weights are normalized, so that the integral of the density
+            over the range remains 1.
 
             Default is ``None``
 
         cumulative : boolean, optional
             If `True`, then a histogram is computed where each bin gives the
             counts in that bin plus all bins for smaller values. The last bin
-            gives the total number of datapoints.  If `normed` is also `True`
-            then the histogram is normalized such that the last bin equals 1.
-            If `cumulative` evaluates to less than 0 (e.g., -1), the direction
-            of accumulation is reversed.  In this case, if `normed` is also
-            `True`, then the histogram is normalized such that the first bin
+            gives the total number of datapoints. If `normed` or 'density'
+            is also `True` then the histogram is normalized such that the last
+            bin equals 1. If `cumulative` evaluates to less than 0 (e.g., -1),
+            the direction of accumulation is reversed.  In this case, if
+            `normed` and/or 'density' is also `True`, then the histogram is
+            normalized such that the first bin
             equals 1.
 
             Default is ``False``
@@ -6012,12 +6018,13 @@ def hist(self, x, bins=None, range=None, density=None, normed=None,
         Returns
         -------
         n : array or list of arrays
-            The values of the histogram bins. See **normed** and **weights**
-            for a description of the possible semantics. If input **x** is an
-            array, then this is an array of length **nbins**. If input is a
-            sequence arrays ``[data1, data2,..]``, then this is a list of
-            arrays with the values of the histograms for each of the arrays
-            in the same order.
+            The values of the histogram bins. See **normed or density**
+            and **weights** for a description of the possible semantics.
+            If input **x** is an array, then this is an array of length
+            **nbins**. If input is a sequence arrays
+            ``[data1, data2,..]``, then this is a list of arrays with
+            the values of the histograms for each of the arrays in the
+            same order.
 
         bins : array
             The edges of the bins. Length nbins + 1 (nbins left edges and right
@@ -6048,6 +6055,50 @@ def hist(self, x, bins=None, range=None, density=None, normed=None,
         bin_range = range
         del range
 
+        # Sets the density variable, if necessary, to its predecessor, 'normed.'
+        if density is not None and normed is not None:
+            raise ValueError('The density and normed arguments represent the '
+                             'same concept. Please set only one of them.')
+        elif normed is not None and density is None:
+            density = normed
+        elif normed is None and density is None:
+            density = False
+
+        def _normalize_input(inp, ename='input'):
+            """Normalize 1 or 2d input into list of np.ndarray or
+            a single 2D np.ndarray.
+
+            Parameters
+            ----------
+            inp : iterable
+            ename : str, optional
+                Name to use in ValueError if `inp` can not be normalized
+
+            """
+            if (isinstance(x, np.ndarray) or
+                    not iterable(cbook.safe_first_element(inp))):
+                # TODO: support masked arrays;
+                inp = np.asarray(inp)
+                if inp.ndim == 2:
+                    # 2-D input with columns as datasets; switch to rows
+                    inp = inp.T
+                elif inp.ndim == 1:
+                    # new view, single row
+                    inp = inp.reshape(1, inp.shape[0])
+                else:
+                    raise ValueError(
+                        "{ename} must be 1D or 2D".format(ename=ename))
+                if inp.shape[1] < inp.shape[0]:
+                    warnings.warn(
+                        '2D hist input should be nsamples x nvariables;\n '
+                        'this looks transposed '
+                        '(shape is %d x %d)' % inp.shape[::-1])
+            else:
+                # multiple hist with data of different length
+                inp = [np.asarray(xi) for xi in inp]
+
+            return inp
+
         if not self._hold:
             self.cla()
 
@@ -6143,7 +6194,9 @@ def hist(self, x, bins=None, range=None, density=None, normed=None,
             m = m.astype(float)  # causes problems later if it's an int
             if mlast is None:
                 mlast = np.zeros(len(bins)-1, m.dtype)
-
+            if density and not stacked:
+                db = np.diff(bins)
+                m = (m.astype(float) / db) / m.sum()
             if stacked:
                 if mlast is None:
                     mlast = np.zeros(len(bins)-1, m.dtype)
@@ -6248,8 +6301,9 @@ def hist(self, x, bins=None, range=None, density=None, normed=None,
                 if np.min(bottom) > 0:
                     minimum = np.min(bottom)
                 elif density or weights is not None:
-                    # For normed (density = True) data full tick-label unit
-                    # for the lowest filled bin)
+                    # For data that is normed to form a probability density,
+                    # set to minimum data value / logbase
+                    # (gives 1 full tick-label unit for the lowest filled bin)
                     ndata = np.array(n)
                     minimum = (np.min(ndata[ndata > 0])) / logbase
                 else:
diff --git a/lib/matplotlib/tests/test_axes.py b/lib/matplotlib/tests/test_axes.py
@@ -2775,13 +2775,12 @@ def test_hist_stacked_normed():
     ax = fig.add_subplot(111)
     ax.hist((d1, d2), stacked=True, normed=True)
 
-@image_comparison(baseline_images=['hist_stacked_normed'])
+
 def test_hist_stacked_density():
     # make some data
     d1 = np.linspace(1, 3, 20)
     d2 = np.linspace(0, 10, 50)
-    fig = plt.figure()
-    ax = fig.add_subplot(111)
+    fig, ax = plt.subplots()
     ax.hist((d1, d2), stacked=True, density=True)
 
 
