API reference¶

The full public API, generated from the source docstrings. Everything here is available directly on the acadgis namespace after import acadgis as agis.

Boundaries¶

acadgis.load_boundaries ¶

load_boundaries(country: str, level: Union[str, int] = 'country', *, within: Optional[str] = None, download: bool = True) -> gpd.GeoDataFrame

Load administrative boundaries for country at level.

Parameters¶

country: Country name, e.g. "Bangladesh". level: Friendly level name ("country", "division"/"state", "district", "upazila" …) or GADM integer 0-4. within: Optional parent-region name to subset by (e.g. all districts within the "Dhaka" division). Uses fuzzy name matching. download: If True (default), fall back to a live GADM download when the data is not bundled or cached.

Returns¶

geopandas.GeoDataFrame in EPSG:4326.

Maps¶

acadgis.plot ¶

plot(gdf: GeoDataFrame, *, column: Optional[str] = None, palette: Optional[str] = None, theme: Union[str, Theme] = 'academic', ax=None, title: Optional[str] = None, highlight: Optional[Union[str, Sequence[str]]] = None, labels: bool = False, legend: bool = False, north_arrow=True, scale_bar=True, graticule: bool = True, border='solid', figsize=(8, 8), pad: float = 0.05)

Plot a styled administrative map.

Without column each region gets its own palette colour (the qualitative 'atlas' look of the reference figure). With a categorical column regions are coloured by category. Use :func:choropleth for numeric data.

Decoration arguments (north_arrow, scale_bar, border) accept: True/False (on/off with defaults), a style string (e.g. north_arrow="rose"), or a dict of options for full control, e.g.::

north_arrow={"style": "rose", "size": 0.15, "color": "#1b4332",
             "loc": (0.9, 0.85)}
scale_bar={"style": "stepped", "length_km": 100, "loc": (0.07, 0.05)}
border={"style": "checker", "checker_size": 0.04, "color": "#2a2a2a"}

acadgis.choropleth ¶

choropleth(gdf: GeoDataFrame, data: Union[DataFrame, dict], *, on: Optional[str] = None, value: Optional[str] = None, key: Optional[str] = None, palette: str = 'viridis', theme: Union[str, Theme] = 'academic', ax=None, title: Optional[str] = None, scheme: Optional[str] = None, k: int = 5, legend: bool = True, legend_label: Optional[str] = None, labels: bool = False, north_arrow=True, scale_bar=True, graticule: bool = True, border='solid', figsize=(8, 8), pad: float = 0.05, missing_color: str = '#dddddd', match_threshold: float = 80.0)

Join a data table to boundaries by name and draw a choropleth.

Parameters¶

data: A DataFrame or {name: value} dict of values to map. on: Boundary name column to join on (defaults to the deepest NAME_*). value: Column in data holding the numeric value (required for DataFrame). key: Column in data holding region names (defaults to first column). scheme: Optional mapclassify scheme name ('quantiles', 'equal_interval', 'natural_breaks', 'fisher_jenks' …). If None, a continuous ramp.

acadgis.points ¶

points(ax, data, *, lon='lon', lat='lat', label=None, value=None, color='#222222', cmap='viridis', size=25, size_by=None, size_range=(15, 220), marker='o', edgecolor='white', linewidth=0.6, fontsize=7, text_color=None, dx=0.0, dy=0.0, halo=True, legend=False, legend_label=None, zorder=12)

Overlay point markers (study sites, sampling locations, capitals).

data may be a DataFrame (lon/lat columns, optional label), a {name: (lon, lat)} dict, or a list of (lon, lat) tuples.

For collected data, pass value= (a column name or array) to colour markers by value (graduated symbols, with an optional legend colorbar), and/or size_by= to scale marker area by value (proportional symbols). Returns the Axes.

Study-area layouts¶

acadgis.study_area ¶

study_area(country: str, steps: Optional[Sequence[Tuple[str, str]]] = None, *, template: str = 'cascade', terrain: bool = False, highlight_style: str = 'overlay', highlight_color: str = '#d6263b', highlight_edge: Optional[str] = None, highlight_alpha: float = 0.3, highlight_width: float = 2.0, links: bool = True, link_color: Optional[str] = None, link_width: float = 1.6, link_style: str = '-', box: bool = True, graticule=True, graticule_interval=None, north_arrow=True, scale_bar=True, uniform_panels: bool = True, width_ratios=None, height_ratios=None, wspace=None, hspace=None, figsize=None, palette: str = 'spectral', detail_palette: str = 'pastel', cmap: str = 'terrain', suptitle: Optional[str] = None, download: bool = True)

