Merge pull request #167 from lukelbd/geogrid-features

Refactor rc_configurator and geoaxes, add new gridline features

Author: lukelbd

.gitignore

@@ -5,6 +5,7 @@
 
 # Ignore auto-generated files
 proplotrc
+rctable.rst
 
 # PyPi stuff
 build

CHANGELOG.rst

@@ -71,6 +71,11 @@ ProPlot v0.6.0 (2020-##-##)
 
 There are quite a lot of deprecations for this release.
 
+- Remove the ``geoaxes`` and ``geogrid`` rc settings (:pr:`168`). Gridline
+  settings are now controlled with ``grid``.
+- Remove the ``lonstep`` and ``latstep`` settings -- we now use
+  `~proplot.ticker.LongitudeLocator` and `~proplot.ticker.LatitudeLocator`
+  to select "nice" gridline locations even when zoomed in (:pr:`168`)
 - Rename `add_errorbars` to `~proplot.axes.plot.indicate_error` and rename
   various keyword args (:pr:`166`, :commit:`d8c50a8d`).
 - Remove ``'rgbcycle'`` setting (:commit:`6653b7f0`).
@@ -118,6 +123,24 @@ There are quite a lot of deprecations for this release.
 
 .. rubric:: Features
 
+- Use `_LonAxis` and `_LatAxis` dummy axes with custom `LongitudeLocator`
+  and `LatitudeLocator` to control geographic gridlines (:pr:`168`).
+- Add ``'dmslat'`` and ``'dmslon'`` as formatters for cartopy projections,
+  along with ``dms`` `format` keyword argument. This labels points with
+  degrees/minutes/seconds when appropriate (:pr:`168`).
+- Support "minor" geographic gridlines with the ``gridminor`` keyword
+  arg and existing ``gridminor`` settings (:pr:`168`). Default locator
+  used for minor gridlines is `~matplotlib.ticker.AutoMinorLocator`.
+- Add `loninline`, `latinline`, and `rotatelabels` keywords for controlling
+  cartopy gridliner behavior (:pr:`168`).
+- Add `proplot.config.rc_configurator.save` and
+  `proplot.config.rc_configurator.from_file` methods (:commit:`e6dd8314`).
+- Increase default :rcraw:`savefig.dpi` to 1200, matching recommendations
+  from academic journals (:commit:`c00e7314`). Also add detailed discussion
+  to user guide.
+- No longer distinguish between "quick" settings and proplot's "added"
+  settings (:commit:`e6dd8314`). Quick settings, added settings, and matplotlib
+  settings can all have "children" so the distinction no longer makes sense.
 - Add options to `~proplot.axes.plot.indicate_error` for adding *shading*
   to arbitrary plots (:pr:`166`, :commit:`d8c50a8d`). Also support automatic legend
   entries for shading and ensure `indicate_error` preserves metadata.
@@ -181,6 +204,8 @@ There are quite a lot of deprecations for this release.
 
 - Fix various issues with axis label sharing and axis sharing for
   twinned axes and panel axes (:pr:`164`).
+- Permit modifying existing cartopy geographic features with successive
+  calls to `~proplot.axes.GeoAxes.format` (:commit:`###`).
 - Fix issue drawing bar plots with datetime *x* axes (:pr:`156`).
 - Fix issue where `~proplot.ticker.AutoFormatter` tools were not locale-aware, i.e. use
   comma as decimal point sometimes (:commit:`c7636296`).

INSTALL.rst

@@ -16,7 +16,6 @@ Likewise, an existing installation of ProPlot can be upgraded to the latest vers
    conda upgrade proplot
 
 
-If you used ``pip install git+https://github.com/lukelbd/proplot.git`` to install ProPlot before it was released on PyPi, you may need to run ``pip uninstall proplot`` before upgrading.
-To install a development version of ProPlot, you can use this same method, or clone the repository and run ``pip install --upgrade .`` inside the ``proplot`` folder.
+To install a development version of ProPlot, you can use ``pip install git+https://github.com/lukelbd/proplot.git`` or clone the repository and run ``pip install -e .`` inside the ``proplot`` folder.
 
 ProPlot's only hard dependency is `matplotlib <https://matplotlib.org/>`__. The *soft* dependencies are `cartopy <https://scitools.org.uk/cartopy/docs/latest/>`__, `basemap <https://matplotlib.org/basemap/index.html>`__, `xarray <http://xarray.pydata.org>`__, and `pandas <https://pandas.pydata.org>`__. See the documentation for details.

README.rst

@@ -22,8 +22,7 @@ Likewise, an existing installation of ProPlot can be upgraded to the latest vers
    pip install --upgrade proplot
    conda upgrade proplot
 
-If you used ``pip install git+https://github.com/lukelbd/proplot.git`` to install ProPlot before it was released on PyPi, you may need to run ``pip uninstall proplot`` before upgrading.
-To install a development version of ProPlot, you can use this same method, or clone the repository and run ``pip install --upgrade .`` inside the ``proplot`` folder.
+To install a development version of ProPlot, you can use ``pip install git+https://github.com/lukelbd/proplot.git`` or clone the repository and run ``pip install -e .`` inside the ``proplot`` folder.
 
 Documentation
 =============

docs/axis.py

@@ -58,8 +58,7 @@
 state = np.random.RandomState(51423)
 plot.rc.facecolor = plot.scale_luminance('powder blue', 1.15)
 plot.rc.update(
-    linewidth=1,
-    small=10, large=12,
+    linewidth=1, fontsize=10,
     color='dark blue', suptitlecolor='dark blue',
     titleloc='upper center', titlecolor='dark blue', titleborder=False,
 )
@@ -134,7 +133,7 @@
 import proplot as plot
 import numpy as np
 plot.rc.update(
-    linewidth=1.2, small=10, large=12, facecolor='gray8', figurefacecolor='gray8',
+    linewidth=1.2, fontsize=10, facecolor='gray8', figurefacecolor='gray8',
     suptitlecolor='w', gridcolor='w', color='w',
     titleloc='upper center', titlecolor='w', titleborder=False,
 )
@@ -177,7 +176,7 @@
 # %%
 import proplot as plot
 plot.rc.linewidth = 2
-plot.rc.small = plot.rc.large = 11
+plot.rc.fontsize = 11
 locator = [0, 0.25, 0.5, 0.75, 1]
 fig, axs = plot.subplots([[1, 1, 2, 2], [0, 3, 3, 0]], axwidth=1.5, share=0)
 
@@ -221,7 +220,7 @@
 import proplot as plot
 import numpy as np
 plot.rc.update(
-    linewidth=1.2, small=10, large=12, ticklenratio=0.7,
+    linewidth=1.2, fontsize=10, ticklenratio=0.7,
     figurefacecolor='w', facecolor='pastel blue',
     titleloc='upper center', titleborder=False,
 )

docs/basics.py

@@ -22,8 +22,8 @@
 # %% [raw] raw_mimetype="text/restructuredtext"
 # .. _ug_intro:
 #
-# Figures and subplots
-# --------------------
+# Creating figures
+# ----------------
 #
 # ProPlot works by subclassing the matplotlib `~matplotlib.figure.Figure` and
 # `~matplotlib.axes.Axes` classes. You can generate grids of proplot
@@ -47,12 +47,21 @@
 # and modify the axes using `~proplot.axes.Axes.format` and
 # `~proplot.ui.SubplotsContainer`. See the :ref:`formatting guide <ug_format>`
 # and :ref:`subplots container <ug_container>` sections for details.
+#
 # Please note that by default, ProPlot sets :rcraw:`figure.facecolor` to gray,
 # :rcraw:`savefig.facecolor` to white, and :rcraw:`savefig.transparent` to ``True``.
 # That is, the default display background is gray, the default background for
 # saved figures is transparent, and the default background is white when you pass
-# ``transparent=False`` to `~matplotlib.figure.Figure.savefig`. See the
-# :ref:`configuration section <ug_proplotrc>` for how to change this.
+# ``transparent=False`` to `~matplotlib.figure.Figure.savefig`.
+# ProPlot also sets the default :rcraw:`savefig.format` to PDF, because
+# (1) vector graphic formats are always more suitable for matplotlib figures than
+# raster formats, (2) most academic journals these days accept PDF format figures
+# alongside the older EPS format, (3) PDF figures are easy to embed in LaTeX documents,
+# and (4) the EPS format does not support transparent graphic elements. If you *do*
+# need raster graphics, ProPlot sets the default :rcraw:`savefig.dpi` to 1200 dots per
+# inch, which is recommended by most journals as the minimum resolution for rasterized
+# figures containing lines and text. See the :ref:`configuration section <ug_proplotrc>`
+# for how to change these settings.
 
 # %%
 import proplot as plot
@@ -218,11 +227,10 @@
 # ProPlot. `~proplot.config.rc` is similar to the matplotlib
 # `~matplotlib.rcParams` dictionary, but can be used to change (1)
 # matplotlib's `builtin settings
-# <https://matplotlib.org/tutorials/introductory/customizing.html>`_, (2)
-# ProPlot's :ref:`added settings <rc_added>`, and (3) :ref:`quick settings
-# <rc_quick>` that can be used to change lots of matplotlib and ProPlot
-# settings at once. `~proplot.config.rc` also provides a ``style`` parameter
-# that can be used to switch between `matplotlib stylesheets\
+# <https://matplotlib.org/tutorials/introductory/customizing.html>`_ and
+# (2) ProPlot's :ref:`added settings <rc_proplot>`. `~proplot.config.rc` also
+# provides a ``style`` parameter that can be used to switch between
+# `matplotlib stylesheets\
 # <https://matplotlib.org/3.1.1/gallery/style_sheets/style_sheets_reference.html>`__.
 # See the :ref:`configuration section <ug_config>` for details.
 #
@@ -245,6 +253,7 @@
 plot.rc.update({'fontname': 'Noto Sans'})
 plot.rc['figure.facecolor'] = 'gray3'
 plot.rc.axesfacecolor = 'gray4'
+# plot.rc.save()  # save the current settings to ~/.proplotrc
 
 # Apply settings to figure with context()
 with plot.rc.context({'suptitle.size': 11}, toplabelcolor='gray6', linewidth=1.5):

docs/colormaps.py

@@ -178,7 +178,7 @@
 
 # Monochromatic colormaps
 axs.format(
-    xlabel='x axis', ylabel='y axis', span=False,
+    xlabel='x axis', ylabel='y axis',
     suptitle='Building your own PerceptuallyUniformColormaps'
 )
 data = state.rand(30, 30).cumsum(axis=1)

docs/conf.py

@@ -216,8 +216,9 @@
         f.write(HtmlFormatter(style=style).get_style_defs('.highlight'))
 
 # Create sample .proplotrc file
-from proplot.config import _write_defaults  # noqa: E402
-_write_defaults(os.path.join('_static', 'proplotrc'), comment=False)
+from proplot.config import rc
+rc._save_proplotrc(os.path.join('_static', 'proplotrc'))
+rc._save_rst(os.path.join('_static', 'rctable.rst'))
 
 # Role
 # default family is py, but can also set default role so don't need