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

# **`@decidables/discountable-math`**<br>Equations for Calculating Hyperbolic Temporal Discounting in [<b>dis<i>k</i>ountable</b>](https://decidables.github.io/discountable)

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

Helper functions for calculations related to Hyperbolic Temporal Discounting for
[<b>dis<i>k</i>ountable</b>](https://decidables.github.io/discountable).

## Usage

### Install

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

### Use

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

A class providing static functions for calculating Hyperbolic Temporal Discounting equations

## Contents

### `HTDMath`

Single class exposing static functions for HTD 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,
`adk2v` takes as input the amount, `a`, the delay, `d`, and a discounting factor, `k`, and outputs
the value, `v`.

#### Variable names

- a = objective amount
- d = delay
- v = subjective value
- k = discounting factor

#### Parameters

- k = discount factor (0, Infinity)

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

- `adk2v(a, d, k)`
  - v = a / (1 + k * d)
- `adv2k(a, d, v)`
  - k = (a - v) / (v * d)

## 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

- `discountable-math/`
  - `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).