5497027953

pending completion

Build # 5497027953

Build Type

push

github

Committed by

morganjwilliams

Commit Message

Merge branch 'release/0.3.3' into main

Run Details

249 of 270 new or added lines in 48 files covered. (92.22%)

217 existing lines in 33 files now uncovered.

5967 of 6601 relevant lines covered (90.4%)

10.84 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

92.19

/pyrolite/util/plot/axes.py

"""
Functions for creating, ordering and modifying :class:`~matplolib.axes.Axes`.
"""
import warnings

import matplotlib.pyplot as plt
import numpy as np
from mpl_toolkits.axes_grid1 import make_axes_locatable

from ..log import Handle
from ..meta import subkwargs

logger = Handle(__name__)


def get_ordered_axes(fig):
    """
    Get the axes from a figure, which may or may not have been modified by
    pyrolite functions. This ensures that ordering is preserved.
    """
    if hasattr(fig, "orderedaxes"):  # previously modified
        axes = fig.orderedaxes
    else:  # unmodified axes
        axes = fig.axes
    return axes


def get_axes_index(ax):
    """
    Get the three-digit integer index of a subplot in a regular grid.

    Parameters
    -----------
    ax : :class:`matplotlib.axes.Axes`
        Axis to to get the gridspec index for.

    Returns
    -----------
    :class:`tuple`
        Rows, columns and axis index for the gridspec.
    """
    nrow, ncol = ax.get_gridspec()._nrows, ax.get_gridspec()._ncols
    index = get_ordered_axes(ax.figure).index(ax)
    triple = nrow, ncol, index + 1
    return triple


def replace_with_ternary_axis(ax):
    """
    Replace a specified axis with a ternary equivalent.

    Parameters
    ------------
    ax : :class:`~matplotlib.axes.Axes`

    Returns
    ------------
    tax : :class:`~mpltern.ternary.TernaryAxes`
    """
    if ax.name != "ternary":
        if not check_default_axes(ax):
            if not check_empty(ax):
                warnings.warn(
                    "Non-empty, non-default bivariate axes being replaced with ternary axes."
                )
            else:
                logger.info(
                    "Non-default bivraite axes being replaced with ternary axes."
                )
    fig = ax.figure
    axes = get_ordered_axes(fig)
    idx = axes.index(ax)
    tax = fig.add_subplot(*get_axes_index(ax), projection="ternary")
    fig.add_axes(tax)  # make sure the axis is added to fig.children
    fig.delaxes(ax)  # remove the original axes
    # update figure ordered axes
    fig.orderedaxes = [a if ix != idx else tax for (ix, a) in enumerate(axes)]
    return tax


def label_axes(ax, labels=[], **kwargs):
    """
    Convenience function for labelling rectilinear and ternary axes.

    Parameters
    -----------
    ax : :class:`~matplotlib.axes.Axes`
        Axes to label.
    labels : :class:`list`
        List of labels: [x, y] | or [t, l, r]
    """
    if (ax.name == "ternary") and (len(labels) == 3):
        tvar, lvar, rvar = labels
        ax.set_tlabel(tvar, **kwargs)
        ax.set_llabel(lvar, **kwargs)
        ax.set_rlabel(rvar, **kwargs)
    elif len(labels) == 2:
        xvar, yvar = labels
        ax.set_xlabel(xvar, **kwargs)
        ax.set_ylabel(yvar, **kwargs)
    else:
        raise NotImplementedError


def axes_to_ternary(ax):
    """
    Set axes to ternary projection after axis creation. As currently implemented,
    note that this will replace and reorder axes as acecessed from the figure (the
    ternary axis will then be at the end), and as such this returns a list of axes
    in the correct order.

    Parameters
    -----------
    ax : :class:`~matplotlib.axes.Axes` | :class:`list` (:class:`~matplotlib.axes.Axes`)
        Axis (or axes) to convert projection for.

    Returns
    ---------
    axes : :class:`list' (:class:`~matplotlib.axes.Axes`, class:`~mpltern.ternary.TernaryAxes`)
    """

    if isinstance(ax, (list, np.ndarray, tuple)):  # multiple Axes specified
        fig = ax[0].figure
        for a in ax:  # axes to set to ternary
            replace_with_ternary_axis(a)
    else:  # a single Axes is passed
        fig = ax.figure
        replace_with_ternary_axis(ax)
    return fig.orderedaxes


