Create gmt.show to embed plots in notebook

Saves them to a temp file and loads them with the IPython.display
machinery.

Fixes #19

doc/api.rst

@@ -14,6 +14,7 @@ function in the ``gmt`` top-level module.
  :template: function.rst
 
  gmt.figure
+ gmt.show
  gmt.psbasemap
  gmt.psconvert
  gmt.psxy

doc/first-steps.ipynb

@@ -47,27 +47,10 @@
  "gmt.psxy('@tut_quakes.ngdc', S='c0.4c', G='red', W='faint', \n",
  " i='4,3')\n",
  "# Unlike the GMT command-line interface, no figure \n",
- "# file is generated unless savefig or psconvert are \n",
- "# called.\n",
- "gmt.psconvert(F='myfigure', T='G', A=True)"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "Insert the figure into the Jupyter notebook."
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {},
- "outputs": [],
- "source": [
- "# Display the figure in the notebook\n",
- "from IPython.display import Image, display\n",
- "Image(filename='myfigure.png', embed=True, width=500)"
+ "# file is generated by default. \n",
+ "# You can display the figure in the notebook\n",
+ "# using the 'show' function.\n",
+ "gmt.show()"
  ]
  },
  {
@@ -106,25 +89,16 @@
  "gmt.psbasemap(region=[130, 150, 35, 50], projection='M6i', \n",
  " frame=True, portrait=True)\n",
  "# You can mix using aliases and the command-line names\n",
- "gmt.psxy('@tut_quakes.ngdc', style='c0.4c', G='red', \n",
+ "gmt.psxy('@tut_quakes.ngdc', style='s0.2c', G='blue', \n",
  " pen='faint', i='4,3')\n",
- "gmt.psconvert(prefix='myotherfigure', fmt='G', crop=True)\n",
- "\n",
- "Image(filename='myotherfigure.png', embed=True, width=500)"
+ "gmt.show()"
  ]
  },
  {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {
- "collapsed": true
- },
- "outputs": [],
+ "cell_type": "markdown",
+ "metadata": {},
  "source": [
- "# Clean up the generated files\n",
- "import os\n",
- "os.remove('myfigure.png')\n",
- "os.remove('myotherfigure.png')"
+ "[]()"
  ]
  }
  ],

gmt/__init__.py

@@ -8,6 +8,7 @@
 # Import modules to make the high-level GMT Python API
 from .session_management import figure, begin as _begin, end as _end
 from .ps_modules import psconvert, psbasemap, psxy
+from .extra_modules import show
 
 
 # Get the version number through versioneer

gmt/extra_modules.py

@@ -0,0 +1,43 @@
+"""
+Extra modules that are exclusive to the Python API (for things like the Jupyter
+notebook or simpler interfaces).
+"""
+import tempfile
+import os
+
+try:
+ from IPython.display import Image, display
+except ImportError:
+ Image, display = None, None
+
+from . import psconvert
+
+
+def show(dpi=100, width=500, return_img=False):
+ """
+ Display the last figure in the Jupyter notebook
+
+ You will need to have IPython installed for this to work. You should have
+ it if you are using a Jupyter notebook.
+
+ Parameters
+ ----------
+ dpi : int
+ The image resolution (dots per inch).
+ width : int
+ Width of the figure shown in the notebook in pixels.
+ return_img : bool
+ Whether or not to return the IPython.display.Image variable.
+
+ """
+ assert Image is not None and display is not None, \
+ "Couldn't find IPython. Please make sure it's installed."
+ with tempfile.TemporaryDirectory() as tmpdir:
+ prefix = os.path.join(tmpdir, 'gmt-figure-for-notebook')
+ fname = prefix + '.png'
+ psconvert(prefix=prefix, fmt='G', dpi=dpi,
+ crop=True, portrait=True)
+ img = Image(filename=fname, embed=True, width=width)
+ display(img)
+ if return_img:
+ return img

gmt/ps_modules.py

@@ -140,9 +140,6 @@ def psconvert(**kwargs):
  C : str
  Specify a single, custom option that will be passed on to GhostScript
  as is.
- D : str
- Sets an alternative output directory (which must exist). Default is the
- same directory as the PS files.
  E : int
  Set raster resolution in dpi. Default = 720 for PDF, 300 for others.
  F : str

gmt/tests/test_extra_modules.py

@@ -0,0 +1,18 @@
+"""
+Test some of the extra modules from the Python API
+"""
+import os
+
+from ..extra_modules import show
+from .. import figure, psbasemap
+
+
+def test_show():
+ "Test that show creates the correct file name and deletes the temp dir"
+ figure()
+ psbasemap(R='10/70/-300/800', J='X3i/5i', B='af',
+ D='30/35/-200/500', F=True)
+ img = show(width=800, return_img=True)
+ assert os.path.split(img.filename)[-1] == 'gmt-figure-for-notebook.png'
+ assert not os.path.exists(img.filename)
+ assert img.width == 800