Attributes & Reads

const Unknown = UnknownValue()

Singleton representing an actively-indeterminate attribute value. Unlike missing, an Unknown value is inserted into a computed environment and propagates/overrides like a normal value — it asserts "unknown here" down to descendants, rather than silently deferring to an ancestor.

const attribute_kinds::Dict{Symbol,AttributeKind}

Registry of every AttributeKind defined with @attribute, keyed by name. Kinds registered in any module are also added here. Look up a single kind with @attr_str (attr"Temperature") rather than indexing this directly.

mutable struct Attribute

Attribute values define the environmental properties of Location objects. There is a single concrete Attribute type for every environmental variable — the specific kind (Temperature, Humidity, ...) is carried as data (an AttributeKind), not as a distinct Julia type.

value is one of:

• a Real: a concrete reading, stored in kind.unit.
• missing: no local opinion — environment defers to an inherited value.
• Unknown: actively indeterminate — asserts "unknown" down to descendants.

struct AttributeKind

A named, interned, immutable value describing a kind of environmental attribute (e.g. :Temperature, :Humidity), mirroring LocationKind. Registered via @attribute.

Fields:

• name: the kind's unique identifier.
• unit: canonical storage unit (e.g. u"°C") — values are converted to this unit on construction.

struct UnknownValue end

Sentinel type for an attribute value that is actively indeterminate (e.g. a broken sensor), as distinct from missing ("no local opinion, defer to an ancestor's value"). Use the singleton Unknown.

See also: isunknown

attribute_kind(x::Attribute)

Access the AttributeKind of an Attribute

attribute_unit(x::Attribute)

Access the canonical unit of an Attribute

isunknown(x::Attribute)

Return true if x's value is the Unknown sentinel. Mirrors ismissing.

quantity(x::Attribute)

Return the quantity of an Attribute. Returns missing/Unknown unchanged if the attribute's value is missing/Unknown.

set_attribute!(x::AttributeDict,attribute::Attribute)

Set the value for key attribute.kind.name of dict to attribute.

This method keeps each attribute under the name of its own kind, so the key and the attribute always match.

value(x::Attribute)

Access the value property of an Attribute

@attr_str(kind)

String macro to recall an AttributeKind registered with @attribute by name, mirroring @loc_str (and sharing its lookup machinery). @attribute doesn't export the name it defines (to avoid flooding the namespace of anyone who usings a lab module with dozens of kind names), so this is the collision-safe way to look one up without needing to using the specific lab module that defined it.

Example:

julia> attr"Temperature"
AttributeKind(Temperature)

@attribute name unit

Define a new AttributeKind and register it under name, both as a const binding and in the attribute_kinds registry — mirrors @species/@location_kind. name is directly callable as a constructor, e.g. Temperature(10u"°C").

Example:

julia> using Unitful
julia> @attribute Temperature u"°C"

julia> Temperature(10u"°C")
10.0 °C

See also: Attribute

const _environment_cache

Evictable, external cache for environment results, keyed by object identity. Entries are reclaimed automatically once a Location is garbage-collected.

environment(x::Location)

Compute the environmental attributes of location x: x's own non-missing attributes overriding its parent's (already-computed, cached) environment.

missing attribute values mean "no local opinion, defer to the inherited value" and are skipped. Unknown values are inserted like any concrete value — they assert "unknown here" down to descendants unless a more proximal location overrides with a real reading or an explicit missing.

Results are cached (see invalidate_environment!); the cache is bounded by whatever's currently resident in memory.

invalidate_environment!(x::Location)

Clear the cached environment for x and every currently-resident descendant. Called whenever x's attributes or tree position change (set_attribute!, move_into!, remove!).

const read_kinds::Dict{Symbol,ReadKind}

Registry of every ReadKind defined with @read, keyed by name. Kinds registered in any module are also added here. Look up a single kind with @read_str (read"Absorbance") rather than indexing this directly.

struct Read

Read values represent a single instrument measurement of a Location — the specific kind (Absorbance, Fluorescence, ...) is carried as data (a ReadKind), not as a distinct Julia type, mirroring Attribute. Unlike Attribute, Read is immutable: nothing ever edits a Read in place, since many independent Reads of the same ReadKind can coexist for the same location at once (as opposed to Attribute's single-slot-per-kind, overwritable semantics) — see reads/record_read!.

value is one of:

• a Real (quantitative kinds only): a concrete measurement, stored in kind.unit.
• a String (qualitative kinds only): a categorical result or free-text observation, validated against kind.allowed_values if that's set.
• Unknown: the instrument attempted this read and got an indeterminate/invalid result (sensor error, saturation, timeout).
• missing: this location was in scope for a batch of reads but produced no result (e.g. masked out of a plate scan) — distinct from never having attempted a read at all.

time is the instrument's own recorded time for this read (nothing if unknown/unavailable) — kept as data only, never compared across different instruments. See read_time.

struct ReadKind

A named, interned, immutable value describing a kind of instrument measurement (e.g. :Absorbance, :ColorimetricResult), mirroring AttributeKind/LocationKind. Registered via @read.

A ReadKind is either quantitative or qualitative — mode is data, not a distinct type (mirroring how LocationKind avoids a type per kind):

• Quantitative: unit is set (e.g. u"percent") — values are Real, converted to unit on construction. See is_quantitative.
• Qualitative: unit is nothing — values are String. allowed_values, if set, constrains them to a fixed enumerated set (e.g. a colorimetric result); if nothing, any string is accepted (free-text observation). See is_qualitative.

Fields:

• name: the kind's unique identifier.
• unit: canonical storage unit for a quantitative kind; nothing for a qualitative kind.
• allowed_values: the fixed set of valid strings for a constrained qualitative kind; nothing for a quantitative kind, or for an unconstrained (free-text) qualitative kind.

is_qualitative(k::ReadKind)

Return true if k is a qualitative (string-valued) kind.

is_quantitative(k::ReadKind)

Return true if k is a quantitative (unit-bearing) kind.

quantity(x::Read)

Return the quantity of a Read. Returns missing/Unknown unchanged if the read's value is missing/Unknown. For a qualitative read, there's no unit to attach – returns the raw String value as-is. Mirrors quantity(x::Attribute).

read_kind(x::Read)

Access the ReadKind of a Read. Mirrors attribute_kind.

read_time(x::Read)

Access the instrument's own recorded time for a Read, or nothing if unavailable. Named to avoid colliding with Base.time.

read_unit(x::Read)

Access the canonical unit of a Read. Mirrors attribute_unit.

value(x::Read)

Access the value property of a Read. Mirrors value(x::Attribute).

@read name unit=nothing allowed_values=nothing

Define a new ReadKind and register it under name, both as a const binding and in the read_kinds registry — mirrors @attribute. name is directly callable as a constructor, e.g. Absorbance(0.9u"percent") or ColorimetricResult("Positive").

Examples:

julia> using Unitful
julia> @read Absorbance u"percent"       # quantitative
julia> Absorbance(90u"percent")
90.0 %

julia> @read Observation                 # qualitative, free text
julia> Observation("looked a bit cloudy")

julia> @read ColorimetricResult nothing Set(["Positive","Negative"])  # qualitative, constrained
julia> ColorimetricResult("Positive")

See also: Read

@read_str(kind)

String macro to recall a ReadKind registered with @read by name, mirroring @loc_str/@attr_str (and sharing their lookup machinery). @read doesn't export the name it defines (to avoid flooding the namespace of anyone who usings a lab module with dozens of kind names), so this is the collision-safe way to look one up without needing to using the specific lab module that defined it.

Example:

julia> read"Absorbance"
ReadKind(Absorbance)