def check_default_axes(ax):
    """
    Simple test to check whether an axis is empty of artists and hasn't been
    rescaled from the default extent.

    Parameters
    -----------
    ax : :class:`matplotlib.axes.Axes`
        Axes to check for artists and scaling.

    Returns
    -------
    :class:`bool`
    """

    if np.allclose(ax.axis(), np.array([0, 1, 0, 1])):
        return check_empty(ax)
    else:
        return False


def check_empty(ax):
    """
    Simple test to check whether an axis is empty of artists.

    Parameters
    -----------
    ax : :class:`matplotlib.axes.Axes`
        Axes to check for artists.

    Returns
    -------
    :class:`bool`
    """
    if not (ax.lines + ax.collections + ax.patches + ax.artists + ax.texts + ax.images):
        return True
    else:
        return False


def init_axes(ax=None, projection=None, minsize=1.0, **kwargs):
    """
    Get or create an Axes from an optionally-specified starting Axes.

    Parameters
    -----------
    ax : :class:`~matplotlib.axes.Axes`
        Specified starting axes, optional.
    projection : :class:`str`
        Whether to create a projected (e.g. ternary) axes.
    minsize : :class:`float`
        Minimum figure dimension (inches).

    Returns
    --------
    ax : :class:`~matplotlib.axes.Axes`
    """
    if "figsize" in kwargs.keys():
        fs = kwargs["figsize"]
        kwargs["figsize"] = (
            max(fs[0], minsize),
            max(fs[1], minsize),
        )  # minimum figsize
    if projection is not None:  # e.g. ternary
        if ax is None:
            fig, ax = plt.subplots(
                1,
                subplot_kw=dict(projection=projection),
                **subkwargs(kwargs, plt.subplots, plt.figure)
            )
        else:  # axes passed
            if ax.name != "ternary":
                # if an axis is converted previously, but the original axes reference
                # is used again, we'll end up with an error
                current_axes = get_ordered_axes(ax.figure)
                try:
                    ix = current_axes.index(ax)
                    axes = axes_to_ternary(ax)  # returns list of axes
                    ax = axes[ix]
                except ValueError:  # ax is not in list
                    # ASSUMPTION due to mis-referencing:
                    # take the first ternary one
                    ax = [a for a in current_axes if a.name == "ternary"][0]
            else:
                pass
    else:
        if ax is None:
            fig, ax = plt.subplots(1, **subkwargs(kwargs, plt.subplots, plt.figure))
    return ax


def share_axes(axes, which="xy"):
    """
    Link the x, y or both axes across a group of :class:`~matplotlib.axes.Axes`.

    Parameters
    -----------
    axes : :class:`list`
        List of axes to link.
    which : :class:`str`
        Which axes to link. If :code:`x`, link the x-axes; if :code:`y` link the y-axes,
        otherwise link both.
    """
    if which == "both":
        which = "xy"
    if "x" in which:
        [a.sharex(axes[0]) for a in axes[1:]]
    if "y" in which:
        [a.sharey(axes[0]) for a in axes[1:]]


def get_twins(ax, which="y"):
    """
    Get twin axes of a specified axis.

    Parameters
    -----------
    ax : :class:`matplotlib.axes.Axes`
        Axes to get twins for.
    which : :class:`str`
        Which twins to get (shared :code:`'x'`, shared :code:`'y'` or the concatenatation
        of both, :code:`'xy'`).

    Returns
    --------
    :class:`list`

    Notes
    ------
    This function was designed to assist in avoiding creating a series of duplicate
    axes when replotting on an existing axis using a function which would typically
    create a twin axis.
    """
    s = []
    if "y" in which:
        s += ax.get_shared_y_axes().get_siblings(ax)
    if "x" in which:
        s += ax.get_shared_x_axes().get_siblings(ax)
    return list(
        set([a for a in s if (a is not ax) & (a.bbox.bounds == ax.bbox.bounds)])
    )


