How to use lingtypology

This is a simple tutorial that allows to start using Lingtypology.
For more information you can consult docstrings (e.g. lingtypology.LingMap.__doc__).

1. Basics

In this paragraph I will consider some basic features that you can use.

1.1. Simplest example

The simplest script that draws a map with Romanian and Ukrainian languages will be:

In [1]:
import lingtypology
In [2]:
m = lingtypology.LingMap(('Romanian', 'Ukrainian'))
m._create_map()
Out[2]:

Be advised that _create_map() returns a Folium map. In this notebook it is used because the map may be displayed this way.
To save your map as html run: m.save('map.html')
To get html as str run: m.render()

1.2. Features

Simply drawing languages on a map is not very interesting. Let's say that we want to mark some morphological features as different colors.

In [3]:
languages = ["Adyghe", "Kabardian", "Polish", "Russian", "Bulgarian"]
features = ["Agglutinative", "Agglutinative", "Inflected", "Inflected", "Analythic"]
m1 = lingtypology.LingMap(languages)
m1.add_features(features)
m1._create_map()
Out[3]:

1.3. Customizing the map

As you can see, the map is not centered properly. It can be fixed with passing coordinates to the start_location attribute.
Also, you can change colors using the colors attribute.

In [4]:
m1.start_location = (40, 40)
m1.colors = ("yellowgreen", "red", "blue")
m1._create_map()
Out[4]:

1.4. Accessing Glottolog

You can also use lingtypology.glottolog to get some data from it. For example, I want to add language affiliations to popups.

In [5]:
affs = lingtypology.glottolog.get_affiliations(languages)
m1.add_popups(affs)
m1._create_map()
Out[5]:

1.5. Customizing features and controls

You can pass additional parameters to the add_features method.
If for some reason you do not wish to use colors, you could use shapes.
If you want to add controls, you can do it as well.

In [6]:
m1.add_features(features, use_shapes=True, control=True)
m1._create_map()
Out[6]:

2. Some real example

Let's draw a map based on data from this CSV.

In [7]:
import pandas
In [8]:
circassian = pandas.read_csv(
    'https://raw.githubusercontent.com/ropensci/lingtypology/master/database_creation/circassian.csv',
    delimiter=',',
    header=0,
)
In [9]:
coordinates = zip(list(circassian.latitude), list(circassian.longitude))
dialects = circassian.dialect
languages = circassian.language
popups = circassian.village
In [10]:
#Creating LingMap object
m2 = lingtypology.LingMap(languages)
#Setting up start location
m2.start_location = (44.21, 42.32)
#Setting up start zoom
m2.start_zoom = 7
#Inner features < dialect
m2.add_features(dialects)
#Outer features < language
m2.add_stroke_features(languages)
#Popups < village
m2.add_popups(popups)
#Tooltips < language
m2.add_tooltips(languages)
#Custom coordinates (override the ones from Glottolog)
m2.add_custom_coordinates(coordinates)
#Inner legend title and position
m2.legend_title = 'Dialects'
m2.legend_position = 'bottomright'
#Outer legend title and position
m2.stroke_legend_title = 'Languages'
m2.stroke_legend_position = 'topright'
m2._create_map()
Out[10]:

3. Wals

It is possible to access Wals data (online) using lingtypology.db_apis.

In [11]:
import lingtypology
from lingtypology.db_apis import Wals

wals_page = Wals('1a').get_df()

Citation for feature 1A:
Ian Maddieson. 2013. Consonant Inventories.
In: Dryer, Matthew S. & Haspelmath, Martin (eds.)
The World Atlas of Language Structures Online.
Leipzig: Max Planck Institute for Evolutionary Anthropology.
(Available online at http://wals.info/chapter/1, Accessed on 2019-05-02.)
In [12]:
m3 = lingtypology.LingMap(wals_page.language)
m3.add_custom_coordinates(wals_page.coordinates)
m3.add_features(wals_page._1A)
m3.legend_title = 'Consonant Inventory'
m3._create_map()
Out[12]:

4. Heatmaps

It would seem unfaire if we could only draw circles.
Let's draw a heatmap (the more density, the more languages with Large consonant inventory).

In [13]:
import pandas
import lingtypology
from lingtypology.db_apis import Wals

wals_page = Wals('1a').get_df()

Citation for feature 1A:
Ian Maddieson. 2013. Consonant Inventories.
In: Dryer, Matthew S. & Haspelmath, Martin (eds.)
The World Atlas of Language Structures Online.
Leipzig: Max Planck Institute for Evolutionary Anthropology.
(Available online at http://wals.info/chapter/1, Accessed on 2019-05-02.)
In [14]:
#First initialize LingMap without languages
m4 = lingtypology.LingMap()
#Add heatmap from  the Wals data
m4.add_heatmap(wals_page[wals_page._1A == 'Large'].coordinates)
#Let's also add a title to the map
m4.title = 'Large Consonant Inventories'
m4._create_map()
Out[14]:

5. Glottolog

You can use a number of functions to work with Glottolog data.

5.1. Usage

In [15]:
from lingtypology import glottolog

Get genealogy information:

In [16]:
glottolog.get_affiliations(('Russian', 'English'))
Out[16]:
['Indo-European, Balto-Slavic, Slavic, East Slavic',
 'Indo-European, Germanic, Northwest Germanic, West Germanic, North Sea Germanic, Anglo-Frisian, Anglic, Later Anglic, Middle-Modern English, Macro-English']

Get coordinates of a language:

In [17]:
glottolog.get_coordinates('Russian')
Out[17]:
(59.0, 50.0)

Get the Glottolog ID (aka Glottocode):

In [18]:
glottolog.get_glot_id('Russian')
Out[18]:
'russ1263'

Get the macroarea:

In [19]:
glottolog.get_macro_area('Russian')
Out[19]:
'Eurasia'

Get the ISO code:

In [20]:
glottolog.get_iso('Russian')
Out[20]:
'rus'

Get language by ISO code:

In [21]:
glottolog.get_by_iso('rus')
Out[21]:
'Russian'

Get language by Glottocode:

In [22]:
glottolog.get_by_glot_id('russ1263')
Out[22]:
'Russian'

Get Glottocode by ISO:

In [23]:
glottolog.get_glot_id_by_iso('rus')
Out[23]:
'russ1263'

Get ISO by Glottocode:

In [24]:
glottolog.get_iso_by_glot_id('russ1263')
Out[24]:
'rus'

5.2. Using the most recent version of Glottolog database

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:

In [25]:
from lingtypology import glottolog
#Yet, I cannot guarantee that this tutorial is updated with each release.
#If you want to get your version, run this code on your machine.
glottolog.version
Out[25]:
'v3.4-7-gfa9d1ec7c5'

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:

1) Download glottolog from here.

2) If you downloaded it as an archive, unpack it.

3) In your home directory make a folder and call it .lingtypology_data (with . in the beginning).

4) Move glottolog into .lingtypology_data.

5) Run the following command:
glottolog --repos=glottolog languoids

6) It will generate two small files (csv and json). Now you can delete everything except for these files from the directory.

6. Credits

This Python package is enspired by the R package made by agricolamz.
Also this module uses JavaScript library Leaflet and its Python-wrapper Folium and Branca.
Also, special thanks to Xrotwang for helping me with the package.

7. License

Copyright (C) 2018-2019 Michael Voronov

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.