Типы данных

В основе Kepler.gl лежит строго табличная модель представления информации, где каждый набор данных рассматривается как совокупность строк и столбцов. Такая структура обеспечивает универсальность: независимо от источника (CSV, JSON, API), данные приводятся к единому формату перед визуализацией.

Типичный dataset в Kepler.gl описывается объектом вида:

const dataset = {
  data: {
    fields: [
      { name: 'latitude', type: 'real' },
      { name: 'longitude', type: 'real' },
      { name: 'timestamp', type: 'timestamp' },
      { name: 'category', type: 'string' }
    ],
    rows: [
      [51.5074, -0.1278, 1680000000000, 'A'],
      [48.8566, 2.3522, 1680003600000, 'B']
    ]
  }
};

Каждая строка соответствует одному объекту в пространстве данных, а каждый столбец — конкретному признаку, используемому слоями визуализации.

Система типов полей (fields)

Kepler.gl строго различает типы данных, поскольку от этого зависит способ интерпретации значений в слоях (layers), фильтрах и агрегациях.

Поле описывается структурой:

{
  name: 'field_name',
  type: 'real' | 'integer' | 'timestamp' | 'string' | 'boolean'
}

Типизация определяет:

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

Числовые типы данных

real и integer

Числовые типы используются в большинстве визуальных слоёв: scatterplot, heatmap, hexagon, arc.

  • integer — целые значения, часто счётчики, идентификаторы, индексы
  • real — числа с плавающей точкой, координаты, измерения, метрики

Пример:

{
  name: 'speed',
  type: 'real'
},
{
  name: 'count',
  type: 'integer'
}

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

Временные данные (timestamp)

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

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

В Kepler.gl временные значения обычно представлены в формате UNIX epoch (миллисекунды).

Использование:

  • анимация движения объектов
  • фильтрация по временным диапазонам
  • построение trip layers
  • анализ временных рядов

Пример данных:

[51.5, -0.12, 1680000000000]

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

Строковые и категориальные данные

Тип string используется для описания категорий, идентификаторов и меток.

{
  name: 'city',
  type: 'string'
}

Особенности:

  • не участвуют в математических операциях
  • используются для группировки
  • применяются в color mapping (categorical color scales)
  • важны для легенд и фильтров

Пример применения:

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

Булевы значения

Тип boolean используется реже, но играет роль в фильтрации и бинарной классификации.

{
  name: 'is_active',
  type: 'boolean'
}

Внутренне Kepler.gl рассматривает их как категориальные значения с двумя состояниями.

Географические координаты как особый случай

Хотя Kepler.gl не выделяет отдельный тип geo, координаты являются фундаментальным элементом всех пространственных слоёв.

Обычно используются два поля:

  • latitude
  • longitude
[
  55.7558,
  37.6173
]

Важно, что:

  • широта и долгота должны быть числовыми (real)

  • порядок строго соблюдается

  • допустимый диапазон обязателен:

    • latitude: -90 до 90
    • longitude: -180 до 180

Ошибки в диапазоне приводят к исчезновению объектов на карте.

GeoJSON как альтернативная структура данных

Kepler.gl поддерживает GeoJSON как отдельный формат географических данных.

Пример объекта:

const geojson = {
  type: "FeatureCollection",
  features: [
    {
      type: "Feature",
      geometry: {
        type: "Point",
        coordinates: [37.6173, 55.7558]
      },
      properties: {
        name: "Moscow"
      }
    }
  ]
};

Особенности GeoJSON:

  • поддержка сложных геометрий (Polygon, LineString, MultiPolygon)
  • вложенные свойства
  • использование в layers типа Geojson Layer

GeoJSON применяется там, где табличная модель недостаточна.

Trip data и временные маршруты

Trip layer требует специфической структуры, где маршрут описывается последовательностью координат с временными метками.

Пример:

[
  {
    route: [
      [37.6, 55.7, 1680000000000],
      [37.7, 55.8, 1680003600000]
    ]
  }
]

Особенности:

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

Trip data фактически объединяет географические и временные типы в одной структуре.

Hexagon и агрегируемые данные

Hexagon layer не требует специального формата, но критически зависит от числовых координат.

Входные данные:

[
  { lat: 55.75, lng: 37.61 },
  { lat: 55.76, lng: 37.62 }
]

или табличный формат:

[
  [55.75, 37.61],
  [55.76, 37.62]
]

Далее Kepler.gl выполняет пространственную агрегацию, преобразуя точки в гексагональную сетку.

Форматы хранения данных внутри Kepler.gl

Kepler.gl поддерживает несколько внутренних представлений dataset:

1. Rows-based format

rows: [
  [value1, value2],
  [value1, value2]
]

Используется для компактности и быстрого доступа по индексам.

2. Object-based format (preprocessed)

rows: [
  { lat: 55.7, lng: 37.6 },
  { lat: 55.8, lng: 37.7 }
]

Используется при загрузке из JSON.

3. Columns-based format

{
  columns: {
    lat: [55.7, 55.8],
    lng: [37.6, 37.7]
  }
}

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

Нормализация данных перед загрузкой

Перед передачей данных в Kepler.gl выполняется обязательная нормализация:

  • приведение координат к числам
  • преобразование дат в timestamp
  • удаление null или NaN значений
  • унификация структуры строк

Пример преобразования:

const normalized = raw.map(d => ({
  lat: Number(d.lat),
  lng: Number(d.lng),
  time: new Date(d.time).getTime()
}));

Приведение типов и автоматическое определение

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

Правила:

  • если значение можно интерпретировать как число → real или integer
  • если строка похожа на дату → timestamp
  • если два числовых поля подряд → координаты

Ошибочная типизация приводит к:

  • отсутствию отображения слоя
  • неправильной фильтрации
  • невозможности анимации

Проблемы несовместимости типов

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

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

"55.75" // вместо 55.75

→ ломает spatial layers

ISO-строки без конвертации

"2024-01-01T00:00:00Z"

→ требует преобразования в timestamp

Перепутанные координаты

[lng, lat] // вместо [lat, lng]

→ приводит к смещению объектов на карте

Структурные паттерны dataset в Kepler.gl

Базовый геодатасет

{
  fields: [
    { name: 'lat', type: 'real' },
    { name: 'lng', type: 'real' }
  ],
  rows: [...]
}

Временной датасет

{
  fields: [
    { name: 'lat', type: 'real' },
    { name: 'lng', type: 'real' },
    { name: 'time', type: 'timestamp' }
  ]
}

Категориально-временной датасет

{
  fields: [
    { name: 'lat', type: 'real' },
    { name: 'lng', type: 'real' },
    { name: 'type', type: 'string' },
    { name: 'time', type: 'timestamp' }
  ]
}

Аггрегируемый датасет

{
  fields: [
    { name: 'lat', type: 'real' },
    { name: 'lng', type: 'real' },
    { name: 'value', type: 'integer' }
  ]
}

Роль типов данных в визуальных слоях

Каждый слой Kepler.gl интерпретирует типы по-своему:

  • Point layer — координаты + категориальные данные
  • Heatmap layer — числовая плотность
  • Arc layer — пары координат + вес
  • Trip layer — координаты + timestamp
  • Hexagon layer — агрегация числовых точек

Тип данных напрямую определяет визуальное поведение, масштабирование и возможность анимации.

Оглавление