פורמטים של נתונים

במסמך הזה אנחנו מסבירים איך לשלוח את נתוני התרשימים אל Google Chart API.

תוכן העניינים

  1. סקירה כללית
  2. פורמט טקסט בסיסי
  3. פורמט טקסט עם קנה מידה אוטומטי
  4. פורמט טקסט עם קנה מידה מותאם אישית
  5. פורמט קידוד פשוט
  6. פורמט קידוד מורחב
  7. התאמת נתונים והתאמת צירים
  8. סקריפט קידוד JavaScript

סקירה כללית

נתונים של כמעט כל התרשימים נשלחים באמצעות הפרמטר chd. צריך לשלוח את הנתונים באחד מהפורמטים הבאים:

  • פורמט טקסט בסיסי הוא למעשה מספרי נקודות צפות פשוטים מ-0 עד 100, כולל. הפורמט הזה קל לקריאה ולכתיבה בכתב יד.
  • פורמט טקסט עם התאמה אוטומטית של קנה המידה בתרשים כך שיתאים לנתונים שלכם.
  • פורמט טקסט עם התאמה אישית של קנה מידה דומה לפורמט הטקסט הבסיסי, אבל הוא מאפשר לציין טווח מותאם אישית באמצעות פרמטר שני של כתובת אתר.
  • פורמט קידוד פשוט מאפשר לציין ערכים של מספרים שלמים בין 0 ל-61 (כולל) ומקודדים באמצעות תו אלפאנומרי יחיד. הקידוד הזה מניב את מחרוזת הנתונים הקצרה ביותר מבין כל אחד מפורמטים של נתונים (אם ערכים כלשהם גדולים מ-9).
  • פורמט קידוד מורחב מאפשר לציין ערכים של מספרים שלמים בין 0 ל-4095 (כולל) ומקודדים באמצעות שני תווים אלפאנומריים. קידוד מורחב הוא המתאים ביותר לתרשים עם הרבה נתונים וטווח נתונים גדול.

הערכים של הנתונים מותאמים לפורמט שבו נעשה שימוש. במאמר קנה מידה של נתונים והתאמת צירים (Axis Scaling) יש הסבר על אופן הטיפול בנתונים כך שיתאימו לתרשים.

אנחנו מספקים קטע קוד JavaScript לקידוד נתונים לקידוד פשוט או לפורמטים של קידוד מורחב. לחלופין, מספר חברים בקבוצה של תרשימי Google תרמו ספריות אחרות כדי לסייע בעיצוב: בצעו חיפוש בארכיונים כדי למצוא אותן.

פורמט טקסט בסיסי

נתונים בסיסיים בפורמט טקסט מאפשרים לציין ערכי נקודה צפה (floating-point) מ-0 עד 100 כולל, כמספרים. ערכים מתחת לאפס מסומנים כחסרים. ערכים מעל 100 יקוצרו ל-100. היתרון של פורמט טקסט בסיסי הוא שכתובת האתר יכולה לקרוא ולהבין את הערכים בקלות, ותוויות ברירת המחדל של הצירים מציגות את ערכי הנתונים באופן מדויק. עם זאת, עיצוב טקסט (פשוט או עם פרמטרים מותאמים אישית) יוצרת את מחרוזת הנתונים הארוכה ביותר מכל הפורמטים.

אם הנתונים כוללים ערכים מחוץ לטווח שצוין עבור עיצוב טקסט, ניתן לשנות את קנה המידה של הנתונים על ידי המרתם לאחוזים של הערך הגדול ביותר בנתונים. לחלופין, אפשר להשתמש בעיצוב טקסט עם התאמה אישית של קנה המידה כדי לטפל בשינוי הגודל.

תחביר:

chd=t:val,val,val|val,val,val...
<data>
כל סדרה היא ערך אחד או יותר שמופרדים בפסיקים. צריך להפריד בין כמה סדרות באמצעות קו אנכי (|). הערכים הם מספרים של נקודות צפות בטווח שבין 0 ל-100, כולל. ערכים קטנים מאפס, או שתו קו תחתון ( _ ) נחשבים לערכים ריקים (null). ערכים מעל 100 מקוצרים ל-100.

 

