selector

A control that declares a parameter whose stops are written out with options: or taken from a column with column:.

selectorNodeExplained in Controls
On this page
Population in millions against year for one country at a time, with a country menu beneath the plot.Population in millions against year for one country at a time, with a country menu beneath the plot.

#Attributes

parameterRequiredImplicit
The parameter the control declares — slider:a — which is the scene's from then on, wherever the control is written. One control declares a parameter: a second for the same name in the scene is refused. An expression reads a parameter by its letter, so a parameter an expression uses is one letter; a word such as country is read in maths as a product of letters, and names a parameter no expression reads.
parameter-name
Also written: varCan be written as shorthand: selector:value
name
The row's label in the footer, in place of the parameter's letter. Rich text, so Frequency $b$ sets its own maths.
rich-text
Also written: label
column
A dataset column to take the stops from: column: #pop.year. A column of numbers gives its distinct values in ascending order as the stops, and the smallest and largest as the range; range: is not read. A column of text gives its distinct names, in the order the rows first give them. A mark's slice: on the same column draws the rows at the parameter's value.
reference
format
How the value reads in the footer. numbers; dates, a year with its fraction read as a date; months, 1 to 12 read Jan to Dec; weekdays, 1 to 7 read Mon to Sun; hours, hours from midnight read as a clock time; weeks, a year with its fraction read as a year and week; names, the data's own words. Every format but names keeps a number line, so range: and step: stay numbers. auto takes the format from the column:, and is numbers without one; a written format is used instead of the column's.
autonumbersdatesmonthsweekdayshoursweeksnames
Defaultauto
range
The ends, [start, end]. An end may be a constant expression: [0, 2pi]. Not read where column: or options: gives the stops.
parametised-interval
Default[-10, 10]
step
The distance between stops on the reader's track. Absent, 1 — or, under column:, the smallest gap between two of the column's values.
number
default
The starting value, held inside the range. Absent, 0 — or, where column: or options: gives the stops, the first of them. Where the stops are names it is an index among them, counted from 0.
number
Also written: start
hiddenAnimatable
Leaves the control's row out of the footer.
boolean
Defaultfalse
lock
Has no effect on a control: an editable graph lists its marks for the reader to change, and no control is among them.
boolean
Also written: locked
Defaultfalse
options
The stops, written out as a list: options: linear, log, logit or options: (1, 2, 5, 10). A list of numbers gives a numeric parameter with those stops in ascending order. Any entry that is not a number makes the whole list names, in the order written: 1, 2, many is three names. Square brackets are not a list: options: [1, 2] is one option. A control with both options: and column: is refused.
string-list
Also written: choices

#Derived attributes

Computed while the element renders — read one with #id.name in attribute position or {{#id.name}} in prose, never set.

valueDerived
Where the parameter currently stands. A selector whose values are names publishes the name itself.

#Allowed in

scene [ ]graph { }cue { }cue.draw { }cue.trace { }cue.highlight { }cue.spotlight { }code { }region { }flowchart { }logic { }circuit { }network { }

#Examples

Five readings with a straight line fitted through them, and a fit degree menu beneath the plot set to 1.Five readings with a straight line fitted through them, and a fit degree menu beneath the plot set to 1.
graph{
    selector:d(name: fit degree; options: 1, 2, 3, 4)
    fit(of: #readings; degree: d)
    scatter#readings(x: 1, 2, 3, 4, 5; y: 2.0, 2.4, 3.1, 4.8, 7.4)
}
The spread of a sample mean as a wide bell curve, with a sample size menu beneath the plot set to 1.The spread of a sample mean as a wide bell curve, with a sample size menu beneath the plot set to 1.
graph{
    selector:n(options: 1, 2, 5, 10, 20; name: sample size)
    curve(expression: sqrt(n / (2 * pi)) * exp(-n * x^2 / 2))
}(
    x-domain: [-3, 3]
    y-domain: [0, 2]
)
Brazil’s population in millions in 1960, 1990 and 2020, with a country menu beneath the plot.Brazil’s population in millions in 1960, 1990 and 2020, with a country menu beneath the plot.
graph{
    selector:country(column: #pop.country)
    bar(x: #pop.year; y: #pop.millions; slice: #pop.country)
}(
    x-format: discrete
)

#Notes

  • It is always discrete, so it takes no discrete:.
  • It is the control whose values can be names: options: of names, or column: naming a column of text, gives a parameter holding a name, and a mark's slice: on that column draws the rows carrying it.
  • The footer offers its stops as a list when they are names or there are 2 to 12 of them, and as a track otherwise.
  • cue.selector is the same control with the scene stepping through the choices.

#Writing guidance

  • Steps, timers, sweeps & parameters — New content on the step that introduces it, timers for timed motion, sweeps for a change the prose describes, and parameters where one sentence holds across the range.

Last updated