"""
Making your first figure
========================
Welcome to PyGMT! Here we'll cover some of basic concepts, like creating simple figures
and naming conventions.
.. note::
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.
To save the figure, use ``fig.savefig("figname.pdf")`` where ``"figname.pdf"``
is the desired name and file extension for the saved figure.
"""
########################################################################################
# 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.