דוגמה:

טבלה עם חמישה ערכים. הקו התחתון נחשב לערך אפס (null), הערך -30 נמוך מהערך המינימלי, ולכן הוא יורד והערך 200 יקוצר ל-100. תרשים עמודות עם 5 ערכים, קידוד טקסט.
chd=t:_,30,-30,50,80,200

חזרה למעלה

פורמט טקסט עם התאמה לעומס (scaling) באופן אוטומטי

יש לכם אפשרות להגדיר תרשימים מסוימים, שגודלם ישתנה באופן אוטומטי כך שיתאימו לנתונים שלהם. התרשים יותאם כך שהערך הגדול ביותר יהיה בראש התרשים, והערך הקטן ביותר (או אפס, אם כל הערכים גדולים מאפס) יופיע מתחתיו.

ערכי סמנים שמוצגים בתרשים יציגו את הערכים שלהם בפועל, ולא את הערכים המותאמים.

התכונה הזו פועלת רק עם ערכים בפורמט טקסט, ולא בכל סוגי התרשימים. נסו לבדוק את סוג התרשים כדי לראות אם הוא נתמך.

תחביר

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

לדוגמה:


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

שימו לב: אין להשתמש בערכים קטן מ-0 עבור תרשימי עוגה.

 תרשים עמודות עם 5 ערכים, קידוד טקסט.
chd=t:-5,30,-30,50,80,200
chds=a

חזרה למעלה

פורמט טקסט עם קנה מידה מותאם אישית

פורמט טקסט עם התאמה אישית של קנה מידה מאפשר לציין מספרי נקודה צפה שרירותיים או שליליים, בשילוב עם פרמטר שינוי קנה מידה שמאפשר לציין טווח מותאם אישית לתרשים. כדאי להשתמש בתרשים הזה כשלא צריך לחשוש לגבי הגבלת הנתונים לטווח ספציפי, או כשלא רוצים להתאים את הנתונים באופן ידני כך שיתאימו טוב לתרשים. הפורמט הזה יתאים את קו האפס, לפי הצורך. פורמט הנתונים זהה לפורמט הטקסט הבסיסי.

לשינוי גודל אוטומטי, יש לציין chds=a.

עיצוב טקסט (בין אם הוא פשוט או עם פרמטרים מותאמים אישית) יוצר את מחרוזת הנתונים הארוכה ביותר מכל הפורמטים.

תחביר:

כדי לעצב טקסט עם קנה מידה מותאם אישית, נדרשים שני פרמטרים:

chd=t:val,val,val|val,val,val
chds=<series_1_min>,<series_1_max>,...,<series_n_min>,<series_n_max>
chd=t:<data>
זהה לפורמט נתונים פשוט: ערך אחד או יותר שמופרדים בפסיקים בכל סדרה, מספר סדרות שמופרדות באמצעות קו אנכי (|). טווח הערכים המותרים בכל סדרה מצוין על ידי הפרמטר chds.
chds
קבוצה של ערך מינימום ומקסימום מותר אחד או יותר לכל סדרת נתונים, מופרדים בפסיקים. צריך לציין גם מקסימום וגם סכום מינימלי. אם תציינו פחות צמדים ממספר סדרות הנתונים, הזוג האחרון יחול על כל סדרות הנתונים שנותרו. לתשומת ליבכם: הפעולה הזו לא משנה את טווח הציר. כדי לשנות את טווח הציר, צריך להגדיר את הפרמטר chxr. הערכים התקינים נעים בין (+/-)9.999e(+/-)199. אפשר לציין ערכים בסימון רגיל או בסימון E.
<series_1_min>
הערך המינימלי המותר בסדרה הראשונה. ערכים נמוכים יותר מסומנים כחסרים.
<series_1_max>
הערך המקסימלי המותר בסדרה הראשונה. ערכים גבוהים יותר יקוצרו לערך הזה.

 

