Компонент ChoroplethMap

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

Характерная особенность choropleth-карт заключается в том, что значение отображается не точкой или линией, а заливкой территории. Это делает компонент особенно подходящим для аналитики плотности, сравнительных показателей и агрегированных метрик.

ChoroplethMap работает на пересечении двух источников данных:

  • геометрия территорий (GeoJSON FeatureCollection)
  • числовые значения по ключу (data array)

Базовая структура данных:

const data = [
  { id: 'FRA', value: 123 },
  { id: 'DEU', value: 98 },
  { id: 'USA', value: 210 }
]

GeoJSON содержит объекты:

{
  "type": "Feature",
  "properties": {
    "id": "FRA",
    "name": "France"
  },
  "geometry": {
    "type": "Polygon",
    "coordinates": [...]
  }
}

Ключевым моментом является совпадение идентификатора id в данных и properties.id в GeoJSON. Именно через это соответствие происходит окрашивание.

Базовая конфигурация ChoroplethMap

Компонент импортируется из geo-набора:

import { Choropleth } from '@nivo/geo'
import worldCountries from './world_countries.json'

Простейшая конфигурация:

<Choropleth
  data={data}
  features={worldCountries.features}
  margin={{ top: 0, right: 0, bottom: 0, left: 0 }}
  colors="nivo"
  domain={[0, 300]}
  unknownColor="#666666"
  label="properties.name"
/>

Основные параметры:

  • data — числовые значения
  • features — GeoJSON
  • domain — диапазон значений
  • colors — палитра
  • unknownColor — цвет для отсутствующих данных

Маппинг данных и механизм join

Внутренний процесс основан на join-операции:

  1. обход всех features GeoJSON
  2. поиск соответствующего элемента в data по id
  3. присвоение значения feature
  4. вычисление цвета через шкалу

Если значение отсутствует, используется unknownColor.

Особое значение имеет стабильность ключей. Несовпадение форматов (например, ISO3 vs ISO2) приводит к разрыву визуализации.

Цветовые шкалы и домены

ChoroplethMap поддерживает различные типы цветовых интерполяций:

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

domain={[0, 500]}
colors={['#e0f3db', '#43a2ca', '#0868ac']}

Значения интерполируются между точками шкалы.

Предустановленные палитры

colors="blues"
colors="greens"
colors="reds"
colors="nivo"

Палитры оптимизированы для восприятия градиентов в аналитике.

Квантильная интерпретация

Часто используется нормализация данных до диапазона:

  • min-max scaling
  • percentiles
  • log scaling

Это особенно важно при сильной асимметрии значений.

Подписи и отображение информации

Параметр label управляет тем, какие данные отображаются внутри области:

label="properties.name"

Можно использовать вложенные свойства GeoJSON. Однако при высокой плотности регионов подписи часто отключаются для сохранения читаемости.

Tooltip и интерактивность

Tooltip формируется динамически на основе feature:

tooltip={({ feature }) => {
  return (
    <div>
      <strong>{feature.properties.name}</strong>
      <div>{feature.value ?? 'no data'}</div>
    </div>
  )
}}

Возможные сценарии:

  • отображение абсолютных значений
  • показ процентов
  • сравнение с медианой
  • вывод дополнительной метаинформации

Стилизация и тематизация

ChoroplethMap интегрируется с системой theme:

theme={{
  tooltip: {
    container: {
      background: '#222',
      color: '#fff',
      fontSize: 12
    }
  },
  labels: {
    text: {
      fontSize: 10,
      fill: '#333'
    }
  }
}}

Ключевые зоны кастомизации:

  • tooltip
  • labels
  • legends
  • axis (если комбинированные визуализации)

Легенды и интерпретация шкалы

Легенда критична для понимания распределения значений.

legends={[
  {
    anchor: 'bottom-left',
    direction: 'column',
    translateX: 20,
    itemWidth: 80,
    itemHeight: 14,
    symbolShape: 'square'
  }
]}

Типы легенд:

  • дискретная (bins)
  • непрерывная (gradient)
  • пороговая (threshold-based)

Для choropleth чаще используется непрерывная шкала.

Географические проекции

Компонент поддерживает различные projection-модели:

  • Mercator (дефолтная)
  • Natural Earth
  • Orthographic
  • Equal Earth

Настройка:

projectionType="mercator"
projectionScale={100}
projectionTranslation={[0.5, 0.5]}

Выбор проекции влияет на:

  • искажение площадей
  • визуальную плотность
  • восприятие распределений

Производительность и оптимизация

ChoroplethMap может работать с крупными GeoJSON-файлами, однако производительность зависит от:

  • количества features
  • сложности геометрии
  • частоты re-render React
  • вычислений цветовой шкалы

Практические оптимизации:

  • мемоизация data и features
  • упрощение GeoJSON (topojson simplification)
  • отключение анимаций
  • использование static layers

Пользовательские слои (custom layers)

Архитектура Nivo позволяет добавлять слои поверх карты:

layers={[
  'features',
  'legends',
  props => {
    return (
      <g>
        <circle cx={100} cy={100} r={10} fill="red" />
      </g>
    )
  }
]}

Слои могут использоваться для:

  • выделения регионов
  • добавления маркеров
  • наложения сеток
  • кастомной аналитики

Работа с отсутствующими данными

Частый сценарий — неполные датасеты.

Поведение контролируется через:

unknownColor="#ccc"

Дополнительно возможна фильтрация:

  • исключение features без данных
  • заполнение нулями
  • интерполяция по соседним регионам (внешняя логика)

Взаимодействие с событиями

ChoroplethMap поддерживает события:

onCl ick={(feature) => {
  console.log(feature.id)
}}

onMouseEn ter={(feature) => {
  console.log(feature.properties.name)
}}

Типичные сценарии:

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

Интеграция в аналитические панели

ChoroplethMap часто используется как центральный компонент dashboard-композиций:

  • карта + bar chart
  • карта + time series
  • карта + scatter plot

Синхронизация осуществляется через shared state:

  • выбранный регион
  • диапазон значений
  • временной фильтр

Типовые ошибки интеграции

Наиболее частые проблемы:

Несовпадение идентификаторов:

  • ISO2 vs ISO3
  • числовые коды vs строки

Несоответствие GeoJSON:

  • отсутствующие properties.id
  • вложенные структуры без flattening

Перегрузка геометрии:

  • слишком детализированные полигоны
  • отсутствие simplification

Неправильный domain:

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

Расширенные сценарии использования

ChoroplethMap применяется не только для статической аналитики:

  • временные изменения (анимация по годам)
  • сравнение двух метрик через переключение data set
  • мультислойные карты (overlay indicators)
  • кластеризация регионов по категориям

Такие сценарии требуют внешнего управления состоянием и подготовки данных вне компонента.

Оглавление