Format Data

Dokumen ini menjelaskan cara mengirim data diagram ke Google Chart API.

Daftar Isi

1. Ringkasan
2. Format Teks Dasar
3. Format Teks dengan Penskalaan Otomatis
4. Format Teks dengan Penskalaan Kustom
5. Format Encoding Sederhana
6. Format Encoding yang Diperluas
7. Penskalaan Data dan Penskalaan Sumbu
8. Skrip Encoding JavaScript

Ringkasan

Data untuk hampir semua diagram dikirim menggunakan parameter chd. Data harus dikirim dalam salah satu format berikut:

• Format teks dasar pada dasarnya adalah angka floating point sederhana dari 0—100, inklusif. Format ini mudah dibaca dan ditulis dengan tangan.
• Format teks dengan penskalaan otomatis menskalakan diagram agar sesuai dengan data Anda.
• Format teks dengan penskalaan kustom mirip dengan format teks dasar, tetapi memungkinkan Anda menentukan rentang kustom menggunakan parameter URL kedua.
• Format encoding sederhana memungkinkan Anda menentukan nilai bilangan bulat dari 0—61, inklusif, yang dienkode dengan karakter alfanumerik tunggal. Encoding ini akan menghasilkan string data terpendek dari salah satu format data apa pun (jika ada nilai lebih besar dari 9).
• Format encoding yang diperluas memungkinkan Anda menentukan nilai bilangan bulat dari 0—4095, inklusif, yang dienkode oleh dua karakter alfanumerik. Encoding yang diperluas paling cocok untuk diagram yang memiliki banyak data dan rentang data yang besar.

Nilai data diskalakan agar sesuai dengan format yang digunakan; lihat Penskalaan Data dan Penskalaan Sumbu untuk penjelasan mengenai cara data dimanipulasi agar sesuai dengan diagram.

Kami menyediakan cuplikan JavaScript untuk mengenkode data ke dalam format encoding sederhana atau format yang diperluas. Atau, beberapa anggota grup Diagram Google telah mengontribusikan library lain untuk membantu pemformatan: telusuri arsip untuk menemukannya.

Format Teks Dasar

Data berformat teks dasar memungkinkan Anda menentukan nilai floating point dari 0—100, inklusif, sebagai angka. Nilai di bawah nol ditandai sebagai tidak ada; nilai di atas 100 akan terpotong menjadi 100. Keuntungan dari format teks dasar adalah nilai mudah dibaca dan dipahami di URL, dan label sumbu default menampilkan nilai data secara akurat. Namun, pemformatan teks (baik sederhana maupun dengan parameter kustom) menghasilkan string data terpanjang di antara semua format.

Jika data Anda menyertakan nilai di luar rentang yang ditentukan untuk pemformatan teks, Anda dapat menskalakan data dengan mengonversinya menjadi persentase nilai terbesar dalam data Anda. Atau, Anda dapat menggunakan format teks dengan penskalaan kustom untuk menangani penskalaan untuk Anda.

Sintaksis:

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

<data>

Setiap deret adalah satu atau beberapa nilai yang dipisahkan koma. Pisahkan beberapa deret menggunakan karakter pipa (|). Nilainya adalah bilangan floating point dari 0—100, inklusif. Nilai kurang dari nol, atau karakter garis bawah ( _ ) dianggap sebagai nilai null. Nilai di atas 100 akan dipotong menjadi 100.

 

Contoh:

Tabel dengan lima nilai. Garis bawah dianggap sebagai nilai null, nilai -30 berada di bawah nilai minimum, sehingga dihapus, dan nilai 200 dipotong menjadi 100.

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

Kembali ke atas

Format Teks dengan Penskalaan Otomatis

Anda dapat mengonfigurasi beberapa diagram agar diskalakan secara otomatis agar sesuai dengan datanya. Diagram akan diskalakan sehingga nilai terbesar berada di bagian atas diagram dan nilai terkecil (atau nol, jika semua nilai lebih besar dari nol) akan berada di bagian bawah.

Setiap nilai penanda yang ditampilkan pada diagram akan menampilkan nilai sebenarnya, bukan nilai yang diskalakan.

Fitur ini hanya berfungsi dengan nilai berformat teks, dan tidak berfungsi dengan semua jenis diagram. Bereksperimenlah dengan jenis diagram Anda untuk melihat apakah diagram tersebut didukung.

Sintaksis

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

Contoh:

chd=t:5,30,50,80,200 chds=a Perhatikan bahwa pai Anda tidak boleh menggunakan nilai < 0 untuk diagram lingkaran.

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

Kembali ke atas

Format Teks dengan Penskalaan Kustom

