diff --git a/doc/install.rst b/doc/install.rst index 33b8cf695f1..2a233cdc425 100644 --- a/doc/install.rst +++ b/doc/install.rst @@ -41,7 +41,7 @@ Start by looking at the tutorials on our sidebar, good luck! The sections below provide more detailed, step by step instructions to installing and testing PyGMT for those who may have a slightly different - setup. + setup or want to install the latest development version. Which Python? ------------- @@ -51,9 +51,10 @@ work, but there is no guarantee that PyGMT will behave as expected. We recommend using the `Anaconda `__ Python distribution to ensure you have all dependencies installed and the -``conda`` package manager available. -Installing Anaconda does not require administrative rights to your computer and -doesn't interfere with any other Python installations in your system. +`conda `__ +package manager available. Installing Anaconda does not require administrative +rights to your computer and doesn't interfere with any other Python +installations in your system. Which GMT? @@ -110,14 +111,14 @@ Now we can create a new conda environment with Python and all our dependencies installed (we'll call it ``pygmt`` but feel free to change it to whatever you want):: - conda create --name pygmt python=3.9 pip numpy pandas xarray netcdf4 packaging gmt + conda create --name pygmt python=3.9 numpy pandas xarray netcdf4 packaging gmt Activate the environment by running the following (**do not forget this step!**):: conda activate pygmt From now on, all commands will take place inside the conda virtual environment -called 'pygmt' and won't affect your default 'base' installation. +called ``pygmt`` and won't affect your default ``base`` installation. Installing PyGMT @@ -134,6 +135,10 @@ This installs the latest stable release of PyGMT from conda install pygmt +This upgrades the installed PyGMT to be the latest stable release:: + + conda update pygmt + Using pip ~~~~~~~~~ @@ -142,18 +147,28 @@ This installs the latest stable release from pip install pygmt -Alternatively, you can install the latest development version from +This upgrades the installed PyGMT to be the latest stable release:: + + pip install --upgrade pygmt + +You also can install the latest development version from `TestPyPI `__:: pip install --pre --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple pygmt -or from PyGMT's `GitHub repository `__ +To upgrade the installed development version to be the latest one, just add ``--upgrade``:: + + pip install --upgrade --pre --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple pygmt + +Alternatively, you can install the latest development version from PyGMT's `GitHub repository `__ (slower as it downloads the whole archive):: pip install git+https://github.com/GenericMappingTools/pygmt.git#egg=pygmt -Any of the above methods (conda/pip) should allow you to use the ``pygmt`` -library from Python. +Run the above command again to upgrade to the latest development version. + +Any of the above methods (conda/pip) should allow you to use the PyGMT package +from Python. Testing your install @@ -182,7 +197,8 @@ dependencies as well (be sure to have your conda environment activated):: conda install pytest pytest-mpl ipython -Test your installation by running the following inside a Python interpreter:: +Test your installation by running the following inside a Python interpreter +(note that it may take a few minutes):: import pygmt pygmt.show_versions() @@ -193,14 +209,14 @@ Finding the GMT shared library ------------------------------ Sometimes, PyGMT will be unable to find the correct version of the GMT shared -library. +library (``libgmt``). This can happen if you have multiple versions of GMT installed. You can tell PyGMT exactly where to look for ``libgmt`` by setting the ``GMT_LIBRARY_PATH`` environment variable. This should be set to the directory where ``libgmt.so``, ``libgmt.dylib`` or -``gmt.dll`` can be found for Linux, macOS and Windows respectively. -e.g. on a command line, run:: +``gmt.dll`` can be found for Linux, macOS and Windows, respectively. +e.g., on a command line, run:: # Linux/macOS export GMT_LIBRARY_PATH=$HOME/anaconda3/envs/pygmt/lib diff --git a/examples/gallery/coast/land_and_water.py b/examples/gallery/coast/land_and_water.py index 3ee3a012088..02413e0dc78 100644 --- a/examples/gallery/coast/land_and_water.py +++ b/examples/gallery/coast/land_and_water.py @@ -2,9 +2,10 @@ Color land and water -------------------- -The ``land`` and ``water`` parameters of :meth:`pygmt.Figure.coast` specify a color to -fill in the land and water masses, respectively. You can use standard GMT color names or -give a hex value (like ``#333333``). +The ``land`` and ``water`` parameters of :meth:`pygmt.Figure.coast` specify a +color to fill in the land and water masses, respectively. You can use +:gmt-docs:`standard GMT color names ` +or give a hex value (like ``#333333``). """ import pygmt diff --git a/examples/gallery/grid/grdview_surface.py b/examples/gallery/grid/grdview_surface.py index 760f30499e6..734795efd23 100644 --- a/examples/gallery/grid/grdview_surface.py +++ b/examples/gallery/grid/grdview_surface.py @@ -5,11 +5,11 @@ The :meth:`pygmt.Figure.grdview()` method can plot 3-D surfaces with ``surftype="s"``. Here, we supply the data as an :class:`xarray.DataArray` with the coordinate vectors ``x`` and ``y`` defined. Note that the ``perspective`` parameter here controls the azimuth and -elevation angle of the view. We provide a list of two arguments to ``frame`` - the -first argument specifies the :math:`x`- and :math:`y`:-axes frame attributes and the +elevation angle of the view. Specifying the same scale for the ``projection`` and ``zcale`` +parameters ensures equal axis scaling. We provide a list of two arguments to ``frame`` - the +first argument specifies the :math:`x`- and :math:`y`-axes frame attributes and the second argument, prepended with ``"z"``, specifies the :math:`z`-axis frame attributes. -Specifying the same scale for the ``projection`` and ``zcale`` parameters ensures equal -axis scaling. The ``shading`` parameter specifies illumination; here we choose an azimuth of +The ``shading`` parameter specifies illumination; here we choose an azimuth of 45° with ``shading="+a45"``. """ @@ -41,13 +41,13 @@ def ackley(x, y): SCALE = 0.5 # in centimeter fig.grdview( data, - frame=["a5f1", "za5f1"], + surftype="s", projection=f"x{SCALE}c", zscale=f"{SCALE}c", - surftype="s", - cmap="roma", perspective=[135, 30], # Azimuth southeast (135°), at elevation 30° + frame=["a5f1", "za5f1"], shading="+a45", + cmap="roma", ) fig.show() diff --git a/examples/gallery/grid/track_sampling.py b/examples/gallery/grid/track_sampling.py index 02ba34a418c..8d17987ca69 100644 --- a/examples/gallery/grid/track_sampling.py +++ b/examples/gallery/grid/track_sampling.py @@ -24,10 +24,10 @@ fig = pygmt.Figure() # Plot the earth relief grid on Cylindrical Stereographic projection, masking land areas -fig.basemap(region="g", frame=True, projection="Cyl_stere/150/-20/15c") +fig.basemap(region="g", projection="Cyl_stere/150/-20/15c", frame=True) fig.grdimage(grid=grid, cmap="gray") fig.coast(land="#666666") -# Plot using circles (c) of 0.15 cm, the sampled bathymetry points +# Plot the sampled bathymetry points using circles (c) of 0.15 cm # Points are colored using elevation values (normalized for visual purposes) fig.plot( x=track.longitude, diff --git a/examples/gallery/line/line-custom-cpt.py b/examples/gallery/line/line-custom-cpt.py index 4406c69f697..09a850e31ea 100644 --- a/examples/gallery/line/line-custom-cpt.py +++ b/examples/gallery/line/line-custom-cpt.py @@ -19,7 +19,7 @@ x = np.arange(start=20, stop=30, step=0.2) fig = pygmt.Figure() -fig.basemap(frame=["WSne", "af"], region=[20, 30, -10, 10]) +fig.basemap(region=[20, 30, -10, 10], frame=["WSne", "af"]) # Create a custom CPT with the batlow CPT and 10 discrete z-values (colors) pygmt.makecpt(cmap="batlow", series=[0, 10, 1]) diff --git a/examples/gallery/line/linestyles.py b/examples/gallery/line/linestyles.py index 625be8c18f2..1bd563b876b 100644 --- a/examples/gallery/line/linestyles.py +++ b/examples/gallery/line/linestyles.py @@ -38,7 +38,9 @@ "1p,lightblue,-.", # dash-dotted line "2p,blue,..-", # dot-dot-dashed line "2p,tomato,--.", # dash-dash-dotted line - "2p,tomato,4_2:2p", # A pattern of 4-point-long line segment and 2-point-gap between segment + # A pattern of 4-point-long line segment and 2-point-gap between segment, + # with pattern offset by 2 points from the origin + "2p,tomato,4_2:2p", ]: y -= 1 # Move the current line down fig.plot(x=x, y=y, pen=linestyle) diff --git a/examples/gallery/plot/colorbar.py b/examples/gallery/plot/colorbar.py index eb9994191ab..7e5485c7087 100644 --- a/examples/gallery/plot/colorbar.py +++ b/examples/gallery/plot/colorbar.py @@ -49,8 +49,7 @@ # with a length/width (+w) of 7cm by 0.5cm and a box for NaN values (+n) position="JMR+o1c/0c+w7c/0.5c+n+mc", # Note that the label 'Elevation' is moved to the opposite side and plotted - # vertically as a column of text using '+mc' in the position parameter - # above + # vertically as a column of text using '+mc' in the position parameter above frame=["x+lElevation", "y+lm"], scale=10, ) diff --git a/examples/gallery/plot/image.py b/examples/gallery/plot/image.py index aa5984d7b1e..8f6f2719d49 100644 --- a/examples/gallery/plot/image.py +++ b/examples/gallery/plot/image.py @@ -18,7 +18,8 @@ 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 +# on a basemap, scaled up to be 3 cm wide 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", diff --git a/examples/gallery/plot/inset.py b/examples/gallery/plot/inset.py index 8f549b00f49..754a7ad903b 100644 --- a/examples/gallery/plot/inset.py +++ b/examples/gallery/plot/inset.py @@ -4,8 +4,8 @@ The :meth:`pygmt.Figure.inset` method adds an inset figure inside a larger figure. The function is called using a ``with`` statement, and its position, -box, offset, and margin parameters are set. Within the ``with`` statement, -PyGMT plotting functions can be called that add to the inset figure. +box, offset, and margin parameters are set. Plotting methods called within the +``with`` statement plot into the inset figure. """ import pygmt diff --git a/examples/gallery/plot/multi-parameter-symbols.py b/examples/gallery/plot/multi-parameter-symbols.py index f4a1171daed..3a28baf681b 100644 --- a/examples/gallery/plot/multi-parameter-symbols.py +++ b/examples/gallery/plot/multi-parameter-symbols.py @@ -26,37 +26,26 @@ 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() diff --git a/examples/gallery/plot/points-transparency.py b/examples/gallery/plot/points-transparency.py index f6b0d5bef04..fe32630a701 100644 --- a/examples/gallery/plot/points-transparency.py +++ b/examples/gallery/plot/points-transparency.py @@ -18,8 +18,8 @@ fig = pygmt.Figure() fig.basemap( region=[-5, 105, 0, 2], - frame=['xaf+l"Transparency level"+u%', "WSrt"], projection="X15c/6c", + frame=['xaf+l"Transparency level"+u%', "WSrt"], ) fig.plot(x=x, y=y, style="c0.6c", color="blue", pen="1p,red", transparency=transparency) fig.show() diff --git a/examples/gallery/plot/scatter3d.py b/examples/gallery/plot/scatter3d.py index a573005cc88..664c20ea81d 100644 --- a/examples/gallery/plot/scatter3d.py +++ b/examples/gallery/plot/scatter3d.py @@ -5,7 +5,7 @@ The :meth:`pygmt.Figure.plot3d` method can be used to plot symbols in 3D. In the example below, we show how the `Iris flower dataset `__ -can be visualized using a perspective 3-dimensional plot. The ``region`` +can be visualized using a perspective 3D plot. The ``region`` parameter has to include the :math:`x`, :math:`y`, :math:`z` axis limits in the form of (xmin, xmax, ymin, ymax, zmin, zmax), which can be done automatically using :meth:`pygmt.info`. To plot the z-axis frame, set ``frame`` as a @@ -36,6 +36,7 @@ x=df.petal_width, y=df.sepal_length, z=df.petal_length, + style="uc", # 3D cUbe, with size in centimeter units sizes=0.1 * df.sepal_width, # Vary each symbol size according to a data column color=df.species.cat.codes.astype(int), # Points colored by categorical number code cmap=True, # Use colormap created by makecpt @@ -46,7 +47,6 @@ 'yafg+l"Sepal Length"', 'zafg+l"Petal Length"', ], - style="uc", # 3D cUbe, with size in centimeter units perspective=[315, 25], # Azimuth NorthWest (315°), at elevation 25° zscale=1.5, # Vertical exaggeration factor ) diff --git a/examples/tutorials/first-figure.py b/examples/tutorials/first-figure.py index 17380d1139b..14689bf36fa 100644 --- a/examples/tutorials/first-figure.py +++ b/examples/tutorials/first-figure.py @@ -7,7 +7,8 @@ .. note:: - This tutorial assumes the use of a Python notebook, such as IPython or Jupyter Notebook. + This tutorial assumes the use of a Python notebook, such as `IPython `__ + or `JupyterLab `__. To see the figures while using a Python script instead, use ``fig.show(method="external")`` to display the figure in the default PDF viewer. @@ -34,11 +35,12 @@ fig = pygmt.Figure() ######################################################################################## -# Add elements to the figure using its methods. For example, let's start a map with an -# automatic frame and ticks around a given longitude and latitude bound, set the -# projection to Mercator (``M``), and the map width to 8 inches: +# Add elements to the figure using its methods. For example, let's use +# :meth:`pygmt.Figure.basemap` to start a map for a region indicated by a given +# longitude and latitude bound, set the projection to Mercator (**M**), the +# map width to 8 cm, and frame type to be generated automatically: -fig.basemap(region=[-90, -70, 0, 20], projection="M8i", frame=True) +fig.basemap(region=[-90, -70, 0, 20], projection="M8c", frame=True) ######################################################################################## # Now we can add coastlines using :meth:`pygmt.Figure.coast` to this map using the @@ -56,7 +58,7 @@ # without calling :meth:`gmt.Figure.basemap`: fig = pygmt.Figure() -fig.coast(shorelines=True, region=[-90, -70, 0, 20], projection="M8i", frame=True) +fig.coast(shorelines=True, region=[-90, -70, 0, 20], projection="M8c", frame=True) fig.show() ######################################################################################## @@ -74,20 +76,25 @@ # ------------------------------ # # You’ll probably have noticed several things that are different from classic -# command-line GMT. Many of these changes reflect the new GMT modern execution mode that -# are part of GMT 6. A few are PyGMT exclusive (like the ``savefig`` method). +# command-line GMT. Many of these changes reflect the new GMT modern execution +# mode that is part of GMT 6. # # 1. The name of method is ``coast`` instead of ``pscoast``. As a general rule, all # ``ps*`` modules had their ``ps`` prefix removed. The exceptions are: # ``psxy`` which is now ``plot``, ``psxyz`` which is now ``plot3d``, and ``psscale`` # which is now ``colorbar``. -# 2. The parameters don't use the GMT 1-letter syntax (**R**, **J**, **B**, etc). We use longer +# +# 2. More details can be found at :gmt-docs:`/cookbook/introduction.html#modern-and-classic-mode` +# +# A few are PyGMT exclusive (like the ``savefig`` method). +# +# 1. The parameters don't use the GMT 1-letter syntax (**R**, **J**, **B**, etc). We use longer # aliases for these parameters and have some Python exclusive names. The mapping # between the GMT parameters and their Python counterparts should be straight # forward. -# 3. Parameters like ``region`` can take lists as well as strings like ``1/2/3/4``. -# 4. If a GMT parameter has no options (like ``-B`` instead of ``-Baf``), use a ``True`` +# 2. Parameters like ``region`` can take lists as well as strings like ``1/2/3/4``. +# 3. If a GMT parameter has no options (like ``-B`` instead of ``-Baf``), use a ``True`` # in Python. An empty string would also be acceptable. For repeated parameters, such # as ``-B+Loleron -Bxaf -By+lm``, provide a list: ``frame=["+Loleron", "xaf", "y+lm"]``. -# 5. There is no output redirecting to a PostScript file. The figure is generated in the +# 4. There is no output redirecting to a PostScript file. The figure is generated in the # background and will only be shown or saved when you ask for it. diff --git a/examples/tutorials/plot.py b/examples/tutorials/plot.py index 52ed3e8f4c1..31fca20308e 100644 --- a/examples/tutorials/plot.py +++ b/examples/tutorials/plot.py @@ -41,8 +41,8 @@ ######################################################################################## -# We'll use :meth:`pygmt.Figure.plot` method to plot circles on the locations of the -# hypocenters of the earthquakes. +# We'll use :meth:`pygmt.Figure.plot` method to plot circles on the locations +# of the earthquakes. fig = pygmt.Figure() fig.basemap(region=region, projection="M15c", frame=True) diff --git a/examples/tutorials/regions.py b/examples/tutorials/regions.py index 34f3587a377..97d7316ad0b 100644 --- a/examples/tutorials/regions.py +++ b/examples/tutorials/regions.py @@ -147,7 +147,7 @@ ######################################################################################## # # The area encompassed by the ISO code can be expanded by appending **+r**\ *increment* -# to the ISO code. The *increment* unit is in degrees, and if only value is added it +# to the ISO code. The *increment* unit is in degrees, and if only one value is added it # expands the range of the region in all directions. Using **+r** rounds to the nearest # increment. @@ -226,8 +226,8 @@ ######################################################################################## # -# The ``region`` increment can be appended with **+e**, which expand the bounding box -# by at least 25% beyond the increment. +# The ``region`` increment can be appended with **+e**, which expands the +# bounding box by at least 25% beyond the increment. fig = pygmt.Figure() fig.coast( diff --git a/examples/tutorials/text.py b/examples/tutorials/text.py index 8474ffbbb3f..b78d70d7197 100644 --- a/examples/tutorials/text.py +++ b/examples/tutorials/text.py @@ -37,10 +37,10 @@ fig.basemap(region=[108, 120, -5, 8], projection="M20c", frame="a") fig.coast(land="black", water="skyblue") -# Plotting text annotations using single elements +# Plot text annotations using single element fig.text(text="SOUTH CHINA SEA", x=112, y=6) -# Plotting text annotations using lists of elements +# Plot text annotations using lists of elements fig.text(text=["CELEBES SEA", "JAVA SEA"], x=[119, 112], y=[3.25, -4.6]) fig.show() @@ -88,7 +88,7 @@ # Plot region names / sea names from a text file, where # the longitude (x) and latitude (y) coordinates are in the first two columns. -# Setting angle/font/justify to ``True`` will indicate that those columns are +# Setting angle/font/justify to True will indicate that those columns are # present in the text file too (Note: must be in that order!). # Finally, the text to be printed will be in the last column fig.text(textfiles="examples.txt", angle=True, font=True, justify=True)