d3-scale

Масштабирование — удобное абстрагирование фундаментальной задачи визуализации: отображение измерения абстрактных данных в визуальном представлении. Хотя чаще всего используется для кодирования позиций количественных данных, таких как отображение измерения в метрах в позицию в пикселях точек в диаграмме рассеяния, масштабирование может представлять практически любое визуальное кодирование, например, расходящиеся цвета, ширины линий или размер символов. Масштабирование также может использоваться с практически любым типом данных, такими как именованные категориальные данные или дискретные данные, требующие разумных разрывов.

Для непрерывных количественных данных, как правило, требуется линейный масштаб. (Для временных рядов — временной масштаб.) Если распределение требует этого, рассмотрите преобразование данных с использованием степенного или логарифмического масштаба. Квантование масштаба может помочь в дифференциации, округляя непрерывные данные до фиксированного набора дискретных значений; аналогично, масштаб квантилей вычисляет квантили из выборочной совокупности, а пороговый масштаб позволяет задать произвольные разрывы в непрерывных данных. Также предоставляется несколько встроенных последовательных цветовых схем; см. d3-scale-chromatic для получения дополнительной информации.

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

Масштабирование не имеет собственного визуального представления. Однако большинство масштабов могут генерировать и форматировать деления для меток, чтобы помочь в построении осей.

Для более подробного введения см. эти рекомендуемые учебные пособия:

• Знакомство с d3-scale от Майкла Бостока

• Глава 7. Масштабы из книги Интерактивная визуализация данных для веб Скотта Мюррея

• d3: масштабы и цвет. от Жерома Кукье

Установка

Если вы используете NPM, npm install d3-scale. В противном случае загрузите последнюю версию. Вы также можете загрузить напрямую с d3js.org, как отдельную библиотеку, так и как часть D3 4.0. Поддерживаются среды AMD, CommonJS и vanilla. В vanilla экспортируется глобальная переменная d3:

<script src="https://d3js.org/d3-array.v1.min.js"></script>
<script src="https://d3js.org/d3-collection.v1.min.js"></script>
<script src="https://d3js.org/d3-color.v1.min.js"></script>
<script src="https://d3js.org/d3-format.v1.min.js"></script>
<script src="https://d3js.org/d3-interpolate.v1.min.js"></script>
<script src="https://d3js.org/d3-time.v1.min.js"></script>
<script src="https://d3js.org/d3-time-format.v2.min.js"></script>
<script src="https://d3js.org/d3-scale.v1.min.js"></script>
<script>

var x = d3.scaleLinear();

</script>

(Вы можете опустить d3-time и d3-time-format, если не используете d3.scaleTime или d3.scaleUtc.)

Попробуйте d3-scale в вашем браузере.

Справочник API

• Непрерывные (Линейные, Степенные, Логарифмические, Тождественные, Временные)
• Последовательные
• Квантование
• Квантили
• Пороговые
• Порядковые (Полосы, Точки, Категории)

Непрерывные масштабы

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

continuous(value) Источник

Принимая значение value из диапазона, возвращает соответствующее значение из диапазона. Если данное значение value находится вне диапазона, и ограничение не включено, отображение может быть экстраполировано таким образом, что возвращаемое значение находится вне диапазона. Например, для применения кодирования позиции:

var x = d3.scaleLinear()
    .domain([10, 130])
    .range([0, 960]);

x(20); // 80
x(50); // 320

Или для применения цветового кодирования:

var color = d3.scaleLinear()
    .domain([10, 100])
    .range(["brown", "steelblue"]);

color(20); // "#9a3439"
color(50); // "#7b5167"

continuous.invert(value) Источник

Принимая значение value из диапазона, возвращает соответствующее значение из диапазона. Инвертирование полезно для взаимодействия, например, для определения значения данных, соответствующего позиции указателя мыши. Например, для инвертирования кодирования позиции:

var x = d3.scaleLinear()
    .domain([10, 130])
    .range([0, 960]);

x.invert(80); // 20
x.invert(320); // 50

Если заданное значение value находится вне диапазона, и ограничение не включено, отображение может быть экстраполировано, так что возвращаемое значение будет за пределами диапазона. Этот метод поддерживается только если диапазон числовой. Если диапазон не числовой, возвращает NaN.

Для допустимого значения y в диапазоне, continuous(continuous.invert(y)) приблизительно равно y; аналогично, для допустимого значения x в диапазоне, continuous.invert(continuous(x)) приблизительно равно x. Масштаб и его обратное отображение могут не быть точными из-за ограничений точности с плавающей запятой.

continuous.domain([domain]) Источник

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

Хотя непрерывные масштабы обычно имеют два значения в каждом диапазоне и области, указание более чем двух значений создаёт ступенчатый масштаб. Например, чтобы создать расходящийся цветовой масштаб, который интерполирует между белым и красным для отрицательных значений, и белым и зелёным для положительных значений, скажем:

var color = d3.scaleLinear()
    .domain([-1, 0, 1])
    .range(["red", "white", "green"]);

color(-0.5); // "rgb(255, 128, 128)"
color(+0.5); // "rgb(128, 192, 128)"

Внутренне, ступенчатый масштаб выполняет двоичный поиск интерполятора диапазона, соответствующего заданному значению области. Таким образом, область должна быть в порядке возрастания или убывания. Если у области и диапазона разная длина N и M, учитываются только первые min(N,M) элементов в каждом.

