Array¶

detroit.extent(values: Iterable[T], accessor: Callable[[T], T] | Callable[[T, int], T] | Callable[[T, int, list[Element]], T] | None = None) → list[T | None]¶

Returns the minimum and maximum value in the given iterable using natural order.

Parameters:

values (Iterable[T]) – Iterator
accessor (Accessor[T, T] | None) – Accessor function

Returns:

Minimum, maximum

Return type:

list[T | None]

Examples

>>> a = [1, 4, -2, 8]
>>> d3.extent(a)
[-2, 8]
>>> b = [{"a": 8}, {"a": 1}, {"a": 16}]
>>> d3.extent(b, lambda x: x["a"])
[1, 16]

Notes

The accessor function can take one, two or three arguments where:

the first argument (type T) is the value over iteration
the second argument (type int) is its index
the last argument (type list[T]) is the input values without any modification

detroit.nice(start: T, stop: T, count: int) → tuple[T, T]¶

Returns a new interval [nice_start, nice_stop] covering the given interval [start, stop] and where nice_start and nice_stop are guaranteed to align with the corresponding tick_step.

Parameters:

start (T) – Start value
stop (T) – End value
count (int) – Count value

Returns:

Aligned interval

Return type:

tuple[T, T]

Examples

>>> d3.nice(10.2, 20.8, 10)
[10, 21]
>>> d3.nice(10.2, 20.8, 1)
[0, 50]

Set operations¶

detroit.difference(iterable: Iterable[Hashable], *others: Iterable[Hashable]) → set[Hashable]¶

Returns a new set containing every value of iterable that is not in any of the other iterables.

Parameters:

iterable (Iterable[Hashable]) – Iterable to differenciate
others (Iterable[Hashable]) – Other iterables

Returns:

Set of the iterable differenciated with other iterables

Return type:

set[Hashable]

Examples

>>> d3.difference([1, 2, 3], [2, 5], [3])
{1}

detroit.union(*iterables: Iterable[Hashable]) → set[Hashable]¶

Returns a new set containing every distinct value that appears in any of the givven iterables.

Parameters:: iterables (Iterable[Hashable]) – Iterables
Returns:: Set of all united values from iterables
Return type:: set[Hashable]

Examples

>>> d3.union([1, 2], [3, 4], [5])
{1, 2, 3, 4, 5}

detroit.intersection(*iterables: Iterable[Hashable]) → set[Hashable]¶

Returns a new set containing every distinct value that appears in all of the given iterables.

Parameters:: iterables (Iterable[Hashable]) – Iterables
Returns:: Set of all intersected iterables
Return type:: set[Hashable]

Examples

>>> d3.intersection([1, 2, 3], [3, 4], [2, 3])
{3}

detroit.superset(a: Iterable[Hashable], b: Iterable[Hashable]) → bool¶

Returns True if every value in the given iterable b is also in the given iterable a.

Parameters:

a (Iterable[Hashable]) – Iterable a
b (Iterable[Hashable]) – Iterable b

Returns:

True if a is a superset of b

Return type:

bool

Examples

>>> d3.superset([1, 2, 3], [1, 2])
True
>>> d3.superset([1, 2, 3], [4, 2])
False

detroit.subset(a: Iterable[Hashable], b: Iterable[Hashable]) → bool¶

Returns True if every value in the given iterable a is also in the given iterable b.

Parameters:

a (Iterable[Hashable]) – Iterable a
b (Iterable[Hashable]) – Iterable b

Returns:

True if a is a subset of b

Return type:

bool

Examples

>>> d3.subset([1, 2], [1, 2, 3])
True
>>> d3.subset([4, 2], [1, 2, 3])
False

detroit.disjoint(a: Iterable[Hashable], b: Iterable[Hashable]) → bool¶

Returns True if a and b contain no shared value

Parameters:

a (Iterable[Hashable]) – Iterable a
b (Iterable[Hashable]) – Iterable b

Returns:

True if a and b are disjoint

Return type:

bool

Examples

>>> d3.disjoint([1, 3], [2, 4])
True
>>> d3.disjoint([1, 3], [3, 4])
False

