d3-scale

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

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

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

Этот репозиторий не предоставляет цветовые схемы; см. d3-scale-chromatic для цветовых схем, предназначенных для работы с d3-scale.

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

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

• Introducing d3-scale от Майкла Бостока

• Глава 7. Масштабы из Interactive Data Visualization for the Web Скотта Меррея

• d3: scales, and color. Жерома Кукиера

Установка

Если вы используете NPM, npm install d3-scale. В противном случае загрузите последнюю версию. Вы также можете загрузить напрямую с d3js.org, как самостоятельную библиотеку, или как часть D3. Поддерживаются среды 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.v2.min.js"></script>
<script>

var x = d3.scaleLinear();

</script>

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

Справочник API

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

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

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

continuous(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) Источник

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

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

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

Если заданное значение находится за пределами диапазона, и прижимание не включено, отображение может быть экстраполировано так, что возвращаемое значение находится за пределами домена. Этот метод поддерживается только в том случае, если диапазон числовой. Если диапазон не числовой, возвращает 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, устанавливает фабрику интерполятора диапазона масштаба. Эта фабрика интерполятора используется для создания интерполяторов для каждой смежной пары значений из диапазона; эти интерполяторы затем отображают нормированный параметр домена 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 представительных значений из области масштаба domain. Если count не указан, он по умолчанию равен 10. Возвращённые значения делений равномерно распределены, имеют удобочитаемые значения (например, кратные степеням 10) и гарантированно находятся в пределах области. Деления часто используются для отображения вспомогательных линий или делений шкалы вместе с визуализируемыми данными. Указанное count является лишь подсказкой; масштаб может вернуть больше или меньше значений в зависимости от области. См. также ticks в d3-array.

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

Возвращает функцию форматирования чисел number format, подходящую для отображения значения деления, автоматически вычисляя соответствующую точность на основе фиксированного интервала между значениями делений. Указанное 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-prefix format, основанный на наибольшем значении в области. Если specifier уже задаёт точность, этот метод эквивалентен методу locale.format.

continuous.nice([count]) Source

Расширяет область масштаба так, чтобы она начиналась и заканчивалась на красивых значениях. Этот метод обычно изменяет область масштаба и может расширять границы до ближайшего подходящего значения. Необязательный аргумент tick count позволяет больше управлять шагом, используемым для расширения границ, гарантируя, что возвращаемые деления будут точно покрывать область. Применение nice полезно, если область вычисляется из данных, скажем, с помощью extent, и может быть нерегулярной. Например, для области [0,201479…, 0,996679…], область nice может быть [0,2, 1,0]. Если область имеет более двух значений, применение nice влияет только на первое и последнее значение. См. также tickStep в d3-array.

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

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) Source

См. continuous.invert.

pow.exponent([exponent]) Source

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

pow.domain([domain]) Source

См. continuous.domain.

pow.range([range]) Source

См. continuous.range.

pow.rangeRound([range]) Source

См. continuous.rangeRound.

pow.clamp(clamp) Source

См. continuous.clamp.

pow.interpolate(interpolate) Source

См. continuous.interpolate.

pow.ticks([count]) Source

См. continuous.ticks.

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

См. continuous.tickFormat.

pow.nice([count]) Source

См. 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) Source

См. continuous.invert.

log.base([base]) Source

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

log.domain([domain]) Source

См. continuous.domain.

log.range([range]) Source

См. continuous.range.

log.rangeRound([range]) Source

См. continuous.rangeRound.

log.clamp(clamp) Source

См. continuous.clamp.

log.interpolate(interpolate) Source

См. continuous.interpolate.

log.ticks([count]) Source

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

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

Подобно continuous.tickFormat, но настраивается для логарифмической шкалы. Указанное значение count обычно имеет то же значение, что и значение подсчета, используемое для создания значений меток. Если меток слишком много, форматер может вернуть пустую строку для некоторых меток; однако обратите внимание, что метки всё ещё отображаются. Чтобы отключить фильтрацию, укажите count равным Infinity. При указании значения count вы также можете указать спецификатор формата или функцию формата. Например, чтобы получить форматер меток, который отобразит 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].

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

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

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

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]) Source

