Форматы данных

В этом документе объясняется, как отправить данные диаграммы в Google Chart API.

Оглавление

  1. Обзор
  2. Основной текстовый формат
  3. Текстовый формат с автоматическим масштабированием
  4. Текстовый формат с пользовательским масштабированием
  5. Простой формат кодирования
  6. Расширенный формат кодирования
  7. Масштабирование данных и масштабирование по осям
  8. Сценарий кодирования JavaScript

Обзор

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

  • Базовый текстовый формат — это, по сути, простые числа с плавающей запятой от 0 до 100 включительно. Этот формат легко читать и писать от руки.
  • Текстовый формат с автоматическим масштабированием масштабирует диаграмму в соответствии с вашими данными.
  • Текстовый формат с настраиваемым масштабированием аналогичен базовому текстовому формату, но позволяет указать настраиваемый диапазон с помощью второго параметра URL-адреса.
  • Простой формат кодирования позволяет указывать целочисленные значения от 0 до 61 включительно, закодированные одним буквенно-цифровым символом. В результате этого кодирования получается самая короткая строка данных из всех форматов данных (если какие-либо значения больше 9).
  • Расширенный формат кодирования позволяет указывать целочисленные значения от 0 до 4095 включительно, закодированные двумя буквенно-цифровыми символами. Расширенное кодирование лучше всего подходит для диаграмм с большим количеством данных и большим диапазоном данных.

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

Мы предоставляем фрагмент JavaScript для кодирования данных в простые или расширенные форматы кодирования. Кроме того, несколько членов группы Google Chart предоставили другие библиотеки для помощи в форматировании: найдите их в архивах.

Основной текстовый формат

Базовые данные в текстовом формате позволяют указывать значения с плавающей запятой от 0 до 100 включительно в виде чисел. Значения ниже нуля помечаются как отсутствующие; значения выше 100 усекаются до 100. Преимущество базового текстового формата заключается в том, что значения легко читаются и понимаются в URL-адресе, а метки осей по умолчанию точно отображают значения данных. Однако форматирование текста (простое или с настраиваемыми параметрами) приводит к созданию самой длинной строки данных из всех форматов.

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

Синтаксис :

chd=t:val,val,val|val,val,val...
< данные >
Каждая серия представляет собой одно или несколько значений, разделенных запятыми. Разделите несколько серий с помощью вертикальной черты ( | ). Значения представляют собой числа с плавающей запятой от 0 до 100 включительно. Значения меньше нуля или символ подчеркивания ( _ ) считаются нулевыми значениями. Значения выше 100 усекаются до 100.

Пример:

Таблица с пятью значениями. Подчеркивание считается нулевым значением, значение -30 падает ниже минимального значения, поэтому оно отбрасывается, а значение 200 усекается до 100. Bar chart with 5 values, text encoding.
chd=t:_,30,-30,50,80,200

Вернуться наверх

Текстовый формат с автоматическим масштабированием

Некоторые диаграммы можно настроить на автоматическое масштабирование в соответствии с их данными. Диаграмма будет масштабирована таким образом, чтобы наибольшее значение располагалось вверху диаграммы, а наименьшее (или нулевое, если все значения больше нуля) — внизу.

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

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

Синтаксис

cht=t:val,val,val...
chds=a

Примеры:


chd=t:5,30,50,80,200
chds=a

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

Bar chart with 5 values, text encoding.
chd=t:-5,30,-30,50,80,200
chds=a

Вернуться наверх

Текстовый формат с пользовательским масштабированием

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

Для автоматического масштабирования укажите chds=a .

Форматирование текста (простое или с настраиваемыми параметрами) приводит к созданию самой длинной строки данных из всех форматов.

Синтаксис:

Для форматирования текста с пользовательским масштабированием требуются два параметра:

chd=t:val,val,val|val,val,val
chds=<series_1_min>,<series_1_max>,...,<series_n_min>,<series_n_max>
chd=t:< данные >
То же, что и обычный формат данных: одно или несколько значений, разделенных запятыми, на серию, несколько серий, разделенных вертикальной чертой ( | ). Диапазон допустимых значений в каждой серии задается параметром chds .
чдс
Набор из одного или нескольких минимальных и максимально допустимых значений для каждой серии данных, разделенных запятыми. Вы должны указать как максимум, так и минимум. Если вы предоставляете меньше пар, чем имеется рядов данных, последняя пара применяется ко всем оставшимся рядам данных. Обратите внимание, что это не меняет диапазон оси ; чтобы изменить диапазон оси, необходимо установить параметр chxr . Допустимые значения находятся в диапазоне (+/-)9,999e(+/-)199. Вы можете указать значения в стандартной нотации или в системе E.
< серия_1_мин >
Минимально допустимое значение в первой серии. Более низкие значения помечаются как отсутствующие.
< серия_1_макс >
Максимально допустимое значение в первой серии. Более высокие значения усекаются до этого значения.

Пример:

Гистограмма со шкалой мин/макс от -80 до 140. Значения 30, -60, 50, 140 и 80 попадают в пределы шкалы, поэтому они не усекаются. Обратите внимание, что нулевая линия настроена автоматически: 80/(140 + 80) = 0,36 вверх по оси Y.

Также обратите внимание, что диапазон оси Y по умолчанию по-прежнему составляет 0–100, несмотря на параметр chds , поэтому значения меток не отражают фактические значения данных.

Bar chart with 5 values, text encoding with data scaling.

chd=t:30,-60,50,140,80,-90
chds=-80,140

Вернуться наверх

Простой формат кодирования

Простой формат кодирования позволяет указывать целочисленные значения от 0 до 61 включительно, закодированные одним буквенно-цифровым символом. В результате получается самый короткий URL-адрес строки данных из всех форматов данных. Однако если у вас есть линейная или гистограмма, длина которой превышает 100 пикселей по оси данных, возможно, вам захочется использовать другой формат. Это связано с тем, что при поддержке всего 62 значений данных степень детализации данных намного выше, чем степень детализации отображения, и значения будут немного отличаться (незначительно, но заметно на диаграммах большего размера).

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

Синтаксис :

chd=s:
  <series_1>
    ,...,
  <series_n>
<серия_1 >
Строка, где каждый символ представляет собой отдельную точку данных, а серии разделяются запятой. Отдельные значения внутри серии не разграничиваются. Ниже приведены поддерживаемые символы данных и соответствующие им значения:
  • A—Z , где A = 0, B = 1 и т. д. до Z = 25.
  • a—z , где a = 26, b = 27 и т. д. до z = 51.
  • 0(zero)—9 , где 0 = 52 и 9 = 61
  • Символ подчеркивания ( _ ) указывает на отсутствующее значение.

Вы можете использовать следующий инструмент для кодирования одного значения или код JavaScript для масштабирования и кодирования всей строки URL-адреса.

Пример:

Эквивалент текстовой строки chd=t:1,19,27,53,61,-1|12,39,57,45,51,27
chd=s:BTb19_,Mn5tzb

Вернуться наверх

Расширенный формат кодирования

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

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

Синтаксис:

chd=e:
  <series_1>
    ,...,
  <series_n>
<серия_1>
Строка, в которой каждые два символа представляют собой одну точку данных, а серии разделяются запятой. Отдельные значения в серии не разграничиваются. Вот поддерживаемые символы кодировки:
  • A—Z
  • a—z
  • 0—9
  • период ( . )
  • дефис ( - )
  • Отсутствующие значения обозначаются двойным подчеркиванием ( __ ).

Вот сокращенное описание закодированных значений:

  • AA = 0, AB = 1 и так до AZ = 25.
  • Aa = 26, Ab = 27 и так до Az = 51.
  • A0 = 52, A1 = 53 и так далее до A9 = 61.
  • A- =62, A. =63
  • BA = 64, BB = 65 и так до BZ = 89.
  • Ba = 90, Bb = 91 и так до Bz = 115.
  • B0 = 116, B1 = 117 и так далее до B9 = 125.
  • B- =126, B. =127
  • 9A = 3904, 9B = 3905 и так до 9Z = 3929.
  • 9a = 3930, 9b = 3931 и так далее до 9z = 3955.
  • 90 = 3956, 91 = 3957 и так далее до 99 = 3965.
  • 9- = 3966, 9. = 3967
  • -A = 3968, -B = 3969 и т. д. до -Z = 3993.
  • -a = 3994, -b = 3995 и т. д. до -z = 4019.
  • -0 = 4020, -1 = 4021 и т. д. до -9 = 4029.
  • -- = 4030, -. = 4031
  • .A = 4032, .B = 4033 и т. д. до .Z = 4057.
  • .a = 4058, .b = 4059 и т. д. до .z = 4083.
  • .0 = 4084, .1 = 4085 и т. д. до .9 = 4093.
  • .- = 4094, .. = 4095

Вы можете использовать следующий инструмент для кодирования одного значения или код JavaScript для масштабирования и кодирования всей строки URL-адреса.

Пример:

Эквивалент текстовой строки chd=t:90,1000,2700,3500|3968,-1,1100,250 Stacked bar chart with two series of four values each, extended encoding.
chd=e:BaPoqM2s,-A__RMD6

Вернуться наверх

Масштабирование данных и масштабирование по осям

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

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

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

В этом разделе описаны обе эти проблемы.

Данные масштабируются в соответствии с диапазоном формата [ Все диаграммы, кроме пирога и диаграммы Венна ]

Различные форматы поддерживают разные диапазоны значений. Ваши данные масштабируются в соответствии с диапазоном вашего формата, поэтому максимальное значение, поддерживаемое вашим форматом, отображается вверху этой оси, а минимальное значение для вашего формата отображается внизу. В следующих примерах показано одно и то же значение (100) с использованием базового текстового формата (диапазон 0–100), текста с пользовательским масштабированием (пользовательский диапазон 0–200) и расширенного формата кодирования (диапазон 0–4095).

