Geographic API Reference

Complete reference for country visualization and geographic analysis functions

Contents

country_choropleth_map()

Create a professional 2D choropleth world map for country data visualization. This is the primary function for creating flat world maps with country-level data.

Signature

country_choropleth_map(
    data,
    country_col='country',
    value_col='value',
    title='Country Risk Distribution',
    backend='plotly',
    color_scale='RdYlGn_r',
    **kwargs
)

Parameters

Parameter Type Default Description
data pd.DataFrame Required DataFrame containing country and value data
country_col str 'country' Column name containing country codes or names
value_col str 'value' Column name containing values to visualize
title str 'Country Risk Distribution' Map title
backend str 'plotly' Visualization backend: 'plotly' or 'matplotlib'
color_scale str 'RdYlGn_r' Color scale for the visualization

Returns

fig : plotly.graph_objects.Figure or matplotlib.figure.Figure

Interactive or static figure object ready for display or export

Example

import riskplot
import pandas as pd

# Create sample data
data = pd.DataFrame({
    'country': ['USA', 'Germany', 'China', 'Japan'],
    'risk_score': [0.25, 0.18, 0.45, 0.22]
})

# Create map
fig = riskplot.country_choropleth_map(
    data,
    country_col='country',
    value_col='risk_score',
    title='Global Risk Assessment',
    width=1200,
    height=700
)

fig.show()

country_risk_globe()

Create an interactive 3D globe visualization for country risk data. Provides engaging 3D perspective perfect for presentations.

Signature

country_risk_globe(
    data,
    country='country',
    risk='risk_score',
    title='Global Country Risk Distribution',
    **kwargs
)

Parameters

Parameter Type Default Description
data pd.DataFrame Required DataFrame containing country and risk data
country str 'country' Column name for country codes (ISO-3 recommended)
risk str 'risk_score' Column name for risk values
title str 'Global Country Risk Distribution' Globe title
center_lon float 0 Center longitude for globe rotation
center_lat float 0 Center latitude for globe rotation

Example

# Create 3D globe
fig = riskplot.country_risk_globe(
    data,
    country='ISO_Code',
    risk='risk_score',
    title='Global Risk Assessment - 3D View',
    center_lon=0,
    center_lat=30
)

fig.show()

regional_risk_heatmap()

Create a heatmap showing countries grouped by regions for comparative analysis.

Signature

regional_risk_heatmap(
    data,
    region_col='region',
    country_col='country',
    value_col='value',
    title='Regional Risk Heatmap',
    figsize=(12, 8)
)

Parameters

Parameter Type Default Description
data pd.DataFrame Required DataFrame with region, country, and value data
region_col str 'region' Column name for regions
country_col str 'country' Column name for countries
value_col str 'value' Column name for values
title str 'Regional Risk Heatmap' Plot title
figsize tuple (12, 8) Figure size in inches

WorldMapPlot

Advanced class for creating customizable 2D world map visualizations with multiple backend support.

Constructor

WorldMapPlot(backend='plotly')

Methods

plot_choropleth()

Create a professional 2D choropleth world map.

plot_choropleth(
    data,
    country_col='country',
    value_col='value',
    title='Country Risk Map',
    color_scale='RdYlGn_r',
    show_borders=True,
    ocean_color='lightblue',
    missing_color='lightgray',
    **kwargs
)
add_annotations()

Add markers and annotations to the map.

add_annotations(
    annotations_data,
    lat_col='latitude',
    lon_col='longitude',
    text_col='text',
    marker_size=8,
    marker_color='red'
)
save()

Save the map to file in various formats.

save(filename, **kwargs)
show()

Display the interactive map.

show()

Advanced Example

# Advanced customization
world_map = riskplot.WorldMapPlot(backend='plotly')

# Create custom map
fig = world_map.plot_choropleth(
    data,
    country_col='country',
    value_col='risk_score',
    title='Advanced Risk Assessment',
    color_scale='Viridis',
    show_borders=True,
    ocean_color='lightsteelblue',
    width=1200,
    height=800
)

# Add city markers
cities = pd.DataFrame({
    'latitude': [40.7, 51.5, 35.7],
    'longitude': [-74.0, -0.1, 139.7],
    'text': ['New York', 'London', 'Tokyo']
})

world_map.add_annotations(cities, marker_color='red', marker_size=10)

# Save in multiple formats
world_map.save('risk_map.html')
world_map.save('risk_map.png')
world_map.show()

GlobeRiskPlot

Advanced class for creating interactive 3D globe visualizations with connection mapping capabilities.

Constructor

GlobeRiskPlot()

Methods

plot()

Create basic globe visualization.

plot(
    data,
    country='country',
    value='value',
    title='Global Risk Distribution',
    color_scale='RdYlGn_r',
    **kwargs
)
plot_connections()

Create globe with connection lines between countries.

plot_connections(
    data,
    src_country='source_country',
    tgt_country='target_country',
    strength='strength',
    src_lat='source_lat',
    src_lon='source_lon',
    tgt_lat='target_lat',
    tgt_lon='target_lon',
    title='Global Risk Connections',
    **kwargs
)
plot_time_series()

Create animated globe showing data evolution over time.

plot_time_series(
    data,
    country_col='country',
    value_col='value',
    time_col='date',
    title='Global Risk Over Time',
    **kwargs
)

Color Scales

Recommended color scales for different types of risk data:

RdYlGn_r

Use for: Risk scores, default for most risk visualizations

Scale: Red (high risk) → Yellow (medium) → Green (low risk)

RdYlGn

Use for: Performance scores, ESG ratings

Scale: Green (good) → Yellow (medium) → Red (poor)

Viridis

Use for: General data visualization, colorblind-friendly

Scale: Purple → Blue → Green → Yellow

Blues

Use for: Economic indicators, growth rates

Scale: Light blue → Dark blue

Country Code Support

RiskPlot automatically handles multiple country code formats:

ISO-3 Codes (Recommended)

USA, GBR, DEU, CHN, JPN, FRA, etc.

ISO-2 Codes

US, GB, DE, CN, JP, FR, etc.

Country Names

United States, United Kingdom, Germany, China, etc.

Common Abbreviations

UK → United Kingdom, USA → United States