דוגמה:

תרשים עמודות בסולם מינימלי/מקסימלי של 80-140-. הערכים של 30, -60, 50, 140 ו-80 נמצאים בטווח הסולם כך שלא ייחתך. חשוב לדעת שקו האפס מותאם עבורך, 80/(140 + 80) = 0.36 מגובהו של ציר ה-Y.

חשוב גם לשים לב שטווח ברירת המחדל של ציר ה-Y הוא עדיין 0-100, למרות הפרמטר chds, כך שערכי התוויות לא משקפים את ערכי הנתונים בפועל.

 תרשים עמודות עם 5 ערכים, קידוד טקסט עם שינוי גודל נתונים.

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

חזרה למעלה

פורמט קידוד פשוט

פורמט קידוד פשוט מאפשר לציין ערכים של מספרים שלמים בין 0 ל-61, כולל, שמקודדים באמצעות תו אלפאנומרי יחיד. התוצאה היא כתובת ה-URL הקצרה ביותר של מחרוזת הנתונים מכל הפורמטים של הנתונים. עם זאת, אם יש לך תרשים קו או תרשים עמודות שאורכו יותר מ-100 פיקסלים לאורך ציר הנתונים, כדאי להשתמש בפורמט אחר. הסיבה לכך היא שבתמיכה רק ב-62 ערכי נתונים, רמת הפירוט של הנתונים גדולה בהרבה מרמת הפירוט של התצוגה, והערכים יהיו מעט שונים (לא הרבה, אבל יוצגו בתרשימים גדולים יותר).

חשוב לשים לב שאם משתמשים בפרמטר chds עם קידוד פשוט, הגודל של רכיב הנתונים בתרשים לא יושפע, אבל כל הערכים של סמן של נקודה על הגרף יושפעו.

תחביר:

chd=s:
  <series_1>
    ,...,
  <series_n>
<series_1>
מחרוזת, שבה כל תו הוא נקודה יחידה על הגרף, והסדרה מופרדת באמצעות פסיק. אין הפרדה בין ערכים בודדים בסדרה. אלה תווי הנתונים הנתמכים והערכים התואמים שלהם:
  • A—Z, כאשר A = 0, B = 1 וכן הלאה, עד Z = 25
  • a—z, כאשר a = 26, b = 27 וכן הלאה, עד 51 = z
  • 0(zero)—9, כאשר 0 = 52 ו-9 = 61
  • תו הקו התחתון (_) מציין ערך חסר

אפשר להשתמש בכלי הבא כדי לקודד ערך יחיד, או בקוד JavaScript כדי לשנות ולקודד מחרוזת של כתובת URL מלאה.

דוגמה:

שווה למחרוזת המקודדת בטקסט 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="תרשים עמודות מוערם עם שני סדרות עם שני סדרות ושישה ערכים כל אחד, פשוט." src=" src="/static/static/chtff13040/4cht
chd=s:BTb19_,Mn5tzb

חזרה למעלה

פורמט קידוד מורחב

פורמט קידוד מורחב מאפשר לציין ערכים של מספרים שלמים בין 0 ל-4095 (כולל) ומקודדים באמצעות שני תווים אלפאנומריים. התחביר שלה שונה במקצת מקידוד פשוט.

שימו לב שאם משתמשים בפרמטר chds עם קידוד פשוט, גודל רכיב הנתונים בתרשים לא יושפע מכך, אבל כל הערכים של סמן של נקודת נתונים יושפעו.

תחביר:

chd=e:
  <series_1>
    ,...,
  <series_n>
<series_1>
מחרוזת שבה כל שני תווים הם נקודת נתונים אחת, והסדרות מופרדות בפסיקים. אין הפרדה בין הערכים הנפרדים בסדרה. אלה תווי הקידוד הנתמכים:
  • A—Z
  • a—z
  • 0—9
  • תקופה (.)
  • מקף (-)
  • ערכים חסרים מסומנים בקו תחתון כפול (__).

הנה תיאור מקוצר של ערכים מקודדים:

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

