Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit 542f7e6

Browse filesBrowse files
jklymakjklymak
authored
Merge pull request #9964 from timhoffm/doc-axes-aspect
Update Axes docs on aspect-related methods
2 parents fad82b8 + a94f682 commit 542f7e6
Copy full SHA for 542f7e6

File tree

Expand file treeCollapse file tree

1 file changed

+133
-53
lines changed
Filter options
Expand file treeCollapse file tree

1 file changed

+133
-53
lines changed

‎lib/matplotlib/axes/_base.py

Copy file name to clipboardExpand all lines: lib/matplotlib/axes/_base.py
+133-53Lines changed: 133 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -1261,43 +1261,52 @@ def get_aspect(self):
12611261

12621262
def set_aspect(self, aspect, adjustable=None, anchor=None):
12631263
"""
1264-
*aspect*
1265-
1266-
======== ================================================
1267-
value description
1268-
======== ================================================
1269-
'auto' automatic; fill position rectangle with data
1270-
'equal' same scaling from data to plot units for x and y
1271-
num a circle will be stretched such that the height
1272-
is num times the width. aspect=1 is the same as
1273-
aspect='equal'.
1274-
======== ================================================
1275-
1276-
*adjustable*
1277-
1278-
============ =====================================
1279-
value description
1280-
============ =====================================
1281-
'box' change physical size of axes
1282-
'datalim' change xlim or ylim
1283-
'box-forced' same as 'box', but axes can be shared
1284-
============ =====================================
1264+
Set the aspect of the axis scaling, i.e. the ratio of y-unit to x-unit.
12851265
1286-
'box' does not allow axes sharing, as this can cause
1287-
unintended side effect. For cases when sharing axes is
1288-
fine, use 'box-forced'.
1289-
1290-
*anchor*
1266+
Parameters
1267+
----------
1268+
aspect : ['auto' | 'equal'] or num
1269+
Possible values:
1270+
1271+
======== ================================================
1272+
value description
1273+
======== ================================================
1274+
'auto' automatic; fill the position rectangle with data
1275+
'equal' same scaling from data to plot units for x and y
1276+
num a circle will be stretched such that the height
1277+
is num times the width. aspect=1 is the same as
1278+
aspect='equal'.
1279+
======== ================================================
1280+
1281+
adjustable : None or ['box' | 'datalim' | 'box-forced'], optional
1282+
If not ``None``, this defines which parameter will be adjusted to
1283+
meet the required aspect. See `.set_adjustable` for further
1284+
details.
1285+
1286+
anchor : None or str or 2-tuple of float, optional
1287+
If not ``None``, this defines where the Axes will be drawn if there
1288+
is extra space due to aspect constraints. The most common way to
1289+
to specify the anchor are abbreviations of carindal directions:
1290+
1291+
===== =====================
1292+
value description
1293+
===== =====================
1294+
'C' centered
1295+
'SW' lower left corner
1296+
'S' middle of bottom edge
1297+
'SE' lower right corner
1298+
etc.
1299+
===== =====================
1300+
1301+
See `.set_anchor` for further details.
12911302
1292-
===== =====================
1293-
value description
1294-
===== =====================
1295-
'C' centered
1296-
'SW' lower left corner
1297-
'S' middle of bottom edge
1298-
'SE' lower right corner
1299-
etc.
1300-
===== =====================
1303+
See Also
1304+
--------
1305+
matplotlib.axes.Axes.set_adjustable
1306+
defining the parameter to adjust in order to meet the required
1307+
aspect.
1308+
matplotlib.axes.Axes.set_anchor
1309+
defining the position in case of extra space.
13011310
"""
13021311
if (isinstance(aspect, six.string_types)
13031312
and aspect in ('equal', 'auto')):
@@ -1316,7 +1325,29 @@ def get_adjustable(self):
13161325

