# kafe2go Guide¶

*kafe2go* is a standalone program for performing fits which comes with *kafe2*.
When using *kafe2go* no programming is required.
Instead all necessary information for performing a fit is defined inside a so-called
YAML file.
Full examples can be found in the Beginners Guide.

To run kafe2go on Linux or MacOS issue this command in the terminal, after installing *kafe2*:

```
kafe2go path/to/fit.yml
```

When using Windows, please use:

```
kafe2go.py path/to/fit.yml
```

The output can be customized via command line arguments. For more information about the command line arguments run:

```
kafe2go --help
```

Additionally, *YAML* files can also be created from fit objects inside a *Python* program by using
the `to_file`

method and loaded from a *YAML* file with
`from_file`

.

## Setting a fit type¶

By default *kafe2go* assumes an XYFit, where each data point has an x and a y component.
Other types are defined via the `type`

keyword inside the *YAML* file:

```
type: histogram
```

Supported types are `type: xy`

, `type: histogram`

, `type: unbinned`

and `type: indexed`

.

## Specifying the data¶

The syntax for specifying fit data differs depending on which fit type is being used.

### XY Fits¶

For XY Fits the x and y values are defined separately:

```
# Data is defined by lists:
x_data: [1.0, 2.0, 3.0, 4.0]
# In yaml lists can also be written out like this:
y_data:
- 2.3
- 4.2
- 7.5
- 9.4
```

The uncertainties in x and y direction can be defined like this:

```
# For errors lists describe pointwise uncertainties.
# By default the errors will be uncorrelated.
x_errors: [0.05, 0.10, 0.15, 0.20]
# Because x_errors is equal to 5% of x_data we could have also defined it like this:
# x_errors: 5%
# For errors a single float gives each data point
# the same amount of uncertainty:
y_errors: 0.4
```

In total the above examples represents the following dataset:

X Values |
Y Values |
---|---|

1.0 +- 0.05 |
2.3 +- 0.4 |

2.0 +- 0.10 |
4.2 +- 0.4 |

3.0 +- 0.15 |
7.5 +- 0.4 |

4.0 +- 0.20 |
9.4 +- 0.4 |

Todo

Add more advanced errors for XY Fits

### Histogram Fits¶

Specifying the data for histogram fits can be done in two different ways:
either by specifying the raw data and bins and let *kafe2* handle the binning or by specifying
the bins and bin heights.

Like with Python code there are two ways of specifying bins. The first way is to specify equidistant binning with the number of bins and the bin range. A binning with 10 bins in the range from -5 to 5 can be achieved like this:

```
n_bins: 10
bin_range: [-5, 5]
```

Alternatively the `bin_edges`

keyword can be used to directly specify bin edges with arbitrary
distances between them:

```
bin_edges: [-5.0, -4.0, -3.0, -2.0, -1.0, 0.0, 1.0, 2.0, 3.0, 4.0, 5.0]
```

Filling the bins with raw data is done like this:

```
raw_data: [-7.5, 1.23, 5.74, 1.9, -0.2, 3.1, -2.75, ...]
```

Data points lying outside the bin range will be stored in an underflow or overflow bin and are not considered when performing the fit.

Alternatively the heights of the bins can be set manually. This is done with the `bin_heights`

keyword:

```
bin_heights: [7, 21, 25, 42, 54, 51, 39, 28, 20, 12]
```

Warning

The length of `bin_heights`

must match the number of bins `n_bins`

or the length of
`bin_edges`

minus one.

The height of the underflow and overflow bin is set via the `underflow`

and `overflow`

keywords.

### Unbinned and Indexed Fits¶

Setting the data for unbinned and indexed fits is done via the `data`

keyword:

```
data: [7.420, 3.773, 5.968, 4.924, 1.468, 4.664, 1.745, 2.144, 3.836, 3.132, 1.568]
```

### Data label and axis labels¶

The name of the dataset or its label is set with the `label`

keyword, axis labels can be set
with the `x_label`

and `y_label`

keywords:

```
label: "My Data"
x_label: "X Values with latex $\\tau$ (µs)"
y_label: "$y_0$-label"
```

Text in between dollar signs will be interpreted as latex code.
The labels are used in the graphical output of *kafe2go*.

Todo

Add errors for HistFits and IndexedFits, implement and add for UnbinnedFits

## Setting a model function¶

A model function is defined with the `model_function`

keyword, followed by Python code as a
string:

```
model_function: |
def exponential_model(x, A0=1., x0=5.):
# Our model is a simple exponential function
# The kwargs in the function header specify parameter defaults.
return A0 * np.exp(x/x0)
```

