aghast.fbs

namespace aghast_generated;

///////////////////////////////////////////////// metadata

enum MetadataLanguage: uint {
  meta_unspecified = 0,
  meta_json = 1,
}

table Metadata {
  data: string (required);
  language: MetadataLanguage = meta_unspecified;
}

///////////////////////////////////////////////// decoration

enum DecorationLanguage: uint {
  deco_unspecified = 0,
  deco_css = 1,
  deco_vega = 2,
  deco_json = 3
}

table Decoration {
  data: string (required);
  language: DecorationLanguage = deco_unspecified;
}

///////////////////////////////////////////////// buffers

enum DType: byte {
  dtype_none = 0,
  dtype_bool = 1,
  dtype_int8 = 2,
  dtype_uint8 = 3,
  dtype_int16 = 4,
  dtype_uint16 = 5,
  dtype_int32 = 6,
  dtype_uint32 = 7,
  dtype_int64 = 8,
  dtype_uint64 = 9,
  dtype_float32 = 10,
  dtype_float64 = 11
}

enum Endianness: byte {
  little_endian = 0,
  big_endian = 1,
}

enum DimensionOrder: byte {
  c_order = 0,
  fortran_order = 1
}

enum Filter: uint {
  filter_none = 0,
  filter_gzip = 1,
  filter_lzma = 2,
  filter_lz4 = 3
  // not just compression; any 1-to-1 buffer transformation
}

struct Slice {
  start: long;
  stop: long;
  step: int;
  has_start: bool;
  has_stop: bool;
  has_step: bool;
}

enum ExternalSource: uint {
  external_memory = 0,
  external_samefile = 1,
  external_file = 2,
  external_url = 3
}

table RawInlineBuffer {
  buffer: [ubyte] (required);
}

table RawExternalBuffer {
  pointer: ulong;
  numbytes: ulong;
  external_source: ExternalSource = external_memory;
  location: string;
}

table InterpretedInlineBuffer {
  buffer: [ubyte] (required);
  filters: [Filter];
  postfilter_slice: Slice;
  dtype: DType = dtype_none;
  endianness: Endianness = little_endian;
  dimension_order: DimensionOrder = c_order;
}

table InterpretedInlineInt64Buffer {
  buffer: [ubyte] (required);
}

table InterpretedInlineFloat64Buffer {
  buffer: [ubyte] (required);
}

table InterpretedExternalBuffer {
  pointer: ulong;
  numbytes: ulong;
  external_source: ExternalSource = external_memory;
  filters: [Filter];
  postfilter_slice: Slice;
  dtype: DType = dtype_none;
  endianness: Endianness = little_endian;
  dimension_order: DimensionOrder = c_order;
  location: string;
}

union RawBuffer {
  RawInlineBuffer,
  RawExternalBuffer
}

union InterpretedBuffer {
  InterpretedInlineBuffer,
  InterpretedInlineInt64Buffer,
  InterpretedInlineFloat64Buffer,
  InterpretedExternalBuffer
}

///////////////////////////////////////////////// descriptive statistics

struct StatisticFilter {
  min: double = "-Inf";
  max: double = "+Inf";
  excludes_minf: bool = false;
  excludes_pinf: bool = false;
  excludes_nan: bool = false;
}

table Moments {
  sumwxn: InterpretedBuffer (required);
  n: int8;
  weightpower: int8 = 0;
  filter: StatisticFilter;
}

table Extremes {
  values: InterpretedBuffer (required);
  filter: StatisticFilter;
}

table Quantiles {
  values: InterpretedBuffer (required);
  p: double = 0.5;    // 0.0 <= p <= 1.0
  weightpower: int8 = 0;
  filter: StatisticFilter;
}

table Modes {
  values: InterpretedBuffer (required);
  filter: StatisticFilter;
}

table Statistics {
  moments: [Moments];
  quantiles: [Quantiles];
  mode: Modes;
  min: Extremes;
  max: Extremes;
}

table Covariance {
  xindex: int;
  yindex: int;
  sumwxy: InterpretedBuffer (required);   // one of the N*(N-1) elements
  weightpower: int8 = 0;
  filter: StatisticFilter;
}