См. continuous.range.

time.rangeRound([range]) Source

См. continuous.rangeRound.

time.clamp(clamp) Source

См. continuous.clamp.

time.interpolate(interpolate) Source

См. 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 позволяет более точно управлять шагом, используемым для расширения границ, гарантируя, что возвращённые деления будут точно покрывать область определения. В качестве альтернативы можно указать интервал времени для явного задания делений. Если указан интервал, можно также указать необязательный аргумент 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, но возвращаемая шкала времени работает в координированном универсальном времени (UTC), а не в местном времени.

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

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

d3.scaleSequential(interpolator) Source

Создаёт новую последовательную шкалу с заданной функцией интерполятора. При применении шкалы интерполятор вызывается со значением, обычно в диапазоне [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);

sequential(value) Source

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

sequential.domain([domain]) Source

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

sequential.clamp([clamp]) Source

См. continuous.clamp.

sequential.interpolator([interpolator]) Source

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

sequential.copy() Source

См. continuous.copy.

Расходящиеся шкалы

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

d3.scaleDiverging(interpolator) Source

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

var spectral = d3.scaleDiverging(d3.interpolateSpectral);

diverging(value) Source

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

diverging.domain([domain]) Source

См. continuous.domain. Обратите внимание, что область определения расходящейся шкалы должна быть числовой и содержать ровно три значения. По умолчанию область определения — [0, 0,5, 1].

diverging.clamp([clamp]) Source

См. continuous.clamp.

diverging.interpolator([interpolator]) Source

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

diverging.copy() Source

См. continuous.copy.

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

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

d3.scaleQuantize() Source

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

quantize(value) Source

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

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) Source

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

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

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

quantize.domain([domain]) Source

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

quantize.range([range]) Source

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

quantize.ticks([count]) Source

Эквивалентно continuous.ticks.

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

Эквивалентно continuous.tickFormat.

quantize.nice() Source

Эквивалентно continuous.nice.

quantize.copy() Source

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

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

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

d3.scaleQuantile() Source

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

quantile(value) Source

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

quantile.invertExtent(value) Source

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

quantile.domain([domain]) Source

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

quantile.range([range]) Source

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

quantile.quantiles() Source

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

quantile.copy() Source

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

Масштабы порогов

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

d3.scaleThreshold() Source

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

threshold(value) Source

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

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) Source

Возвращает диапазон значений в домене [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]) Source

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

threshold.range([range]) Source

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

threshold.copy() Source

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

Порядковые масштабы

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

d3.scaleOrdinal([range]) Source

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

ordinal(value) Source

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

ordinal.domain([domain]) Source

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

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

ordinal.range([range]) Source

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

ordinal.unknown([value]) Source

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

ordinal.copy() Source

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

d3.scaleImplicit Source

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

Диапазонные шкалы

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

d3.scaleBand() Source

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

band(значение) Source

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

band.domain([domain]) Source

Если domain указан, устанавливает область значений в указанный массив значений. Первый элемент в domain будет сопоставлен с первой полосой, второе значение области — со второй полосой и так далее. Значения области хранятся в памяти в отображении от строкового значения к индексу; полученный индекс затем используется для определения полосы. Таким образом, значения диапазонной шкалы должны быть преобразуемы в строку, а строковое представление значения области uniquely определяет соответствующую полосу. Если 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() Source

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

point(значение) Source

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

point.domain([domain]) Source

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

point.range([range]) Source

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

point.rangeRound([range]) Source

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

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

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

point.round([round]) Source

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

point.padding([padding]) Source

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

point.align([align]) Source

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

point.bandwidth() Source

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

point.step() Source

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

point.copy() Source

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