continuous.range([range]) Источник

Если задан range, устанавливает диапазон масштаба на заданный массив значений. Массив должен содержать два или более элементов. В отличие от диапазона, элементы в заданном массиве не обязательно должны быть числами; любое значение, поддерживаемое базовым интерполятором, будет работать, хотя обратите внимание, что числовые диапазоны необходимы для invert. Если range не задан, возвращает копию текущего диапазона масштаба. См. continuous.interpolate для получения дополнительных примеров.

continuous.rangeRound([range]) Источник

Устанавливает range масштаба на указанный массив значений, также устанавливая интерполятор масштаба на interpolateRound. Это удобный метод, эквивалентный:

continuous
    .range(range)
    .interpolate(d3.interpolateRound);

Иногда округление интерполятора полезно для избегания артефактов дробления, хотя также следует учитывать стили shape-rendering «crispEdges». Обратите внимание, что этот интерполятор может использоваться только с числовыми диапазонами.

continuous.clamp(clamp) Источник

Если задан clamp, соответственно включает или выключает ограничение. Если ограничение отключено, и масштабу передано значение, выходящее за пределы диапазона, масштаб может вернуть значение, выходящее за пределы диапазона, путем экстраполяции. Если ограничение включено, возвращаемое значение масштаба всегда находится в диапазоне масштаба. Ограничение аналогично применяется к continuous.invert. Например:

var x = d3.scaleLinear()
    .domain([10, 130])
    .range([0, 960]);

x(-10); // -160, outside range
x.invert(-160); // -10, outside domain

x.clamp(true);
x(-10); // 0, clamped to range
x.invert(-160); // 10, clamped to domain

Если clamp не задан, возвращает, включено или выключено ли ограничение значений масштаба в пределах диапазона.

continuous.interpolate(interpolate) Источник

Если задан interpolate, устанавливает фабрику интерполятора range масштаба. Эта фабрика интерполятора используется для создания интерполяторов для каждой соседней пары значений из диапазона; эти интерполяторы затем отображают нормализованный параметр области t в [0, 1] на соответствующее значение в диапазоне. Если factory не задан, возвращает текущую фабрику интерполятора масштаба, которая по умолчанию равна interpolate. См. d3-interpolate для получения дополнительных интерполяторов.

Например, рассмотрим расходящийся цветовой масштаб с тремя цветами в диапазоне:

var color = d3.scaleLinear()
    .domain([-100, 0, +100])
    .range(["red", "white", "green"]);

Два интерполятора создаются в масштабе, эквивалентные:

var i0 = d3.interpolate("red", "white"),
    i1 = d3.interpolate("white", "green");

Частой причиной указания пользовательского интерполятора является изменение цветового пространства интерполяции. Например, для использования HCL:

var color = d3.scaleLinear()
    .domain([10, 100])
    .range(["brown", "steelblue"])
    .interpolate(d3.interpolateHcl);

Или для Cubehelix с пользовательским гамма-фактором:

var color = d3.scaleLinear()
    .domain([10, 100])
    .range(["brown", "steelblue"])
    .interpolate(d3.interpolateCubehelix.gamma(3));

Примечание: по умолчанию используемый интерполятор может переиспользовать возвращаемые значения. Например, если значения диапазона являются объектами, интерполятор значений всегда возвращает один и тот же объект, изменяя его на месте. Если шкала используется для установки атрибута или стиля, это обычно приемлемо (и желательно для производительности); однако, если вам нужно сохранить возвращаемое значение шкалы, вы должны указать свой собственный интерполятор или сделать копию, как соответствующим образом.

continuous.ticks([count])

Возвращает приблизительно count представительных значений из домена шкалы. Если count не указан, по умолчанию используется 10. Возвращаемые значения делений равномерно распределены, имеют удобочитаемые значения (например, кратные степеням 10) и гарантированно находятся в пределах области домена. Деления часто используются для отображения вспомогательных линий или делений вместе с визуализируемыми данными. Указанное значение count является лишь подсказкой; шкала может вернуть больше или меньше значений в зависимости от домена. См. также ticks из d3-array.

continuous.tickFormat([count[, specifier]]) Source

Возвращает функцию форматирования чисел подходящую для отображения значения деления, автоматически вычисляя соответствующую точность на основе фиксированного интервала между значениями делений. Указанное значение count должно совпадать со значением count, используемым для генерации значений делений.

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

var x = d3.scaleLinear()
    .domain([-1, 1])
    .range([0, 960]);

var ticks = x.ticks(5),
    tickFormat = x.tickFormat(5, "+%");

ticks.map(tickFormat); // ["-100%", "-50%", "+0%", "+50%", "+100%"]

Если specifier использует тип формата s, шкала вернёт формат с префиксом SI на основе наибольшего значения в домене. Если specifier уже определяет точность, этот метод эквивалентен методу locale.format.

continuous.nice([count]) Source

Расширяет домен так, чтобы он начинался и заканчивался на красивых круглых значениях. Этот метод обычно изменяет домен шкалы и может расширить границы до ближайшего круглого значения. Необязательный аргумент count для делений позволяет лучше управлять размером шага, используемого для расширения границ, гарантируя, что возвращаемые деления будут точно покрывать домен. Улучшение подходит, если домен вычисляется по данным, например, с помощью extent, и может быть нерегулярным. Например, для домена [0.201479…, 0.996679…], улучшенным доменом может быть [0.2, 1.0]. Если домен содержит более двух значений, улучшение домена влияет только на первое и последнее значение. См. также tickStep из d3-array.

