Scales

@ripl/core

Data-to-visual mapping functions: continuous, band, logarithmic, and more.

Overview

Interfaces: ScaleBindingOptions · LinearScaleOptions · BandScale · DivergingScaleOptions · LogarithmicScaleOptions · PowerScaleOptions · Scale

Type Aliases: BandScaleOptions · ScaleMethod

Functions: padDomain · createScale · getLinearScaleMethod · createNumericIncludesMethod · getLinearTicks · scaleBand · scaleContinuous · scaleDiscrete · scaleDiverging · scaleLogarithmic · scaleLog · scalePower · scaleQuantile · scaleQuantize · scaleThreshold · scaleTime

Constants: scaleSqrt

ScaleBindingOptions interface

Low-level options for constructing a scale, providing conversion, inversion, inclusion, and tick generation callbacks.

interface ScaleBindingOptions<TDomain, TRange> {
    readonly domain: TDomain[];
    readonly range: TRange[];
    convert: ScaleMethod<TDomain, TRange>;
    invert: ScaleMethod<TRange, TDomain>;
    includes?(value: TDomain): boolean;
    ticks?(count?: number): TDomain[];
}

Properties:

Property	Type	Description
domain	TDomain[]
range	TRange[]
convert	ScaleMethod<TDomain, TRange>
invert	ScaleMethod<TRange, TDomain>
includes?	((value: TDomain) => boolean) | undefined
ticks?	((count?: number) => TDomain[]) | undefined

---

LinearScaleOptions interface

Options shared by linear-based scales (continuous, logarithmic, power, etc.).

interface LinearScaleOptions {
    clamp?: boolean;
    padToTicks?: boolean | number;
}

Properties:

Property	Type	Description
clamp?	boolean | undefined
padToTicks?	number | boolean | undefined

---

BandScale interface

A band scale that divides a continuous range into uniform bands for categorical data, exposing bandwidth and step.

interface BandScale<TDomain = string> extends Scale<TDomain, number> {
    bandwidth: number;
    step: number;
}

Properties:

Property	Type	Description
bandwidth	number
step	number
domain	TDomain[]
range	number[]
inverse	ScaleMethod<number, TDomain>
ticks	(count?: number) => TDomain[]
includes	(value: TDomain) => boolean

---

DivergingScaleOptions interface

Options for a diverging scale, adding a midpoint to the base linear scale options.

interface DivergingScaleOptions extends LinearScaleOptions {
    midpoint?: number;
}

Properties:

Property	Type	Description
midpoint?	number | undefined
clamp?	boolean | undefined
padToTicks?	number | boolean | undefined

---

LogarithmicScaleOptions interface

Options for a logarithmic scale, adding a configurable base to the base linear scale options.

interface LogarithmicScaleOptions extends LinearScaleOptions {
    base?: number;
}

Properties:

Property	Type	Description
base?	number | undefined
clamp?	boolean | undefined
padToTicks?	number | boolean | undefined

---

PowerScaleOptions interface

Options for a power scale, adding a configurable exponent to the base linear scale options.

interface PowerScaleOptions extends LinearScaleOptions {
    exponent?: number;
}

Properties:

Property	Type	Description
exponent?	number | undefined
clamp?	boolean | undefined
padToTicks?	number | boolean | undefined

---

Scale interface

A callable scale with domain, range, inverse mapping, tick generation, and inclusion testing.

interface Scale<TDomain = number, TRange = number> {
    (value: TDomain): TRange;
    domain: TDomain[];
    range: TRange[];
    inverse: ScaleMethod<TRange, TDomain>;
    ticks(count?: number): TDomain[];
    includes(value: TDomain): boolean;
}

Properties:

Property	Type	Description
domain	TDomain[]
range	TRange[]
inverse	ScaleMethod<TRange, TDomain>
ticks	(count?: number) => TDomain[]
includes	(value: TDomain) => boolean

---

BandScaleOptions type

type BandScaleOptions = {
    innerPadding?: number;
    outerPadding?: number;
    alignment?: number;
    round?: boolean;
};

---

ScaleMethod type

A function that maps a value from one space to another.

type ScaleMethod<TInput = number, TOutput = number> = (value: TInput) => TOutput;

---

padDomain function

Expands a numeric domain to "nice" tick-aligned boundaries and returns [min, max, step].

function padDomain(domain: number[], count: number = 10)

Parameters:

Name	Type	Description
domain	number[]
count	number

Returns: number[]

---

createScale function

Assembles a Scale object from explicit conversion, inversion, and tick functions.

function createScale<TDomain = number, TRange = number>(options: ScaleBindingOptions<TDomain, TRange>): Scale<TDomain, TRange>

Parameters:

Name	Type	Description
options	ScaleBindingOptions<TDomain, TRange>

Returns: Scale<TDomain, TRange>

---

getLinearScaleMethod function

