01_Modules_scripting.ipynb

{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from subprocess import PIPE\n",
    "import numpy as np\n",
    "from IPython.display import Image"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Ipython notebook tips"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Some small tips of the new interface in python/ipython:\n",
    "\n",
    "* Tab inside brackets gives the help of the command;\n",
    "* or using:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from grass import script"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Test the IPython API completition to access GRASS script API, uncomment the line below and press **```tab```** key "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#script."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Access IPython helper function using the **```?```** suffix"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "script?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Replace BASH"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "GRASS6 and GRASS7, the traditional way for scripting."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Import grass script module, which has some useful functions:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from grass import script"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's have a look which function containing the word command are available, with:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from grass.pygrass.utils import looking\n",
    "\n",
    "looking(script, '*command*')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "script.list_pairs(type='rast')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Start and wait until the end of the process"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "script.run_command('r.info', map='elevation')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Parse the kwargs and return a list of parameters"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "script.make_command('r.info', map='elevation', flags='r')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Start and return a `Popen` object"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "script.start_command('r.info', map='elevation')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "process = script.start_command('r.info', map='elevation', flags='r', stdout=PIPE)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "stdout = process.stdout"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print([line.strip().split('=') for line in stdout])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Parse the output of a command"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "script.parse_command('r.info', map='elevation', flags='g', delimiter='=')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "script.parse_command('g.region', flags='p', delimiter=':')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Catch the command output"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "region = script.pipe_command('r.info', map='elevation', flags='r')\n",
    "region"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "stdout = ''.join(line for line in region.stdout)\n",
    "print(stdout)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Catch and return the stdout"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "stdout = script.read_command('r.info', map='elevation', flags='r')\n",
    "print(stdout)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "mrange = dict([line.split('=') for line in stdout.split('\\n') if line != ''])\n",
    "for k in mrange:\n",
    "    mrange[k] = float(mrange[k])\n",
    "mrange"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Use the pipe as input for another command"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Write the rules that we want to use for the reclassification:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "keys = ['low', 'medium low', 'medium', 'medium high', 'high']\n",
    "vals = np.linspace(mrange['min']-1, mrange['max']+1, num=len(keys)+1, endpoint=True)\n",
    "\n",
    "rvals = [(int(vals[i-1])+1, int(vals[i]), i, keys[i-1]) for i in range(1, len(vals))]\n",
    "rules = '\\n'.join(['%3d thru %3d = %2d %s' % v for v in rvals])\n",
    "print(rules)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now we can pass as input for the r.reclass the rules using the function `write_command`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "script.write_command('r.reclass', input='elevation', output='elev_reclass', rules='-', overwrite=True, stdin=rules)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Display the map inside the ipython notebook"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Start a new virtual monitor that generate a file: `view.png` that we can display inside the ipython notebook."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "script.run_command('d.mon', start='png', output='view.png', overwrite=True)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "script.run_command('d.rast', map='elevation')\n",
    "Image('view.png')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "script.run_command('d.rast', map='elev_reclass')\n",
    "Image('view.png')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "script.run_command('d.mon', stop='png')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Summary"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We have seen:\n",
    "\n",
    "* how we can replace Bash script with Python;\n",
    "* how to use some IPython Notebook features with GRASS Python;"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Exercise"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Time for coding!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Transform the following Bash script:"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "#!/bin/bash\n",
    "#\n",
    "# Compute the distance from a road\n",
    "#\n",
    "\n",
    "# set the region to elevation map:\n",
    "g.region rast=elevation\n",
    "\n",
    "# convert street vector to raster\n",
    "v.to.rast input=streets type=line output=streets use=cat --overwrite\n",
    "\n",
    "# create a unitary map of the cost\n",
    "r.mapcalc expression=\"dist_cost=10./cos(slope)\" --overwrite\n",
    "\n",
    "# compute the distance\n",
    "r.cost input=dist_cost output=distance_from_streets outdir=direction start_rast=streets -k --overwrite \n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "into a Python one:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Create a GRASS module using scripting library"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%file mygrassmodule.py\n",
    "#!/usr/bin/env python\n",
    "# -- coding: utf-8 --\n",
    "#\n",
    "############################################################################\n",
    "#\n",
    "# MODULE:\t    <name of your module>\n",
    "#\n",
    "# AUTHOR(S):    <your name>\n",
    "#\n",
    "# COPYRIGHT:\t(C) 2013 by the GRASS Development Team\n",
    "#\n",
    "#\t\tThis program is free software under the GNU General Public\n",
    "#\t\tLicense (>=v2). Read the file COPYING that comes with GRASS\n",
    "#\t\tfor details.\n",
    "#\n",
    "#############################################################################\n",
    "\n",
    "##-----------------------\n",
    "## DESCRIPTION\n",
    "##-----------------------\n",
    "#%Module\n",
    "#%  description: <description>\n",
    "#%  keywords: <keyword 1>\n",
    "#%  keywords: <keyword 1>\n",
    "#%  keywords: <keyword 1>\n",
    "#%  overwrite: yes\n",
    "#%End\n",
    "\n",
    "##-----------------------\n",
    "## VECTOR INPUT\n",
    "##-----------------------\n",
    "#%option G_OPT_V_MAP\n",
    "#%  key: key0\n",
    "#%  description: <parameter description>\n",
    "#%  required: yes\n",
    "#%end\n",
    "\n",
    "##-----------------------\n",
    "## MULTI RASTER INPUT\n",
    "##-----------------------\n",
    "#%option G_OPT_R_INPUTS\n",
    "#%  key: key1\n",
    "#%  description: <parameter description>\n",
    "#%  multiple: yes\n",
    "#%  required: no\n",
    "#%end\n",
    "\n",
    "##-----------------------\n",
    "## STRING INPUT\n",
    "##-----------------------\n",
    "#%option\n",
    "#%  key: key2\n",
    "#%  description: <parameter description>\n",
    "#%  type: string\n",
    "#%  multiple: yes\n",
    "#%  required: no\n",
    "#%end\n",
    "from pprint import pprint\n",
    "from grass.script import parser\n",
    "\n",
    "def main(opts, flgs):\n",
    "    print('OPTIONS:')\n",
    "    pprint(opts)\n",
    "    print('FLAGS:')\n",
    "    pprint(flgs)\n",
    "    #do something with scripting library\n",
    "\n",
    "if __name__ == \"__main__\":\n",
    "    opts, flgs = parser()\n",
    "    main(opts, flgs)\n",
    "\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!python2 mygrassmodule.py --h"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!python2 mygrassmodule.py key0=pippo key1=pluto,topolino key2=minni,clarabella"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 2",
   "language": "python",
   "name": "python2"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 2
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython2",
   "version": "2.7.16"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}