Build a multi-panel study-area figure from a preset template.

Highlight highlight_style ∈ {overlay, rect, circle}. graticule and graticule_interval (and north_arrow/scale_bar) accept a scalar (all panels) or a per-panel list. uniform_panels=True keeps panel boxes the same size (no shrink-to-aspect). See module docstring for the rest.

acadgis.StudyArea ¶

Build a multi-panel study-area figure for a country.

Example¶

sa = StudyArea("Iraq").zoom_into("Babil") fig = sa.figure() sa.save("study_area.png", dpi=300)

zoom_into ¶

zoom_into(region: str, *, detail_level: Optional[Union[str, int]] = None)

Choose the region to highlight & zoom into.

detail_level optionally adds a third panel showing that region's sub-divisions (e.g. districts within a division).

figure ¶

figure(*, figsize=(14, 8), suptitle: Optional[str] = None, arrows: bool = True)

Render the figure and return the matplotlib Figure.

save ¶

save(path, *, dpi: int = 300, **kwargs)

Save the (already-built or freshly-built) figure to path.

World maps¶

acadgis.load_world ¶

load_world() -> gpd.GeoDataFrame

Load bundled world country boundaries (Natural Earth 110m, EPSG:4326).

Columns: NAME_0 (country), GID_0 (ISO-A3), CONTINENT.

acadgis.highlight_country ¶

highlight_country(country: str, *, world: Optional[GeoDataFrame] = None, color: Optional[str] = None, context_color: Optional[str] = None, ocean_color: str = '#eef4fb', theme: Union[str, Theme] = 'academic', ax=None, title: Optional[str] = None, label: bool = True, graticule: bool = True, figsize=(13, 7))

Plot a world map with country filled in a highlight colour.

Returns the matplotlib Axes.

acadgis.world_locator ¶

world_locator(country: str, *, theme: Union[str, Theme] = 'academic', color: Optional[str] = None, figsize=(15, 7), suptitle: Optional[str] = None, zoom_pad: float = 1.2)

Two-panel figure: world map (country marked) -> zoomed country.

Returns the matplotlib Figure.

Terrain & drainage¶

acadgis.load_dem ¶

load_dem(area, *, buffer=0.0, max_size: int = 1400, clip: bool = True, download: bool = True) -> DEM

Download & mosaic a Copernicus GLO-30 DEM for a study area.

Parameters¶

area: country/region name, a (minx,miny,maxx,maxy) bbox, or a GeoDataFrame. buffer: degrees of padding to add around the area. max_size: cap on the longer raster dimension (downsamples large areas so plotting stays fast). clip: if True and area has a polygon, mask elevations outside it to nan.

acadgis.relief ¶

relief(dem: DEM, *, ax=None, cmap: str = 'terrain', hillshade: bool = True, blend: float = 0.55, azimuth: float = 315, altitude: float = 45, vert_exag: float = 0.0008, legend: bool = True, legend_label: str = 'Elevation (m)', title: Optional[str] = None, graticule: bool = True, north_arrow=True, scale_bar=True, ocean_color: Optional[str] = None, sea_level: float = 0.0, vmin: Optional[float] = None, figsize=(9, 9), theme='academic')

Plot a hypsometric (elevation-tinted) + hillshaded relief map.

Set ocean_color (e.g. "#cce5f0") to render elevations at/below sea_level — and the area outside the data — as a realistic sea, so the topography reads clearly down to the coast. Returns the matplotlib Axes.

acadgis.hillshade ¶

hillshade(dem: DEM, *, azimuth: float = 315, altitude: float = 45, vert_exag: float = 0.0008) -> np.ndarray

Return a 0–1 hillshade (shaded-relief) array from a DEM.

acadgis.drainage ¶

Drainage networks derived from a DEM (flow accumulation → stream lines).

