D3 para impacientes

Capítulo 1. Introducción Introducción

Este trabajo se ha traducido utilizando IA. Agradecemos tus opiniones y comentarios: [e-mail]

D3.js (o simplemente D3, por Data-Driven Documents) es una biblioteca de JavaScript para manipular el árbol del Modelo de Objetos del Documento (DOM) con el fin de representar información visualmente. Se ha convertido en un estándar de facto para los gráficos de información en la web.

A pesar de su popularidad, D3 tiene fama de tener una curva de aprendizaje pronunciada. No creo que esto se deba a que D3 sea complicado (no lo es), y ni siquiera a que tenga una gran API (la tiene, pero la API está bien estructurada y extremadamente bien diseñada), sino que creo que muchas de las dificultades que experimentan los nuevos usuarios se deben a suposiciones incorrectas. Dado que D3 se utiliza para crear algunos gráficos impresionantes, es fácil -incluso natural- considerarlo como una "biblioteca gráfica" que facilita el manejo de primitivas gráficas y proporciona soporte de alto nivel para tipos de trazado comunes. Al acercarse a D3 con esta expectativa, el nuevo usuario se sorprende desagradablemente de la verbosidad necesaria para establecer algo tan elemental como el color de un elemento, y ¿qué es eso de la "selección"? ¿Por qué no puedo obtener simplemente un elemento similar a un lienzo y ya está?

El error aquí es que D3 no es una biblioteca de gráficos: en su lugar, ¡es una biblioteca JavaScript para manipular el árbol DOM! Sus bloques de construcción básicos no son círculos y rectángulos, sino nodos y elementos DOM; y la actividad típica no consiste en pintar una forma gráfica en un lienzo, sino en estilizar un elemento mediante atributos. La "ubicación actual" no se da tanto mediante una coordenada xy en un lienzo, sino mediante una selección de nodos en un árbol DOM.

Esto nos lleva a lo que creo que es el segundo gran reto para muchos usuarios nuevos: D3 es una tecnología web, y se basa en una colección de otras tecnologías web: la API DOM y el modelo de eventos, los selectores y propiedades de las Hojas de Estilo en Cascada (CSS), el modelo de objetos JavaScript y, por supuesto, los Gráficos Vectoriales Escalables (SVG). En muchos casos, D3 sólo proporciona una capa relativamente fina alrededor de estas tecnologías, y su propio diseño refleja con frecuencia las API subyacentes. Esto hace que el entorno sea amplio y algo heterogéneo. Si ya estás familiarizado con la pila completa de tecnologías web modernas que se conoce como HTML5, te sentirás como en casa, pero si no estás familiarizado con ellas, la falta de una capa de abstracción distinta y unificada puede resultar muy confusa.

Afortunadamente, no necesitas estudiar a fondo todas estas tecnologías subyacentes: D3 las hace más fáciles de usar y proporciona una cantidad considerable de unificación y abstracción sobre ellas. La única área en la que definitivamente no basta con "improvisar" es SVG. Debes tener un conocimiento adecuado de SVG, no sólo de sus elementos de representación, sino también de los elementos estructurales que controlan cómo se organiza la información dentro de un gráfico. He intentado reunir la información necesaria en el Apéndice B. Si no estás familiarizado con SVG, te sugiero que leas este apéndice antes de leer el resto del libro: ¡te alegrarás de haberlo hecho!

A quién va dirigido este libro

Este libro está dirigido a programadores y científicos que quieran añadir D3 a su caja de herramientas. Asumo que eres razonablemente competente como programador y que te sientes cómodo trabajando con datos y gráficos. Al mismo tiempo, no espero que tengas más que un conocimiento superficial del desarrollo web profesional contemporáneo.

Esto es lo que ya deberías tener:

• Conocimiento de al menos uno o dos lenguajes de programación (pero no necesariamente JavaScript), y confianza para aprender la sintaxis de un nuevo lenguaje a partir de su referencia lingüística.

• Familiaridad con los conceptos contemporáneos de programación; es decir, no sólo bucles, condicionales y estructuras de datos comunes, sino también cierres y funciones de orden superior.

• Conocimientos básicos de XML y de la estructura jerárquica que impone a los documentos. Espero que conozcas el DOM y cómo trata los elementos de una página web como nodos de un árbol, pero no asumo que estés familiarizado con la API DOM original ni con ninguno de sus sustitutos modernos (como jQuery).

• Exposición a HTML y CSS sencillos (deberías ser capaz de reconocer y utilizar las etiquetas <body> y <p>, etc.), así como cierta familiaridad con la sintaxis y los mecanismos de CSS.

Pero, en particular, el lector que tengo en mente es impaciente: competente y capaz, pero frustrado por intentos anteriores de envolver su cabeza en D3. Si esto describe tu situación, ¡este libro es para ti!

