# Model Visualization

## Textual Output

In low- to medium-complexity applications, the simplest way of examining the
performance models generated by dfatool is textual output: `--show-model=param`.
This is implemented for most modeling methods.

## Graphical Output via dot(1)

`--export-dot PREFIX` exports the generated performance models for each pair of
name (state/transition/…) and performance attribute to
`PREFIX(name)-(attribute).dot`. The dot(1) program is capable of transforming
those into images. For instance, if feh(1) is available, a visual model is
accessible via `dot -Tpng filename.dot | feh -`.

In case of regression forests (XGBoost), dfatool exports the individual trees to
`PREFIX(name)-(attribute).(index).dot`.

## Plotting Model Predictions for Individual Configurations

`--plot-param name:attribute:parameter` displays both raw readings (as points,
see [[analysis-visual.md]]) and the corresponding performance model (as lines).
The plot is saved to (name)-(attribute)-(parameter).pdf and shown interactively
unless `--non-interactive` has been specified.

## JSON Export

Use `--export-json FILENAME` to export the performance model to FILENAME.
The model for NAME ATTRIBUTE is located in .name.NAME.ATTRIBUTE.modelFunction.
If it is a list, it is an XGB forest. Otherwise, it is an CART/LMT/RMT element
described by the `type` key.

### CART/LMT scalar split node

```
{
	"value": 123,
	"type": "scalarSplit",
	"paramIndex": 0,
	"threshold": 24,
	"left": …,
	"right": …
}
```

The model for `param[paramIndex] <= threshold` is located in `left`, the model
for `param[paramIndex] > threshold` is located in `right`. `value` is a
static model that serves as fall-back if `param[paramIndex]` is undefined.

### RMT categorical split node

```
{
	"value": 123,
	"type": "split",
	"paramIndex": 0,
	"child": {
		"y": …,
		"n": …,
	}
}
```

Given some (usually not numeric) `value`, the model for `param[paramIndex] ==
value` is located in `child[value]`. In this example, the node describes a
boolean Kconfig feature, so there are just two children: `y` (feature enabled)
and `n` (feature disabled). Again, `value` refers to a static fall-back model.

### ULS (least-squares regresion) node

```
{
	"value": 123,
	"type": "analytic",
	"functionStr": "0 + regression_arg(0) + regression_arg(1) * np.log(parameter(bitrate))",
	"regressionModel": [674574496.5381737, -51732985.15977712]
}
```

The model function is `674574496.5381737 - 51732985.15977712 * log(bitrate)`.
`value` is a static model that serves as fall-back if `bitrate` is undefined.

### Static node

```
{
	"value": 123,
	"type": "static"
}
```