Format teks dengan penskalaan kustom memungkinkan Anda menentukan bilangan floating point positif atau negatif arbitrer, yang dikombinasikan dengan parameter penskalaan yang memungkinkan Anda menentukan rentang kustom untuk diagram. Diagram ini berguna ketika Anda tidak ingin khawatir membatasi data ke rentang tertentu, atau tidak ingin menskalakan data secara manual agar muat di dalam diagram. Format ini akan menyesuaikan garis nol untuk Anda, jika diperlukan. Format data sama dengan format teks dasar.

Untuk penskalaan otomatis, tentukan chds=a.

Pemformatan teks (baik sederhana maupun dengan parameter kustom) menghasilkan string data terpanjang di antara semua format.

Sintaksis:

Pemformatan teks dengan penskalaan kustom memerlukan dua parameter:

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

chd=t:<data>

Sama seperti format data biasa: satu atau beberapa nilai yang dipisahkan koma per deret, beberapa deret yang dipisahkan dengan karakter pipa (|). Rentang nilai yang diizinkan di setiap deret ditentukan oleh parameter chds.

chds

Kumpulan satu atau beberapa nilai minimum dan maksimum yang diizinkan untuk setiap deret data, yang dipisahkan oleh koma. Anda harus menyediakan nilai maks dan minimum. Jika Anda memberikan lebih sedikit pasangan daripada deret data, pasangan terakhir akan diterapkan ke semua deret data yang tersisa. Perhatikan bahwa ini tidak mengubah rentang sumbu; untuk mengubah rentang sumbu, Anda harus menetapkan parameter chxr. Nilai yang valid berkisar dari (+/-)9.999e(+/-)199. Anda dapat menentukan nilai dalam standar atau notasi E.

<series_1_min>

Nilai minimum yang diizinkan dalam deret pertama. Nilai yang lebih rendah ditandai sebagai tidak ada.

<series_1_max>

Nilai maksimum yang diizinkan di deret pertama. Nilai yang lebih tinggi akan terpotong ke nilai ini.

 

Contoh:

Diagram batang dengan skala min/maks -80—140. Nilai 30, -60, 50, 140, dan 80 berada dalam skala, sehingga tidak terpotong. Perhatikan bahwa garis nol disesuaikan untuk Anda, 80/(140 + 80) = 0,36 panjang ke atas sumbu y. Perhatikan juga bahwa rentang sumbu y default masih 0—100, meskipun ada parameter chds, sehingga nilai label tidak mencerminkan nilai data yang sebenarnya.

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

Kembali ke atas

Format Encoding Sederhana

Format encoding sederhana memungkinkan Anda menentukan nilai bilangan bulat dari 0—61, inklusif, dienkode oleh satu karakter alfanumerik. Cara ini akan menghasilkan URL string data terpendek dari semua format data. Namun, jika memiliki diagram garis atau diagram batang yang panjangnya lebih dari 100 piksel di sepanjang sumbu data, Anda dapat menggunakan format lain. Ini karena, dengan hanya 62 nilai data yang didukung, perincian data jauh lebih besar daripada perincian tampilan, dan nilainya akan sedikit menurun (tidak banyak, tetapi terlihat pada diagram yang lebih besar).

Perhatikan bahwa jika Anda menggunakan parameter chds dengan encoding sederhana, ukuran elemen data pada diagram tidak akan terpengaruh, tetapi nilai penanda titik data akan terpengaruh.

Sintaksis:

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

<serial_1>

String, dengan setiap karakter adalah satu titik data, dan deret dipisahkan dengan koma. Nilai individual dalam seri tidak dipisahkan. Berikut adalah karakter data yang didukung, dan nilainya yang sesuai:

• A—Z, dengan A = 0, B = 1, dan seterusnya, menjadi Z = 25
• a—z, dengan a = 26, b = 27, dan seterusnya, menjadi z = 51
• 0(zero)—9, dengan 0 = 52 dan 9 = 61
• Karakter garis bawah (_) menunjukkan nilai yang tidak ada

Anda dapat menggunakan alat berikut untuk mengenkode satu nilai, atau kode JavaScript untuk menskalakan dan mengenkode seluruh string URL.

Contoh:

Setara dengan string chd=t:1,19,27,53,61,-1|12,39,57,45,51,27 yang dienkode teks

<title="chs=320x200&cht=bvs&chd=s:btb19_,mn5tzb&chco=ffcc33,ffe9a4&chxr=0,0,61,5&chxt=y" alt="Stacked bar chart dengan dua rangkaian dan enam nilai masing-masing, encoding sederhana." src/static/charts3 chd=s:BTb19_,Mn5tzb

Kembali ke atas

Format Encoding yang Diperpanjang

