Macaw.Data.Quantity (macaw_data v0.16.0)

View Source

A fixed list of quantities, each with its facts: a base unit, a kind, bounds, additivity, and display families by unit system (spec/03 §8–§13).

A quantity is what a unit measures. A unit (a UCUM code, Macaw.Data.Unit) and a quantity together are a measure, %{unit: code, quantity: quantity}, the two facts a field description carries. They are facts about the data, not knobs: a measure does not change a value, it says what the value already is, so a display can choose how to show it.

The list is fixed and grows by proposal: duration, information, data_rate, frequency, ratio, count, temperature, length, speed, power, energy, pressure, area, volume, mass, pace, angle, currency, electric_potential, electric_current, electric_charge, illuminance, sound_level, mass_concentration and amount_concentration. spec/03 §8–§13 tables each one's facts and families.

  • Kind is :linear, :affine (a temperature), :logarithmic (a sound level) or :cyclic (an angle, whose mean is circular).
  • Bounds are a display hint, never validation: a difference is legitimately negative, so a value outside them is never refused.
  • Additivity depends on the aggregation: additivity/2 refines the quantity's defaults across series and over time by the field's metric kind (:gauge, :counter, :rate).
  • Unit systems are :metric, :us, :uk and :as_posted; a system picks the family a value is shown in and never touches the data.

Information is decimal by default: UCUM's kBy and Telemetry.Metrics' :kilobyte are 1,000 bytes, and a unit written with a binary prefix (MiBy) or in bit belongs to its own family. The data picks it; no setting does.

