-
Notifications
You must be signed in to change notification settings - Fork 24
Expand file tree
/
Copy pathui.py
More file actions
240 lines (202 loc) · 5.96 KB
/
ui.py
File metadata and controls
240 lines (202 loc) · 5.96 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
#!/usr/bin/env python3
"""
The starting point for creating ultraplot figures.
"""
import matplotlib.pyplot as plt
from . import axes as paxes
from . import figure as pfigure
from . import gridspec as pgridspec
from .internals import (
_not_none,
_pop_params,
_pop_props,
_pop_rc,
docstring,
ic, # noqa: F401
)
__all__ = [
"figure",
"subplot",
"subplots",
"show",
"close",
"switch_backend",
"ion",
"ioff",
"isinteractive",
]
# Docstrings
_pyplot_docstring = """
This is included so you don't have to import `~matplotlib.pyplot`.
"""
docstring._snippet_manager["ui.pyplot"] = _pyplot_docstring
def _parse_figsize(kwargs):
"""
Translate `figsize` into ultraplot-specific `figwidth` and `figheight` keys.
"""
# WARNING: Cannot have Figure.__init__() interpret figsize() because
# the figure manager fills it with the matplotlib default.
figsize = kwargs.pop("figsize", None)
figwidth = kwargs.pop("figwidth", None)
figheight = kwargs.pop("figheight", None)
if figsize is not None:
figsize_width, figsize_height = figsize
figwidth = _not_none(figwidth=figwidth, figsize_width=figsize_width)
figheight = _not_none(figheight=figheight, figsize_height=figsize_height)
kwargs["figwidth"] = figwidth
kwargs["figheight"] = figheight
@docstring._snippet_manager
def show(*args, **kwargs):
"""
Call `matplotlib.pyplot.show`.
%(ui.pyplot)s
Parameters
----------
*args, **kwargs
Passed to `matplotlib.pyplot.show`.
"""
return plt.show(*args, **kwargs)
@docstring._snippet_manager
def close(*args, **kwargs):
"""
Call `matplotlib.pyplot.close`.
%(ui.pyplot)s
Parameters
----------
*args, **kwargs
Passed to `matplotlib.pyplot.close`.
"""
return plt.close(*args, **kwargs)
@docstring._snippet_manager
def switch_backend(*args, **kwargs):
"""
Call `matplotlib.pyplot.switch_backend`.
%(ui.pyplot)s
Parameters
----------
*args, **kwargs
Passed to `matplotlib.pyplot.switch_backend`.
"""
return plt.switch_backend(*args, **kwargs)
@docstring._snippet_manager
def ion():
"""
Call `matplotlib.pyplot.ion`.
%(ui.pyplot)s
"""
return plt.ion()
@docstring._snippet_manager
def ioff():
"""
Call `matplotlib.pyplot.ioff`.
%(ui.pyplot)s
"""
return plt.ioff()
@docstring._snippet_manager
def isinteractive():
"""
Call `matplotlib.pyplot.isinteractive`.
%(ui.pyplot)s
"""
return plt.isinteractive()
@docstring._snippet_manager
def figure(**kwargs):
"""
Create an empty figure. Subplots can be subsequently added using
`~ultraplot.figure.Figure.add_subplot` or `~ultraplot.figure.Figure.subplots`.
This command is analogous to `matplotlib.pyplot.figure`.
Parameters
----------
%(figure.figure)s
Other parameters
----------------
**kwargs
Passed to `ultraplot.figure.Figure.format`.
See also
--------
ultraplot.ui.subplots
ultraplot.figure.Figure.add_subplot
ultraplot.figure.Figure.subplots
ultraplot.figure.Figure
matplotlib.figure.Figure
"""
_parse_figsize(kwargs)
return plt.figure(FigureClass=pfigure.Figure, **kwargs)
@docstring._snippet_manager
def subplot(**kwargs):
"""
Return a figure and a single subplot.
This command is analogous to `matplotlib.pyplot.subplot`,
except the figure instance is also returned.
Other parameters
----------------
%(figure.figure)s
**kwargs
Passed to `ultraplot.figure.Figure.format` or the
projection-specific ``format`` command for the axes.
Returns
-------
fig : `ultraplot.figure.Figure`
The figure instance.
ax : `ultraplot.axes.Axes`
The axes instance.
See also
--------
ultraplot.ui.figure
ultraplot.figure.Figure.subplot
ultraplot.figure.Figure
matplotlib.figure.Figure
"""
_parse_figsize(kwargs)
rc_kw, rc_mode = _pop_rc(kwargs)
kwsub = _pop_props(kwargs, "patch") # e.g. 'color'
kwsub.update(_pop_params(kwargs, pfigure.Figure._parse_proj))
for sig in paxes.Axes._format_signatures.values():
kwsub.update(_pop_params(kwargs, sig))
kwargs["aspect"] = kwsub.pop("aspect", None) # keyword conflict
fig = figure(rc_kw=rc_kw, **kwargs)
ax = fig.add_subplot(rc_kw=rc_kw, **kwsub)
return fig, ax
@docstring._snippet_manager
def subplots(*args, **kwargs):
"""
Return a figure and an arbitrary grid of subplots.
This command is analogous to `matplotlib.pyplot.subplots`,
except the subplots are stored in a :class:`~ultraplot.gridspec.SubplotGrid`.
Parameters
----------
%(figure.subplots_params)s
Other parameters
----------------
%(figure.figure)s
**kwargs
Passed to `ultraplot.figure.Figure.format` or the
projection-specific ``format`` command for each axes.
Returns
-------
fig : `ultraplot.figure.Figure`
The figure instance.
axs : `ultraplot.gridspec.SubplotGrid`
The axes instances stored in a :class:`~ultraplot.gridspec.SubplotGrid`.
See also
--------
ultraplot.ui.figure
ultraplot.figure.Figure.subplots
ultraplot.gridspec.SubplotGrid
ultraplot.figure.Figure
matplotlib.figure.Figure
"""
_parse_figsize(kwargs)
rc_kw, rc_mode = _pop_rc(kwargs)
kwsubs = _pop_props(kwargs, "patch") # e.g. 'color'
kwsubs.update(_pop_params(kwargs, pfigure.Figure._add_subplots))
kwsubs.update(_pop_params(kwargs, pgridspec.GridSpec._update_params))
for sig in paxes.Axes._format_signatures.values():
kwsubs.update(_pop_params(kwargs, sig))
for key in ("subplot_kw", "gridspec_kw"): # deprecated args
if key in kwargs:
kwsubs[key] = kwargs.pop(key)
kwargs["aspect"] = kwsubs.pop("aspect", None) # keyword conflict
fig = figure(rc_kw=rc_kw, **kwargs)
axs = fig.add_subplots(*args, rc_kw=rc_kw, **kwsubs)
return fig, axs