Улучшение шкалы изменяет только текущий домен; оно не автоматически улучшает домены, которые впоследствии устанавливаются с помощью continuous.domain. Для улучшения домена, установленного с помощью continuous.domain, необходимо вновь выполнить улучшение.

continuous.copy() Source

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

Линейные шкалы

d3.scaleLinear() Source

Создаёт новую непрерывную шкалу с единичным доменом [0, 1], единичным диапазоном [0, 1], по умолчанию интерполятором и отключенной привязкой. Линейные шкалы являются хорошим выбором по умолчанию для непрерывных количественных данных, так как они сохраняют пропорциональные различия. Каждое значение диапазона y может быть выражено как функция значения домена x: y = mx + b.

Шкалы степени

Шкалы степени похожи на линейные шкалы, за исключением того, что к значению входного домена применяется экспоненциальное преобразование перед вычислением выходного значения диапазона. Каждое значение диапазона y можно выразить как функцию значения домена x: y = mx^k + b, где k — значение показателя степени. Шкалы степени также поддерживают отрицательные значения домена, в этом случае входное значение и полученное выходное значение умножаются на -1.

d3.scalePow() Source

Создаёт новую непрерывную шкалу с единичным доменом [0, 1], единичным диапазоном [0, 1], показателем степени 1, по умолчанию интерполятором и отключенной привязкой. (Обратите внимание, что это фактически линейная шкала до тех пор, пока вы не установите другой показатель степени.)

pow(value) Source

См. continuous.

pow.invert(value)

См. continuous.invert.

pow.exponent([exponent]) Source

Если exponent указан, устанавливает текущий показатель степени заданному числовому значению. Если exponent не указан, возвращает текущий показатель степени, который по умолчанию равен 1. (Обратите внимание, что это фактически линейная шкала до тех пор, пока вы не установите другой показатель степени.)

pow.domain([domain])

См. continuous.domain.

pow.range([range])

См. continuous.range.

pow.rangeRound([range])

См. continuous.rangeRound.

pow.clamp(clamp)

См. continuous.clamp.

pow.interpolate(interpolate)

См. continuous.interpolate.

pow.ticks([count])

См. continuous.ticks.

pow.tickFormat([count[, specifier]])

См. continuous.tickFormat.

pow.nice([count])

См. continuous.nice.

pow.copy() Source

См. continuous.copy.

d3.scaleSqrt() Source

Создаёт новую непрерывную шкалу степени с единичным доменом [0, 1], единичным диапазоном [0, 1], показателем степени 0,5, по умолчанию интерполятором и отключенной привязкой. Это удобный метод, эквивалентный d3.scalePow().exponent(0.5).

Логарифмические шкалы

Логарифмические шкалы похожи на линейные шкалы, за исключением того, что к значению входного домена применяется логарифмическое преобразование перед вычислением выходного значения диапазона. Сопоставление с выходным значением y можно выразить как функцию от входного значения x: y = m log(x) + b.

Поскольку log(0) = -∞, домен логарифмической шкалы должен быть строго положительным или строго отрицательным; домен не должен содержать или пересекать ноль. Логарифмическая шкала с положительным доменом имеет хорошо определённое поведение для положительных значений, а логарифмическая шкала с отрицательным доменом имеет хорошо определённое поведение для отрицательных значений. (Для отрицательного домена входные и выходные значения неявно умножаются на -1.) Поведение шкалы не определено, если вы передадите отрицательное значение логарифмической шкале с положительным доменом или наоборот.

d3.scaleLog() Source

Создаёт новую непрерывную шкалу с доменом [1, 10], единичным диапазоном [0, 1], основанием 10, по умолчанию интерполятором и отключенной привязкой.

log(value) Source

См. continuous.

log.invert(value)

См. continuous.invert.

log.base([base]) Source

Если base указан, устанавливает основание для этой логарифмической шкалы указанному значению. Если base не указан, возвращает текущее основание, которое по умолчанию равно 10.

log.domain([domain]) Source

См. continuous.domain.

log.range([range]) Source

См. continuous.range.

log.rangeRound([range])

См. continuous.rangeRound.

log.clamp(clamp)

См. continuous.clamp.

log.interpolate(interpolate)

См. continuous.interpolate.

log.ticks([count]) Source

Подобно continuous.ticks, но адаптировано для логарифмической шкалы. Если основание — целое число, возвращаемые отметки равномерно распределены внутри каждой целой степени основания; в противном случае возвращается одна отметка на каждую степень основания. Возвращаемые отметки гарантированно находятся в пределах области значений. Если порядок величин в области значений больше, чем count, то возвращается не более одной отметки на степень. В противном случае значения отметок не отфильтровываются, но обратите внимание, что вы можете использовать log.tickFormat для фильтрации отображения меток. Если count не указан, он по умолчанию равен 10.

log.tickFormat([count[, specifier]]) Source

