Frequently Asked Questions

What is GTC?

The GUM Tree Calculator (GTC) is a software tool designed to simplify the application of international guidelines on how to calculate measurement uncertainty and report results are readily available [1]. GTC also extends the approach recommended for real-valued quantities in those guidelines so that problems involving complex-valued quantities can be handled.

GTC is developed at the Measurement Standards Laboratory of New Zealand (MSL) [3], the national metrology institute in New Zealand.

GTC can be used as an interactive calculator, or as a batch processing tool. It is self-contained (requiring no supporting software), programmable (using the Python language [2]) and can be configured for specific applications.

We think that GTC will appeal to a wide range of users, from students of engineering and physical sciences needing to process experimental data, to professional metrologists working in calibration laboratories that have strict requirements for quality standards.

Being a stand-alone Windows application, GTC will resilient to changes elsewhere in a computer system. This is important in the context of quality standards such as ISO 17025 [4] (which many calibration laboratories adhere to, including MSL).

GTC runs on Windows operating systems [5]. It is a simple console application (i.e. command prompt) without a graphical user interface.

What does that funny symbol mean?

Python defines symbols for a variety of operations. For example, ** represents ‘to the power of’, e.g.

>>> 2**3
8

If you encounter a symbol and want to find out what it means, use the Python Help file. Type in the symbol at the index search tab on the left. Here is an example using the % symbol

Help about the ``%`` symbol

The information available may be a little terse. If so, choose a few key words from the Help file and then do an internet search on them.

For example, suppose we need information about %. We select the % formatting entry in the Help, which is the right topic, but find the information there difficult to follow. Nevertheless, from what we see, the topic of interest is something like ‘string formatting’. So, then an internet search on “Python string formatting tutorial” brings up a range of helpful material.

How do I report a bug in GTC?

Please send us a short example that demonstrates the problem.

Can I do a type-A analysis on a set of uncertain numbers?

There will be situations where data is subject to some errors that are accounted for by type-B uncertainty components, while other sources of error cause the observations to fluctuate, so a type-A analysis would be appropriate.

For example, an instrument readout is subject to an unknown offset error, due to imperfect adjustment, in addition to noise that changes from one reading to the next. The offset error estimate is zero, but there is uncertainty associated with this estimate.

Suppose five readings are observed when the input stimulus is fixed

1.2090047238650097, 1.1920239005254694, 1.2023705451450373,
1.1999502398020352, 1.2120802857623008

and the type-B standard uncertainty associated with the offset error is 0.01.

We first create a sequence of uncertain-number data in which each element is influenced by the same offset error

>>> x = [1.2090047238650097, 1.1920239005254694, 1.2023705451450373,
... 1.1999502398020352, 1.2120802857623008]
>>> e_offset = ureal(0,0.01,label='offset')
>>> data = [ x_i + e_offset for x_i in x ]

A type-A analysis of this data can be done using estimate, which looks only at the values of the elements in data

>>> data_a = type_a.estimate( data, label='type-A' )
>>> data_a
ureal(1.2030859390199704, 0.003525928111849485, 4, label=type-A)

This is a conventional type-A evaluation of the sample mean, based on the five observations.

Independently, we may do a calculation with propagation of uncertainty using function.mean

>>> data_b = function.mean(data)
>>> data_b
ureal(1.2030859390199704, 0.010000000000000002, inf)

In that case the uncertainty associated with the mean is the same as the uncertainty of a single reading, because the adjustment error is systematic and is not reduced by averaging.

In one last step, these two results can be combined to obtain an uncertain number that allows for both the influence of random noise and the offset error

>>> mu = type_a.merge_components(data_a,data_b)
>>> mu
ureal(1.2030859390199704, 0.01060340365401273, 327.15032481132585)
>>> for cpt in rp.budget(mu,trim=0):
...         print "  %s: %G" % cpt
...
  offset: 0.01
  type-A: 0.00352593

Note

Several function names are deliberately paired in the type_a and function modules, to suggest that this type of analysis can be carried out. Various types of linear regression may be used in this way, as well as the calculation of a mean, as shown here.

Can I use CSV (comma-separated value) files?

It is possible to read and write comma-separated value (CSV) files. There is a standard Python module available for this.

Some knowledge of Python is required.

A simple example is given in Reading and Writing CSV files.

Can I use .XLS spreadsheet files?

Three third-party packages (xlrd, xlwt and xlutils) that support .xls files are included in the installation directory (usually C:\Users\user.name\AppData\Local\GTC\lib). With these modules it is possible to read and write .xls files.

A useful guide is available http://www.simplistix.co.uk/presentations/python-excel.pdf.

Some knowledge of Python is required.

A simple example with GTC is given in Reading and Writing XLS files.

Can I use .XLSX spreadsheet files?

A third-party package (openpyxl) that supports .xlsx files is included in GTC. With this module it is possible to read and write .xlsx files, although not while they are open in a spreadsheet application.

A useful guide is available at http://packages.python.org/openpyxl/tutorial.html.

Some knowledge of Python is required.

A simple example is given in Reading and Writing XLSX files.

Can I use RTF (rich text format) files?

A third-party package called PyRTF is included in the installation directory (usually C:\Users\user.name\AppData\Local\GTC\lib).

