@decidables/discountable-elements

v0.3.6

Published

7 months ago

discountable-elements: Web Components for visualizing Hyperbolic Temporal Discounting

Downloads

0High
0Medium
0Low

web component explorable explanation explorable decision making decidables hyperbolic temporal discounting temporal discounting delay discounting discountable

`@decidables/discountable-elements`Web Components for Visualizing Hyperbolic Temporal Discounting in diskountable

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.

Usage

Install

yarn add @decidables/discountable-elements

Use

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.

Components

Building blocks for interactive visualizations of HTD

`DiscountableControl` / `<discountable-control>`

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
  - 1 to 100 in steps of 1
duration: number = undefined
- 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
  - 10 to 4000 in steps of 10
run: boolean = false
- Show a button to run the task
pause: boolean = false
- Show a button to pause the task
reset: boolean = false
- 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
- detail
  - trials: number
    - The new number of trials
discountable-control-duration
- Indicates the duration of trials slider has been adjusted
- detail
  - duration: number
    - The new duration
discountable-control-run
- Indicates the run button has been pushed
discountable-control-pause
- Indicates the pause button has been pushed
discountable-control-reset
- Indicates the reset button has been pushed

Example

<discountable-control trials="15" duration="1500" run pause reset></discountable-control>

`DiscountableResponse` / `<discountable-response>`

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.

Attributes

interactive: boolean = false
- Allow user to respond, instead of just displaying simulated model responses
feedback: boolean = false
- Display response feedback, i.e. 'First'
trial: boolean = false
- 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
  - as: number
    - Amount of smaller sooner option
  - ds: number
    - Delay of smaller sooner option
  - al: number
    - Amount of larger later option
  - dl: number
    - Delay of larger later option
  - trial: number
    - The count of the trial within the block
stop()
- 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
first()
- Emulate a 'first' response
second()
- Emulate an 'second' response
responded(response)
- Emulate a response
- Parameters
  - response: string
    - Whether to emulate a 'first' or 'second' response
reset()
- 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
- detail
  - trial: number
    - The count of this trial in the block
  - as: number
    - Amount of smaller sooner option
  - ds: number
    - Delay of smaller sooner option
  - al: number
    - Amount of larger later option
  - dl: number
    - Delay of larger later option
  - response: string
    - Whether the response was 'first' or 'second'

Example

<discountable-response interactive feedback trial></discountable-response>

`HTDCalculation` / `<htd-calculation>`

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
interactive: boolean = false
- Allow editing of numeric values
amount-ss: number = 20
- Amount of smaller sooner option
delay-ss: number = 5
- Delay of smaller sooner option
amount-ll: number = 50
- Amount of larger later option
delay-ll: number = 40
- Delay of larger later option
k: number = 0.1
- Parameter k (discounting factor)

Custom Events

htd-calculation-change
- Indicates that the values in the calculation have changed
- detail
  - as: number
    - Amount of smaller sooner option
  - ds: number
    - Delay of smaller sooner option
  - al: number
    - Amount of larger later option
  - dl: number
    - Delay of larger later option
  - k: number
    - Parameter k (discounting factor)

Example

<htd-calculation numeric interactive amount-ss="20" delay-ss="10" amount-ll="80" delay-ll="50" k="0.05"></htd-calculation>

`HTDFit` / `<htd-fit>`

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
clear()
- Removes all choice data, and initiates a data-free initial fit
get(name = 'default')
- Gets the specified choice data
- Parameters
  - name: string = 'default'
    - Identifier for the choice data
- Return value
  - choice: object or null
    - as: number
      - Amount of smaller sooner option
    - ds: number
      - Delay of smaller sooner option
    - al: number
      - Amount of larger later option
    - dl: number
      - Delay of larger later option
    - response: string
      - Chosen option, either 'first' or 'second'
    - name: string
      - Identifier for choice
    - label: string
      - Label for choice
set(as, ds, al, dl, response, name = '', label = '')
- Creates or changes the specified choice data
- Parameters
  - as: number
    - Amount of smaller sooner option
  - ds: number
    - Delay of smaller sooner option
  - al: number
    - Amount of larger later option
  - dl: number
    - Delay of larger later option
  - response: string
    - Chosen option, either 'first' or 'second'
  - name: string
    - Identifier for choice
  - label: string
    - Label for choice

Custom Events

htd-fit-update
- Indicates that the fit has completed
- detail
  - k: number
    - New value for parameter k (discounting factor)

Example

<htd-fit></htd-fit>

`HTDCurves` / `<htd-curves>`

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: number = null
- Amount
delay: number = null
- Delay
k: number = 0.1
- Parameter k (discounting factor)
label: string = ''
- Label for data point

Methods

trial(as, ds, al, dl, trial, response)
- Creates or changes the specified trial data
- Parameters
  - as: number
    - Amount of smaller sooner option
  - ds: number
    - Delay of smaller sooner option
  - al: number
    - Amount of larger later option
  - dl: number
    - Delay of larger later option
  - trial: number
    - Trial count
  - response: string
    - Chosen option, either 'first' or 'second'
