Skip to content

Latest commit

 

History

History
150 lines (102 loc) · 5.75 KB

Utilities.stories.mdx

File metadata and controls

150 lines (102 loc) · 5.75 KB
Raw

import { Meta } from '@storybook/react';

Utilities

The library exposes a number of utility functions, which are documented below, as well as all the enums and types used by these utility functions. In most cases, you'll only need getDomain and/or useDomain.

getDomain

Find the min and max values contained in a array (or ndarray) of numbers. If scaleType is ScaleType.Log and the domain crosses zero, clamp the min to the first positive value or return undefined if the domain is not supported (i.e. [-x, 0]).

getDomain(values: NdArray | number[], scaleType: ScaleType = ScaleType.Linear): Domain | undefined

const linearDomain = getDomain([10, 5, -1]); // [-1, 10]
const logDomain = getDomain([-1, 2, 10], ScaleType.Log); // [2, 10]

const myArray = ndarray([0, 1, 2, 3], [2, 2]);
const myDomain = getDomain(myArray); // [0, 3]

getDomains

Find the domains of multiple arrays (or ndarrays) of numbers. Useful when dealing with auxiliary curves.

getDomains(arrays: (NdArray | number[])[], scaleType: ScaleType = ScaleType.Linear): (Domain | undefined)[]

const linearDomains = getDomains([[-1, 5, 10], myArray]); // [[-1, 10], [0, 3]]
const logDomains = getDomains([[-1, 5, 10], myArray], ScaleType.Log); // [[2, 10], [0, 3]]

getCombinedDomain

Combine multiple domains into one. Useful to find the overall domain of a line visualization with auxiliary curves.

getCombinedDomain(domains: (Domain | undefined)[]): Domain | undefined

const combinedDomain = getCombinedDomain([[-1, 10], [0, 30]]]); // [-1, 30]

extendDomain

Extend a domain by a factor in a given scale.

extendDomain(domain: Domain, extendFactor: number, scaleType: ScaleType = ScaleType.Linear): Domain

const extendedDomain1 = extendDomain([0, 100], 0.5]); // [-50, 150]
const extendedDomain2 = extendDomain([10, 100], 1, ScaleType.Log); // approx. [1, 1000]
const extendedDomain3 = extendDomain([2, 2], 0.5); // [1, 3]
const extendedDomain4 = extendDomain([1, 1], 1, ScaleType.Log); // [0.1, 10]

computeCanvasSize

Compute the optimal size for a visualization based on the available size and an aspect ratio. If aspecRatio is not provided, availableSize is returned unchanged.

computeCanvasSize(availableSize: Size, aspectRatio?: number): Size | undefined

const size = computeCanvasSize({ width: 20, height: 10 }, 1.5); // { width: 15, height: 10 }

getLinearGradient

Generate a CSS linear gradient for a given D3 interpolator, to be used as background-image. If minMaxOnly is true, the gradient will include only two colours stops.

getLinearGradient(interpolator: D3Interpolator, direction: 'top' | 'bottom' | 'right' | 'left', minMaxOnly = false): string

getVisDomain

Determine the domain to be used for the visualization based on a user-selected custom domain. If a bound of the custom domain is null, it falls back to the corresponding bound of the data domain.

getVisDomain(customDomain: CustomDomain, dataDomain: Domain): Domain

const visDomain1 = getVisDomain([null, null], [0, 100]); // [0, 100]
const visDomain2 = getVisDomain([null, 20], [0, 100]); // [0, 20]

getSafeDomain

Determine a domain that is safe for the visualization. This is typically called with a user-defined customDomain, or with a visDomain as returned by getVisDomain(). If the domain is determined to be unsafe, a safe domain based on fallbackDomain is returned along with an error object. Note that fallbackDomain is assumed to be safe. The domain is considered unsafe if it's inverted (min > max), or if the scale is log and at least one of the bounds is negative.

getSafeDomain(domain: Domain, fallbackDomain: Domain, scaleType: ScaleType): [Domain, DomainErrors]

const safeDomain1 = getSafeDomain([-10, 50], [1, 100], ScaleType.Linear]); // [0, 50]
const safeDomain2 = getSafeDomain([-10, 50], [1, 100], ScaleType.Log]); // [1, 50]
const safeDomain3 = getSafeDomain([-50, -10], [1, 100], ScaleType.Log]); // [1, 100]
const safeDomain4 = getSafeDomain([-10, 50], [80, 100], ScaleType.Log]); // [50, 50] => log-safe min (80) is greater than max (50)

scaleGamma

A @visx/scale-like power scale that implements gamma correction. With scaleGamma, the normalization happens before raising to the exponent, contrary to scalePower where it happens after. Implements domain, range, rangeRound, exponent, interpolate, clamp, nice, ticks, tickFormat and copy.

const scale = scaleGamma({
    domain: Domain = [0, 1]
    range: Domain = [0, 1],
    exponent: number = 1,
    clamp: boolean = false,
});

Hooks

  • useDomain(...args): Domain | undefined - Memoised version of getDomain.
  • useDomains(...args): (Domain | undefined)[] - Memoised version of getDomains.
  • useCombinedDomain(...args): Domain | undefined - Memoised version of getCombinedDomain.
  • useVisDomain(...args): Domain - Memoised version of getVisDomain.
  • useSafeDomain(...args): [Domain, DomainErrors] - Memoised version of getSafeDomain.

Context hooks

useAxisSystemContext

useAxisSystemContext(): AxisSystemParams

const {
  abscissaConfig,
  ordinateConfig,
  abscissaScale,
  ordinateScale,
  visSize
} = useAxisSystemContext();

Mock data

The library exposes a utility function to retrieve a mock entity's metadata and a mock dataset's value as ndarray for testing purposes. You can browse through the available mock data at https://h5web.panosc.eu/mock.

import { findMockEntity, getMockDataArray } from '@h5web/lib';

const entity = findMockEntity('/nD_datasets/twoD');
const dataArray = getMockDataArray('/nD_datasets/twoD');