Oms API Read Run Output table compare runs

Read a "page" of output table values and compare model runs.

• Compare output table expressions between multiple model runs.

• Comparison typically is a calculation between [base] and [variant] model runs, for example: Expr0[variant] / Expr0[base].

• It is also posiible to include calculation results for each single run, for example: Expr0 or 100 * Expr0 / Expr1.

• Page is part of output table values defined by zero-based "start" row number and row count. If row count <= 0 then all rows below start row number returned.

• Dimension(s) and enum-based parameters returned as enum codes. If dimension type or parameter type is simple (integer or boolean) then string value used (ex.: "true", "1234").

• Method verb must be POST and Content-Type header "application/json".

JSON body POSTed to specify output table name, page size, row count, filters and row order. It is expected to be JSON representation of db.ReadCompareTableLayout structure from Go library. See also: db.ReadLayout structure from Go library.

// ReadCompareTableLayout to compare output table runs with base run using multiple comparison expressions and/or calculation measures.
type ReadCompareTableLayout struct {
	ReadCalculteTableLayout          // output table, base run and comparison expressions or calculations
	Runs                    []string // runs to compare: list of digest, stamp or name
}

// ReadCalculteTableLayout describe table read layout and additional measures to calculte.
type ReadCalculteTableLayout struct {
	ReadLayout                         // output table name, run id, page size, where filters and order by
	Calculation []CalculateTableLayout // additional measures to calculate
}

// CalculateLayout describes calculation to output table values.
type CalculateTableLayout struct {
	CalculateLayout      // expression to calculate and layout
	IsAggr          bool // if true then select output table accumulator else expression
}

// CalculateLayout describes calculation to parameters or output table values.
type CalculateLayout struct {
	Calculate string // expression to calculate, ex.: Expr0[base] - Expr0[variant]
	CalcId    int    // calculated expression id, calc_id column in csv,     ex.: 0, 12000, 24000
	Name      string // calculated expression name, calc_name column in csv, ex.: Expr0, AVG_Expr0, RATIO_Expro0
}

// ReadLayout describes source and size of data page to read input parameter, output table values or microdata.
//
// Row filters combined by AND and allow to select dimension or attribute items,
// it can be enum codes or enum id's, ex.: dim0 = 'CA' AND dim1 IN (2010, 2011, 2012)
type ReadLayout struct {
	Name           string           // parameter name, output table name or entity microdata name
	FromId         int              // run id or set id to select input parameter, output table values or microdata from
	ReadPageLayout                  // read page first row offset, size and last page flag
	Filter         []FilterColumn   // dimension or attribute filters, final WHERE does join all filters by AND
	FilterById     []FilterIdColumn // dimension or attribute filters by enum ids, final WHERE does join filters by AND
	OrderBy        []OrderByColumn  // order by columnns, if empty then dimension id ascending order is used
}

Method:

POST /api/model/:model/run/:run/table/compare

For example:

curl -v -X POST -H "Content-Type: application/json" http://localhost:4040/api/model/modelOne/run/Default/table/compare -d @test.json
curl -v -X POST -H "Content-Type: application/json" http://localhost:4040/api/model/modelOne/run/2019_01_17_19_59_52_998/table/compare -d @test.json

Arguments:

:model - (required) model digest or model name

Model can be identified by digest or by model name. It is recommended to use digest because it is uniquely identifies model. It is possible to use model name, which is more human readable than digest, but if there are multiple models with same name in database than result is undefined.

:run - (required) model run digest, run stamp or run name

Model run can be identified by run digest, run stamp or run name. It is recommended to use digest because it is uniquely identifies model run. Run stamp, if not explicitly specified as model run option, automatically generated as timestamp string, ex.: 2016_08_17_21_07_55_123. It is also possible to use name, which is more human readable than digest, but if there are multiple runs with same name in database than result is undefined.

JSON body arguments:

Example 1. For modelOne output table salarySex:

