python-demo-google-colab.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Try PyGMT on Google Colab"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This Jupyter Notebook shows how to install and use PyGMT on Google Colab."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**NOTE:** Any changes will be lost when the Jupyter lab is closed. Select \"File\"->\"Download\" to save notebooks to your computer."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To execute the code cells, select it and type `Shift + Enter` or click on the \"Run\" ► button in the menu bar. \n",
    "\n",
    "For tutorials and more examples, visit the official website: https://www.pygmt.org"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "tags": []
   },
   "source": [
    "## Install PyGMT and its dependencies on Google Colab\n",
    "\n",
    "**Google Colab** doesn't have PyGMT and its dependencies installed. We need to follow the instructions below to install them.\n",
    "\n",
    "First, we need to install conda on Google Colab. The installation process is greatly simplified using the [condacolab](https://github.com/conda-incubator/condacolab) package.\n",
    "\n",
    "*After condacolab finishes the installation, it will restart the Python kernel for changes to be applied. This happens automatically. Thus, you will see a message saying \"Your session crashed for an unknown reason\". You can safely ignore this message!*"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!pip install -q condacolab\n",
    "import condacolab\n",
    "condacolab.install()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now we can install PyGMT and its dependencies using a single command. The installation may take a few minutes:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!mamba install pygmt"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Loading the PyGMT package\n",
    "\n",
    "You can load PyGMT by importing the `pygmt` Python package. Most GMT processing modules will be avialable as functions in this package. The plotting modules are methods of the `pygmt.Figure` class."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Load the PyGMT package. This only needs to be run once\n",
    "import pygmt"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Check the installed environment\n",
    "\n",
    "Before starting, let's first check the current environment:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pygmt.show_versions()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Example 1"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "All figure generation in PyGMT is handled by the `pygmt.Figure` class. \n",
    "It has methods to add layers to your figure, like a basemap, coastlines, etc."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We start a new figure by creating an instance of `pygmt.Figure`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "fig = pygmt.Figure()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We add elements to the figure using its methods. For example, lets add the global coastlines to a 15 cm wide map using the Hammer projection (**H**). \n",
    "Our figure will also have a nice frame with automatic ticks."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "fig.coast(region='g', projection='H15c', frame=True, land='lightbrown', water='lightblue')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can see a preview of the figure directly in the Jupyter notebook using `fig.show()`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "fig.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can also save your figure in several graphics formats (e.g., png, pdf, jpg) using `fig.savefig()`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "fig.savefig(\"global.png\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Example 2"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from pygmt.datasets import load_earth_relief\n",
    "\n",
    "grid = load_earth_relief(resolution='01d', registration='pixel')\n",
    "\n",
    "fig = pygmt.Figure()\n",
    "fig.basemap(region='g', projection='G200/30/12c', frame=True)\n",
    "fig.grdimage(grid, cmap='geo', shading=True)\n",
    "fig.coast(resolution='c', shorelines=True, area_thresh=1000)\n",
    "fig.plot(data='@hotspots.txt', style='c0.2c', fill='red')\n",
    "fig.colorbar()\n",
    "fig.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Experiment for yourself"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Try running different things in the cells below or edit and rerun the cells above."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "fig = pygmt.Figure()\n",
    "# Any Python codes here\n",
    "fig.show()"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.9.15"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}