matplotlib
diff --git a/‎doc/users/next_whats_new/colorbar_has_location_argument.rst
Copy file name to clipboard
+24Lines changed: 24 additions & 0 deletions b/‎doc/users/next_whats_new/colorbar_has_location_argument.rst
Copy file name to clipboard
+24Lines changed: 24 additions & 0 deletions
diff --git a/‎lib/matplotlib/colorbar.py
Copy file name to clipboardExpand all lines: lib/matplotlib/colorbar.py
+30-4Lines changed: 30 additions & 4 deletions b/‎lib/matplotlib/colorbar.py
Copy file name to clipboardExpand all lines: lib/matplotlib/colorbar.py
+30-4Lines changed: 30 additions & 4 deletions
diff --git a/‎lib/matplotlib/tests/baseline_images/test_colorbar/colorbar_extend_alpha.png
Copy file name to clipboard
2.02 KB b/‎lib/matplotlib/tests/baseline_images/test_colorbar/colorbar_extend_alpha.png
Copy file name to clipboard
2.02 KB
@@ -0,0 +1,24 @@
+``colorbar`` now has a ``location`` keyword argument
+====================================================
+
+The ``colorbar`` method now supports a ``location`` keyword argument
+to more easily position the color bar. This is useful when providing
+your own inset axes using the ``cax`` keyword argument and behaves
+similar to the case where axes are not provided (where the ``location``
+keyword is passed on). The ``orientation`` and ``ticklocation`` are no
+longer required to be provided as they are determined by ``location``.
+``ticklocation`` can still be provided if the automatic setting is not
+preferred. (``orientation`` can also be provided but must be compatible
+with the ``location``.)
+
+An example is:
+
+.. code-block:: python
+    import matplotlib.pyplot as plt
+    import numpy as np
+    rng = np.random.default_rng(19680801)
+    imdata = rng.random((10, 10))
+    fig, ax = plt.subplots()
+    im = ax.imshow(imdata)
+    fig.colorbar(im, cax=ax.inset_axes([0, 1.05, 1, 0.05]),
+                 location='top')
@@ -42,6 +42,11 @@
     of the colorbar, as that also determines the *orientation*; passing
     incompatible values for *location* and *orientation* raises an exception.
 
+ticklocation : {'auto', 'left', 'right', 'top', 'bottom'}
+    The location of the colorbar ticks. The *ticklocation* location value must
+    match *orientation*. For example, a horizontal colorbar can only have ticks
+    at the top or the bottom.
+
 fraction : float, default: 0.15
     Fraction of original axes to use for colorbar.
 
@@ -321,13 +326,17 @@ class Colorbar:
     alpha : float
         The colorbar transparency between 0 (transparent) and 1 (opaque).
 
-    orientation : {'vertical', 'horizontal'}
+    orientation : None or {'vertical', 'horizontal'}
+        If None, use the value determined by *location*. If both
+        *orientation* and *location* are None, 'vertical'.
 
     ticklocation : {'auto', 'left', 'right', 'top', 'bottom'}
 
     drawedges : bool
 
     filled : bool
+
+    location : None or {'left', 'right', 'top', 'bottom'}
     %s
     """
 
@@ -339,7 +348,7 @@ def __init__(self, ax, mappable=None, *, cmap=None,
                  alpha=None,
                  values=None,
                  boundaries=None,
-                 orientation='vertical',
+                 orientation=None,
                  ticklocation='auto',
                  extend=None,
                  spacing='uniform',  # uniform or proportional
@@ -350,6 +359,7 @@ def __init__(self, ax, mappable=None, *, cmap=None,
                  extendfrac=None,
                  extendrect=False,
                  label='',
+                 location=None,
                  ):
 
         if mappable is None:
@@ -380,14 +390,26 @@ def __init__(self, ax, mappable=None, *, cmap=None,
         mappable.colorbar_cid = mappable.callbacks.connect(
             'changed', self.update_normal)
 
+        location_orientation = _api.check_getitem(
+            {None: None, "left": "vertical", "right": "vertical",
+             "top": "horizontal", "bottom": "horizontal"},
+            location=location)
+
         _api.check_in_list(
-            ['vertical', 'horizontal'], orientation=orientation)
+            [None, 'vertical', 'horizontal'], orientation=orientation)
         _api.check_in_list(
             ['auto', 'left', 'right', 'top', 'bottom'],
             ticklocation=ticklocation)
         _api.check_in_list(
             ['uniform', 'proportional'], spacing=spacing)
 
+        if location_orientation is not None and orientation is not None:
+            if location_orientation != orientation:
+                raise TypeError(
+                    "location and orientation are mutually exclusive")
+        else:
+            orientation = orientation or location_orientation or "vertical"
+
         self.ax = ax
         self.ax._axes_locator = _ColorbarAxesLocator(self)
 
@@ -445,7 +467,11 @@ def __init__(self, ax, mappable=None, *, cmap=None,
         self.__scale = None  # linear, log10 for now.  Hopefully more?
 
         if ticklocation == 'auto':
-            ticklocation = 'bottom' if orientation == 'horizontal' else 'right'
+            if location is None:
+                ticklocation = (
+                    'bottom' if orientation == 'horizontal' else 'right')
+            else:
+                ticklocation = location
         self.ticklocation = ticklocation
 
         self.set_label(label)