Blur functions¶

detroit.blur(values: list[float], r: float) → list[float]¶

Blurs an array of data in-place by applying three iterations of a moving average transform (box filter) for a fast approximation of a Gaussian kernel of the given radius, a non-negative number. Returns the given data.

Parameters:

values (list[float]) – Data
r (float) – Radius

Returns:

Blurred data

Return type:

list[float]

Examples

>>> d3.blur([0, 0, 1, 0, 0], 1)
[0.14814814814814814, 0.2222222222222222, 0.25925925925925924, 0.22222222222222224, 0.1481481481481482]

detroit.blur2(data: dict, rx: float, ry: float | None = None)¶

Blurs a matrix of the given width and height in-place by applying a horizontal blur of radius rx and a vertical blur of radius ry (which defaults to rx). The matrix values data are stored in a flat (one-dimensional) array.

Parameters:

data (dict) – Dictionary with three keys: "data", "width" and "height". If "height" is not specified, it is inferred from the given width and length of data.
rx (float) – Radius x
ry (float | None) – Radius y

Returns:

Returns the blurred matrix

Return type:

dict

Examples

>>> data = [
... 0, 0, 0, 0, 0,
... 0, 0, 1, 0, 0,
... 0, 1, 1, 1, 0,
... 0, 0, 1, 0, 0,
... 0, 0, 0, 0, 0,
... ]
>>> d3.blur2({"data": data, "width": 5, "height": 5}, 1)
{'data': [0.1316872427983539, 0.1755829903978052, 0.20027434842249658, 0.17558299039780523, 0.13168724279835398, 0.1755829903978052, 0.23045267489711932, 0.262002743484225, 0.23045267489711938, 0.1755829903978053, 0.20027434842249656, 0.262002743484225, 0.29766803840877915, 0.262002743484225, 0.20027434842249667, 0.1755829903978052, 0.23045267489711932, 0.262002743484225, 0.23045267489711938, 0.1755829903978053, 0.1316872427983539, 0.1755829903978052, 0.20027434842249656, 0.17558299039780523, 0.13168724279835398], 'width': 5, 'height': 5}

detroit.blur_image(data: dict, rx: float, ry: float | None = None)¶

Blurs the given image in-place, blurring each of the RGBA layers independently by applying an horizontal blur of radius rx and a vertical blur of radius ry (which defaults to rx).

Parameters:

data (dict) – Dictionary with three keys: "data", "width" and "height". If "height" is not specified, it is inferred from the given width and length of data.
rx (float) – Radius x
ry (float | None) – Radius y

Returns:

Returns the blurred image

Return type:

dict

Tick functions¶

Returns the negative inverse tick step instead.

Parameters:

start (int | float | str) – Start value which can be converted as float
stop (int | float | str) – Stop value which can be converted as float
count (int | float) – Count value

Returns:

Increment value

Return type:

int

Examples

>>> d3.tick_increment(0, 1, 10)
-10.0
>>> d3.tick_increment(0, 1, 1)
1
>>> d3.tick_increment(0, 1, 100)
-100.0
>>> d3.tick_increment(0, 20, 10)
2

Returns the difference between adjacent tick value.

Parameters:

start (int | float | str) – Start value which can be converted as float
stop (int | float | str) – Stop value which can be converted as float
count (int | float) – Count value

Returns:

Increment value

Return type:

int

Examples

>>> d3.tick_step(0, 10, 1)
10
>>> d3.tick_step(0, 1, 10)
0.1

Returns an array of approximately count + 1 uniformly-spaced, nicely-rounded values between start and stop (inclusive).

Parameters:

start (int | float | str) – Start value which can be converted as float
stop (int | float | str) – Stop value which can be converted as float
count (int | float) – Count value

Returns:

Array of nicely-rounded values

Return type:

list[float]

Examples

>>> d3.ticks(0, 1, 10)
[0.0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0]
>>> d3.ticks("1.2", "2", 10)
[1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9, 2.0]

Group functions¶

