discountable-elements: Web Components for visualizing Hyperbolic Temporal Discounting
npm install @decidables/discountable-elements@decidables/discountable-elements
The web components used to visualize Hyperbolic Temporal Discounting in
diskountable. There is an emphasis
on direct manipulation and consistent use of color. SVG is used extensively to provide clean
scalable diagrams.
``shell`
yarn add @decidables/discountable-elements
`javascript`
import '@decidables/discountable-elements';
A bare import is used to register the elements in the custom registry, so they are then available
for use in HTML.
Building blocks for interactive visualizations of HTD
#### DiscountableControl /
Control panel for HTD demos
A configurable set of controls for user manipulation of examples of hyperbolic temporal discounting.
Controls can be provided for the number of trials, the timing of trials, and for running, pausing,
or resetting a block of trials.
##### Attributes
- trials: number = undefined
- Show a slider for setting the number of trials, initialized to the value provided
- Options
- to 100 in steps of 1
-
- Show a slider for setting the duration of the stimulus, wait, and inter-trial interval on each
trial, initialized to the value provided in milliseconds
- Options
- to 4000 in steps of 10
-
- Show a button to run the task
-
- Show a button to pause the task
-
- Show a button to reset the task
##### Methods
- complete()
- Indicates that a trial block is done, so it can no longer be paused
##### Custom Events
- discountable-control-trials
- Indicates the number of trials slider has been adjusted
-
-
- The new number of trials
-
- Indicates the duration of trials slider has been adjusted
-
-
- The new duration
-
- Indicates the run button has been pushed
-
- Indicates the pause button has been pushed
-
- Indicates the reset button has been pushed
##### Example
`html`
#### DiscountableResponse /
Response buttons and feedback for inter-temporal choice tasks
This element provides 'first' and 'second' response buttons. It can also display a running count
of the trials and display response feedback.
Also accepts keyboard responses: ArrowLeft for 'first' button and ArrowRight for
'second' button.
##### Attributes
- interactive: boolean = false
- Allow user to respond, instead of just displaying simulated model responses
-
- Display response feedback, i.e. 'First'
-
- Display the running count of trials, i.e. 'Trial: 2 of 10'
##### Methods
- start(as, ds, al, dl, trial)
- Indicates that a trial has started, and its time to wait for a response
- Parameters
-
- Amount of smaller sooner option
-
- Delay of smaller sooner option
-
- Amount of larger later option
-
- Delay of larger later option
-
- The count of the trial within the block
-
- Indicates that the trial is over and it is time to display any requested feedback
- Note: If no response has been made yet, the trial is recorded as having no response
-
- Emulate a 'first' response
-
- Emulate an 'second' response
-
- Emulate a response
- Parameters
-
- Whether to emulate a or 'second' responsereset()
-
- Reset to the state at the start of a block of trials
##### Custom Events
- discountable-response
- Indicates that a response has been made on this trial
-
-
- The count of this trial in the block
-
- Amount of smaller sooner option
-
- Delay of smaller sooner option
-
- Amount of larger later option
-
- Delay of larger later option
-
- Whether the response was or 'second'
##### Example
`html`
#### HTDCalculation /
Calculation and comparison of subjective value for smaller sooner and larger later options
Displays a live comparison of the subjective values for smaller sooner and larger later options,
indicating which one is better, or if they are equal. Breaks the calculation down into multiple
steps. Leverages the concepts from live equations to explicitly link objective amount and delay to
subjective value.
##### Attributes
- numeric: boolean = false
- Show values instead of just the names of variables
-
- Allow editing of numeric values
-
- Amount of smaller sooner option
-
- Delay of smaller sooner option
-
- Amount of larger later option
-
- Delay of larger later option
-
- Parameter k (discounting factor)
##### Custom Events
- htd-calculation-change
- Indicates that the values in the calculation have changed
-
-
- Amount of smaller sooner option
-
- Delay of smaller sooner option
-
- Amount of larger later option
-
- Delay of larger later option
-
- Parameter k (discounting factor)
##### Example
`html`
#### HTDFit /
Fits HTD parameters to empirical data using a Bayesian model running in a WebWorker
The component displays trace plots of the sampling and histograms of the posterior distributions for
the k and luce parameters. The model consists of the following:
- Parameters
- k: gamma prior with mean of 2 and shape of 3
- luce: gamma prior with mean of 2 and shape of 3
- Data (for ith trial)
- as_i: smaller sooner amount
- ds_i: smaller sooner delay
- al_i: larger later amount
- dl_i: larger later delay
- response_i: 'first' (smaller sooner) or 'second' (larger later)
- Functions
- v(): subjective value
- v = a / (1 + k * d)
- choice(): Luce choice probability
- cg = 1 / (1 + e^(luce * (vs - vl)))
- Model
- vs_i: subjective value of the ith smaller sooner option
- vs_i = v(as_i, ds_i, k)
- vl_i: subjective value of the ith larger later option
- vl_i = v(al_i, dl_i, k)
- cg_i: probability of choosing the ith smaller sooner option
- cg_i = choice(vs_i, vl_i, luce)
- choice_i: Bernoulli distribution given response_i and cg_i
##### Methods
- fit()
- Initiates a new fit, or queues one if the model is already fitting
-
- Removes all choice data, and initiates a data-free initial fit
-
- Gets the specified choice data
- Parameters
-
- Identifier for the choice data
- Return value
- or null
-
- Amount of smaller sooner option
-
- Delay of smaller sooner option
-
- Amount of larger later option
-
- Delay of larger later option
-
- Chosen option, either or 'second'
-
- Identifier for choice
-
- Label for choice
-
- Creates or changes the specified choice data
- Parameters
-
- Amount of smaller sooner option
-
- Delay of smaller sooner option
-
- Amount of larger later option
-
- Delay of larger later option
-
- Chosen option, either or 'second'
-
- Identifier for choice
-
- Label for choice
##### Custom Events
- htd-fit-update
- Indicates that the fit has completed
-
-
- New value for parameter k (discounting factor)
##### Example
`html`
#### HTDCurves /
Temporal discounting curves for HTD
Displays options as an amount to be received at a certain delay, with a discounting curve
illustrating the present value of that option. The amount, the delay, and the discounting curve can
be directly manipulated.
##### Attributes
- interactive: boolean = false
- Allow direct manipulation of functions or data points
-
- Amount
-
- Delay
-
- Parameter k (discounting factor)
-
- Label for data point
##### Methods
- trial(as, ds, al, dl, trial, response)
- Creates or changes the specified trial data
- Parameters
-
- Amount of smaller sooner option
-
- Delay of smaller sooner option
-
- Amount of larger later option
-
- Delay of larger later option
-
- Trial count
-
- Chosen option, either or 'second'
-
- Pause trial animations
-
- Resume trial animations
-
- Remove all options except the default
-
- Remove the identified option
- Parameters
-
- Identifier for option
-
- Retrieve the identified option
- Parameters
-
- Identifier for option
- Return value
-
-
- Identifier for option
-
- Amount of option
-
- Delay of option
-
- Label for option
-
- Create or change the identified option
- Parameters
-
- Amount of option
-
- Delay of option
-
- Identifier for option
-
- Label for option
-
- Is this for an animated trial?
##### Custom Events
- htd-curves-change
- Indicates that an option has changed
-
-
- Identifier for option
-
- Amount
-
- Delay
-
- Parameter k (discounting factor)
-
- Label for option
##### Example
`html`
#### HTDParameters /
Control panel for HTD model parameters
A configurable set of controls for user manipulation of HTD model parameters. Controls can be
provided for the discounting factor.
##### Attributes
- k: number = undefined
- Show a slider for setting the discounting factor, initialized to the value provided
- Options
- to 100 in steps of 0.001
##### Methods
##### Custom Events
- ddm-parameters-k
- Indicates an update to the discounting factor
-
-
- New value for the discounting factor
##### Example
`html`
#### ITCChoice /
A choice between two options at different times
Presents a choice between two options, one smaller sooner and one larger later. The display can
either show the choice, a fixation, or a blank display. It is optionally interactive, in which case
the amounts and the delays can be edited.
##### Attributes
- interactive: boolean = false
- Allow direct manipulation of probabilities and values
-
- Amount of smaller sooner option
-
- Delay of smaller sooner option
-
- Amount of larger later option
-
- Delay of larger later option
-
- Current state of the display
- Options
-
- Show the options with a question mark in between
-
- Show blank pies with a fixation in between
-
- Show blank pies with a dot in between
##### Custom Events
- itc-choice-change
- Indicates that one or more numbers in the choice have been changed
-
-
- Amount of smaller sooner option
-
- Delay of smaller sooner option
-
- Amount of larger later option
-
- Delay of larger later option
##### Example
`html`
#### ITCOption /
A single decision option consisting of an amount and a delay
Displays its amount and delay numerically.
Optionally, the amount and the delay can be edited.
##### Attributes
- interactive: boolean = false
- Allow direct manipulation of probabilities and values
-
- Amount of option
-
- Delay of option
-
- Current state of the display
- Options
-
- Show the option quantities
-
- Show blank option
-
- Show blank option
##### Custom Events
- itc-option-change
- Indicates that the option has been changed
-
-
- Amount
-
- delay
##### Example
`html`
#### ITCTask /
Displays stimuli for inter-temporal choice task
When run, a block of trials is presented. Before each trial is an inter-trial interval (ITI). Each
trial then consists of a stimulus during which a participant can respond. The stimulus consists of
two options, each of which is represented as an amount at a delay.The choice is generally between a
smaller sooner option and a larger later option. The task can be paused and then resumed, and it can
also be reset and run again.
##### Attributes
- duration: number = 2000
- Duration of stimulus in milliseconds
-
- Duration of inter-trial interval in milliseconds
-
- Number of trials per block
-
- Currently executing block of trials
##### Methods
- reset()
- Stops a currently running or ended block of trials and resets everything to be ready to run
again
##### Custom Events
- itc-block-start
- Indicates the beginning of a block of trials
-
- Indicates the completion of a block of trials
- for itc-block-start and itc-block-end
-
- Number of trials in the block
-
- Indicates the beginning of a trial (iti is over and stimulus is about to start)
-
- Indicates the end of a trial (stimulus is over and iti is about to start)
- for itc-trial-start and itc-trial-end
- duration: number
- Number of trials in the block
-
- Duration of stimulus in milliseconds
-
- Duration of inter-trial interval in milliseconds
-
- Count of trial in block (one-based)
-
- Amount of smaller sooner option
-
- Delay of smaller sooner option
-
- Amount of larger later option
-
- Delay of larger later option
##### Example
`html`
Interactive equations for HTD
The equations can either be static and display the variable names, be static and display names and
values or be interactive with names and editable values, in which case only the values on the right
side of the equals sign are editable.
Note: The layout for these equations leaves something to be desired, especially on smaller
screens. Ideally a proper math renderer would be used, but I haven't found one that takes kindly to
insertion of the custom elements needed for live editing.
#### HTDEquationADK2V /
Subjective value from objective amount and delay, and a discounting factor
##### Attributes
- numeric: boolean = false
- Show values instead of just the names of variables
-
- Allow editing of numeric values in the equation
-
- Amount
-
- Delay
-
- Parameter k (discounting factor)
##### Properties
- v: number
- Value
##### Custom Events
- htd-equation-adk2v-change
- Indicates that the values in the equation have changed
-
-
- New value of amount
-
- New value of delay
-
- New value of parameter k (discounting factor)
-
- New subjective value
##### Example
`html`
#### HTDEquation
Base class for all interactive HTD equations
To define a new equation:
`javascript`
export default class HTDEquationSomething extends HTDEquation {
...
}
HTDEquation extends DiscountableElement extends DecidablesElement extends LitElement
Full examples built from multiple components
#### HTDExampleHuman /
User runs task, and results are fit and displayed in real-time using HTD
Used to build examples where the user is performing the inter-temporal choice task. Can include
controls, the task itself, response buttons with feedback, HTD curves, and trace plots and
histograms for the parameters in the model fit. The HTD curves should not be interactive, because
their rendering is determined by the user's task performance.
##### Attributes
Note: Since model parameter attributes are set on the example, they don't need to be set on the
individual components, as they will be propagated and kept in sync.
- trials: number = 10
- Number of trials to run
-
- The duration of the stimulus, wait, and inter-trial interval on each trial, initialized to the
value provided in milliseconds
-
- Parameter k (discounting factor)
##### Slots
- unnamed
- Place relevant discountable-elements components here
- Wired elements
-
- Allows user to adjust parameters and control the task
-
- Allows user to make responses and see feedback
-
- Fits the user's responses to HTD using a Bayesian model running in a Web Worker
-
- Displays the options as amounts with delays with discounting curves based on the current
model parameters
-
- Displays the task
##### Example
`html`
#### HTDExampleInteractive /
Explore how decision and HTD model parameters relate
Used to build examples where the user can explore the relationship between a choice and model
parameters. Can include the choice, a visual rendering of the comparative value calculation, and the
HTD curves with the current options. All components can be interactive.
##### Attributes
Note: Since many attributes are set on the example, they don't need to be set on the individual
components, as they will be propagated and kept in sync.
- amount-ss: number = 10
- Smaller sooner amount
-
- Smaller sooner delay
-
- Larger later amount
-
- Larger later delay
-
- Parameter k (discounting factor)
##### Slots
- unnamed
- Place relevant discountable-elements components here
- Wired elements
-
- Display and change the value calculations
-
- Allows user to adjust model parameters with sliders
-
- Displays the model parameters for current fit
-
- Displays the options as amounts with delays with discounting curves based on the current
model parameters
-
- Display and change the choice between smaller sooner and larger later options
##### Example
`html`
#### HTDExampleModel /
Model simulates task based on HTD parameter values
Used to build examples where the model is simulated to perform the inter-temporal choice task. Can
include controls, the task itself, response buttons with feedback, and a visual rendering of the HTD
curves. The HTD curves should be interactive, so the user can modify the model. The responses should
not be interactive, because their values are received from the model's task performance.
##### Attributes
Note: Since model parameter attributes are set on the example, they don't need to be set on the
individual components, as they will be propagated and kept in sync.
- trials: number = 10
- Number of trials to run
-
- The duration of the stimulus, wait, and inter-trial interval on each trial, initialized to the
value provided in milliseconds
-
- Parameter k (discounting factor)
##### Slots
- unnamed
- Place relevant discountable-elements components here
- Wired elements
-
- Allows user to adjust parameters and control the task
-
- Allows user to view model responses and feedback
-
- Display the value calculations
-
- Displays the options as amounts with delays with discounting curves based on the current
model parameter, which can be changed
-
- Displays the task
##### Example
`html`
#### HTDExample
Base class for all HTD examples
To define a new example:
`javascript`
export default class HTDExampleSomething extends HTDExample {
...
}
HTDExample extends DiscountableElement extends DecidablesElement extends LitElement
#### DiscountableElement
Base class for all discountable web components
To define a new element:
`javascript`
export default class DiscountableElementSomething extends DiscountableElement {
...
}
DiscountableElement extends DecidablesElement extends LitElement
- Add to HTDMath
- Luce choice rule
- yarn lint
- Lints scripts in
-
- Runs all tests and reports coverage in
-
-
- Runs all tests in watch mode and reports coverage in
-
- Runs tests for a single file and reports coverage in
-
-
- Runs tests for a single file in watch mode and reports coverage in
-
- Builds browser-compatible optimized bundle from to lib/
- discountable-elements/
- (Bundles created from src/ by build)src/
\[autogenerated\]
- (Source files)components/
- (Source for visualizations)equations/
- (Source for equations)examples/
- (Source for examples combining visualizations)test/
- (Testing files)coverage/
- (Code coverage results) \[autogenerated\]CHANGELOG.md
- (Based on conventional commits) \[autogenerated\]gulpfile.js
- (Tasks for gulp)package.json
- (Package config for yarn and npm)README.md
- (This file)rollup-stats.auto.html` (Report on js bundle composition and size) \[autogenerated\]
-
The content of this project is licensed under Creative Commons Attribution-ShareAlike 4.0
International License (CC-BY-SA-4.0) and the
source code of this project is licensed under GNU General Public License v3.0 or any later version
(GPL-3.0-or-later).