pauseTrial()
- Pause trial animations
resumeTrial()
- Resume trial animations
clearOptions()
- Remove all options except the default
removeOption(name)
- Remove the identified option
- Parameters
  - name: string
    - Identifier for option
getOption(name = 'default')
- Retrieve the identified option
- Parameters
  - name: string = 'default'
    - Identifier for option
- Return value
  - option: object
    - name: string
      - Identifier for option
    - a: number
      - Amount of option
    - d: number
      - Delay of option
    - label: string
      - Label for option
setOption(a, d, name = 'default', label = '', trial = false)
- Create or change the identified option
- Parameters
  - a: number
    - Amount of option
  - d: number
    - Delay of option
  - name: string = 'default'
    - Identifier for option
  - label: string = ''
    - Label for option
  - trial: boolean = false
    - Is this for an animated trial?

Custom Events

htd-curves-change
- Indicates that an option has changed
- detail
  - name: string
    - Identifier for option
  - a: number
    - Amount
  - d: number
    - Delay
  - k: number
    - Parameter k (discounting factor)
  - label: string
    - Label for option

Example

<htd-curves interactive amount="60" delay="30" k="0.05" label="1"></htd-curves>

`ITCChoice` / `<itc-choice>`

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-ss: number = 20
- Amount of smaller sooner option
delay-ss: number = 5
- Delay of smaller sooner option
amount-ll: number = 50
- Amount of larger later option
delay-ll: number = 40
- Delay of larger later option
state: string = 'choice'
- Current state of the display
- Options
  - 'choice'
    - Show the options with a question mark in between
  - 'fixation'
    - Show blank pies with a fixation in between
  - 'blank'
    - 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
- detail
  - as: number
    - Amount of smaller sooner option
  - ds: number
    - Delay of smaller sooner option
  - al: number
    - Amount of larger later option
  - dl: number
    - Delay of larger later option

Example

<itc-choice interactive amount-ss="20" delay-ss="10" amount-ll="80" delay-ll="50" state="choice"></itc-choice>

`ITCOption` / `<itc-option>`

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: number = 20
- Amount of option
delay: number = 5
- Delay of option
state: string = 'choice'
- Current state of the display
- Options
  - 'choice'
    - Show the option quantities
  - 'fixation'
    - Show blank option
  - 'blank'
    - Show blank option

Custom Events

itc-option-change
- Indicates that the option has been changed
- detail
  - a: number
    - Amount
  - d: number
    - delay

Example

<itc-option interactive amount="75" delay="25" state="choice"></itc-option>

`ITCTask` / `<itc-task>`

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
iti: number = 2000
- Duration of inter-trial interval in milliseconds
trials: number = 5
- Number of trials per block
running: boolean = false
- 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
itc-block-end
- Indicates the completion of a block of trials
- detail for itc-block-start and itc-block-end
  - trials: number
    - Number of trials in the block
itc-trial-start
- Indicates the beginning of a trial (iti is over and stimulus is about to start)
itc-trial-end
- Indicates the end of a trial (stimulus is over and iti is about to start)
- detail for itc-trial-start and itc-trial-end
  - trials: number
    - Number of trials in the block
  - duration: number
    - Duration of stimulus in milliseconds
  - iti: number
    - Duration of inter-trial interval in milliseconds
  - trial: number
    - Count of trial in block (one-based)
  - as: number
    - Amount of smaller sooner option
  - ds: number
    - Delay of smaller sooner option
  - al: number
    - Amount of larger later option
  - dl: number
    - Delay of larger later option

Example

<itc-task duration="3000" iti="500" trials="10" running></itc-task>