Подобно continuous.tickFormat, но адаптировано для логарифмической шкалы. Указанное значение count обычно совпадает со значением счётчика, используемого для генерации значений отметок. Если отметок слишком много, форматировщик может вернуть пустую строку для некоторых меток; однако обратите внимание, что отметки по-прежнему отображаются. Чтобы отключить фильтрацию, укажите count равным Infinity. При указании значения счётчика вы также можете указать спецификатор формата или функцию формата. Например, чтобы получить форматировщик отметок, который отобразит 20 отметок валюты, скажем log.tickFormat(20, "$,f"). Если у спецификатора нет определённой точности, точность будет установлена автоматически масштабом, возвращая соответствующий формат. Это предоставляет удобный способ задания формата, точность которого будет автоматически установлена масштабом.

log.nice() Source

Подобно continuous.nice, за исключением того, что область значений расширяется до целых степеней основания. Например, для области значений [0.201479…, 0.996679…], и основания 10, нормализованная область значений — [0.1, 1]. Если область значений имеет более двух значений, нормализация области значений влияет только на первое и последнее значение.

log.copy() Source

См. continuous.copy.

Идентичные шкалы

Идентичные шкалы — это частный случай линейных шкал, где область значений и диапазон совпадают; таким образом, шкала и её метод инвертирования — это идентичная функция. Эти шкалы иногда полезны при работе с координатами пикселей, например, в сочетании с осью или кистью. Идентичные шкалы не поддерживают rangeRound, clamp или interpolate.

d3.scaleIdentity() Source

Создаёт новую идентичную шкалу с единичной областью значений [0, 1] и единичным диапазоном [0, 1].

Шкалы времени

Шкалы времени — это разновидность линейных шкал с временной областью значений: значения области значений приводятся к датам, а не числам, и invert аналогичным образом возвращает дату. Шкалы времени реализуют ticks, основанные на календарных интервалах, упрощая генерацию осей для временных областей значений.

Например, для создания кодирования позиций:

var x = d3.scaleTime()
    .domain([new Date(2000, 0, 1), new Date(2000, 0, 2)])
    .range([0, 960]);

x(new Date(2000, 0, 1,  5)); // 200
x(new Date(2000, 0, 1, 16)); // 640
x.invert(200); // Sat Jan 01 2000 05:00:00 GMT-0800 (PST)
x.invert(640); // Sat Jan 01 2000 16:00:00 GMT-0800 (PST)

Для допустимого значения y в диапазоне, time(time.invert(y)) равно y; аналогично, для допустимого значения x в области значений, time.invert(time(x)) равно x. Метод инвертирования полезен для взаимодействия, например, для определения значения в области значений, соответствующего местоположению пикселя под курсором.

d3.scaleTime() Source

Создаёт новую шкалу времени с областью значений [2000-01-01, 2000-01-02], единичным диапазоном [0, 1], по умолчанию интерполятором и отключенной ограничением.

time(value) Source

См. continuous.

time.invert(value) Source

См. continuous.invert.

time.domain([domain]) Source

См. continuous.domain.

time.range([range])

См. continuous.range.

time.rangeRound([range])

См. continuous.rangeRound.

time.clamp(clamp)

См. continuous.clamp.

time.interpolate(interpolate)

См. continuous.interpolate.

time.ticks([count]) Source
time.ticks([interval])

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

Можно указать необязательный count, чтобы повлиять на количество генерируемых отметок. Если count не указан, он по умолчанию равен 10. Указанное значение count является лишь подсказкой; шкала может вернуть больше или меньше значений в зависимости от области значений. Например, для создания десяти отметок по умолчанию:

var x = d3.scaleTime();

x.ticks(10);
// [Sat Jan 01 2000 00:00:00 GMT-0800 (PST),
//  Sat Jan 01 2000 03:00:00 GMT-0800 (PST),
//  Sat Jan 01 2000 06:00:00 GMT-0800 (PST),
//  Sat Jan 01 2000 09:00:00 GMT-0800 (PST),
//  Sat Jan 01 2000 12:00:00 GMT-0800 (PST),
//  Sat Jan 01 2000 15:00:00 GMT-0800 (PST),
//  Sat Jan 01 2000 18:00:00 GMT-0800 (PST),
//  Sat Jan 01 2000 21:00:00 GMT-0800 (PST),
//  Sun Jan 02 2000 00:00:00 GMT-0800 (PST)]

Следующие временные интервалы рассматриваются для автоматических отметок:

• 1-, 5-, 15- и 30-секундные.
• 1-, 5-, 15- и 30-минутные.
• 1-, 3-, 6- и 12-часовые.
• 1- и 2-дневные.
• 1-недельные.
• 1- и 3-месячные.
• 1-годовые.

Вместо count можно явно указать временной интервал. Для обрезания сгенерированных отметок для заданного временного интервала используйте interval.every. Например, для генерации отметок через 15-минут:

var x = d3.scaleTime()
    .domain([new Date(2000, 0, 1, 0), new Date(2000, 0, 1, 2)]);

x.ticks(d3.timeMinute.every(15));
// [Sat Jan 01 2000 00:00:00 GMT-0800 (PST),
//  Sat Jan 01 2000 00:15:00 GMT-0800 (PST),
//  Sat Jan 01 2000 00:30:00 GMT-0800 (PST),
//  Sat Jan 01 2000 00:45:00 GMT-0800 (PST),
//  Sat Jan 01 2000 01:00:00 GMT-0800 (PST),
//  Sat Jan 01 2000 01:15:00 GMT-0800 (PST),
//  Sat Jan 01 2000 01:30:00 GMT-0800 (PST),
//  Sat Jan 01 2000 01:45:00 GMT-0800 (PST),
//  Sat Jan 01 2000 02:00:00 GMT-0800 (PST)]