אפשר להשתמש בכלי הבא כדי לקודד ערך יחיד, או בקוד JavaScript כדי לשנות ולקודד מחרוזת של כתובת URL מלאה.

דוגמה:

שווה למחרוזת המקודדת בטקסט chd=t:90,1000,2700,3500|3968,-1,1100,250 תרשים עמודות מוערם עם שתי סדרות של ארבעה ערכים כל אחד, קידוד מורחב.
chd=e:BaPoqM2s,-A__RMD6

חזרה למעלה

התאמה של נתונים והתאמת צירים

הנתונים משתנים בהתאם לתרשים שלכם, באופן מפורש (כשמשתמשים בפורמט טקסט עם התאמה אישית של קנה המידה) או באופן מרומז (כל הסוגים האחרים). המשמעות היא שכל תרשים מותאם לטווח הזמין של הפורמט, ולא לטווח בפועל של הנתונים שאתם מספקים.

כדאי להתאים את קנה המידה של הנתונים כך שיכלול את טווח הערכים המלא המותר לפי הפורמט, כדי שההבדלים יהיו ברורים יותר. אפשר לשנות את קנה המידה של הנתונים על ידי התאמת הנתונים לפורמט שבו משתמשים, או על ידי ציון טווח הנתונים באופן מפורש (כלומר, שימוש בפורמט טקסט עם שינוי קנה מידה בהתאמה אישית).

חשוב לשים לב שהערכים של תוויות הציר מחושבים לפי קנה מידה בלתי תלוי לחלוטין, שאין להם כל קשר לערכי הנתונים. עם זאת, יש להשתמש בטווח ברירת המחדל של 0-100. עם זאת, אפשר לשנות את הטווח הזה.

בקטע הזה מתוארות שתי הבעיות האלה.

הנתונים מותאמים לטווח הפורמטים [כל התרשימים חוץ מ-Pie and Venn]

פורמטים שונים תומכים בטווחי ערכים שונים. הנתונים מותאמים לטווח הפורמטים, כך שהערך המקסימלי שנתמך בפורמט מוצג בחלק העליון של הציר והערך המינימלי של הפורמט מוצג בחלק התחתון. בדוגמאות הבאות מוצגים אותו ערך (100) בפורמט טקסט בסיסי (טווח 0 עד 100), טקסט עם שינוי גודל בהתאמה אישית (טווח מותאם אישית של 0 עד 200) ופורמט קידוד מורחב (טווח 0 עד 4095).

פורמט טקסט בסיסי פורמט טקסט עם קנה מידה מותאם אישית פורמט קידוד מורחב
תרשים עמודות עם טקסט בסיסי עם שינוי קנה מידה מותאם אישית

ערך: 100 (chd=t:100)

טווח פורמטים: 0-100

הערך 100 מוצג כ-100/100 במעלה הסולם.

ערך 100 (chd=t:100, chds=0,200)

טווח הפורמטים: 0-200

הערך 100 מוצג בסולם של 100/200 בסולם גבוה.

ערך: 100 (chd=e:Bk)

טווח פורמטים: 0—4095

הערך 100 מוצג כ-100/4095 במעלה הסולם.

דרך קלה להתאים את הנתונים לתרשים היא להשתמש בפורמט טקסט עם התאמה לתרשים. שיטה מורכבת יותר היא להתאים את הנתונים באופן ידני לטווח הנתמך בפורמט שלך.

תרשימי עוגה ו-Ven: בתרשימים עוגה ו-Venn, כל הערכים יחסיים זה לזה, ולא לקנה המידה הכולל של התרשים.

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