13171326
def set_adjustable(self, adjustable):
13181327
"""
1319-
ACCEPTS: [ 'box' | 'datalim' | 'box-forced']
1328+
Define which parameter the Axes will change to achieve a given aspect.
1329+
1330+
Possible values are:
1331+
1332+
============ =====================================
1333+
value description
1334+
============ =====================================
1335+
'box' change the physical size of the Axes
1336+
'datalim' change xlim or ylim
1337+
'box-forced' same as 'box', but axes can be shared
1338+
============ =====================================
1339+
1340+
'box' does not allow axes sharing, as this can cause
1341+
unintended side effect. For cases when sharing axes is
1342+
fine, use 'box-forced'.
1343+
1344+
..
1345+
ACCEPTS: [ 'box' | 'datalim' | 'box-forced']
1346+
1347+
See Also
1348+
--------
1349+
matplotlib.axes.Axes.set_aspect
1350+
for a description of aspect handling.
13201351
"""
13211352
if adjustable in ('box', 'datalim', 'box-forced'):
13221353
if self in self._shared_x_axes or self in self._shared_y_axes:
@@ -1329,29 +1360,60 @@ def set_adjustable(self, adjustable):
13291360
self.stale = True
13301361

13311362
def get_anchor(self):
1363+
"""
1364+
Get the anchor location.
1365+
1366+
See Also
1367+
--------
1368+
matplotlib.axes.Axes.set_anchor
1369+
for a description of the anchor.
1370+
matplotlib.axes.Axes.set_aspect
1371+
for a description of aspect handling.
1372+
"""
13321373
return self._anchor
13331374

13341375
def set_anchor(self, anchor):
13351376
"""
1336-
*anchor*
1337-
1338-
===== ============
1339-
value description
1340-
===== ============
1341-
'C' center
1342-
'SW' bottom left
1343-
'S' bottom
1344-
'SE' bottom right
1345-
'E' right
1346-
'NE' top right
1347-
'N' top
1348-
'NW' top left
1349-
'W' left
1350-
===== ============
1377+
Define the anchor location.
1378+
1379+
The actual drawing area (active position) of the Axes may be smaller
1380+
than the Bbox (original position) when a fixed aspect is required. The
1381+
anchor defines where the drawing area will be located within the
1382+
available space.
13511383
13521384
..
13531385
ACCEPTS:
13541386
[ 'C' | 'SW' | 'S' | 'SE' | 'E' | 'NE' | 'N' | 'NW' | 'W' ]
1387+
1388+
Parameters
1389+
----------
1390+
anchor : str or 2-tuple of floats
1391+
The anchor position may be either:
1392+
1393+
- a sequence (*cx*, *cy*). *cx* and *cy* may range from 0
1394+
to 1, where 0 is left or bottom and 1 is right or top.
1395+
1396+
- a string using cardinal directions as abbreviation:
1397+
1398+
- 'C' for centered
1399+
- 'S' (south) for bottom-center
1400+
- 'SW' (south west) for bottom-left
1401+
- etc.
1402+
1403+
Here is an overview of the possible positions:
1404+
1405+
+------+------+------+
1406+
| 'NW' | 'N' | 'NE' |
1407+
+------+------+------+
1408+
| 'W' | 'C' | 'E' |
1409+
+------+------+------+
1410+
| 'SW' | 'S' | 'SE' |
1411+
+------+------+------+
1412+
1413+
See Also
1414+
--------
1415+
matplotlib.axes.Axes.set_aspect
1416+
for a description of aspect handling.
13551417
"""
13561418
if anchor in mtransforms.Bbox.coefs or len(anchor) == 2:
13571419
self._anchor = anchor
@@ -1390,8 +1452,26 @@ def get_data_ratio_log(self):
13901452

13911453
def apply_aspect(self, position=None):
13921454
"""
1393-
Use :meth:`_aspect` and :meth:`_adjustable` to modify the
1394-
axes box or the view limits.
1455+
Adjust the Axes so that it fulfills its aspect setting.
1456+
1457+
Depending on `.get_adjustable` and `.get_anchor` this will either
1458+
modify the Axes box or the view limits.
1459+
1460+
Notes
1461+
-----
1462+
This is automatically called on draw. So you won't need to call this
1463+
yourself in most cases. One exception may be if you need to update the
1464+
Axes before drawing.
1465+
1466+
See Also
1467+
--------
1468+
matplotlib.axes.Axes.set_aspect
1469+
for a description of aspect handling.
1470+
matplotlib.axes.Axes.set_adjustable
1471+
defining the parameter to adjust in order to meet the required
1472+
aspect.
1473+
matplotlib.axes.Axes.set_anchor
1474+
defining the position in case of extra space.
13951475
"""
13961476
if position is None:
13971477
position = self.get_position(original=True)

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.