How a value is drawn in its family (the display unit, tick formats, a value's label in a locale) is the drawing library's: visualize's Visualize.Quantity keeps it, over this vocabulary.

The vocabulary half of visualize's Visualize.Quantity.

Examples

iex> Macaw.Data.Quantity.family!(:mass, "kg", :us)
["[oz_av]", "[lb_av]"]

iex> Macaw.Data.Quantity.additivity!(:data_rate)
%{across: true, over_time: false}

iex> Macaw.Data.Quantity.label!(%{unit: "{request}"})
"request"

Summary

Types

How a quantity's values combine (spec/03 §9).

A unit and a quantity, either or both; the two facts a field description carries.

How a field's values were measured, which refines its quantity's additivity.

Why a measure does not resolve.

A unit system: a display preference, never applied to the data.

t()

One of the fixed list of quantities.

Functions

Whether a sum of the quantity's values means anything (spec/03 §10, D-155): %{across: boolean, over_time: boolean} — summing several series at one instant, and summing one series over time. The quantity's physical defaults are refined by the field's metric kind: a :gauge and a :rate never add over time, and a :counter's increments add over time when the quantity adds across. No quantity (a plain number) defaults to both.

As additivity/2, the map alone, raising Macaw.Data.Error naming the reason.

The fixed list of quantities (spec/03 §8).

A quantity's base unit, the unit its values are in when no unit is given; nil for a :currency, whose code the data must say. {:ok, unit}, or {:error, {:unknown_quantity, quantity}} for a quantity not in all/0 (spec/00 §5); base_unit!/1 answers the unit or raises.

As base_unit/1, the unit alone, raising Macaw.Data.Error naming the quantity.

Where a quantity's values physically lie, in its base unit, {min | nil, max | nil} (spec/03 §9): a display hint an axis may anchor at, never validation — a value outside them is never refused.

A quantity's bounds in a unit of it: the base's, converted, as {:ok, bounds}. A unit without a factor (Cel) takes the base's bounds as they are. A unit that is no code, or not of the quantity's dimension, is Macaw.Data.Unit.convert/3's {:error, reason} (spec/00 §5); bounds!/2 answers the bounds or raises.

As bounds/1, the bounds alone, raising Macaw.Data.Error naming the quantity.

The display family a unit of the quantity belongs to, smallest first; [] for a unit of no family's shape (spec/03 §11). Within the unit's convention (family/3), a unit belongs to the first family holding a member of its shape — its atoms and exponents, prefixes aside and a binary prefix kept apart — so the unit picks among a quantity's families: bits, binary prefixes, hertz, watt-hours, US lengths. No unit means the base unit.

The display family a system shows a unit of the quantity in (spec/03 §11, D-158): the family the unit's convention names for :metric, :us or :uk when it names one, else the unit's own (family/2), which is what :as_posted always is.

As family/2, the family alone, raising Macaw.Data.Error naming the reason.

As family/3, the family alone, raising Macaw.Data.Error naming the reason.

How a quantity's values combine (spec/03 §9): :linear, :affine (a temperature), :logarithmic (a sound level) or :cyclic (an angle).

As kind/1, the kind alone, raising Macaw.Data.Error naming the quantity.

The label rule (spec/03 §14): the unit, else the quantity, else nothing — the unit's symbol with its annotations written when it is not empty, else the quantity's name with spaces for underscores, else nil, as {:ok, label}. A measure resolve/1 refuses is its {:error, reason} (spec/00 §5); label!/1 answers the label or raises.

As label/1, the label alone, raising Macaw.Data.Error naming the reason.

The quantity a code's dimension implies, or nil when none of the list has it. A dimensionless code holding % is a :ratio, any other a :count, and a code of one currency alone ({iso4217:USD}) a :currency.

As of_unit/1, the quantity alone, raising Macaw.Data.Error in Macaw.Data.Unit.format_error/1's words.

A measure completed and checked (spec/03 §13): a unit alone implies its quantity, a quantity alone means its base unit, and a unit whose dimension is not its quantity's is refused. A :ratio or a :count takes any dimensionless unit, and a :currency a code of one currency alone.

The unit systems a display may prefer (spec/03 §12), :as_posted the default.

Types

kind()

@type kind() :: :linear | :affine | :logarithmic | :cyclic

How a quantity's values combine (spec/03 §9).

measure()

@type measure() :: %{
  optional(:unit) => Macaw.Data.Unit.code() | nil,
  optional(:quantity) => t() | nil
}

A unit and a quantity, either or both; the two facts a field description carries.

metric_kind()

@type metric_kind() :: :gauge | :counter | :rate

How a field's values were measured, which refines its quantity's additivity.

reason()

@type reason() ::
  {:unit, Macaw.Data.Unit.code(), Macaw.Data.Unit.reason()}
  | {:quantity, t(), Macaw.Data.Unit.code()}
  | {:unknown_quantity, term()}

Why a measure does not resolve.

system()

@type system() :: :metric | :us | :uk | :as_posted

A unit system: a display preference, never applied to the data.

t()

@type t() ::
  :duration
  | :information
  | :data_rate
  | :frequency
  | :ratio
  | :count
  | :temperature
  | :length
  | :speed
  | :power
  | :energy
  | :pressure
  | :area
  | :volume
  | :mass
  | :pace
  | :angle
  | :currency
  | :electric_potential
  | :electric_current
  | :electric_charge
  | :illuminance
  | :sound_level
  | :mass_concentration
  | :amount_concentration

One of the fixed list of quantities.

Functions

additivity(quantity, metric_kind \\ nil)

@spec additivity(t() | nil, metric_kind() | nil) ::
  {:ok, %{across: boolean(), over_time: boolean()}} | {:error, reason()}

Whether a sum of the quantity's values means anything (spec/03 §10, D-155): %{across: boolean, over_time: boolean} — summing several series at one instant, and summing one series over time. The quantity's physical defaults are refined by the field's metric kind: a :gauge and a :rate never add over time, and a :counter's increments add over time when the quantity adds across. No quantity (a plain number) defaults to both.

Examples

iex> Macaw.Data.Quantity.additivity(:count, :gauge)
{:ok, %{across: true, over_time: false}}

iex> Macaw.Data.Quantity.additivity!(:temperature, :counter)
%{across: false, over_time: false}

{:error, {:unknown_quantity, quantity}} for a quantity not in all/0, and {:error, {:unknown_metric_kind, kind}} for a metric kind not :gauge, :counter or :rate; additivity!/2 answers the map or raises.

additivity!(quantity, metric_kind \\ nil)

@spec additivity!(t() | nil, metric_kind() | nil) :: %{
  across: boolean(),
  over_time: boolean()
}

As additivity/2, the map alone, raising Macaw.Data.Error naming the reason.

all()

@spec all() :: [t(), ...]

The fixed list of quantities (spec/03 §8).

base_unit(quantity)

@spec base_unit(t()) :: {:ok, Macaw.Data.Unit.code() | nil} | {:error, reason()}

A quantity's base unit, the unit its values are in when no unit is given; nil for a :currency, whose code the data must say. {:ok, unit}, or {:error, {:unknown_quantity, quantity}} for a quantity not in all/0 (spec/00 §5); base_unit!/1 answers the unit or raises.

base_unit!(quantity)

@spec base_unit!(t()) :: Macaw.Data.Unit.code() | nil

As base_unit/1, the unit alone, raising Macaw.Data.Error naming the quantity.

bounds(quantity)

@spec bounds(t()) :: {:ok, {number() | nil, number() | nil}} | {:error, reason()}

Where a quantity's values physically lie, in its base unit, {min | nil, max | nil} (spec/03 §9): a display hint an axis may anchor at, never validation — a value outside them is never refused.

Examples

iex> Macaw.Data.Quantity.bounds(:duration)
{:ok, {0, nil}}

{:error, {:unknown_quantity, quantity}} for a quantity not in all/0; bounds!/1 answers the bounds or raises.

bounds(quantity, unit)

@spec bounds(t(), Macaw.Data.Unit.code()) ::
  {:ok, {number() | nil, number() | nil}} | {:error, term()}

A quantity's bounds in a unit of it: the base's, converted, as {:ok, bounds}. A unit without a factor (Cel) takes the base's bounds as they are. A unit that is no code, or not of the quantity's dimension, is Macaw.Data.Unit.convert/3's {:error, reason} (spec/00 §5); bounds!/2 answers the bounds or raises.

Examples

iex> Macaw.Data.Quantity.bounds(:ratio, "%")
{:ok, {0.0, 100.0}}

iex> Macaw.Data.Quantity.bounds(:ratio, "s")
{:error, {:dimension, "1", "s"}}

bounds!(quantity)

@spec bounds!(t()) :: {number() | nil, number() | nil}

As bounds/1, the bounds alone, raising Macaw.Data.Error naming the quantity.

bounds!(quantity, unit)

@spec bounds!(t(), Macaw.Data.Unit.code()) :: {number() | nil, number() | nil}

As bounds/2, the bounds alone, raising Macaw.Data.Error in Macaw.Data.Unit.format_error/1's words.

family(quantity, unit)

@spec family(t(), Macaw.Data.Unit.code() | nil) ::
  {:ok, [Macaw.Data.Unit.code()]} | {:error, term()}

The display family a unit of the quantity belongs to, smallest first; [] for a unit of no family's shape (spec/03 §11). Within the unit's convention (family/3), a unit belongs to the first family holding a member of its shape — its atoms and exponents, prefixes aside and a binary prefix kept apart — so the unit picks among a quantity's families: bits, binary prefixes, hertz, watt-hours, US lengths. No unit means the base unit.

Examples

iex> Macaw.Data.Quantity.family(:information, "MiBy")
{:ok, ["By", "KiBy", "MiBy", "GiBy", "TiBy"]}

iex> Macaw.Data.Quantity.family!(:length, "[ft_i]")
["[in_i]", "[ft_i]", "[mi_i]"]

{:error, reason} for a quantity not in all/0 ({:unknown_quantity, quantity}) or a unit that is no code (Macaw.Data.Unit.parse/1's reason); family!/2 raises it.

family(quantity, unit, system)

@spec family(t(), Macaw.Data.Unit.code() | nil, system()) ::
  {:ok, [Macaw.Data.Unit.code()]} | {:error, term()}

The display family a system shows a unit of the quantity in (spec/03 §11, D-158): the family the unit's convention names for :metric, :us or :uk when it names one, else the unit's own (family/2), which is what :as_posted always is.

A quantity read in several conventions — a pressure is gauge, barometric or clinical — picks the unit's by its exact code first, then by its shape, else the first, so a system chooses within a convention and never across: a barometric hPa is shown in inches of mercury under :us, and a blood pressure in mm[Hg] stays in it under every system.

Examples

iex> Macaw.Data.Quantity.family(:mass, "kg", :uk)
{:ok, ["[oz_av]", "[lb_av]", "[stone_av]"]}

iex> Macaw.Data.Quantity.family!(:duration, "ms", :us)
["ns", "us", "ms", "s", "min", "h", "d"]

iex> Macaw.Data.Quantity.family!(:pressure, "hPa", :us)
["[in_i'Hg]"]

iex> Macaw.Data.Quantity.family(:mass, "kg", :imperial)
{:error, {:unknown_system, :imperial}}

A quantity, a unit or a system none of systems/0 is {:error, reason}, as family/2 answers, {:unknown_system, system} for the system; family!/3 raises it.

family!(quantity, unit)

@spec family!(t(), Macaw.Data.Unit.code() | nil) :: [Macaw.Data.Unit.code()]

As family/2, the family alone, raising Macaw.Data.Error naming the reason.

family!(quantity, unit, system)

@spec family!(t(), Macaw.Data.Unit.code() | nil, system()) :: [Macaw.Data.Unit.code()]

As family/3, the family alone, raising Macaw.Data.Error naming the reason.

kind(quantity)

@spec kind(t()) :: {:ok, kind()} | {:error, reason()}

How a quantity's values combine (spec/03 §9): :linear, :affine (a temperature), :logarithmic (a sound level) or :cyclic (an angle).

Examples

iex> Macaw.Data.Quantity.kind(:angle)
{:ok, :cyclic}

iex> Macaw.Data.Quantity.kind(:vibes)
{:error, {:unknown_quantity, :vibes}}

{:error, {:unknown_quantity, quantity}} for a quantity not in all/0; kind!/1 answers the kind or raises.

kind!(quantity)

@spec kind!(t()) :: kind()

As kind/1, the kind alone, raising Macaw.Data.Error naming the quantity.

label(measure)

@spec label(measure()) :: {:ok, String.t() | nil} | {:error, reason()}

The label rule (spec/03 §14): the unit, else the quantity, else nothing — the unit's symbol with its annotations written when it is not empty, else the quantity's name with spaces for underscores, else nil, as {:ok, label}. A measure resolve/1 refuses is its {:error, reason} (spec/00 §5); label!/1 answers the label or raises.

Examples

iex> Macaw.Data.Quantity.label(%{unit: "ms"})
{:ok, "ms"}

iex> Macaw.Data.Quantity.label!(%{quantity: :count})
"count"

iex> Macaw.Data.Quantity.label!(%{})
nil

iex> Macaw.Data.Quantity.label(%{unit: "By", quantity: :duration})
{:error, {:quantity, :duration, "By"}}

label!(measure)

@spec label!(measure()) :: String.t() | nil

As label/1, the label alone, raising Macaw.Data.Error naming the reason.

of_unit(unit)

@spec of_unit(Macaw.Data.Unit.code()) :: {:ok, t() | nil} | {:error, term()}

The quantity a code's dimension implies, or nil when none of the list has it. A dimensionless code holding % is a :ratio, any other a :count, and a code of one currency alone ({iso4217:USD}) a :currency.

Examples

iex> Macaw.Data.Quantity.of_unit("kW.h")
{:ok, :energy}

iex> Macaw.Data.Quantity.of_unit!("{request}")
:count

of_unit!(unit)

@spec of_unit!(Macaw.Data.Unit.code()) :: t() | nil

As of_unit/1, the quantity alone, raising Macaw.Data.Error in Macaw.Data.Unit.format_error/1's words.

resolve(measure)

@spec resolve(measure()) ::
  {:ok, %{unit: Macaw.Data.Unit.code() | nil, quantity: t() | nil}}
  | {:error, reason()}

A measure completed and checked (spec/03 §13): a unit alone implies its quantity, a quantity alone means its base unit, and a unit whose dimension is not its quantity's is refused. A :ratio or a :count takes any dimensionless unit, and a :currency a code of one currency alone.

Examples

iex> Macaw.Data.Quantity.resolve(%{quantity: :duration})
{:ok, %{unit: "s", quantity: :duration}}

iex> Macaw.Data.Quantity.resolve(%{unit: "By", quantity: :duration})
{:error, {:quantity, :duration, "By"}}

systems()

@spec systems() :: [system(), ...]

The unit systems a display may prefer (spec/03 §12), :as_posted the default.