d3fc-extent

Extends the D3 extent functionality (found in d3-array) to allow padding, multiple accessors and date support

Main D3FC package

Installing

npm install @d3fc/d3fc-extent

API Reference

• Linear
• Time
• Date

Linear

Calculates the extent of an array of data which can be used to set the range on a scale. Can also optionally pad the data in various ways as described below. Internally makes use of d3-array's min and max methods.

import { extentLinear } from 'd3fc-extent';

const data = [{ x: 1 }, { x: 2 }, { x: 4 }, { x: 8 }, { x: 16 }];

const extent = extentLinear()
  .accessors([d => d.x])
  .pad([1, 4])
  .padUnit('domain');

extent(data);

// [0, 20]

fc.extentLinear()

Constructs a new linear extent calculator.

linear.accessors([accessors])

If accessors is specified, sets the array of value accessors to the specified array and returns this extent instance. The accessors are applied to each data value before computing the extent. The value returned by the accessors must be a scalar value or an array of scalar values. Defaults to an identity function (i.e. d => d). If accessors is not specified, returns the current array of value accessors, which defaults [].

linear.pad([values])

If values is specified, sets the amount of padding applied to the minimum and maximum values of the extent, to the specified array [minPad, maxPad] and returns this extent instance. The unit of these values is set by padUnit. If values is not specified, returns the current array of padding values, which defaults [0, 0].

linear.padUnit([value])

If value is specified, sets the unit of the pad values applied to minimum and maximum values and returns this extent instance. Possible values are -

• 'percent' - the default behavior of applying the values as a percentage of the extent e.g. pad values of [0.5, 0.5] would double the calculated extent.
• 'domain' - the padding values specified are applied directly to the calculated extent. If value is not specified, returns the current array of padding unit, which defaults percent.

linear.symmetricalAbout([value])

If value is specified, sets the value around which the extent will be centered around and returns this extent instance. Can also be set to null to disable centering. Note this is applied before padding. If value is not specified, returns the current center value, which defaults null.

linear.include([values])

If values is specified, sets the array of additional values to include within the calculated extent to the specified array and returns this extent instance. This allows for always including an origin (e.g. [0]) or specifying a minimum extent to always be displayed (e.g. [10, 20]). Note included values are applied before symmetricalAbout. If values is not specified, returns the current array of included values, which defaults [].

Time

Calculates the extent of an array of data which can be used to set the range on a scale. Can also optionally pad the data in various ways as described below. Equivalent in functionality to linear but for Date values.

import extentTime from 'd3fc-extent';

const data = [{ x: new Date(2016, 0, 1) }, { x: new Date(2016, 0, 11) }];

const extent = extentTime()
  .accessors([d => d.x])
  .pad([0, 0.2]);

extent(data);

// [ 2016-01-01T00:00:00.000Z, 2016-01-13T00:00:00.000Z ]

fc.extentTime()

Constructs a new time extent calculator.

time.accessors([accessors])

If accessors is specified, sets the array of value accessors to the specified array and returns this extent instance. The accessors are applied to each data value before computing the extent. The value returned be the accessors must be a Date or an array of Dates. Defaults to an identity function (i.e. d => d). If accessors is not specified, returns the current array of value accessors, which defaults [].

time.pad([values])

If values is specified, sets the amount of padding applied to the minimum and maximum values of the extent, to the specified array [minPad, maxPad] and returns this extent instance. The unit of these values is set by padUnit. If values is not specified, returns the current array of padding values, which defaults [0, 0].

time.padUnit([value])

If value is specified, sets the unit of the pad values applied to minimum and maximum values and returns this extent instance. Possible values are -

• 'percent' - the default behavior of applying the values as a percentage of the extent e.g. pad values of [0.5, 0.5] would double the calculated extent.
• 'domain' - the padding values specified in milliseconds are applied directly to the calculated extent. If value is not specified, returns the current array of padding unit, which defaults percent.

time.symmetricalAbout([value])

If value is specified, sets the value around which the extent will be centered around and returns this extent instance. Can also be set to null to disable centering. Note this is applied before padding. If value is not specified, returns the current center value, which defaults null.

time.include([values])

If values is specified, sets the array of additional values to include within the calculated extent to the specified array and returns this extent instance. If values is not specified, returns the current array of included values, which defaults [].

Date

Deprecated - use time instead.