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 1f7b450

Browse filesBrowse files
timhoffmtimhoffm
committed
update Axes docs on aspect-related methods
1 parent baa5f8e commit 1f7b450
Copy full SHA for 1f7b450

File tree

Expand file treeCollapse file tree

1 file changed

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

1 file changed

+132
-53
lines changed

‎lib/matplotlib/axes/_base.py

Copy file name to clipboardExpand all lines: lib/matplotlib/axes/_base.py
+132-53Lines changed: 132 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -1261,43 +1261,51 @@ 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 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 details.
1284+
1285+
anchor : None or str or 2-tuple of float, optional
1286+
If not ``None``, this defines where the axes will be drawn if there
1287+
is extra space due to aspect constraints. The most common way to
1288+
to specify the anchor are abbreviations of carindal directions:
1289+
1290+
===== =====================
1291+
value description
1292+
===== =====================
1293+
'C' centered
1294+
'SW' lower left corner
1295+
'S' middle of bottom edge
1296+
'SE' lower right corner
1297+
etc.
1298+
===== =====================
1299+
1300+
See `.set_anchor` for further details.
12911301
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-
===== =====================
1302+
See Also
1303+
--------
1304+
matplotlib.axes.Axes.set_adjustable
1305+
defining the parameter to adjust in order to meet the required
1306+
aspect.
1307+
matplotlib.axes.Axes.set_anchor
1308+
defining the position in case of extra space.
13011309
"""
13021310
if (isinstance(aspect, six.string_types)
13031311
and aspect in ('equal', 'auto')):
@@ -1316,7 +1324,29 @@ def get_adjustable(self):
13161324

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

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

13341374
def set_anchor(self, anchor):
13351375
"""
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-
===== ============
1376+
Define the anchor location.
1377+
1378+
The actual drawing area (active position) of the axes may be smaller
1379+
than the Bbox (original position) when a fixed aspect is required. The
1380+
anchor defines where the drawing area will be located within the
1381+
available space.
13511382
13521383
..
13531384
ACCEPTS:
13541385
[ 'C' | 'SW' | 'S' | 'SE' | 'E' | 'NE' | 'N' | 'NW' | 'W' ]
1386+
1387+
Parameters
1388+
----------
1389+
anchor : str or 2-tuple of floats
1390+
The anchor position may be either:
1391+
1392+
- a sequence (*cx*, *cy*). *cx* and *cy* may range from 0
1393+
to 1, where 0 is left or bottom and 1 is right or top.
1394+
1395+
- a string using cardinal directions as abbreviation:
1396+
1397+
- 'C' for centered
1398+
- 'S' (south) for bottom-center
1399+
- 'SW' (south west) for bottom-left
1400+
- etc.
1401+
1402+
Here is an overview of the possible positions:
1403+
1404+
+------+------+------+
1405+
| 'NW' | 'N' | 'NE' |
1406+
+------+------+------+
1407+
| 'W' | 'C' | 'E' |
1408+
+------+------+------+
1409+
| 'SW' | 'S' | 'SE' |
1410+
+------+------+------+
1411+
1412+
See Also
1413+
--------
1414+
matplotlib.axes.Axes.set_aspect
1415+
for a description of aspect handling.
13551416
"""
13561417
if anchor in mtransforms.Bbox.coefs or len(anchor) == 2:
13571418
self._anchor = anchor
@@ -1390,8 +1451,26 @@ def get_data_ratio_log(self):
13901451

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