Formati di dati

Questo documento spiega come inviare i dati del grafico all'API Google Chart.

Indice

1. Panoramica
2. Formato di testo di base
3. Formato del testo con scalabilità automatica
4. Formato di testo con scalabilità personalizzata
5. Formato di codifica semplice
6. Formato di codifica esteso
7. Scalabilità dei dati e scalabilità degli assi
8. Script di codifica JavaScript

Panoramica

I dati relativi a quasi tutti i grafici vengono inviati utilizzando il parametro chd. I dati devono essere inviati in uno dei seguenti formati:

• Il formato di testo di base è essenzialmente un semplice numero in virgola mobile da 0 a 100 inclusi. Questo formato è facile da leggere e scrivere a mano.
• Il formato di testo con scalabilità automatica scala il grafico per adattarlo ai tuoi dati.
• Il formato di testo con scalabilità personalizzata è simile al formato di testo di base, ma consente di specificare un intervallo personalizzato utilizzando un secondo parametro URL.
• Il formato di codifica semplice consente di specificare valori interi da 0 a 61 inclusi, codificati da un singolo carattere alfanumerico. Questa codifica genera la stringa di dati più breve tra tutti i formati di dati (se i valori sono maggiori di 9).
• Il formato di codifica esteso consente di specificare valori interi da 0 a 4095 inclusi, codificati da due caratteri alfanumerici. La codifica estesa è più adatta a un grafico con molti dati e un ampio intervallo di dati.

I valori dei dati vengono scalati in base al formato utilizzato. Consulta Scalabilità dei dati e scalabilità dell'asse per una spiegazione di come i dati vengono manipolati per adattarsi al grafico.

Forniamo uno snippet JavaScript per la codifica dei dati in formati di codifica semplici o estesi. In alternativa, diversi membri del gruppo Google Chart hanno contribuito con altre librerie che possono aiutarti con la formattazione: esegui una ricerca negli archivi per trovarle.

Formato testo di base

I dati di base in formato testo consentono di specificare valori in virgola mobile compresi tra 0 e 100 inclusi come numeri. I valori inferiori a zero sono contrassegnati come mancanti; quelli superiori a 100 vengono troncati a 100. Il vantaggio del formato di testo di base è che i valori sono facili da leggere e capire nell'URL e le etichette dell'asse predefinito mostrano i valori dei dati in modo accurato. Tuttavia, la formattazione del testo (se semplice o con parametri personalizzati) genera la stringa di dati più lunga di tutti i formati.

Se i dati includono valori che non rientrano nell'intervallo specificato per la formattazione del testo, puoi scalarli convertendoli in percentuali del valore più grande dei dati. In alternativa, potresti utilizzare la formattazione del testo con scalabilità personalizzata per gestire il ridimensionamento al posto tuo.

Sintassi:

chd=t:val,val,val|val,val,val...

<data>

Ogni serie contiene uno o più valori separati da virgole. Separa più serie utilizzando una barra verticale (|). I valori sono numeri in virgola mobile compresi tra 0 e 100 inclusi. I valori inferiori a zero o il trattino basso ( _ ) sono considerati valori null. I valori superiori a 100 vengono troncati a 100.

 

Esempio:

Una tabella con cinque valori. Il trattino basso viene considerato un valore null, il valore -30 è inferiore al valore minimo, quindi viene eliminato e il valore 200 viene troncato a 100.

chd=t:_,30,-30,50,80,200

Torna all'inizio

Formato del testo con scalabilità automatica

Puoi configurare alcuni grafici in modo che vengano ridimensionati automaticamente in base ai relativi dati. Il grafico viene ridimensionato in modo che il valore più grande si trovi nella parte superiore del grafico e il valore più piccolo (o zero, se tutti i valori sono maggiori di zero) sia nella parte inferiore.

I valori degli indicatori mostrati nel grafico mostreranno i valori effettivi, non i valori in scala.

Questa funzionalità può essere utilizzata solo con valori in formato testo e non funziona con tutti i tipi di grafici. Prova il tipo di grafico per verificare se è supportato.

