9 Uncertainty descriptions
u attaches a description of uncertainty to a value. It does not calculate uncertainty or say that the description is scientifically adequate.
Compact
#lang sciencelogo |
workflow "Time a pendulum" |
period = 2.01 u [ |
declared = [ |
timing-resolution = [type = "epistemic" estimate = 0.02 unit = "s"] |
trial-spread = [type = "aleatory" estimate = unknown] |
] |
omitted = [reaction-delay = [reason = "not estimated"]] |
] |
print period |
print period.u.declared.timing-resolution.estimate |
Verbose
#lang sciencelogo |
workflow "Time a pendulum" |
set period to 2.01 with uncertainty [ |
set declared to [ |
set timing-resolution to [set type to "epistemic" set estimate to 0.02 set unit to "s"] |
set trial-spread to [set type to "aleatory" set estimate to unknown] |
] |
set omitted to [set reaction-delay to [set reason to "not estimated"]] |
] |
print period |
print estimate of period.u.declared.timing-resolution |
The first print shows 2.01. The second shows 0.02. The value and its description remain separate to read: period is the value, and period.u is its uncertainty record. u is a reserved word. It can follow any value expression; use parentheses to qualify the entire expression, as in (duration / swings) u [ ... ].
9.1 Named sources
The u record accepts only declared and omitted at its top level. Both are records of named sources. Each source is a record with freely chosen fields. An absent collection or [] is empty. For example, value u [] explicitly records no sources in either collection. It does not mean zero uncertainty. A value with no u has no attached description; reading its .u path is an error.
Put a considered source under declared, even when its magnitude is unknown or judged negligible. Put a known source that is left out under omitted, and describe why when useful. The language does not require a particular estimate, unit, or reason field.
type is an ordinary, optional source field. It can distinguish "aleatory" from "epistemic", use another label, or hold more than one label, such as type = ["aleatory" "epistemic"]. These words are not language keywords. A library can define a more specific vocabulary for a particular method.
9.2 Reading and revising
Read a source through its name, such as period.u.omitted.reaction-delay.reason. A direct copy such as other-period = period keeps the attached description. Later edits to one name do not change the copy.
period.u.declared.timing-resolution.estimate = 0.03 revises a field in the description. period.u = [declared = [ ... ]] replaces the description on an already qualified value. Assigning a new plain value to period replaces both the old value and its attachment; write u [ ... ] again if the new value has a description. += is rejected on a qualified value.
Arithmetic and comparisons use the underlying value. Arithmetic does not calculate or carry uncertainty forward, so describe uncertainty on a derived result explicitly, for example result = (period / 2) u [ ... ]. Applications can inspect the written description to assess uncertainty by methods they define. See the compact uncertainty contract for the complete reader and update rules.