ForEST_Demo2.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# ForEST Demo 2\n",
    "This ForEST demo will walk through a simple raster example using ASCII Grid files. Feel free to check out ForEST Demo 1 for additional tricks using map algebra in ForEST.\n",
    "\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Let's pull ForEST in using import\n",
    "from forest import *"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {},
   "outputs": [],
   "source": [
    "# A choice of Engines again (Multi-Processing, Tile, or the Pass (do nothing) Engine)\n",
    "Config.engine=mp_engine\n",
    "Config.engine=tile_engine\n",
    "Config.engine=pass_engine"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {},
   "outputs": [],
   "source": [
    "# This function will create some raster files in the ASCII Grid format and store them in the unittests folder.\n",
    "\n",
    "def makefiles(nfiles,nrows,ncols):\n",
    "   for f_i in range(nfiles):\n",
    "        f = open(\"unittests/tmp_raster\"+str(f_i)+\".asc\",\"w\")\n",
    "        f.write(\"ncols \"+str(ncols)+\"\\n\")\n",
    "        f.write(\"nrows \"+str(nrows)+\"\\n\")\n",
    "        f.write(\"xllcorner 0.0\\n\")\n",
    "        f.write(\"yllcorner 0.0\\n\")\n",
    "        f.write(\"cellsize 1.0\\n\")\n",
    "        f.write(\"NODATA_value -999\\n\")\n",
    "        \n",
    "        for i in range(nrows):\n",
    "            for j in range(ncols):\n",
    "                f.write(str(i+j+f_i)+\" \")\n",
    "            f.write(\"\\n\")\n",
    "\n",
    "        f.close()\n",
    "\n",
    "# Call the function to make 3 raster files of dimension 6x4 (nice and small for demonstration purposes)\n",
    "makefiles(3,6,4)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Now we will take the file names from each raster file\n",
    "\n",
    "r1_name = \"unittests/tmp_raster0.asc\"\n",
    "r2_name = \"unittests/tmp_raster1.asc\"\n",
    "r3_name = \"unittests/tmp_raster2.asc\"\n",
    "ro_name = \"unittests/tmp_rastero.asc\"\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "load file unittests/tmp_raster0.asc\n",
      "load file unittests/tmp_raster1.asc\n",
      "AsciiGridLoad == (Sequence) AsciiGridLoad\n",
      "Running AsciiGridLoad\n",
      "Open unittests/tmp_raster1.asc\n",
      "4 6 0.0 0.0 1.0 -999.0\n",
      "4.0 4.0\n",
      "bobdata [[1. 2. 3. 4.]\n",
      " [2. 3. 4. 5.]\n",
      " [3. 4. 5. 6.]\n",
      " [4. 5. 6. 7.]\n",
      " [5. 6. 7. 8.]\n",
      " [6. 7. 8. 9.]]\n",
      "PUSH Bob (0.000000,0.000000) [4.000000,6.000000]\n",
      "load file unittests/tmp_raster2.asc\n",
      "AsciiGridLoad == (Sequence) AsciiGridLoad\n",
      "Running AsciiGridLoad\n",
      "Open unittests/tmp_raster2.asc\n",
      "4 6 0.0 0.0 1.0 -999.0\n",
      "4.0 4.0\n",
      "bobdata [[ 2.  3.  4.  5.]\n",
      " [ 3.  4.  5.  6.]\n",
      " [ 4.  5.  6.  7.]\n",
      " [ 5.  6.  7.  8.]\n",
      " [ 6.  7.  8.  9.]\n",
      " [ 7.  8.  9. 10.]]\n",
      "PUSH Bob (0.000000,0.000000) [4.000000,6.000000]\n",
      "AsciiGridLoad == (Sequence) RasterAdd\n",
      "Running AsciiGridLoad\n",
      "Open unittests/tmp_raster2.asc\n",
      "4 6 0.0 0.0 1.0 -999.0\n",
      "4.0 4.0\n",
      "bobdata [[ 2.  3.  4.  5.]\n",
      " [ 3.  4.  5.  6.]\n",
      " [ 4.  5.  6.  7.]\n",
      " [ 5.  6.  7.  8.]\n",
      " [ 6.  7.  8.  9.]\n",
      " [ 7.  8.  9. 10.]]\n",
      "PUSH Bob (0.000000,0.000000) [4.000000,6.000000]\n",
      "RasterAdd == (Sequence) RasterSub\n",
      "Running RasterAdd\n",
      "POP\n",
      "POP\n",
      "PUSH Bob (0.000000,0.000000) [4.000000,6.000000]\n",
      "store file unittests/tmp_rastero.asc\n",
      "RasterSub == (Sequence) AsciiGridStore\n",
      "Running RasterSub\n",
      "POP\n",
      "POP\n",
      "PUSH Bob (0.000000,0.000000) [4.000000,6.000000]\n",
      "Running AsciiGridStore\n",
      "POP\n",
      "Open for writing  unittests/tmp_rastero.asc\n",
      "bobdata [[ 3.  4.  5.  6.]\n",
      " [ 4.  5.  6.  7.]\n",
      " [ 5.  6.  7.  8.]\n",
      " [ 6.  7.  8.  9.]\n",
      " [ 7.  8.  9. 10.]\n",
      " [ 8.  9. 10. 11.]]\n"
     ]
    }
   ],
   "source": [
    "# Now the ForEST magic. # This is a line of code in the ForEST langauge.\n",
    "\n",
    "run_primitive(AGLoad.file(r1_name) == AGLoad.file(r2_name) == AGLoad.file(r3_name) == RasterAdd == RasterSub == AGStore.file(ro_name))\n",
    "\n",
    "# Definitions:\n",
    "# run_primitive: This will execute the Primitives in the Pattern\n",
    "# AGLoad: This will read in (load) an Ascii Grid (AG) file\n",
    "# RasterAdd: This will add two raster datasets\n",
    "# RasterSub: This will subtract two raster datasets\n",
    "# AGStore: This will write out (store) an Ascii Grid (AG) file\n",
    "# ==: This is called a 'Sequence' it means keep going or \"next instruction\"\n",
    "\n",
    "# Pattern explanation\n",
    "# The first three primitives (AGLoad) will push the 3 raster datasets onto the data stack\n",
    "# RasterAdd: pop off the top two (r2, r3), add them together, and push the output to the stack\n",
    "# RasterSub: pop off the top two (r1, RasterAdd output), subtract them, and push the output to the stack\n",
    "# AGStore:   pop off the remaining raster and write it to unittests/tmp_rastero.asc\n",
    "\n",
    "# This style of programming is called postfix notation (or Reverse Polish Notation)\n",
    "# This was all the rage when pocket protectors and hand-held Hewlett-Packard calculators were hip\n",
    "# It is also a very powerful way to program Stack Machines, which is the computational model for ForEST\n",
    "# Postfix notation translates A + B to A B +\n",
    "# Notice the AGLoads (e.g., A, B) happen before the operations (e.g., RasterAdd, RasterSub) in our example\n",
    "\n",
    "# This line of ForEST is the same as the following lines of pseudo code\n",
    "# r1 = AsciiGridRead(r1_name)\n",
    "# r2 = AsciiGridRead(r2_name)\n",
    "# r3 = AsciiGridRead(r3_name)\n",
    "\n",
    "# ri = RasterAdd(r2, r3)\n",
    "# ro = RasterSub(ro, r1)\n",
    "# AsciiGridWrite(ro, ro_name)\n",
    "\n",
    "# While it looks a little funny at first\n",
    "# It is a very simple and very powerful system to enable scalable spatial-temporal computation.\n",
    "# If you want to learn more, then look at our paper in the Proceedings of GeoComputation 2019.\n",
    "# https://auckland.figshare.com/articles/Space-Time_is_the_Key_For_Expressing_Spatial-Temporal_Computing/9870416"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "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.5.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}