В качестве альтернативы, передайте функцию-тест в interval.filter:

x.ticks(d3.timeMinute.filter(function(d) {
  return d.getMinutes() % 15 === 0;
}));

Примечание: в некоторых случаях, например, с суточными отметками, указание шага может привести к неравномерному размещению отметок, так как временные интервалы имеют различную длительность.

time.tickFormat([count[, specifier]]) Source
time.tickFormat([interval[, specifier]])

Возвращает функцию форматирования времени, подходящую для отображения значений отметок. Указанное значение count или interval в настоящее время игнорируется, но принимается для согласованности с другими шкалами, такими как continuous.tickFormat. Если указан спецификатор формата specifier, этот метод эквивалентен format. Если specifier не указан, возвращается формат времени по умолчанию. По умолчанию многомасштабный формат времени выбирает удобочитаемое представление на основе указанной даты следующим образом:

• %Y - для границ года, таких как 2011.
• %B - для границ месяца, таких как February.
• %b %d - для границ недели, таких как Feb 06.
• %a %d - для границ дня, таких как Mon 07.
• %I %p - для границ часа, таких как 01 AM.
• %I:%M - для границ минуты, таких как 01:23.
• :%S - для границ секунды, таких как :45.
• .%L - миллисекунды для всех остальных времен, таких как .012.

Хотя это и несколько необычно, такое поведение по умолчанию имеет преимущество в обеспечении как локального, так и глобального контекста: например, форматирование последовательности отметок как [23:00, Пн 07, 01:00] показывает информацию об часах, датах и днях одновременно, а не только о часах [23:00, 00:00, 01:00]. Обратитесь к d3-time-format, если вы хотите создать собственный условный формат времени.

time.nice([count]) Source
time.nice([interval[, step]])

Расширяет область значений так, чтобы она начиналась и заканчивалась на красивых круглых значениях. Этот метод обычно изменяет область значений шкалы и может расширять границы до ближайшего круглого значения. См. continuous.nice для получения дополнительной информации.

Необязательный аргумент счётчика отметок count позволяет получить больший контроль над шагом, используемым для расширения границ, гарантируя, что возвращаемые отметки будут точно покрывать область значений. В качестве альтернативы можно указать временной интервал для явного задания отметок. Если interval указан, можно также указать необязательный step для пропуска некоторых отметок. Например, time.nice(d3.timeSecond, 10) расширит область значений до целых десяти секунд (0, 10, 20, и т.д.). См. time.ticks и interval.every для получения более подробной информации.

Нормализация полезна, если область значений вычисляется из данных, например, с помощью extent, и может быть нерегулярной. Например, для области значений [2009-07-13T00:02, 2009-07-13T23:48], нормализованная область значений — [2009-07-13, 2009-07-14]. Если область значений имеет более двух значений, нормализация области значений влияет только на первое и последнее значение.

d3.scaleUtc() Source

Эквивалентно time, но возвращаемая шкала времени работает в координированном универсальном времени вместо местного времени.

Последовательные шкалы

Последовательные шкалы аналогичны непрерывным шкалам в том, что они отображают непрерывную числовую область входных данных в непрерывный диапазон выходных данных. Однако, в отличие от непрерывных шкал, диапазон выходных данных последовательной шкалы фиксирован её интерполятором и не настраивается. Эти шкалы не предоставляют методы invert, range, rangeRound и interpolate.

d3.scaleSequential(interpolator) Исходный код

Создаёт новую последовательную шкалу с заданной функцией интерполятора. Когда шкала применяется, интерполятор будет вызываться со значением, как правило, в диапазоне [0, 1], где 0 представляет начало области определения, а 1 — конец области определения. Например, для реализации неудачной шкалы радуги HSL:

var rainbow = d3.scaleSequential(function(t) {
  return d3.hsl(t * 360, 1, 0.5) + "";
});

Более эстетически приятное и перцептивно эффективное кодирование циклической цветовой гаммы — использовать d3.interpolateRainbow:

var rainbow = d3.scaleSequential(d3.interpolateRainbow);

Для получения ещё более последовательных цветовых схем см. d3-scale-chromatic.

sequential(value) Исходный код

См. непрерывный.

sequential.domain([domain]) Исходный код

См. непрерывный.domain. Обратите внимание, что область определения последовательной шкалы должна быть числовой и содержать ровно два значения.

sequential.clamp([clamp]) Исходный код

См. непрерывный.clamp.

sequential.interpolator([interpolator]) Исходный код

Если интерполятор указан, устанавливает интерполятор шкалы в указанную функцию. Если интерполятор не указан, возвращает текущий интерполятор шкалы.

sequential.copy() Исходный код

См. непрерывный.copy.

d3.interpolateViridis(t) Исходный код

Принимая число t в диапазоне [0,1], возвращает соответствующий цвет из перцептивно-равномерной цветовой схемы «viridis», разработанной ван дер Валтом, Смитом и Файрингом для matplotlib, представленный в виде RGB-строки.

d3.interpolateInferno(t)

Принимая число t в диапазоне [0,1], возвращает соответствующий цвет из перцептивно-равномерной цветовой схемы «inferno», разработанной ван дер Валтом и Смитом для matplotlib, представленный в виде RGB-строки.

d3.interpolateMagma(t)