Creates a linear mapping function from a numeric domain to a numeric range, with optional clamping and tick-padding.

function getLinearScaleMethod(domain: number[], range: number[], options?: LinearScaleOptions): ScaleMethod

Parameters:

Name	Type	Description
domain	number[]
range	number[]
options	LinearScaleOptions | undefined

Returns: ScaleMethod

---

createNumericIncludesMethod function

Creates an includes predicate that tests whether a value falls within the numeric domain.

function createNumericIncludesMethod(domain: number[])

Parameters:

Name	Type	Description
domain	number[]

Returns: (value: number) => boolean

---

getLinearTicks function

Generates an array of evenly spaced, "nice" tick values across the domain.

function getLinearTicks(domain: number[], count: number = 10)

Parameters:

Name	Type	Description
domain	number[]
count	number

Returns: number[]

---

scaleBand function

Creates a band scale that maps discrete domain values to evenly spaced bands within the range.

function scaleBand<TDomain = string>(
    domain: TDomain[],
    range: number[],
    options?: BandScaleOptions
): BandScale<TDomain>

Parameters:

Name	Type	Description
domain	TDomain[]
range	number[]
options	BandScaleOptions | undefined

Returns: BandScale<TDomain>

---

scaleContinuous function

Creates a continuous linear scale that maps a numeric domain to a numeric range.

function scaleContinuous(
    domain: number[],
    range: number[],
    options?: LinearScaleOptions
): Scale<number>

Parameters:

Name	Type	Description
domain	number[]
range	number[]
options	LinearScaleOptions | undefined

Returns: Scale<number, number>

---

scaleDiscrete function

Creates a discrete (ordinal) scale that maps domain values to corresponding range values by index.

function scaleDiscrete<TDomain>(
    domain: TDomain[],
    range: number[]
): Scale<TDomain>

Parameters:

Name	Type	Description
domain	TDomain[]
range	number[]

Returns: Scale<TDomain, number>

---

scaleDiverging function

Creates a diverging scale that maps values below and above a midpoint to separate sub-ranges.

function scaleDiverging(
    domain: number[],
    range: number[],
    options?: DivergingScaleOptions
): Scale<number>

Parameters:

Name	Type	Description
domain	number[]
range	number[]
options	DivergingScaleOptions | undefined

Returns: Scale<number, number>

---

scaleLogarithmic function

Creates a logarithmic scale that maps a numeric domain to a range using a log transformation.

function scaleLogarithmic(
    domain: number[],
    range: number[],
    options?: LogarithmicScaleOptions
): Scale<number>

Parameters:

Name	Type	Description
domain	number[]
range	number[]
options	LogarithmicScaleOptions | undefined

Returns: Scale<number, number>

---

scaleLog function

function scaleLog(
    domain: number[],
    range: number[],
    options?: LinearScaleOptions
): Scale<number>

Parameters:

Name	Type	Description
domain	number[]
range	number[]
options	LinearScaleOptions | undefined

Returns: Scale<number, number>

---

scalePower function

Creates a power scale that maps a numeric domain to a range using an exponential transformation.

function scalePower(
    domain: number[],
    range: number[],
    options?: PowerScaleOptions
): Scale<number>

Parameters:

Name	Type	Description
domain	number[]
range	number[]
options	PowerScaleOptions | undefined

Returns: Scale<number, number>

---

scaleQuantile function

Creates a quantile scale that divides a sorted numeric domain into quantiles mapped to discrete range values.

function scaleQuantile<TRange>(
    domain: number[],
    range: TRange[]
): Scale<number, TRange>

Parameters:

Name	Type	Description
domain	number[]
range	TRange[]

Returns: Scale<number, TRange>

---

scaleQuantize function

Creates a quantize scale that divides a continuous numeric domain into uniform segments mapped to discrete range values.

function scaleQuantize<TRange>(
    domain: number[],
    range: TRange[]
): Scale<number, TRange>

Parameters:

Name	Type	Description
domain	number[]
range	TRange[]

Returns: Scale<number, TRange>

---

scaleThreshold function

Creates a threshold scale that maps numeric values to range values based on a set of threshold breakpoints.

function scaleThreshold<TRange>(
    domain: number[],
    range: TRange[]
): Scale<number, TRange>

Parameters:

Name	Type	Description
domain	number[]
range	TRange[]

Returns: Scale<number, TRange>

---

scaleTime function

Creates a time scale that maps a Date domain to a numeric range using linear interpolation of timestamps.

function scaleTime(
    domain: Date[],
    range: number[],
    options?: LinearScaleOptions
): Scale<Date, number>

Parameters:

Name	Type	Description
domain	Date[]
range	number[]
options	LinearScaleOptions | undefined

Returns: Scale<Date, number>

---

scaleSqrt const

Shortcut for a power scale with exponent 0.5 (square root).

const scaleSqrt: (domain: number[], range: number[], options?: LinearScaleOptions) => Scale<number>

---