• read expr0 values from [base] run and from [variant] runs: "Default-4", "First Task Run_modelOne_other"
• calculate difference of expr0 values between [variant] runs and [base]

{
  "Name":      "salarySex",
  "Calculation": [
    {
      "Calculate": "expr0",
      "CalcId":    0,
      "Name":      "expr0",
      "IsAggr": false
    },
    {
      "Calculate": "expr0[variant] - expr0[base]",
      "CalcId":    12000,
      "Name":      "Diff_of_expr0",
      "IsAggr": false
    }
  ],
  "Runs": [
    "Default-4",
    "First Task Run_modelOne_other"
  ]
}

Calculation must be done over output table expressions and can NOT include table accumulators. Output table expression can be from [base] or from [variant] model run, e.g.: expr0[variant] - expr0[base]. It is also possible to use to do a calcultion for each single (not between two runs), e.g.: expr0, or 100 * expr0 / expr1. Calcultion must be a comparison formula between two runs [base] and [variant] or done on single run. You cannot mix comparison and sincle run calcultion, it is mutually exclusive, for exampel: thisi is an error: expr1 + expr0[variant] - expr0[base]. Calculation can include expression names, + - * / operators and following functions:

• SQRT square root
• ABS absolute value
• OM_IF equivalent of if .... then .... else ....
• OM_DIV_BY wrap denominator

It is also possible to use parameter(s) in calculation, parameter must be a scalar of float or integer type. For example: (Expr1[variant] - Expr1[base]) * param.Scale[base], where param.Scale is a value of scalar parameter Scale in [base] model run.

For more details please see: Model Output Expressions

Example 2.:

• read expr0 values from [base] run and from [variant] runs: "Default-4", "First Task Run_modelOne_other"
• calculate difference of expr0 values between [variant] runs and [base], adjusted by using parameter StartingSeed value from base run
• read only first 100 rows: Offset: 0, Size: 100
• apply WHERE filters and ORDER BY

{
  "Name":      "salarySex",
  "Calculation": [
    {
      "Calculate": "expr0",
      "CalcId":    0,
      "Name":      "expr0",
      "IsAggr": false
    },
    {
      "Calculate": "(expr0[variant] - expr0[base]) + param.StartingSeed[base] / 100",
      "CalcId":    12000,
      "Name":      "Diff_of_expr0_adjusted",
      "IsAggr": false
    }
  ],
  "Runs": [
    "Default-4",
    "First Task Run_modelOne_other"
  ],
  "Offset": 0,
  "Size": 100,
  "IsFullPage": true,
  "Filter": [{
      "Name": "dim0",
      "Op": "IN",
      "Values": ["L", "H"]
    }, {
      "Name": "dim1",
      "Op": "BETWEEN",
      "Values": ["F", "all"]
    }
  ],
  "OrderBy": [{
      "IndexOne": 2,
      "IsDesc": true
    }, {
      "IndexOne": 3,
      "IsDesc": true
    }
  ]
}

Name       - (required) output table name
Offset     - (optional) zero-based start row to select output table values
Size       - (optional) max row count to select output table values, if size <= 0 then all rows selected
IsFullPage - (optional) if true then always return non-empty last page of data
Filter     - (optional) conditions to filter dimension enum id's
OrderBy    - (optional) list of columns indexes (one based) to order by

Filter conditions joined by AND and can have following operations:

=       - enum equal to:          AgeGroup = "20-30"
!=      - enum not equal to:      AgeGroup <> "20-30"
>       - enum greater than:      AgeGroup > "20-30"
>=      - enum greater or equal:  AgeGroup >= "20-30"
<       - enum less than:         AgeGroup < "20-30"
<=      - enum less or equal:     AgeGroup <= "20-30"
IN      - enum is in the list of: AgeGroup IN ("20-30", "30-40", "40+")
BETWEEN - between min and max:    AgeGroup BETWEEN "30-40" AND "all"
IN_AUTO - automatically choose most suitable: = or != or IN or BETWEEN