detroit.group(values: list[T], *keys: Callable[[T], K] | Callable[[T, int], K] | Callable[[T, int, list[T]], K]) → dict[K, list[T]]¶

Groups the specified list of values into a nested dictionary given keys.

Parameters:

values (list[U]) – List of values
*keys (Callable[[T], K] | Callable[[T, Index], K] | Callable[[T, Index, list[T]], K]) – List of functions which take in arguments data, index and list of data and returns the key value of the data.

Returns:

Nested dictionary

Return type:

dict[K, list[T]]

Examples

>>> data = [
...     {"id": 0, "value": 10},
...     {"id": 0, "value": 20},
...     {"id": 1, "value": 3},
... ]
>>> d3.group(data, lambda d: d["id"])
{0: [{'id': 0, 'value': 10}, {'id': 0, 'value': 20}], 1: [{'id': 1, 'value': 3}]}

detroit.groups(values: list[T], *keys: Callable[[T], K] | Callable[[T, int], K] | Callable[[T, int, list[T]], K]) → list[tuple[K, list[T]]]¶

Equivalent to d3.group, returns a list of collections [key; array of values].

Parameters:

values (list[U]) – List of values
*keys (Callable[[T], K] | Callable[[T, Index], K] | Callable[[T, Index, list[T]], K]) – List of functions which take in arguments data, index and list of data and returns the key value of the data.

Returns:

Nested list of collections [key; array of values].

Return type:

list[tuple[K, list[T]]]

Examples

>>> data = [
...     {"id": 0, "value": 10},
...     {"id": 0, "value": 20},
...     {"id": 1, "value": 3},
... ]
>>> d3.groups(data, lambda d: d["id"])
[(0, [{'id': 0, 'value': 10}, {'id': 0, 'value': 20}]), (1, [{'id': 1, 'value': 3}])]

detroit.index(values: list[T], *keys: Callable[[T], K] | Callable[[T, int], K] | Callable[[T, int, list[T]], K]) → dict[K, T]¶

Groups and reduces the specified list of values into a nested dictionary. The reducer extracts the first element from each group.

Parameters:

values (list[T]) – List of values
keys (Callable[[T], K] | Callable[[T, Index], K] | Callable[[T, Index, list[T]], K]) – List of functions which take in arguments data, index and list of data and returns the key value of the data.

Returns:

Nested dictionary.

Return type:

dict[K, T]

Examples

>>> data = [
...     {"id": 0, "value": 10},
...     {"id": 0, "value": 20},
...     {"id": 1, "value": 3},
... ]
>>> d3.index(data, lambda d: d["value"])
{10: {'id': 0, 'value': 10}, 20: {'id': 0, 'value': 20}, 3: {'id': 1, 'value': 3}}

detroit.indexes(values: list[T], *keys: Callable[[T], K] | Callable[[T, int], K] | Callable[[T, int, list[T]], K]) → list[tuple[K, T]]¶

Equivalent to d3.index, returns a list of collections [key, array of values]. The reducer extracts the first element from each group.

Parameters:

values (list[U]) – List of values
*keys (Callable[[T], K] | Callable[[T, Index], K] | Callable[[T, Index, list[T]], K]) – List of functions which take in arguments data, index and list of data and returns the key value of the data.

Returns:

Nested list of collections [key; array of values].

Return type:

list[tuple[K, T]]

Examples

>>> data = [
...     {"id": 0, "value": 10},
...     {"id": 0, "value": 20},
...     {"id": 1, "value": 3},
... ]
>>> d3.indexes(data, lambda d: d["value"])
[(10, {'id': 0, 'value': 10}), (20, {'id': 0, 'value': 20}), (3, {'id': 1, 'value': 3})]

detroit.rollup(values: list[T], reduce_function: Callable[[list[T]], R], *keys: Callable[[T], K] | Callable[[T, int], K] | Callable[[T, int, list[T]], K]) → dict[K, R]¶

Groups and reduces the specified list of values into a nested dictionary.

Parameters:

values (list[T]) – List of values
reduce_function (Callable[[list[T]], V]) – Reducer function
*keys (Callable[[T, int, list[T]], U]) – List of functions which take in arguments data, index and list of data and returns the key value of the data.

