Порядковые шкалы

Справочник API ▸ Шкалы ▸ Порядковые шкалы

Шкалы — это функции, отображающие входную область значений на выходной диапазон. Порядковые шкалы имеют дискретную область значений, например, набор имён или категорий. Также существуют количественные шкалы, у которых непрерывная область значений, например, множество вещественных чисел. Шкалы являются необязательной функцией в D3; вы можете обойтись и без них, если предпочитаете самостоятельно выполнять вычисления. Однако использование шкал может значительно упростить код, необходимый для отображения измерения данных в визуальном представлении.

Объект шкалы, например, тот, что возвращается d3.scale.ordinal, является одновременно объектом и функцией. То есть: вы можете вызвать шкалу как любую другую функцию, а также у шкалы есть дополнительные методы, изменяющие её поведение. Как и другие классы в D3, шкалы следуют методу цепочки вызовов, где методы-установщики возвращают саму шкалу, что позволяет вызывать несколько установок в одном кратком операторе.

d3.scale.ordinal()

Создаёт новую порядковую шкалу с пустой областью значений и пустым диапазоном. Порядковая шкала недействительна (всегда возвращает undefined) до тех пор, пока не будет указан выходной диапазон.

ordinal(x)

Принимая значение x из входной области значений, возвращает соответствующее значение в выходном диапазоне.

Если диапазон был задан явно (например, с помощью range, но не rangeBands, rangeRoundBands или rangePoints), и заданное значение x не входит в область значений шкалы, то x неявно добавляется в область значений; последующие вызовы шкалы с тем же значением x вернут то же значение y из диапазона.

ordinal.domain([values])

Если values задано, устанавливает входную область значений порядковой шкалы в указанный массив значений. Первый элемент в values будет сопоставлен с первым элементом в выходном диапазоне, второе значение области значений — со вторым значением диапазона и так далее. Значения области значений хранятся во внутренней ассоциативной таблице как сопоставление значения с индексом; полученный индекс затем используется для получения значения из выходного диапазона. Таким образом, значения порядковой шкалы должны быть преобразуемы в строку, а строковое представление значения области значений однозначно идентифицирует соответствующее значение диапазона. Если values не указано, этот метод возвращает текущую область значений.

Установка области значений для порядковой шкалы необязательна. Если область значений не задана, необходимо явно указать диапазон. В этом случае каждое уникальное значение, передаваемое функции шкалы, будет назначено новое значение из выходного диапазона; другими словами, область значений будет неявно определена из использования. Хотя области значений могут быть построены неявно, всё же рекомендуется явно задать область значений порядковой шкалы, чтобы обеспечить детерминированное поведение, так как определение области значений из использования будет зависеть от порядка.

ordinal.range([values])

Если values задано, устанавливает выходной диапазон порядковой шкалы в указанный массив значений. Первый элемент области значений будет сопоставлен с первым элементом в values, второе значение области значений со вторым значением диапазона и так далее. Если в диапазоне элементов меньше, чем в области значений, шкала будет переиспользовать значения с начала диапазона. Если values не указано, этот метод возвращает текущий выходной диапазон.

Этот метод предназначен для случаев, когда набор дискретных выходных значений вычисляется явно, например, набор категориальных цветов. В других случаях, таких как определение макета порядковой диаграммы рассеяния или столбчатой диаграммы, операторы rangePoints или rangeBands могут оказаться более удобными.

ordinal.rangePoints(interval[, padding])

Устанавливает выходной диапазон из указанного непрерывного interval. Массив interval содержит два элемента, представляющие минимальное и максимальное числовое значение. Этот интервал делится на n равномерно распределённых точек, где n — количество (уникальных) значений в входной области значений. Первая и последняя точка могут быть смещены относительно края интервала в соответствии с заданным padding, который по умолчанию равен нулю. Padding выражается как кратное расстоянию между точками. Разумное значение — 1.0, так что первая и последняя точка будут смещены от минимального и максимального значения на половину расстояния между точками.

var o = d3.scale.ordinal()
    .domain([1, 2, 3, 4])
    .rangePoints([0, 100]);

o.range(); // [0, 33.333333333333336, 66.66666666666667, 100]

ordinal.rangeRoundPoints(interval[, padding])

Подобно rangePoints, за исключением того, что гарантирует, что значения диапазона являются целыми числами, чтобы избежать артефактов размытия.

var o = d3.scale.ordinal()
    .domain([1, 2, 3, 4])
    .rangeRoundPoints([0, 100]);

o.range(); // [1, 34, 67, 100]

Обратите внимание, что округление неизбежно приводит к дополнительному внешнему отступу, который в среднем пропорционален длине области значений. Например, для области значений размером 50 может потребоваться дополнительный отступ 25px с каждой стороны. Изменение диапазона до значения, близкого к кратному длине области значений, может уменьшить дополнительный отступ.

var o = d3.scale.ordinal()
    .domain(d3.range(50))
    .rangeRoundPoints([0, 95]);

o.range(); // [23, 24, 25, …, 70, 71, 72]
o.rangeRoundPoints([0, 100]);
o.range(); // [1, 3, 5, …, 95, 97, 98]

(В качестве альтернативы вы можете вручную округлить выход шкалы или применить рендеринг форм: crispEdges. Однако это приведёт к неравномерно расположенным точкам.)

