@decidables/prospectable-math/README.md

prospectable-math: Equations for calculating Cumulative Prospect Theory

<!--lint ignore first-heading-level  maximum-heading-length-->

# **`@decidables/prospectable-math`**<br>Equations for Calculating Cumulative Prospect Theory in [<b>prospect<i>α</i>b<i>λ</i>e</b>](https://decidables.github.io/prospectable)

[![npm version](https://img.shields.io/npm/v/@decidables/prospectable-math?logo=npm)](https://www.npmjs.com/package/@decidables/prospectable-math)
[![license](https://img.shields.io/npm/l/@decidables/prospectable-math?color=informational)](https://github.com/decidables/decidables/blob/main/LICENSE.md)

Helper functions for calculations related to Cumulative Prospect Theory for
[<b>prospect<i>α</i>b<i>λ</i>e</b>](https://decidables.github.io/prospectable).

## Usage

### Install

```shell
yarn add @decidables/prospectable-math
```

### Use

```javascript
import CPTMath from '@decidables/prospectable-math';
```

A class providing static functions for calculating Signal Detection Theory equations

## Contents

### `CPTMath`

Single class exposing static functions for CPT calculations. Each function takes values for one or
more variables and returns the value of another variable. The functions are named with a list of the
input variables followed by a '2' followed by the output variable, in camelcase. For example,
`hM2Hr` takes as input the number of hits, `H`, and the number of misses, `M`, and outputs the hit
rate, `HR`

#### Variable names

- x = objective value
- p = probability
- v = subjective value
- w = decision weight
- u = subjective utility
- a = α (alpha, diminishing marginal utility)
- l = λ (lambda, loss aversion)
- g = γ (gamma, probability distortion)

#### Parameters

- a = α (alpha, diminishing marginal utility) [0, 1]
- l = λ (lambda, loss aversion) [0, Infinity)
- g = γ (gamma, probability distortion) [0, 1]

The values offered for parameters are:

- DEFAULT = a recommended default value
- MIN = the minimum value recommended for a UI (not necessarily the lower bound of its interval)
- MAX = the maximum value recommended for a UI (not necessarily the upper bound of its interval)
- STEP = a recommended step size for a UI
- JUMP = a recommended "large" step size for a UI

#### Methods w/implemented equations

- `xal2v(x, a, l)`
  - v = if (x >= 0) x^a; if (x < 0) -l * (-x)^a
- `xlv2a(x, l, v)`
  - a = if (x >= 0) log(v) / log(x); if (x < 0) (log(-v) - log(l)) / log(-x)
- `xav2l(x, a, v)`
  - a = if (x >= 0) 1; if (x < 0) -v / (-x)^a
- `pg2w(p, g)`
  - w = p^g / (p^g + (1 - p)^g)^(1 / g)
- `vw2u(v, w)`
  - u = Sum_n(v_n * w_n)
  - Accepts numbers or equal-length arrays of numbers

## Development

### Features/Bugs/Notes

### Package Scripts

- `yarn lint`
  - Lints markdown, scripts and styles
- `yarn test`
  - Runs all tests and reports coverage in `test/coverage/`
- `yarn test --watch`
- `yarn test -w`
  - Runs all tests in watch mode and reports coverage in `test/coverage/`
- `yarn test <directory/filename>`
  - Runs tests for a single file and reports coverage in `test/coverage/`
- `yarn test <directory/filename> --watch`
- `yarn test <directory/filename> -w`
  - Runs tests for a single file in watch mode and reports coverage in `test/coverage/`
- `yarn build`
  - Builds bundles from `src/` to `lib/`

### File Organization

- `prospectable-elements/`
  - `lib/` (Bundles created from `src/` by `build`) **\[autogenerated\]**
  - `src/` (Source files)
  - `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](https://github.com/decidables/decidables/blob/main/LICENSE.md)

The content of this project is licensed under [Creative Commons Attribution-ShareAlike 4.0
International License (CC-BY-SA-4.0)](https://creativecommons.org/licenses/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)](https://www.gnu.org/licenses/gpl-3.0.html).