def subaxes(ax, side="bottom", width=0.2, moveticks=True):
    """
    Append a sub-axes to one side of an axes.

    Parameters
    -----------
    ax : :class:`matplotlib.axes.Axes`
        Axes to append a sub-axes to.
    side : :class:`str`
        Which side to append the axes on.
    width : :class:`float`
        Fraction of width to give to the subaxes.
    moveticks : :class:`bool`
        Whether to move ticks to the outer axes.

    Returns
    -------
    :class:`matplotlib.axes.Axes`
        Subaxes instance.
    """
    div = make_axes_locatable(ax)
    ax.divider = div

    if side in ["bottom", "top"]:
        which = "x"
        subax = div.append_axes(side, width, pad=0, sharex=ax)
        div.subax = subax
        subax.yaxis.set_visible(False)
        subax.spines["left"].set_visible(False)
        subax.spines["right"].set_visible(False)

    else:
        which = "y"
        subax = div.append_axes(side, width, pad=0, sharex=ax)
        div.subax = subax
        subax.yaxis.set_visible(False)
        subax.spines["top"].set_visible(False)
        subax.spines["bottom"].set_visible(False)

    share_axes([ax, subax], which=which)
    if moveticks:
        ax.tick_params(
            axis=which, which="both", bottom=False, top=False, labelbottom=False
        )
    return subax


def add_colorbar(mappable, **kwargs):
    """
    Adds a colorbar to a given mappable object.

    Source: http://joseph-long.com/writing/colorbars/

    Parameters
    ----------
    mappable
        The Image, ContourSet, etc. to which the colorbar applies.

    Returns
    -------
    :class:`matplotlib.colorbar.Colorbar`

    Todo
    ----
    *  Where no mappable specificed, get most recent axes, and check for collections etc
    """
    ax = kwargs.get("ax", None)
    if hasattr(mappable, "axes"):
        ax = ax or mappable.axes
    elif hasattr(mappable, "ax"):
        ax = ax or mappable.ax

    position = kwargs.pop("position", "right")
    size = kwargs.pop("size", "5%")
    pad = kwargs.pop("pad", 0.05)

    fig = ax.figure
    if ax.name == "ternary":
        cax = ax.inset_axes([1.05, 0.1, 0.05, 0.9], transform=ax.transAxes)
        colorbar = fig.colorbar(mappable, cax=cax, **kwargs)
    else:
        divider = make_axes_locatable(ax)
        cax = divider.append_axes(position, size=size, pad=pad)
        colorbar = fig.colorbar(mappable, cax=cax, **kwargs)
    return colorbar

