Drop-in for python-ags4¶

Available in: Python (by design — the whole point is the pandas-shaped python-ags4 surface; see the capability matrix)

Already have code built on python-ags4? Swap the import for laterite.compat and the existing AGS4_to_dataframe call works unchanged — same (tables, headings) 2-tuple, same pandas frames.

# EX11 — the python-ags4 drop-in: laterite.compat is a faithful AGS4_to_dataframe shim.
from laterite import compat as AGS4

result = AGS4.AGS4_to_dataframe("examples/sample_site.ags")

# python-ags4 returns a (tables, headings) 2-tuple; tables maps group -> pandas DataFrame.
print(type(result), list(result[0])[:5])
print(result[0]["LOCA"].shape)

assert isinstance(result, tuple) and len(result) == 2 and "LOCA" in result[0]

<class 'tuple'> ['PROJ', 'TRAN', 'UNIT', 'TYPE', 'ABBR']
(16, 7)

from laterite import compat as AGS4 aliases the shim to the name python-ags4 code already uses, so AGS4.AGS4_to_dataframe(path) returns the faithful 2-tuple: result[0] maps each group code to a pandas DataFrame (including the metadata groups TRAN/UNIT/TYPE/ABBR), and result[1] carries the heading metadata. The import-swap is the migration — no call-site edits.

The shim is faithful by design: it mirrors python-ags4's verdicts and is gated against that library's own test suite. The pandas backend is the default, so downstream df.shape, indexing, and .to_numeric code keeps working.

It's also faster. AGS4_to_dataframe reads a Rust-built Arrow table (no per-cell Python boxing) and materialises pandas through DuckDB — ~2× faster than python-ags4 on the pyarrow-free [compat] install, more with the pyarrow accelerator. The frames are object dtype by default, byte-identical to python-ags4 today. Want pandas' Arrow-backed str dtype (what python-ags4 returns on pandas 3)? Install [compat,pyarrow] and pass string_dtype="string" (or set_string_dtype("string") / LATERITE_COMPAT_STRING_DTYPE=string). See Dependency shape.

Gotcha — the pandas frames need the [compat] extra: pip install laterite[compat]. Importing laterite.compat without it is safe, but a pandas-backed call raises ModuleNotFoundError with install guidance. The base pip install laterite ships polars + duckdb only.

When you're ready to leave the shim behind, laterite.read() gives you born-typed frames directly — no .cast(), no pd.to_numeric.