User Guide

This guide will give a short overview of the basic functions in maabara package. For further details you may check the reference guide as well.

Basic setup

First and foremost all the magic requires an import:

import maabara as ma

If you only need propagation of uncertainty you may reduce import:

from maabara import uncertainty

Basic error propagation

To begin a computation you have to initialize a calculation object and assign it to a variable of your choice.

ekin = ma.uncertainty.Sheet()

Next it is necessary to specify an equation for the following calculation.

ekin.set_equation("Rational(1,2)*m*V**2")

You may use fundamental functions like sin, exp, sqrt, atan etc. and Rational(a,b) to define a fraction a/b.

Note

Allowed variable names are alphanumeric and use _ only. They must be specifed by set_value(). Avoid using I as variable name since it will be interpreted as imaginary unit.

Additionaly you may specify a name for the so described term.

ekin.set_name("E_{kin}")

Abbreviatory it is possible to set an equation and name during init.

ekin = ma.uncertainty.Sheet("Rational(1,2)*m*V**2", "E_{kin}")

Each variable used in equation has to be specified in value through set_value command. It takes symbol name, value and its deviation. You may also set an optional Latex markup replacement. If given, all symbol occurrences in equations will be replaced by the more complex Latex expression.

ekin.set_value('m',5,0.1)
ekin.set_value('V',1,tex='\\nu_{A}')

That’s it, time to get the results.

>>> ekin.print_result()
2.5+/-0.05

print_result-function will return the result as ufloat and print out the corresponding Latex markup:

\(E_{kin}=\frac{m}{2} \cdot \nu_{A}^{2}\)

E_{kin}=\frac{m}{2} \cdot \nu_{A}^{2}

\(E_{kin}=2.50 \pm 0.05\)

E_{kin}=2.50 \pm 0.05

\(\sigma_{E_{kin}}=\frac{\sigma_{m}}{2} \cdot \nu_{A}^{2}\)

\sigma_{E_{kin}}=\frac{\sigma_{m}}{2} \cdot \nu_{A}^{2}

You might change multipler symbol by passing a Latex code for it to print_result-function.

To sum up see a more complex and subsumed example below.

phi = ma.uncertainty.Sheet("atan(w*L/(Ro+Ra+Rl))")
phi.set_value("w",1272,4,"\\omega_R")
phi.set_value("L",0.36606,0.00004,"L")
phi.set_value("Ro",9.9,0.05,"R_\\Omega")
phi.set_value("Ra",10.5,1,"R_A")
phi.set_value("Rl",65.4,0.1,"R_L")
phi.print_result()
\[\operatorname{atan}{\left (\frac{L \cdot \omega_R}{R_A + R_L + R_\Omega} \right )} = 1.3886 \pm 0.0022\]

You’ll be happy it is a computer which does computation of uncertainty in this case …

Abbreviations

But still life can be easier. The frequently used methods provide short alias names to save time.

Method Abbreviation
set_equation() eq()
set_name() n()
set_value() v()
print_result() p() or ps()

Batch data

But what if you want to process a bunch of values in equal expressions? In this case it is recommend to use the batch-method which will efficiently iterate the calculations and result in a numpy array.

If not yet happend retrieve a computation object and set equation.

stack = ma.uncertainty.Sheet('a*x**3')

The multiple data should be given by an array wherein the datasets to compute are specified row-by-row.

         #  a   x   x_error
data =  [ [0.5, 1. , 0.1],
          [0.3, 2. ,0.15] ]

It is possible to set constant values or errors before calling batch method. The batch method will automaticly use the constant values, if not overridden by the array data.

stack.set_value('a', error=0.05)    # set constant error for a

To run the computation you have to pass the data array and a list of columns fields divided by | to batch-method. Deviations columns must be suffix by %.

>>> stack.batch(data, 'a|x|x%')
array([[ 0.5       ,  0.15811388],
       [ 2.4       ,  0.6720119 ]])     # line-by-line result with uncertainty

It will return an numpy array wherein each row represents an input-corresponding value-deviation result. By passing exact to mode parameter it will be rounded to significant digits. Moreover ufloat-mode will result in an ufloated array:

>>> stack.set_value('a',1., 0.05)          # define constant a value
>>> stack.batch(data, '*|x|x%', 'ufloat')  # rerun computation ignoring first data column
array([[1.0+/-0.30000000000000004],
       [8.0+/-1.7999999999999998]], dtype=object)

As you might conjectured * denotes a data column to be ignored in computation.

Generate Latex Tables

But how to document a bunch of calculated values cleverly? Latex Table class will help you to generate tables functional and fast.

Assign to a Table object first.

tbl = ma.latex.Table()

You can add columns easily with add_column function.

tbl.add_column( ['Example', 1.0] )

The arbitrative feature is that you can render data in a special way. Let’s say you stored the computation results from batch() in a results variable.

results = [[ 0.5       ,  0.15811388],
           [ 2.4       ,  0.6720119 ]]

To format these results in an appropiate form you can use function instruction. Moreover you might set a column title.

tbl.add_column(results, 'num($0,$1)', 'Results')

$x will link to x. column of dataset. Without $ the value will be interpreted as constant in each row. Available functions are:

num(value, deviation, format) : Number formating

num($0) – Format first column in data as number

num($0,0.1) – Format numbers with constant uncertainty 0.1

num($0,$1) – Dynamic uncertainty from second column of data

num($0,$1,{:L}) – Optional format for ufloat printing

uc(ufloat, format) : Number formating alias
Like num function but with ufloat argument
lit(reference, value, deviation) : Compare to literature value, see literature_value()

lit(3.141, $0) – Compare with literature value of pi

lit(3.141, $0,$1) – Compare including deviation

rnd(value, digits) : rounding
rnd($0,3) – round numbers in 3 digits

Note

num will be default if no function name was specified: $0,$1 will be interpreted as num($0,$1). You can use shorthand alias c() instead of add_column()

Before you generate the final Latex markup, you might customize some settings.

tbl.set_caption('My table')
tbl.set_label('tbl:label1')
tbl.set_placement('[htb]')

Read the function reference to get a more detailed overview of provided functionality.

What you will get is a copyable Latex table.

>>> print tbl.latex()
\begin{table}[htb]
\centering
\begin{tabular}{|l|l|}
\hline
 & Results\\
\hline
Example & $0,50 \pm 0,16$\\
\hline
1.0 & $2,4 \pm 0,7$\\
\hline
\end{tabular}
\caption{My table}\label{tbl:label1}\end{table}

It most cases it makes sense to save it directly to a file so you can include it trought \input directive in your Latex document.

>>> print tbl.export('table1.tex')
\input{table1.tex}

Handling experimental data

Maabara provides a set of helper functions which allow to process experimental data, e.g. calculate weighted average, statistical deviation or linear regressions.

For a detailed documentation you might read the data reference documentation.