Add a "density" kwarg to hist2d #11070

thoo · thoo · commit ce6ed74e9915 · 2018-10-16T17:23:36.000-04:00
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -6778,7 +6778,7 @@ def hist(self, x, bins=None, range=None, density=None, weights=None,
             return tops, bins, cbook.silent_list('Lists of Patches', patches)
 
     @_preprocess_data(replace_names=["x", "y", "weights"], label_namer=None)
-    def hist2d(self, x, y, bins=10, range=None, normed=False, weights=None,
+    def hist2d(self, x, y, bins=10, range=None, density=None,  normed=None, weights=None,
                cmin=None, cmax=None, **kwargs):
         """
         Make a 2D histogram plot.
@@ -6812,11 +6812,22 @@ def hist2d(self, x, y, bins=10, range=None, normed=False, weights=None,
              xmax], [ymin, ymax]]``. All values outside of this range will be
              considered outliers and not tallied in the histogram.
 
-        normed : bool, optional, default: False
-             Normalize histogram.
+        density : boolean, optional
+             If False, the default, returns the number of samples in each bin. 
+             If True, returns the probability *density* function at the bin,
+             ``bin_count / sample_count / bin_area``.
+
+             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``.
+             If both *density* and *normed* are set an error is raised. 
+        
+        normed : bool, optional, default: None
+             Deprecated; use the density keyword argument instead.  
+        
 
         weights : array_like, shape (n, ), optional, default: None
-            An array of values w_i weighing each sample (x_i, y_i).
+             An array of values w_i weighing each sample (x_i, y_i).
 
         cmin : scalar, optional, default: None
              All bins that has count less than cmin will not be displayed and
@@ -6870,7 +6881,16 @@ def hist2d(self, x, y, bins=10, range=None, normed=False, weights=None,
           in effect to gamma correction) can be accomplished with
           `.colors.PowerNorm`.
         """
-
+        if density is not None and normed is not None:
+            raise ValueError("kwargs 'density' and 'normed' cannot be used "
+                             "simultaneously. "
+                             "Please only use 'density', since 'normed'"
+                             "is deprecated.")
+        if normed is not None:
+            cbook.warn_deprecated("2.1", name="'normed'", obj_type="kwarg",
+                                  alternative="'density'", removal="3.1")
+                                  
+        normed = bool(density) or bool(normed)
         h, xedges, yedges = np.histogram2d(x, y, bins=bins, range=range,
                                            normed=normed, weights=weights)
 
