Keyboard shortcuts

Press ← or → to navigate between chapters

Press ? to show this help

Press Esc to hide this help

Vega Chart 위젯

Vega Chart는 JSON 명세로 Workshop 시각화의 표현과 상호작용을 구성합니다. Vega는 D3 위에서 시각화의 모양과 동작을 선언하는 언어이며, Vega-Lite는 Vega 위에서 일반적인 시각화를 더 간결하게 작성하는 문법입니다.

Chart XY보다 세밀한 표현이 필요할 때 사용할 수 있습니다. 예제에는 2차원 히스토그램 히트맵, 바람 벡터 지도, 월별 손익 워터폴 차트, 임계값을 강조한 막대그래프, 방사형 그래프와 이중 축을 사용하는 중첩 그래프가 있습니다.

이름 붙은 데이터

위젯은 구조체 배열을 시각화의 데이터로 사용합니다. 다음은 데이터 부분의 JSON 형태를 보여 주는 설명용 값입니다. 차트의 mark와 encoding은 뒤의 완전한 명세 예처럼 별도로 구성합니다.

Vega의 data에는 이름과 values를 가진 항목들을 넣습니다.

{
  "data": [
    {
      "name": "nba-player-data",
      "values": [
        { "name": "Michael Jordan", "height-in-inches": 78, "weight-in-lbs": 216 },
        { "name": "Stephen Curry", "height-in-inches": 74, "weight-in-lbs": 185 }
      ]
    }
  ]
}

Vega-Lite는 datasets에 여러 이름을 정의할 수 있습니다.

{
  "datasets": {
    "nba-player-data": [
      { "name": "Michael Jordan", "height-in-inches": 78, "weight-in-lbs": 216 },
      { "name": "Stephen Curry", "height-in-inches": 74, "weight-in-lbs": 185 }
    ],
    "nba-team-data": [
      { "name": "Toronto Raptors", "has-won-championship": true },
      { "name": "Memphis Grizzlies", "has-won-championship": false }
    ]
  }
}

이 예제 행은 데이터 형식을 설명하는 값입니다. 실제 입력은 다음 세 경로로 구성할 수 있습니다.

Workshop 데이터 입력

Object set은 집합과 포함할 객체 속성을 고릅니다.

Aggregation은 집합, group-by 속성과 버킷 방식 및 집계를 지정합니다. 결과의 각 행에는 그룹 속성값과 사용자가 지정한 집계 이름을 키로 한 집계값이 포함됩니다.

Function은 Struct 목록을 반환하는 함수를 선택하여 그 결과를 그대로 데이터로 사용합니다.

여러 입력을 만들고 각 이름으로 명세에서 참조할 수 있습니다. 위젯은 데이터를 명세에 주입하며, 직접 inline 데이터를 넣는 방식도 사용할 수 있습니다.

정량 값과 Long

언어Long의 값 표현
TypeScript v1number이며 @foundry/functions-api에서 가져옵니다.
TypeScript v2string이며 @osdk/functions에서 가져옵니다.
Pythonfunctions.api의 Long은 int에 대응합니다. int로만 선언하면 Integer로 등록되므로 Long이 필요할 때는 해당 별칭을 사용합니다.

TSv2의 Long 문자열을 quantitative 축에 바로 연결하면 기대한 숫자 표시가 되지 않을 수 있습니다. Double, Integer와 Float는 두 TypeScript 버전에서 number입니다. 정량 축에 사용할 숫자 자료형을 선택하고 큰 정수를 변환할 때는 보존할 정밀도를 먼저 정합니다.

실제 객체 집합을 Struct 목록으로 변환

아래 예는 가상의 Company 유형에 String name, Double marketCap과 선택적인 String logoUrl이 있다고 가정합니다. 실제 저장소의 생성 SDK에 해당 유형과 속성을 준비해야 합니다. 이름이나 시가총액이 없으면 그 행은 제외하고, 로고가 없는 경우에는 선택 값으로 남깁니다.

반환 JSON의 필드 이름을 name, marketCap과 logoUrl로 맞춥니다. Python에서도 이 출력 계약의 이름을 사용하며 입력 객체의 속성은 생성 SDK의 snake_case 이름으로 읽습니다.

TypeScript v1

import { Double, Function } from "@foundry/functions-api";
import { Company, ObjectSet } from "@foundry/ontology-api";

interface CompanyData {
    name: string;
    marketCap: Double;
    logoUrl?: string;
}

export class CompanyChartFunctions {
    @Function()
    public companyVegaData(companies: ObjectSet<Company>): CompanyData[] {
        const rows: CompanyData[] = [];
        for (const company of companies.all()) {
            if (company.name == null || company.marketCap == null) continue;
            rows.push({ name: company.name, marketCap: company.marketCap, logoUrl: company.logoUrl });
        }
        return rows;
    }
}

TypeScript v2

import { ObjectSet } from "@osdk/client";
import { Double } from "@osdk/functions";
import { Company } from "@ontology/sdk";

interface CompanyData {
    name: string;
    marketCap: Double;
    logoUrl?: string;
}