Принимая число t в диапазоне [0,1], возвращает соответствующий цвет из перцептивно-равномерной цветовой схемы «magma», разработанной ван дер Валтом и Смитом для matplotlib, представленный в виде RGB-строки.

d3.interpolatePlasma(t)

Принимая число t в диапазоне [0,1], возвращает соответствующий цвет из перцептивно-равномерной цветовой схемы «plasma», разработанной ван дер Валтом и Смитом для matplotlib, представленный в виде RGB-строки.

d3.interpolateWarm(t)

Принимая число t в диапазоне [0,1], возвращает соответствующий цвет из 180° поворота перцептивной радуги Никколи, представленный в виде RGB-строки.

d3.interpolateCool(t)

Принимая число t в диапазоне [0,1], возвращает соответствующий цвет из перцептивной радуги Никколи, представленный в виде RGB-строки.

d3.interpolateRainbow(t) Исходный код

Принимая число t в диапазоне [0,1], возвращает соответствующий цвет из шкалы d3.interpolateWarm от [0,0, 0,5] и шкалы d3.interpolateCool от [0,5, 1,0], таким образом реализуя циклическую менее агрессивную радужную цветовую схему.

d3.interpolateCubehelixDefault(t) Исходный код

Принимая число t в диапазоне [0,1], возвращает соответствующий цвет из стандартной схемы Cubehelix Грина, представленный в виде RGB-строки.

Шкалы квантования

Шкалы квантования похожи на линейные шкалы, за исключением того, что они используют дискретный, а не непрерывный диапазон. Непрерывная область определения входных данных делится на равные сегменты, основанные на количестве значений в (то есть, мощности) области значений вывода. Каждое значение диапазона y может быть выражено как квантованная линейная функция значения области определения x: y = m round(x) + b. См. bl.ocks.org/4060606 для примера.

d3.scaleQuantize() Исходный код

Создаёт новую шкалу квантования с единичной областью определения [0, 1] и единичным диапазоном [0, 1]. Таким образом, стандартная шкала квантования эквивалентна функции Math.round.

quantize(value) Исходный код

Принимая значение в области определения входных данных, возвращает соответствующее значение в диапазоне вывода. Например, для применения цветового кодирования:

var color = d3.scaleQuantize()
    .domain([0, 1])
    .range(["brown", "steelblue"]);

color(0.49); // "brown"
color(0.51); // "steelblue"

Или деления области определения на три равных части с разными значениями диапазона для вычисления соответствующей ширины штриха:

var width = d3.scaleQuantize()
    .domain([10, 100])
    .range([1, 2, 4]);

width(20); // 1
width(50); // 2
width(80); // 4

quantize.invertExtent(value) Исходный код

Возвращает область значений в области определения [x0, x1] для соответствующего значения в диапазоне вывода: обратная функция quantize. Этот метод полезен для взаимодействия, например, для определения значения в области определения, соответствующего расположению пикселя под курсором мыши.

var width = d3.scaleQuantize()
    .domain([10, 100])
    .range([1, 2, 4]);

width.invertExtent(2); // [40, 70]

quantize.domain([domain]) Исходный код

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

quantize.range([range]) Исходный код

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

quantize.ticks([count])

Эквивалентно непрерывный.ticks.

quantize.tickFormat([count[, specifier]]) Исходный код

Эквивалентно непрерывный.tickFormat.

quantize.nice()

Эквивалентно непрерывный.nice.

quantize.copy() Исходный код

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

Шкалы квантилей

Шкалы квантилей отображают выборочную область определения входных данных в дискретный диапазон. Область определения считается непрерывной, и поэтому шкала примет любое разумное входное значение; однако область определения задается как дискретный набор выборочных значений. Количество значений в (мощность) области значений вывода определяет количество квантилей, которые будут вычислены из области определения. Для вычисления квантилей область определения сортируется и рассматривается как совокупность дискретных значений; см. квантиль d3-array’s quantile. См. bl.ocks.org/8ca036b3505121279daf для примера.

d3.scaleQuantile() Исходный код

Создаёт новую шкалу квантилей с пустой областью определения и пустым диапазоном. Шкала квантилей недействительна, пока не будут заданы область определения и диапазон.

quantile(value) Исходный код

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

quantile.invertExtent(value) Источник

Возвращает диапазон значений в области [x0, x1] для соответствующего значения в диапазоне: обратное значение quantile. Этот метод полезен для взаимодействия, например, для определения значения в области, соответствующего положению пикселя под курсором.

quantile.domain([domain]) Источник

Если domain задан, устанавливает область шкалы quantile в указанный набор дискретных числовых значений. Массив не должен быть пустым и должен содержать по крайней мере одно числовое значение; значения NaN, null и undefined игнорируются и не считаются частью выборки. Если элементы в заданном массиве не являются числами, они будут преобразованы в числа. Копия входного массива сортируется и хранится внутри. Если domain не задан, возвращает текущую область шкалы.

quantile.range([range]) Источник

Если range задан, устанавливает дискретные значения в диапазоне. Массив не должен быть пустым и может содержать любые типы значений. Количество значений в (мощность или длина) массиве range определяет количество квантилей, которые вычисляются. Например, чтобы вычислить квартили, range должен быть массивом из четырех элементов, таких как [0, 1, 2, 3]. Если range не задан, возвращает текущий диапазон.

quantile.quantiles() Источник