Note the block style indicate `|`

which indicates a multiline string and keeps line breaks.

Additionally the output names for the model and its parameters can be changed.
Then the `model_function`

block gains its own keywords and the Python code is moved to the
`python_code`

sub keyword:

```
model_function:
python_code: |
def exponential_model(x, A0=1., x0=5.):
# Our model is a simple exponential function
# The kwargs in the function header specify parameter defaults.
return A0 * np.exp(x/x0)
name: "exponential function"
latex_name: "\\exp"
expression_string: "{A0} * exp({x}/{x0})"
latex_expression_string: "{A0} e^{{\\frac{{{x}}}{{{x0}}}}}"
arg_formatters:
x: 'x'
x0: "x_0"
A0:
- name: A
- latex_name: A_0
```

All other keywords are pretty much self-explanatory:

`name`

is the model function name for the terminal output. If omitted the function name from the definition will be used.`latex_name`

is the model function name for the graphical output. If omitted the function name from the definition will be used.`expression_string`

is the model function expression for the terminal output. If omitted, the output won’t have any function expression after its name. Every parameter name inside curly brackets which matches the parameter names from the function definition will be replaced with its formatted version defined in`arg_formatters`

.`latex_expression_string`

is the same as`expression_string`

but for the graphical output and supports latex syntax.`arg_formatters`

defines the replacements for the function parameters. If only one string is given (see x and x0 in the example), the default name will be used for the terminal output and the given string will be used for the graphical latex output. If`name`

and`latex_name`

are defined, they are used for terminal and graphical outputs (see A0).

Note

Special characters inside the strings need to be escaped. E.g. a single `\`

needs to be
`\\`

.

Note

Inside the latex expression string, `{`

and `}`

for latex expression like `\\frac`

need to
be doubled, because single curly brackets are used for replacing the parameters with their
respective latex names. E.g. kafe2 tries to replace `{x0}`

with its latex string `x_0`

in
this example.

## Parameter Constraints¶

The parameter constraints specified with *kafe2go* require the same information as those
specified with Python code:
parameter names, values, and uncertainties.

### Simple Gaussian Constraints¶

Simple gaussian parameter constraints can be defined by parameter name like this:

```
parameter_constraints:
a:
value: 10.0
uncertainty: 0.001 # a = 10.0+-0.001
b:
value: 0.6
uncertainty: 0.006
relative: true # Make constraint uncertainty relative to value, b = 0.6+-0.6%
```

The same can also be done with a list and the name keyword:

```
parameter_constraints:
- name: a
value: 10.0
uncertainty: 0.001 # a = 10.0+-0.001
- name: b
value: 0.6
uncertainty: 0.006
relative: true # Make constraint uncertainty relative to value, b = 0.6+-0.6%
```

### Matrix Gaussian Constraints¶

Matrix constraints can only be specified using the list format since they constrain multiple
parameters, possibly making the first format ambiguous.
Inside a list element, the type can be set with the `type: matrix`

keyword and a covariance
matrix can be given via the `matrix`

keyword like this:

```
parameter_constraints:
- type: matrix
names: [a, b]
values: [1.3, 2.5]
matrix: [[1.1, 0.1], [0.1, 2.4]]
- type: simple
name: c
value: 5.2
uncertainty: 0.001
```

Here `type: simple`

can be omitted, as a simple gaussian constraint is assumed when no type
is given.

A covariance matrix is assumed by default for matrix constraints. Correlation matrices are
supported as well. The matrix type can be set via the `matrix_type`

keyword.
Only `matrix_type: cov`

for covariance matrices and `matrix_type: cor`

for correlation matrices
are supported.

## Fixing and limiting parameters¶

Fixing and limiting parameters is just as simple as the following example. Please use the parameter names as they are defined inside the model function (see: Setting a model function).

```
fixed_parameters:
a: 1
b: 11.5
limited_parameters:
c: [0.0, 1.0]
d: [-5, 5]
e: [0.0, null]
```

Note that a limited parameter needs two arguments: a lower and an upper limit.
The first value of the list is the lower limit and the second value is the upper limit.
For a one-sided limit simply set the argument for the side that you don’t want to limit to `null`

.
For technical reasons parameter limits are *inclusive*, meaning that the specified bounds are
included in the range of allowed parameter values.
For example, in the above configuration the parameter *e* is limited to non-negative numbers and
*can* become 0 during the fit.
If the final fit result is close to or at the parameter limits, the limits should be reassessed,
as the final minimum of the cost function might be a local minimum for the given limits.