Equations

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` / `<htd-equation-adk2v>`

Subjective value from objective amount and delay, and a discounting factor

Attributes

numeric: boolean = false
- Show values instead of just the names of variables
interactive: boolean = false
- Allow editing of numeric values in the equation
amount: number = 100
- Amount
delay: number = 30
- Delay
k: number = 0.05
- Parameter k (discounting factor)

Properties

v: number
- Value

Custom Events

htd-equation-adk2v-change
- Indicates that the values in the equation have changed
- detail
  - a: number
    - New value of amount
  - d: number
    - New value of delay
  - k: number
    - New value of parameter k (discounting factor)
  - v: number
    - New subjective value

Example

<htd-equation-adk2v numeric interactive amount="20" delay="10" k="0.2"></htd-equation-adk2v>

`HTDEquation`

Base class for all interactive HTD equations

To define a new equation:

export default class HTDEquationSomething extends HTDEquation {
  ...
}

HTDEquation extends DiscountableElement extends DecidablesElement extends LitElement

Examples

Full examples built from multiple components

`HTDExampleHuman` / `<htd-example-human>`

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.

Slots

unnamed
- Place relevant discountable-elements components here
- Wired elements
  - <discountable-control>
    - Allows user to adjust parameters and control the task
  - <discountable-response>
    - Allows user to make responses and see feedback
  - <htd-fit>
    - Fits the user's responses to HTD using a Bayesian model running in a Web Worker
  - <htd-curves>
    - Displays the options as amounts with delays with discounting curves based on the current model parameters
  - <itc-task>
    - Displays the task

Example

<htd-example-human>
  <discountable-control trials="10" run pause reset></discountable-control>
  <itc-task trials="10"></itc-task>
  <discountable-response interactive trial feedback></discountable-response>
  <htd-curves></htd-curves>
  <htd-fit></htd-fit>
</htd-example-human>

`HTDExampleInteractive` / `<htd-example-interactive>`

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
delay-ss: number = 1
- Smaller sooner delay
amount-ll: number = 50
- Larger later amount
delay-ll: number = 40
- Larger later delay
k: number = 0.05
- Parameter k (discounting factor)

Slots

unnamed
- Place relevant discountable-elements components here
- Wired elements
  - <htd-calculation>
    - Display and change the value calculations
  - <htd-curves>
    - Displays the options as amounts with delays with discounting curves based on the current model parameters
  - <itc-choice>
    - Display and change the choice between smaller sooner and larger later options

Example

<htd-example-interactive a1="5" d1="20" a2="30" d2="350" k="0.01">
  <itc-choice interactive></itc-choice>
  <htd-curves interactive></htd-curves>
  <htd-calculation numeric interactive></htd-calculation>
</htd-example-interactive>

`HTDExampleModel` / `<htd-example-model>`

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.

k: number = 0.2
- Parameter k (discounting factor)

Slots

unnamed
- Place relevant discountable-elements components here
- Wired elements
  - <discountable-control>
    - Allows user to adjust parameters and control the task
  - <discountable-response>
    - Allows user to view model responses and feedback
  - <htd-calculation>
    - Display the value calculations
  - <htd-curves>
    - Displays the options as amounts with delays with discounting curves based on the current model parameter, which can be changed
  - <itc-task>
    - Displays the task

Example

<htd-example-model k="0.2" >
  <discountable-control trials="10" run pause reset></discountable-control>
  <itc-task trials="10"></itc-task>
  <htd-curves interactive></htd-curves>
  <discountable-response trial feedback></discountable-response>
</htd-example-model>

`HTDExample`

Base class for all HTD examples

To define a new example:

export default class HTDExampleSomething extends HTDExample {
  ...
}

HTDExample extends DiscountableElement extends DecidablesElement extends LitElement

Base class

`DiscountableElement`

Base class for all discountable web components

To define a new element:

export default class DiscountableElementSomething extends DiscountableElement {
  ...
}

DiscountableElement extends DecidablesElement extends LitElement

Development

Features/Bugs/Notes

Add to HTDMath
- Luce choice rule

Package Scripts

yarn lint
- Lints scripts in src/
yarn test
- Runs all tests and reports coverage in test/coverage/
yarn test:watch
- Runs all tests in watch mode and reports coverage in test/coverage/
yarn test:file <filename>
- Runs tests for a single file and reports coverage in test/coverage/
yarn build
- Builds browser-compatible optimized bundle from src/ to lib/

File Organization

discountable-elements/
- lib/ (Bundles created from src/ by build) [autogenerated]
- src/ (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.html (Report on js bundle composition and size) [autogenerated]

License

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).

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@decidables/discountable-elementsWeb Components for Visualizing Hyperbolic Temporal Discounting in diskountable

Usage

Install

Use

Contents

Components

DiscountableControl / <discountable-control>

Attributes

Methods

Custom Events

Example

DiscountableResponse / <discountable-response>

Attributes

Methods

Custom Events

Example

HTDCalculation / <htd-calculation>

Attributes

Custom Events

Example

HTDFit / <htd-fit>

Methods

Custom Events

Example

HTDCurves / <htd-curves>

Attributes

Methods

Custom Events

Example

ITCChoice / <itc-choice>

Attributes

Custom Events

Example

ITCOption / <itc-option>

Attributes

Custom Events

Example

ITCTask / <itc-task>

Attributes

Methods

Custom Events

Example

Equations

HTDEquationADK2V / <htd-equation-adk2v>

Attributes

Properties

Custom Events

Example

HTDEquation

Examples

HTDExampleHuman / <htd-example-human>

Slots

Example

HTDExampleInteractive / <htd-example-interactive>

Attributes

Slots

Example

HTDExampleModel / <htd-example-model>

Attributes

Slots

Example

HTDExample

Base class

DiscountableElement

Development

Features/Bugs/Notes

Package Scripts

File Organization

License

`@decidables/discountable-elements`Web Components for Visualizing Hyperbolic Temporal Discounting in diskountable

`DiscountableControl` / `<discountable-control>`

`DiscountableResponse` / `<discountable-response>`

`HTDCalculation` / `<htd-calculation>`

`HTDFit` / `<htd-fit>`

`HTDCurves` / `<htd-curves>`

`ITCChoice` / `<itc-choice>`

`ITCOption` / `<itc-option>`

`ITCTask` / `<itc-task>`

`HTDEquationADK2V` / `<htd-equation-adk2v>`

`HTDEquation`

`HTDExampleHuman` / `<htd-example-human>`

`HTDExampleInteractive` / `<htd-example-interactive>`

`HTDExampleModel` / `<htd-example-model>`

`HTDExample`

`DiscountableElement`