{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* [Main Page](https://oneadder.github.io/lingtypology/)\n",
    "* [Glottolog](https://oneadder.github.io/lingtypology/glottolog)\n",
    "* [DB APIs](https://oneadder.github.io/lingtypology/db_apis)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Maps <a name=\"up\"></a>\n",
    "\n",
    "It is possible to draw interactive linguistic maps using `lingtypology`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "import lingtypology"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 0. Table of Contents\n",
    "### 1. [Maps](#maps)\n",
    "#### 1.1. [Simplest example](#simplest_example)  \n",
    "#### 1.2. [Save, Render or Save as an image](#save)\n",
    "#### 1.3. [Features](#features)\n",
    "#### 1.4. [Map Customization](#map_cust)\n",
    "#### 1.5. [Popups](#popups)\n",
    "#### 1.6. [Accessing Glottolog](#access_glot)\n",
    "#### 1.7. [Customizing Features and Controls](#feat_cont)\n",
    "#### 1.8. [Stroke Features](#s_features)\n",
    "#### 1.9. [Heatmaps](#heatmaps)\n",
    "#### 1.10. [Title](#title_)\n",
    "#### 1.11. [Lines](#lines)\n",
    "#### 1.12. [Customizing markers](#markers)\n",
    "#### 1.13. [Start Location/Zoom shortcuts](#shortcuts)\n",
    "#### 1.14. [Color Gradients](#gradients)\n",
    "#### 1.15. [Minicharts](#minicharts)\n",
    "#### 1.16. [Overlapping Features](#overlapping)\n",
    "#### 1.17. [Using Existing folium.Map](#folium)\n",
    "#### 1.18. [Merging Maps](#merge)\n",
    "#### 1.19. [Tiles](#tiles)\n",
    "#### 1.20. [Elevation](#elevation)\n",
    "### 2. [Real examples](#real_examples)\n",
    "#### 2.1. [Circassian Example](#example1)\n",
    "#### 2.2. [Consonants Example](#example3)\n",
    "\n",
    "\n",
    "## 1. Maps <a name=\"maps\"></a>\n",
    "In this paragraph I will consider some basic features that you can use.\n",
    "\n",
    "### 1.1. Simplest example <a name=\"simplest_example\"></a>\n",
    "\n",
    "The simplest script that draws a map with Romanian and Ukrainian languages will be:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div style=\"width:100%;\"><div style=\"position:relative;width:100%;height:0;padding-bottom:60%;\"><iframe src=\"data:text/html;charset=utf-8;base64,[encoded data, 13168 characters]\" style=\"position:absolute;width:100%;height:100%;left:0;top:0;border:none !important;\" allowfullscreen webkitallowfullscreen mozallowfullscreen></iframe></div></div>"
      ],
      "text/plain": [
       "<folium.folium.Map at 0x7f30729379e8>"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "m = lingtypology.LingMap(('Romanian', 'Afrikaans', 'Tlingit', 'Japanese'))\n",
    "m.create_map()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you have Glottocodes rather then language names, you can pass them as well (you need to set `glottocode` to `True`)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div style=\"width:100%;\"><div style=\"position:relative;width:100%;height:0;padding-bottom:60%;\"><iframe src=\"data:text/html;charset=utf-8;base64,[encoded data, 13152 characters]\" style=\"position:absolute;width:100%;height:100%;left:0;top:0;border:none !important;\" allowfullscreen webkitallowfullscreen mozallowfullscreen></iframe></div></div>"
      ],
      "text/plain": [
       "<folium.folium.Map at 0x7f3074245a20>"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "m = lingtypology.LingMap(('russ1263', 'afri1274', 'tlin1245', 'nucl1643'), glottocode=True)\n",
    "m.create_map()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 1.2. Save, Render or Save as Image <a name=\"save\"></a>\n",
    "Be advised that `create_map()` returns a `Folium` map. In this notebook it is used because the map may\n",
    "be displayed this way.\n",
    "\n",
    "To save your map as html run: `m.save('map.html')`\n",
    "\n",
    "To get html as `str` run: `m.render()`  \n",
    "\n",
    "To get a `png` image run `m.save_static(fname=fname)` (if no arguments are given it will be returned as `bytes`).  \n",
    "`geckodriver` should be installed.  \n",
    "**Note:** `save_static` is an experimental method."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`m.save_static()`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img src=https://raw.githubusercontent.com/OneAdder/lingtypology/master/data_processing/map.png></img>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 1.3. Features <a name=\"features\"></a>\n",
    "Simply drawing languages on a map is not very interesting. Let's say that we want to mark some morphological features as different colors."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div style=\"width:100%;\"><div style=\"position:relative;width:100%;height:0;padding-bottom:60%;\"><iframe src=\"data:text/html;charset=utf-8;base64,[encoded data, 18460 characters]\" style=\"position:absolute;width:100%;height:100%;left:0;top:0;border:none !important;\" allowfullscreen webkitallowfullscreen mozallowfullscreen></iframe></div></div>"
      ],
      "text/plain": [
       "<folium.folium.Map at 0x7f30742459b0>"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "languages = [\"Adyghe\", \"Kabardian\", \"Polish\", \"Russian\", \"Bulgarian\"]\n",
    "features = [\"Agglutinative\", \"Agglutinative\", \"Inflected\", \"Inflected\", \"Analytic\"]\n",
    "m = lingtypology.LingMap(languages)\n",
    "m.add_features(features)\n",
    "m.create_map()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 1.4. Customizing the map <a name=\"map_cust\"></a>\n",
    "As you can see, the map is not centered properly. It can be fixed with passing coordinates to the `start_location` attribute. You can change start zoom as well `start_zoom`.\n",
    "Also, you can change colors using the `colors` parameter."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div style=\"width:100%;\"><div style=\"position:relative;width:100%;height:0;padding-bottom:60%;\"><iframe src=\"data:text/html;charset=utf-8;base64,[encoded data, 18464 characters]\" style=\"position:absolute;width:100%;height:100%;left:0;top:0;border:none !important;\" allowfullscreen webkitallowfullscreen mozallowfullscreen></iframe></div></div>"
      ],
      "text/plain": [
       "<folium.folium.Map at 0x7f3072937828>"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "m.start_location = (40, 40)\n",
    "m.start_zoom = 3\n",
    "m.add_features(features, colors=(\"#00FFFF\", \"#FF00FF\", \"#FFFF00\"))\n",
    "m.create_map()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 1.5. Popups <a name=\"popups\"></a>\n",
    "You can add popups using `add_popups` method.\n",
    "You can disable links to Glottolog by setting `glottolog_links` parameter to `False`.  \n",
    "Basically, you can set any html-code in the popups."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div style=\"width:100%;\"><div style=\"position:relative;width:100%;height:0;padding-bottom:60%;\"><iframe src=\"data:text/html;charset=utf-8;base64,[encoded data, 18256 characters]\" style=\"position:absolute;width:100%;height:100%;left:0;top:0;border:none !important;\" allowfullscreen webkitallowfullscreen mozallowfullscreen></iframe></div></div>"
      ],
      "text/plain": [
       "<folium.folium.Map at 0x7f30742199b0>"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "contents = ('Caucasus', 'Caucasus', 'Europe', 'Europe', 'Europe')\n",
    "html = '''\n",
    "<a href=\"https://en.wikipedia.org/wiki/{data}\" target=\"_blank\">\n",
    "{data}\n",
    "</a>\n",
    "'''\n",
    "m.add_popups([html.format(data=popup) for popup in contents], glottolog_links=False)\n",
    "m.languages_in_popups = False\n",
    "m.create_map()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 1.6. Accessing Glottolog <a name=\"access_glot\"></a>\n",
    "\n",
    "You can also use `lingtypology.glottolog` to get some data from it. For example, I want to add language affiliations to popups.  \n",
    "See more details [here](https://oneadder.github.io/lingtypology/glottolog)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "scrolled": false
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div style=\"width:100%;\"><div style=\"position:relative;width:100%;height:0;padding-bottom:60%;\"><iframe src=\"data:text/html;charset=utf-8;base64,[encoded data, 18788 characters]\" style=\"position:absolute;width:100%;height:100%;left:0;top:0;border:none !important;\" allowfullscreen webkitallowfullscreen mozallowfullscreen></iframe></div></div>"
      ],
      "text/plain": [
       "<folium.folium.Map at 0x7f3074262710>"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "affs = lingtypology.glottolog.get_affiliations(languages)\n",
    "m.add_popups(affs)\n",
    "m.create_map()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 1.7. Customizing features and controls <a name=\"feat_cont\"></a>\n",
    "\n",
    "You can pass additional parameters to the `add_features` method.  \n",
    "If for some reason you do not wish to use colors, you could use shapes.  \n",
    "If you want to add controls, you can do it as well."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div style=\"width:100%;\"><div style=\"position:relative;width:100%;height:0;padding-bottom:60%;\"><iframe src=\"data:text/html;charset=utf-8;base64,[encoded data, 17312 characters]\" style=\"position:absolute;width:100%;height:100%;left:0;top:0;border:none !important;\" allowfullscreen webkitallowfullscreen mozallowfullscreen></iframe></div></div>"
      ],
      "text/plain": [
       "<folium.folium.Map at 0x7f3074175320>"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "m.add_features(features, use_shapes=True, control=True)\n",
    "m.create_map()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 1.8. Stroke features <a name=\"s_features\"></a>\n",
    "\n",
    "It is possible to add another set of features to strokes of markers using `add_stroke_features` method."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div style=\"width:100%;\"><div style=\"position:relative;width:100%;height:0;padding-bottom:60%;\"><iframe src=\"data:text/html;charset=utf-8;base64,[encoded data, 28572 characters]\" style=\"position:absolute;width:100%;height:100%;left:0;top:0;border:none !important;\" allowfullscreen webkitallowfullscreen mozallowfullscreen></iframe></div></div>"
      ],
      "text/plain": [
       "<folium.folium.Map at 0x7f3074262048>"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "stroke_features = ['Ergative', 'Ergative', 'Accusative', 'Accusative', 'Accusative']\n",
    "m = lingtypology.LingMap(languages)\n",
    "m.add_features(features)\n",
    "m.add_stroke_features(stroke_features)\n",
    "m.create_map()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 1.9. Heatmaps <a name=\"heatmaps\"></a>\n",
    "It would seem unfair if we could only draw circles.  \n",
    "Let's draw a heatmap (the more density, the more languages with Large consonant inventory) using `add_heatmap` method.  \n",
    "It is from Wals. For more information consult [this](https://oneadder.github.io/lingtypology/db_apis)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Citation for feature 1A:\n",
      "Ian Maddieson. 2013. Consonant Inventories.\n",
      "In: Dryer, Matthew S. & Haspelmath, Martin (eds.)\n",
      "The World Atlas of Language Structures Online.\n",
      "Leipzig: Max Planck Institute for Evolutionary Anthropology.\n",
      "(Available online at http://wals.info/chapter/1, Accessed on 2019-06-12.)\n",
      "\n"
     ]
    },
    {
     "data": {
      "text/html": [
       "<div style=\"width:100%;\"><div style=\"position:relative;width:100%;height:0;padding-bottom:60%;\"><iframe src=\"data:text/html;charset=utf-8;base64,[encoded data, 5876 characters]\" style=\"position:absolute;width:100%;height:100%;left:0;top:0;border:none !important;\" allowfullscreen webkitallowfullscreen mozallowfullscreen></iframe></div></div>"
      ],
      "text/plain": [
       "<folium.folium.Map at 0x7f3074170160>"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from lingtypology.datasets import Wals\n",
    "wals_page = Wals('1a').get_df()\n",
    "\n",
    "#First initialize LingMap without languages\n",
    "m = lingtypology.LingMap()\n",
    "#Add heatmap from  the Wals data\n",
    "m.add_heatmap(wals_page[wals_page._1A_desc == 'Large'].coordinates)\n",
    "m.create_map()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 1.10. Title <a name=\"title_\"></a>\n",
    "To add title, use `title` attribute."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div style=\"width:100%;\"><div style=\"position:relative;width:100%;height:0;padding-bottom:60%;\"><iframe src=\"data:text/html;charset=utf-8;base64,[encoded data, 8408 characters]\" style=\"position:absolute;width:100%;height:100%;left:0;top:0;border:none !important;\" allowfullscreen webkitallowfullscreen mozallowfullscreen></iframe></div></div>"
      ],
      "text/plain": [
       "<folium.folium.Map at 0x7f3074196208>"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "m.title = 'Large Consonant Inventories'\n",
    "m.create_map()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 1.11. Lines <a name=\"lines\"></a>\n",
    "\n",
    "Let's say we have this list of languages:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [],
   "source": [
    "balkan = ['Modern Greek', 'Romanian', 'Bulgarian', 'Macedonian', 'Gheg Albanian']\n",
    "other = ['Ukrainian', 'Turkish', 'Italian']\n",
    "languages_all = balkan + other"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We want the ones from Balkan sprachbund connected with lines with a popup that says 'Balkan'. It is possible using `add_line` method."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div style=\"width:100%;\"><div style=\"position:relative;width:100%;height:0;padding-bottom:60%;\"><iframe src=\"data:text/html;charset=utf-8;base64,[encoded data, 24328 characters]\" style=\"position:absolute;width:100%;height:100%;left:0;top:0;border:none !important;\" allowfullscreen webkitallowfullscreen mozallowfullscreen></iframe></div></div>"
      ],
      "text/plain": [
       "<folium.folium.Map at 0x7f3074139ac8>"
      ]
     },
     "execution_count": 13,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "#Let's get the coordinates that we need to draw a line\n",
    "coordinates = map(lingtypology.glottolog.get_coordinates, balkan)\n",
    "m = lingtypology.LingMap(languages_all)\n",
    "m.add_line(coordinates, popup='Balkan')\n",
    "m.start_location = (43, 27)\n",
    "m.start_zoom = 5\n",
    "m.create_map()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 1.12. Customizing markers <a name=\"markers\"></a>\n",
    "It is possible to set opacity and width of markers."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div style=\"width:100%;\"><div style=\"position:relative;width:100%;height:0;padding-bottom:60%;\"><iframe src=\"data:text/html;charset=utf-8;base64,[encoded data, 28624 characters]\" style=\"position:absolute;width:100%;height:100%;left:0;top:0;border:none !important;\" allowfullscreen webkitallowfullscreen mozallowfullscreen></iframe></div></div>"
      ],
      "text/plain": [
       "<folium.folium.Map at 0x7f3073e3e860>"
      ]
     },
     "execution_count": 14,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "m = lingtypology.LingMap(languages)\n",
    "m.add_features(features, radius=7, opacity=0.9)\n",
    "m.add_stroke_features(stroke_features, opacity=0.7)\n",
    "m.create_map()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 1.13. Start Location/Zoom shortcuts <a name=\"shortcuts\"></a>\n",
    "There are some shortcuts that can allow not to choose `start_location` and `start_zoom` manually."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div style=\"width:100%;\"><div style=\"position:relative;width:100%;height:0;padding-bottom:60%;\"><iframe src=\"data:text/html;charset=utf-8;base64,[encoded data, 27264 characters]\" style=\"position:absolute;width:100%;height:100%;left:0;top:0;border:none !important;\" allowfullscreen webkitallowfullscreen mozallowfullscreen></iframe></div></div>"
      ],
      "text/plain": [
       "<folium.folium.Map at 0x7f3073e3e7f0>"
      ]
     },
     "execution_count": 15,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "m = lingtypology.LingMap([\n",
    "    'Irish', 'Estonian', 'Norwegian', 'Romanian', 'Polish',\n",
    "    'Italian', 'Turkish', 'French', 'English', 'Spanish'\n",
    "])\n",
    "m.start_location = 'Central Europe'\n",
    "m.create_map()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Full list of shortcuts:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'Central Europe': {'start_location': (50, 0), 'start_zoom': 4},\n",
       " 'Caucasus': {'start_location': (43, 42), 'start_zoom': 6},\n",
       " 'Australia & Oceania': {'start_location': (-16, 159), 'start_zoom': 3},\n",
       " 'Papua New Guinea': {'start_location': (-5, 141), 'start_zoom': 6},\n",
       " 'Africa': {'start_location': (3, 22), 'start_zoom': 3},\n",
       " 'Asia': {'start_location': (36, 100), 'start_zoom': 3},\n",
       " 'North America': {'start_location': (51, -102), 'start_zoom': 3},\n",
       " 'Central America': {'start_location': (19, -81), 'start_zoom': 4},\n",
       " 'South America': {'start_location': (-27, -49), 'start_zoom': 3}}"
      ]
     },
     "execution_count": 16,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "m.start_location_mapping"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 1.14. Color gradients <a name=\"gradients\"></a>\n",
    "There are two ways to use color gradients.\n",
    "Let's say we have features called \"Millions of native speakers\"."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [],
   "source": [
    "native_speakers = [0, 1, 5, 24, 44, 62, 78, 78, 378, 442]\n",
    "m.legend_title = 'Native speakers (mln)'\n",
    "m.legend_position = 'topright'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The first way is simply pass the features as `numeric`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div style=\"width:100%;\"><div style=\"position:relative;width:100%;height:0;padding-bottom:60%;\"><iframe src=\"data:text/html;charset=utf-8;base64,[encoded data, 47448 characters]\" style=\"position:absolute;width:100%;height:100%;left:0;top:0;border:none !important;\" allowfullscreen webkitallowfullscreen mozallowfullscreen></iframe></div></div>"
      ],
      "text/plain": [
       "<folium.folium.Map at 0x7f3074262cf8>"
      ]
     },
     "execution_count": 18,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "m.add_features(native_speakers, numeric=True)\n",
    "m.colormap_colors = ('white', 'red')\n",
    "m.create_map()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Or you can simply set attribute `color` to a gradient using `gradient` function."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div style=\"width:100%;\"><div style=\"position:relative;width:100%;height:0;padding-bottom:60%;\"><iframe src=\"data:text/html;charset=utf-8;base64,[encoded data, 30684 characters]\" style=\"position:absolute;width:100%;height:100%;left:0;top:0;border:none !important;\" allowfullscreen webkitallowfullscreen mozallowfullscreen></iframe></div></div>"
      ],
      "text/plain": [
       "<folium.folium.Map at 0x7f3073dcc908>"
      ]
     },
     "execution_count": 19,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "m.add_features(native_speakers, colors=lingtypology.gradient(10, 'white', 'red'))\n",
    "m.create_map()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 1.15. Minicharts <a name=\"minicharts\"></a>\n",
    "You can add minicharts to the map using `add_minicharts` method. Just pass all the data.\n",
    "\n",
    "Note, that if you are passing data as anything except for `pandas.Series` you should specify `names`\n",
    "parameter (e.g. `names=('consonants', 'vowels')`)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {},
   "outputs": [],
   "source": [
    "import pandas\n",
    "data = pandas.read_csv(\n",
    "    'https://raw.githubusercontent.com/ropensci/lingtypology/master/database_creation/ejective_and_n_consonants.csv',\n",
    "    delimiter=',',\n",
    "    header=0,\n",
    ")\n",
    "data = data[data.language != 'Paraguayan Guarani']"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div style=\"width:100%;\"><div style=\"position:relative;width:100%;height:0;padding-bottom:60%;\"><iframe src=\"data:text/html;charset=utf-8;base64,[encoded data, 81600 characters]\" style=\"position:absolute;width:100%;height:100%;left:0;top:0;border:none !important;\" allowfullscreen webkitallowfullscreen mozallowfullscreen></iframe></div></div>"
      ],
      "text/plain": [
       "<folium.folium.Map at 0x7f3073e6f5f8>"
      ]
     },
     "execution_count": 21,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "m = lingtypology.LingMap(data.language)\n",
    "m.add_minicharts(data.consonants, data.vowels)\n",
    "m.create_map()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It is possible to customize them using these parameters:\n",
    "1. `colors`  \n",
    "    Colors for your features. If not given, default colors (`LingMap().colors`) will be used.  \n",
    "    \n",
    "2. `size`  \n",
    "    Size of the chart. Please, bear in mind that they should be small. Default: `0.6`.\n",
    "3. `startangle`  \n",
    "    Start angle. Default `90`. Pie-chart only.\n",
    "4. `labels`  \n",
    "    Show values inside the chart. Pie-chart only.\n",
    "5. `textprops`  \n",
    "    Set text properties (`matplotlib` format). Default: `None`. E.g.: `textprops={'color': 'red'}`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div style=\"width:100%;\"><div style=\"position:relative;width:100%;height:0;padding-bottom:60%;\"><iframe src=\"data:text/html;charset=utf-8;base64,[encoded data, 135684 characters]\" style=\"position:absolute;width:100%;height:100%;left:0;top:0;border:none !important;\" allowfullscreen webkitallowfullscreen mozallowfullscreen></iframe></div></div>"
      ],
      "text/plain": [
       "<folium.folium.Map at 0x7f3073d8e4a8>"
      ]
     },
     "execution_count": 22,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "m = lingtypology.LingMap(data.language)\n",
    "m.add_minicharts(\n",
    "    data.consonants, data.vowels,\n",
    "    colors = ('#0020c2', '#c22000'),\n",
    "    size = 0.8,\n",
    "    startangle = 45,\n",
    "    labels = True,\n",
    "    textprops = {'color': 'white'}\n",
    ")\n",
    "m.create_map()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can also use **bar** charts."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div style=\"width:100%;\"><div style=\"position:relative;width:100%;height:0;padding-bottom:60%;\"><iframe src=\"data:text/html;charset=utf-8;base64,[encoded data, 61088 characters]\" style=\"position:absolute;width:100%;height:100%;left:0;top:0;border:none !important;\" allowfullscreen webkitallowfullscreen mozallowfullscreen></iframe></div></div>"
      ],
      "text/plain": [
       "<folium.folium.Map at 0x7f3073323b38>"
      ]
     },
     "execution_count": 23,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "m = lingtypology.LingMap(data.language)\n",
    "m.add_minicharts(\n",
    "    data.consonants, data.vowels,\n",
    "    typ = 'bar',\n",
    "    colors = ('blue', 'red'),\n",
    "    size = 0.4\n",
    ")\n",
    "m.create_map()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 1.16. Overlapping Features <a name=\"overlapping\"></a>\n",
    "Let's say we want to see info about whether language:\n",
    "1. is ergative;\n",
    "2. has cases;\n",
    "3. is slavic.\n",
    "\n",
    "It is possible with `add_overlapping_features` method. It allows to draw several markers of different radius and color for each given language."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div style=\"width:100%;\"><div style=\"position:relative;width:100%;height:0;padding-bottom:60%;\"><iframe src=\"data:text/html;charset=utf-8;base64,[encoded data, 14472 characters]\" style=\"position:absolute;width:100%;height:100%;left:0;top:0;border:none !important;\" allowfullscreen webkitallowfullscreen mozallowfullscreen></iframe></div></div>"
      ],
      "text/plain": [
       "<folium.folium.Map at 0x7f3073c18c50>"
      ]
     },
     "execution_count": 24,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "languages = ('Tsakhur', 'Russian', 'Bulgarian')\n",
    "m = lingtypology.LingMap(languages)\n",
    "m.add_overlapping_features([\n",
    "    ['ergative', 'has cases'],\n",
    "    ['has cases', 'slavic'],\n",
    "    ['slavic']\n",
    "])\n",
    "m.create_map()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can use these parameters:\n",
    "1. `radius`\n",
    "    Default radius. Default: 7.\n",
    "2. `radius_increment`\n",
    "    Radius increment. By how much the size of the marker increases with each additional feature. Default: 4.\n",
    "3. `mapping`\n",
    "    If you want to use custom colors, use this parameter. If it is not given, the default color will be used."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div style=\"width:100%;\"><div style=\"position:relative;width:100%;height:0;padding-bottom:60%;\"><iframe src=\"data:text/html;charset=utf-8;base64,[encoded data, 14476 characters]\" style=\"position:absolute;width:100%;height:100%;left:0;top:0;border:none !important;\" allowfullscreen webkitallowfullscreen mozallowfullscreen></iframe></div></div>"
      ],
      "text/plain": [
       "<folium.folium.Map at 0x7f3073cd7588>"
      ]
     },
     "execution_count": 25,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "m.add_overlapping_features(\n",
    "    [\n",
    "        ['ergative', 'has cases'],\n",
    "        ['has cases', 'slavic'],\n",
    "        ['slavic']\n",
    "    ],\n",
    "    radius = 10,\n",
    "    radius_increment = 5,\n",
    "    mapping = {\n",
    "        'ergative': '#e6194b',\n",
    "        'has cases': '#4be619',\n",
    "        'slavic': '#194be6'\n",
    "    }\n",
    ")\n",
    "m.create_map()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 1.17. Using Existing Folium Map <a name=\"folium\"></a>\n",
    "If you already have a `folium.Map` that you want to edit using `lingtypology`, you can pass it as `base_map` attribute."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div style=\"width:100%;\"><div style=\"position:relative;width:100%;height:0;padding-bottom:60%;\"><iframe src=\"data:text/html;charset=utf-8;base64,[encoded data, 9320 characters]\" style=\"position:absolute;width:100%;height:100%;left:0;top:0;border:none !important;\" allowfullscreen webkitallowfullscreen mozallowfullscreen></iframe></div></div>"
      ],
      "text/plain": [
       "<folium.folium.Map at 0x7f3073d471d0>"
      ]
     },
     "execution_count": 26,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "import folium\n",
    "folium_map = folium.Map((0, 0), zoom_start=2)\n",
    "marker = folium.Marker((0, 0))\n",
    "icon = folium.DivIcon(\n",
    "    html='<img src=\"https://raw.githubusercontent.com/OneAdder' + \\\n",
    "    '/lingtypology/master/data_processing/waifu6060.jpg\"></img>'\n",
    ")\n",
    "marker.add_child(icon)\n",
    "folium_map.add_child(marker)\n",
    "\n",
    "m = lingtypology.LingMap(('Russian', 'Afrikaans'))\n",
    "m.base_map = folium_map\n",
    "m.create_map()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 1.18. Merging Maps <a name=\"merge\"></a>\n",
    "You can also draw two `lingtypology` maps the way it is described in [1.16](#folium). However, it is not recommended and may cause glitches.\n",
    "\n",
    "You can use `lingtypology.merge`. Let's merge examples from [1.12](#gradients) and [1.13](#minicharts)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 27,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div style=\"width:100%;\"><div style=\"position:relative;width:100%;height:0;padding-bottom:60%;\"><iframe src=\"data:text/html;charset=utf-8;base64,[encoded data, 125476 characters]\" style=\"position:absolute;width:100%;height:100%;left:0;top:0;border:none !important;\" allowfullscreen webkitallowfullscreen mozallowfullscreen></iframe></div></div>"
      ],
      "text/plain": [
       "<folium.folium.Map at 0x7f30732bbe48>"
      ]
     },
     "execution_count": 27,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "m1 = lingtypology.LingMap([\n",
    "    'Irish', 'Estonian', 'Norwegian', 'Romanian', 'Polish',\n",
    "    'Italian', 'Turkish', 'French', 'English', 'Spanish'\n",
    "])\n",
    "m1.add_features(native_speakers, numeric=True)\n",
    "m1.colormap_colors = ('white', 'red')\n",
    "m1.legend_title = 'Native Speakers'\n",
    "m1.legend_position = 'bottomleft'\n",
    "\n",
    "m2 = lingtypology.LingMap(data.language)\n",
    "m2.legend_title = 'Consonants/Vowels'\n",
    "m2.add_minicharts(data.consonants, data.vowels)\n",
    "\n",
    "m = lingtypology.merge(m1, m2)\n",
    "m.create_map()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 1.19. Using Different Tiles <a name=\"tiles\"></a>\n",
    "You can change tiles using `tiles` attribute. Let's use `Stamen Terrain`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div style=\"width:100%;\"><div style=\"position:relative;width:100%;height:0;padding-bottom:60%;\"><iframe src=\"data:text/html;charset=utf-8;base64,[encoded data, 81104 characters]\" style=\"position:absolute;width:100%;height:100%;left:0;top:0;border:none !important;\" allowfullscreen webkitallowfullscreen mozallowfullscreen></iframe></div></div>"
      ],
      "text/plain": [
       "<folium.folium.Map at 0x7f30732552e8>"
      ]
     },
     "execution_count": 28,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "m2 = lingtypology.LingMap(data.language)\n",
    "m2.tiles = 'Stamen Terrain'\n",
    "m2.legend_title = 'Consonants/Vowels'\n",
    "m2.add_minicharts(data.consonants, data.vowels, colors=('black', 'white'))\n",
    "m2.create_map()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 1.20. Using Elevation Data <a name=\"elevation\"></a>\n",
    "`lingtypology` package contains data on elevation (raw data taken from [here](http://srtm.csi.cgiar.org/)) for each language from Glottolog.  \n",
    "You can get elevation for any language using `lingtypology.get_elevations` function."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 29,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div style=\"width:100%;\"><div style=\"position:relative;width:100%;height:0;padding-bottom:60%;\"><iframe src=\"data:text/html;charset=utf-8;base64,[encoded data, 70540 characters]\" style=\"position:absolute;width:100%;height:100%;left:0;top:0;border:none !important;\" allowfullscreen webkitallowfullscreen mozallowfullscreen></iframe></div></div>"
      ],
      "text/plain": [
       "<folium.folium.Map at 0x7f3073249278>"
      ]
     },
     "execution_count": 29,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "m = lingtypology.LingMap(data.language)\n",
    "data['elevation'] = lingtypology.get_elevations(data.language)\n",
    "m.add_features(data.elevation, numeric=True)\n",
    "m.add_tooltips(data.elevation)\n",
    "m.legend_position = 'bottomleft'\n",
    "m.create_map()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2. Some real examples <a name=\"real_examples\"></a>\n",
    "\n",
    "### 2.1. Circassian Example <a name=\"example1\"></a>\n",
    "Let's draw a map based on data from [this](https://github.com/ropensci/lingtypology/blob/master/database_creation/circassian.csv) CSV.  "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 30,
   "metadata": {},
   "outputs": [],
   "source": [
    "import pandas"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 31,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>latitude</th>\n",
       "      <th>longitude</th>\n",
       "      <th>village</th>\n",
       "      <th>district</th>\n",
       "      <th>dialect</th>\n",
       "      <th>language</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>45.183330</td>\n",
       "      <td>39.666670</td>\n",
       "      <td>Khatukay</td>\n",
       "      <td>ra</td>\n",
       "      <td>Temirgoy</td>\n",
       "      <td>Adyghe</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>43.092518</td>\n",
       "      <td>43.522085</td>\n",
       "      <td>Psygansu</td>\n",
       "      <td>kbr</td>\n",
       "      <td>Baksan</td>\n",
       "      <td>Kabardian</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>43.217748</td>\n",
       "      <td>43.738020</td>\n",
       "      <td>Verkhny Lesken</td>\n",
       "      <td>kbr</td>\n",
       "      <td>Baksan</td>\n",
       "      <td>Kabardian</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>43.260246</td>\n",
       "      <td>43.653788</td>\n",
       "      <td>Zhemtala</td>\n",
       "      <td>kbr</td>\n",
       "      <td>Baksan</td>\n",
       "      <td>Kabardian</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>43.317842</td>\n",
       "      <td>43.876519</td>\n",
       "      <td>Erokko</td>\n",
       "      <td>kbr</td>\n",
       "      <td>Baksan</td>\n",
       "      <td>Kabardian</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "    latitude  longitude         village district   dialect   language\n",
       "0  45.183330  39.666670        Khatukay       ra  Temirgoy     Adyghe\n",
       "1  43.092518  43.522085        Psygansu      kbr    Baksan  Kabardian\n",
       "2  43.217748  43.738020  Verkhny Lesken      kbr    Baksan  Kabardian\n",
       "3  43.260246  43.653788        Zhemtala      kbr    Baksan  Kabardian\n",
       "4  43.317842  43.876519          Erokko      kbr    Baksan  Kabardian"
      ]
     },
     "execution_count": 31,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "circassian = pandas.read_csv(\n",
    "    'https://raw.githubusercontent.com/ropensci/lingtypology/master/database_creation/circassian.csv',\n",
    "    delimiter=',',\n",
    "    header=0,\n",
    ")\n",
    "circassian.head()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 32,
   "metadata": {},
   "outputs": [],
   "source": [
    "coordinates = zip(list(circassian.latitude), list(circassian.longitude))\n",
    "dialects = circassian.dialect\n",
    "languages = circassian.language\n",
    "popups = circassian.village"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 33,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div style=\"width:100%;\"><div style=\"position:relative;width:100%;height:0;padding-bottom:60%;\"><iframe src=\"data:text/html;charset=utf-8;base64,[encoded data, 661016 characters]\" style=\"position:absolute;width:100%;height:100%;left:0;top:0;border:none !important;\" allowfullscreen webkitallowfullscreen mozallowfullscreen></iframe></div></div>"
      ],
      "text/plain": [
       "<folium.folium.Map at 0x7f307326f0f0>"
      ]
     },
     "execution_count": 33,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "#Creating LingMap object\n",
    "m = lingtypology.LingMap(languages)\n",
    "#Setting up start location\n",
    "m.start_location = (44.21, 42.32)\n",
    "#Setting up start zoom\n",
    "m.start_zoom = 7\n",
    "#Inner features < dialect\n",
    "m.add_features(dialects, opacity=0.7)\n",
    "#Outer features < language\n",
    "m.add_stroke_features(languages, opacity=0.8)\n",
    "#Popups < village\n",
    "m.add_popups(popups)\n",
    "#Tooltips < language\n",
    "m.add_tooltips(languages)\n",
    "#Custom coordinates (override the ones from Glottolog)\n",
    "m.add_custom_coordinates(coordinates)\n",
    "#Inner legend title and position\n",
    "m.legend_title = 'Dialects'\n",
    "m.legend_position = 'bottomright'\n",
    "#Outer legend title and position\n",
    "m.stroke_legend_title = 'Languages'\n",
    "m.stroke_legend_position = 'topright'\n",
    "m.create_map()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 2.2. Consonants Example <a name=\"example3\"></a>\n",
    "Map based on [this](https://raw.githubusercontent.com/ropensci/lingtypology/master/database_creation/ejective_and_n_consonants.csv) data."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 34,
   "metadata": {},
   "outputs": [],
   "source": [
    "data = pandas.read_csv(\n",
    "    'https://raw.githubusercontent.com/ropensci/lingtypology/master/database_creation/ejective_and_n_consonants.csv',\n",
    "    delimiter=',',\n",
    "    header=0,\n",
    ")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 35,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div style=\"width:100%;\"><div style=\"position:relative;width:100%;height:0;padding-bottom:60%;\"><iframe src=\"data:text/html;charset=utf-8;base64,[encoded data, 70492 characters]\" style=\"position:absolute;width:100%;height:100%;left:0;top:0;border:none !important;\" allowfullscreen webkitallowfullscreen mozallowfullscreen></iframe></div></div>"
      ],
      "text/plain": [
       "<folium.folium.Map at 0x7f307326f400>"
      ]
     },
     "execution_count": 35,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "m = lingtypology.LingMap(data.language)\n",
    "m.legend_title = 'Consonants'\n",
    "m.legend_position = 'bottomleft'\n",
    "m.add_tooltips(data.consonants)\n",
    "#If numeric is True, it will look like this\n",
    "m.add_features(data.consonants, numeric=True)\n",
    "m.create_map()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "[Go back up](#up)"
   ]
  }
 ],
 "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.7.3"
  },
  "title": "Lingtypology"
 },
 "nbformat": 4,
 "nbformat_minor": 2
}
