docs

# Documentation¶

In this part I will provide full guide for `lingtypology` package. It is divided into four parts: Installation, Interactive Maps, Glottolog functions and the API for databases.

## Installation¶

The package is uploaded to PyPI software repository, therefore it can be installed with the `pip` utility with the following command:

`pip3 install lingtypology –user`

## Interactive Maps¶

Interactive maps can be created with `lingtypology.maps` module.

### LingMap Class¶

class lingtypology.maps.LingMap (languages=[], glottocode=False)

Bases: object

Parameters:

languages: list or pandas.Series of strings, default [].

A list of languages. The language names should correspond to their names from Glottolog unless you use add_custom_coordinates method.

Instead of language names you could use Glottocodes (language ID in Glottolog). In this case you need to set glottocode parameter to true.

glottocode: bool, default False.

Whether to treat languages as Glottocodes.

Attributes:

- tiles: str, default 'OpenStreetMap'

  Tiles for the map. You can use one of these tiles (list of tiles is borrowed from the Folium Documentation:

  - "OpenStreetMap"

  - "Mapbox Bright" (Limited levels of zoom for free tiles)

  - "Mapbox Control Room" (Limited levels of zoom for free tiles)

  - "Stamen" (Terrain, Toner, and Watercolor)

  - "Cloudmade" (Must pass API key)

  - "Mapbox" (Must pass API key)

  - "CartoDB" (positron and dark_matter)

  - or pass the custum URL.

- start_location: (float, float) or str, default (0, 0)

  Coordinates of the start location for the map (latitude, longitude) or a text shortcut. List of available shortcuts: "Central Europe", "Caucasus", "Australia & Oceania", "Papua New Guinea", "Africa", "Asia", "North America", "Central America", "South America".

- start_zoom: int, default 2

  Initial zoom level. Bypassed if you are using a shortcut start_location.

- control_scale: bool, default True

  Whether to add control scale.

- prefer_canvas: bool, default False

  Use canvas instead of SVG. If set to True, the map may be more responsive in case you have a lot of markers.

- base_map: folium.Map, default None

  In case you want to draw something on particular folium.Map.

- title: str, default None

  You can add a title to the map.

- legend: bool, default True

  Whether to add legend for features (add_features method).

- stroke_legend: bool, default True.

  Whether to add legend for stroke features (add_stroke_features method)

- legend_title: str, default 'Legend'

  Legend title.

- stroke_legend_title: str, default 'Legend'

  Stroke legend title.

- legend_position: str, default 'bottomright'

  Legend position. Available values: 'right', 'left', 'top', 'bottom', 'bottomright', 'bottomleft', 'topright', 'topleft'.

- stroke_legend_position: str, default 'bottomleft'

  Stroke legend position. Available values: 'right', 'left', 'top', 'bottom', 'bottomright', 'bottomleft', 'topright', 'topleft'.

- colors: list of html codes for colors (str), default None

  Colors that represent features. You can either use the 20 default colors(if None) or set yours(else).

- shapes: list of characters (str)

  If you use shapes instead of colors, you can either use the default shapes or set yours. Shapes are Unicode symbols.

- stroked: bool, default True

  Whether to add stroke to markers.

- unstroked: bool, default True

  If set to True, circle marker will merge if you zoom out without stroke between them. It multiplies the number of markers by 2. For better performance set it to False. More information and examples in Chapter 2, Paragraph 4.4.

- control: bool, default False

  Whether to add LayerControls and group by features.

- stroke_control: bool, default False

  Whether to add LayerControls and group by stroke features.

- control_position: str, default 'topright'

  Position of LayerControls. May be 'topleft', 'topright', 'bottomleft' or 'bottomright'.

- colormap_colors: tuple, default ('white', 'green')

  Colors for the colormap.

Methods:

- add_custom_coordinates (custom_coordinates)

  Set custom coordinates. By default cooordinates for the languages are taken from the Glottolog database. If you have coordinates and want to use them, use this function.

  It could be useful if you are using data from a dataset which provides coordinates and you do not need to rely on the Glottolog data.

  Parameter custom_coordinates: list of custom_coordinates (tuples)

  Length of the list should equal to length of languages.

- add_features*(features, radius=7, opacity=1, colors=None, numeric=False, control=False, use_shapes=False)*

  Add features to the map.

  Parameters:

  - features: list

    List of features. Amount of features should be equal to the amount of languages. By default, if you add features, a legend will appear. To shut it down set legend attribute to False. To change the title of the legend use legend_title attribute. To change legend position use use legend_position attribute.

  - radius: int, default 7

    Marker radius.

  - opacity: float, default 1

    Marker opacity: a number between 0(invisible) and 1(not transparent).

  - colors: list of html codes for colors (str), default None

    Colors that represent features. You can either use the 20 default colors(if None) or set yours(else).

  - numeric: bool, default False

    Whether to assign different color to each feature (False), or to assign a color from colormap (True). You can set it to True only in case your features are numeric and stroke features are not given. To change the default colors of the color scale use colormap_colors attribute.

  - control: bool, default False

    Whether to add LayerControls to the map. It allows interactive turning on/off given features.

  - use_shapes: bool, default False

    Whether to use shapes instead of colors. This option allows to represent features as shapes. Shapes are Unicode charaters. You can replace or add to default symbols by changing shapes attribute. If colors are not a viable option for you, you can set this option to True.

- add_stroke_features*(features, radius=12, opacity=1, colors=None, numeric=False, control=False)*:

  Add additional set of features that look like strokes around markers.

  - features: list

    List of additional features. Amount of features should be equal to the amount of languages. By default, if you add stroke features, a legend will appear. To shut it down set stroke_legend attribute to False. To change the title of the legend use stroke_legend_title attribute. To change legend position use use stroke_legend_position attribute.

  - radius: int, default 12

    Marker radius. Note that this radius is absolute as well.

  - opacity: float, default 1

    Marker opacity: a number between 0(invisible) and 1(not transparent).

  - colors: list of html codes for colors (str), default None

    Colors that represent stroke features. You can either use the 20 default colors(if None) or set yours(else).

  - control: bool, default False

    Whether to add LayerControls to the map. It allows interactive turning on/off given stroke features.

- add_overlapping_features (features, radius=7, radius_increment=4, colors=None, mapping=None):

  Add overlapping features. For example, if you want to draw on map whether language 'is ergative', 'is slavic', 'is spoken in Russia'. It will draw several markers of different size for each feature.

  Parameters:

  - features: list of lists

    List of features. Amount of features should be equal to the amount of languages.

  - radius: int, default 7

    Radius of the smallest circle.

  - radius_increment: int, default 4

    Step by which the size of the marker for each feature will be incremented.

  - colors: list of html codes for colors (str), default None

    Colors that represent features. You can either use the 20 default colors(if None) or set yours(else).

  - mapping: dict, default None

    Mapping for the legend.

- add_minicharts (*minicharts, typ='pie', size=0.6, names=None, textprops=None, labels=False, colors=None , startangle=90):

  Create minicharts using Maplotlib.

  Parameters:

  - *minicharts: list-like objects

    Data for minicharts. Two list-like objects.

  - typ: str, default pie

    Type of the minicharts. Either pie or bar.

  - size: float

    Size of the minicharts.

  - texprops: dict, default None

    Textprops for Matplotlib.

  - labels: bool, default False

    Whether to display labels.

  - colors: list, default None

    Minicharts colors.

  - startange: int, default 90

    Start angle of pie-charts (pie-charts only).

- add_heatmap: (heatmap=[])

  Add heatmap.

  Parameter heatmap: list-like object with tuples

  Coordinates for the heatmap. To create a heatmap-only map, do not pass any languages.

- add_popups (popups, parse_html=False, glottolog_links=True)

  Add popups to markers.

  Parameters:

  - popups: list of strings List of popups. Length of the list should equal to length of languages.

  - parse_html: bool, default False By default (False) you can add HTML elements. If you need to add full HTML pages(e.g. with JavaScript code) to popups, you need to set the option to True.

  - glottolog_links: bool, default True

    Whether to show links to Glottolog website in popups. Automatically disabled when parse_html is used.

- add_tooltips (tooltips):

  Add tooltips to markers.

  Parameter tooltips: list of strings

  List of tooltips. Length of the list should equal to length of languages.

- add_minimap (position='bottomleft', width=150, height=150, collapsed_width=25, collapsed_height=25, zoom_animation=True)

  Add minimap.

  Parameters:

  - position: str, default 'bottomleft'

  - width and height: int, default 150

  - collapsed_width and collapsed_height: int, default 25

  - zoom_animation: bool, default True

    You can disable zoom animation for better performance.

- add_line and add_rectangle (locations, tooltip=", popup=", color='black')

  Parameters:

  - locations: list-like object of tuples

    Coordinates necessary ro draw the figure.

  - tooltip: str, default "

    Tooltip for the figure.

  - popup: str, default "

    Popup for the figure.

  - color: str, default 'black'

    Color of the figure.

- create_map ()

  Create the map. To display the map in Jupyter Notebook, use this method.

  Returns folium.Map

- render*()*

  Returns the HTML code as str. It might be useful in case you want to implement it into a website.

- save (path)

  Save the map as HTML. It is useful when you need to include a map into a web-publication.

  Parameter path, str

  Path to the file.

- save_static (path=None)

  Save the map as PNG. Experimental function. Requires additional Python package Selenium and additional application Geckodriver.

  It is useful for handouts, presentations and publications in paper journals.

  If path is not given returns the PNG as bytes.

### Functions¶

function lingtypology.maps.merge (*maps)

Accepts LingMap objects and creates map of them.

It is impossible to add, for example, features and minicharts. If you need it, you can create two LingMap objects and then use the merge function.

Parameter maps: lingtypology.maps.LingMap* objects.

Returns lingtypology.maps.LingMap

function lingtypology.maps.get_elevations (languages)

Get data on elevation for languages. More information in Chapter 2, Paragraph 4.2.

Parameter lagnauges: list of strings

Returns list

function lingtypology.maps.gradient (iterations, color1='white', color2='green')

Creates color gradient of given length.

Returns list of HEX-colors

## Glottolog¶

`lingtypology.glottolog`

### Functions¶

Glottolog module includes various functions to work with Glottolog data.

The only funcntion that accepts list-like objects and returns list is get_affiliations. Its parameter is language names, it returns the genealogical information for the given languages.

The parameter of all the other functions is str and they return str.

The following functions use language name as the parameter and return coordinates, Glottocode, macro area and ISO code respectively:

- lingtypology.glottolog.get_coordinates

- lingtypology.glottolog.get_glot_id

- lingtypology.glottolog.get_macroarea

- lingtypology.glottolog.get_iso

The following functions use Glottocode as the parameter and return coordinates, language name and ISO code respectively:

- lingtypology.glottolog.get_coordinates_by_glot_id

- lingtypology.glottolog.get_by_glot_id

- lingtypology.glottolog.get_iso_by_glot_id

The following functions use ISO code as the parameter and return language name and Glottocode respectively.

- lingtypology.glottolog.get_by_iso

- lingtypology.glottolog.get_glot_id_by_iso

### Versions¶

Processed Glottolog data is stored statically in the package directory. It is updated with each new release of `lingtypology`.

The version of the Glottolog data which is currently used is stored in lingtypology.glottolog.version variable.

It is possible to use local Glottolog data. To do so, it is necessary to perform the following steps:

- Download the current version of the Glottolog data.

- Create directory `.lingtypology_data` in your home directory.

- Move `glottolog` to `.lingtypology_data`.

- Run the following command: `glottolog –repos=glottolog languoids`

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

- Lingtypology will automatically use the local data.

## Databases API¶

`lingtypology.datasets`

### General¶

One of the objectives of LingTypology is to provide a simple interface for linguistic databases. Therefore, classes used for acccessing them have unified API: most attributes and methods overlap among all of them. In this subsection I will describe this universal interface.

Attributes:

- citation: str

  Citation for the database.

- show_citation: bool, default True

  Whether to print the citation when get_df method is called.

- features_list or subsets_list: list of strings

  List of available features for all the databases except for Phoible. In the case of Phoible it is list of available subsets (UPSID, SPA etc.).

Methods:

- get_df

  In all cases parameters are optional. They depend on the particular class.

  In the case of Wals it has optional str parameter join_how: the way multiple WALS pages will be joined (either 'inner' or 'outer'). If the value is 'inner', the resulting table will only contain data for languages mentioned in all the given pages. Else, the resulting table will contain values mentioned in at least one of the pages. Default: 'inner'.

  In the case of Autotyp and Phoible it has optional list parameter strip_na. It is a list of columns. If this parameter is given, the rows where some values in the given columns are not present will be dropped. Default: [].

  Returns the dataset as pandas.DataFrame.

- get_json

  It works the same way as get_df but it returns dict object where keys are headers of the table.

### WALS¶

class lingtypology.datasets.Wals (*features)

Parameter *features, list

List of WALS pages that will be present in the resulting table. E.g. ['1A']

Additional attribite general_citation, str

The general citation for all the WALS pages.

### Autotyp¶

class lingtypology.datasets.Autotyp (*tables)

Parameter *tables: list of strings

List of the Autoptyp tables that will be merged in the resulting table. E.g. ['gender']

### AfBo¶

class lingtypology.datasets.AfBo (*features)

Parameter *features: list of strings

List of Autotyp features that will be present in the resulting table. E.g. ['adjectivizer'].

### SAILS¶

class lingtypology.datasets.Sails (*features)

Parameter *features: list of strings

List of SAILS pages that will be included in the resulting table.

Additional attribute features_descriptions: pandas.DataFrame

Table that contain description for all the SAILS pages.

Additional method feature_descriptions (features)*

Returns table with description for each given feature.

### PHOIBLE¶

class lingtypology.datasets.Phoible (subset='all', aggregated=True)

Parameters:

- subset: str, default 'all'

  One of the PHOIBLE datasets or all of them.

- aggregated: bool, default True

  If is True only aggregated data (e.g. amount of consonants) will be included into the resulting table. The table will be small and easy to operate.

  Else, full PHOIBLE data will be included.