AGS data types¶
Every heading in an AGS4 file declares a data type — the short code in its TYPE row (ID, 2DP, DT, …). The type fixes how the value is written, validated (AGS Format Rule 8 enforces numeric precision), and read back. laterite maps each AGS type to a canonical type and reads every column born-typed: a 2DP heading arrives as a float, a DT as a datetime.
Three families are parametric — the leading digit is the precision: nDP is n decimal places (1DP…4DP), nSF is n significant figures, nSCI is scientific notation with n mantissa decimals.
Quick reference¶
| Code(s) | Reads as | Meaning |
|---|---|---|
ID |
str |
Unique Identifier |
X |
str |
Text |
XN |
str |
Text/numeric |
PA |
str |
Text listed in ABBR Group |
PT |
str |
Text listed in TYPE Group |
PU |
str |
Text listed in UNIT Group |
U |
str |
Unit (text) |
T |
str |
Elapsed Time |
MC |
str |
BS1377 reported moisture content |
DMS |
str |
Degrees:Minutes:Seconds |
YN |
bool |
Yes or No |
DT |
datetime |
Date time in international format |
RL |
str |
Record Link |
0DP |
int |
Value; required number of decimal places, 0 |
1DP, 2DP, 3DP, 4DP |
float |
Value; required number of decimal places, n |
1SF, 2SF, 3SF |
float |
Value; required number of significant figures, n |
1SCI, 2SCI, 3SCI, 4SCI |
float |
Scientific Notation; required number of decimal places, n |
Type reference¶
ID — Unique identifier¶
- Codes:
ID - Reads as:
str(canonicalstring) - AGS standard: Unique Identifier
A KEY-style text code that names a record (a borehole, a sample, a test). Read as a string; never coerced to a number even when it looks numeric.
Example: BH01, BH01/4.50
X — Text¶
- Codes:
X - Reads as:
str(canonicalstring) - AGS standard: Text
Free-form alphanumeric text — the catch-all type. Read verbatim (whitespace trimmed).
Example: Made Ground, Light brown sandy CLAY
XN — Text or numeric¶
- Codes:
XN - Reads as:
str(canonicalstring) - AGS standard: Text/numeric
Usually a number but may carry non-numeric tokens (<0.05, n/a, >1000), so it is read as a string by default. The opt-in xn="numeric" read knob coerces the parseable cells to floats.
Example: 12.5, <0.05, n/a
PA — Abbreviation pick-list¶
- Codes:
PA - Reads as:
str(canonicalstring) - AGS standard: Text listed in ABBR Group
A controlled value that must appear in the file's ABBR group. Read as a string; the validator checks membership.
Example: CP (cable percussion), RC (rotary cored)
PT — Type pick-list¶
- Codes:
PT - Reads as:
str(canonicalstring) - AGS standard: Text listed in TYPE Group
A controlled value drawn from the TYPE group — i.e. one of the data-type codes on this page. Read as a string.
Example: 2DP, DT
PU — Unit pick-list¶
- Codes:
PU - Reads as:
str(canonicalstring) - AGS standard: Text listed in UNIT Group
A controlled value drawn from the file's UNIT group. Read as a string.
Example: m, kN/m2, Mg/m3
U — Unit¶
- Codes:
U - Reads as:
str(canonicalstring) - AGS standard: Unit (text)
A unit string. Read as text. Note: U is used by headings in the dictionary but is not itself defined in the standard TYPE group — treat it as a free unit label.
Example: mm, %
T — Elapsed time¶
- Codes:
T - Reads as:
str(canonicalstring) - AGS standard: Elapsed Time
A duration / elapsed time written in a colon-separated form (not a clock time-of-day). Read as a string.
Example: 12:30 (12 h 30 m), 00:00:45
MC — Moisture content¶
- Codes:
MC - Reads as:
str(canonicalstring) - AGS standard: BS1377 reported moisture content
A moisture content reported per BS 1377 : Part 2 conventions. Read as a string.
Example: 23
DMS — Degrees:minutes:seconds¶
- Codes:
DMS - Reads as:
str(canonicalstring) - AGS standard: Degrees:Minutes:Seconds
A sexagesimal angle / geographic coordinate. Read as a string (it is not a single decimal).
Example: 51:28:38
YN — Yes / No¶
- Codes:
YN - Reads as:
bool(canonicalbool) - AGS standard: Yes or No
A boolean. Read as True/False; the parser accepts Y/N, YES/NO, TRUE/FALSE, 1/0 (case-insensitive).
Example: Y, N
DT — Date / date-time¶
- Codes:
DT - Reads as:
datetime(canonicaldatetime) - AGS standard: Date time in international format
An ISO-8601-style date or date-time. Read as a datetime; a date-only value is promoted to midnight. Accepted forms include YYYY-MM-DD, YYYY-MM-DD HH:MM[:SS] and YYYY-MM-DDTHH:MM:SS.
Example: 2024-03-15, 2024-03-15 09:30:00
RL — Record link¶
- Codes:
RL - Reads as:
str(canonicalstring) - AGS standard: Record Link
A typed cross-reference to another group's KEY record (heading-name / value pairs concatenated). Read as a string.
Example: LOCA_ID
0DP — Whole number¶
- Codes:
0DP - Reads as:
int(canonicalinteger) - AGS standard: Value; required number of decimal places, 0
An integer (zero decimal places). Read as an int; values written 5.0 are tolerated and parsed via float.
Example: 5, 100
nDP — Fixed decimal places¶
- Codes:
1DP,2DP,3DP,4DP - Reads as:
float(canonicaldecimal) - AGS standard: Value; required number of decimal places, n
A fixed-point number carrying exactly n decimal places (1DP … 4DP). The digit count is the declared precision the validator enforces (Rule 8); read as a float.
Example: 12.30 (2DP), 0.001 (3DP)
nSF — Significant figures¶
- Codes:
1SF,2SF,3SF - Reads as:
float(canonicaldecimal) - AGS standard: Value; required number of significant figures, n
A number expressed to exactly n significant figures (1SF … 3SF are used). Read as a float.
Example: 0.045 (2SF), 12300 (3SF)
nSCI — Scientific notation¶
- Codes:
1SCI,2SCI,3SCI,4SCI - Reads as:
float(canonicaldecimal) - AGS standard: Scientific Notation; required number of decimal places, n
A number in scientific notation with n decimal places in the mantissa (1SCI, 2SCI are used). Read as a float.
Example: 1.2E-08 (1SCI), 4.50E+03 (2SCI)
The canonical mapping and value parsing live in laterite.ags_types (canonical_type, parse_value). See Born-typed reads for how types flow into the polars frames, and the Group catalogue for which headings use each type.