Bedrock

AGS4 is a standardized text file format specifically designed for exchanging geotechnical information between different software systems used in geotechnical engineering. It organizes borehole logs, laboratory test results, and field measurements into structured data tables with validation rules to ensure consistent data quality across the geotechnical industry.

Groups

In the AGS4 format, Groups are organizational containers that structure geotechnical data. Each Group represents a specific aspect of geotechnical investigation, for example, project information (PROJ), location details (LOCA), sample information (SAMP), or specific test types like Standard Penetration Tests (ISPT).

AGS4 Groups are organised in a hierarchical manner. Each sample (SAMP) belongs to a location (LOCA). Each location belongs to a project (PROJ).

Here’s a visual of the hierarchy of groups commonly found in an AGS4 file.

All Groups Hierarchy Tree

While AGS defines a load of groups, not all of them are used in every project. For reference, here is the full hierarchy tree of all groups.

Code

viewof groupSearch = Inputs.search(ags4, {
  placeholder: "Search groups..."
})

Code

viewof groupTable = Inputs.table(groupSearch, {
  format: { headings: (d) => d.map((h) => h.heading).join(", ") },
  multiple: false,
  layout: "auto"
})

Code

ags4 = FileAttachment("ags4_data_dictionary.json").json()

Headings

Headings are the specific data fields (i.e. the columns) within each group that define individual data items. Each heading represents a specific piece of information that can be recorded during geotechnical investigations, such as sample depth, moisture content, or test result values

Headings follow a standardized naming pattern, typically beginning with the group name as a prefix (e.g., “PROJ_ID” for project identifier in the PROJ group). Some headings are marked as required (*R or R), indicating that they must be populated in a valid AGS file to maintain data integrity. Headings include additional information like units of measurement, descriptions, and example values to help users understand their purpose.

Code

groupTable ? md`### ${groupTable.group_name}\n${groupTable.group_description}` : md`### Select a group in the table above to view its headings.`

Code

groupTable
  ? Inputs.table(groupTable.headings, {
      layout: "auto",
      columns: ["heading", "description", "type", "unit", "example"],
      format: {
        type: (d) => (d in types ? types[d] : d),
        status: (d) => {
          switch (d) {
            case "*":
              return "KEY";
            case "R":
              return "Required";
            default:
              return "";
          }
        }
      }
    })
  : md`In the table above, select a group on the left side to view its headings here.`

Code

types = ({
  ...Object.fromEntries(
    Array.from({ length: 5 }, (_, i) => i).map((i) => [
      `${i}DP`,
      `Value with ${i} required decimal places`
    ])
  ),
  ...Object.fromEntries(
    Array.from({ length: 4 }, (_, i) => i).map((i) => [
      `${i}SF`,
      `${i} sign. figures`
    ])
  ),
  DT: "Datetime",
  T: "Time elapsed",
  X: "Text",
  YN: "Yes/no",
  ID: "Unique Identifier",
  XN: "Text/numeric",
  PA: "Text listed in ABBR Group",
  PU: "Text listed in UNIT Group",
  U: "Value with a variable format"
})