Skip to content

MEP 31: dimension units handling

Jump to bottom
Jody Klymak edited this page Sep 25, 2017 · 1 revision

The goal here is to have a consistent interface for users to specify units for dimensions in the matplotlib libraries. Dimensions that require units include:

  • figure: figsize currently inches
  • subplots: left, right etc and paddings. Currently left, right in figure-relative units, pads in "ems"!
  • colorbar: paddings
  • tight_layout: as in subplots, but mostly paddings: in "ems" (fraction font size).
  • legend: borderpad etc (currently points)
  • savefig: pad_inches (inches)
  • axes: set_xlabel, set_ylabel: labelpad: currently points

... Probably many more.

The proposal here is to allow many of these to be specified as a string: pad="xxx.xSSS", where xxx.x is parsable as a float, and SSS is the units specifier. The units would always be the last three characters of the string. i.e.

pad='1.0ins'   # 1 inch
pad='1.0cms'   # 1 cm
pad='10.003pts'  # 10.003 pts (=1./72. in)
pad='1.0ems'   # 1 em (though ambiguity about what em - presumably the default font size)
pad='0.2rel'   # 0.2 figure-relative units.   i.e. if a horizontal dimension, then 0.2 of the figure width.
pad=0.2        # 0.2 times whatever the default unit for the module is.

The user would then call using these units. The float would be allowed for backwards compatibility.

Methods and functions would interact with this via a simple converter:

padval = dimunits.translate(pad, 'pts')

If pad is a float, it just returns the float. If its a string, it is decoded as above. If we don't want to allow some units (i.e. it may be undesirable for many dimensions to have relative units):

padval = dimunits.translate(pad, 'pts', disallow={'rel', 'mms'})

If pad is None, we could specify a default:

padval = dimunits.translate(pad, 'pts', default="3pts", disallow={'rel', 'mms'})
Clone this wiki locally