Основной текстовый формат Текстовый формат с пользовательским масштабированием Расширенный формат кодирования
Bar chart with basic text with custom scaling

Значение: 100 ( chd=t:100 )

Диапазон формата: 0–100

Число 100 отображается как 100/100 вверх по шкале.

Значение 100 ( chd=t:100, chds=0,200 )

Диапазон формата: 0–200

Число 100 отображается в масштабе 100/200.

Значение: 100 ( chd=e:Bk )

Диапазон формата: 0–4095.

100 отображается как 100/4095 вверх по шкале.

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

Круговые диаграммы и диаграммы Венна . В круговых диаграммах и диаграммах Венна все значения относятся друг к другу, а не к общему масштабу диаграммы.

chd=e:BkDIEs chd=t:100,200,300
chds=0,300

Диапазон меток оси рассчитывается независимо [ бар, линия, радар, разброс и свеча ]

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

Диапазон оси по умолчанию составляет 0–100, независимо от значений данных или масштабирования данных . Так, например, если вы отображаете ось Y с использованием меток оси по умолчанию на диаграмме, в которой используется расширенная кодировка (диапазон 0–4095), метки оси Y по-прежнему будут иметь значения 0–100, если вы не измените это явно, как описано ниже. . Вот пример, показывающий метки оси Y по умолчанию на гистограмме расширенного кодирования со значением данных 100:


chd=e:Bk (эквивалент chd=t:100 )

Однако вы можете указать диапазон оси, используя параметр chxr . Если вы хотите, чтобы значения осей отражали фактические значения данных, необходимо указать минимальные и максимальные значения осей, соответствующие диапазону вашего формата. Обратите внимание, что базовый текстовый формат уже имеет шкалу от 0 до 100, поэтому, если вы используете базовое форматирование текста (без пользовательского масштабирования), значения осей по умолчанию будут соответствовать значениям данных. Проиллюстрируем это несколькими примерами. Вот три диаграммы с одинаковыми данными (15,26,51,61), но разного формата и с разными масштабами осей:

Простое кодирование, без масштабирования по осям Простое кодирование, масштабированная ось Базовый текст, без масштабирования по осям

chd=s:Paz9

Диапазон значений простого кодирования: 0–61.

Диапазон оси по умолчанию (0–100)

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

chd=s:Paz9
chxr=0,0,61,10

Диапазон значений простого кодирования: 0–61.

Диапазон оси явно установлен на 0–61.

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

chd=t:15,26,51,61

Диапазон значений основного текстового формата: 0–100.

Диапазон оси по умолчанию (0–100)

Диапазон кодирования и диапазон оси снова одинаковы, поэтому точные значения данных по умолчанию отображаются на оси.

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

Вернуться наверх

Сценарий кодирования JavaScript

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

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

var simpleEncoding =
  'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';

// This function scales the submitted values so that
// maxVal becomes the highest value.
function simpleEncode(valueArray,maxValue) {
  var chartData = ['s:'];
  for (var i = 0; i < valueArray.length; i++) {
    var currentValue = valueArray[i];
    if (!isNaN(currentValue) && currentValue >= 0) {
    chartData.push(simpleEncoding.charAt(Math.round((simpleEncoding.length-1) *
      currentValue / maxValue)));
    }
      else {
      chartData.push('_');
      }
  }
  return chartData.join('');
}

// Same as simple encoding, but for extended encoding.
var EXTENDED_MAP=
  'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-.';
var EXTENDED_MAP_LENGTH = EXTENDED_MAP.length;
function extendedEncode(arrVals, maxVal) {
  var chartData = 'e:';

  for(i = 0, len = arrVals.length; i < len; i++) {
    // In case the array vals were translated to strings.
    var numericVal = new Number(arrVals[i]);
    // Scale the value to maxVal.
    var scaledVal = Math.floor(EXTENDED_MAP_LENGTH *
        EXTENDED_MAP_LENGTH * numericVal / maxVal);

    if(scaledVal > (EXTENDED_MAP_LENGTH * EXTENDED_MAP_LENGTH) - 1) {
      chartData += "..";
    } else if (scaledVal < 0) {
      chartData += '__';
    } else {
      // Calculate first and second digits and add them to the output.
      var quotient = Math.floor(scaledVal / EXTENDED_MAP_LENGTH);
      var remainder = scaledVal - EXTENDED_MAP_LENGTH * quotient;
      chartData += EXTENDED_MAP.charAt(quotient) + EXTENDED_MAP.charAt(remainder);
    }
  }

  return chartData;
}

Чтобы закодировать данные, вызовите функцию simpleEncode или extendedEncode , передав массив, содержащий ваши данные ( valueArray ), и максимальное значение ваших данных ( maxValue ). Чтобы создать некоторое пространство между самым высоким значением и верхней частью диаграммы, установите maxValue больше, чем наибольшее число в массиве данных, следующим образом:

var valueArray = new Array(0,1,4,4,6,11,14,17,23,28,33,36,43,59,65);
var maxValue = 70;
simpleEncode(valueArray, maxValue);

Вернуться наверх