Oms API Read Run Microdata aggregated - openmpp/openmpp.github.io GitHub Wiki

// ReadCalculteMicroLayout describe microdata generation read layout, aggregation measures and group by attributes.
type ReadCalculteMicroLayout struct {
	ReadLayout           // entity name, run id, page size, where filters and order by
	CalculateMicroLayout // microdata aggregations
}

// CalculateMicroLayout describes aggregations of microdata.
//
// It can be comparison aggregations and/or calculation aggregations.
// Comparison aggregation must contain [base] and [variant] attribute(s), ex.: OM_AVG(Income[base] - Income[variant]).
// Calculation aggregation is attribute(s) aggregation expression, ex.: OM_MAX(Income) / OM_MIN(Salary).
type CalculateMicroLayout struct {
	Calculation []CalculateLayout // aggregation measures, ex.: OM_MIN(Salary), OM_AVG(Income[base] - Income[variant])
	GroupBy     []string          // attributes to group by
}

// CalculateLayout describes calculation expression for parameters, output table values or microdata entity.
// It can be comparison calculation for multiple model runs, ex.: Expr0[base] - Expr0[variant].
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
}

POST /api/model/:model/run/:run/microdata/calc

curl -v -X POST -H "Content-Type: application/json" http://localhost:4040/api/model/modelOne/run/Microdata%20in%20database/microdata/calc -d @read_m1_person_calc_1.json

:model - (required) model digest or model name

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

{
    "Name": "Person",
    "Calculation": [{
            "Calculate": "OM_AVG(Income)",
            "CalcId": 2401,
            "Name": "Avg_Income"
        }
    ],
    "GroupBy": [
        "AgeGroup",
        "Sex"
    ]
}

{
    "Name": "Person",
    "Calculation": [{
            "Calculate": "OM_AVG(Income) * (param.StartingSeed / 100)",
            "CalcId": 2401,
            "Name": "Avg_Income_adjusted"
        }, {
            "Calculate": "OM_AVG(Salary + Pension + param.StartingSeed)",
            "CalcId": 2404,
            "Name": "Avg_Salary_Pension_adjusted"
        }
    ],
    "GroupBy": [
        "AgeGroup",
        "Sex"
    ],
    "Offset": 0,
    "Size": 100,
    "IsFullPage": true,
    "Filter": [{
            "Name": "AgeGroup",
            "Op": "IN",
            "Values": ["20-30", "40+"]
        }, {
            "Name": "Sex",
            "Op": "=",
            "Values": ["F"]
        }, {
            "Name": "Avg_Income_adjusted",
            "Op": ">",
            "Values": ["8500000"]
        }, {
            "Name": "Avg_Salary_Pension_adjusted",
            "Op": "<",
            "Values": ["85000"]
        }
    ],
    "OrderBy": [{
            "IndexOne": 2,
            "IsDesc": true
        }, {
            "IndexOne": 3,
            "IsDesc": true
        }
    ]
}

Name       - (required) entity name
Offset     - (optional) zero-based start row to select aggreagted microdata values
Size       - (optional) max row count to select rows, 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 attributes
OrderBy    - (optional) list of columns indexes (one based) to order by

=       - 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

  SELECT run_id, CalcId AS calc_id, AgeGroup, Sex, ..., calc_value FROM .... ORDER BY 1, 2,...

{
  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...]
}

{
  "Page": [{
      "Attr": [{
          "IsNull": false,
          "Value": "40+"
        }, {
          "IsNull": false,
          "Value": "F"
        }, {
          "IsNull": false,
          "Value": 69934.18
        }
      ],
      "CalcName": "Avg_Salary_Pension_adjusted",
      "RunDigest": "703d8b78039d69b795ab2e601c32b789"
    }, {
      "Attr": [{
          "IsNull": false,
          "Value": "20-30"
        }, {
          "IsNull": false,
          "Value": "F"
        }, {
          "IsNull": false,
          "Value": 8897709.41
        }
      ],
      "CalcName": "Avg_Income_adjusted",
      "RunDigest": "703d8b78039d69b795ab2e601c32b789"
    }
  ],
  "Layout": {
    "Offset": 0,
    "Size": 2,
    "IsLastPage": true,
    "IsFullPage": true
  }
}