|
26 | 26 | # Geographic and polar plots |
27 | 27 | # ========================== |
28 | 28 | # |
29 | | -# ProPlot includes several advanced features for working with |
30 | | -# `polar <polar_>`_ and :ref:`geographic projections <ug_geo>`. |
| 29 | +# ProPlot includes several advanced features for working with `polar`_ |
| 30 | +# and :ref:`geographic projections <ug_geo>`. |
31 | 31 | # |
32 | 32 | # To change the axes projection, pass ``proj='name'`` to an axes-creation command |
33 | 33 | # (i.e., `~proplot.figure.Figure.add_subplot`, `~proplot.figure.Figure.add_subplots`, |
|
37 | 37 | # or a dictionary of projection names with the subplot number as the key. For example, |
38 | 38 | # a 2-column figure with a Cartesian axes on the left and a Plate Carrée projection |
39 | 39 | # on the right can be built with either ``proj=('cartesian', 'pcarree')`` or |
40 | | -# ``proj={2: 'pcarree'}``. The default "projection" is `~proplot.axes.CartesianAxes` |
41 | | -# and can be explicitly specified with the ``'cartesian'`` key. |
| 40 | +# ``proj={2: 'pcarree'}``. The default projection is `~proplot.axes.CartesianAxes`, |
| 41 | +# specified with the key ``'cartesian'``. |
42 | 42 |
|
43 | 43 | # %% [raw] raw_mimetype="text/restructuredtext" |
44 | 44 | # .. _ug_geo: |
45 | 45 | # |
46 | 46 | # Geographic axes |
47 | 47 | # --------------- |
48 | 48 | # |
49 | | -# Geographic plots can be created in ProPlot using either `cartopy`_ or `basemap`_ |
50 | | -# as "backends". Note that this feature is *optional* -- installation of cartopy |
51 | | -# or basemap is not required. To create geographic axes, pass |
52 | | -# e.g. ``proj='name'`` to an axes-creation command (see :ref:`above <ug_proj>`) |
53 | | -# where ``name`` is any valid :ref:`PROJ projection name <proj_included>`. |
54 | | -# Alternatively, you can use ``proj=projection_instance`` where ``projection_instance`` |
55 | | -# is a `cartopy.crs.Projection` or `mpl_toolkits.basemap.Basemap` generated with |
| 49 | +# To create geographic axes, pass e.g. ``proj='name'`` to an axes-creation |
| 50 | +# command (see :ref:`above <ug_proj>`) where ``name`` is any valid |
| 51 | +# :ref:`PROJ projection name <proj_included>`. Alternatively, you can use |
| 52 | +# ``proj=projection_instance`` where ``projection_instance`` is a |
| 53 | +# `cartopy.crs.Projection` or `mpl_toolkits.basemap.Basemap` generated with |
56 | 54 | # the `~proplot.constructor.Proj` :ref:`constructor function <why_constructor>`. |
| 55 | +# A very simple geographic plot is shown below. |
| 56 | + |
| 57 | +# %% |
| 58 | +# Option A: Create a projection with pplt.Proj() |
| 59 | +# import proplot as plot |
| 60 | +# proj = pplt.Proj('robin', lon_0=180) |
| 61 | +# fig, axs = pplt.subplots(nrows=2, refwidth=3, proj=proj) |
| 62 | + |
| 63 | +# Option B: Create an on-the-fly projection |
| 64 | +import proplot as pplt |
| 65 | +fig = pplt.figure(refwidth=3) |
| 66 | +axs = fig.subplots(nrows=2, proj='robin', proj_kw={'lon_0': 180}) |
| 67 | +axs.format( |
| 68 | + suptitle='Figure with single projection', |
| 69 | + coast=True, latlines=30, lonlines=60, |
| 70 | +) |
| 71 | + |
| 72 | +# %% [raw] raw_mimetype="text/restructuredtext" |
| 73 | +# .. _ug_backends: |
| 74 | +# |
| 75 | +# Cartopy and basemap |
| 76 | +# ------------------- |
57 | 77 | # |
| 78 | +# Geographic axes in ProPlot use either `cartopy`_ or `basemap`_ as "backends". |
58 | 79 | # When you request a geographic projection, the axes-creation command returns |
59 | | -# a `proplot.axes.GeoAxes` instance(s). This `~proplot.axes.Axes` subclass has its |
60 | | -# own `~proplot.axes.GeoAxes.format` command that :ref:`manages geographic features |
| 80 | +# a `proplot.axes.GeoAxes` instance(s) that uses either cartopy or basemap |
| 81 | +# under the hood. The `proplot.axes.GeoAxes` subclass has its own |
| 82 | +# `~proplot.axes.GeoAxes.format` command that :ref:`manages geographic features |
61 | 83 | # <ug_geoformat>` like meridional and parallel gridlines and land mass outlines |
62 | 84 | # with the same syntax for either backend. A few details: |
63 | 85 | # |
|
89 | 111 | # available via the `~proplot.axes.GeoAxes.projection` attribute. |
90 | 112 | # |
91 | 113 | # Together, these features let you work with geophysical data without invoking |
92 | | -# verbose cartopy classes like `~cartopy.crs.LambertAzimuthalEqualArea` and |
93 | | -# `~cartopy.feature.NaturalEarthFeature` or keeping track of separate |
94 | | -# `~mpl_toolkits.basemap.Basemap` instances. They considerably reduce the amount of |
95 | | -# code needed to make geographic plots. In the below examples, we create a variety |
96 | | -# of geographic plots using both cartopy and basemap as backends. |
| 114 | +# verbose cartopy classes like `~cartopy.crs.LambertAzimuthalEqualArea` |
| 115 | +# or keeping track of separate `~mpl_toolkits.basemap.Basemap` instances. They |
| 116 | +# considerably reduce the amount of code needed to make geographic plots. |
| 117 | +# In the below examples, we create a variety of geographic plots using both |
| 118 | +# cartopy and basemap as backends. |
97 | 119 | # |
98 | 120 | # .. note:: |
99 | 121 | # |
|
115 | 137 | # of `central_longitude`) and instantiates `~mpl_toolkits.basemap.Basemap` |
116 | 138 | # projections with sensible default PROJ parameters rather than raising an error |
117 | 139 | # when they are omitted (e.g., ``lon_0=0`` as the default for most projections). |
118 | | -# |
119 | | -# .. warning:: |
120 | | -# |
121 | | -# Basemap is `no longer maintained \ |
122 | | -# <https://matplotlib.org/basemap/users/intro.html#cartopy-new-management-and-eol-announcement>`__ |
123 | | -# and will not work with matplotlib versions more recent than 3.2.2. However, |
124 | | -# as shown below, gridline labels often look nicer in basemap than cartopy -- |
125 | | -# especially when "inline" cartopy labels are disabled. This is the main reason |
126 | | -# ProPlot continues to support basemap. When cartopy gridline labels improve, |
127 | | -# basemap support may be deprecated. |
128 | | - |
129 | | -# %% |
130 | | -# Option A: Create a projection with pplt.Proj() |
131 | | -# import proplot as plot |
132 | | -# proj = pplt.Proj('robin', lon_0=180) |
133 | | -# fig, axs = pplt.subplots(nrows=2, refwidth=3, proj=proj) |
134 | | - |
135 | | -# Option B: Create an on-the-fly projection |
136 | | -import proplot as pplt |
137 | | -fig = pplt.figure(refwidth=3) |
138 | | -axs = fig.subplots(nrows=2, proj='robin', proj_kw={'lon_0': 180}) |
139 | | -axs.format( |
140 | | - suptitle='Figure with single projection', |
141 | | - coast=True, latlines=30, lonlines=60, |
142 | | -) |
| 140 | +# * Basemap is `no longer maintained \ |
| 141 | +# <https://matplotlib.org/basemap/users/intro.html#cartopy-new-management-and-eol-announcement>`__ |
| 142 | +# and will not work with matplotlib versions more recent than 3.2.2. However, |
| 143 | +# basemap gridline labels often look nicer than cartopy -- especially when |
| 144 | +# "inline" cartopy labels are disabled. This is the main reason ProPlot continues |
| 145 | +# to support basemap. When cartopy gridline labels improve, basemap support |
| 146 | +# may be deprecated. |
143 | 147 |
|
144 | 148 | # %% |
145 | 149 | import proplot as pplt |
|
0 commit comments