הטווח של תוויות הצירים מחושב בנפרד [סרגל, קו, מכ"ם, פיזור ופמוט]

אפשר לבחור להציג את הערכים של הציר באמצעות הפרמטר chxt. עם זאת, חשוב לציין שתוויות הצירים לא מחושבות כדי לשקף את נתוני התרשים. הן מחושבות בנפרד על ידי ה-API או שהן מוגדרות באופן מפורש על ידך.

טווח ברירת המחדל של הציר הוא 0-100, ללא קשר לערכי הנתונים או לשינוי קנה המידה של הנתונים. לדוגמה, אם מציגים את ציר ה-Y באמצעות תוויות ברירת מחדל של צירים בתרשים שנעשה בו שימוש בקידוד מורחב (טווח 0-4095), התוויות של ציר ה-Y עדיין יראו את הערך 0-100 אלא אם תשנו את הערך באופן מפורש, כפי שמוסבר בהמשך. זוהי דוגמה לתוויות ברירת המחדל של ציר ה-Y, בתרשים עמודות מורחב לקידוד עם ערך נתונים של 100:


chd=e:Bk (שווה ערך ל-chd=t:100)

עם זאת, אפשר לציין את טווח הציר באמצעות הפרמטר chxr. כדי שערכי הציר ישקפו את ערכי הנתונים בפועל, צריך לציין ערכי מינימום ומקסימום לצירים שתואמים לטווח הפורמט שלך. לתשומת ליבך, לפורמט הטקסט הבסיסי כבר יש סולם מ-0 עד 100, כך שאם משתמשים בעיצוב טקסט בסיסי (ללא קנה מידה מותאם אישית), ערכי הציר יתאימו לערכי הנתונים כברירת מחדל. נמחיש את זה בעזרת כמה דוגמאות. לפניכם שלושה תרשימים עם אותם נתונים (15,26,51,61), אבל בפורמטים שונים ובקנה מידה שונים של צירים:

קידוד פשוט, ללא התאמת צירים קידוד פשוט, ציר מותאם טקסט בסיסי, ללא התאמת צירים

chd=s:Paz9
 

טווח פשוט של ערכי קידוד: 0-61

טווח ברירת המחדל של הציר (0-100)

טווח הקידוד קטן יותר מהטווח של ציר התווית, כך שהעמודות לא תואמות לערך בפועל בתווית של הציר. עם זאת, העמודות פרופורציונליות כראוי.

chd=s:Paz9
    chxr=0,0,61,10

טווח פשוט של ערכי קידוד: 0-61

טווח הצירים מוגדר באופן מפורש בין 0 ל-61

טווח הקידוד וטווח הציר זהים, כך שהעמודות תואמות לערך הנכון שלהן בציר.

chd=t:15,26,51,61
 

טווח ערכים בסיסי של פורמט טקסט: 0-100

טווח ברירת המחדל של הציר (0-100)

טווח הקידוד וטווח הצירים חוזרים להיות זהים, כך שערכי הנתונים המדויקים מוצגים בציר, כברירת מחדל.

מאחר שהטווח של תבניות הטקסט גדול מהטווח של פורמט הקידוד הפשוט (100 יחידות לעומת 61 יחידות), העמודות כאן קטנות יותר מאשר בתרשימים האחרים, אבל כל התרשימים נשארים יחסיים זה עם זה.

חזרה למעלה

סקריפט קידוד ב-JavaScript

בעולם האמיתי, סביר להניח שקל יותר לקודד נתונים באופן פרוגרמטי מאשר באופן ידני.

קטע הקוד הבא של JavaScript מקודד סדרה יחידה בקידוד פשוט או extended, ומשנה את קנה המידה של ערכי הנתונים כך שיתאימו לטווח המלא של הקידוד הזה. צריך לספק את הנתונים כמערך של מספרים חיוביים. כל ערך שצוין שאינו מספר חיובי מקודד כערך חסר באמצעות קו תחתון (_).

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

כדי לקודד נתונים, צריך לקרוא לפונקציה simpleEncode או extendedEncode ולהעביר את המערך שמכיל את הנתונים שלך (valueArray) ואת הערך המקסימלי של הנתונים (maxValue). כדי ליצור רווח בין הערך הגבוה ביותר לחלק העליון של התרשים, צריך להגדיר את maxValue כך שיהיה גדול מהמספר הגדול ביותר במערך הנתונים, באופן הבא:

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

חזרה למעלה