abja_utils

A collection of reusable Python utilities for MIKE, FUNWAVE-TVD, and GIS workflows — the tools I reach for across projects, packaged so they install the same way on every machine.

Installation

pip install abja_utils

Optional extras:

pip install "abja_utils[basemap]"   # web-tile basemaps for wind-vector plots
pip install "abja_utils[dev]"       # test dependencies

ArcPy-based helpers (abja_utils.gis.arcpro) require a licensed ArcGIS install; see ArcPy setup below.

What's inside

Subpackages import lazily, so import abja_utils stays fast; access them as abja_utils.mike, abja_utils.gis, etc.

Quick start

MIKE — dfs2 to shapefile

Export one item at one timestep to a polygon shapefile (with x_index / y_index columns). The item can be given by name or index, and the timestep by index or timestamp string:

import abja_utils as au

au.mike.dfs2_to_shapefile(
    "model.dfs2", "surface.shp",
    item="Surface elevation",     # or an integer index
    timestep="2018-01-01 01:00",  # or an integer index
)

# Or work with the GeoDataFrame directly:
gdf = au.mike.dfs2_to_geodataframe("model.dfs2", item=0, timestep=0)

Convert a mesh to element polygons, or plot true-north wind vectors:

au.mike.mesh2poly("domain.mesh", "domain.shp")
au.mike.plot_wind_vectors("wind.dfs2", u_item=0, v_item=1, timestep=0)

Package a MIKE setup and every linked input into a self-contained zip:

report = au.mike.package_mike_setup("model.m21fm")
print(report.summary())

FUNWAVE — build a grid from a raster

import abja_utils as au

result = au.funwave.generate_grid(
    xmin=-127.0, xmax=-126.0, ymin=48.1, ymax=48.5,
    dphi=30/3600, dtheta=30/3600,
    raster_path="dem.tif", out_txt_path="depth.txt",
    export_shapefile=True, export_clipped_raster=True,
)
au.funwave.txt2tif("depth.txt", "depth.tif", result["Mglob"], result["Nglob"],
                   result["dphi"], result["dtheta"])

GIS

import abja_utils as au

au.gis.bbox2shp(-127, -126, 48, 49, "bbox.shp", epsg=4326)
au.gis.make_snap_raster(-127, -126, 48, 49, epsg=4326, res=0.01,
                        output_fname="snap.tif")
hull = au.gis.concave_hull(points, alpha=2.0, plot=True)

from abja_utils.gis.nonna import parse_file
gdf = parse_file("nonna10.txt")

Plotting style

Importing the package applies its matplotlib style globally — Times New Roman, inward ticks, and a curated colour cycle — so every figure shares one look, including the plots produced by mike.plot_wind_vectors, mike.contourf, and gis.concave_hull. Use subplots for figures sized in centimetres:

import abja_utils as au
fig, ax = au.subplots(figwidth=16, figheight=12)  # sizes in centimetres
ax.plot(x, y, color=au.Colors.blue2)

au.use_style(font_family="Arial")   # re-apply / customise the style if needed

ArcPy (optional)

abja_utils.gis.arcpro bridges to a licensed ArcGIS Pro install from a standalone Python (matching major.minor version). Install the bridge with:

from abja_utils.gis import install_arcpy
install_arcpy()   # Windows only

See src/abja_utils/data/README.md for details.

Development

pip install -e ".[dev]"
pytest

License

MIT — see LICENSE.