10 A Biblioteca Plotly
A biblioteca Plotly.js constitui uma ferramenta de código aberto para visualização de dados interativos em JavaScript. Criada em 2015, foi lançada pela empresa canadense homônima Plotly Inc.. A biblioteca foi originalmente idealizada para aplicações científicas e empresariais, como uma solução de contorno à limitações de interatividade de outras bibliotecas para uso na web. O principal diferencial de Plotly.js é sua habilidade para criação e manejo de gráficos e mapas diretamente em um visualizador HTML ou navegador de internet, embora sem a necessidade de renderização em servidor, e mesmo de conexão à rede. Essa habilidade decorre da incorporação da linguagem JavaScript na estrutura moderna da linguagem de marcação HTML5.
A biblioteca permite construir uma diversidade rica de gráficos (mais de 40 tipos, segundo seu mantenedor. Plotly.js é amplamente utilizada por instituições e empresas de porte, incluindo NASA, Google, Microsoft, MIT, Harvard, Johns Hopkins University, e IBM, em função de sua flexibilidade e capacidade para lidar com grandes volumes de dados interativos. Para informações detalhadas, documentação oficial e exemplos de uso, sugere-se consultar os repositórios do Plotly.js no GitHub, bem como os tutoriais e documentação disponíveis no site oficial, ou sites devotados à linguagem (ex: W3Schools.
Depois de explorar, você consegue:
- compreender para que serve a biblioteca Plotly.js e suas aplicações;
- entender como é produzido um gráfico interativo com Plotly;
- observar os tipos de gráficos e mapas produzidos com a biblioteca;
- criar gráficos e mapas com Plotly;
- editar exemplos de scripts do livro com instruções da biblioteca.
Antes de observar a riqueza gráfica e interativa que a biblioteca Plotly permite, experimente abrir um JSPlotly qualquer do livro, ou o app padrão neste LINK do site Bioquanti(). Depois, basta apagar o código-padrão (delete) e substitui-lo pelo que segue:
const dados = [{
x: [1, 2, 3, 4, 5],
y: [2, 4, 1, 5, 3],
type: `scatter` // experimente substituir por `bar`, `pie`, etc
}];
Plotly.newPlot('grafico', dados)
Plotly.js.
Um gráfico com Plotly.js é executado dentro de um container estruturado em HTML. Isso equivale dizer que o gráfico pode ser construido em qualquer editor para HTML, incluindo um simples bloco de notas, e visualizado offline em qualquer browser (navegador) moderno (ex: Google Chrome, Safari, Firefox, Opera, etc). Dessa forma, o gráfico não precisa ser compilado a partir de códigos para sua exibição, mas sim interpretado, já que a linguagem JavaScript em que se ampara a biblioteca é uma linguagem de interpretação. Nesse caso, o código-fonte para um gráfico Plotly.js é executado diretamente pelo interpretador JavaScript do navegador HTML5, como ocorre no JSPlotly.
O container HTML da estrutura do JSPlotly segue essa configuração:
divId, # 1o. argumento; identificação do gráfico na estrutura do
# container HTML (ou ID do elemento HTML)
data, # 2o. argumento: dados do gráfico ou conjunto de traços
# (trace array)
layout, # objeto de layout (ou leiaute, disposição de elementos - plano
# de fundo, títulos, legenda, margens, dimensões, intervalos)
config # objeto de configuração (controla o comportamento da interface)Assim, para a construção de um gráfico Plotly.js convencional, a estrutura envolverá a construção de cada trecho de argumentos (ao menos divId e data) e elaborar a linha de chamada do gráfico, uma vez que a biblioteca opera com camadas de objetos JavaScript:
Plotly.newPlot(divId, data, layout, config)
A biblioteca Plotly permite a construção de mais de 40 tipos de gráficos. A construção do gráfico é realizada a partir de propriedades que definem diferentes aspectos de visualização dos dados. O tipo fundamental do gráfico é definido pela propriedade type, que cria o traço:
# Propriedade `type`
# Básicos
scatter # dispersão, linhas, ou área
bar # barras
pie # pizza
box # diagramas de caixa (box plots)
histogram # histograma
violin # violino
heatmap # mapas de calor
scatter3D # dispersão em 3D
chloroplet # mapa cloroplético
# Estatísticos
contour # contorno
histogram2d # histogramas bidimensionais
histogram2dcontour # contornos de histogramas 2D
ohlc # mercado financeiro (Open#High#Low#Close)
candlestick # velas (mercado financeiro)
waterfall # cascata
# 3D
scatter3d # Para gráficos de dispersão 3D
surface # Para superfícies 3D
mesh3d # Para malhas 3D
cone # Para gráficos de cone 3D
streamtube # Para tubos de fluxo 3D
# Mapa
choropleth # Para mapas coropléticos (coloridos por região)
scattergeo # Para mapas de dispersão geográficos
scattermapbox # Para mapas usando Mapbox
# Específicos
sankey # diagramas de Sankey
parcoords # coordenadas paralelas
carpet # carpete
funnel # funil
funnelarea # área de funil
treemap # mapas de árvore
sunburst # explosão solar
icicle # tipo "pingente de gelo"
indicator # indicadores ou medidores
table # tabelasAlém da configuração type, acrescenta-se a propriedade mode, essa apenas para gráficos de dispersão de pontos (scatter). A propriedade mode acrescenta linhas, marcadores e/ou texto aos pontos gráficos, elevando seu grau de interatividade, e controlando a aparência dos pontos de dados:
# Propriedade `mode` (somente para `type` - dispersão)
markers - pontos/marcadores
lines - linhas conectando os pontos
text - texto para cada ponto
markers+lines - marcadores e linhas
markers+text - marcadores e texto para cada ponto
lines+text - linhas e texto para cada ponto
markers+lines+text - marcadores, linhas e texto
Além das propriedades type e mode, um gráfico Plotly.js pode ser configurado para um conjunto extenso de argumentos, apresentando rótulos nos eixos, cores, símbolos, marcas, plano de fundo, texto, fontes, e legendas, dentre vários. Segue um elenco de possibilidades básicas:
# Plano de fundo
Cor
Grid
# Títulos (rótulos)
Fonte (tipo, tamanho)
Cor
# Eixos
Etiquetas (rótulos)
Ticks
Limites
# Símbolos & Linhas
Tipos
Cores
Tamanho
Transparência
Preenchimento
# Legendas
Inserção
Personalização
# Anotações
Inserção
PersonalizaçãoUm exemplo mais completo de uso dessas propriedades pode ser encontrado na Figura 10.3 que segue. Para reproduzi-lo, faça como realizado anteriormente na Figura 10.2 (ou seja, cópia e cola do código num JSPlotly).
var data = [{
x: [1, 2, 3, 4, 5],
y: [2, 4, 1, 5, 3],
type: 'scatter',
mode: 'lines+markers', // Adiciona linhas e marcadores para melhor visualização
line: { color: 'blue' }, // Cor da linha
marker: { size: 8, color: 'red' } // Cor e tamanho dos marcadores
}];
var layout = {
title: {
text: 'Gráfico Exemplo', // Título do gráfico
font: {
family: 'Arial, sans-serif', // Tipo de fonte
size: 18, // Tamanho da fonte
color: 'darkblue' // Cor da fonte
}
},
xaxis: {
title: {
text: 'Eixo X',
font: {
family: 'Arial, sans-serif',
size: 14,
color: 'black'
}
},
showgrid: true, // Exibir grid
gridcolor: 'lightgray', // Cor do grid
zeroline: true, // Linha zero visível
zerolinecolor: 'gray' // Cor da linha zero
},
yaxis: {
title: {
text: 'Eixo Y',
font: {
family: 'Arial, sans-serif',
size: 14,
color: 'black'
}
},
showgrid: true,
gridcolor: 'lightgray',
zeroline: true,
zerolinecolor: 'gray'
},
plot_bgcolor: '#f5f5dc', // Cor de fundo do gráfico (bege claro)
paper_bgcolor: '#ffffff' // Cor de fundo da área do gráfico
};
Plotly.newPlot('grafico', data, layout);O script acima produz o gráfico representado na Figura 10.3 que segue.
Não há limites para outros mundos gráficos e cartográficos criados com Plotly. Para se ter uma ideia, observe as variações posssíveis com auxílio das tabelas que seguem, para configurações e ajustes de códigos de JSPlotly, tanto os contidos nessa obra, como os que lhe vier à cabeça depois dessa leitura e aprendizado. E contemple a imensa flexibilidade para criação personalizada junto à biblioteca, tal como segue.
1. Títulos (layout)
| Propriedade | Descrição | Exemplo |
|---|---|---|
title.text |
Define o texto do título principal | title: { text: 'Análise de Vendas 2024' } |
title.font.family |
Define a família da fonte do título | title: { font: { family: 'Arial, sans-serif' } } |
title.font.size |
Define o tamanho da fonte do título | title: { font: { size: 24 } } |
title.font.color |
Define a cor da fonte do título | title: { font: { color: '#1f77b4' } } |
title.xref |
Define a referência X para posicionamento do título | title: { xref: 'paper' } |
title.x |
Define a posição horizontal do título (0-1) | title: { x: 0.5 } |
title.yref |
Define a referência Y para posicionamento do título | title: { yref: 'paper' } |
title.y |
Define a posição vertical do título (0-1) | title: { y: 0.95 } |
2. Eixos (layout)
| Propriedade | Descrição | Exemplo |
|---|---|---|
xaxis.title.text |
Define o texto do título do eixo X | xaxis: { title: { text: 'Tempo (s)' } } |
xaxis.title.font |
Define a fonte do título do eixo X | xaxis: { title: { font: { family: 'Arial', size: 18, color: '#7f7f7f' } } } |
xaxis.range |
Define os limites do eixo X | xaxis: { range: [0, 100] } |
xaxis.tickmode |
Define o modo de graduação (auto, linear, array) | xaxis: { tickmode: 'linear' } |
xaxis.tick0 |
Define a posição do primeiro rótulo quando tickmode=‘linear’ | xaxis: { tick0: 0 } |
xaxis.dtick |
Define o intervalo entre rótulos quando tickmode=‘linear’ | xaxis: { dtick: 10 } |
xaxis.tickvals |
Define posições personalizadas dos rótulos | xaxis: { tickvals: [0, 25, 50, 75, 100] } |
xaxis.ticktext |
Define textos personalizados para os rótulos | xaxis: { ticktext: ['Zero', '25%', '50%', '75%', 'Max'] } |
xaxis.showgrid |
Mostra/oculta as linhas de grade do eixo | xaxis: { showgrid: true } |
xaxis.gridcolor |
Define a cor das linhas de grade | xaxis: { gridcolor: '#e6e6e6' } |
xaxis.gridwidth |
Define a largura das linhas de grade | xaxis: { gridwidth: 1 } |
3. Símbolos/Marcadores (layout - via trace)
| Propriedade | Descrição | Exemplo |
|---|---|---|
marker.symbol |
Define o tipo de símbolo/marcador | marker: { symbol: 'circle' } |
marker.size |
Define o tamanho do marcador | marker: { size: 12 } |
marker.color |
Define a cor do marcador | marker: { color: 'rgb(255, 0, 0)' } |
marker.opacity |
Define a transparência do marcador (0-1) | marker: { opacity: 0.8 } |
marker.line.color |
Define a cor da linha do marcador | marker: { line: { color: 'black' } } |
marker.line.width |
Define a largura da linha do marcador | marker: { line: { width: 2 } } |
marker.gradient |
Define um gradiente para os marcadores | marker: { gradient: { type: 'radial', color: 'white' } } |
4. Linhas (layout - via trace)
| Propriedade | Descrição | Exemplo |
|---|---|---|
line.color |
Define a cor da linha | line: { color: 'rgb(55, 128, 191)' } |
line.width |
Define a largura da linha | line: { width: 3 } |
line.dash |
Define o estilo da linha (solid, dot, dash, etc.) | line: { dash: 'dash' } |
line.shape |
Define a forma da linha (linear, spline, etc.) | line: { shape: 'spline' } |
line.smoothing |
Define o nível de suavização para linhas | line: { smoothing: 1.3 } |
5. Grid (layout)
| Propriedade | Descrição | Exemplo |
|---|---|---|
grid.rows |
Define o número de linhas no grid | grid: { rows: 2 } |
grid.columns |
Define o número de colunas no grid | grid: { columns: 3 } |
grid.pattern |
Define o padrão do grid | grid: { pattern: 'independent' } |
grid.roworder |
Define a ordem das linhas | grid: { roworder: 'top to bottom' } |
grid.xgap |
Define o espaçamento horizontal entre subplots | grid: { xgap: 0.1 } |
grid.ygap |
Define o espaçamento vertical entre subplots | grid: { ygap: 0.1 } |
6. Plano de Fundo (layout)
| Propriedade | Descrição | Exemplo |
|---|---|---|
paper_bgcolor |
Define a cor de fundo da área do papel | paper_bgcolor: 'rgb(250, 250, 250)' |
plot_bgcolor |
Define a cor de fundo da área do gráfico | plot_bgcolor: 'rgba(240, 240, 240, 0.8)' |
images |
Adiciona imagens de fundo ao gráfico | images: [{ source: 'url', x: 0, y: 0, xref: 'paper', yref: 'paper', sizex: 1, sizey: 1 }] |
shapes |
Adiciona formas geométricas ao plano de fundo | shapes: [{ type: 'rect', x0: 0, y0: 0, x1: 1, y1: 1, fillcolor: '#d3d3d3', opacity: 0.2 }] |
7. Texto (layout - via trace)
| Propriedade | Descrição | Exemplo |
|---|---|---|
text |
Define o texto a ser exibido para cada ponto | text: ['A', 'B', 'C'] |
textposition |
Define a posição do texto | textposition: 'top center' |
textfont.family |
Define a família da fonte do texto | textfont: { family: 'Arial' } |
textfont.size |
Define o tamanho da fonte do texto | textfont: { size: 12 } |
textfont.color |
Define a cor da fonte do texto | textfont: { color: 'blue' } |
hovertext |
Define o texto para hover | hovertext: ['Info A', 'Info B', 'Info C'] |
hoverinfo |
Define quais informações mostrar no hover | hoverinfo: 'x+y+text' |
annotations |
Adiciona anotações ao gráfico | annotations: [{ text: 'Ponto máximo', x: 5, y: 10, showarrow: true }] |
JSPlotly, JavaScript e sua biblioteca Plotly.js, os dois últimos presentes na contração do próprio nome do app explorado nesse livro vivo, foram abordoados para além da superfície ao longo dessa seção e dos capítulos da obra.
Não que não lhes falte observações e instruções adicionais ao entendimento e aplicações virtualmente infinitas, muito antes pelo contrário. Mas tudo que é bom dura … o suficiente para que a gente possa aprender a melhorar cada vez mais, e cada vez mais “com as próprias pernas” amparadas em uma boa leitura e mesmo a um assistente de inteligência artificial, como fora a experiência única deste autor ao longo da saudável interação humano-máquina que se fez presente na construção desse livro vivo.