¿Por qué D3?

¿Por qué debería interesar D3 a programadores y científicos o, de hecho, a cualquiera que no sea principalmente un desarrollador web? Destacan las siguientes razones:

• D3 proporciona una forma cómoda de publicar gráficos en a través de la web. Si trabajas con datos y visualizaciones, conoces el procedimiento: creas tus figuras en el programa de trazado de tu elección, luego guardas los resultados como PNG o PDF, y después creas una página web con etiquetas<img>, para que otras personas puedan ver tu trabajo. ¿No estaría bien que pudieras crear y publicar tus figuras en un solo paso?

• Y lo que es más importante, D3 hace que sea fácil y cómodo crear gráficos animadose interactivos. Nunca se insistirá lo suficiente en este punto: la visualización científica tiene tanto que beneficiarse de la animación y la interactividad como cualquier otro campo, pero en el pasado este objetivo ha sido notoriamente difícil de alcanzar. A menudo requería tecnologías intrincadas y poco adecuadas (¿has probado alguna vez a programar con Xlib?) o paquetes comerciales especializados y a menudo caros. D3 te permite dejar atrás estos retos y te sitúa en la actualidad para tus necesidades de visualización.

• Gráficos aparte, D3 es un marco de trabajo accesible, fácil de aprender y de usar para la manipulación del DOM con fines generales. Si tienes la necesidad ocasional de manipular el DOM, entonces D3 puede ser todo lo que necesites, sin la obligación de dominar todos los demás marcos y API para la programación web. El diseño de la propia biblioteca también es interesante como modelo por las facilidades que proporciona "out of the box" para manejar tareas comunes de manipulación y visualización de datos.

Pero, sobre todo, creo que D3 es una tecnología facilitadora que, en general, amplía la gama de soluciones disponibles para sus usuarios. Las aplicaciones más interesantes de D3 son posiblemente las que aún no se han inventado.

Qué contiene este libro

Este libro trata de ser una introducción completa, aunque concisa, a D3, cubriendo la mayoría de las partes principales de la funcionalidad con suficiente profundidad.

• Trata de ser un recurso cómodo y único, incluyendo tanto documentación de referencia de la API como información de fondo sobre temas auxiliares que pueden no resultar familiares al lector típico (como SVG, JavaScript y el DOM, pero también los espacios de color o el elemento HTML Canvas).

• El libro hace hincapié en los mecanismos y conceptos de diseño, más que en recetas prefabricadas. Se parte del supuesto de que los lectores querrán aprender D3 con la suficiente profundidad como para poder aplicarlo a sus propios fines, posiblemente novedosos e imprevistos.

Básicamente, ¡la esperanza es que este libro te prepare para hacer cosas con D3 que a mí nunca se me habrían ocurrido!

... y lo que no lo es

Este libro se limita intencionadamente sólo a D3, sus capacidades y mecanismos. Esto implica una serie de omisiones:

• No hay estudios de casos extensos ni recetas tipo libro de cocina

• No hay introducción al análisis de datos, la estadística o el diseño visual

• No se mencionan otros frameworks de JavaScript aparte de D3

• No hay debate sobre el desarrollo web contemporáneo en general

Me gustaría hacer hincapié en los dos últimos puntos. Este libro trata estrictamente sólo de D3, sin ninguna referencia ni dependencia de otros marcos o bibliotecas de JavaScript. Esto es bastante intencionado: quería hacer accesible D3 también a aquellos lectores que no estén familiarizados o se sientan incómodos con el rico pero heterogéneo ecosistema de JavaScript. Por la misma razón, este libro no trata otros temas del desarrollo web contemporáneo. En particular,no encontrarásningún debate sobre la compatibilidad de los navegadores y temas relacionados. Se asume que, en general, utilizas un navegador moderno, actualizado y compatible con JavaScript, capaz de procesar SVG.¹

Otra omisión se refiere a la compatibilidad de D3 con la información geográfica y geoespacial. Aunque importante, este tema parece lo suficientemente bien contenido como para que no resulte demasiado difícil aprenderlo de la Documentación de Referencia D3 una vez que se tengan claros los fundamentos de D3.

Cómo leer este libro

Este libro presenta una narrativa continua y progresiva, con nuevo material introducido sistemáticamente de capítulo en capítulo. Dicho esto, los últimos capítulos en particular pueden leerse en cualquier orden después de haber sentado las bases necesarias en la primera mitad del libro. He aquí mi hoja de ruta sugerida:

1. A menos que ya tengas una base sólida en SVG, te recomiendo encarecidamente que leas el Apéndice B. Sin estos conocimientos, nada de lo demás tendrá mucho sentido.

