# Module: LocusZoom_ScaleFunctions

Plugin registry of available functions that can be used in scalable layout directives.

These "scale functions" are used during rendering to return output (eg color) based on input value

Source:
  - helpers/scalable.js, line 1
See:
  - module:LocusZoom_DataLayers~ScalableParameter for details on how scale functions are used by datalayers

### Methods

#### (inner) categorical_bin(parameters)

Function to sort values of any type into bins based on direct equality testing with a list of categories. Will return null if provided an input value that does not match to a listed category.

##### Parameters:

Name | Type | Description
--- | --- | ---
`parameters` | Object | ###### Properties
Name | Type | Description
--- | --- | ---
`categories` | Array | Array of values against which to evaluate the input value. Must be of equal length to values parameter. If the input value is equal to category n then returned value is the nth entry in the values parameter.
`values` | Array | Array of values to return given evaluations against categories. Must be of equal length to categories parameter. Each entry n represents the value to return if the input value is equal to the nth value in the categories parameter.
`null_value` | * | Value to return if the input value fails to match to any categories. Optional.

Source:
  - helpers/scalable.js, line 66

#### (inner) effect_direction(parameters, input) → {null}

Calculate the effect direction based on beta, or the combination of beta and standard error. Typically used with phewas plots, to show point shape based on the beta and stderr_beta fields.

##### Parameters:

Name | Type | Description
--- | --- | ---
`parameters` |  | ###### Properties
Name | Type | Description
--- | --- | ---
`'+'` |  | The value to return if the effect direction is positive
`'-'` |  | The value to return if the effect direction is positive
`beta_field` |  | The name of the field containing beta
`stderr_beta_field` |  | The name of the field containing stderr_beta
`input` | Object | This function should receive the entire datum object, rather than one single field

Source:
  - helpers/scalable.js, line 210

##### Returns:

Type
  null

#### (inner) if(parameters, value)

Basic conditional function to evaluate the value of the input field and return based on equality.

##### Parameters:

Name | Type | Description
--- | --- | ---
`parameters` | Object | ###### Properties
Name | Type | Description
--- | --- | ---
`field_value` | * | The value against which to test the input value.
`then` | * | The value to return if the input value matches the field value
`else` | * | The value to return if the input value does not match the field value. Optional. If not defined this scale function will return null (or value of null_value parameter, if defined) when input value fails to match field_value.
`value` | * | value

Source:
  - helpers/scalable.js, line 23

#### (inner) interpolate()

Function for continuous interpolation of numerical values along a gradient with arbitrarily many break points.

Source:
  - helpers/scalable.js, line 159

#### (inner) numerical_bin(parameters, value) → {*}

Function to sort numerical values into bins based on numerical break points. Will only operate on numbers and return null (or value of null_value parameter, if defined) if provided a non-numeric input value. Parameters:

##### Parameters:

Name | Type | Description
--- | --- | ---
`parameters` | Object | ###### Properties
Name | Type | Description
--- | --- | ---
`breaks` | Array.<Number> | Array of numerical break points against which to evaluate the input value. Must be of equal length to values parameter. If the input value is greater than or equal to break n and less than or equal to break n+1 (or break n+1 doesn't exist) then returned value is the nth entry in the values parameter.
`values` | Array | Array of values to return given evaluations against break points. Must be of equal length to breaks parameter. Each entry n represents the value to return if the input value is greater than or equal to break n and less than or equal to break n+1 (or break n+1 doesn't exist).
`null_value` | * |
`value` | * | value

Source:
  - helpers/scalable.js, line 35

##### Returns:

Type
  *

#### (inner) ordinal_cycle(parameters) → {*}

Cycle through a set of options, so that the each element in a set of data receives a value different than the element before it. For example: "use this palette of 10 colors to visually distinguish 100 adjacent items" This is useful when ADJACENT items must be guaranteed to yield a different result, but it leads to unstable color choices if the user pans to a region with a different number/order of items. (the same item is assigned a different color)

See also: stable_choice.

##### Parameters:

Name | Type | Description
--- | --- | ---
`parameters` | Object | ###### Properties
Name | Type | Description
--- | --- | ---
`values` | Array | A list of option values

Source:
  - helpers/scalable.js, line 87

##### Returns:

Type
  *

#### (inner) stable_choice(parameters, value, index)

A scale function that auto-chooses something (like color) from a preset scheme, and makes the same choice every time given the same value, regardless of ordering or what other data is in the region

This is useful when categories must be stable (same color, every time). But sometimes it will assign adjacent values the same color due to hash collisions.

For performance reasons, this is memoized once per instance. Eg, each scalable color parameter has its own cache. This function is therefore slightly less amenable to layout mutations like "changing the options after scaling function is used", but this is not expected to be a common use case.

CAVEAT: Some datasets do not return true datum ids, but instead append synthetic ID fields ("item 1, item2"...) just to appease D3. This hash function only works if there is a meaningful, stable identifier in the data, like a category or gene name.

##### Parameters:

Name | Type | Description
--- | --- | ---
`parameters` |  | ###### Properties
Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`values` | Array | <optional> |  | A list of options to choose from
`max_cache_size` | Number | <optional> | 500 | The maximum number of values to cache. This option is mostly used for unit testing, because stable choice is intended for datasets with a relatively limited number of discrete categories.
`value` |  |
`index` |  |

Source:
  - helpers/scalable.js, line 104

#### (inner) to_rgb(parameters, value)

(extension) Convert a value ""rr,gg,bb" (if given) to a css-friendly color string: "rgb(rr,gg,bb)". This is tailored specifically to the color specification format embraced by the BED file standard.

##### Parameters:

Name | Type | Description
--- | --- | ---
`parameters` | Object | This function has no defined configuration options
`value` | String | null | The value to convert to rgb

Source:
  - ext/lz-intervals-track.js, line 132
See:
  - module:ext/lz-intervals-track for required extension and installation instructions