An Introduction to the AGS Data Format
The AGS data format is a standard, and associated file format, for the exchange of geotechnical and geo-environmental data. The standard is maintained by the Association of Geotechnical and Geo-Environmental Specialists in the UK. It is used widely in the UK, but variations of the standard are also used elsewhere around the world.
AGS Versions
The AGS Data Management Working Group manage the evolution of the data format, and have done for decades, so there are many iterations and versions of the standard. For practical purposes though, broadly speaking, you need to know about AGS 3 and AGS 4. Legacy projects may be stored as AGS 3, and most commercial geotechnical software can handle this to some extent. Most modern systems are working to a sub-version of AGS 4. The main difference is that trial pit and borehole location IDs are referred to as HOLE_ID in AGS 3, and as LOCA_ID in AGS 4.
At the time of writing this article the most up-to-date production version of the AGS 4 standard is 4.1.1. However, practically-speaking, most people are working to AGS 4.0.4. The differences will be minor variations in the fields and field definitions within the various data groups.
What can you record in an AGS data file?
An AGS file can be used to record and transfer trial pit and borehole logging data, plus lots of other aspects of ground and site investigation, both geotechnical and geo-environmental. There is scope to record things like: project metadata; trial pit and borehole location, type and hole construction; geological field descriptions and legend codes; samples, in-situ and laboratory tests; installation and monitoring.
What is the file format of an AGS data file?
AGS data files are just text files with a .ags file extension, for example Gasworks_Site.ags and you can open them using a text editor such as notepad. Within the text file the data is arranged in tables, or ‘groups’ as they are known in the AGS standard. Each table of data is in a sort of CSV (comma-separated) format.
AGS Data Groups
You can think of an AGS group as a data table, each representing one type of entity within the dataset. Each data group has a four-letter name or code; for example the ‘GEOL’ group holds the geological field descriptions within a borehole log. There are many groups defined in the AGS standard.
Within the AGS file each group is formatted as a block of CSV (comma-separated) data. Below is a typical example of an AGS data group called ‘BKFL’ (backfill data).
The first four rows of a data group are the ‘group header’ rows GROUP, HEADING, UNIT and TYPE which define the structure and nature of the table of data.
Row one stores the group name. Note that it only has only two columns of data. All of the subsequent rows must have the same number of columns or fields.
Row two stores the HEADING values – i.e. the column names. To ensure they are always unique across a dataset, these column names are pre-fixed with the group name and an underscore, e.g. ‘BKFL_’.
Row three stores the UNITs for each column of data, for example ‘m’ for metres.
Row four stores the TYPE of each column of data; for example a value of ‘2DP’ means the data column should store a decimal number, formatted to two decimal places.
The actual data values for the group will begin from line five, and are labelled as ‘DATA’.
Certain data groups are mandatory within a valid AGS file, for example the PROJ group, and some metadata groups such as TRAN, UNIT and ABBR. The details of the mandatory groups will be covered in a separate article.
A Note on IDs
For an AGS file to function it’s important to understand what the ID fields mean. If a field has a TYPE value of ID then it means it holds a value that can used to link records from other data groups. In most datasets the most common ID is the borehole ID, called ‘LOCA_ID’.
A common cause of broken AGS files is where different ID schemes are used between data tables. The values in the ID fields must match exactly to be linked correctly, for example by commercial geotechnical software or databases.
Common Data Groups
Most AGS data files contain the same small subset of AGS data groups. Here are a few to be aware of.
PROJ
PROJ stores the high-level project metadata for the dataset (project ID, name, client, engineer, contractor, etc.). Every AGS file must have a PROJ data group, BUT it’s important to note that this should only contain a single DATA row. A typical PROJ data group looks like this.
LOCA
This group is the list of trial pit and / or borehole locations within the dataset. The group should contain one row per-location, and each row must have a unique value for the LOCA_ID column. A typical LOCA data row looks like this.
GEOL
This group contains the down-hole geological descriptions for a trial pit or borehole. Each row represents a single stratum, so each location can have multiple rows of data. A typical GEOL group looks like this (truncated, for illustration). Note the repetition of the LOCA_ID for each stratum.
Hatching patterns in the borehole logs are driven by the GEOL_LEG value. Click here for a list of typical GEOL_LEG codes and descriptions.
How to Create an AGS File
To create a complete, valid AGS file you really need dedicated geotechnical or borehole logging software, like Pebble Geo! Therefore, when specifying software for a project it is important to ensure that it has AGS support.
It is very important that any AGS data file you produce is a ‘valid’ AGS file, which means that it adheres to all of the rules laid out in the standard. This can be quite difficult, and non-valid files create problems. Files that don’t pass validation will be difficult for your clients to handle, as they may have problems loading them into their proprietary or commercial database systems. That said, if you're a Pebble Geo user, you'll find that it is very forgiving in terms of AGS import, and will only very rarely block the import of a non-valid file.
If you don’t have access to AGS-compatible software then you can construct a valid file using Excel or a text editor, although it will of course mean that you need to check carefully that all of the IDs, cross-references, metadata tables, field names, units, types etc. are accurately entered. The AGS offers a free AGS file validator, which can be very useful for identifying the issues in a problem AGS data file.
Need Some Help With AGS Data Files?
If you need any help with producing, fixing or importing an AGS data file using Pebble Geo just get in touch with us. We have a lot of experience in fixing non-valid data files from various sources!