ASAsense Binary Table-formaat (ABT)

Het ASAsense Binary Table-formaat (ABT) is een alternatief voor het CSV-formaat, maar dan voor binaire data met vaste rijlengtes. De structuur is als volgt:

naam	lengte (bytes)	type	toegestane waarden	uitleg
file_type	1	u8	1	Het interne nummer van het bestandstype en de versie
n_cols	4	u32	1-u32::max	Het aantal kolommen
col_widths	4 × n_cols	u32[n_cols]	1-u32::max per kolom	n_cols u32-gehele getallen die de breedte van de kolommen in bytes beschrijven
metadata_length	4	u32	0-u32::max	De lengte van het metadataveld (kan 0 zijn als het moet worden overgeslagen)
metadata	metadata_length	char[]	string met vaste lengte (dus geen '\0'-teken dat het einde van de string aangeeft)	JSON-gecodeerde metadata
data	variabel, tot EOF	byte[]	willekeurig	De eigenlijke data

De JSON-metadata moet een object zijn met de volgende structuur:

veld	verplicht	type	uitleg
n_rows	false	number	Het aantal rijen in het bestand, indien vooraf bekend (kan worden weggelaten voor streamingdata)
comment	false	string	Een vrije tekst
columns	true	een lijst van kolomdefinitie-objecten	Een lijst van objecten die de kolommen in meer detail beschrijven (moet n_cols elementen bevatten)
extra	false	JSON-object	Een JSON-object dat vrij kan worden ingevuld

Een "kolomdefinitie-object" moet het volgende formaat hebben:

veld	verplicht	type	uitleg
name	false	string	Een optionele naam voor de kolom
comment	false	string	Een vrije tekst
datatype	true	string	Een identificatie van het datatype van de kolom

The datatype identifiers can be anything, but the reader should support at least the following:

identifier	description
utf8	Interpret the data as a UTF-8 string (with fixed length; it does not need to be terminated with '\0')
int	Interpret the data as a signed integer
uint	Interpret the data as an unsigned integer
float	Interpret the data as floating-point data (only possible for 4- or 8-byte fields)
bool	Boolean value (0 = false, anything else = true)
numtype/div	"div" should be replaced by any floating-point number. The data is first interpreted as "numtype" (int, uint or float) and then divided by "div". This is mainly useful for storing decimal numbers in integer fields.
unix_timestamp(numtype/div)	Interprets the data as specified within the brackets (so any numtype, with optional divider), but takes into account that it is a Unix timestamp (seconds since the Unix epoch, 1 January 1970 at UTC)

Other, unknown datatype identifiers should be treated by the reader as opaque binary data (bytes).

Common extra metadata fields

In many ABT files used by ASAsense, the following extra metadata fields will be found:

Field name	Field type	Default value	Description
sorted_by_timestamp	bool	true	Indicates whether the data in the ABT file is sorted by timestamp (column 1)
frame_width_s	float	NaN	Indicates the frame width of one sample (for example the sampling period or spectrogram frame width)

CLI tool for ABT handling

To make the ABT format easier to use, a few precompiled binaries are available:

• Linux
  • Ubuntu 22.04 x86_64
  • Ubuntu 20.04 x86_64
• Windows 11 x64

The MD5 sums of the ZIP files are as follows:

adcd6a227861bb6b188ef8c5748faae8  abt-cli-ubuntu-20.04-x86_64.zip
6f4c63cbd7416ead026f170c97b3ab89  abt-cli-ubuntu-22.04-x86_64.zip
39db54827d2634262d9d666b4262b212  abt-cli-win11-x64.zip