HOWTO

# 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__`).

## 0. Table of Contents¶

### 1. Basics¶

#### 1.1. Simplest example¶

#### 1.2. Features¶

#### 1.3. Map Customization¶

#### 1.4. Accessing Glottolog¶

#### 1.5. Customizing Features and Controls¶

### 2. Real examples¶

#### 2.1. Circassian Example¶

#### 2.2. Another way¶

#### 2.3. Consonants Example¶

### 3. Wals¶

### 4. Heatmaps¶

### 5. Glottolog¶

#### 5.1 Glottolog Usage¶

#### 5.2. Glottolog Version¶

### 6. Credits¶

### 7. License¶

## 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 examples ¶

### 2.1. Circassian 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]:

### 2.2. Another way ¶

If you are used to the R package, you may find this way to program the second example more appealing.
However, it is not recommended because most of customization is impossible.

In [11]:

    coordinates = zip(list(circassian.latitude), list(circassian.longitude))
    dialects = circassian.dialect
    languages = circassian.language
    popups = circassian.village

    lingtypology.map_feature(
        languages,
        custom_coordinates = coordinates,
        features = dialects,
        stroke_features = languages,
        popups = popups,
        tooltips = languages,
        legend_title = 'Dialects',
        legend_position = 'bottomright',
        stroke_legend_title = 'Languages',
        stroke_legend_position = 'topright',
        start_zoom = 7,
        start_location = (44.21, 42.32),
        save_html = 'circassian.html',
    )

### 2.3. Consonants Example ¶

Map based on this data.

In [12]:

    data = pandas.read_csv(
        'https://raw.githubusercontent.com/ropensci/lingtypology/master/database_creation/ejective_and_n_consonants.csv',
        delimiter=',',
        header=0,
    )

In [13]:

    mc = lingtypology.LingMap(data.language)
    mc.legend_title='Amount of consonants'
    mc.add_tooltips(data.consonants)
    #If numeric is True, it will look like this
    mc.add_features(data.consonants, numeric=True)
    mc._create_map()

    (get_coordinates) Warning: coordinates for Paraguayan Guarani not found

Out[13]:

## 3. Wals ¶

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

In [14]:

    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 [15]:

    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()

    (get_coordinates) Warning: coordinates for Paraguayan Guarani not found

Out[15]:

## 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 [16]:

    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 [17]:

    #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[17]:

## 5. Glottolog ¶

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

### 5.1. Usage ¶

In [18]:

    from lingtypology import glottolog

Get genealogy information:

In [19]:

    glottolog.get_affiliations(('Russian', 'English'))

Out[19]:

    ['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 [20]:

    glottolog.get_coordinates('Russian')

Out[20]:

    (59.0, 50.0)

Get the Glottolog ID (aka Glottocode):

In [21]:

    glottolog.get_glot_id('Russian')

Out[21]:

    'russ1263'

Get the macroarea:

In [22]:

    glottolog.get_macro_area('Russian')

Out[22]:

    'Eurasia'

Get the ISO code:

In [23]:

    glottolog.get_iso('Russian')

Out[23]:

    'rus'

Get language by ISO code:

In [24]:

    glottolog.get_by_iso('rus')

Out[24]:

    'Russian'

Get language by Glottocode:

In [25]:

    glottolog.get_by_glot_id('russ1263')

Out[25]:

    'Russian'

Get Glottocode by ISO:

In [26]:

    glottolog.get_glot_id_by_iso('rus')

Out[26]:

    'russ1263'

Get ISO by Glottocode:

In [27]:

    glottolog.get_iso_by_glot_id('russ1263')

Out[27]:

    '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 [28]:

    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[28]:

    '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.