Returns:

Nested dictionary

Return type:

dict[K, R]

Examples

>>> data = [
...     {"id": 0, "value": 10},
...     {"id": 0, "value": 20},
...     {"id": 1, "value": 3},
... ]
>>> d3.rollup(
...     data,
...     lambda values: sum([d["value"] for d in values]),
...     lambda d: d["id"],
... )
{0: 30, 1: 3}

detroit.rollups(values: list[T], reduce_function: Callable[[list[T]], R], *keys: Callable[[T], K] | Callable[[T, int], K] | Callable[[T, int, list[T]], K]) → list[tuple[K, R]]¶

Equivalent to d3.rollup, returns a list of collections [key; array of values].

Parameters:

values (list[T]) – List of values
reduce_function (Callable[[list[T]], V]) – Reducer function
*keys (Callable[[T, int, list[T]], U]) – List of functions which take in arguments data, index and list of data and returns the key value of the data.

Returns:

Nested list of collections [key; array of values].

Return type:

list[tuple[K, R]]

Examples

>>> data = [
...     {"id": 0, "value": 10},
...     {"id": 0, "value": 20},
...     {"id": 1, "value": 3},
... ]
>>> d3.rollups(
...     data,
...     lambda values: sum([d["value"] for d in values]),
...     lambda d: d["id"],
... )
[(0, 30), (1, 3)]

Bin functions¶

detroit.bin()¶: Bin generator with the default settings

class detroit.array.bin.Bin¶: Bin quantitative values into consecutive, non-overlapping intervals, as in histograms

class detroit.array.bin.bin¶

Bin generator with the default settings

__call__(data: Iterable[int | float]) → list[Bin]¶

Returns an array of bins, where each bin is an array containing the associated elements from the input data.

Parameters:: data (Iterable[int | float]) – Data samples
Returns:: Array of bins
Return type:: list[Bin]

Examples

>>> d3.bin()([0, 0, 0, 10, 20, 20])
[Bin([0, 0, 0], x0=0, x1=5), Bin([], x0=5, x1=10), Bin([10], x0=10, x1=15), Bin([], x0=15, x1=20), Bin([20, 20], x0=20, x1=25)]

set_value(value: Callable[[int | float, int, Iterable[int | float]], float] | Any) → bin¶

Sets value

Parameters:: Value (Callable[[int | float, int, Iterable[int | float]], float] | Any) – Value function or constant object
Returns:: Itself
Return type:: bin

set_domain(domain: Callable[[float], float] | tuple[float, float]) → bin¶

Sets domain

Parameters:: obj (Callable[[float], float] | tuple[float, float]) – Domain function or domain tuple
Returns:: Itself
Return type:: bin

set_thresholds(thresholds: Callable[[list[float | None]], float] | Any) → bin¶

Sets thresholds

Parameters:: thresholds (Callable[[list[float | None]], float] | Any) – Object or function
Returns:: Itself
Return type:: bin

Threshold functions¶

detroit.threshold_freedman_diaconis(values: list[float | None], mini: float, maxi: float) → int¶

Returns the number of bins according to the Freedman–Diaconis rule; the input values must be numbers.

Parameters:

values (list[float | None]) – Input values
mini (float) – Minimum value
maxi (float) – Maximum value

Returns:

Number of bins according to the Freedman-Diaconis rule

Return type:

int

detroit.threshold_scott(values: list[float | None], mini: float, maxi: float) → int¶

Returns the number of bins according to Scott’s normal reference rule; the input values must be numbers.

Parameters:

values (list[float | None]) – Input values
mini (float) – Minimum value
maxi (float) – Maximum value

Returns:

Number of bins according to Scott’s normal

Return type:

int

detroit.threshold_sturges(values: list[float | None], *args: Any) → int¶

Returns the number of bins according to Sturges’ formula; the input values must be numbers.

Parameters:

values (list[float | None]) – Input values
*args (Any) – Unused arguments

Returns:

Number of bins according to Sturges’ formula

Return type:

int