MESQUAL 307: Country Plotter Utility Module¶
This notebook demonstrates a simple but useful module to project countries from the country library to a folium map.
Module Use-Case¶
There are two primary use-cases for the module:
Using it as a library with geo data for countries. Using it to project countries that are not the focus of your study (e.g. neighboring countries) in a neutral color to your map.
Whenever you are creating a KPI Map for your study (e.g. a map with European prices or anything alike), you often want to project the countries that are not part of your study itself (e.g. neighboring countries) to the map as well. You can, of course, also use Folium's native tile layers. However, those are often overloaded with unnecessary texts and geo information that distracts from your actual data. The module enables you to include other countries that are not the focus of your study, without distracting from the information you are trying to communicate.
Setup¶
First, we need to set up the environment. If you are on Colab, the first cell will clone and install all dependencies. You will have to restart the session afterwards and continue with cell 2. If you are in a local environment, make sure that you have followed the Getting started steps in the README, so that mesqual and all requirements are installed.
import os
if "COLAB_RELEASE_TAG" in os.environ:
import importlib.util
def is_module_available(module_name):
return importlib.util.find_spec(module_name) is not None
if os.path.exists("mesqual-vanilla-studies") and is_module_available("mesqual"):
print("✅ Environment already set up. Skipping installation.")
else:
print("🔧 Setting up Colab environment...")
!git clone --recursive https://github.com/helgeesch/mesqual-vanilla-studies.git
%cd mesqual-vanilla-studies/
!pip install git+https://github.com/helgeesch/mesqual -U
!pip install git+https://github.com/helgeesch/mesqual-pypsa -U
!pip install git+https://github.com/helgeesch/captain-arro -U
!pip install -r requirements.txt
print('✅ Setup complete. 🔁 Restart the session, then skip this cell and continue with the next one.')
else:
print("🖥️ Running locally. No setup needed.")
Running locally, let's continue.
import os
if "COLAB_RELEASE_TAG" in os.environ:
import sys
sys.path.append('/content/mesqual-vanilla-studies')
os.chdir('/content/mesqual-vanilla-studies')
else:
def setup_notebook_env():
"""Set working directory to repo root and ensure it's in sys.path."""
import os
import sys
from pathlib import Path
def find_repo_root(start_path: Path) -> Path:
current = start_path.resolve()
while current != current.parent:
if (current / 'vanilla').exists():
return current
current = current.parent
raise FileNotFoundError(f"Repository root not found from: {start_path}")
repo_root = find_repo_root(Path.cwd())
os.chdir(repo_root)
if str(repo_root) not in sys.path:
sys.path.insert(0, str(repo_root))
setup_notebook_env()
try:
from mesqual import StudyManager
except ImportError:
raise ImportError("❌ 'mesqual' not found. If you're running locally, make sure you've installed all dependencies as described in the README.")
if not os.path.isdir("studies"):
raise RuntimeError(f"❌ 'studies' folder not found. Make sure your working directory is set to the mesqual-vanilla-studies root. Current working directory: {os.getcwd()}")
print("✅ Environment ready. Let’s go!")
✅ Environment ready. Let’s go!
import os
import folium
from mesqual.utils.folium_utils import set_background_color_of_map, MapCountryPlotter
from vanilla.notebook_config import configure_clean_output_for_jupyter_notebook
from vanilla.conditional_renderer import ConditionalRenderer
configure_clean_output_for_jupyter_notebook()
renderer = ConditionalRenderer()
Basic Usage¶
The MapCountryPlotter class provides a simple interface to add country geometries to folium maps. It handles the loading of GeoJSON data and provides methods to easily add countries to feature groups.
# Create a basic map centered on Europe
m = folium.Map(location=[46, 10], zoom_start=4.75, tiles=None)
# Set a clean white background
m = set_background_color_of_map(m, color='#ffffff')
# Initialize the plotter (uses default geojson)
plotter = MapCountryPlotter()
# Create a feature group for our countries
countries_fg = folium.FeatureGroup(name="Selected Countries")
# Add some countries with default styling
plotter.add_countries_to_feature_group(
countries_fg,
countries=["DE", "FR", "IT", "ES"],
)
countries_fg.add_to(m)
# Let's add layer control
folium.LayerControl().add_to(m)
renderer.show_folium(m)
The plotter looks up countries using standard ISO country codes (ISO-A2, ISO-A3, SOV-A3). This is particularly useful when working with data that uses these standard codes.
Custom Styling¶
One of the key benefits of using this plotter is the ability to customize the styling of countries. This is useful when you want to highlight specific regions or apply styling based on data values.
# Create a map
custom_map = folium.Map(location=[60, 14], zoom_start=5, tiles=None)
# Create feature group with custom styling
nordic_fg = folium.FeatureGroup(name="Nordic Countries")
# Add Nordic countries with blue styling
plotter.add_countries_to_feature_group(
nordic_fg,
countries=["NOR", "SE", "FI", "DK"],
style={
"fillColor": "#3388ff",
"color": "black",
"weight": 1,
"fillOpacity": 0.4
}
)
nordic_fg.add_to(custom_map)
folium.LayerControl().add_to(custom_map)
renderer.show_folium(m)
The style dictionary accepts the same parameters as Folium's GeoJSON styling. You can customize:
fillColor: The color to fill the countrycolor: The border colorweight: The border thicknessfillOpacity: The transparency of the fill color
This flexibility allows you to create visually distinct regions or apply data-driven styling, which is perfect for market zonal analysis.Excluding Countries
Working with Individual Countries¶
Sometimes you need more direct access to country geometries. The `get_geojson_for_country method allows you to retrieve the raw GeoJSON for specific processing.
# Get GeoJSON for Germany
germany_gdf = plotter.get_geojson_for_country("DE")
# Create a focused map
germany_map = folium.Map(location=[51, 10], zoom_start=6, tiles=None)
# Add Germany with custom styling
folium.GeoJson(
germany_gdf,
style_function=lambda x: {
"fillColor": "#ff0000",
"color": "black",
"weight": 2,
"fillOpacity": 0.6
}
).add_to(germany_map)
renderer.show_folium(germany_map)
This direct access to country GeoJSON is useful when you need to:
- Perform spatial analysis with country boundaries
- Combine country shapes with other geometries
- Add custom interactive elements to specific countries
- Calculate centroids or other geometric properties for positioning labels or markers
Feel free to combine this module with the map created in any of the previous modules (mesqual_303, mesqual_304, mesqual_305, mesqual_306) to show neighboring countries in the same map.
Conclusion¶
The MapCountryPlotter module is a simple but powerful tool for extending clean, informative geographical visualizations. By providing an easy way to add country shapes to your maps, it helps you to a) provide geo shapes for countries; b) focus on communicating your data rather than relying on the rather distractive default tile_layers in folium.