Format encoding yang diperluas memungkinkan Anda menentukan nilai bilangan bulat dari 0—4095, inklusif, yang dienkode oleh dua karakter alfanumerik. Kode ini menggunakan sintaksis yang sedikit berbeda dengan encoding sederhana.

Perhatikan bahwa jika Anda menggunakan parameter chds dengan encoding sederhana, ukuran elemen data pada diagram tidak akan terpengaruh, tetapi nilai penanda titik data akan terpengaruh.

Sintaksis:

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

<seri_1>

String yang setiap dua karakternya merupakan satu titik data, dan deret dipisahkan dengan koma. Nilai individual dalam deret tidak dipisahkan. Berikut adalah karakter encoding yang didukung:

• A—Z
• a—z
• 0—9
• titik (.)
• tanda hubung (-)
• Nilai yang tidak ada ditunjukkan dengan garis bawah ganda (__).

Berikut adalah deskripsi singkat dari nilai yang dienkode:

• AA = 0, AB = 1, dan seterusnya untuk AZ = 25
• Aa = 26, Ab = 27, dan seterusnya untuk Az = 51
• A0 = 52, A1 = 53, dan seterusnya untuk A9 = 61
• A- = 62, A. = 63
• BA = 64, BB = 65, dan seterusnya untuk BZ = 89
• Ba = 90, Bb = 91, dan seterusnya untuk Bz = 115
• B0 = 116, B1 = 117, dan seterusnya menjadi B9 = 125
• B- = 126, B. = 127
• 9A = 3.904, 9B = 3.905, dan seterusnya menjadi 9Z = 3.929
• 9a = 3.930, 9b = 3.931, dan seterusnya menjadi 9z = 3.955
• 90 = 3.956, 91 = 3.957, dan seterusnya menjadi 99 = 3.965
• 9- = 3.966, 9. = 3.967
• -A = 3.968, -B = 3.969, dan seterusnya menjadi -Z = 3.993
• -a = 3994, -b = 3.995, dan seterusnya menjadi -z = 4019
• -0 = 4020, -1 = 4021, dan seterusnya menjadi -9 = 4029
• -- = 4.030, -. = 4.031
• .A = 4032, .B = 4033, dan seterusnya menjadi .Z = 4057
• .a = 4058, .b = 4059, dan seterusnya menjadi .z = 4083
• .0 = 4084, .1 = 4085, dan seterusnya menjadi .9 = 4093
• .- = 4.094, .. = 4.095

Anda dapat menggunakan alat berikut untuk mengenkode satu nilai, atau kode JavaScript untuk menskalakan dan mengenkode seluruh string URL.

Contoh:

Setara dengan string chd=t:90,1000,2700,3500|3968,-1,1100,250 yang dienkode teks

chd=e:BaPoqM2s,-A__RMD6

Kembali ke atas

Penskalaan Data dan Penskalaan Sumbu

Data diskalakan agar sesuai dengan diagram Anda, baik secara eksplisit (saat menggunakan format teks dengan penskalaan kustom) maupun secara implisit (semua jenis lainnya). Artinya, setiap diagram diskalakan agar sesuai dengan rentang format yang tersedia, bukan rentang sebenarnya dari data yang Anda berikan.

Anda mungkin ingin menskalakan data sehingga mencakup seluruh rentang nilai yang diizinkan oleh format Anda, agar perbedaan menjadi lebih jelas. Anda dapat menskalakan data dengan menskalakan data agar sesuai dengan format yang digunakan, atau dengan menentukan rentang data secara eksplisit (yaitu, menggunakan format teks dengan penskalaan kustom).

Perhatikan bahwa nilai label sumbu dihitung pada skala yang sepenuhnya independen dan tidak ada hubungannya dengan nilai data, tetapi menggunakan rentang default 0—100. Namun, Anda dapat mengubah rentang tersebut.

Bagian ini menjelaskan kedua masalah tersebut.

Data diskalakan agar sesuai dengan rentang format [Semua diagram kecuali Pie dan Venn]

Format yang berbeda mendukung rentang nilai yang berbeda. Data Anda diskalakan ke rentang format Anda, sehingga nilai maksimum yang didukung oleh format Anda dirender di bagian atas sumbu tersebut, dan nilai minimum untuk format Anda dirender di bagian bawah. Contoh berikut menunjukkan nilai yang sama (100) menggunakan format teks dasar (rentang 0—100), teks dengan penskalaan kustom (rentang kustom 0—200), dan format encoding yang diperluas (rentang 0—4095).