See http://pyrtf.sourceforge.net/ for further details.

How do I define an uncertain number with relative uncertainty?

Suppose that measurement of a quantity \(A\) yields \(a=125.56\) with a relative uncertainty of \(u(a)/a = 0.05\). We can define an uncertain number e_rel for the relative error

>>> a = 125.56
>>> e_rel = ureal(1,0.05)

then an uncertain number representing \(A\) is

>>> A = a * e_rel
>>> A
ureal(125.56, 6.2780000000000005, inf)

Is there a simple way to chain GTC calculations?

Often a calculation proceeds in distinct stages and it is convenient to separate these in different files.

If the first part of a calculation is contained in one file but the remaining steps are in another. The results of the first calculation can be passed to the second.

Multiple files can be processed in GTC by putting their names together on the command line. For example,

C:\my work>gtc first_file.py second_file.py

would process first_file.py and then second_file.py, as if they were just one big file.

If this method is not suitable, then Storing uncertain numbers and restoring them in a later calculation is another possibility.

Why does the GTC window close before I can read anything?

If an error occurs while running GTC, the GTC command window may close before the error message can be read.

Try running the same script using The SciTE editor, which will show error messages in the output window. Alternatively, open a Command Prompt and run the script (see The Command Prompt). The Command Prompt window should stay open and display any error messages.

Evaluating a component of uncertainty with respect to a result

The function component is provided to evaluate the component of uncertainty due to an elementary uncertain number in a result. For example,

>>> I = ureal(1E-3,1E-5)
>>> R = ureal(1E3,1)
>>> V = I*R
>>> P = V**2/R
>>> component(P,I)
2e-05

It is also possible to declare intermediate uncertain number results and evaluate the corresponding components of uncertainty. Declaration of an intermediate uncertain number result uses the function result. For instance,

>>> I = ureal(1E-3,1E-5,label='I')
>>> R = ureal(1E3,1,label='R')
>>> V = result( I*R, label='V' )
>>> summary(V)
'V: 1.000, u=0.010, df=inf'
>>> P = V**2/R
>>> component(P,V)
2.0099751242241783E-05
>>> for i,u in rp.budget(P,[V,I,R]):
...         print "{}: {}".format(i,u)
...
V: 2.00997512422e-05
I: 2e-05
R: 1e-06

Intermediate results that depend on each other

The function result provides a way to refer to specific intermediate steps in a calculation. In cases where one intermediate result depends on another, the use of result can be used to avoid subtle ambiguities in the calculation. Here is a simple example, which is presented in terms of partial derivatives to make it easier to follow the mathematical steps (problems defined using elementary uncertain numbers with uncertainties of unity are equivalent to working with partial derivatives).

Suppose that \(x\) and \(y\) are problem inputs and that \(u\), \(v\) and \(w\) are calculated as follows

\[u=x, v=u+y+1 \text{ and } w=u+v\]

What is \(\partial w / \partial u\)? The answer intended is probably 1.0, but it is easy to come up with an alternative answer of 2.0, because \(v\) depends on \(u\). In fact, the question is not properly posed. It could mean what is \(\partial w / \partial u\), where \(u = x\), or it could mean what is \(\partial w / \partial u\), where \(u\) is one argument of the sum \(w=u+v\)? Here is how these two different calculations can be coded in GTC (assuming that \(x=1\) and \(y=2\)). Note that the, first, more intuitive, coding probably leads to an undesirable result!

First, what is \(\partial w / \partial u\), where \(u = x\)

>>> x = ureal(1,1,label='x')
>>> y = ureal(2,1,label='y')
>>> u = x
>>> v = u + y + 1
>>> w = u + v
>>> component(w,u)
2.0
>>> component(w,x)
2.0

Here component returns 2.0, because the calculation finds a dependency on \(u\) in each argument of the sum \(w\); the chain rule is applied. To force GTC to interpret \(u\) as just an argument of \(w=u+v\), ignoring the dependency of \(v\) on \(u\), we must declare an explicit intermediate uncertain number result (here u_arg) using result. In effect, the argument \(u\) in \(w=u+v\) is associated with a different object in memory

>>> x = ureal(1,1,label='x')
>>> y = ureal(2,1,label='y')
>>> u = x
>>> v = u + y + 1
>>> u_arg = result(u,label='u_arg')
>>> w = u_arg + v
>>> component(w,u_arg)
1.0

This identifies a distinct entity \(u_{\mathrm arg}\), so there is no dependence of \(v\) now on \(u_{\mathrm arg}\), so the calculation of \(\partial w / \partial u_{\mathrm arg}\) returns the expected value 1.0.

Footnotes

[1]BIPM and IEC and IFCC and ISO and IUPAC and IUPAP and OIML, Evaluation of measurement data - Guide to the expression of uncertainty in measurement JCGM 100:2008 (GUM 1995 with minor corrections), (2008) http://www.bipm.org/en/publications/guides/gum
[2]http://www.python.org/
[3]http://msl.irl.cri.nz/
[4]ISO/IEC 17025:2005, General requirements for the competence of testing and calibration laboratories (see http://en.wikipedia.org/wiki/ISO/IEC_17025)
[5]GTC is a ‘win32 console’ application that will run on Windows 7 and Windows 10.