2. Todos deben leer el Capítulo 2 como calentamiento tutorial y para establecer expectativas sobre los temas que se van a tratar.

3. El capítulo 3 es de lectura obligatoria. Las selecciones son el principal concepto organizativo de D3. Las selecciones no sólo representan un asidero en el árbol DOM, sino que también gestionan la asociación entre los elementos DOM y el conjunto de datos. Prácticamente todos los programas D3 comienzan tomando una selección, y comprenderlas y sus capacidades es obligatorio cuando se trabaja con D3.

4. Estrictamente hablando, el Capítulo 4 sobre manejo de eventos, interactividad y animaciones es opcional. Pero como éstas son algunas de las capacidades más interesantes que ofrece D3, sería una pena saltárselo.

5. El capítulo 5 es importante porque explica algunos conceptos fundamentales del diseño D3 (como los componentes y los diseños) e introduce técnicas generalmente útiles (como las transformaciones SVG y los componentes personalizados).

6. Los capítulos restantes pueden leerse en gran medida en cualquier orden, a medida que surja la necesidad de ese tema concreto. En particular, me gustaría llamar la atención sobre el Capítulo 7 y su detallada descripción de los discretos pero extremadamente versátiles objetos de escala, y sobre la variedad de funciones para el manejo de matrices en el Capítulo 10.

Convenios

Esta sección explica algunas convenciones específicas utilizadas en el resto de este libro.

Convenciones de la API D3

La API D3 utiliza algunas convenciones uniformes que mejoran enormemente su usabilidad. Algunas de ellas son modismos comunes de JavaScript y no son específicas de D3, pero pueden no resultar familiares a los programadores que no utilizan JavaScript. Al establecerlas explícitamente en un lugar, las discusiones posteriores no necesitan estar abarrotadas de información redundante.

• D3 es principalmente una capa de acceso al árbol DOM. Por regla general, D3 no intenta encapsular las tecnologías subyacentes y, en su lugar, proporciona manejos convenientes, aunque genéricos, sobre ellas. Por ejemplo, D3 no introduce abstracciones propias de "círculo" o "rectángulo", sino que da al programador acceso directo a las facilidades SVG para crear formas gráficas. La ventaja de este enfoque es que D3 es tremendamente adaptable y no está atado a una tecnología o versión concreta. La desventaja es que los programadores necesitan tener conocimientos de las tecnologías subyacentes, además de D3, ya que el propio D3 no proporciona una capa de abstracción completa.

• Como JavaScript no impone firmas de función formales, todos los argumentos de función son técnicamente opcionales. Muchas funciones D3 utilizan el siguiente lenguaje: cuando se invocan con los argumentos adecuados, estas funciones actúan como definidores de (fijando la propiedad correspondiente al valor suministrado); cuando se invocan sin argumentos, estas funciones actúan como captadores de (devolviendo el valor actual de la propiedad). Paraeliminar por completo una propiedad, llama al definidor correspondiente y proporciona nullcomo argumento.

• Cuando se invocan como definidores, las funciones suelen devolver una referencia al objeto actual, lo que permite encadenar métodos. (Este modismo es tan intuitivo y coherente que rara vez se volverá a mencionar explícitamente).

• En lugar de un valor, muchos establecedores D3 pueden tomar como argumento una función accesoria, de la que se espera que devuelva un valor que se utilizará para establecer la propiedad en cuestión. Los parámetros esperados por las funciones accesorias no son los mismos en todo D3, pero un conjunto de funciones D3 relacionadas siempre llamará a las funciones accesorias de manera uniforme. Los detalles de los argumentos de los accesorios se documentan con las respectivas funciones D3.

• Algunas facilidades importantes de D3 se implementan como objetos de función. Realizan su tarea principal cuando se les llama como función, pero también son objetos, con funciones miembro y estado interno (ejemplos sonlos objetos de escala, ver Capítulo 7; ylos generadores y componentes, ver Capítulo 5). Es un patrón común instanciar un objeto de este tipo, configurarlo utilizando sus funciones miembro y, finalmente, invocarlo para completar su propósito. Con frecuencia, la invocación final no utiliza la sintaxis explícita de llamada a función, sino que emplea uno de los métodos de JavaScript para llamadas a función "sintéticas": el objeto función se pasa a otra función (como call()), que suministra los argumentos necesarios y, finalmente, evalúa el propio objeto función.

Convenciones para las Tablas de Referencia API

A lo largo del libro, encontrarás tablas que muestran partes de la API D3 en un formato de referencia. Las entradas de estas tablas están ordenadas por relevancia, manteniendo juntas las funciones relacionadas.

• Las funciones D3 se invocan o bien en el objeto global d3, o bien como funciones miembro de algún objeto D3; algunas funciones están disponibles de ambas formas. Si se llama a una función a través de un objeto, este objeto se denomina receptor de la llamada al método. Dentro de la función miembro, el receptor es el objeto apuntado por la variable this.