Возвращает пороговые значения квантилей. Если диапазон содержит n дискретных значений, возвращаемый массив будет содержать n - 1 пороговых значения. Значения, меньшие первого порога, считаются в первой квантили; значения, большие или равные первому порогу, но меньшие второго порога, находятся во второй квантили и так далее. Внутри массив пороговых значений используется с бисекцией для нахождения выходной квантили, связанной с заданным входным значением.

quantile.copy() Источник

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

Шкалы пороговых значений

Шкалы пороговых значений аналогичны шкалам квантизации, за исключением того, что они позволяют отображать произвольные подмножества области в дискретные значения в диапазоне. Входная область по-прежнему непрерывна и разделена на части на основе набора пороговых значений. См. bl.ocks.org/3306362 для примера.

d3.scaleThreshold() Источник

Создает новую шкалу пороговых значений с домен по умолчанию [0,5] и диапазоном по умолчанию [0, 1]. Таким образом, шкала пороговых значений по умолчанию эквивалентна функции Math.round для чисел; например, threshold(0,49) возвращает 0, а threshold(0,51) возвращает 1.

threshold(value) Источник

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

var color = d3.scaleThreshold()
    .domain([0, 1])
    .range(["red", "white", "green"]);

color(-1);   // "red"
color(0);    // "white"
color(0.5);  // "white"
color(1);    // "green"
color(1000); // "green"

threshold.invertExtent(value) Источник

Возвращает диапазон значений в области [x0, x1] для соответствующего значения в диапазоне, представляющего обратное отображение из диапазона в область. Этот метод полезен для взаимодействия, например, для определения значения в области, соответствующего положению пикселя под курсором. Например:

var color = d3.scaleThreshold()
    .domain([0, 1])
    .range(["red", "white", "green"]);

color.invertExtent("red"); // [undefined, 0]
color.invertExtent("white"); // [0, 1]
color.invertExtent("green"); // [1, undefined]

threshold.domain([domain]) Источник

Если domain задан, устанавливает область шкалы в указанный массив значений. Значения должны быть отсортированы в порядке возрастания, в противном случае поведение шкалы не определено. Значения, как правило, являются числами, но любые естественно упорядоченные значения (например, строки) также подойдут; шкала пороговых значений может использоваться для кодирования любого упорядоченного типа. Если количество значений в диапазоне шкалы равно N+1, количество значений в области шкалы должно быть равно N. Если элементов в области меньше, чем N, дополнительные значения в диапазоне игнорируются. Если элементов в области больше, чем N, шкала может вернуть неопределенное значение для некоторых входных данных. Если domain не задан, возвращает текущую область шкалы.

threshold.range([range]) Источник

Если range задан, устанавливает диапазон шкалы в указанный массив значений. Если количество значений в области шкалы равно N, количество значений в диапазоне шкалы должно быть равно N+1. Если элементов в диапазоне меньше, чем N+1, шкала может вернуть неопределенное значение для некоторых входных данных. Если элементов в диапазоне больше, чем N+1, дополнительные значения игнорируются. Элементы в заданном массиве не обязательно должны быть числами; подойдет любое значение или тип. Если range не задан, возвращает текущий диапазон.

threshold.copy() Источник

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

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

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

d3.scaleOrdinal([range]) Источник

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

ordinal(value) Источник

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

ordinal.domain([domain]) Источник

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

Установка области на порядковой шкале необязательна, если неизвестное значение является явным (по умолчанию). В этом случае область будет неявно выводиться из использования, назначая каждому уникальному значению, переданному шкале, новое значение из диапазона. Обратите внимание, что явная область рекомендуется для обеспечения детерминированного поведения, так как вывод области из использования будет зависеть от порядка.

ordinal.range([range]) Источник

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

ordinal.unknown([value]) Источник

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

ordinal.copy() Источник

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

d3.scaleImplicit

Специальное значение для ordinal.unknown, которое позволяет неявно создавать область: неизвестные значения неявно добавляются в область.

Шкалы полос

Масштабы полос похожи на шкалы порядка, за исключением того, что диапазон вывода непрерывный и числовой. Дискретные значения вывода автоматически вычисляются масштабом путём деления непрерывного диапазона на равномерные полосы. Масштабы полос обычно используются для столбиковых диаграмм с порядковой или категориальной размерностью. Неизвестное значение шкалы полос фактически не определено: они не позволяют создавать неявные домены.

d3.scaleBand() Source

Создаёт новый масштаб полос с пустым домен, единичным диапазоном [0, 1], без отступа, без округления и центрированным выравниванием.

band(value) Source

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

band.domain([domain]) Source

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

band.range([range]) Source

Если указан range, устанавливает диапазон шкалы в указанный массив из двух чисел. Если элементы заданного массива не являются числами, они будут приведены к числовому типу. Если range не указан, возвращает текущий диапазон шкалы, который по умолчанию равен [0, 1].

band.rangeRound([range]) Source

Устанавливает диапазон шкалы в указанный массив из двух чисел, одновременно включив округление. Это вспомогательный метод, эквивалентный:

band
    .range(range)
    .round(true);

Округление иногда полезно для устранения артефактов антиалиасинга, хотя также следует рассмотреть стили shape-rendering «crispEdges».

band.round([round]) Source

Если указан round, включает или выключает округление соответственно. При включенном округлении начало и конец каждой полосы будут целыми числами. Округление иногда полезно для устранения артефактов антиалиасинга, хотя также следует рассмотреть стили shape-rendering «crispEdges». Обратите внимание, что если ширина домена не является кратной количеству элементов в диапазоне, может остаться неиспользуемое пространство, даже без отступа! Используйте band.align для указания, как распределяется оставшееся пространство.

