diff --git a/.gitignore b/.gitignore index c5d41027a5f..74dc9ec2767 100644 --- a/.gitignore +++ b/.gitignore @@ -28,6 +28,7 @@ doc/_build/ doc/gallery/ doc/projections/ doc/tutorials/ +doc/get-started/ # Jupyter Notebook .ipynb_checkpoints/ diff --git a/doc/Makefile b/doc/Makefile index 08ce0330a89..b25cbc6c91e 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -57,4 +57,5 @@ clean: rm -rf api/generated rm -rf gallery rm -rf tutorials + rm -rf get-started rm -rf projections diff --git a/doc/conf.py b/doc/conf.py index 1ce78b421f0..07ab69bde94 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -66,10 +66,11 @@ "examples_dirs": [ "../examples/gallery", "../examples/tutorials", + "../examples/get-started", "../examples/projections", ], # path where to save gallery generated examples - "gallery_dirs": ["gallery", "tutorials", "projections"], + "gallery_dirs": ["gallery", "tutorials", "get-started", "projections"], "subsection_order": ExplicitOrder( [ "../examples/gallery/maps", @@ -89,6 +90,7 @@ "../examples/projections/table", "../examples/tutorials/basics", "../examples/tutorials/advanced", + "../examples/get-started", ] ), # Patter to search for example files diff --git a/doc/index.rst b/doc/index.rst index 6d34e27b28c..092eda4bbb0 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -20,7 +20,7 @@ overview.rst install.rst - tutorials/basics/first_figure.rst + get-started/index.rst .. toctree:: :maxdepth: 2 diff --git a/examples/get-started/README.txt b/examples/get-started/README.txt new file mode 100644 index 00000000000..a8fac64a7f7 --- /dev/null +++ b/examples/get-started/README.txt @@ -0,0 +1,17 @@ +Intro to PyGMT +============== + +Welcome to PyGMT! This tutorial is designed to teach the basic concepts to +make a map in PyGMT. + +**About this tutorial** + +This tutorial assumes that PyGMT has been successfully +:doc:`installed `. A quick way to test this is to type +``import pygmt`` in a Python IDE or +`Jupyter `__ Notebook. + +This tutorial will progressively cover PyGMT plotting concepts, and later +examples will use concepts explained in previous examples. It will not +cover all PyGMT modules. + diff --git a/examples/get-started/first_figure.py b/examples/get-started/first_figure.py new file mode 100644 index 00000000000..86346dc6f34 --- /dev/null +++ b/examples/get-started/first_figure.py @@ -0,0 +1,156 @@ +""" +1. Making your first figure +=========================== + +This tutorial page covers the basics of creating a figure using PyGMT - a +Python wrapper for the Generic Mapping Tools (GMT). It will only use +the ``coast`` module for plotting. Later examples will address other PyGMT +modules. +""" + +############################################################################### +# Setting up the development environment +# -------------------------------------- +# +# PyGMT can be used in both a Python script and a notebook environment, such +# as Jupyter. The tutorial's recommended method is to use a notebook, and the +# code will be for a notebook environment. + + +############################################################################### +# Loading the library +# ------------------- +# +# The first step is to import ``pygmt``. All modules and figure generation is +# accessible from the :mod:`pygmt` top level package. + +# sphinx_gallery_thumbnail_number = 4 +import pygmt + +############################################################################### +# Creating a figure +# ----------------- +# +# All figure generation in PyGMT is handled by the :class:`pygmt.Figure` class. +# Start a new figure by creating an instance of this class: + +fig = pygmt.Figure() + +############################################################################### +# To add to a plot object (``fig`` in this example), the PyGMT module is used +# as a method on the class. This example will use the module ``coast``, which +# can be used to create a map without any other modules or external data. The +# ``coast`` module plots the coastlines, borders, and bodies of water using a +# database that is included in GMT. +# +# First, a region for the figure must be selected. This example will plot some +# of the coast of Maine in the northeastern US. A Python list can be passed to +# the ``region`` argument with the minimum and maximum X-values (longitude) +# and the minimum and maximum Y-values (latitude). For this example, the +# minimum (bottom left) coordinates are (N43.75, W69) and the maximum (top +# right) coordinates are (N44.75, W68). Negative values can be passed for +# latitudes in the southern hemisphere or longitudes in the western hemisphere. +# +# In addition to the region, an argument needs to be passed to ``coast`` to +# tell it what to plot. In this example, ``coast`` will be told to plot the +# shorelines by passing the Boolean value ``True`` to the ``shorelines`` +# parameter. The ``shorelines`` parameter has other options for finer control, +# but setting it to ``True`` uses the default values. + +fig.coast(region=[-69, -68, 43.75, 44.75], shorelines=True) + +############################################################################### +# To see the figure, call :meth:`pygmt.Figure.show`. + +fig.show() + +############################################################################### +# Color the land and water +# ------------------------ +# +# This figure plots all of the coastlines in the given region, but it does not +# indicate where the land and water are. Color values can be passed to ``land`` +# and ``water`` to set the colors on the figure. +# +# When plotting colors in PyGMT, there are multiple +# :gmt-docs:`color codes `, that can be used. This includes +# standard GMT color names (like ``skyblue``), R/G/B levels (like ``0/0/255``), +# a hex value (like ``#333333``), or a graylevel (like ``50``). For this +# example, GMT color names are used. + +fig = pygmt.Figure() +fig.coast( + region=[-69, -68, 43.75, 44.75], + shorelines=True, + land="lightgreen", + water="lightblue", +) +fig.show() + +############################################################################### +# Set the projection +# ------------------ +# +# This figure now has its colors set, but there is no projection or size +# set for the map. Both of these values are set using the ``projection`` +# parameter. +# +# The appropriate projection varies for the type of map. The available +# projections are explained in the :doc:`projection ` +# gallery. For this example, the Mercator projection is set using ``"M"``. +# The width of the figure will be 10 centimeters, as set by ``"10c"``. The map +# size can also be set in inches using "i" (e.g. a 5 inch wide Mercator +# projection would use ``"M5i"``). + +fig = pygmt.Figure() +fig.coast( + region=[-69, -68, 43.75, 44.75], + shorelines=True, + land="lightgreen", + water="lightblue", + projection="M10c", +) +fig.show() + +############################################################################### +# Add a frame +# ----------- +# +# While that the map's colors, projection, and size have been set, the region +# that is being displayed is not apparent. A frame can be added to +# annotate the latitude and longitude of the region. +# +# The ``frame`` parameter is used to add a frame to the figure. For now, it +# will be set to ``True`` to use default settings, but later tutorials will +# show how ``frame`` can be used to customize the axes, gridlines, and titles. + +fig = pygmt.Figure() +fig.coast( + region=[-69, -68, 43.75, 44.75], + shorelines=True, + land="lightgreen", + water="lightblue", + projection="M10c", + frame=True, +) +fig.show() + +############################################################################### +# Additional exercises +# -------------------- +# +# This is the end of the first tutorial. Here are some additional exercises +# for the concepts that were discussed: +# +# 1. Make a map of Germany using its ISO country code ("DE"). Pass the ISO +# code as a Python string to the ``region`` parameter. +# +# 2. Change the color of the land to "khaki" and the water to "azure". +# +# 3. Change the color of the lakes (using the ``lakes`` parameter) to "red". +# +# 4. Create a global map. Set the region to "d" to center the map at the Prime +# Meridian or "g" to center the map at the International Date Line. When the +# region is set without using a list full of integers or floating numbers, +# the argument needs to be passed as a Python string. Create a 15 centimeter +# map using the Mollwide ("W") projection. diff --git a/examples/tutorials/basics/first_figure.py b/examples/tutorials/basics/first_figure.py deleted file mode 100644 index 66ff736020f..00000000000 --- a/examples/tutorials/basics/first_figure.py +++ /dev/null @@ -1,98 +0,0 @@ -""" -Making your first figure -======================== - -Welcome to PyGMT! Here we'll cover some of basic concepts, like creating simple -figures and naming conventions. -""" - -############################################################################### -# Loading the library -# ------------------- -# -# All modules and figure generation is accessible from the :mod:`pygmt` top -# level package: - -import pygmt - -############################################################################### -# Creating figures -# ---------------- -# -# All figure generation in PyGMT is handled by the :class:`pygmt.Figure` class. -# Start a new figure by creating an instance of this class: - -fig = pygmt.Figure() - -############################################################################### -# Add elements to the figure using its methods. For example, let's use -# :meth:`pygmt.Figure.basemap` to start the creation of a map. We'll use the -# ``region`` parameter to provide the longitude and latitude bounds, the -# ``projection`` parameter to set the projection to Mercator (**M**) and the -# map width to 15 cm, and the ``frame`` parameter to generate a frame with -# automatic tick and annotation spacings. - -fig.basemap(region=[-90, -70, 0, 20], projection="M15c", frame=True) - -############################################################################### -# Now we can add coastlines using :meth:`pygmt.Figure.coast` to this map using -# the default resolution, line width, and color: - -fig.coast(shorelines=True) - -############################################################################### -# To see the figure, call :meth:`pygmt.Figure.show`: - -fig.show() - -############################################################################### -# You can also set the map region, projection, and frame type directly in other -# methods without calling :meth:`gmt.Figure.basemap`: - -fig = pygmt.Figure() -fig.coast(shorelines=True, region=[-90, -70, 0, 20], projection="M15c", frame=True) -fig.show() - -############################################################################### -# Saving figures -# -------------- -# -# Use the method :meth:`pygmt.Figure.savefig` to save your figure to a file. -# The figure format is inferred from the extension. -# -# .. code:: python -# -# fig.savefig("central-america-shorelines.png") -# -# Note for experienced GMT users -# ------------------------------ -# -# You have probably noticed several things that are different from classic -# command-line GMT. Many of these changes reflect the new GMT modern execution -# mode that is part of GMT 6. -# -# 1. As a general rule, the ``ps`` prefix has been removed from all ``ps*`` -# modules (PyGMT methods). For example, the name of the GMT 5 module -# ``pscoast`` is ``coast`` in GMT 6 and PyGMT. The exceptions are: ``psxy`` -# which is now ``plot``, ``psxyz`` which is now ``plot3d``, and ``psscale`` -# which is now ``colorbar``. -# -# 2. More details can be found in the :gmt-docs:`GMT cookbook introduction to -# modern mode `. -# -# A few are PyGMT exclusive (like the ``savefig`` method). -# -# 1. The PyGMT parameters (called options or arguments in GMT) 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 PyGMT aliases should be straightforward. -# For some modules, these aliases are still being developed. -# 2. Parameters like ``region`` can take :class:`lists ` as well as -# strings like ``1/2/3/4``. -# 3. If a GMT option has no arguments (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 -# :class:`list`: ``frame=["+Loleron", "xaf", "y+lm"]``. -# 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.