Форматы дат и чисел

Работа с временными данными в Kepler.gl опирается на строгую интерпретацию входных значений, поскольку временные поля используются в фильтрах, анимации и агрегации. Основная сложность заключается в том, что библиотека не навязывает единый формат хранения даты, а поддерживает несколько распространённых представлений, приводя их к внутреннему унифицированному виду.

Поддерживаемые форматы входных дат

На уровне подготовки данных чаще всего встречаются три варианта:

1. ISO-строки

2026-06-14
2026-06-14T12:30:00Z
2026-06-14T12:30:00+06:00

ISO-формат является предпочтительным, поскольку он однозначен и не зависит от локали.

2. Unix timestamp

1718366400        // секунды
1718366400000     // миллисекунды

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

3. Строковые локализованные даты

14.06.2026
06/14/2026

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

Внутреннее преобразование времени

При загрузке данных Kepler.gl стремится привести временные значения к числовому timestamp (обычно в миллисекундах). Это позволяет:

  • унифицировать работу фильтров времени
  • ускорить сравнения и сортировки
  • обеспечить совместимость с deck.gl слоями

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

  1. Определение типа входного значения
  2. Парсинг строки или числа
  3. Нормализация в UTC
  4. Приведение к timestamp

В результате любой временной столбец внутри состояния приложения становится числовым полем.

Настройка временного поля в конфигурации слоя

В Kepler.gl тип поля задаётся в visState. Временные поля помечаются как timestamp или date.

const config = {
  visState: {
    layers: [
      {
        id: 'trips',
        type: 'line',
        config: {
          dataId: 'my_data',
          columns: {
            lat0: 'start_lat',
            lng0: 'start_lng',
            lat1: 'end_lat',
            lng1: 'end_lng'
          },
          columnFormat: {
            timestamp: 'YYYY-MM-DD HH:mm:ss'
          }
        }
      }
    ]
  }
};

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

Форматы чисел и их отображение

Числовые данные в Kepler.gl разделяются на две категории:

  • геометрические значения (координаты, радиусы, высоты)
  • агрегированные показатели (суммы, средние, плотности)

Внутреннее хранение чисел

Все числовые поля приводятся к типу Number JavaScript. Это означает:

  • отсутствие разделителей тысяч
  • использование точки как десятичного разделителя
  • отсутствие локализации на уровне хранения

Форматирование чисел для отображения

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

Примеры распространённых форматов:

Обычное число

12345 → 12,345

Десятичное значение

12345.678 → 12,345.68

Сокращённый формат

1200000 → 1.2M

Настройка форматирования чисел

Формат чисел может задаваться через конфигурацию слоя или через глобальные настройки визуализации:

const formatOptions = {
  numberFormat: {
    format: '0,0.00',
    trimmed: true
  }
};

Здесь используются правила, аналогичные библиотекам форматирования чисел (например, через d3-format-подобный синтаксис):

  • 0,0 — разделение тысяч
  • .00 — фиксированное число знаков после запятой
  • trimmed — удаление незначащих нулей

Локализация числовых и временных значений

Kepler.gl поддерживает локализацию отображения данных, однако важно разделять:

  • локализацию отображения
  • внутреннее представление данных

Локаль чисел

Локаль влияет на:

  • разделитель тысяч
  • десятичный разделитель
  • формат сокращений

Примеры:

Локаль Число Отображение
en-US 12345.67 12,345.67
de-DE 12345.67 12.345,67

Локаль дат

Формат отображения дат зависит от:

  • порядка день/месяц/год
  • формата времени (24h / 12h)
  • наличия секунд

Примеры:

  • 2026-06-14T18:00:00Z → 14.06.2026, 18:00
  • 2026-06-14T18:00:00Z → 06/14/2026 6:00 PM

Форматы дат в фильтрах времени

Фильтры времени в Kepler.gl работают только с числовыми timestamp-значениями, но отображают их в удобочитаемом виде.

TimeRangeFilter

Фильтр диапазона времени оперирует минимальным и максимальным значениями:

{
  id: 'time_filter',
  dataId: ['my_data'],
  type: 'timeRange',
  fieldIdx: 2,
  value: [1718300000000, 1718400000000]
}

Внутри:

  • значения всегда в миллисекундах
  • сравнение происходит численно
  • отображение преобразуется через форматтер

TimeColumn формат

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

{
  name: 'timestamp',
  type: 'timestamp'
}

Типизация влияет на:

  • доступность фильтрации
  • отображение в UI
  • выбор шкалы времени

Анимация времени и интерполяция

Kepler.gl поддерживает временную анимацию, где ключевую роль играет равномерное распределение timestamp.

Принцип работы

  1. берётся временной диапазон
  2. разбивается на шаги
  3. каждый шаг соответствует моменту времени
  4. данные рендерятся в соответствии с текущим шагом

Влияние формата данных на анимацию

Если данные не нормализованы (например, строки вместо чисел), возможны проблемы:

  • пропуски кадров
  • некорректная сортировка
  • невозможность построения интерполяции

Поэтому обязательным этапом является приведение всех дат к timestamp.

Числовые форматы в слоях визуализации

Разные слои Kepler.gl используют числа по-разному:

ScatterplotLayer

  • радиус точки
  • цветовое кодирование
  • плотность распределения

LineLayer

  • длина сегментов
  • высота (3D-режим)
  • вес линии

HexagonLayer

  • агрегация значений
  • вычисление плотности
  • нормализация чисел внутри ячеек

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

Влияние форматов на агрегацию данных

Kepler.gl выполняет агрегацию на этапе подготовки данных для рендера.

Пример агрегации

value: 10
value: 20
value: 30
→ average: 20

Ошибки в формате чисел (например, строки "10" вместо 10) могут привести к:

  • некорректным суммам
  • ошибкам сортировки
  • пропуску значений

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

Строковые числа

"1000" + "2000" → "10002000"

Решение — явное приведение:

Number(value)
parseFloat(value)

Неоднозначные даты

01/02/2026

Интерпретация зависит от локали:

  • США: 1 февраля
  • Европа: 2 января

Рекомендуемое решение — ISO 8601.

Несоответствие timestamp единиц

1718366400    // секунды
1718366400000 // миллисекунды

Ошибочное использование приводит к смещению дат на десятки лет. В Kepler.gl важно стандартизировать миллисекунды.

Взаимодействие форматов с визуальными настройками

Форматы чисел и дат напрямую влияют на:

  • tooltip отображение
  • legend панели
  • фильтры
  • временную анимацию
  • экспорт данных

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

Роль форматтеров в архитектуре Kepler.gl

Форматирование реализовано как слой абстракции между данными и UI:

  • data processing layer — чистые числа и timestamp
  • formatter layer — преобразование в строки
  • UI layer — отображение пользователю

Такое разделение обеспечивает:

  • предсказуемость вычислений
  • независимость от локали
  • стабильность визуализации
Оглавление