Format Teks Dasar	Format Teks dengan Penskalaan Kustom	Format Encoding yang Diperpanjang
Nilai: 100 (chd=t:100) Rentang format: 0—100 Angka 100 dirender sebagai 100/100 pada skala yang lebih besar.	Nilai 100 (chd=t:100, chds=0,200) Rentang format: 0—200 100 dirender 100/200 ke atas.	Nilai: 100 (chd=e:Bk) Rentang format: 0—4095 Angka 100 dirender sebagai 100/4095 pada skala yang lebih besar.

Cara mudah untuk menskalakan data agar sesuai dengan diagram Anda adalah menggunakan format teks dengan penskalaan. Metode yang lebih terlibat adalah menskalakan data secara manual agar sesuai dengan rentang yang didukung oleh format Anda.

Diagram Lingkaran dan Venn: Dengan diagram lingkaran dan Venn, semua nilai relatif satu sama lain, bukan terhadap total skala diagram.

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

Rentang label Sumbu dihitung secara terpisah [Batang, Garis, Radar, Sebar, dan Batang Lilin]

Anda dapat memilih untuk menampilkan nilai sumbu dengan menggunakan parameter chxt. Namun, penting untuk diperhatikan bahwa label sumbu tidak dihitung untuk mencerminkan data diagram, tetapi dihitung secara independen oleh API, atau ditentukan secara eksplisit oleh Anda.

Rentang sumbu default adalah 0—100, terlepas dari nilai data atau penskalaan data. Jadi, misalnya, jika Anda menampilkan sumbu y menggunakan label sumbu default pada diagram yang menggunakan encoding yang diperluas (rentang 0—4095), label sumbu y akan tetap terbaca 0—100 kecuali jika Anda mengubahnya secara eksplisit, seperti yang dijelaskan di bawah. Berikut ini contoh yang menunjukkan label sumbu y default dalam diagram batang encoding yang diperluas dengan nilai data 100:

chd=e:Bk (setara dengan chd=t:100)

Namun, Anda dapat menentukan rentang sumbu menggunakan parameter chxr. Jika ingin nilai sumbu mencerminkan nilai data sebenarnya, Anda harus menentukan nilai sumbu minimum dan maksimum yang sesuai dengan rentang format Anda. Perhatikan bahwa format teks dasar sudah memiliki skala 0—100, jadi jika Anda menggunakan pemformatan teks dasar (tanpa penskalaan kustom), nilai sumbu akan cocok dengan nilai data secara default. Mari kita gambarkan hal ini dengan beberapa contoh. Berikut tiga diagram dengan data yang sama (15,26,51,61), tetapi format dan skala sumbu yang berbeda:

Encoding Sederhana, Tanpa Penskalaan Sumbu	Encoding Sederhana, Sumbu Skala Besar	Teks Dasar, Tanpa Penskalaan Sumbu
chd=s:Paz9   Rentang nilai encoding sederhana: 0—61 Rentang sumbu default (0—100) Rentang encoding lebih kecil dari rentang sumbu label, sehingga batang tidak sesuai dengan nilai sebenarnya pada label sumbu. Namun, batang tersebut disejajarkan dengan benar satu sama lain.	chd=s:Paz9     chxr=0,0,61,10 Rentang nilai encoding sederhana: 0—61 Rentang sumbu secara eksplisit ditetapkan ke 0—61 Rentang encoding dan rentang sumbu sama, sehingga batang sesuai dengan nilainya yang benar pada sumbu.	chd=t:15,26,51,61   Rentang nilai format teks dasar: 0—100 Rentang sumbu default (0—100) Rentang encoding dan rentang sumbu lagi sama, sehingga nilai data yang akurat ditampilkan di sumbu secara default. Karena rentang format teks lebih besar dari rentang format encoding sederhana (100 unit vs 61 unit), batang di sini lebih kecil daripada diagram lain, tetapi semua diagram tetap proporsional satu sama lain.

Kembali ke atas

Skrip Encoding JavaScript

Untuk penggunaan di dunia nyata, mungkin lebih mudah untuk mengenkode data secara terprogram daripada secara manual.

Cuplikan JavaScript berikut mengenkode satu rangkaian ke dalam encoding sederhana atau extended, dan menskalakan nilai data agar sesuai dengan rentang lengkap encoding tersebut. Data harus disediakan sebagai array angka positif. Setiap nilai yang diberikan dan bukan angka positif dienkode sebagai nilai yang hilang menggunakan karakter garis bawah (_).

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;
}

Untuk mengenkode data, panggil fungsi simpleEncode atau extendedEncode, dengan meneruskan array yang berisi data Anda (valueArray), dan nilai maksimum data Anda (maxValue). Untuk menciptakan ruang di antara nilai tertinggi dan bagian atas diagram, tetapkan maxValue menjadi lebih besar dari angka terbesar dalam array data, sebagai berikut:

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);

Kembali ke atas