@@ -403,6 +403,25 @@ def inset_axes(parent_axes, width, height, loc='upper right',
403403 cases, it is recommended to read
404404 :ref:`the examples <sphx_glr_gallery_axes_grid1_inset_locator_demo.py>`.
405405
406+ Notes
407+ -----
408+ The meaning of *bbox_to_anchor* and *bbox_to_transform* is interpreted
409+ differently from that of legend. The value of bbox_to_anchor
410+ (or the return value of its get_points method; the default is
411+ *parent_axes.bbox*) is transformed by the bbox_transform (the default
412+ is Identity transform) and then interpreted as points in the pixel
413+ coordinate (which is dpi dependent).
414+
415+ Thus, following three calls are identical and creates an inset axes
416+ with respect to the *parent_axes*::
417+
418+ axins = inset_axes(parent_axes, "30%%", "40%%")
419+ axins = inset_axes(parent_axes, "30%%", "40%%",
420+ bbox_to_anchor=parent_axes.bbox)
421+ axins = inset_axes(parent_axes, "30%%", "40%%",
422+ bbox_to_anchor=(0, 0, 1, 1),
423+ bbox_transform=parent_axes.transAxes)
424+
406425 Parameters
407426 ----------
408427 parent_axes : `matplotlib.axes.Axes`
@@ -432,25 +451,26 @@ def inset_axes(parent_axes, width, height, loc='upper right',
432451
433452 bbox_to_anchor : tuple or `matplotlib.transforms.BboxBase`, optional
434453 Bbox that the inset axes will be anchored to. If None,
435- *parent_axes.bbox* is used. If a tuple, can be either
454+ a tuple of (0, 0, 1, 1) is used if *bbox_transform* is set
455+ to *parent_axes.transAxes* or *parent_axes.figure.transFigure*.
456+ Otherwise, *parent_axes.bbox* is used. If a tuple, can be either
436457 [left, bottom, width, height], or [left, bottom].
437458 If the kwargs *width* and/or *height* are specified in relative units,
438- the 2-tuple [left, bottom] cannot be used. Note that
439- the units of the bounding box are determined through the transform
440- in use. When using *bbox_to_anchor* it almost always makes sense to
441- also specify a *bbox_transform*. This might often be the axes transform
459+ the 2-tuple [left, bottom] cannot be used. Note that,
460+ unless *bbox_transform* is set, the units of the bounding box
461+ are interpreted in the pixel coordinate. When using *bbox_to_anchor*
462+ with tuple, it almost always makes sense to also specify
463+ a *bbox_transform*. This might often be the axes transform
442464 *parent_axes.transAxes*.
443465
444466 bbox_transform : `matplotlib.transforms.Transform`, optional
445467 Transformation for the bbox that contains the inset axes.
446- If None, a `.transforms.IdentityTransform` is used (i.e. pixel
447- coordinates). This is useful when not providing any argument to
448- *bbox_to_anchor*. When using *bbox_to_anchor* it almost always makes
449- sense to also specify a *bbox_transform*. This might often be the
450- axes transform *parent_axes.transAxes*. Inversely, when specifying
451- the axes- or figure-transform here, be aware that not specifying
452- *bbox_to_anchor* will use *parent_axes.bbox*, the units of which are
453- in display (pixel) coordinates.
468+ If None, a `.transforms.IdentityTransform` is used. The value
469+ of *bbox_to_anchor* (or the return value of its get_points method)
470+ is transformed by the *bbox_transform* and then interpreted
471+ as points in the pixel coordinate (which is dpi dependent).
472+ You may provide *bbox_to_anchor* in some normalized coordinate,
473+ and give an appropriate transform (e.g., *parent_axes.transAxes*).
454474
455475 axes_class : `matplotlib.axes.Axes` type, optional
456476 If specified, the inset axes created will be created with this class's