///////////////////////////////////////////////// binning

enum BinLocation: int8 {
  loc_below3 = -3,
  loc_below2 = -2,
  loc_below1 = -1,
  loc_nonexistent = 0,
  loc_above1 = 1,
  loc_above2 = 2,
  loc_above3 = 3
}

table IntegerBinning {
  min: long;   // assumed to be inclusive (if not, change its value!)
  max: long;
  loc_underflow: BinLocation = loc_nonexistent;
  loc_overflow: BinLocation = loc_nonexistent;
}

struct RealInterval {
  low: double;
  high: double;
  low_inclusive: bool = true;
  high_inclusive: bool = false;
}

enum NonRealMapping: byte {
  missing = 0,
  in_underflow = 1,
  in_overflow = 2,
  in_nanflow = 3
}

struct RealOverflow {
  loc_underflow: BinLocation = loc_nonexistent;
  loc_overflow: BinLocation = loc_nonexistent;
  loc_nanflow: BinLocation = loc_nonexistent;
  minf_mapping: NonRealMapping = in_underflow;
  pinf_mapping: NonRealMapping = in_overflow;
  nan_mapping: NonRealMapping = in_nanflow;
}

table RegularBinning {
  num: ulong;
  interval: RealInterval (required);
  overflow: RealOverflow;
  circular: bool = false;
}

// https://www.redblobgames.com/grids/hexagons
enum HexagonalCoordinates: byte {
  hex_offset = 0,
  hex_doubled_offset = 1,
  hex_cube_xy = 2,
  hex_cube_yz = 3,
  hex_cube_xz = 4
}

table HexagonalBinning {
  qmin: long;   // assumed to be inclusive (if not, change its value!)
  qmax: long;
  rmin: long;
  rmax: long;
  coordinates: HexagonalCoordinates = hex_offset;
  xorigin: double = 0.0;    // x coordinate of (q, r) == (0, 0)
  yorigin: double = 0.0;    // y coordinate of (q, r) == (0, 0)
  qangle: double = 0.0;     // angle of (q, r) == (1, 0) relative to (x, y) == (1, 0) in -pi/2 <= x <= pi/2
  bin_width: double = 1.0;  // shortest distance between two tile centers (intersects the boundary perpendicularly)
  qoverflow: RealOverflow;
  roverflow: RealOverflow;
}

table EdgesBinning {
  edges: [double] (required);
  overflow: RealOverflow;
  low_inclusive: bool = true;
  high_inclusive: bool = false;
  circular: bool = false;
}

enum OverlappingFillStrategy: byte {
  overfill_unspecified = 0,
  overfill_all = 1,
  overfill_first = 2,
  overfill_last = 3
}

table IrregularBinning {
  intervals: [RealInterval] (required);
  overflow: RealOverflow;
  overlapping_fill: OverlappingFillStrategy = overfill_unspecified;
}

table CategoryBinning {
  categories: [string] (required);
  loc_overflow: BinLocation = loc_nonexistent;
}

table SparseRegularBinning {
  bins: [long] (required);
  bin_width: double;
  origin: double = 0.0;
  overflow: RealOverflow;
  low_inclusive: bool = true;
  high_inclusive: bool = false;
  minbin: long = -9223372036854775808;
  maxbin: long = 9223372036854775807;
}

enum FractionLayout: byte {
  frac_passall = 0,
  frac_failall = 1,
  frac_passfail = 2
}

enum FractionErrorMethod: byte {
  frac_unspecified = 0,
  frac_normal = 1,
  frac_clopper_pearson = 2,
  frac_wilson = 3,
  frac_agresti_coull = 4,
  frac_feldman_cousins = 5,
  frac_jeffrey = 6,
  frac_bayesian_uniform = 7
}

table FractionBinning {
  layout: FractionLayout = frac_passall;
  layout_reversed: bool = false;
  error_method: FractionErrorMethod = frac_unspecified;
}

table PredicateBinning {
  predicates: [string] (required);
  overlapping_fill: OverlappingFillStrategy = overfill_unspecified;
}

table Assignment {
  identifier: string (key);
  expression: string (required);
}

table Variation {
  assignments: [Assignment] (required);
  systematic: [double];
  category_systematic: [string];
}

