Geospatial module#

The geospatial module contains functions and objects that enable straightforward network plots together with geospatial data.

It relies on geopandas and cartopy in the background.

See “Geospatial networks” for an example.

Content#

The module provides four main tools:

  • draw_map() to plot a network on a map

  • maps, a dictionary of GeoDataFrame containing data from the NaturalEarth project:

    • "adaptive" entry contains 280 entries (in 2021) at the coarsest scale available for each entry,

    • "110m" entry contains 177 countries at 110m resolution,

    • "50m" entry contains 241 countries at 50m resolution,

    • "10m" entry contains 295 map subunits at 10m resolution.

  • code_to_names is a dictionary converting A3 ISO codes to the associated unit’s name (available for all four scales: adaptive and 110/50/10m).

  • cities is a GeoDataFrame containing cities’ data from from NaturalEarth “populated places”.

Note

This data is automatically downloaded when the module is loaded for the first time. It is stored in cartopy.config['data_dir'].

Details#

nngt.geospatial.draw_map(graph, node_names, geodata=None, geodata_names=None, points=None, show_points=False, linecolor=None, hue=None, proj=None, all_geodata=True, axis=None, show=False, **kwargs)[source]#

Draw a network on a map.

Parameters
  • graph (Graph or subclass) – Graph to plot.

  • node_names (str) – Node attribute containing the nodes’ names or A3 codes. This attribute will be used to place each node on the map. By default (if no geodata is provided), the world map is used and each node must therefore be associated to a country name or (better) an A3 ISO code.

  • geodata (GeoDataFrame, optional (default: world map)) – Optional dataframe containing the geospatial information. Predefined geodatas are “110m”, “50m”, and “10m” for world maps with respectively 110, 50, and 10 meter resolutions, or “adaptive” (default) for a world map with adaptive resolution depending on the country size.

  • geodata_names (str, optional (default: “NAME_LONG” or “SU_A3”)) – Column in geodata corresponding to the node_names (respectively for full country names or A3 codes).

  • points (str, optional (default: capitals and representative points)) – Whether a precise point should be associated to each node. It can be either an entry in geodata, the “centroid” of each geometry entry, or a “representative” point. By default, if the world map is used, each country will be associated to its capital (contained in the module’s cities object); if another geodata element is provided, it defaults to “representative”.

  • show_points (bool, optional (default: False)) – Wether the points should be displayed.

  • linecolor (str, char, float or array, optional (default: current palette)) – Color of the map lines.

  • esize (float, str, or array of floats, optional (default: 0.5)) – Width of the edges in percent of canvas length. Available string values are “betweenness” and “weight”.

  • ecolor (str, char, float or array, optional (default: “k”)) – Edge color. If ecolor=”groups”, edges color will depend on the source and target groups, i.e. only edges from and toward same groups will have the same color.

  • max_esize (float, optional (default: 5.)) – If a custom property is entered as esize, this normalizes the edge width between 0. and max_esize.

  • threshold (float, optional (default: 0.5)) – Size under which edges are not plotted.

  • proj (cartopy.crs object, optional (default: cartesian plane)) – Projection that will be used to draw the map.

  • all_geodata (bool, optional (default: True)) – Whether all the data contained in geodata should be plotted, even if graph contains only a subset of it.

  • axis (matplotlib axis, optional (default: a new axis)) – Axis that will be used to plot the graph.

  • **kwargs (dict) – All possible arguments from draw_network().