{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# How to use lingtypology\n",
    "\n",
    "This is a simple tutorial that allows to start using Lingtypology.  \n",
    "For more information you can consult docstrings (e.g. `lingtypology.LingMap.__doc__`).\n",
    "\n",
    "## 0. Table of Contents\n",
    "### 1. [Maps](#maps)\n",
    "#### 1.1. [Simplest example](#simplest_example)  \n",
    "#### 1.2. [Features](#features)\n",
    "#### 1.3. [Map Customization](#map_cust)\n",
    "#### 1.4. [Accessing Glottolog](#access_glot)\n",
    "#### 1.5. [Customizing Features and Controls](#feat_cont)\n",
    "#### 1.6 [Stroke Features](#s_features)\n",
    "#### 1.7. [Heatmaps](#heatmaps)\n",
    "#### 1.8.  [Lines](#lines)\n",
    "### 2. [Real examples](#real_examples)\n",
    "#### 2.1. [Circassian Example](#example1)\n",
    "#### 2.2. [Another way](#example2)\n",
    "#### 2.3. [Consonants Example](#example3)\n",
    "### 3. [Wals](#wals)\n",
    "### 4. [Autotyp](#autotyp)\n",
    "### 5. [Glottolog](#glottolog)\n",
    "#### 5.1 [Glottolog Usage](#g_usage)\n",
    "#### 5.2. [Glottolog Version](#g_version)\n",
    "### 8. [Credits](#credits)\n",
    "### 9. [Citation](#citation)\n",
    "### 10. [License](#license)\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": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "import lingtypology"
   ]
  },
  {
   "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, 8552 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 0x7f0167fcdeb8>"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "m = lingtypology.LingMap(('Romanian', 'Ukrainian'))\n",
    "m._create_map()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "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",
    "To save your map as html run: `m.save('map.html')`  \n",
    "To get html as `str` run: `m.render()`\n",
    "\n",
    "### 1.2. 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": 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, 18548 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 0x7f0167fcdef0>"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "languages = [\"Adyghe\", \"Kabardian\", \"Polish\", \"Russian\", \"Bulgarian\"]\n",
    "features = [\"Agglutinative\", \"Agglutinative\", \"Inflected\", \"Inflected\", \"Analythic\"]\n",
    "m = lingtypology.LingMap(languages)\n",
    "m.add_features(features)\n",
    "m._create_map()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 1.3. 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` attribute."
   ]
  },
  {
   "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, 18540 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 0x7f0167d6ee10>"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "m.start_location = (40, 40)\n",
    "m.start_zoom = 3\n",
    "m.colors = (\"yellowgreen\", \"red\", \"blue\")\n",
    "m._create_map()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 1.4. 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."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "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, 18864 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 0x7f0167d813c8>"
      ]
     },
     "execution_count": 5,
     "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.5. 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": 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, 17388 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 0x7f0167d27cf8>"
      ]
     },
     "execution_count": 6,
     "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.6. Stroke features <a name=\"s_features\"></a>\n",
    "\n",
    "It is possible to add another set of features to strokes of markers."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "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, 28652 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 0x7f0167d3f128>"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "m = lingtypology.LingMap(languages)\n",
    "m.add_features(features)\n",
    "m.add_stroke_features(['Ergative', 'Ergative', 'Accusative', 'Accusative', 'Accusative'])\n",
    "m._create_map()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 1.7. 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)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "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-05-08.)\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, 6600 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 0x7f0167d04f98>"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "import lingtypology\n",
    "#I take coordinates from Wals. More in paragraph 3.Wals\n",
    "import pandas\n",
    "from lingtypology.db_apis 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 == 'Large'].coordinates)\n",
    "#Let's also add a title to the map\n",
    "m.title = 'Large Consonant Inventories'\n",
    "m._create_map()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 1.8. Lines <a name=\"lines\"></a>\n",
    "\n",
    "Let's say we have this list of languages:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {},
   "outputs": [],
   "source": [
    "balkan = ['Modern Greek', 'Romanian', 'Bulgarian', 'Macedonian', 'Gheg Albanian']\n",
    "other = ['Ukrainian', 'Turkish', 'Italian']\n",
    "languages = balkan + other"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We want the ones from Balkan sprachbund connected with lines."
   ]
  },
  {
   "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, 24540 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 0x7f015008b358>"
      ]
     },
     "execution_count": 22,
     "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)\n",
    "m.add_line(coordinates)\n",
    "m.start_location = (43, 27)\n",
    "m.start_zoom = 5\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": 9,
   "metadata": {},
   "outputs": [],
   "source": [
    "import pandas"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [],
   "source": [
    "circassian = pandas.read_csv(\n",
    "    'https://raw.githubusercontent.com/ropensci/lingtypology/master/database_creation/circassian.csv',\n",
    "    delimiter=',',\n",
    "    header=0,\n",
    ")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "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": 12,
   "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, 656552 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 0x7f0167c91080>"
      ]
     },
     "execution_count": 12,
     "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)\n",
    "#Outer features < language\n",
    "m.add_stroke_features(languages)\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. Another way <a name=\"example2\"></a>\n",
    "If you are used to the R package, you may find this way to program the second example more appealing.  \n",
    "However, it is not recommended because most of customization is impossible."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [],
   "source": [
    "coordinates = zip(list(circassian.latitude), list(circassian.longitude))\n",
    "dialects = circassian.dialect\n",
    "languages = circassian.language\n",
    "popups = circassian.village\n",
    "\n",
    "lingtypology.map_feature(\n",
    "    languages,\n",
    "    custom_coordinates = coordinates,\n",
    "    features = dialects,\n",
    "    stroke_features = languages,\n",
    "    popups = popups,\n",
    "    tooltips = languages,\n",
    "    legend_title = 'Dialects',\n",
    "    legend_position = 'bottomright',\n",
    "    stroke_legend_title = 'Languages',\n",
    "    stroke_legend_position = 'topright',\n",
    "    start_zoom = 7,\n",
    "    start_location = (44.21, 42.32),\n",
    "    save_html = 'circassian.html',\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 2.3. 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": 14,
   "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": 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, 53756 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 0x7f016528b9b0>"
      ]
     },
     "execution_count": 15,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "m = lingtypology.LingMap(data.language)\n",
    "m.legend_title = 'Amount of consonants'\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": [
    "## 3. Wals <a name=\"wals\"></a>\n",
    "\n",
    "It is possible to access Wals data (online) using `lingtypology.db_apis`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "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-05-08.)\n",
      "\n",
      "Citation for feature 2A:\n",
      "Ian Maddieson. 2013. Vowel Quality 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/2, Accessed on 2019-05-08.)\n",
      "\n"
     ]
    },
    {
     "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>wals code</th>\n",
       "      <th>language</th>\n",
       "      <th>genus</th>\n",
       "      <th>family</th>\n",
       "      <th>area</th>\n",
       "      <th>coordinates</th>\n",
       "      <th>_1A</th>\n",
       "      <th>_2A</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>kiw</td>\n",
       "      <td>Kiwai (Southern)</td>\n",
       "      <td>Kiwaian</td>\n",
       "      <td>Kiwaian</td>\n",
       "      <td>Phonology</td>\n",
       "      <td>(-8.0, 143.5)</td>\n",
       "      <td>Small</td>\n",
       "      <td>Average (5-6)</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>xoo</td>\n",
       "      <td>!Xóõ</td>\n",
       "      <td>Tu</td>\n",
       "      <td>Tu</td>\n",
       "      <td>Phonology</td>\n",
       "      <td>(-24.0, 21.5)</td>\n",
       "      <td>Large</td>\n",
       "      <td>Average (5-6)</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>ani</td>\n",
       "      <td>//Ani</td>\n",
       "      <td>Khoe-Kwadi</td>\n",
       "      <td>Khoe-Kwadi</td>\n",
       "      <td>Phonology</td>\n",
       "      <td>(-18.9166666667, 21.9166666667)</td>\n",
       "      <td>Large</td>\n",
       "      <td>Average (5-6)</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>abi</td>\n",
       "      <td>Abipón</td>\n",
       "      <td>South Guaicuruan</td>\n",
       "      <td>Guaicuruan</td>\n",
       "      <td>Phonology</td>\n",
       "      <td>(-29.0, -61.0)</td>\n",
       "      <td>Moderately small</td>\n",
       "      <td>Average (5-6)</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>abk</td>\n",
       "      <td>Abkhaz</td>\n",
       "      <td>Northwest Caucasian</td>\n",
       "      <td>Northwest Caucasian</td>\n",
       "      <td>Phonology</td>\n",
       "      <td>(43.0833333333, 41.0)</td>\n",
       "      <td>Large</td>\n",
       "      <td>Small (2-4)</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "  wals code           language                genus               family  \\\n",
       "0       kiw   Kiwai (Southern)              Kiwaian              Kiwaian   \n",
       "1       xoo               !Xóõ                   Tu                   Tu   \n",
       "2       ani              //Ani           Khoe-Kwadi           Khoe-Kwadi   \n",
       "3       abi             Abipón     South Guaicuruan           Guaicuruan   \n",
       "4       abk             Abkhaz  Northwest Caucasian  Northwest Caucasian   \n",
       "\n",
       "        area                      coordinates               _1A            _2A  \n",
       "0  Phonology                    (-8.0, 143.5)             Small  Average (5-6)  \n",
       "1  Phonology                    (-24.0, 21.5)             Large  Average (5-6)  \n",
       "2  Phonology  (-18.9166666667, 21.9166666667)             Large  Average (5-6)  \n",
       "3  Phonology                   (-29.0, -61.0)  Moderately small  Average (5-6)  \n",
       "4  Phonology            (43.0833333333, 41.0)             Large    Small (2-4)  "
      ]
     },
     "execution_count": 16,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "import lingtypology\n",
    "from lingtypology.db_apis import Wals\n",
    "\n",
    "wals_page = Wals('1a', '2a').get_df()\n",
    "wals_page.head()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "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, 1324984 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 0x7f0150730e80>"
      ]
     },
     "execution_count": 17,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "m = lingtypology.LingMap(wals_page.language)\n",
    "m.add_custom_coordinates(wals_page.coordinates)\n",
    "m.add_features(wals_page._1A)\n",
    "m.legend_title = 'Consonant Inventory'\n",
    "m._create_map()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 4. Autotyp <a name=\"autotyp\"></a>\n",
    "\n",
    "It is possible to access Autotyp data (online) using `lingtypology.db_apis`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {
    "scrolled": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Bickel, Balthasar, Johanna Nichols, Taras Zakharko,\n",
      "Alena Witzlack-Makarevich, Kristine Hildebrandt, Michael Rießler,\n",
      "Lennart Bierkandt, Fernando Zúñiga & John B. Lowe.\n",
      "2017. The AUTOTYP typological databases.\n",
      "Version 0.1.0 https://github.com/autotyp/autotyp-data/tree/0.1.0\n",
      "(get_by_glot_id) Warning: language by ngiy1239 not found\n",
      "(get_by_glot_id) Warning: language by east2283 not found\n"
     ]
    },
    {
     "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>Language</th>\n",
       "      <th>LID</th>\n",
       "      <th>Gender.n</th>\n",
       "      <th>Gender.binned4</th>\n",
       "      <th>Gender.Presence</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>Godoberi</td>\n",
       "      <td>1531</td>\n",
       "      <td>3</td>\n",
       "      <td>3 genders</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>Bininj Kun-Wok</td>\n",
       "      <td>655</td>\n",
       "      <td>4</td>\n",
       "      <td>4 genders</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>Luvale</td>\n",
       "      <td>553</td>\n",
       "      <td>10</td>\n",
       "      <td>more than 4 genders</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>Chamalal</td>\n",
       "      <td>1149</td>\n",
       "      <td>5</td>\n",
       "      <td>more than 4 genders</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>North-Central Dargwa</td>\n",
       "      <td>2949</td>\n",
       "      <td>3</td>\n",
       "      <td>3 genders</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "               Language   LID Gender.n       Gender.binned4 Gender.Presence\n",
       "0              Godoberi  1531        3            3 genders            True\n",
       "1        Bininj Kun-Wok   655        4            4 genders            True\n",
       "2                Luvale   553       10  more than 4 genders            True\n",
       "3              Chamalal  1149        5  more than 4 genders            True\n",
       "4  North-Central Dargwa  2949        3            3 genders            True"
      ]
     },
     "execution_count": 18,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "import lingtypology\n",
    "from lingtypology.db_apis import Autotyp\n",
    "Autotyp_table = Autotyp('Gender').get_df()\n",
    "Autotyp_table.head()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "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, 743120 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 0x7f0150730940>"
      ]
     },
     "execution_count": 20,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "m = lingtypology.LingMap(Autotyp_table.Language)\n",
    "m.add_features(Autotyp_table['Gender.binned4'])\n",
    "m._create_map()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 5. Glottolog <a name=\"glottolog\"></a>\n",
    "You can use a number of functions to work with Glottolog data.\n",
    "\n",
    "### 5.1. Usage <a name=\"g_usage\"></a>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from lingtypology import glottolog"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Get genealogy information:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "glottolog.get_affiliations(('Russian', 'English'))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Get coordinates of a language:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "glottolog.get_coordinates('Russian')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Get the Glottolog ID (aka Glottocode):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "glottolog.get_glot_id('Russian')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Get the macroarea:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "glottolog.get_macro_area('Russian')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Get the ISO code:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "glottolog.get_iso('Russian')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Get language by ISO code:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "glottolog.get_by_iso('rus')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Get language by Glottocode:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "glottolog.get_by_glot_id('russ1263')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Get Glottocode by ISO:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "glottolog.get_glot_id_by_iso('rus')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Get ISO by Glottocode:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "glottolog.get_iso_by_glot_id('russ1263')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 5.2. Using the most recent version of Glottolog database <a name=\"g_version\"></a>\n",
    "\n",
    "Each new release of `lingtypology` is shipped with the latest version of the Glottolog data. The information about the version of Glottolog can be retrieved using:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from lingtypology import glottolog\n",
    "#Yet, I cannot guarantee that this tutorial is updated with each release.\n",
    "#If you want to get your version, run this code on your machine.\n",
    "glottolog.version"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Nevertheless, if you want to get the newest release and do not wish to wait for the next version of `lingtypology`, you can download the version you wish locally by following these steps: \n",
    "\n",
    "1) Download `glottolog` from [here](https://github.com/clld/glottolog).  \n",
    "\n",
    "2) If you downloaded it as an archive, unpack it.  \n",
    "\n",
    "3) In your home directory make a folder and call it `.lingtypology_data` (with `.` in the beginning).  \n",
    "\n",
    "4) Move `glottolog` into `.lingtypology_data`.  \n",
    "\n",
    "5) Run the following command:  \n",
    "`glottolog --repos=glottolog languoids`  \n",
    "\n",
    "6) It will generate two small files (`csv` and `json`). Now you can delete everything **except** for these files from the directory."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 8. Credits <a name=\"credits\"></a>\n",
    "\n",
    "This Python package is inspired by the [R package](https://github.com/ropensci/lingtypology) made by [agricolamz](https://github.com/agricolamz).  \n",
    "Also this module uses JavaScript library [Leaflet](https://leafletjs.com/) and its Python-wrapper [Folium](https://github.com/python-visualization/folium) and [Branca](https://github.com/python-visualization/branca).  \n",
    "Also, special thanks to [Xrotwang](https://github.com/xrotwang) for helping me with the package.\n",
    "\n",
    "## 9. Citation <a name=\"citation\"></a>\n",
    "\n",
    "It will be most appreciated if you cite `lingtypology`:\n",
    "```\n",
    "@misc{michael_voronov_2019_2669684,\n",
    "author       = {Michael Voronov},\n",
    "title        = {{lingtypology: a Python tool for linguistic interactive mapping}},\n",
    "month        = may,\n",
    "year         = 2019,\n",
    "doi          = {10.5281/zenodo.2669684},\n",
    "url          = {https://doi.org/10.5281/zenodo.2669684}\n",
    "}\n",
    "```\n",
    "\n",
    "\n",
    "## 10. License <a name=\"license\"></a>\n",
    "\n",
    "Copyright (C) 2018-2019  Michael Voronov\n",
    "\n",
    "This program is free software: you can redistribute it and/or modify  \n",
    "it under the terms of the GNU General Public License as published by  \n",
    "the Free Software Foundation, either version 3 of the License, or  \n",
    "(at your option) any later version.\n",
    "\n",
    "This program is distributed in the hope that it will be useful,  \n",
    "but WITHOUT ANY WARRANTY; without even the implied warranty of  \n",
    "MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the  \n",
    "[GNU General Public License](https://github.com/OneAdder/lingtypology/blob/master/LICENSE.md) for more details."
   ]
  }
 ],
 "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.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}