enum SystematicUnits: byte {
  syst_unspecified = 0,
  syst_confidence = 1,
  syst_sigmas = 2,
}

table VariationBinning {
  variations: [Variation] (required);
  systematic_units: SystematicUnits = syst_unspecified;
  systematic_names: [string];
  category_systematic_names: [string];
}

union Binning {
  IntegerBinning,
  RegularBinning,
  HexagonalBinning,
  EdgesBinning,
  IrregularBinning,
  CategoryBinning,
  SparseRegularBinning,
  FractionBinning,
  PredicateBinning,
  VariationBinning
}

///////////////////////////////////////////////// axis

table Axis {
  binning: Binning;      // note: it's allowed to have no binning
  expression: string;
  statistics: [Statistics];
  title: string;
  metadata: Metadata;
  decoration: Decoration;
}

table Profile {
  expression: string (required);
  statistics: Statistics (required);
  title: string;
  metadata: Metadata;
  decoration: Decoration;
}

///////////////////////////////////////////////// distributions

table UnweightedCounts {
  counts: InterpretedBuffer (required);
}

table WeightedCounts {
  sumw: InterpretedBuffer (required);
  sumw2: InterpretedBuffer;               // optional
  unweighted: UnweightedCounts;           // optional
}

union Counts {
  UnweightedCounts,
  WeightedCounts
}

///////////////////////////////////////////////// functions

table Parameter {
  identifier: string (key);
  values: InterpretedBuffer (required);
  errors: InterpretedBuffer;
}

table ParameterizedFunction {
  expression: string (required);
  parameters: [Parameter];
  paramaxis: [int];
  parameter_covariances: [Covariance];
}

table EvaluatedFunction {
  values: InterpretedBuffer (required);
  derivatives: InterpretedBuffer;
  errors: [Quantiles];
}

// FIXME: ContourFunction? Has to specify its own number of points because it can't be determined by its place in the hierarchy

union FunctionData {
  ParameterizedFunction,
  EvaluatedFunction
  // ContourFunction
}

table Function {
  data: FunctionData (required);
  title: string;
  metadata: Metadata;
  decoration: Decoration;
  script: string;
}

table BinnedEvaluatedFunction {
  axis: [Axis] (required);
  data: EvaluatedFunction (required);
}

union FunctionObjectData {
  ParameterizedFunction,
  BinnedEvaluatedFunction
  // ContourFunction
}

table FunctionObject {
  data: FunctionObjectData (required);
}

///////////////////////////////////////////////// histogram

table Histogram {
  axis: [Axis] (required);
  counts: Counts (required);
  profile: [Profile];
  axis_covariances: [Covariance];
  profile_covariances: [Covariance];
  functions_lookup: [string];
  functions: [Function];
}

///////////////////////////////////////////////// ntuple

table Page {
  buffer: RawBuffer (required);
}

table ColumnChunk {
  pages: [Page] (required);
  page_offsets: [long] (required);
  page_min: [Extremes];
  page_max: [Extremes];
}

table Chunk {
  column_chunks: [ColumnChunk] (required);
  metadata: Metadata;
}

table Column {
  identifier: string (key);
  dtype: DType = dtype_none;
  endianness: Endianness = little_endian;
  filters: [Filter];
  postfilter_slice: Slice;
  title: string;
  metadata: Metadata;
  decoration: Decoration;
}

table NtupleInstance {
  chunks: [Chunk] (required);
  chunk_offsets: [ulong];
}

table Ntuple {
  columns: [Column] (required);
  instances: [NtupleInstance] (required);
  column_statistics: [Statistics];
  column_covariances: [Covariance];
  functions_lookup: [string];
  functions: [FunctionObject];
}

///////////////////////////////////////////////// objects and collections

table Collection {
  lookup: [string];
  objects: [Object];
  axis: [Axis];
}

union ObjectData {
  Histogram,
  Ntuple,
  FunctionObject,
  Collection
}

table Object {
  data: ObjectData (required);
  title: string;
  metadata: Metadata;
  decoration: Decoration;
  script: string;
}

file_extension "agh";
file_identifier "gast";
root_type Object;