How to read an AGS 4 file before you trust an import
AGS 4 is an open, plain-text standard for ground-investigation data, so you do not need any vendor's software to see what is in a file. This guide is for anyone who has been handed an .ags file — from a client, a lab, or an old project — and wants to check it before it goes near a model. It is software-independent: everything here you can verify in a text editor.
1 · What the file is made of
An AGS 4 file is a set of groups, each a small table with a header (HEADING), units (UNIT), data types (TYPE) and rows (DATA). A handful of groups appear in almost every ground-investigation file:
| Group | What it holds |
|---|---|
| PROJ | The job itself: project number, name, site. One per file. |
| TRAN | The transaction header: who produced the file, when, and the AGS version. |
| LOCA | Borehole and trial-pit locations: ID, co-ordinates, ground level, final depth. |
| GEOL | The stratum in each interval: top and base depth, geology, description. |
| ISPT | Standard Penetration Test readings: depth, blows per increment, the N value. |
| SAMP | Samples taken: depth, type, reference, recovery. |
2 · AGS 4 and DIGGS are not the same thing
Both are open transfer formats and TerraBrains reads both, but they look different. AGS 4 is the plain-text, group-and-row format above; DIGGS is XML — it opens with tags, not GROUP rows. If your file is XML, it is DIGGS; the same boreholes, strata and SPT are in it, just structured differently. The checks below apply to both — only the way you read them changes.
3 · The groups that carry the factual record
Four groups carry the core of a borehole record. When you drop the file into TerraBrains, each is mapped to a part of the log — and anything that does not line up is flagged for your review, never imported silently.
| Group | The core it carries | Watch for |
|---|---|---|
| LOCA | One row per hole: where it is, its level, how deep it went. | If the hole count here is short, the export was scoped to a selection. |
| GEOL | The layers down each hole, top and base depth. | Layer boundaries are depths below ground level, not elevations. |
| ISPT | The SPT series: a row per test, with the N value. | Watch the blows-per-increment columns; a seated reading is not a full test. |
| SAMP | What was sampled, where, and how much was recovered. | Pairs with the lab groups (LLPL, CMPG, GRAG) when those are present. |
The lab groups — LLPL (tests by sample), CMPG (grading), GRAG (particle-size) and PTIM (in-situ tests) — ride along where present. The mapping happens in your browser; the file is not uploaded.
4 · Four quick checks that catch a bad export
It opens as plain text
AGS 4 is not binary. Open it in any editor: you should see GROUP, HEADING, UNIT, TYPE and DATA rows. If it is unreadable or a different structure, it is not AGS 4 — it may be a DIGGS XML file, which we also read, or a proprietary format we do not.
The four factual groups are present
For a borehole record you want LOCA, GEOL, ISPT and SAMP. A file with only ABBR, DICT and PROJ is a library or template export — the lookup lists, not the job — and it carries no boreholes.
One hole reads end to end
Find the deepest hole in LOCA, then follow its ID through GEOL and ISPT. Do the depths join up — layer bases to the final depth, SPT readings inside the layers? A hole that stops early usually means the export filtered it.
The grid and datum are stated
Co-ordinates and levels are meaningless without their reference. Confirm the file records the grid you expect and that ground levels sit on the same datum as your issued drawings before you map anything.
5 · Then let the software check it too
Your eye and the importer check different things. You confirm the right holes are there and the levels sit on the right datum; the importer confirms every column maps and flags what it cannot read. Run both. Drop the file in and see the boreholes, layers and SPT results we read — before you sign up, and before anything is saved.
Have a file in hand? See what we read, check it first with the free AGS validator, or read the gINT-specific guide.