Maps

D3Blocks.maps(df=None, size=10, color='#0981D1', opacity=0.8, label='', countries=None, country_names=None, country_colors=None, country_opacity=None, country_values=None, map_name: str = 'world', include_overseas: bool = True, cmap='Set2', title: str = 'Maps - D3blocks', filepath: str = 'maps.html', figsize=None, showfig: bool = True, overwrite: bool = True, notebook: bool = False, save_button: bool = True, show_controls: bool = True, dark_mode: bool = True, return_html: bool = False, reset_properties: bool = True)

Maps block.

Interactive world map with optional country coloring (choropleth) and lon/lat markers. Country coloring follows the same idea as the worldmap package: pass names (fuzzy-matched to the map) plus optional colors, opacity, or numeric values.

Parameters:

  • df (pd.DataFrame or None) – Marker data with columns lon, lat, and optionally label, size, opacity, color. None or empty → country-only map (no markers).

  • size – Marker defaults (see previous docs). Used when building node properties.

  • color – Marker defaults (see previous docs). Used when building node properties.

  • opacity – Marker defaults (see previous docs). Used when building node properties.

  • label – Marker defaults (see previous docs). Used when building node properties.

  • countries (dict or None) –

    Explicit country styling::
    {‘World’: {‘color’: ‘#D3D3D3’, ‘opacity’: 0.6, ‘line’: ‘none’, ‘linewidth’: 1},

    ’Netherlands’: {‘color’: ‘#000FFF’, ‘opacity’: 0.8}}

    Ignored when country_names is provided.

  • country_names (list of str or None) – Countries to color (worldmap-style). Fuzzy-matched to GeoJSON names.

  • country_colors (list of str or None) – Hex colors or category labels for each name (via cmap).

  • country_opacity (float, list, or None) – Opacity per country. If None and country_values is set, opacity is scaled from the values.

  • country_values (list of float or None) – Numeric values → sequential colors/opacity.

  • map_name (str, (default: 'world')) –

    Map geometry to load.

    • 'world': country-level world map

    • Any country name or ISO code for admin-1 regions, e.g. 'netherlands', 'NL', 'germany', 'US', 'japan'

    Full catalog: Maps.list_map_names() (~240 regional maps). Region names: Maps.list_country_names(map_name).

  • include_overseas (bool, (default: False)) – For regional maps, keep distant overseas territories (e.g. Caribbean islands for the Netherlands). When False, only the main landmass cluster is shown so the map fills the view.

  • cmap (str) – Colormap for markers and/or country colors.

  • title – Standard figure options.

  • filepath – Standard figure options.

  • figsize – Standard figure options.

  • showfig – Standard figure options.

  • overwrite – Standard figure options.

  • notebook – Standard figure options.

  • save_button (bool, (default: True)) – Show Save (SVG) control.

  • show_controls (bool, (default: True)) – Top bar + side panels.

  • dark_mode (bool, (default: True)) – Default theme.

  • return_html (bool, (default: False)) – Return HTML string.

  • reset_properties (bool, (default: True)) – Rebuild node properties each call.

Returns:

  • HTML string if return_html else None.

  • Side effects (sets node_properties, edge_properties, config.)

Examples

>>> from d3blocks import D3Blocks
>>> d3 = D3Blocks()
>>> # Markers only
>>> df = d3.import_example('surfspots')
>>> d3.maps(df)
>>>
>>> # Country coloring (worldmap-style) without markers
>>> d3.maps(country_names=['Netherlands', 'France', 'Germany'], cmap='Set1')
>>>
>>> # Regional map: Dutch provinces
>>> d3.maps(country_names=['Zeeland', 'Overijssel', 'Flevoland'],
...         map_name='netherlands', cmap='Set1')
>>>
>>> # Countries + values (opacity scaled) + markers
>>> d3.maps(df,
...         country_names=['Netherlands', 'Australia', 'USA'],
...         country_values=[10, 5, 20],
...         cmap='Blues')
>>>
>>> # Explicit countries dict
>>> d3.maps(df, countries={
...     'World': {'color': '#D3D3D3', 'opacity': 0.4, 'line': 'none', 'linewidth': 0.1},
...     'Netherlands': {'color': '#000FFF', 'opacity': 0.5},
...     'France': {'color': '#FFA500', 'opacity': 1, 'line': 'dashed', 'linewidth': 2},
... })
>>>
>>> # Stepwise workflow
>>> d3 = D3Blocks(chart='maps', frame=False)
>>> d3.set_node_properties(df)
>>> d3.set_edge_properties(country_names=['Netherlands', 'Belgium'], cmap='Set2')
>>> d3.show()

Input Data (Maps)

The input dataset is a DataFrame that contains the lat and lon coordinates. More features can be added such as label, size opacity.

#        lat    lon          label  size
# 0    -82.9  135.0     Antarctica     4
# 1    -54.8  -68.3  South America     4
# 2    -53.8  -67.7  South America     1
# 3    -53.2  -70.9            NaN     2
# 4    -52.4  -71.0  South America     2
#    ...    ...            ...   ...
# 9408  69.6   19.0            NaN     1
# 9409  70.0   23.3         Europe     1
# 9410  70.4   29.5         Europe    13
# 9411  76.3 -100.1  North America     1
# 9412  78.2   15.6         Europe     3

Charts (Maps)