ordinal.rangeBands(interval[, padding[, outerPadding]])

Устанавливает выходной диапазон из указанного непрерывного interval. Массив interval содержит два элемента, представляющие минимальное и максимальное числовое значение. Этот интервал делится на n равномерно распределённых полос, где n — количество (уникальных) значений в области значений. Полосы могут смещаться от края интервала и других полос в соответствии с заданным padding, который по умолчанию равен нулю. Padding обычно находится в диапазоне [0,1] и соответствует количеству места в интервале диапазона, выделяемому для отступа. Значение 0,5 означает, что ширина полосы будет равна ширине отступа. Аргумент outerPadding предназначен для всей группы полос; значение 0 означает, что будет отступ только между полосами.

var o = d3.scale.ordinal()
    .domain([1, 2, 3])
    .rangeBands([0, 100]);

o.rangeBand(); // 33.333333333333336
o.range(); // [0, 33.333333333333336, 66.66666666666667]
o.rangeExtent(); // [0, 100]

ordinal.rangeRoundBands(interval[, padding[, outerPadding]])

Подобно rangeBands, за исключением того, что гарантирует, что значения диапазона и ширина полосы являются целыми числами, чтобы избежать артефактов размытия.

var o = d3.scale.ordinal()
    .domain([1, 2, 3])
    .rangeRoundBands([0, 100]);

o.range(); // [1, 34, 67]
o.rangeBand(); // 33
o.rangeExtent(); // [0, 100]

Обратите внимание, что округление неизбежно приводит к дополнительному внешнему отступу, который в среднем пропорционален длине области значений. Например, для области значений размером 50 может потребоваться дополнительный отступ 25px с каждой стороны. Изменение диапазона до значения, близкого к кратному длине области значений, может уменьшить дополнительный отступ.

var o = d3.scale.ordinal()
    .domain(d3.range(50))
    .rangeRoundBands([0, 95]);

o.range(); // [23, 24, 25, …, 70, 71, 72]

o.rangeRoundBands([0, 100]);
o.range(); // [0, 2, 4, …, 94, 96, 98]

(В качестве альтернативы вы можете вручную округлить выход шкалы или применить рендеринг форм: crispEdges. Однако это приведёт к неравномерно расположенным и размещённым полосам.)

ordinal.rangeBand()

Возвращает ширину полосы. Когда диапазон шкалы настроен с помощью rangeBands или rangeRoundBands, шкала возвращает нижнее значение для данного ввода. Верхнее значение можно затем вычислить, сместив его на ширину полосы. Если диапазон шкалы настроен с помощью range или rangePoints, ширина полосы равна нулю.

ordinal.rangeExtent()

Возвращает массив из двух элементов, представляющий диапазон шкалы, т.е. наименьшее и наибольшее значения.

ordinal.copy()

Возвращает точную копию этой порядковой шкалы. Изменения в этой шкале не повлияют на возвращённую шкалу, и наоборот.

Цветовая палитра категорий

d3.scale.category10()

Создаёт новую порядковую шкалу с диапазоном из десяти категориальных цветов:

#1f77b4
#ff7f0e
#2ca02c
#d62728
#9467bd
#8c564b
#e377c2
#7f7f7f
#bcbd22
#17becf

d3.scale.category20()

Создаёт новую порядковую шкалу с диапазоном из двадцати категориальных цветов:

#1f77b4
#aec7e8
#ff7f0e
#ffbb78
#2ca02c
#98df8a
#d62728
#ff9896
#9467bd
#c5b0d5
#8c564b
#c49c94
#e377c2
#f7b6d2
#7f7f7f
#c7c7c7
#bcbd22
#dbdb8d
#17becf
#9edae5

d3.scale.category20b()

Создаёт новую порядковую шкалу с набором из двадцати категориальных цветов:

#393b79
#5254a3
#6b6ecf
#9c9ede
#637939
#8ca252
#b5cf6b
#cedb9c
#8c6d31
#bd9e39
#e7ba52
#e7cb94
#843c39
#ad494a
#d6616b
#e7969c
#7b4173
#a55194
#ce6dbd
#de9ed6

d3.scale.category20c()

Создаёт новую порядковую шкалу с набором из двадцати категориальных цветов:

#3182bd
#6baed6
#9ecae1
#c6dbef
#e6550d
#fd8d3c
#fdae6b
#fdd0a2
#31a354
#74c476
#a1d99b
#c7e9c0
#756bb1
#9e9ac8
#bcbddc
#dadaeb
#636363
#969696
#bdbdbd
#d9d9d9

ColorBrewer

Библиотека D3 также включает в себя замечательные категориальные цветовые шкалы, разработанные Синтией Брюэр. Вы можете найти их в формате CSS или JavaScript в lib/colorbrewer. Для CSS, назначьте класс, например, "q0-3", "q1-3" или "q2-3" элементу, который вы хотите заполнить. Затем установите атрибут класса на родительском элементе (например, элементе SVG) с именем нужной цветовой шкалы, например, "RdBu" или "Blues". Примеры смотрите: диаграмма тепловой карты календаря, картограмма.

Для JavaScript вы можете использовать colorbrewer.RdBu[9] или эквивалент в качестве диапазона d3.scale.ordinal. Например:

var o = d3.scale.ordinal()
    .domain(["foo", "bar", "baz"])
    .range(colorbrewer.RdBu[9]);