-
Notifications
You must be signed in to change notification settings - Fork 94
/
plot.py
4621 lines (4255 loc) 路 183 KB
/
plot.py
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
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
#!/usr/bin/env python3
"""
The second-level axes subclass used for all ProPlot figures.
Implements plotting method overrides.
"""
import functools
import inspect
import itertools
import re
import sys
from numbers import Integral
import matplotlib.axes as maxes
import matplotlib.cm as mcm
import matplotlib.collections as mcollections
import matplotlib.colors as mcolors
import matplotlib.contour as mcontour
import matplotlib.lines as mlines
import matplotlib.patches as mpatches
import matplotlib.ticker as mticker
import numpy as np
import numpy.ma as ma
from .. import colors as pcolors
from .. import constructor
from .. import ticker as pticker
from ..config import rc
from ..internals import ic # noqa: F401
from ..internals import (
_guide_kw_to_arg,
_guide_kw_to_obj,
_keyword_to_positional,
_not_none,
_pop_kwargs,
_pop_params,
_pop_props,
_process_props,
_snippet_manager,
_state_context,
docstring,
warnings,
)
from ..utils import edges, edges2d, to_xyz
from . import base
try:
from cartopy.crs import PlateCarree
except ModuleNotFoundError:
PlateCarree = object
__all__ = ['PlotAxes']
# Constants
EDGEWIDTH = 0.25 # native linewidth used for grid box edges in matplotlib
BASEMAP_FUNCS = ( # default latlon=True
'barbs', 'contour', 'contourf', 'hexbin',
'imshow', 'pcolor', 'pcolormesh', 'plot',
'quiver', 'scatter', 'streamplot', 'step',
)
CARTOPY_FUNCS = ( # default transform=PlateCarree()
'barbs', 'contour', 'contourf',
'fill', 'fill_between', 'fill_betweenx', # NOTE: not sure if these work
'imshow', 'pcolor', 'pcolormesh', 'plot',
'quiver', 'scatter', 'streamplot', 'step',
'tricontour', 'tricontourf', 'tripcolor', # NOTE: not sure why these work
)
# Data argument docstrings
_args_1d_docstring = """
*args : {y} or {x}, {y}
The data passed as positional or keyword arguments. Interpreted as follows:
* If only `{y}` coordinates are passed, try to infer the `{x}` coordinates
from the `~pandas.Series` or `~pandas.DataFrame` indices or the
`~xarray.DataArray` coordinates. Otherwise, the `{x}` coordinates
are ``np.arange(0, {y}.shape[0])``.
* If the `{y}` coordinates are a 2D array, plot each column of data in succession
(except where each column of data represents a statistical distribution, as with
``boxplot``, ``violinplot``, or when using ``means=True`` or ``medians=True``).
* If any arguments are `pint.Quantity`, auto-add the pint unit registry
to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`.
A `pint.Quantity` embedded in an `xarray.DataArray` is also supported.
"""
_args_1d_multi_docstring = """
*args : {y}2 or {x}, {y}2, or {x}, {y}1, {y}2
The data passed as positional or keyword arguments. Interpreted as follows:
* If only `{y}` coordinates are passed, try to infer the `{x}` coordinates from
the `~pandas.Series` or `~pandas.DataFrame` indices or the `~xarray.DataArray`
coordinates. Otherwise, the `{x}` coordinates are ``np.arange(0, {y}2.shape[0])``.
* If only `{x}` and `{y}2` coordinates are passed, set the `{y}1` coordinates
to zero. This draws elements originating from the zero line.
* If both `{y}1` and `{y}2` are provided, draw elements between these points. If
either are 2D, draw elements by iterating over each column.
* If any arguments are `pint.Quantity`, auto-add the pint unit registry
to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`.
A `pint.Quantity` embedded in an `xarray.DataArray` is also supported.
"""
_args_2d_docstring = """
*args : {z} or x, y, {z}
The data passed as positional or keyword arguments. Interpreted as follows:
* If only {zvar} coordinates are passed, try to infer the `x` and `y` coordinates
from the `~pandas.DataFrame` indices and columns or the `~xarray.DataArray`
coordinates. Otherwise, the `y` coordinates are ``np.arange(0, y.shape[0])``
and the `x` coordinates are ``np.arange(0, y.shape[1])``.
* For ``pcolor`` and ``pcolormesh``, calculate coordinate *edges* using
`~proplot.utils.edges` or `~proplot.utils.edges2d` if *centers* were provided.
For all other methods, calculate coordinate *centers* if *edges* were provided.
* If the `x` or `y` coordinates are `pint.Quantity`, auto-add the pint unit registry
to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. If the
{zvar} coordinates are `pint.Quantity`, pass the magnitude to the plotting
command. A `pint.Quantity` embedded in an `xarray.DataArray` is also supported.
"""
_snippet_manager['plot.args_1d_y'] = _args_1d_docstring.format(x='x', y='y')
_snippet_manager['plot.args_1d_x'] = _args_1d_docstring.format(x='y', y='x')
_snippet_manager['plot.args_1d_multiy'] = _args_1d_multi_docstring.format(x='x', y='y')
_snippet_manager['plot.args_1d_multix'] = _args_1d_multi_docstring.format(x='y', y='x')
_snippet_manager['plot.args_2d'] = _args_2d_docstring.format(z='z', zvar='`z`')
_snippet_manager['plot.args_2d_flow'] = _args_2d_docstring.format(z='u, v', zvar='`u` and `v`') # noqa: E501
# Shared docstrings
_args_1d_shared_docstring = """
data : dict-like, optional
A dict-like dataset container (e.g., `~pandas.DataFrame` or
`~xarray.DataArray`). If passed, positional arguments can optionally
be string `data` keys and the arrays used for plotting are retrieved
with ``data[key]``. This is a `native matplotlib feature
<https://matplotlib.org/stable/gallery/misc/keyword_plotting.html>`__.
autoformat : bool, optional
Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles,
legend titles, and colorbar labels are automatically configured when a
`~pandas.Series`, `~pandas.DataFrame`, `~xarray.DataArray`, or `~pint.Quantity`
is passed to the plotting command. Default is :rc:`autoformat`.
"""
_args_2d_shared_docstring = """
%(plot.args_1d_shared)s
order : {{'C', 'F'}}, optional
If ``'C'`` (C-style row-major order), `z` coordinates should be shaped
``(y, x)``. If ``'F'`` (Fortran-style column-major order) `z` coordinates
should be shaped ``(x, y)``. Default is ``'C'``.
globe : bool, optional
For `proplot.axes.GeoAxes` only. Whether to enforce global coverage.
Default is ``False``. When set to ``True`` this does the following:
#. Interpolates input data to the North and South poles by setting the data
values at the poles to the mean from latitudes nearest each pole.
#. Makes meridional coverage "circular", i.e. the last longitude coordinate
equals the first longitude coordinate plus 360\N{DEGREE SIGN}.
#. When basemap is the backend, cycles 1D longitude vectors to fit within
the map edges. For example, if the central longitude is 90\N{DEGREE SIGN},
the data is shifted so that it spans -90\N{DEGREE SIGN} to 270\N{DEGREE SIGN}.
"""
_snippet_manager['plot.args_1d_shared'] = _args_1d_shared_docstring
_snippet_manager['plot.args_2d_shared'] = _args_2d_shared_docstring
# Auto colorbar and legend docstring
_guide_docstring = """
colorbar : bool, int, or str, optional
If not ``None``, this is a location specifying where to draw an
*inset* or *panel* colorbar from the resulting object(s). If ``True``,
the default :rc:`colorbar.loc` is used. Valid locations are described
in `~proplot.axes.Axes.colorbar`.
colorbar_kw : dict-like, optional
Extra keyword args for the call to `~proplot.axes.Axes.colorbar`.
legend : bool, int, or str, optional
If not ``None``, this is a location specifying where to draw an *inset*
or *panel* legend from the resulting object(s). If ``True``, the default
:rc:`legend.loc` is used. Valid locations are described in
`~proplot.axes.Axes.legend`.
legend_kw : dict-like, optional
Extra keyword args for the call to `~proplot.axes.Axes.legend`.
"""
_snippet_manager['plot.guide'] = _guide_docstring
# Misc shared 1D plotting docstrings
_inbounds_docstring = """
inbounds : bool, optional
Whether to restrict the default `y` (`x`) axis limits to account for only
in-bounds data when the `x` (`y`) axis limits have been locked. Default
is :rc:`axes.inbounds`. See also :rcraw:`cmap.inbounds`.
"""
_error_means_docstring = """
mean, means : bool, optional
Whether to plot the means of each column for 2D `{y}` coordinates. Means
are calculated with `numpy.nanmean`. If no other arguments are specified,
this also sets ``barstd=True`` (and ``boxstd=True`` for violin plots).
median, medians : bool, optional
Whether to plot the medians of each column for 2D `{y}` coordinates. Medians
are calculated with `numpy.nanmedian`. If no other arguments arguments are
specified, this also sets ``barstd=True`` (and ``boxstd=True`` for violin plots).
"""
_error_bars_docstring = """
barstd, barstds : bool, float, or 2-tuple of float, optional
Valid only if `mean` or `median` is ``True``. Standard deviation multiples for
*thin error bars* with optional whiskers (i.e., caps). If scalar, then +/- that
multiple is used. If ``True``, the default standard deviation range of +/-3 is used.
barpctile, barpctiles : bool, float, or 2-tuple of float, optional
Valid only if `mean` or `median` is ``True``. As with `barstd`, but instead
using percentiles for the error bars. If scalar, that percentile range is
used (e.g., ``90`` shows the 5th to 95th percentiles). If ``True``, the default
percentile range of 0 to 100 is used.
bardata : 2D array or 1D array, optional
Valid only if `mean` and `median` are ``False``. If shape is 2 x N, these
are the lower and upper bounds for the thin error bars. If shape is N, these
are the absolute, symmetric deviations from the central points.
boxstd, boxstds, boxpctile, boxpctiles, boxdata : optional
As with `barstd`, `barpctile`, and `bardata`, but for *thicker error bars*
representing a smaller interval than the thin error bars. If `boxstd` is
``True``, the default standard deviation range of +/-1 is used. If `boxpctiles`
is ``True``, the default percentile range of 25 to 75 is used (i.e., the
interquartile range). When "boxes" and "bars" are combined, this has the
effect of drawing miniature box-and-whisker plots.
capsize : float, optional
The cap size for thin error bars in points. Default is :rc:`errorbar.capsize`.
barz, barzorder, boxz, boxzorder : float, optional
The "zorder" for the thin and thick error bars. Default is ``2.5``.
barc, barcolor, boxc, boxcolor : color-spec, optional
Colors for the thin and thick error bars. Default is
:rc:`boxplot.whiskerprops.color`.
barlw, barlinewidth, boxlw, boxlinewidth : float, optional
Line widths for the thin and thick error bars, in points. The defaults
:rc:`boxplot.whiskerprops.linewidth` (bars) and four times that value (boxes).
boxm, boxmarker : bool or marker-spec, optional
Whether to draw a small marker in the middle of the box denoting the mean or
median position. Ignored if `boxes` is ``False``. Default is ``'o'``.
boxms, boxmarkersize : size-spec, optional
The marker size for the `boxmarker` marker in points ** 2. Default size
is equal to ``(2 * boxlinewidth) ** 2``.
boxmc, boxmarkercolor, boxmec, boxmarkeredgecolor : color-spec, optional
Color, face color, and edge color for the `boxmarker` marker. Default color
and edge color are ``'w'``.
"""
_error_shading_docstring = """
shadestd, shadestds, shadepctile, shadepctiles, shadedata : optional
As with `barstd`, `barpctile`, and `bardata`, but using *shading* to indicate
the error range. If `shadestds` is ``True``, the default standard deviation
range of +/-2 is used. If `shadepctiles` is ``True``, the default
percentile range of 10 to 90 is used.
fadestd, fadestds, fadepctile, fadepctiles, fadedata : optional
As with `shadestd`, `shadepctile`, and `shadedata`, but for an additional,
more faded, *secondary* shaded region. If `fadestds` is ``True``, the default
standard deviation range of +/-3 is used. If `fadepctiles` is ``True``,
the default percentile range of 0 to 100 is used.
shadec, shadecolor, fadec, fadecolor : color-spec, optional
Colors for the different shaded regions. Default is to inherit the parent color.
shadez, shadezorder, fadez, fadezorder : float, optional
The "zorder" for the different shaded regions. Default is ``1.5``.
shadea, shadealpha, fadea, fadealpha : float, optional
The opacity for the different shaded regions. Defaults are ``0.4`` and ``0.2``.
shadelw, shadelinewidth, fadelw, fadelinewidth : float, optional
The edge line width for the shading patches. Default is :rc:`patch.linewidth`.
shdeec, shadeedgecolor, fadeec, fadeedgecolor : float, optional
The edge color for the shading patches. Default is ``'none'``.
shadelabel, fadelabel : bool or str, optional
Labels for the shaded regions to be used as separate legend entries. To toggle
labels "on" and apply a *default* label, use e.g. ``shadelabel=True``. To apply
a *custom* label, use e.g. ``shadelabel='label'``. Otherwise, the shading is
drawn underneath the line and/or marker in the legend entry.
"""
_snippet_manager['plot.inbounds'] = _inbounds_docstring
_snippet_manager['plot.error_means_y'] = _error_means_docstring.format(y='y')
_snippet_manager['plot.error_means_x'] = _error_means_docstring.format(y='x')
_snippet_manager['plot.error_bars'] = _error_bars_docstring
_snippet_manager['plot.error_shading'] = _error_shading_docstring
# Color docstrings
_cycle_docstring = """
cycle : cycle-spec, optional
The cycle specifer, passed to the `~proplot.constructor.Cycle` constructor.
If the returned cycler is unchanged from the current cycler, the axes
cycler will not be reset to its first position. To disable property cycling
and just use black for the default color, use ``cycle=False``, ``cycle='none'``,
or ``cycle=()`` (analogous to disabling ticks with e.g. ``xformatter='none'``).
To restore the default property cycler, use ``cycle=True``.
cycle_kw : dict-like, optional
Passed to `~proplot.constructor.Cycle`.
"""
_cmap_norm_docstring = """
cmap : colormap-spec, optional
The colormap specifer, passed to the `~proplot.constructor.Colormap`
constructor function.
cmap_kw : dict-like, optional
Passed to `~proplot.constructor.Colormap`.
norm : norm-spec, optional
The continuous colormap normalizer, passed to the `~proplot.constructor.Norm`
constructor function. If `discrete` is ``True`` this is also used to normalize
values passed to `~proplot.colors.DiscreteNorm` before colors is selected.
norm_kw : dict-like, optional
Passed to `~proplot.constructor.Norm`.
discrete : bool, optional
If ``False``, then `~proplot.colors.DiscreteNorm` is not applied to the
colormap. Instead, for non-contour plots, the number of levels will be
roughly controlled by :rcraw:`cmap.lut`. This has a similar effect to
using `levels=large_number` but it may improve rendering speed. Default
is ``False`` for `~proplot.axes.Axes.imshow`, `~proplot.axes.Axes.matshow`,
`~proplot.axes.Axes.spy`, `~proplot.axes.Axes.hexbin`, `~proplot.axes.Axes.hist2d`,
and `~proplot.axes.Axes.heatmap` plots, but ``True`` otherwise.
sequential : bool, optional
Use :rc:`cmap.sequential` as the default colormap.
diverging : bool, optional
Use :rc:`cmap.diverging` as the default colormap and use
`~proplot.colors.DivergingNorm` as the default continuous normalizer.
This will also ensure auto-generated levels include a value at zero.
cyclic : bool, optional
Use :rc:`cmap.cyclic` as the default colormap and modify the default
arguments passed to `~proplot.colors.DiscreteNorm` so that colors
on either end are distinct.
sequential, diverging, cyclic, qualitative : bool, optional
Boolean arguments used if `cmap` is not passed. Set these to ``True``
to use the default :rcraw:`cmap.sequential`, :rcraw:`cmap.diverging`,
:rcraw:`cmap.cyclic`, and :rcraw:`cmap.qualitative` colormaps. The
latter three options also change level- and norm-generation behavior.
extend : {{'neither', 'min', 'max', 'both'}}, optional
Whether to assign unique colors to out-of-bounds data and draw
colorbar "extensions" when a colorbar is drawn.
"""
_snippet_manager['plot.cycle'] = _cycle_docstring
_snippet_manager['plot.cmap_norm'] = _cmap_norm_docstring
# Levels docstrings
# NOTE: In some functions we only need some components
_vlim_levels_docstring = """
vmin, vmax : float, optional
Used to determine level locations if `levels` or `values` is an integer.
Actual levels may not fall exactly on `vmin` and `vmax`, but the minimum
level will be no smaller than `vmin` and the maximum level will be
no larger than `vmax`. If `vmin` or `vmax` are not provided, the
minimum and maximum data values are used.
"""
_manual_levels_docstring = """
N
Shorthand for `levels`.
levels : int or sequence of float, optional
The number of level edges or a sequence of level edges. If the former,
`locator` is used to generate this many level edges at "nice" intervals.
If the latter, the levels should be monotonically increasing or
decreasing (note that decreasing levels will only work with ``pcolor``
plots, not ``contour`` plots). Default is :rc:`cmap.levels`.
values : int or sequence of float, optional
The number of level centers or a sequence of level centers. If the former,
`locator` is used to generate this many level centers at "nice" intervals.
If the latter, levels are inferred using `~proplot.utils.edges`.
This will override any `levels` input.
"""
_auto_levels_docstring = """
robust : bool, float, or 2-tuple, optional
If ``True`` and `vmin` or `vmax` were not provided, they are
determined from the 2nd and 98th data percentiles rather than the
minimum and maximum. If float, this percentile range is used (for example,
``90`` corresponds to the 5th to 95th percentiles). If 2-tuple of float,
these specific percentiles should be used. This feature is useful
when your data has large outliers. Default is :rc:`cmap.robust`.
inbounds : bool, optional
If ``True`` and `vmin` or `vmax` were not provided, when axis limits
have been explicitly restricted with `~matplotlib.axes.Axes.set_xlim`
or `~matplotlib.axes.Axes.set_ylim`, out-of-bounds data is ignored.
Default is :rc:`cmap.inbounds`. See also :rcraw:`axes.inbounds`.
locator : locator-spec, optional
The locator used to determine level locations if `levels` or `values`
is an integer. Passed to the `~proplot.constructor.Locator` constructor.
Default is `~matplotlib.ticker.MaxNLocator` with ``levels`` integer levels.
locator_kw : dict-like, optional
Passed to `~proplot.constructor.Locator`.
symmetric : bool, optional
If ``True``, automatically generated levels are symmetric about zero.
Default is always ``False``.
positive : bool, optional
If ``True``, automatically generated levels are positive with a minimum at zero.
Default is always ``False``.
negative : bool, optional
If ``True``, automatically generated levels are negative with a maximum at zero.
Default is always ``False``.
nozero : bool, optional
If ``True``, ``0`` is removed from the level list. This is mainly useful for
single-color `~matplotlib.axes.Axes.contour` plots.
"""
_snippet_manager['plot.levels_vlim'] = _vlim_levels_docstring
_snippet_manager['plot.levels_manual'] = _manual_levels_docstring
_snippet_manager['plot.levels_auto'] = _auto_levels_docstring
# Labels docstrings
_labels_1d_docstring = """
label, value : float or str, optional
The single legend label or colorbar coordinate to be used for this plotted
element. This is generally used with 1D input coordinates.
labels, values : sequence of float or sequence of str, optional
The legend labels or colorbar coordinates used for each plotted element.
Can be numeric or string, and must match the number of plotted elements.
This is generally used with 2D input coordinates.
"""
_labels_2d_docstring = """
labels : bool, optional
Whether to apply labels to contours and grid boxes. The text will be
white when the luminance of the underlying filled contour or grid box
is less than 50 and black otherwise.
labels_kw : dict-like, optional
Ignored if `labels` is ``False``. Extra keyword args for the labels.
For contour plots, this is passed to `~matplotlib.axes.Axes.clabel`.
Otherwise, this is passed to `~matplotlib.axes.Axes.text`.
fmt : format-spec, optional
Passed to the `~proplot.constructor.Norm` constructor, used to format
number labels. You can also use the `precision` keyword arg.
precision : int, optional
Maximum number of decimal places for the number labels. Number labels
are generated with the `~proplot.ticker.SimpleFormatter` formatter,
which permits limiting the precision.
label : str, optional
The legend label to be used for this object. In the case of
contours, this is paired with the the central artist in the artist
list returned by `matplotlib.contour.ContourSet.legend_elements`.
"""
_snippet_manager['plot.labels_1d'] = _labels_1d_docstring
_snippet_manager['plot.labels_2d'] = _labels_2d_docstring
# Plot docstring
_plot_docstring = """
Plot standard lines.
Parameters
----------
%(plot.args_1d_{y})s
%(plot.args_1d_shared)s
Other parameters
----------------
%(plot.cycle)s
%(plot.labels_1d)s
%(plot.guide)s
%(plot.error_means_{y})s
%(plot.error_bars)s
%(plot.error_shading)s
%(plot.inbounds)s
**kwargs
Passed to `~matplotlib.axes.Axes.plot`.
See also
--------
PlotAxes.plot
PlotAxes.plotx
matplotlib.axes.Axes.plot
"""
_snippet_manager['plot.plot'] = _plot_docstring.format(y='y')
_snippet_manager['plot.plotx'] = _plot_docstring.format(y='x')
# Step docstring
# NOTE: Internally matplotlib implements step with thin wrapper of plot
_step_docstring = """
Plot step lines.
Parameters
----------
%(plot.args_1d_{y})s
%(plot.args_1d_shared)s
Other parameters
----------------
%(plot.cycle)s
%(plot.labels_1d)s
%(plot.guide)s
%(plot.inbounds)s
**kwargs
Passed to `~matplotlib.axes.Axes.step`.
See also
--------
PlotAxes.step
PlotAxes.stepx
matplotlib.axes.Axes.step
"""
_snippet_manager['plot.step'] = _step_docstring.format(y='y')
_snippet_manager['plot.stepx'] = _step_docstring.format(y='x')
# Stem docstring
_stem_docstring = """
Plot stem lines.
Parameters
----------
%(plot.args_1d_{y})s
%(plot.args_1d_shared)s
Other parameters
----------------
%(plot.cycle)s
%(plot.guide)s
%(plot.inbounds)s
**kwargs
Passed to `~matplotlib.axes.Axes.stem`.
"""
_snippet_manager['plot.stem'] = _stem_docstring.format(y='x')
_snippet_manager['plot.stemx'] = _stem_docstring.format(y='x')
# Lines docstrings
_lines_docstring = """
Plot {orientation} lines.
Parameters
----------
%(plot.args_1d_multi{y})s
%(plot.args_1d_shared)s
Other parameters
----------------
stack, stacked : bool, optional
Whether to "stack" successive columns of the `{y}1` coordinates. If this
is ``True`` and `{y}2` was provided, it will be ignored.
negpos : bool, optional
Whether to color lines greater than zero with `poscolor` and lines less
than zero with `negcolor`.
negcolor, poscolor : color-spec, optional
Colors to use for the negative and positive lines. Ignored if `negpos`
is ``False``. Defaults are :rc:`negcolor` and :rc:`poscolor`.
c, color, colors : color-spec or sequence, optional
The line color(s).
ls, linestyle, linestyles : str or sequence, optional
The line style(s).
lw, linewidth, linewidths : float or sequence, optional
The line width(s).
%(plot.cycle)s
%(plot.labels_1d)s
%(plot.guide)s
%(plot.inbounds)s
**kwargs
Passed to `~matplotlib.axes.Axes.{prefix}lines`.
See also
--------
PlotAxes.vlines
PlotAxes.hlines
matplotlib.axes.Axes.vlines
matplotlib.axes.Axes.hlines
"""
_snippet_manager['plot.vlines'] = _lines_docstring.format(
y='y', prefix='v', orientation='vertical'
)
_snippet_manager['plot.hlines'] = _lines_docstring.format(
y='x', prefix='h', orientation='horizontal'
)
# Scatter docstring
_parametric_docstring = """
Plot a parametric line.
Parameters
----------
%(plot.args_1d_y)s
c, color, colors, values : array-like, optional
The parametric coordinate. These can be passed as a third
positional argument or as a keyword argument. They can also
be string labels instead of numbers and the resulting
colorbar ticks will be labeled accordingly.
%(plot.args_1d_shared)s
Other parameters
----------------
%(plot.cmap_norm)s
%(plot.levels_vlim)s
%(plot.guide)s
interp : int, optional
Interpolate to this many additional points between the parametric
coordinates. Default is ``0``. This can be increased to make the color
gradations between a small number of coordinates appear "smooth".
scalex, scaley : bool, optional
Whether the view limits are adapted to the data limits. The values are
passed on to `~matplotlib.axes.Axes.autoscale_view`.
%(plot.inbounds)s
**kwargs
Valid `~matplotlib.collections.LineCollection` properties.
Returns
-------
`~matplotlib.collections.LineCollection`
The parametric line. See `this matplotlib example \
<https://matplotlib.org/stable/gallery/lines_bars_and_markers/multicolored_line>`__.
See also
--------
PlotAxes.plot
PlotAxes.plotx
matplotlib.collections.LineCollection
"""
_snippet_manager['plot.parametric'] = _parametric_docstring
# Scatter function docstring
_scatter_docstring = """
Plot markers with flexible keyword arguments.
Parameters
----------
%(plot.args_1d_{y})s
s, size, ms, markersize : float or sequence of float, optional
The marker size(s). If this is an array matching the shape of `x` and `y`,
the units are scaled by `smin` and `smax`.
c, color, colors, mc, markercolor, markercolors \
: array-like or color-spec, optional
The marker fill color(s). If this is an array matching the shape of `x` and `y`,
the colors are generated using `cmap`, `norm`, `vmin`, and `vmax`.
smin, smax : float, optional
The minimum and maximum marker size in units ``points**2`` used to scale
`s`. If not provided, the marker sizes are equivalent to the values in `s`.
%(plot.levels_vlim)s
%(plot.args_1d_shared)s
Other parameters
----------------
lw, linewidth, linewidths, markeredgewidth, markeredgewidths \
: float or sequence, optional
The marker edge width.
edgecolors, markeredgecolor, markeredgecolors \
: color-spec or sequence, optional
The marker edge color.
%(plot.cmap_norm)s
%(plot.levels_manual)s
%(plot.levels_auto)s
%(plot.cycle)s
%(plot.labels_1d)s
%(plot.guide)s
%(plot.error_means_{y})s
%(plot.error_bars)s
%(plot.error_shading)s
%(plot.inbounds)s
**kwargs
Passed to `~matplotlib.axes.Axes.scatter`.
See also
--------
PlotAxes.scatter
PlotAxes.scatterx
matplotlib.axes.Axes.scatter
"""
_snippet_manager['plot.scatter'] = _scatter_docstring.format(y='y')
_snippet_manager['plot.scatterx'] = _scatter_docstring.format(y='x')
# Bar function docstring
_bar_docstring = """
Plot individual, grouped, or stacked bars.
Parameters
----------
%(plot.args_1d_{y})s
width : float or array-like, optional
The width(s) of the bars relative to the {x} coordinate step size.
Can be passed as a third positional argument.
{bottom} : float or array-like, optional
The coordinate(s) of the {bottom} edge of the bars. Default is
``0``. Can be passed as a fourth positinal argument.
absolute_width : bool, optional
Whether to make the `width` units *absolute*. If ``True``, this
restores the default matplotlib behavior. Default is ``False``.
%(plot.args_1d_shared)s
Other parameters
----------------
stack, stacked : bool, optional
Whether to stack columns of the input array or plot the bars
side-by-side in groups.
negpos : bool, optional
Whether to shade bars greater than zero with `poscolor` and bars less
than zero with `negcolor`.
negcolor, poscolor : color-spec, optional
Colors to use for the negative and positive bars. Ignored if `negpos`
is ``False``. Defaults are :rc:`negcolor` and :rc:`poscolor`.
lw, linewidth, linewidths : float, optional
The edge width for the bar patches.
ec, edgecolor, edgecolors : color-spec, optional
The edge color for the bar patches.
%(plot.cycle)s
%(plot.labels_1d)s
%(plot.guide)s
%(plot.error_means_{y})s
%(plot.error_bars)s
%(plot.inbounds)s
**kwargs
Passed to `~matplotlib.axes.Axes.bar{suffix}`.
See also
--------
PlotAxes.bar
PlotAxes.barh
matplotlib.axes.Axes.bar
matplotlib.axes.Axes.barh
"""
_snippet_manager['plot.bar'] = _bar_docstring.format(
x='x', y='y', bottom='bottom', suffix=''
)
_snippet_manager['plot.barh'] = _bar_docstring.format(
x='y', y='x', bottom='left', suffix='h'
)
# Area plot docstring
_fill_docstring = """
Plot individual, grouped, or overlaid shading patches.
Parameters
----------
%(plot.args_1d_multi{y})s
%(plot.args_1d_shared)s
Other parameters
----------------
stack, stacked : bool, optional
Whether to "stack" successive columns of the `{y}1` array. If this is
``True`` and `{y}2` was provided, it will be ignored.
negpos : bool, optional
Whether to shade where ``{y}1 >= {y}2`` with `poscolor` and where ``{y}1 < {y}2``
with `negcolor`. For example, to shade positive values red and negative values
blue, simply use ``ax.fill_between{suffix}({x}, {y}, negpos=True)``.
negcolor, poscolor : color-spec, optional
Colors to use for the negative and positive shaded regions. Ignored if `negpos`
is ``False``. Defaults are :rc:`negcolor` and :rc:`poscolor`.
where : ndarray, optional
Boolean ndarray mask for points you want to shade. See `this example \
<https://matplotlib.org/stable/gallery/pyplots/whats_new_98_4_fill_between.html>`__.
lw, linewidth, linewidths : float, optional
The edge width for the area patches.
ec, edgecolor, edgecolors : color-spec, optional
The edge color for the area patches.
%(plot.cycle)s
%(plot.labels_1d)s
%(plot.guide)s
%(plot.inbounds)s
**kwargs
Passed to `~matplotlib.axes.Axes.fill_between{suffix}`.
See also
--------
PlotAxes.area
PlotAxes.areax
PlotAxes.fill_between
PlotAxes.fill_betweenx
matplotlib.axes.Axes.fill_between
matplotlib.axes.Axes.fill_betweenx
"""
_snippet_manager['plot.fill_between'] = _fill_docstring.format(
x='x', y='y', suffix=''
)
_snippet_manager['plot.fill_betweenx'] = _fill_docstring.format(
x='y', y='x', suffix='x'
)
# Histogram docstrings
_weight_docstring = """
weights : array-like, optional
The weights associated with each point. If string this
can be retrieved from `data` (see below).
"""
_snippet_manager['plot.weights'] = _weight_docstring
_hist_docstring = """
Plot {orientation} histograms.
Parameters
----------
%(plot.args_1d_{y})s
bins : int or sequence of float, optional
The bin count or sequence of bins.
%(plot.weights)s
%(plot.args_1d_shared)s
Other parameters
----------------
%(plot.cycle)s
%(plot.labels_1d)s
%(plot.guide)s
**kwargs
Passed to `~matplotlib.axes.Axes.hist`.
See also
--------
PlotAxes.hist
PlotAxes.histh
matplotlib.axes.Axes.hist
"""
_snippet_manager['plot.hist'] = _hist_docstring.format(
y='x', orientation='vertical'
)
_snippet_manager['plot.histh'] = _hist_docstring.format(
y='x', orientation='horizontal'
)
# Box plot docstrings
_boxplot_docstring = """
Plot {orientation} boxes and whiskers with a nice default style.
Parameters
----------
%(plot.args_1d_{y})s
%(plot.args_1d_shared)s
Other parameters
----------------
mean, means : bool, optional
If ``True``, this passes ``showmeans=True`` and ``meanline=True`` to
`~matplotlib.axes.Axes.boxplot`.
fill : bool, optional
Whether to fill the box with a color.
fc, facecolor, fillcolor : color-spec or sequence, optional
The fill color for the boxes. Default is the next color cycler color. If
a sequence, it should be the same length as the number of objects.
a, alpha, fa, facealpha, fillalpha : float, optional
The opacity of the boxes. Default is ``1.0``. If a sequence, should
be the same length as the number of objects.
lw, linewidth, linewidths : float, optional
The linewidth of all objects. Default is :rc:`patch.linewidth`.
c, color, colors, ec, edgecolor, edgecolors : color-spec or sequence, optional
The color of all objects. Default is ``'black'``. If a sequence, should
be the same length as the number of objects.
meanls, medianls, meanlinestyle, medianlinestyle, meanlinestyles, medianlinestyles \
: line style-spec, optional
The line style for the mean and median lines drawn horizontally
across the box.
boxc, capc, whiskerc, flierc, meanc, medianc, \
boxcolor, capcolor, whiskercolor, fliercolor, meancolor, mediancolor \
boxcolors, capcolors, whiskercolors, fliercolors, meancolors, mediancolors \
: color-spec or sequence, optional
The color of various boxplot components. If a sequence, should be the
same length as the number of objects. These are shorthands so you don't
have to pass e.g. a ``boxprops`` dictionary.
boxlw, caplw, whiskerlw, flierlw, meanlw, medianlw, boxlinewidth, caplinewidth, \
meanlinewidth, medianlinewidth, whiskerlinewidth, flierlinewidth, boxlinewidths, \
caplinewidths, meanlinewidths, medianlinewidths, whiskerlinewidths, flierlinewidths \
: float, optional
The line width of various boxplot components. These are shorthands so
you don't have to pass e.g. a ``boxprops`` dictionary.
m, marker : marker-spec, optional
Marker style for the 'fliers', i.e. outliers.
ms, markersize : float, optional
Marker size for the 'fliers', i.e. outliers.
%(plot.cycle)s
%(plot.labels_1d)s
**kwargs
Passed to `matplotlib.axes.Axes.boxplot`.
See also
--------
PlotAxes.boxes
PlotAxes.boxesh
PlotAxes.boxplot
PlotAxes.boxploth
matplotlib.axes.Axes.boxplot
"""
_snippet_manager['plot.boxplot'] = _boxplot_docstring.format(
y='y', orientation='vertical'
)
_snippet_manager['plot.boxploth'] = _boxplot_docstring.format(
y='x', orientation='horizontal'
)
# Violin plot docstrings
_violinplot_docstring = """
Plot {orientation} violins with a nice default style matching
`this matplotlib example \
<https://matplotlib.org/stable/gallery/statistics/customized_violin.html>`__.
Parameters
----------
%(plot.args_1d_{y})s
%(plot.args_1d_shared)s
Other parameters
----------------
fc, facecolor, facecolors, fillcolor, fillcolors : color-spec or sequence, optional
The violin plot fill color. Default is the next color cycler color. If
a sequence, should be the same length as the number of objects.
c, color, colors, ec, edgecolor, edgecolors : color-spec or sequence, optional
The edge color for the violin patches. Default is ``'black'``. If a
sequence, should be the same length as the number of objects.
a, alpha, fa, facealpha, fillalpha : float or sequence, optional
The opacity of the violins. Default is ``1.0``. If a sequence,
should be the same length as the number of objects.
lw, linewidth, linewidths : float, optional
The linewidth of the line objects. Default is :rc:`patch.linewidth`.
%(plot.cycle)s
%(plot.labels_1d)s
%(plot.error_bars)s
**kwargs
Passed to `matplotlib.axes.Axes.violinplot`.
Note
----
It is no longer possible to show minima and maxima with whiskers --
while this is useful for `~matplotlib.axes.Axes.boxplot`\\ s it is
redundant for `~matplotlib.axes.Axes.violinplot`\\ s.
See also
--------
PlotAxes.violins
PlotAxes.violinsh
PlotAxes.violinplot
PlotAxes.violinploth
matplotlib.axes.Axes.violinplot
"""
_snippet_manager['plot.violinplot'] = _violinplot_docstring.format(
y='y', orientation='vertical'
)
_snippet_manager['plot.violinploth'] = _violinplot_docstring.format(
y='x', orientation='horizontal'
)
# Contour docstrings
_contour_docstring = """
Plot {descrip}.
Parameters
----------
%(plot.args_2d)s
%(plot.args_2d_shared)s
Other parameters
----------------
%(plot.cmap_norm)s
%(plot.levels_manual)s
%(plot.levels_vlim)s
%(plot.levels_auto)s
%(plot.labels_2d)s
%(plot.guide)s
{add}lw, linewidth, linewidths : optional
The width of the contour lines.
For `contourf` plots, lines are added between the filled contours.
ls, linestyle, linestyles : optional
The style of the contour lines.
For `contourf` plots, lines are added between the filled contours.
ec, edgecolor, edgecolors : optional
The color for the contour lines.
For `contourf` plots, lines are added between the filled contours.
c, color, colors : optional
The color(s) for the contour lines or filled contours. If not passed,
the color is determined by `cmap` and the `z` data.
**kwargs
Passed to `matplotlib.axes.Axes.{command}`.
See also
--------
PlotAxes.contour
PlotAxes.contourf
PlotAxes.tricontour
PlotAxes.tricontourf
matplotlib.axes.Axes.{command}
"""
_edgefix_docstring = """
edgefix : bool or float, optional
Whether to fix an issue where `white lines appear between filled contours
<https://stackoverflow.com/q/8263769/4970632>`__ in saved vector graphics.
This can slow down figure rendering. Default is :rc:`cmap.edgefix`.
If ``True``, a default linewidth is used. If float, this linewidth is used.
"""
_snippet_manager['plot.contour'] = _contour_docstring.format(
descrip='contour lines', command='contour', add=''
)
_snippet_manager['plot.contourf'] = _contour_docstring.format(
descrip='filled contours', command='contourf', add=_edgefix_docstring
)
_snippet_manager['plot.tricontour'] = _contour_docstring.format(
descrip='contour lines on a triangular grid', command='tricontour', add=''
)
_snippet_manager['plot.tricontourf'] = _contour_docstring.format(
descrip='filled contours on a triangular grid', command='tricontourf', add=_edgefix_docstring # noqa: E501
)
# Pcolor docstring
_pcolor_docstring = """
Plot {descrip}.
Parameters
----------
%(plot.args_2d)s
%(plot.args_2d_shared)s
{add}
Other parameters
----------------
%(plot.cmap_norm)s
%(plot.levels_manual)s
%(plot.levels_vlim)s
%(plot.levels_auto)s
%(plot.labels_2d)s
%(plot.guide)s
lw, linewidth, linewidths : optional