Keep in mind: dimension enums are always ordered by id's, not by code and result of filter Sex < "M" may not be Sex = "F".

Order by specified by one-based column(s) index(es) in result. Columns always contain enum id's, not enum codes and therefore result ordered by id's. First two columns are run_id, calc_id:

  SELECT run_id, CalcId AS calc_id, dim0, dim1, ..., calc_value FROM .... ORDER BY 1, 2,...

JSON response:

{
  Layout: {
    Offset:     actual first row number of the page data (zero-base),
    Size:       actual data page row count,
    IsLastPage: true if this is last page of data
  },
  Page: [....page of data...]
}

Example:

curl -v -X POST -H "Content-Type: application/json" http://localhost:4040/api/model/modelOne/run/Default/table/compare -d @test.json

JSON body (test.json):

{
  "Name":      "salarySex",
  "Calculation": [
    {
      "Calculate": "expr0",
      "CalcId":    0,
      "Name":      "expr0",
      "IsAggr": false
    },
    {
      "Calculate": "expr0[variant] - expr0[base]",
      "CalcId":    12000,
      "Name":      "Diff_of_expr0",
      "IsAggr": false
    }
  ],
  "Runs": [
    "Default-4",
    "First Task Run_modelOne_other"
  ]
}

Result:

> POST /api/model/modelOne/run/Default/table/compare HTTP/1.1
> Host: localhost:4040
> User-Agent: curl/8.0.1
> Accept: */*
> Content-Type: application/json
> Content-Length: 363
>
< HTTP/1.1 200 OK
< Content-Type: application/json
< Date: Thu, 26 Oct 2023 02:53:46 GMT
< Transfer-Encoding: chunked
<
{
    "Page": [{
            "Dims": ["L", "M"],
            "IsNull": false,
            "Value": 50,
            "CalcName": "expr0",
            "RunDigest": "ca663651953bae94d0afdf71edba4c91"
        }, {
            "Dims": ["L", "F"],
            "IsNull": false,
            "Value": 60,
            "CalcName": "expr0",
            "RunDigest": "ca663651953bae94d0afdf71edba4c91"
        }, {
            "Dims": ["L", "all"],
            "IsNull": false,
            "Value": 1,
            "CalcName": "expr0",
            "RunDigest": "ca663651953bae94d0afdf71edba4c91"
        }, {
            "Dims": ["M", "M"],
            "IsNull": false,
            "Value": 51.599999999999994,
            "CalcName": "expr0",
            "RunDigest": "ca663651953bae94d0afdf71edba4c91"
        }, {
            "Dims": ["M", "F"],
            "IsNull": false,
            "Value": 62,
            "CalcName": "expr0",
            "RunDigest": "ca663651953bae94d0afdf71edba4c91"
        }, {
            "Dims": ["M", "all"],
            "IsNull": false,
            "Value": 2,
            "CalcName": "expr0",
            "RunDigest": "ca663651953bae94d0afdf71edba4c91"
        }, {
            "Dims": ["H", "M"],
            "IsNull": false,
            "Value": 53.2,
            "CalcName": "expr0",
            "RunDigest": "ca663651953bae94d0afdf71edba4c91"
        }, {
            "Dims": ["H", "F"],
            "IsNull": false,
            "Value": 64,
            "CalcName": "expr0",
            "RunDigest": "ca663651953bae94d0afdf71edba4c91"
        }, {
            "Dims": ["H", "all"],
            "IsNull": false,
            "Value": 3,
            "CalcName": "expr0",
            "RunDigest": "ca663651953bae94d0afdf71edba4c91"
        }, {
            "Dims": ["L", "M"],
            "IsNull": false,
            "Value": 50,
            "CalcName": "expr0",
            "RunDigest": "c519fc5869f244ac4c80ae44695a4272"
        }, {
            "Dims": ["L", "F"],
            "IsNull": false,
            "Value": 60,
            "CalcName": "expr0",
            "RunDigest": "c519fc5869f244ac4c80ae44695a4272"
        }, {
            "Dims": ["L", "all"],
            "IsNull": false,
            "Value": 1201,
            "CalcName": "expr0",
            "RunDigest": "c519fc5869f244ac4c80ae44695a4272"
        }, {
            "Dims": ["M", "M"],
            "IsNull": false,
            "Value": 51.599999999999994,
            "CalcName": "expr0",
            "RunDigest": "c519fc5869f244ac4c80ae44695a4272"
        }, {
            "Dims": ["M", "F"],
            "IsNull": false,
            "Value": 62,
            "CalcName": "expr0",
            "RunDigest": "c519fc5869f244ac4c80ae44695a4272"
        }, {
            "Dims": ["M", "all"],
            "IsNull": false,
            "Value": 1202,
            "CalcName": "expr0",
            "RunDigest": "c519fc5869f244ac4c80ae44695a4272"
        }, {
            "Dims": ["H", "M"],
            "IsNull": false,
            "Value": 53.2,
            "CalcName": "expr0",
            "RunDigest": "c519fc5869f244ac4c80ae44695a4272"
        }, {
            "Dims": ["H", "F"],
            "IsNull": false,
            "Value": 64,
            "CalcName": "expr0",
            "RunDigest": "c519fc5869f244ac4c80ae44695a4272"
        }, {
            "Dims": ["H", "all"],
            "IsNull": false,
            "Value": 1203,
            "CalcName": "expr0",
            "RunDigest": "c519fc5869f244ac4c80ae44695a4272"
        }, {
            "Dims": ["L", "M"],
            "IsNull": false,
            "Value": 0,
            "CalcName": "Diff_of_expr0",
            "RunDigest": "c519fc5869f244ac4c80ae44695a4272"
        }, {
            "Dims": ["L", "F"],
            "IsNull": false,
            "Value": 0,
            "CalcName": "Diff_of_expr0",
            "RunDigest": "c519fc5869f244ac4c80ae44695a4272"
        }, {
            "Dims": ["L", "all"],
            "IsNull": false,
            "Value": 1200,
            "CalcName": "Diff_of_expr0",
            "RunDigest": "c519fc5869f244ac4c80ae44695a4272"
        }, {
            "Dims": ["M", "M"],
            "IsNull": false,
            "Value": 0,
            "CalcName": "Diff_of_expr0",
            "RunDigest": "c519fc5869f244ac4c80ae44695a4272"
        }, {
            "Dims": ["M", "F"],
            "IsNull": false,
            "Value": 0,
            "CalcName": "Diff_of_expr0",
            "RunDigest": "c519fc5869f244ac4c80ae44695a4272"
        }, {
            "Dims": ["M", "all"],
            "IsNull": false,
            "Value": 1200,
            "CalcName": "Diff_of_expr0",
            "RunDigest": "c519fc5869f244ac4c80ae44695a4272"
        }, {
            "Dims": ["H", "M"],
            "IsNull": false,
            "Value": 0,
            "CalcName": "Diff_of_expr0",
            "RunDigest": "c519fc5869f244ac4c80ae44695a4272"
        }, {
            "Dims": ["H", "F"],
            "IsNull": false,
            "Value": 0,
            "CalcName": "Diff_of_expr0",
            "RunDigest": "c519fc5869f244ac4c80ae44695a4272"
        }, {
            "Dims": ["H", "all"],
            "IsNull": false,
            "Value": 1200,
            "CalcName": "Diff_of_expr0",
            "RunDigest": "c519fc5869f244ac4c80ae44695a4272"
        }, {
            "Dims": ["L", "M"],
            "IsNull": false,
            "Value": 225.6,
            "CalcName": "expr0",
            "RunDigest": "9a1121a0392aa3eddd0932d269838e2d"
        }, {
            "Dims": ["L", "F"],
            "IsNull": false,
            "Value": 272,
            "CalcName": "expr0",
            "RunDigest": "9a1121a0392aa3eddd0932d269838e2d"
        }, {
            "Dims": ["L", "all"],
            "IsNull": false,
            "Value": 1,
            "CalcName": "expr0",
            "RunDigest": "9a1121a0392aa3eddd0932d269838e2d"
        }, {
            "Dims": ["M", "M"],
            "IsNull": false,
            "Value": 232,
            "CalcName": "expr0",
            "RunDigest": "9a1121a0392aa3eddd0932d269838e2d"
        }, {
            "Dims": ["M", "F"],
            "IsNull": false,
            "Value": 280,
            "CalcName": "expr0",
            "RunDigest": "9a1121a0392aa3eddd0932d269838e2d"
        }, {
            "Dims": ["M", "all"],
            "IsNull": false,
            "Value": 2,
            "CalcName": "expr0",
            "RunDigest": "9a1121a0392aa3eddd0932d269838e2d"
        }, {
            "Dims": ["H", "M"],
            "IsNull": false,
            "Value": 238.39999999999998,
            "CalcName": "expr0",
            "RunDigest": "9a1121a0392aa3eddd0932d269838e2d"
        }, {
            "Dims": ["H", "F"],
            "IsNull": false,
            "Value": 288,
            "CalcName": "expr0",
            "RunDigest": "9a1121a0392aa3eddd0932d269838e2d"
        }, {
            "Dims": ["H", "all"],
            "IsNull": false,
            "Value": 3,
            "CalcName": "expr0",
            "RunDigest": "9a1121a0392aa3eddd0932d269838e2d"
        }, {
            "Dims": ["L", "M"],
            "IsNull": false,
            "Value": 175.6,
            "CalcName": "Diff_of_expr0",
            "RunDigest": "9a1121a0392aa3eddd0932d269838e2d"
        }, {
            "Dims": ["L", "F"],
            "IsNull": false,
            "Value": 212,
            "CalcName": "Diff_of_expr0",
            "RunDigest": "9a1121a0392aa3eddd0932d269838e2d"
        }, {
            "Dims": ["L", "all"],
            "IsNull": false,
            "Value": 0,
            "CalcName": "Diff_of_expr0",
            "RunDigest": "9a1121a0392aa3eddd0932d269838e2d"
        }, {
            "Dims": ["M", "M"],
            "IsNull": false,
            "Value": 180.4,
            "CalcName": "Diff_of_expr0",
            "RunDigest": "9a1121a0392aa3eddd0932d269838e2d"
        }, {
            "Dims": ["M", "F"],
            "IsNull": false,
            "Value": 218,
            "CalcName": "Diff_of_expr0",
            "RunDigest": "9a1121a0392aa3eddd0932d269838e2d"
        }, {
            "Dims": ["M", "all"],
            "IsNull": false,
            "Value": 0,
            "CalcName": "Diff_of_expr0",
            "RunDigest": "9a1121a0392aa3eddd0932d269838e2d"
        }, {
            "Dims": ["H", "M"],
            "IsNull": false,
            "Value": 185.2,
            "CalcName": "Diff_of_expr0",
            "RunDigest": "9a1121a0392aa3eddd0932d269838e2d"
        }, {
            "Dims": ["H", "F"],
            "IsNull": false,
            "Value": 224,
            "CalcName": "Diff_of_expr0",
            "RunDigest": "9a1121a0392aa3eddd0932d269838e2d"
        }, {
            "Dims": ["H", "all"],
            "IsNull": false,
            "Value": 0,
            "CalcName": "Diff_of_expr0",
            "RunDigest": "9a1121a0392aa3eddd0932d269838e2d"
        }
    ],
    "Layout": {
        "Offset": 0,
        "Size": 45,
        "IsLastPage": true,
        "IsFullPage": false
    }
}