Thematic Map

Thematic Map Creation Skill

This document is GeoCode's official cartographic specification for thematic mapping. As a GeoAgent, you MUST strictly follow every instruction in this document when producing any thematic map — no step may be skipped, abridged, or substituted with your own judgment.

You cannot directly operate the QGIS graphical interface; all thematic maps must therefore be produced through Python code.

Runtime Environment and Dependencies

Before mapping, confirm whether the following dependencies are installed in the user's Python environment. Do not install any library without asking the user first — clarify their environment setup before deciding on the installation approach.

The three Optional libraries are only needed when a reference explicitly calls for them (data classification, colormap / palette choices) — install them on demand, not upfront.

Producing a Thematic Map

This chapter walks you step by step through producing a high-quality, standards-compliant thematic map in Python. A thematic map combines several visual elements: a geographic frame (projection, extent, graticules), a data layer carrying the analytical content, context layers (boundaries, basemaps), and decorative elements (titles, legends, scale bars, north arrows).

How to Work Through This Document

One element at a time: read its reference, write its code, then move to the next. NEVER read all references up front. NEVER write the whole script in one pass.

Reading everything first floods your context and leads to a rushed, broken script. Read a bit, write a bit.

Run the script only once, after all the code is written — do NOT render the figure to check it after every element.

Commenting Conventions

The user reads, runs, and modifies every script you write — and well-placed comments are what make the script actually adjustable. Follow these commenting conventions in every script you produce.

• Annotate every adjustable map element parameter (title, legend, scale bar, colorbar, etc.) so the user knows exactly where to tweak the appearance.
• Comment the purpose of each major step in the script — what it does and why.

China Base Map (whole-China shortcut)

If the study area is the whole of China, do not build the frame by hand. The china_base module renders a standards-compliant China base map — national boundary, nine-dash line, province boundaries, coastline, maritime gradient, and a South China Sea inset — in one call, and returns a normal fig, ax.

For a whole-China map: read references/china-base-map.md and use create_china_map(...) in place of the next four sections (Establishing the Geographic Frame, Adding the Map Frame, Adding a Basemap, Adding the Study Area Boundary) — they are all handled for you. Then continue from Adding the Data Layers (overlay your data via draw_china) and finish as usual.

For any sub-national or non-China extent, ignore this and follow the general workflow below.

Establishing the Geographic Frame

Every map starts with two decisions: what region it shows (the extent) and how that region is projected onto the page. Make both before drawing anything else — the rest of the map hinges on them.

1. Find the data's lat/lon range. Use the ReadGeoData tool to read the input file's bounds.
2. Set the map extent — slightly larger than the data's lat/lon range, leaving a small margin on each side.
3. Choose a projection that suits the extent and your cartographic purpose. The wrong choice silently distorts distances, areas, or angles, so think this one through. If you know which projection you want but aren't sure how to construct it in Cartopy, look it up in references/cartopy-projection.md.

Every thematic map script opens with this scaffold — set the lon/lat bounds and projection parameters to match your map.

import sys
sys.dont_write_bytecode = True  # keep the folder clean — don't generate __pycache__ / .pyc files

import cartopy.crs as ccrs
import matplotlib.pyplot as plt

plt.rcParams["font.family"] = ["Times New Roman", "SimSun", "Songti SC", "Noto Serif CJK SC"]  # default fonts: English + Chinese serif fallbacks
plt.rcParams["axes.unicode_minus"] = False

lon_min, lon_max, lat_min, lat_max = 73.5, 135.1, 18.1, 53.6  # data's lon/lat bounds from ReadGeoData — replace with your own
lon_pad, lat_pad = (lon_max - lon_min) * 0.10, (lat_max - lat_min) * 0.10  # pad each side by 10% so data isn't pressed against the frame
extent = [lon_min - lon_pad, lon_max + lon_pad, lat_min - lat_pad, lat_max + lat_pad]

map_proj = ccrs.AlbersEqualArea(central_longitude=110, standard_parallels=(25, 47))  # pick a projected CRS that suits your map's region and purpose

fig, ax = plt.subplots(figsize=(10, 8), dpi=800, subplot_kw={"projection": map_proj})  # create the figure with the chosen projection
ax.set_extent(extent, crs=ccrs.PlateCarree())
ax.set_title("Map Title", fontsize=16, fontweight="bold", pad=12)

Reading Geographic Data

After the geographic frame is set, load the vector and raster data needed for this map using these two libraries.

import geopandas as gpd
import rioxarray as rxr

gdf = gpd.read_file("path/to/your.shp")                  # vector (.shp / .geojson / .gpkg)
da = rxr.open_rasterio("path/to/your.tif", masked=True).squeeze()  # raster (.tif / GeoTIFF); masked=True → nodata becomes NaN, squeeze() drops the single-band axis

Adding the Map Frame

After the geographic frame is set up, the next layer on the canvas is the map's frame — ticks, graticules, and (optionally) decorative edges that give spatial reference and a polished look.

Work through these elements:

1. Add latitude/longitude ticks and labels along the axes.
2. (Optional) Add graticules as light gridlines inside the map.
3. (Optional) Apply a GMT-style checkerboard frame for the map edges.

Required reading: read references/ticks-and-graticules.md in full before writing any code for this section. It covers the API choices, parameter recommendations, and common pitfalls for all three elements above.

Adding a Basemap (Optional)

A basemap is mainly decorative — it adds land, oceans, terrain, or satellite texture behind the data. Most thematic maps don't need one; add one only when the visual context genuinely helps.

If you add a basemap: read references/basemap.md — it covers the two one-call helpers, add_basemap (raster tiles: ocean / imagery / relief) and add_vector_basemap (a clean Natural Earth vector backdrop), and how to choose between them.