band.paddingInner([padding]) Source

Если указан padding, устанавливает внутренний отступ в указанное значение, которое должно находиться в диапазоне [0, 1]. Если padding не указан, возвращает текущий внутренний отступ, который по умолчанию равен 0. Внутренний отступ определяет пропорцию диапазона, зарезервированную для пустого места между полосами.

band.paddingOuter([padding]) Source

Если указан padding, устанавливает внешний отступ в указанное значение, которое должно находиться в диапазоне [0, 1]. Если padding не указан, возвращает текущий внешний отступ, который по умолчанию равен 0. Внешний отступ определяет пропорцию диапазона, зарезервированную для пустого места перед первой полосой и после последней полосы.

band.padding([padding]) Source

Вспомогательный метод для установки внутреннего и внешнего отступа на одно и то же значение padding. Если padding не указан, возвращает внутренний отступ.

band.align([align]) Source

Если указан align, устанавливает выравнивание в указанное значение, которое должно находиться в диапазоне [0, 1]. Если align не указан, возвращает текущее выравнивание, которое по умолчанию равно 0,5. Выравнивание определяет, как распределяется любое оставшееся неиспользуемое пространство в диапазоне. Значение 0,5 указывает, что оставшееся пространство должно быть равномерно распределено перед первой полосой и после последней полосы; т.е., полосы должны быть центрированы в диапазоне. Значение 0 или 1 может использоваться для смещения полос в одну сторону, например, для позиционирования их рядом с осью.

band.bandwidth() Source

Возвращает ширину каждой полосы.

band.step() Source

Возвращает расстояние между началом смежных полос.

band.copy() Source

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

Шкалы точек

Шкалы точек — это вариант шкал полос с шириной полосы, фиксированной в нуле. Шкалы точек обычно используются для диаграмм рассеяния с порядковой или категориальной размерностью. Неизвестное значение шкалы точек всегда не определено: они не позволяют создавать неявные домены.

d3.scalePoint()

Создаёт новую шкалу точек с пустым домен, единичным диапазоном [0, 1], без отступа, без округления и центрированным выравниванием.

point(value)

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

point.domain([domain])

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

point.range([range])

Если указан range, устанавливает диапазон шкалы в указанный массив из двух чисел. Если элементы заданного массива не являются числами, они будут приведены к числовому типу. Если range не указан, возвращает текущий диапазон шкалы, который по умолчанию равен [0, 1].

point.rangeRound([range])

Устанавливает диапазон шкалы в указанный массив из двух чисел, одновременно включив округление. Это вспомогательный метод, эквивалентный:

point
    .range(range)
    .round(true);

Округление иногда полезно для устранения артефактов антиалиасинга, хотя также следует рассмотреть стили shape-rendering «crispEdges».

point.round([round])

Если указан round, включает или выключает округление соответственно. При включенном округлении позиция каждой точки будет целым числом. Округление иногда полезно для устранения артефактов антиалиасинга, хотя также следует рассмотреть стили shape-rendering «crispEdges». Обратите внимание, что если ширина домена не является кратной количеству элементов в диапазоне, может остаться неиспользуемое пространство, даже без отступа! Используйте point.align для указания, как распределяется оставшееся пространство.

point.padding([padding])

Если указан padding, устанавливает внешний отступ в указанное значение, которое должно находиться в диапазоне [0, 1]. Если padding не указан, возвращает текущий внешний отступ, который по умолчанию равен 0. Внешний отступ определяет пропорцию диапазона, зарезервированную для пустого места перед первой точкой и после последней точки. Эквивалентно band.paddingOuter.

point.align([align])

Если указан align, устанавливает выравнивание в указанное значение, которое должно находиться в диапазоне [0, 1]. Если align не указан, возвращает текущее выравнивание, которое по умолчанию равно 0,5. Выравнивание определяет, как распределяется любое оставшееся неиспользуемое пространство в диапазоне. Значение 0,5 указывает, что оставшееся пространство должно быть равномерно распределено перед первой точкой и после последней точки; т.е., точки должны быть центрированы в диапазоне. Значение 0 или 1 может использоваться для смещения точек в одну сторону, например, для позиционирования их рядом с осью.

point.bandwidth()

Возвращает ноль.

point.step()

Возвращает расстояние между началом смежных точек.

point.copy()

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

Категориальные шкалы

Эти схемы цветов разработаны для работы со d3.scaleOrdinal. Например:

var color = d3.scaleOrdinal(d3.schemeCategory10);

Для ещё большего разнообразия категориальных шкал, см. d3-scale-chromatic.

d3.schemeCategory10 Source

Массив из десяти категориальных цветов, представленных в виде шестнадцатеричных строк RGB.

d3.schemeCategory20 Source

Массив из двадцати категориальных цветов, представленных в виде шестнадцатеричных строк RGB.

d3.schemeCategory20b Source

Массив из двадцати категориальных цветов, представленных в виде шестнадцатеричных строк RGB.

d3.schemeCategory20c Source

Массив из двадцати категориальных цветов, представленных в виде шестнадцатеричных строк RGB. Эта цветовая шкала включает в себя спецификации и дизайны цветов, разработанные Синтией Брюэр (colorbrewer2.org).