This reproduces the "stream order" hydrology look (e.g. the Ethiopia DEM with its branching drainage). Streams are extracted with :mod:pysheds and returned as a GeoDataFrame whose line widths can be weighted by flow accumulation.

Requires the optional extra: pip install "acadgis[drainage]" (pysheds).

drainage ¶

drainage(dem, *, threshold: int = 500)

Extract a stream network from a :class:acadgis.DEM.

threshold is the minimum number of upstream cells for a pixel to count as a channel (smaller → denser network). Returns a GeoDataFrame of LineStrings (EPSG:4326) with an acc column (flow accumulation, a proxy for stream size/order).

add_streams ¶

add_streams(ax, streams, *, by_order: bool = True, color='#2b7bba', width=0.4, max_width=2.4, alpha=0.9, zorder=7)

Plot a drainage network on ax, optionally weighting line width by flow accumulation (by_order).

acadgis.add_streams ¶

add_streams(ax, streams, *, by_order: bool = True, color='#2b7bba', width=0.4, max_width=2.4, alpha=0.9, zorder=7)

Plot a drainage network on ax, optionally weighting line width by flow accumulation (by_order).

Rivers & hydrology¶

acadgis.load_rivers ¶

load_rivers(scale: str = '50m', download: bool = True) -> gpd.GeoDataFrame

Natural Earth river centerlines (EPSG:4326).

scale="50m" is bundled/offline; "10m" is denser (downloads & caches on first use, falls back to 50m offline). Has a scalerank column (lower = larger river) used to weight line widths.

acadgis.load_lakes ¶

load_lakes(scale: str = '50m', download: bool = True) -> gpd.GeoDataFrame

Natural Earth lakes / water bodies (EPSG:4326).

acadgis.add_rivers ¶

add_rivers(ax, area=None, *, source='ne', rivers=None, scale='50m', osm_kinds=('river', 'canal'), color=RIVER_COLOR, by_order=True, width=0.8, max_width=2.6, alpha=0.95, zorder=6, labels=False, label_color=None, label_size=7, download=True)

Overlay river centerlines on ax.

source: - "ne" (default): bundled Natural Earth (scale 50m/10m). - "osm": dense OpenStreetMap rivers/canals/streams (downloaded & cached) — the realistic delta look; width is set per kind.

area (name/bbox/GeoDataFrame) clips the rivers; if None, clips to the current axes extent. labels=True draws river names (italic).

acadgis.add_water ¶

add_water(ax, area=None, *, lakes=None, color='#a6cee3', edgecolor='#6aa6cf', linewidth=0.4, alpha=1.0, zorder=5, download=True)

Overlay lake / water-body polygons on ax.

acadgis.atlas ¶

atlas(area, *, level='country', neighbors=True, rivers='ne', rivers_scale='10m', osm_kinds=('river', 'canal'), land_color=LAND_COLOR, ocean_color=OCEAN_COLOR, neighbor_color='#e6e6e6', river_color=RIVER_COLOR, water_color=WATER_COLOR, labels=True, river_labels=True, cities=None, pad=0.18, title: Optional[str] = None, figsize=(9, 10), download=True, north_arrow=True, scale_bar=True, graticule=True, theme='academic')

A clean WorldAtlas-style figure with realistic water cartography.

Tinted study country over greyed, labelled neighbours; rivers (with names) and water bodies; optional cities points.

rivers="osm" uses the dense OpenStreetMap network (realistic delta / drainage detail, downloaded & cached); "ne" uses bundled Natural Earth. cities is a DataFrame (lon/lat/name) or {name: (lon,lat)}.

Returns the matplotlib Axes.

acadgis.fetch_osm_rivers ¶

fetch_osm_rivers(area, *, kinds=('river', 'canal'), clip=True, timeout=180, download=True, use_cache=True)

Download a dense OpenStreetMap river/canal/stream network for an area.

This is the high-fidelity option (e.g. the full delta) — it queries the Overpass API for waterway ways and returns a GeoDataFrame with a kind column (river/canal/stream/…). Results are cached. Add "stream" to kinds for maximum density (larger/slower).

Export¶

acadgis.save ¶

save(obj, path, *, dpi: int = 300, **kwargs)

Save a matplotlib Axes/Figure or a :class:StudyArea to path.

ax = agis.plot(gdf) agis.save(ax, "map.png", dpi=300)