add description about plot types

Author: Chilipp

docs/user-guide.rst

@@ -8,13 +8,13 @@ User guide
 Starting the GUI
 ----------------
 
-Assuming that you :ref:`installed <install>` psy-view, you can start it by 
+Assuming that you :ref:`installed <install>` psy-view, you can start it by
 typing::
 
     $ psy-view
 
-in the terminal (or Anaconda Prompt on Windows). On windows you additionally 
-have the opportunity to start it from the start menu (just search for 
+in the terminal (or Anaconda Prompt on Windows). On windows you additionally
+have the opportunity to start it from the start menu (just search for
 psy-view), assuming that you have :ref:`installed it via conda <install-conda>`.
 
 You can also directly pass a path to a netCDF file, e.g.::
@@ -49,8 +49,8 @@ in the terminal.
 The GUI
 -------
 
-The usage of psy-view should be quite intuitive and this small guide gives you 
-a quick intro into the central elements. Please let us know if you 
+The usage of psy-view should be quite intuitive and this small guide gives you
+a quick intro into the central elements. Please let us know if you
 encounter any problems.
 
 .. screenshot-figure:: ds_widget docs-ds_widget.png
@@ -63,8 +63,8 @@ application, or within the psyplot gui (see :ref:`psyplot-gui-embed`).
 
 Resizing the GUI elements
 ^^^^^^^^^^^^^^^^^^^^^^^^^
-The widget is made flexible such that you can adapt the heights of the 
-individual elements. Just move your cursor between the elements to change their 
+The widget is made flexible such that you can adapt the heights of the
+individual elements. Just move your cursor between the elements to change their
 size.
 
 .. only:: html
@@ -82,9 +82,9 @@ Open a netCDF file
 
 .. screenshot:: ds_widget.open_widget docs-open_widget.png
 
-Click the |btn_open| button to select a netCDF file from the disk, or directly 
-enter the path in the line widget. You can open multiple datasets at the 
-same time within the widget. The selection of the current dataset can be 
+Click the |btn_open| button to select a netCDF file from the disk, or directly
+enter the path in the line widget. You can open multiple datasets at the
+same time within the widget. The selection of the current dataset can be
 done through the dataset tree (see below)
 
 
@@ -99,8 +99,8 @@ View the dataset
 
 .. screenshot:: ds_widget.ds_tree docs-ds_tree.png
 
-Here you can see all open datasets and select the one you want  to 
-visualize. Expand the items to get more information about variables and 
+Here you can see all open datasets and select the one you want  to
+visualize. Expand the items to get more information about variables and
 their attributes.
 
 .. _user-guide-navigation:
@@ -111,13 +111,13 @@ Navigate and export
 .. screenshot:: ds_widget.navigation_box.parentWidget() docs-navigation.png
     :plot:
 
-In the top row, you can increase or decrease the dimension of the plotted variable. 
+In the top row, you can increase or decrease the dimension of the plotted variable.
 Clicking |btn_prev| (or |btn_next|) decreases (or increases) the selected
 dimension, whereas |btn_animate_backward| and |btn_animate_forward| makes an
-animation. You can control the speed (i.e. frames per second) of the 
+animation. You can control the speed (i.e. frames per second) of the
 animation via the slider next to the control |sl_interval| |lbl_interval|
 
-The |btn_export| menu allows you to export your plots as images files, 
+The |btn_export| menu allows you to export your plots as images files,
 animations or to export the plot settings for later usage. The |btn_preset|
 button lets you select custom presets for your plots (see the
 :ref:`psyplot docs <psyplot:presets>`).
@@ -163,14 +163,14 @@ Select the active plot
 .. screenshot:: ds_widget.array_frame docs-array_frame.png
     :plot:
 
-The next section let's you switch between the different open plots. Once you 
-have created a new plot with one of the variable buttons (see 
-:ref:`below <user-guide-variables>`), you can 
+The next section let's you switch between the different open plots. Once you
+have created a new plot with one of the variable buttons (see
+:ref:`below <user-guide-variables>`), you can
 
-- create additional plots by clicking the |btn_add| button. This will open a 
+- create additional plots by clicking the |btn_add| button. This will open a
   dialog to select a variable which is then plotted with the current plotmethod
 - close existing plots by clicking the |btn_del| button.
-- switch between the plots using the combo box |combo_array| which allows you 
+- switch between the plots using the combo box |combo_array| which allows you
   to change the appearence of a different plot.
 
 .. |btn_add| screenshot:: ds_widget.btn_add docs-btn_add.png
@@ -197,10 +197,11 @@ Select the plot method
 psy-view (currently) supports three of the psyplot plot methods.
 
 - :attr:`~psy_simple:psyplot.project.plot.plot2d` for 2D scalar fields
-  (rectilinear or unstructured)
-- :attr:`~psy_maps:psyplot.project.plot.mapplot` for **georeferenced** 2D scalar 
-  fields (rectilinear or unstructured)
-- :attr:`~psy_simple:psyplot.project.plot.lineplot` for 1D lines
+  (rectilinear or unstructured, see the section :ref:`user-guide-plot2d`)
+- :attr:`~psy_maps:psyplot.project.plot.mapplot` for **georeferenced** 2D scalar
+  fields (rectilinear or unstructured, see the section :ref:`user-guide-mapplot`)
+- :attr:`~psy_simple:psyplot.project.plot.lineplot` for 1D lines (see the
+  section , see the section :ref:`user-guide-lineplot`)
 
 .. _user-guide-mapplot:
 
@@ -212,7 +213,7 @@ mapplot
 
     In [1]: import psyplot.project as psy
        ...: with psy.plot.mapplot(
-       ...:         "demo.nc", name="t2m", 
+       ...:         "demo.nc", name="t2m",
        ...:         cmap="viridis", xgrid=False, ygrid=False,
        ...:     ) as sp:
        ...:     sp.export("docs-mapplot-example.png")
@@ -227,14 +228,43 @@ mapplot
 For georeferenced 2D-scalar fields (or more than 2D), you have the following
 options:
 
-- clicking on a grid cell in the plot generates a line plot of the variable at 
-  that location (as you know it from ncview). The x-axis is determined by the 
+- clicking on a grid cell in the plot generates a line plot of the variable at
+  that location (as you know it from ncview). The x-axis is determined by the
   dimension you chose in the navigation (see :ref:`user-guide-navigation`).
 - the colormap button |btn_cmap| changes the colormap to another preset
 - the |btn_cmap_settings| button opens a dialog for more advanced color settings
 - the |btn_proj| button switches to other projections for the basemap
-- the |btn_proj_settings| button opens a dialog for formatting the background 
+- the |btn_proj_settings| button opens a dialog for formatting the background
   (meridionals, parallels, land color, ocean color, coastlines, etc.)
+- the :guilabel:`Plot type` menu |combo_plot| let's you select the type of
+  plotting. You can choose one of the following options
+
+  Default
+      This mode uses an efficient algorithm for regular lat-lon meshes (using
+      matplotlibs :func:`~matplotlib.pyplot.pcolormesh` function), or an
+      explicit drawing of the individual grid cell polygons for unstructured
+      grids (see `Gridcell polygons` below). These two methods draw each grid
+      cells explicitly. Gridcell boundaries are thereby extracted following the
+      CF (or UGRID)-Conventions. If this is not possible, they are interpolated
+      from the gridcell coordinates.
+  Filled contours
+      Different from the `Default` method this is not visualizing each cell
+      individually, but instead plots the contours using matplotlibs
+      :func:`~matplotlib.pyplot.contourf` function.
+  Contours
+      Similar to `Filled contours`, but we only draw the outlines of the contour
+      areas using matplotlibs :func:`~matplotlib.pyplot.contour` function.
+  Gridcell polygons
+      This mode (which is the default for unstructured grids (not curvilinear
+      grids) draws each grid cell individually using a variant of matplotlibs
+      :func:`~matplotlib.pyplot.pcolor` function
+  Disable
+      Make no plotting at all. This can be useful if you want to display the
+      datagrid only (see next point)
+
+  More information on the plot options can be found in the docs of the
+  :attr:`~psy_maps.plotters.FieldPlotter.plot` formatoption.
+
 - the |btn_datagrid| toggles the visibility of grid cell boundaries
 - the |btn_labels| button opens a dialog to edit colorbar labels, titles, etc.
 
@@ -243,13 +273,13 @@ Furthermore you have a couple of dropdowns:
 x- and y-dimension
     This is the dimension in the netCDF variable that represents the longitudinal
     (latitudinal) dimension.
-x- and y-coordinate 
+x- and y-coordinate
     This is the coordinate in the netCDF file that is used for the finally to
     visualize the data (equivalent to the `CF-conventions coordinates attribute`_
     of a netCDF variable.)
 
 psyplot automatically decodes the variable and sets x- and y-dimension, as well
-as the appropriate coordinate. These dropdowns, however, let you modify the 
+as the appropriate coordinate. These dropdowns, however, let you modify the
 automatic choice of psyplot.
 
 .. _CF-conventions coordinates attribute: http://cfconventions.org/Data/cf-conventions/cf-conventions-1.8/cf-conventions.html#coordinate-types
@@ -270,6 +300,10 @@ automatic choice of psyplot.
     :width: 1.3em
     :plot:
 
+.. |combo_plot| screenshot:: ds_widget.plotmethod_widget.combo_plot docs-mapplot-combo_plot.png
+    :height: 1.3em
+    :plot:
+
 .. |btn_datagrid| screenshot:: ds_widget.plotmethod_widget.btn_datagrid docs-mapplot-btn_datagrid.png
     :height: 1.3em
     :plot:
@@ -289,7 +323,7 @@ plot2d
 
     In [1]: import psyplot.project as psy
        ...: with psy.plot.plot2d(
-       ...:         "demo.nc", name="t2m", 
+       ...:         "demo.nc", name="t2m",
        ...:         cmap="viridis",
        ...:     ) as sp:
        ...:     sp.export("docs-plot2d-example.png")
@@ -300,7 +334,7 @@ plot2d
     :plot:
     :plotmethod: plot2d
 
-Simple 2D plots are also possible for variables with 2 dimensions and more (or 
+Simple 2D plots are also possible for variables with 2 dimensions and more (or
 scalar fields on an unstructured grid). The options are the same as for
 :ref:`mapplot <user-guide-mapplot>`, but for obvious reasons there are no
 projection and basemap settings.
@@ -343,7 +377,7 @@ following functionalities:
 
 .. note::
 
-    Changing the variable (see :ref:`user-guide-variables`) or the 
+    Changing the variable (see :ref:`user-guide-variables`) or the
     dimensions (see :ref:`user-guide-dimensions`) only affects the current
     line that you can select with the |combo_lines| dropdown.
 
@@ -377,18 +411,18 @@ Select the variables
 
 .. screenshot:: ds_widget.variable_frame docs-variable_frame.png
 
-The next section in the GUI shows the variables in the active dataset (note that 
-you can switch to another dataset using the dataset tree, see 
+The next section in the GUI shows the variables in the active dataset (note that
+you can switch to another dataset using the dataset tree, see
 :ref:`above <user-guide-ds_tree>`).
 
-Click on a variable to make a plot. If there is already a plot of a variable in 
+Click on a variable to make a plot. If there is already a plot of a variable in
 the dataset, it will be updated to show the new data.
 
-.. note:: 
+.. note::
 
-    The variable buttons will make new plots, if there is None already, or 
+    The variable buttons will make new plots, if there is None already, or
     update the variable in the current plot. If you want to visualize two plots
-    at the same time, use the |btn_add| button (see the 
+    at the same time, use the |btn_add| button (see the
     :ref:`plot selection above <user-guide-select-plot>`).
 
 
@@ -421,21 +455,21 @@ right-click decreases the dimension.
 Navigation inside the plot
 --------------------------
 
-psy-view uses matplotlib for the visualization which comes with an interactive 
-backend to navigate inside the plot. 
+psy-view uses matplotlib for the visualization which comes with an interactive
+backend to navigate inside the plot.
 
 .. screenshot:: ds_widget.plotter.ax.figure.canvas.manager.toolbar docs-mpl-toolbar.png
     :plot:
 
-Especially the Pan/Zoom button |btn_mpl_pan| and the zoom-to-rectangle button 
-|btn_mpl_zoom| are of interest for you. You can enable and disable them by 
+Especially the Pan/Zoom button |btn_mpl_pan| and the zoom-to-rectangle button
+|btn_mpl_zoom| are of interest for you. You can enable and disable them by
 clicking on the corresponding button in the toolbar.
 
 .. warning::
 
     In principal you can also edit the colormap using the |btn_mpl_settings|
-    button from the toolbar. But this is known to cause errors for the mapplot 
-    method (see `#25`_), so you should use the corresponding widgets from the gui (see 
+    button from the toolbar. But this is known to cause errors for the mapplot
+    method (see `#25`_), so you should use the corresponding widgets from the gui (see
     :ref:`user-guide-mapplot`).
 
 .. screenshot:: ds_widget.plotter.ax.figure.canvas.manager.toolbar.actions()[4].associatedWidgets()[1] docs-btn_mpl_pan.png
@@ -495,12 +529,12 @@ More information can be found in the `matplotlib documentation`_.
 
 Using psy-view within the psyplot GUI
 -------------------------------------
-psy-view is also available from the psyplot GUI. Just type ``psyplot`` in the 
+psy-view is also available from the psyplot GUI. Just type ``psyplot`` in the
 terminal to start it. The only difference is that the available plots (see
 :ref:`user-guide-select-plot`) are managed through the current main project
-(:func:`psyplot.project.gcp`, see also the psyplot GUIs 
+(:func:`psyplot.project.gcp`, see also the psyplot GUIs
 :ref:`project content <psyplot_gui:project-content>`), also accessible through
-the ``mp`` variable in the 
+the ``mp`` variable in the
 :ref:`integrated IPython console <psyplot_gui:console>`. This gives you extra
 power as you now cannot only change your plots through the intuitive psy-view
 interface, but also from the command line or through the more flexible