AGS4 Developers Quickstart

Note

This is a quick guide intended to bring new developers whove never used ags up to speed.

Whats is AGS4 ?

AGS4 is a text file format and a data dictionary used for the exchange of GeoTechnical data. Its design and roots are spereasheets, and a way to share and serialise spreadsheet data, without sharing spreadsheet itself.

What does it smell like ?

Its “essentially” a set of concated CSV files, with each group representing a spreadsheet tab and its columns/rows.

The simple example below shows two groups, although on a real file there would be many more

  • the Project Info (PROJ) group, with one row of data
  • the Location / Test Points (LOCA) group with three rows
"GROUP","PROJ"
"HEADING","PROJ_ID","PROJ_ID","PROJ_ID","PROJ_CLNT"
"UNIT","","","",""
"TYPE","ID","X","X","X"
"DATA","Prj-AG","Acme Gasworks","Greenwich, London","Acme Enterprises"

"GROUP","LOCA"
"HEADING","LOCA_ID","LOCA_TYPE","LOCA_NATE","LOCA_NATN","LOCA_GL","LOCA_FDEP"
"UNIT","","","m","m","m","m"
"TYPE","ID","PA","0DP","0DP","2DP","1DP"
"DATA","TP1","RO","539277","179635","-20.35","3.5"
"DATA","TP2","RO","539245","179456","-23.35","2.1"
"DATA","TP3","RO","539299","179474","-20.22","2.9"

Note

Looks like CSV, but unlike a true csv, its not equal column length down the rows which is why most csv parsers can handle it.

What does it all mean ?

The first column are the DATA DESCRIPTORS, and basically describe what the row’s data means:

  • GROUP - indicates a new group (spreadsheet tab)
  • HEADING - the column headings for this group (column in a tab)
  • UNIT - the units for the columns, is there is one
  • TYPE - the column type, eg X for text or 2DP for two decimal places (the column formatting)
  • DATA - one or more data rows conforming to the TYPE (the lines of data after fixed header)
  • The HEADING, UNIT and TYPE are coolectively called the HEADER and define the column ? (to check)

Mysterious codes ?

The codes are defined, maintained and published by the AGS (here), and called the AGS4 Data Dictionary.

The data dictionary comprises a few parts and are pretty fixed to mean some things. This is one of the strength og ags in data interchange (see validator soon):

  • The list of four digit GROUP codes
    • eg PROJ for project details, SAMP for sample information
  • The HEADING codes which always start with the group code
    • eg SAMP_REF, SAMP_ID, SAMP_TYPE
  • A list of registered UNIT eg
    • km2 for square kilometre
    • lbf for pounds force
  • A TYPE which defined the format/type of data, eg
    • 2DP for 2 decimal points
    • X
    • DT for a date time type
    • Important is PA for abbrs (abbreviations)
  • ABBR (Abbreviations) for various HEADINGS
    • The TYPE PA means pick abbreviation eg - B for a Bulk Sample in SAMP_TYPE - PRELIM for a Relim in LOCA_STAT