lingtypology.maps

Intro

This module consist of the class and functions to draw linguistic interactive maps.

lingtypology.LingMap class

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

Lingtypology map object.

Parameters:

• languages (list 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.

• glottocodes (bool, default False) – Whether to treat languages as Glottocodes.

tiles

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.

Type:str, default ‘OpenStreetMap’

start_location

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”

Type:(float, float), default (0, 0)

start_zoom

Initial zoom level.

Bypassed if you are using a start_location shortcut.

Type:int, default 2

control_scale

Whether to add control scale.

Type:bool, default True

base_map

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

Type:folium.Map, default None

colors

Colors that represent features. You can either use the default colors or set yours.

Type:list of html codes for colors

stroke_colors

Colors that represent additional (stroke) features. You can either use the default colors or set yours.

Type:list of html codes for colors

shapes

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

Type:list of characters

prefer_canvas

Use canvas instead of SVG.

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

Type:bool, default False

base_map

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

Type:folium.Map, default None

title

You can add a title to the map.

Type:str, default None

legend

Whether to add legend for features (add_features method).

Type:bool, default True

stroke_legend

Whether to add legend for stroke features (add_stroke_features method).

Type:bool, default True.

legend_title

Legend title.

Type:str, default ‘Legend’

stroke_legend_title

Stroke legend title.

Type:str, default ‘Legend’

legend_position

Legend position.

Available values: ‘right’, ‘left’, ‘top’, ‘bottom’, ‘bottomright’, ‘bottomleft’, ‘topright’, ‘topleft’.

Type:str, default ‘bottomright’

stroke_legend_position

Stroke legend position.

Available values: ‘right’, ‘left’, ‘top’, ‘bottom’, ‘bottomright’, ‘bottomleft’, ‘topright’, ‘topleft’.

Type:str, default ‘bottomleft’

colors

Colors that represent features.

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

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

stroke_colors

Colors that represent stroke features.

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

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

colormap_colors

Colors for the colormap.

Type:tuple, default (‘white’, ‘green’)

shapes

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

Type:list of characters (str)

stroked

Whether to add stroke to markers.

Type:bool, default True

unstroked

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.

Type:bool, default True

control

Whether to add LayerControls and group by features.

Type:bool, default False

stroke_control

Whether to add LayerControls and group by stroke features.

Type:bool, default False

control_position

Position of LayerControls.

May be ‘topleft’, ‘topright’, ‘bottomleft’ or ‘bottomright’.

Type:str, default ‘topright’

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.

Parameters:custom_coordinates (list of 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, factor=None)

Add features.

Parameters:

• features (list of strings) –

  List of features.

  Length of the list should equal to length of languages. 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.
• factor (list-like, default None) – Unless the factor of sorting is specified, the features will be sorted alphabetically. How to use it: For example you have features (‘a’, ‘a’, ‘b’, ‘c’). By default they will be included into the legend with the following order: a, b, c. If you pass (‘b’, ‘a’, ‘c’) as factor, they will be included into the legend this way.

add_stroke_features(features, radius=12, opacity=1, colors=None, numeric=False, control=False, factor=None)

Add stroke features.

This function assigns features to strokes of markers.

Parameters:

• features (list of strings) – 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.
• 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).
• radius (int, default 12) – Marker radius.
• control (bool, default False) – Whether to add LayerControls to the map. It allows interactive turning on/off given features.

add_overlapping_features(marker_groups, 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 location.

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, startangle=90, colors=None, bar_width=1)

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.

Parameters:heatmap (list of tuples) – Coordinates for the heatmap.

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 small pieces of html code. If you need to add full html pages to popups, you need to set the option to True.
• glottolog_links (bool, default True) – Whether to include links to Glottolog in popups.

add_tooltips(tooltips)

Add tooltips to markers.

Parameters: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 (int, default 150) –
• height (int, default 150) –
• collapsed_width (int, default 25) –
• collapsed_height (int, default 25) –
• zoom_animation (bool, default True) – You can disable zoom animation for better performance.

add_rectangle(locations, tooltip='', popup='', color='black')

Add one rectangle.

To add several rectangles, use this method several times.

Parameters:

• locations (list of two tuples) – Coordinates of two points to draw a rectangle.
• tooltip (str, default '') –
• popups (str, default '') –
• color (str, default 'black') –

add_line(locations, tooltip='', popup='', color='black', smooth_factor=1.0)

Add one line.

To add several lines, use this method several times.

Parameters:

• locations (list of two tuples) – Coordinates of two points to draw a line.
• tooltip (str, default '') –
• popups (str, default '') –
• color (str, default 'black') –
• smooth_factor (float, default 1.0) –

create_map()

Create the map.

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

Returns:m Return type:folium.Map

save(path)

Save as html.

Parameters:path (str) – Path to the output HTML file.

render()

Renders the map returns it as HTML string.

Returns: Return type:str

save_static(fname=None)

Save the map as PNG.

Experimental function. Requires additional Python package Selenium and additional application Geckodriver.

Parameters:fname (str, default None) – Path to the output PNG file. If None, the method will return PNG as bytes. Returns: Return type:bytes

Functions

lingtypology.maps.merge(*maps, autoset_legends=True)

Merge several LingMap objects

Parameters:

• *maps (list of LingMap) – List of LingMap objects.
• autoset_legends (bool, default True) – If set to True, legends will automatically move to free spaces

Returns:

m

Return type:

lingtypology.maps.LingMap

lingtypology.maps.get_elevations(languages)

Get elevation data for list of languages.

Parameters:languages (list of str) – Languages from Glottolog. Returns:elevations Return type:list of coordinates

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

Makes a color gradient.

Parameters:

• iterations (int) – Length of gradient.
• color1 (str, default 'white') – First color.
• color2 (str, default 'green') – Second color.

Returns:

colors – List of HEX-colors with #.

Return type:

list of str