Sintassi

cht=t:val,val,val...
chds=a

Esempi:

chd=t:5,30,50,80,200 chds=a Tieni presente che a torta non devi utilizzare valori < 0 per i grafici a torta.

chd=t:-5,30,-30,50,80,200 chds=a

Torna all'inizio

Formato di testo con scalabilità personalizzata

Il formato di testo con scalabilità personalizzata consente di specificare numeri in virgola mobile arbitrari, positivi o negativi, in combinazione con un parametro di scalabilità che consente di specificare un intervallo personalizzato per il grafico. Questo grafico è utile quando non vuoi preoccuparti di limitare i dati a un intervallo specifico o non vuoi scalare i dati manualmente per adattarli correttamente a un grafico. Questo formato regolerà automaticamente la riga zero, se necessario. Il formato dei dati è lo stesso del formato di testo di base.

Per la scalabilità automatica, specifica chds=a.

La formattazione del testo (se semplice o con parametri personalizzati) genera la stringa di dati più lunga di tutti i formati.

Sintassi:

La formattazione del testo con scalabilità personalizzata richiede due parametri:

chd=t:val,val,val|val,val,val
chds=<series_1_min>,<series_1_max>,...,<series_n_min>,<series_n_max>

chd=t:<data>

Uguale al formato dei dati normale: uno o più valori separati da virgole per serie, più serie separate da una barra verticale (|). L'intervallo di valori consentiti in ogni serie è specificato dal parametro chds.

chd

Un insieme di uno o più valori minimi e massimi consentiti per ogni serie di dati, separati da virgole. Devi indicare un valore minimo e un valore massimo. Se fornisci un numero inferiore di coppie rispetto alle serie di dati, l'ultima coppia viene applicata a tutte le serie di dati rimanenti. Tieni presente che ciò non modifica l'intervallo dell'asse; per modificare l'intervallo dell'asse, devi impostare il parametro chxr. I valori validi sono compresi tra (+/-)9,999e(+/-)199. Puoi specificare i valori in standard o in notazione E.

<series_1_min>

Il valore minimo consentito nella prima serie. I valori più bassi sono contrassegnati come mancanti.

<series_1_max>

Valore massimo consentito nella prima serie. I valori più alti vengono troncati a questo valore.

 

Esempio:

Un grafico a barre con una scala min/max compresa tra -80 e 140. I valori 30, -60, 50, 140 e 80 rientrano nella scala, quindi non vengono troncati. Tieni presente che la linea zero viene regolata automaticamente: 80/(140 + 80) = 0, 36 della parte superiore dell'asse y. Nota inoltre che l'intervallo predefinito dell'asse Y è ancora 0-100, nonostante il parametro chds, quindi i valori delle etichette non riflettono i valori effettivi dei dati.

chd=t:30,-60,50,140,80,-90 chds=-80,140

Torna all'inizio

Formato di codifica semplice

Il formato di codifica semplice consente di specificare valori interi da 0 a 61 inclusi, codificati da un singolo carattere alfanumerico. Questo comporta l'URL della stringa di dati più breve di tutti i formati di dati. Tuttavia, se il tuo grafico a linee o a barre è più lungo di 100 pixel lungo l'asse dei dati, ti consigliamo di utilizzare un altro formato. Il motivo è che, con solo 62 valori di dati supportati, la granularità dei dati è molto maggiore rispetto a quella della visualizzazione e i valori saranno leggermente ridotti (non molto, ma visibili sui grafici più grandi).

Tieni presente che se utilizzi il parametro chds con una codifica semplice, le dimensioni degli elementi dati nel grafico non saranno interessate, ma lo saranno i valori degli indicatori del punto dati.

Sintassi:

chd=s:
  <series_1>
    ,...,
  <series_n>

<serie_1>

Una stringa, in cui ogni carattere è un singolo punto dati, e le serie sono delimitate da una virgola. I singoli valori all'interno di una serie non sono delimitati. Ecco i caratteri dei dati supportati e i relativi valori:

• A—Z, dove A = 0, B = 1 e così via, per Z = 25
• a—z, dove a = 26, b = 27 e così via, per z = 51
• 0(zero)—9, dove 0 = 52 e 9 = 61
• Il trattino basso (_) indica un valore mancante

Puoi utilizzare il seguente strumento per codificare un singolo valore o il codice JavaScript per scalare e codificare un'intera stringa URL.

Esempio:

Equivale alla stringa con codifica di testo chd=t:1,19,27,53,61,-1|12,39,57,45,51,27

<title="chs=320x200&cht=bvs&chd=s:btb19_,mn5tzb&chco=ffcc33,ffe9a4&chxr=0,0,61,5&chxt=y" alt="Grafico a barre in pila con due serie e sei valori ciascuna, codifica semplice." src="/static/chart_7</a>chd=s:BTb19_,Mn5tzb

Torna all'inizio

Formato di codifica esteso

Il formato di codifica esteso consente di specificare valori interi compresi tra 0 e 4095 inclusi, codificati con due caratteri alfanumerici. Utilizza una sintassi leggermente diversa dalla codifica semplice.

Tieni presente che se utilizzi il parametro chds con una codifica semplice, le dimensioni degli elementi dati nel grafico non saranno interessate, ma lo saranno i valori degli indicatori del punto dati.

Sintassi:

chd=e:
  <series_1>
    ,...,
  <series_n>

<serie_1>

Una stringa in cui ogni due caratteri corrisponde a un singolo punto dati, mentre le serie sono delimitate da una virgola. I singoli valori di una serie non sono delimitati. Ecco i caratteri di codifica supportati:

• A—Z
• a—z
• 0—9
• periodo (.)
• Trattino (-)
• I valori mancanti sono indicati con un doppio trattino basso (__).

Di seguito è riportata una descrizione abbreviata dei valori codificati:

• AA = 0, AB = 1 e così via a AZ = 25
• Aa = 26, Ab = 27 e così via a Az = 51
• A0 = 52, A1 = 53 e così via a A9 = 61
• A- = 62, A. = 63
• BA = 64, BB = 65 e così via a BZ = 89
• Ba = 90, Bb = 91 e così via a Bz = 115
• B0 = 116, B1 = 117 e così via a B9 = 125
• B- = 126, B. = 127
• 9A = 3904, 9B = 3905 e così via fino a 9Z = 3929
• 9a = 3930, 9b = 3931 e così via a 9z = 3955
• 90 = 3956, 91 = 3957 e così via fino a 99 = 3965
• 9- = 3966, 9. = 3967
• -A = 3968, -B = 3969 e così via fino a -Z = 3993
• -a = 3994, -b = 3995 e così via fino a -z = 4019
• -0 = 4020, -1 = 4021 e così via fino a -9 = 4029
• -- = 4030, -. = 4031
• .A = 4032, .B = 4033 e così via fino a .Z = 4057
• .a = 4058, .b = 4059 e così via fino a .z = 4083
• .0 = 4084, .1 = 4085 e così via fino a .9 = 4093
• .- = 4094, .. = 4095

Puoi utilizzare il seguente strumento per codificare un singolo valore o il codice JavaScript per scalare e codificare un'intera stringa URL.

Esempio:

Equivale alla stringa con codifica di testo chd=t:90,1000,2700,3500|3968,-1,1100,250

chd=e:BaPoqM2s,-A__RMD6

Torna all'inizio

Scalabilità dei dati e scalabilità degli assi

I dati vengono scalati per adattarsi al grafico in modo esplicito (quando si utilizza il formato di testo con scalabilità personalizzata) o implicitamente (tutti gli altri tipi). Ciò significa che ogni grafico viene ridimensionato per adattarsi all'intervallo disponibile del formato, non all'intervallo effettivo dei dati forniti.