export default async function companyVegaData(
    companies: ObjectSet<Company>,
): Promise<CompanyData[]> {
    const rows: CompanyData[] = [];
    for await (const company of companies.asyncIter({ $select: ["name", "marketCap", "logoUrl"] })) {
        if (company.name == null || company.marketCap == null) continue;
        rows.push({ name: company.name, marketCap: company.marketCap, logoUrl: company.logoUrl });
    }
    return rows;
}

Python

from dataclasses import dataclass
from typing import Optional
from functions.api import Double, function
from ontology_sdk.ontology.object_sets import CompanyObjectSet


@dataclass
class CompanyData:
    name: str
    marketCap: Double
    logoUrl: Optional[str]


@function
def company_vega_data(companies: CompanyObjectSet) -> list[CompanyData]:
    rows: list[CompanyData] = []
    for company in companies.iterate():
        if company.name is None or company.market_cap is None:
            continue
        rows.append(CompanyData(
            name=company.name,
            marketCap=company.market_cap,
            logoUrl=company.logo_url,
        ))
    return rows

함수를 게시하고 Function 데이터 입력에서 선택한 뒤 companies에 실제 객체 집합 변수를 연결합니다. 데이터 입력의 이름을 company-data로 정합니다. 객체를 목록으로 반환하는 로드 비용과 함수의 객체 처리 한도도 고려합니다.

명세와 문법 선택

Specification에는 JSON을 직접 쓰거나 String 변수로 제공할 수 있습니다. Vega 또는 Vega-Lite 중 사용할 문법을 선택합니다. 이 위젯은 Vega-Lite 5.18을 사용합니다.

일반 차트와 selection parameters에는 Vega-Lite를, 더 복잡한 사용자 정의 시각화에는 Vega를 검토합니다.

앞의 company-data 입력을 구성한 뒤 Vega-Lite 명세 칸에 다음 전체 JSON을 사용할 수 있습니다. 시가총액을 숫자 X축으로 표시하고 X축 구간 선택을 정의합니다.

{
  "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
  "data": { "name": "company-data" },
  "mark": "bar",
  "params": [
    {
      "name": "intervalSelection",
      "select": { "type": "interval", "encodings": ["x"] }
    }
  ],
  "encoding": {
    "x": { "field": "marketCap", "type": "quantitative", "title": "Market cap" },
    "y": { "field": "name", "type": "nominal", "sort": "-x" },
    "tooltip": [
      { "field": "name", "type": "nominal" },
      { "field": "marketCap", "type": "quantitative" }
    ]
  }
}

Theme

기본 theme은 Chart XY의 Blueprint 표현에 맞춥니다. String 변수로 사용자 theme을 제공하거나 theme 주입을 끌 수도 있습니다.

기본 theme을 수정하려면 Inline editor의 Preview에서 주입된 config를 확인하고 필요한 값을 바꾸어 명세에 넣습니다.

AIP로 명세 작성

필요한 입력을 구성한 뒤 AIP에 초기 차트를 요청하고 후속 지시로 수정할 수 있습니다. 예를 들어 선수의 평균 경기당 득점과 시즌 수가 있는 별도 농구 데이터에서는 다음과 같이 요청할 수 있습니다.

Make me a bar chart of average points per game, bucketed by the number of seasons played.


Remove the gridlines from this chart, and only show number of seasons greater than 4.

원하는 결과가 아니면 명세를 직접 편집합니다. 예제 명세를 사용할 때는 예제 데이터 참조를 자신의 입력 이름과 실제 필드에 맞춥니다.

Preview와 외부 편집기

Preview는 입력 데이터와 theme을 주입한 전체 명세를 보여 줍니다. 읽기 쉽게 데이터를 잘라 표시하고 전체 명세를 클립보드에 복사할 수 있습니다.

온라인 Vega Editor로 옮길 때에는 명세 안에 실제 데이터가 포함된다는 점을 고려합니다. 행 수를 줄이는 것은 익명화가 아니므로 필요한 경우 민감한 값을 가상 데이터로 바꾸고 반출 정책에 맞춰 사용합니다. 복사한 설정과 데이터는 외부 편집기로 전송될 수 있습니다.

Selection parameters

이 기능은 Vega-Lite에만 제공합니다. 위젯에서 매개변수 이름과 출력 변수를 여러 개 구성할 수 있으며 출력은 Object Set Filter 또는 String입니다.

선택 정의는 명세의 여러 위치에 둘 수 있어 자동 주입하지 않습니다. 위젯에 구성한 이름마다 명세 안에도 같은 이름의 params를 작성해야 합니다. 위의 전체 명세는 intervalSelection을 사용하므로 위젯에도 그 이름으로 출력 변수를 연결합니다.

객체 집합과 속성을 직접 사용하거나 group-by 집계를 입력으로 쓰면 선택을 Object Set Filter로 변환할 수 있는 경우가 많습니다. 다른 선택은 Vega-Lite가 반환한 JSON을 String 변수로 받아 함수나 변수 변환에서 처리할 수 있습니다. 위의 함수 기반 company-data 예는 String 출력으로 선택 결과를 받는 구성입니다.