• Todas las tablas de referencia de la API indican el tipo de receptor en la leyenda. Las tablas no hacen referencia explícita al prototipo del objeto.

• Las firmas de las funciones intentan indicar el tipo de cada argumento, pero muchas funciones aceptan tal variedad de tipos de argumentos diferentes que no resulta práctica una notación unívoca. Lee la descripción textual para conocer todos los detalles. Cuando se utilizan, los corchetes indican una matriz. Los argumentos opcionales de las funciones no se indican explícitamente.

Convenciones para los ejemplos de código

Los ejemplos de código están pensados para demostrar las características y mecanismos de D3. Con el fin de resaltar sus puntos respectivos con la mayor claridad, los ejemplos se reducen a lo esencial. He prescindido de la mayoría de las "sutilezas", como colores agradables o conjuntos de datos semánticamente interesantes. Los colores suelen ser primarios, y la mayoría de los conjuntos de datos son pequeños y sencillos.

Por otra parte, cada ejemplo es completo en sí mismo, puede ejecutarse tal cual y creará el gráfico asociado. Salvo contadas excepciones, no muestro fragmentos de código. He descubierto que es mejor mostrar ejemplos sencillos en su totalidad, en lugar de mostrar sólo los "fragmentos interesantes" de un ejemplo más largo; de este modo, no hay peligro de que se pierda el contexto general. Todo es ejecutable y está listo para ser ampliado y embellecido a voluntad.

Convenciones de denominación

Los ejemplos utilizan las siguientes convenciones de nomenclatura para las variables:

• Siglas de primera letra para objetos individuales: c para "círculo",p para punto, etc. Añade una "s" para las colecciones: cs será una matriz de círculos, ps una matriz de puntos.

• Las cantidades que aparecen con frecuencia tienen su propia notación: los píxeles se denotan con px, los objetos de escala con sc. Los generadores y componentes son objetos de función que "hacen" algo y por eso se denominan mkr.

• La letra d se utiliza genéricamente para indicar "lo actual" en funciones anónimas. Cuando se trabaja con selecciones D3, d suele ser un punto de datos individual vinculado a un elemento DOM; cuando se trabaja con matrices, d es un elemento de matriz (como en ds.map( d => +d )).

• Los conjuntos de datos se denominan data o ds.

• Las selecciones que representan un elemento <svg> o <g> son comunes y, cuando se asignan a una variable, se denotan como svg o g.

Organización del archivo fuente

A partir del capítulo 3, adopto una convención según la cual, para cada listado de código, se espera que la página ya contenga un elemento <svg> con un único id y con los atributos width y height correctamente configurados. A continuación, el código de ejemplo selecciona este elemento SVG por su atributo id y, a menudo, asigna esta selección a una variable para futuras referencias:

var svg = d3.select( "#fig" );

Esto evita la ambigüedad de utilizar un selector más general (comod3.select( "svg" )) y facilita la inclusión de varios ejemplos en una sola página HTML.

A cada gráfico le corresponde una función JavaScript que crea dinámicamente los elementos SVG que componen la figura. Por convención, los nombres de las funciones comienzan por make... y continúan con el valor del atributo id del elemento SVG de destino.

Con la excepción de los ejemplos del capítulo 2, hay una página HTML y un archivo JavaScript por capítulo. (Salvo raras excepciones, no incluyo código JavaScript en una página HTML directamente).

Plataforma, JavaScript y navegador

Para ejecutar los ejemplos, necesitas un servidor web local o alojado (véase el Apéndice A). Los ejemplos deberían funcionar en cualquier navegador contemporáneo compatible con JavaScript. Actualmente existen varias versiones de JavaScript.² Salvo tres excepciones, los ejemplos de código sólo utilizan JavaScript "clásico" (ES5, publicado en 2009/2011) sin ningún otro marco o biblioteca. Las tres funciones que requieren una versión más reciente de JavaScript (ES6, publicada en 2015) son:

• La notación concisa de flecha gorda para funciones anónimas (véaseel Apéndice C), que se utiliza en todos los ejemplos.

• Asignación de desestructuración ([a, b] = [b, a]), que se utiliza en algunos lugares.

• Varios ejemplos acceden a recursos remotos utilizando envoltorios D3 para la API Fetch (ver Capítulo 6); éstos dependen del objeto JavaScriptPromise.

¹ Esto está en el espíritu del propio D3. Como afirma el sitio web de D3 "D3 no es una capa de compatibilidad, así que si tu navegador no soporta los estándares, no tienes suerte"(https://github.com/d3/d3/wiki).

² Véase https://en.wikipedia.org/wiki/ECMAScript.