Ti consigliamo di scalare i dati in modo che coprano l'intera gamma di valori consentiti dal formato, per rendere le differenze più evidenti. Puoi scalare i dati ridimensionandoli per adattarli al formato che utilizzi oppure specificando esplicitamente l'intervallo di dati (ovvero, utilizza il formato di testo con la scalabilità personalizzata).

Tieni presente che i valori delle etichette dell'asse vengono calcolati su una scala completamente indipendente e non hanno nulla a che fare con i valori dei dati, ma utilizzano l'intervallo predefinito 0-100. Tuttavia, puoi modificare questo intervallo.

In questa sezione vengono descritti entrambi i problemi.

I dati vengono ridimensionati per adattarsi all'intervallo di formato [Tutti i grafici tranne Torta e Venn]

Formati diversi supportano intervalli di valori differenti. I dati vengono adattati all'intervallo di formato, in modo che il valore massimo supportato dal formato venga visualizzato nella parte superiore di quell'asse e il valore minimo del formato venga visualizzato nella parte inferiore. Gli esempi seguenti mostrano lo stesso valore (100) utilizzando il formato di testo di base (intervallo 0-100), il testo con scalabilità personalizzata (intervallo personalizzato 0-200) e il formato di codifica esteso (intervallo 0-4095).

Formato testo di base	Formato di testo con scalabilità personalizzata	Formato di codifica esteso
Valore: 100 (chd=t:100) Intervallo di formato: da 0 a 100 Il 100 viene visualizzato come 100/100 sulla scala.	Valore 100 (chd=t:100, chds=0,200) Intervallo di formato: 0-200 Il 100 è reso 100/200 sulla scala.	Valore: 100 (chd=e:Bk) Intervallo di formato: da 0 a 4095 Il 100 viene visualizzato come 100/4095 sulla scala.

Un modo semplice per scalare i dati per adattarli al grafico è utilizzare il formato di testo con scalabilità. Un metodo più complesso è scalare manualmente i dati per adattarli all'intervallo supportato dal formato.

Grafici a torta e di Venn: con i grafici a torta e di Venn, tutti i valori sono relativi tra loro, non con la scala totale del grafico.

chd=e:BkDIEs	chd=t:100,200,300 chds=0,300

L'intervallo delle etichette dell'asse viene calcolato in modo indipendente [a barre, a linee, radar, dispersione e a candele]

Puoi scegliere di visualizzare i valori dell'asse utilizzando il parametro chxt. Tuttavia, è importante notare che le etichette degli assi non vengono calcolate in modo da riflettere i dati del grafico, ma vengono calcolate in modo indipendente dall'API o specificate esplicitamente da te.

L'intervallo predefinito dell'asse è 0-100, indipendentemente dai valori o dalla scala dei dati. Ad esempio, se visualizzi l'asse Y utilizzando le etichette dell'asse predefinito su un grafico che utilizza la codifica estesa (intervallo 0-4095), le etichette dell'asse Y continueranno a leggere 0-100, a meno che non lo modifichi esplicitamente, come spiegato di seguito. Ecco un esempio che mostra le etichette predefinite dell'asse Y in un grafico a barre di codifica estesa con un valore dei dati pari a 100:

chd=e:Bk (equivalente a chd=t:100)

Tuttavia, puoi specificare l'intervallo dell'asse utilizzando il parametro chxr. Se vuoi che i valori dell'asse riflettano i valori effettivi dei dati, devi specificare i valori minimo e massimo dell'asse corrispondenti all'intervallo di formato. Tieni presente che il formato del testo di base ha già una scala da 0 a 100, quindi se utilizzi la formattazione di base del testo (senza scalabilità personalizzata), i valori dell'asse corrisponderanno ai valori dei dati per impostazione predefinita. Vediamo questo concetto con alcuni esempi. Ecco tre grafici con gli stessi dati (15, 26, 51 e 61), ma con formati e scale di assi diversi:

Codifica semplice, nessuna scalabilità degli assi	Codifica semplice, asse in scala	Testo di base, nessun ridimensionamento dell'asse
chd=s:Paz9   Intervallo di valori di codifica semplice: da 0 a 61 Intervallo asse predefinito (0-100) L'intervallo di codifica è inferiore all'intervallo dell'asse delle etichette, pertanto le barre non corrispondono al valore effettivo sull'etichetta dell'asse. Tuttavia, le barre sono correttamente proporzionate tra loro.	chd=s:Paz9     chxr=0,0,61,10 Intervallo di valori di codifica semplice: da 0 a 61 Intervallo assi impostato esplicitamente su 0-61 L'intervallo di codifica e l'intervallo dell'asse sono uguali, quindi le barre corrispondono al valore corretto sull'asse.	chd=t:15,26,51,61   Intervallo di valori del formato di testo di base: da 0 a 100 Intervallo asse predefinito (0-100) L'intervallo di codifica e l'intervallo dell'asse sono di nuovo uguali, quindi i valori dei dati precisi vengono mostrati sull'asse per impostazione predefinita. Poiché l'intervallo del formato del testo è maggiore dell'intervallo del formato di codifica semplice (100 unità rispetto a 61 unità), le barre sono più piccole qui rispetto agli altri grafici, ma tutti i grafici rimangono in proporzione tra loro.

Torna all'inizio

Script di codifica JavaScript

Per l'uso reale, probabilmente è più facile codificare i dati in modo programmatico anziché manualmente.

Il seguente snippet di JavaScript codifica una singola serie nella codifica semplice o extended e scala i valori dei dati per adattarli all'intervallo completo di tale codifica. I dati devono essere forniti sotto forma di matrice di numeri positivi. Qualsiasi valore fornito che non sia un numero positivo viene codificato come valore mancante utilizzando il trattino basso (_).

var simpleEncoding =
  'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';

// This function scales the submitted values so that
// maxVal becomes the highest value.
function simpleEncode(valueArray,maxValue) {
  var chartData = ['s:'];
  for (var i = 0; i < valueArray.length; i++) {
    var currentValue = valueArray[i];
    if (!isNaN(currentValue) && currentValue >= 0) {
    chartData.push(simpleEncoding.charAt(Math.round((simpleEncoding.length-1) *
      currentValue / maxValue)));
    }
      else {
      chartData.push('_');
      }
  }
  return chartData.join('');
}

// Same as simple encoding, but for extended encoding.
var EXTENDED_MAP=
  'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-.';
var EXTENDED_MAP_LENGTH = EXTENDED_MAP.length;
function extendedEncode(arrVals, maxVal) {
  var chartData = 'e:';

  for(i = 0, len = arrVals.length; i < len; i++) {
    // In case the array vals were translated to strings.
    var numericVal = new Number(arrVals[i]);
    // Scale the value to maxVal.
    var scaledVal = Math.floor(EXTENDED_MAP_LENGTH *
        EXTENDED_MAP_LENGTH * numericVal / maxVal);

    if(scaledVal > (EXTENDED_MAP_LENGTH * EXTENDED_MAP_LENGTH) - 1) {
      chartData += "..";
    } else if (scaledVal < 0) {
      chartData += '__';
    } else {
      // Calculate first and second digits and add them to the output.
      var quotient = Math.floor(scaledVal / EXTENDED_MAP_LENGTH);
      var remainder = scaledVal - EXTENDED_MAP_LENGTH * quotient;
      chartData += EXTENDED_MAP.charAt(quotient) + EXTENDED_MAP.charAt(remainder);
    }
  }

  return chartData;
}

Per codificare i dati, chiama la funzione simpleEncode o extendedEncode, passando l'array contenente i tuoi dati (valueArray) e il valore massimo dei dati (maxValue). Per creare uno spazio tra il valore più alto e la parte superiore del grafico, imposta maxValue in modo che sia maggiore del numero più grande nell'array di dati, come segue:

var valueArray = new Array(0,1,4,4,6,11,14,17,23,28,33,36,43,59,65);
var maxValue = 70;
simpleEncode(valueArray, maxValue);

Torna all'inizio