1	"""
2	Functions for creating, ordering and modifying :class:`~matplolib.axes.Axes`.
3	"""
4	import warnings	12✔
5
6	import matplotlib.pyplot as plt	12✔
7	import numpy as np	12✔
8	from mpl_toolkits.axes_grid1 import make_axes_locatable	12✔
9
10	from ..log import Handle	12✔
11	from ..meta import subkwargs	12✔
12
13	logger = Handle(__name__)	12✔
14
15
16	def get_ordered_axes(fig):	12✔
17	"""
18	Get the axes from a figure, which may or may not have been modified by
19	pyrolite functions. This ensures that ordering is preserved.
20	"""
21	if hasattr(fig, "orderedaxes"): # previously modified	12✔
22	axes = fig.orderedaxes	12✔
23	else: # unmodified axes
24	axes = fig.axes	12✔
25	return axes	12✔
26
27
28	def get_axes_index(ax):	12✔
29	"""
30	Get the three-digit integer index of a subplot in a regular grid.
31
32	Parameters
33	-----------
34	ax : :class:`matplotlib.axes.Axes`
35	Axis to to get the gridspec index for.
36
37	Returns
38	-----------
39	:class:`tuple`
40	Rows, columns and axis index for the gridspec.
41	"""
42	nrow, ncol = ax.get_gridspec()._nrows, ax.get_gridspec()._ncols	12✔
43	index = get_ordered_axes(ax.figure).index(ax)	12✔
44	triple = nrow, ncol, index + 1	12✔
45	return triple	12✔
46
47
48	def replace_with_ternary_axis(ax):	12✔
49	"""
50	Replace a specified axis with a ternary equivalent.
51
52	Parameters
53	------------
54	ax : :class:`~matplotlib.axes.Axes`
55
56	Returns
57	------------
58	tax : :class:`~mpltern.ternary.TernaryAxes`
59	"""
60	if ax.name != "ternary":	12✔
61	if not check_default_axes(ax):	12✔
UNCOV 62	if not check_empty(ax):	×
UNCOV 63	warnings.warn(	×
64	"Non-empty, non-default bivariate axes being replaced with ternary axes."
65	)
66	else:
UNCOV 67	logger.info(	×
68	"Non-default bivraite axes being replaced with ternary axes."
69	)
70	fig = ax.figure	12✔
71	axes = get_ordered_axes(fig)	12✔
72	idx = axes.index(ax)	12✔
73	tax = fig.add_subplot(*get_axes_index(ax), projection="ternary")	12✔
74	fig.add_axes(tax) # make sure the axis is added to fig.children	12✔
75	fig.delaxes(ax) # remove the original axes	12✔
76	# update figure ordered axes
77	fig.orderedaxes = [a if ix != idx else tax for (ix, a) in enumerate(axes)]	12✔
78	return tax	12✔
79
80
81	def label_axes(ax, labels=[], **kwargs):	12✔
82	"""
83	Convenience function for labelling rectilinear and ternary axes.
84
85	Parameters
86	-----------
87	ax : :class:`~matplotlib.axes.Axes`
88	Axes to label.
89	labels : :class:`list`
90	List of labels: [x, y] \| or [t, l, r]
91	"""
92	if (ax.name == "ternary") and (len(labels) == 3):	12✔
93	tvar, lvar, rvar = labels	12✔
94	ax.set_tlabel(tvar, **kwargs)	12✔
95	ax.set_llabel(lvar, **kwargs)	12✔
96	ax.set_rlabel(rvar, **kwargs)	12✔
97	elif len(labels) == 2:	12✔
98	xvar, yvar = labels	12✔
99	ax.set_xlabel(xvar, **kwargs)	12✔
100	ax.set_ylabel(yvar, **kwargs)	12✔
101	else:
UNCOV 102	raise NotImplementedError	×
103
104
105	def axes_to_ternary(ax):	12✔
106	"""
107	Set axes to ternary projection after axis creation. As currently implemented,
108	note that this will replace and reorder axes as acecessed from the figure (the
109	ternary axis will then be at the end), and as such this returns a list of axes
110	in the correct order.
111
112	Parameters
113	-----------
114	ax : :class:`~matplotlib.axes.Axes` \| :class:`list` (:class:`~matplotlib.axes.Axes`)
115	Axis (or axes) to convert projection for.
116
117	Returns
118	---------
119	axes : :class:`list' (:class:`~matplotlib.axes.Axes`, class:`~mpltern.ternary.TernaryAxes`)
120	"""
121
122	if isinstance(ax, (list, np.ndarray, tuple)): # multiple Axes specified	12✔
123	fig = ax[0].figure	12✔
124	for a in ax: # axes to set to ternary	12✔
125	replace_with_ternary_axis(a)	12✔
126	else: # a single Axes is passed
127	fig = ax.figure	12✔
128	replace_with_ternary_axis(ax)	12✔
129	return fig.orderedaxes	12✔
130
131
132	def check_default_axes(ax):	12✔
133	"""
134	Simple test to check whether an axis is empty of artists and hasn't been
135	rescaled from the default extent.
136
137	Parameters
138	-----------
139	ax : :class:`matplotlib.axes.Axes`
140	Axes to check for artists and scaling.
141
142	Returns
143	-------
144	:class:`bool`
145	"""
146
147	if np.allclose(ax.axis(), np.array([0, 1, 0, 1])):	12✔
148	return check_empty(ax)	12✔
149	else:
UNCOV 150	return False	×
151
152
153	def check_empty(ax):	12✔
154	"""
155	Simple test to check whether an axis is empty of artists.
156
157	Parameters
158	-----------
159	ax : :class:`matplotlib.axes.Axes`
160	Axes to check for artists.
161
162	Returns
163	-------
164	:class:`bool`
165	"""
166	if not (ax.lines + ax.collections + ax.patches + ax.artists + ax.texts + ax.images):	12✔
167	return True	12✔
168	else:
UNCOV 169	return False	×
170
171
172	def init_axes(ax=None, projection=None, minsize=1.0, **kwargs):	12✔
173	"""
174	Get or create an Axes from an optionally-specified starting Axes.
175
176	Parameters
177	-----------
178	ax : :class:`~matplotlib.axes.Axes`
179	Specified starting axes, optional.
180	projection : :class:`str`
181	Whether to create a projected (e.g. ternary) axes.
182	minsize : :class:`float`
183	Minimum figure dimension (inches).
184
185	Returns
186	--------
187	ax : :class:`~matplotlib.axes.Axes`
188	"""
189	if "figsize" in kwargs.keys():	12✔
190	fs = kwargs["figsize"]	12✔
191	kwargs["figsize"] = (	12✔
192	max(fs[0], minsize),
193	max(fs[1], minsize),
194	) # minimum figsize
195	if projection is not None: # e.g. ternary	12✔
196	if ax is None:	12✔
197	fig, ax = plt.subplots(	12✔
198	1,
199	subplot_kw=dict(projection=projection),
200	**subkwargs(kwargs, plt.subplots, plt.figure)
201	)
202	else: # axes passed
203	if ax.name != "ternary":	12✔
204	# if an axis is converted previously, but the original axes reference
205	# is used again, we'll end up with an error
206	current_axes = get_ordered_axes(ax.figure)	12✔
207	try:	12✔
208	ix = current_axes.index(ax)	12✔
209	axes = axes_to_ternary(ax) # returns list of axes	12✔
210	ax = axes[ix]	12✔
UNCOV 211	except ValueError: # ax is not in list	×
212	# ASSUMPTION due to mis-referencing:
213	# take the first ternary one
UNCOV 214	ax = [a for a in current_axes if a.name == "ternary"][0]	×
215	else:
216	pass	12✔
217	else:
218	if ax is None:	12✔
219	fig, ax = plt.subplots(1, **subkwargs(kwargs, plt.subplots, plt.figure))	12✔
220	return ax	12✔
221
222
223	def share_axes(axes, which="xy"):	12✔
224	"""
225	Link the x, y or both axes across a group of :class:`~matplotlib.axes.Axes`.
226
227	Parameters
228	-----------
229	axes : :class:`list`
230	List of axes to link.
231	which : :class:`str`
232	Which axes to link. If :code:`x`, link the x-axes; if :code:`y` link the y-axes,
233	otherwise link both.
234	"""
235	if which == "both":	12✔
236	which = "xy"	12✔
237	if "x" in which:	12✔
238	[a.sharex(axes[0]) for a in axes[1:]]	12✔
239	if "y" in which:	12✔
240	[a.sharey(axes[0]) for a in axes[1:]]	12✔
241
242
243	def get_twins(ax, which="y"):	12✔
244	"""
245	Get twin axes of a specified axis.
246
247	Parameters
248	-----------
249	ax : :class:`matplotlib.axes.Axes`
250	Axes to get twins for.
251	which : :class:`str`
252	Which twins to get (shared :code:`'x'`, shared :code:`'y'` or the concatenatation
253	of both, :code:`'xy'`).
254
255	Returns
256	--------
257	:class:`list`
258
259	Notes
260	------
261	This function was designed to assist in avoiding creating a series of duplicate
262	axes when replotting on an existing axis using a function which would typically
263	create a twin axis.
264	"""
265	s = []	12✔
266	if "y" in which:	12✔
267	s += ax.get_shared_y_axes().get_siblings(ax)	12✔
268	if "x" in which:	12✔
269	s += ax.get_shared_x_axes().get_siblings(ax)	12✔
270	return list(	12✔
271	set([a for a in s if (a is not ax) & (a.bbox.bounds == ax.bbox.bounds)])
272	)
273
274
275	def subaxes(ax, side="bottom", width=0.2, moveticks=True):	12✔
276	"""
277	Append a sub-axes to one side of an axes.
278
279	Parameters
280	-----------
281	ax : :class:`matplotlib.axes.Axes`
282	Axes to append a sub-axes to.
283	side : :class:`str`
284	Which side to append the axes on.
285	width : :class:`float`
286	Fraction of width to give to the subaxes.
287	moveticks : :class:`bool`
288	Whether to move ticks to the outer axes.
289
290	Returns
291	-------
292	:class:`matplotlib.axes.Axes`
293	Subaxes instance.
294	"""
295	div = make_axes_locatable(ax)	12✔
296	ax.divider = div	12✔
297
298	if side in ["bottom", "top"]:	12✔
299	which = "x"	12✔
300	subax = div.append_axes(side, width, pad=0, sharex=ax)	12✔
301	div.subax = subax	12✔
302	subax.yaxis.set_visible(False)	12✔
303	subax.spines["left"].set_visible(False)	12✔
304	subax.spines["right"].set_visible(False)	12✔
305
306	else:
307	which = "y"	12✔
308	subax = div.append_axes(side, width, pad=0, sharex=ax)	12✔
309	div.subax = subax	12✔
310	subax.yaxis.set_visible(False)	12✔
311	subax.spines["top"].set_visible(False)	12✔
312	subax.spines["bottom"].set_visible(False)	12✔
313
314	share_axes([ax, subax], which=which)	12✔
315	if moveticks:	12✔
316	ax.tick_params(	12✔
317	axis=which, which="both", bottom=False, top=False, labelbottom=False
318	)
319	return subax	12✔
320
321
322	def add_colorbar(mappable, **kwargs):	12✔
323	"""
324	Adds a colorbar to a given mappable object.
325
326	Source: http://joseph-long.com/writing/colorbars/
327
328	Parameters
329	----------
330	mappable
331	The Image, ContourSet, etc. to which the colorbar applies.
332
333	Returns
334	-------
335	:class:`matplotlib.colorbar.Colorbar`
336
337	Todo
338	----
339	* Where no mappable specificed, get most recent axes, and check for collections etc
340	"""
341	ax = kwargs.get("ax", None)	12✔
342	if hasattr(mappable, "axes"):	12✔
343	ax = ax or mappable.axes	12✔
344	elif hasattr(mappable, "ax"):	×
345	ax = ax or mappable.ax	×
346
347	position = kwargs.pop("position", "right")	12✔
348	size = kwargs.pop("size", "5%")	12✔
349	pad = kwargs.pop("pad", 0.05)	12✔
350
351	fig = ax.figure	12✔
352	if ax.name == "ternary":	12✔
353	cax = ax.inset_axes([1.05, 0.1, 0.05, 0.9], transform=ax.transAxes)	12✔
354	colorbar = fig.colorbar(mappable, cax=cax, **kwargs)	12✔
355	else:
356	divider = make_axes_locatable(ax)	12✔
357	cax = divider.append_axes(position, size=size, pad=pad)	12✔
358	colorbar = fig.colorbar(mappable, cax=cax, **kwargs)	12✔
359	return colorbar	12✔

morganjwilliams / pyrolite / 5497027953

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous