Merge pull request #88 from ioam/geopandas_interface

Added GeoPandas data interface

.travis.yml

@@ -23,7 +23,7 @@ install:
   - source activate test-environment
   - pip install coveralls
   - pip install git+https://github.com/ioam/holoviews.git
-  - conda install -c conda-forge iris cartopy xarray
+  - conda install -c conda-forge iris cartopy xarray geopandas numpy=1.13.3
   - python setup.py install
 
 script:

doc/Geometries.ipynb

@@ -3,9 +3,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {
-    "collapsed": false
-   },
+   "metadata": {},
    "outputs": [],
    "source": [
     "import pandas as pd\n",
@@ -16,8 +14,10 @@
     "import cartopy\n",
     "import cartopy.feature as cf\n",
     "from cartopy import crs as ccrs\n",
-    "hv.notebook_extension()\n",
-    "%output dpi=120"
+    "\n",
+    "hv.extension('matplotlib', 'bokeh')\n",
+    "\n",
+    "%output dpi=120 fig='svg'"
    ]
   },
   {
@@ -34,9 +34,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {
-    "collapsed": false
-   },
+   "metadata": {},
    "outputs": [],
    "source": [
     "(gf.ocean + gf.land + gf.ocean * gf.land * gf.coastline * gf.borders).cols(3)"
@@ -52,9 +50,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {
-    "collapsed": false
-   },
+   "metadata": {},
    "outputs": [],
    "source": [
     "%%opts Feature.Lines [projection=ccrs.Robinson()] (facecolor='none' edgecolor='gray')\n",
@@ -77,9 +73,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {
-    "collapsed": false
-   },
+   "metadata": {},
    "outputs": [],
    "source": [
     "land_geoms = list(gf.land.data.geometries())\n",
@@ -96,9 +90,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {
-    "collapsed": false
-   },
+   "metadata": {},
    "outputs": [],
    "source": [
     "%%opts Points (color=\"black\")\n",
@@ -117,9 +109,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {
-    "collapsed": false
-   },
+   "metadata": {},
    "outputs": [],
    "source": [
     "%%opts NdOverlay [aspect=2]\n",
@@ -136,9 +126,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {
-    "collapsed": false
-   },
+   "metadata": {},
    "outputs": [],
    "source": [
     "shapefile = './assets/boundaries/boundaries.shp'\n",
@@ -155,9 +143,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {
-    "collapsed": false
-   },
+   "metadata": {},
    "outputs": [],
    "source": [
     "shapes = cartopy.io.shapereader.Reader(shapefile)\n",
@@ -174,9 +160,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {
-    "collapsed": false
-   },
+   "metadata": {},
    "outputs": [],
    "source": [
     "referendum = pd.read_csv('./assets/referendum.csv')\n",
@@ -194,16 +178,76 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {
-    "collapsed": false
-   },
+   "metadata": {},
    "outputs": [],
    "source": [
+    "%%output backend='bokeh'\n",
     "%%opts Shape (cmap='viridis')\n",
     "gv.Shape.from_records(shapes.records(), referendum, on='code', value='leaveVoteshare',\n",
     "                     index=['name', 'regionName'], crs=ccrs.PlateCarree())"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## GeoPandas"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "GeoPandas extends the datatypes used by pandas to allow spatial operations on geometric types, which makes it a very convenient way of working with geometries with associated variables. GeoViews ``Path``, ``Contours`` and ``Polygons`` Elements natively support projecting and plotting of\n",
+    "geopandas DataFrames using both ``matplotlib`` and ``bokeh`` plotting extensions. We will load the example dataset of the world which also includes some additional data about each country:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import geopandas as gpd\n",
+    "world = gpd.read_file(gpd.datasets.get_path('naturalearth_lowres'))\n",
+    "world.head()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "We can simply pass the GeoPandas DataFrame to a Polygons, Path or Contours element and it will plot the data for us. The ``Contours`` and ``Polygons`` will automatically color the data by the first specified value dimension defined by the ``vdims`` keyword (the geometries may be colored by any dimension using the ``color_index`` plot option):"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "%%opts Polygons [projection=ccrs.Robinson() fig_size=250]\n",
+    "gv.Polygons(world, vdims='pop_est')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Geometries can be displayed using both matplotlib and bokeh, here we will switch to bokeh allowing us to color by a categorical variable (``continent``) and activating the hover tool to reveal information about the plot."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "%%output backend='bokeh'\n",
+    "%%opts Polygons [width=600 height=500 tools=['hover']] (cmap='tab20')\n",
+    "gv.Polygons(world, vdims=['continent',  'name', 'pop_est']).redim.range(Latitude=(-60, 90))"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -215,27 +259,27 @@
  "metadata": {
   "hide_input": false,
   "kernelspec": {
-   "display_name": "Python 2",
+   "display_name": "Python 3",
    "language": "python",
-   "name": "python2"
+   "name": "python3"
   },
   "language_info": {
    "codemirror_mode": {
     "name": "ipython",
-    "version": 2
+    "version": 3
    },
    "file_extension": ".py",
    "mimetype": "text/x-python",
    "name": "python",
    "nbconvert_exporter": "python",
-   "pygments_lexer": "ipython2",
-   "version": "2.7.11"
+   "pygments_lexer": "ipython3",
+   "version": "3.6.2"
   },
   "widgets": {
    "state": {},
    "version": "1.1.2"
   }
  },
  "nbformat": 4,
- "nbformat_minor": 0
+ "nbformat_minor": 1
 }

geoviews/__init__.py

@@ -8,7 +8,9 @@
 
 from .element import (_Element, Feature, Tiles,     # noqa (API import)
                       WMTS, LineContours, FilledContours, Text, Image,
-                      Points, Path, Polygons, Shape, Dataset, RGB)
+                      Points, Path, Polygons, Shape, Dataset, RGB,
+                      Contours)
+from . import data                                  # noqa (API import)
 from . import operation                             # noqa (API import)
 from . import plotting                              # noqa (API import)
 from . import feature                               # noqa (API import)

geoviews/data/__init__.py

@@ -0,0 +1,12 @@
+from __future__ import absolute_import
+
+import param
+
+try:
+    from . import geopandas # noqa (API import)
+except ImportError:
+    pass
+except Exception as e:
+    param.main.warning('GeoPandas interface failed to import with '
+                       'following error: %s' % e)
+