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()
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 printinguc(ufloat, format)
: Number formating alias- Like
num
function but with ufloat argumentlit(reference, value, deviation)
: Compare to literature value, seeliterature_value()
lit(3.141, $0)
– Compare with literature value of pi
lit(3.141, $0,$1)
– Compare including deviationrnd(value, digits)
: roundingrnd($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.