8000 update Axes docs on aspect-related methods · matplotlib/matplotlib@a94f682 · GitHub
[go: up one dir, main page]
Skip to content

Commit a94f682

Browse files
timhoffmtimhoffm
committed
update Axes docs on aspect-related methods
1 parent baa5f8e commit a94f682

File tree

1 file changed

+133
-53
lines changed

1 file changed

+133
-53
lines changed

‎lib/matplotlib/axes/_base.py

Lines 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