Merge branch 'master' into gmt-library

AUTHORS.md

@@ -8,6 +8,7 @@ Manoa.
 The following people have contributed code to the project (alphabetical by last name)
 and are considered the "PyGMT Developers":
 
+* [Michael Grund](https://github.com/michaelgrund)
 * [Wei Ji Leong](https://github.com/weiji14)
 * [Tyler Newton](http://www.tnewton.com/)
 * [William Schlitzer](https://github.com/willschlitzer)

examples/gallery/line/line-custom-cpt.py

@@ -0,0 +1,32 @@
+"""
+Line colors with a custom CPT
+-----------------------------
+
+The color of the lines made by :meth:`pygmt.Figure.plot` can be set according to a
+custom CPT and assigned with the ``pen`` argument.
+
+The custom CPT can be used by setting the plot command's ``cmap`` argument to ``True``. The
+``zvalue`` argument sets the z-value (color) to be used from the custom CPT, and the line
+color is set as the z-value by using **+z** when setting the ``pen`` color.
+
+"""
+
+import numpy as np
+import pygmt
+
+# Create a list of values between 20 and 30 with at 0.2 intervals
+x = np.arange(start=20, stop=30, step=0.2)
+
+fig = pygmt.Figure()
+fig.basemap(frame=["WSne", "af"], region=[20, 30, -10, 10])
+
+# Create a custom CPT with the batlow CPT and 10 discrete z-values (colors)
+pygmt.makecpt(cmap="batlow", series=[0, 10, 1])
+
+# Plot 10 lines and set a different z-value for each line
+for zvalue in range(0, 10):
+    y = zvalue * np.sin(x)
+    fig.plot(x=x, y=y, cmap=True, zvalue=zvalue, pen="thick,+z,-")
+# Color bar to show the custom CPT and the associated z-values
+fig.colorbar()
+fig.show()

examples/gallery/plot/image.py

@@ -0,0 +1,29 @@
+"""
+Images or EPS files on maps
+---------------------------
+The :meth:`pygmt.Figure.image` method can be used to read and 
+place a raster image file or an Encapsulated PostScript file
+on a map. We must specify the file as *str* via the ``imagefile`` 
+argument or simply use the filename as first argument. You can 
+also use a full URL pointing to your desired image. The ``position`` 
+argument allows us to set a reference point on the map for the image.
+
+For more advanced style options, see the full option list 
+at :gmt-docs:`image.html`.
+"""
+
+import pygmt
+
+fig = pygmt.Figure()
+
+fig.basemap(region=[0, 2, 0, 2], projection="X6c", frame=True)
+
+# place and center the GMT logo from the GMT website to the position 1/1
+# on a basemap and draw a rectangular border around the image
+fig.image(
+    imagefile="https://www.generic-mapping-tools.org/_static/gmt-logo.png",
+    position="g1/1+w3c+jCM",
+    box=True,
+)
+
+fig.show()

examples/gallery/plot/multi-parameter-symbols.py

@@ -0,0 +1,63 @@
+"""
+Multi-parameter symbols
+-------------------------
+
+The :meth:`pygmt.Figure.plot` method can plot individual multi-parameter symbols by passing 
+the corresponding shortcuts listed below to the ``style`` argument. Additionally, we must define 
+the required parameters in a 2d list or numpy array (``[[parameters]]`` for a single symbol 
+or ``[[parameters_1],[parameters_2],[parameters_i]]`` for several ones) or use an 
+appropriately formatted input file and pass it to ``data``. 
+
+The following symbols are available:
+
+- **e**: ellipse, ``[[lon, lat, direction, major_axis, minor_axis]]``
+- **j**: rotated rectangle, ``[[lon, lat, direction, width, height]]``
+- **r**: rectangle, ``[[lon, lat, width, height]]``
+- **R**: rounded rectangle, ``[[lon, lat, width, height, radius]]``
+- **w**: pie wedge, ``[[lon, lat, radius, startdir, stopdir]]``, the last two arguments are 
+  directions given in degrees counter-clockwise from horizontal 
+
+Upper-case versions **E**, **J**, and **W** are similar to **e**, **j** and **w** but expect geographic 
+azimuths and distances.
+
+For more advanced options, see the full option list at :gmt-docs:`plot.html`.
+"""
+
+import numpy as np
+import pygmt
+
+fig = pygmt.Figure()
+
+fig.basemap(region=[0, 6, 0, 2], projection="x3c", frame=True)
+
+###################
+# ELLIPSE
+data = np.array([[0.5, 1, 45, 3, 1]])
+
+fig.plot(data=data, style="e", color="orange", pen="2p,black")
+
+###################
+# ROTATED RECTANGLE
+data = np.array([[1.5, 1, 120, 5, 0.5]])
+
+fig.plot(data=data, style="j", color="red3", pen="2p,black")
+
+###################
+# RECTANGLE
+data = np.array([[3, 1, 4, 1.5]])
+
+fig.plot(data=data, style="r", color="dodgerblue", pen="2p,black")
+
+###################
+# ROUNDED RECTANGLE
+data = np.array([[4.5, 1, 1.25, 4, 0.5]])
+
+fig.plot(data=data, style="R", color="seagreen", pen="2p,black")
+
+###################
+# PIE WEDGE
+data = np.array([[5.5, 1, 2.5, 45, 330]])
+
+fig.plot(data=data, style="w", color="lightgray", pen="2p,black")
+
+fig.show()

examples/projections/README.txt

@@ -4,7 +4,7 @@ Projections
 PyGMT support many map projections. Use the ``projection`` argument to specify which one
 you want to use in all plotting modules. The projection is specified by a one letter
 code along with (sometimes optional) reference longitude and latitude and the width of
-the map (for example, ``Alon0/lat0[/horizon]/width``). The map height is determined
-based on the region and projection.
+the map (for example, **A**\ *lon0/lat0*\ [*/horizon*\ ]\ */width*). The map height is
+determined based on the region and projection.
 
 These are all the available projections:

examples/projections/azim/azim_equidistant.py

@@ -1,4 +1,4 @@
-"""
+r"""
 Azimuthal Equidistant
 =====================
 
@@ -8,11 +8,13 @@
 that lie within a certain distance or for comparing distances of different
 locations relative to the projection center.
 
-``elon0/lat0[/horizon]/scale`` or ``Elon0/lat0[/horizon]/width``
+**e**\ *lon0/lat0*\ [*/horizon*]\ */scale* or
+**E**\ *lon0/lat0*\ [*/horizon*]\ */width*
 
-``lon0/lat0`` specifies the projection center. The optional parameter
-``horizon`` specifies the max distance to the projection center (i.e. the
-visibile portion of the rest of the world map) in degrees <= 180° (default 180°).
+The projection type is set with **e** or **E**, *lon0/lat0* specifies the projection
+center, and the optional parameter *horizon* specifies the max distance to the
+projection center (i.e. the visibile portion of the rest of the world map) in
+degrees <= 180° (default 180°). The size of the figure is set by *scale* or *width*.
 """
 import pygmt
 

examples/projections/azim/azim_general_perspective.py

@@ -1,21 +1,24 @@
-"""
+r"""
 General Perspective
 ===================
 
 The general perspective projection imitates the view of the Earth from a finite
 point in space. In a full view of the earth one third of its surface area can
 be seen.
 
-``lon0/lat0/altitude/azimuth/tilt/twist/Width/Height/scale`` or ``width``
+**g**\ *lon0/lat0*\ */altitude*\ */azimuth*\ */tilt*\ */twist*\ */Width*\ */Height*\ */scale*
+or **G**\ *lon0/lat0*\ */altitude*\ */azimuth*\ */tilt*\ */twist*\ */Width*\ */Height*\ */width*
 
-``lon0/lat0`` specifies the projection center, ``altitude`` the height
+The projection type is set with **g** or **G**.
+*lon0/lat0* specifies the projection center and *altitude* sets the height
 in km of the viewpoint above local sea level (If altitude is less than 10,
 then it is the distance from the center of the earth to the viewpoint in earth
-radii). With ``azimuth`` the direction (in degrees) in which you are looking is
-specified, measured clockwise from north. ``tilt`` is given in degrees and is the
+radii). With *azimuth* the direction (in degrees) in which you are looking is
+specified, measured clockwise from north. *tilt* is given in degrees and is the
 viewing angle relative to zenith. A tilt of 0° is looking straight down, 60° is
-looking 30° above horizon. ``twist`` is the clockwise rotation of the image (in
-degrees). ``Width`` and ``Height`` describe the viewport angle in degrees.
+looking 30° above horizon. *twist* is the clockwise rotation of the image (in
+degrees). *Width* and *Height* describe the viewport angle in degrees, and *scale*
+or *width* determine the size of the figure.
 
 The example shows the coast of northern europe viewed from 250 km above sea
 level looking 30° from north at a tilt of 45°. The height and width of the

examples/projections/azim/azim_general_stereographic.py

@@ -1,4 +1,4 @@
-"""
+r"""
 General Stereographic
 =====================
 
@@ -9,17 +9,13 @@
 It is often used as a hemisphere map like the Lambert Azimuthal Equal Area
 projection.
 
-``slon0/lat0[/horizon]/scale`` or ``Slon0/lat0[/horizon]/width``
-
-``lon0/lat0`` specifies the projection center, the optional ``horizon`` parameter
-specifies the max distance from projection center (in degrees, < 180, default 90).
-
-This projection can be displayed:
+**s**\ *lon0/lat0*\ [*/horizon*]\ */scale*
+or **S**\ *lon0/lat0*\ [*/horizon*\]\ */width*
 
-* With map boundaries coinciding with longitude and latitude:
-  ``region`` specified via ``xmin/xmax/ymin/ymax``
-* As a map with rectangular boundaries: ``region`` specified as lower left and
-  upper right corner ``xlleft/ylleft/xuright/yurightr``. Note the appended ``r``.
+The projection type is set with **s** or **S**. *lon0/lat0* specifies the
+projection center, the optional *horizon* parameter specifies the max distance from
+projection center (in degrees, < 180, default 90), and the *scale* or *width* sets the
+size of the figure.
 """
 import pygmt
 

examples/projections/azim/azim_gnomonic.py

@@ -1,4 +1,4 @@
-"""
+r"""
 Gnomonic
 ========
 
@@ -10,10 +10,13 @@
 that the scope of application is restricted to a small area around the
 projection center (at a maximum of 60°).
 
-``flon0/lat0[/horizon]/scale`` or ``Flon0/lat0[/horizon]/width``
+**f**\ *lon0/lat0*\ [*/horizon*\ ]\ */scale*
+or **F**\ *lon0/lat0*\ [*/horizon*\ ]\ */width*
 
-``lon0/lat0`` specify the projection center, the optional parameter ``horizon``
-specifies the max distance from projection center (in degrees, < 90, default 60).
+**f** or **F** specifies the projection type, *lon0/lat0* specifies the projection
+center, the optional parameter *horizon* specifies the max distance from projection
+center (in degrees, < 90, default 60), and *scale* or *width* sets the size of the
+figure.
 """
 import pygmt
 

examples/projections/azim/azim_lambert.py

@@ -1,4 +1,4 @@
-"""
+r"""
 Lambert Azimuthal Equal Area
 ============================
 
@@ -7,9 +7,12 @@
 equal-area projection, but is not perspective. Distortion is zero at the center of the
 projection, and increases radially away from this point.
 
-``Alon0/lat0[/horizon]/width``: ``lon0`` and ``lat0`` specifies the projection center.
-``horizon`` specifies the max distance from projection center (in degrees, <= 180,
-default 90).
+**a**\ *lon0/lat0*\ [*/horizon*\ ]\ */scale*
+or **A**\ *lon0/lat0*\ [*/horizon*\ ]\ */width*
+
+**a** or **A** specifies the projection type, and *lon0/lat0* specifies the projection
+center, *horizon* specifies the max distance from projection center (in degrees,
+<= 180, default 90), and *scale* or *width* sets the size of the figure.
 """
 import pygmt
 

examples/projections/azim/azim_orthographic.py

@@ -1,4 +1,4 @@
-"""
+r"""
 Orthographic
 ============
 
@@ -8,10 +8,12 @@
 space, were one hemisphere can be seen as a whole. It is neither conformal nor
 equal-area and the distortion increases near the edges.
 
-``glon0/lat0[/horizon]/scale`` or ``Glon0/lat0[/horizon]/width``
+**g**\ *lon0/lat0*\ [*/horizon*\ ]\ */scale*
+or **G**\ *lon0/lat0*\ [*/horizon*\ ]\ */width*
 
-``lon0/lat0`` specifies the projection center, the optional parameter ``horizon``
-specifies the max distance from projection center (in degrees, <= 90, default 90)
+**g** or **G** specifies the projection type, *lon0/lat0* specifies the projection
+center, the optional parameter *horizon* specifies the max distance from projection
+center (in degrees, <= 90, default 90), and *scale* and *width* set the figure size.
 """
 import pygmt
 

examples/projections/conic/conic_albers.py

@@ -1,4 +1,4 @@
-"""
+r"""
 Albers Conic Equal Area
 =======================
 
@@ -11,8 +11,12 @@
 Between them, the scale along parallels is too small; beyond them it is too large.
 The opposite is true for the scale along meridians.
 
-``Blon0/lat0/lat1/lat2/width``: Give projection center ``lon0/lat0`` and two standard
-parallels ``lat1/lat2``.
+**b**\ *lon0/lat0*\ /\ *lat1/lat2*\ */scale*
+or **B**\ *lon0/lat0*\ /\ *lat1/lat2*\ */width*
+
+The projection is set with **b** or **B**. The projection center is set by *lon0/lat0*
+and two standard parallels for the map are set with *lat1/lat2*. The figure size is set
+with *scale* or *width*.
 """
 import pygmt
 

examples/projections/conic/conic_equidistant.py

@@ -1,4 +1,4 @@
-"""
+r"""
 Equidistant conic
 =================
 
@@ -7,8 +7,12 @@
 compromise between them. The scale is true along all meridians and the
 standard parallels.
 
-``Dlon0/lat0/lat1/lat2/width``: Give projection center ``lon0/lat0``, two standard
-parallels ``lat1/lat2``, and the map width.
+**d**\ *lon0/lat0*\ /\ *lat1/lat2*\ */scale*
+or **D**\ *lon0/lat0*\ /\ *lat1/lat2*\ */width*
+
+The projection is set with **d** or **D**. The projection center is set by *lon0/lat0*
+and two standard parallels for the map are set with *lat1/lat2*. The figure size is set
+with *scale* or *width*.
 """
 import pygmt
 

examples/projections/conic/conic_lambert.py

@@ -1,4 +1,4 @@
-"""
+r"""
 Lambert Conic Conformal Projection
 ==================================
 
@@ -9,8 +9,12 @@
 with a common origin, and meridians are the equally spaced radii of these circles. As
 with Albers projection, it is only the two standard parallels that are distortion-free.
 
-``Llon0/lat0/lat1/lat2/width``: Give projection center ``lon0/lat0``, two standard
-parallels ``lat1/lat2``, and the map width.
+**l**\ *lon0/lat0*\ /\ *lat1/lat2*\ */scale*
+or **L**\ *lon0/lat0*\ /\ *lat1/lat2*\ */width*
+
+The projection is set with **l** or **L**. The projection center is set by *lon0/lat0*
+and two standard parallels for the map are set with *lat1/lat2*. The figure size is set
+with *scale* or *width*.
 """
 import pygmt
 

examples/projections/conic/polyconic.py

@@ -1,4 +1,4 @@
-"""
+r"""
 Polyconic Projection
 ====================
 
@@ -18,7 +18,10 @@
 consequence, no parallel is standard because conformity is lost with the lengthening of
 the meridians.
 
-``Poly/width``:  The only additional argument for the projection is the map width.
+**poly**\ */scale* or **Poly**\ */width*
+
+The projection is set with **poly** or **Poly**. The figure size is set
+with *scale* or *width*.
 """
 import pygmt