라이브러리

개요

OJS에서 일반적으로 사용하는 라이브러리는 세 가지 유형입니다.

모든 문서에서 자동으로 사용 가능한 Observable 핵심 라이브러리
npm과 ObservableHQ의 서드파티 JavaScript 라이브러리
여러분이나 동료가 만든 커스텀 라이브러리

이 문서에서는 핵심 라이브러리에 대한 높은 수준의 개요와 서드파티 라이브러리(D3, Arquero) 사용 예제를 제공합니다. 자체 라이브러리 만들기는 코드 재사용 문서에서 다룹니다.

표준 라이브러리

Observable 표준 라이브러리는 콘텐츠 렌더링과 코드/데이터 로딩의 기반이 되는 핵심 기능을 제공합니다. 특히 중요한 구성 요소는 다음과 같습니다.

구성 요소	설명
DOM	DOM 요소를 동적으로 생성
FileAttachments	다양한 형식의 파일 읽기
require	NPM과 GitHub의 서드파티 모듈 가져오기

표준 라이브러리의 전체 문서는 https://github.com/observablehq/stdlib에서 확인할 수 있습니다.

Note

Quarto는 항상 ObservableHQ 런타임의 특정 버전을 내장하므로, 웹사이트의 최신 ObservableHQ 버전보다 뒤처질 수 있습니다. Plot(또는 다른 핵심 라이브러리)의 최신 버전이 필요하다면 import 함수를 사용해 CDN에서 최신 버전을 직접 가져올 수 있습니다. 예를 들면 다음과 같습니다.

Plot = import("https://cdn.jsdelivr.net/npm/@observablehq/plot/+esm")

입력 위젯

Observable inputs 라이브러리는 viewof 키워드를 통해 반응형 표현식에 바인딩할 수 있는 위젯을 제공합니다. 특히 유용한 입력 위젯은 다음과 같습니다.

구성 요소	설명
Radio	상호 배타적인 옵션 중 선택
Checkbox	목록에서 하나 이상 선택
Range	연속 숫자 값을 위한 슬라이더
Select	드롭다운 선택 상자
Table	표에서 하나 이상의 행 선택

입력 위젯의 전체 문서는 https://github.com/observablehq/inputs에서 확인할 수 있습니다.

Plot

Observable Plot은 탐색적 데이터 시각화를 위한 JavaScript 라이브러리입니다. Plot은 사용자 정의 시각화를 만들 수 있도록 결합 가능한 핵심 개념(Marks, Scales, Transforms, Facets) 위에 구성되어 있습니다.

다음은 Plot으로 만든 올림픽 선수 체중 히스토그램 예시입니다.

```{ojs}
athletes = FileAttachment("athletes.csv").csv({typed: true})

Plot.plot({
  grid: true,
  facet: {
    data: athletes,
    y: "sex"
  },
  marks: [
    Plot.rectY(
      athletes, 
      Plot.binX({y: "count"}, {x: "weight", fill: "sex"})
    ),
    Plot.ruleY([0])
  ]
})
```

Observable Plot의 전체 문서는 https://github.com/observablehq/plot에서 확인할 수 있습니다.

D3

D3.js는 데이터를 기반으로 문서를 조작하는 JavaScript 라이브러리입니다. D3는 상상할 수 있는 거의 모든 인터랙티브 그래픽을 만들 수 있습니다!

다음은 D3로 만든 “확대/축소 가능한 선버스트” 다이어그램입니다(원본 공개: https://observablehq.com/@d3/zoomable-sunburst). 한 번에 계층의 두 레이어만 표시됩니다. 노드를 클릭하면 확대되고, 중앙을 클릭하면 축소됩니다.

sunburst = {
  const root = partition(flareData);

  root.each(d => d.current = d);

  const svg = d3.create("svg")
      .attr("viewBox", [0, 0, width, width])
      .style("font", "15px sans-serif");

  const g = svg.append("g")
      .attr("transform", `translate(${width / 2},${width / 2})`);

  const path = g.append("g")
    .selectAll("path")
    .data(root.descendants().slice(1))
    .join("path")
      .attr("fill", d => { while (d.depth > 1) d = d.parent; return color(d.data.name); })
      .attr("fill-opacity", d => arcVisible(d.current) ? (d.children ? 0.6 : 0.4) : 0)
      .attr("d", d => arc(d.current));

  path.filter(d => d.children)
      .style("cursor", "pointer")
      .on("click", clicked);

  path.append("title")
      .text(d => `${d.ancestors().map(d => d.data.name).reverse().join("/")}\n${format(d.value)}`);

  const label = g.append("g")
      .attr("pointer-events", "none")
      .attr("text-anchor", "middle")
      .style("user-select", "none")
    .selectAll("text")
    .data(root.descendants().slice(1))
    .join("text")
      .attr("dy", "0.35em")
      .attr("fill-opacity", d => +labelVisible(d.current))
      .attr("transform", d => labelTransform(d.current))
      .text(d => d.data.name);

  const parent = g.append("circle")
      .datum(root)
      .attr("r", radius)
      .attr("fill", "none")
      .attr("pointer-events", "all")
      .on("click", clicked);

  function clicked(event, p) {
    parent.datum(p.parent || root);

    root.each(d => d.target = {
      x0: Math.max(0, Math.min(1, (d.x0 - p.x0) / (p.x1 - p.x0))) * 2 * Math.PI,
      x1: Math.max(0, Math.min(1, (d.x1 - p.x0) / (p.x1 - p.x0))) * 2 * Math.PI,
      y0: Math.max(0, d.y0 - p.depth),
      y1: Math.max(0, d.y1 - p.depth)
    });

    const t = g.transition().duration(750);

    // Transition the data on all arcs, even the ones that aren’t visible,
    // so that if this transition is interrupted, entering arcs will start
    // the next transition from the desired position.
    path.transition(t)
        .tween("data", d => {
          const i = d3.interpolate(d.current, d.target);
          return t => d.current = i(t);
        })
      .filter(function(d) {
        return +this.getAttribute("fill-opacity") || arcVisible(d.target);
      })
        .attr("fill-opacity", d => arcVisible(d.target) ? (d.children ? 0.6 : 0.4) : 0)
        .attrTween("d", d => () => arc(d.current));

    label.filter(function(d) {
        return +this.getAttribute("fill-opacity") || labelVisible(d.target);
      }).transition(t)
        .attr("fill-opacity", d => +labelVisible(d.target))
        .attrTween("transform", d => () => labelTransform(d.current));
  }
  
  function arcVisible(d) {
    return d.y1 <= 3 && d.y0 >= 1 && d.x1 > d.x0;
  }

  function labelVisible(d) {
    return d.y1 <= 3 && d.y0 >= 1 && (d.y1 - d.y0) * (d.x1 - d.x0) > 0.03;
  }

  function labelTransform(d) {
    const x = (d.x0 + d.x1) / 2 * 180 / Math.PI;
    const y = (d.y0 + d.y1) / 2 * radius;
    return `rotate(${x - 90}) translate(${y},0) rotate(${x < 180 ? 0 : 180})`;
  }

  return svg.node();
}

{ojs} 셀에서 D3를 사용하려면 먼저 require 함수를 사용해 가져옵니다(이 함수는 jsDelivr에 호스팅된 모듈을 로드합니다).

```{ojs}
d3 = require("d3@7")
```

그다음 필요한 대로 d3를 사용해 시각화를 만듭니다. 예를 들어 위의 시각화를 만드는 셀의 첫 부분은 다음과 같습니다.

```{ojs}
sunburst = {
  const root = partition(flareData);
  root.each(d => d.current = d);
  const svg = d3.create("svg")
      .attr("viewBox", [0, 0, width, width])
      .style("font", "15px sans-serif");

  // ...remainder of implementation
  
  return svg.node();
}
```

Sunburst 예제에서 전체 소스 코드를 확인하세요. D3에 대해 더 알아보려면 https://d3js.org/를 방문하세요.

Arquero

Arquero는 배열 기반 데이터 테이블의 쿼리 처리와 변환을 위한 JavaScript 라이브러리입니다. 관계 대수를 따르고 dplyr의 설계에서 영감을 받아, 열 지향 데이터 프레임을 조작하는 유창한 API를 제공합니다.

여기서는 Arquero(aq)와 Arquero 연산의 별칭(op)을 가져온 뒤, 데이터셋을 읽고 필터링, 집계, 조회까지 수행합니다.

```{ojs}
import { aq, op } from '@uwdata/arquero'
penguins = aq.loadCSV("palmer-penguins.csv")
penguins
  .groupby('species')
  .filter(p => p.body_mass_g > 0)
  .rollup({
    count: op.count(),
    avg_mass: op.average('body_mass_g')
   })
  .view()
```

Arquero 예제에서 전체 소스 코드를 확인하세요. Arquero 사용법은 Introducing Arquero 튜토리얼을 참고하세요.

모듈

NPM

표준 라이브러리의 require 함수로 npm 모듈을 가져올 수 있습니다(jsDelivr CDN에서 제공됩니다).

```{ojs}
d3 = require("d3")
topojson = require("topojson")
```

모듈에는 버전과 함께 @ 기호를 포함할 수 있습니다. 예를 들면 다음과 같습니다.

```{ojs}
d3 = require("d3@7")
```

jsDelivr 문서에서 자세한 내용을 확인하세요. require 함수는 import를 해석할 때 https://cdn.jsdelivr.net/npm/ 접두사를 자동으로 붙이므로, jsDeliver 문서에서 다음 URL을 사용하라고 할 때,

https://cdn.jsdelivr.net/npm/package@version/file

require에는 다음처럼 전달하기만 하면 됩니다.

package@version/file

ObservableHQ

http://observablehq.com에 배포된 노트북은 JavaScript 모듈로 컴파일해 내려받을 수도 있습니다.

노트북에는 자체 데이터셋이 포함된 경우가 많지만, 가져올 때 이 데이터를 여러분의 데이터로 바꿀 수 있습니다! 위의 선버스트 예제로 돌아가 보면, 여기서는 노트북을 import하고 with 키워드를 사용해 data에 우리의 값을 제공합니다.

```{ojs}
pdata = FileAttachment("population.json").json()
import { chart } with { pdata as data } from "@d3/zoomable-sunburst"
chart
```

주의해야 할 중요한 제한 사항은 ObservableHQ에 배포된 모든 노트북이 오픈 소스 라이선스를 갖고 있지는 않다는 점입니다. ObservableHQ 밖에서 사용해도 되는지 표시하려면 노트북에 라이선스를 명시적으로 태그해야 합니다.

노트북의 헤더 영역에서 라이선스를 확인할 수 있습니다. 예를 들어 다음 노트북은 ISC 라이선스로 태그되어 있습니다.

ObservableHQ 노트북을 가져오기 전에 라이선스를 확인해야 합니다. 자세한 내용은 노트북 라이선스 문서를 참고하세요.

```{ojs}
flareData = FileAttachment("examples/flare-2.json").json()
```

```{ojs}
partition = flareData => {
  const root = d3.hierarchy(flareData)
      .sum(d => d.value)
      .sort((a, b) => b.value - a.value);
  return d3.partition()
      .size([2 * Math.PI, root.height + 1])
    (root);
}
```

```{ojs}
color = d3.scaleOrdinal(d3.quantize(d3.interpolateRainbow, flareData.children.length + 1))
```

```{ojs}
format = d3.format(",d")
```

```{ojs}
width = 932
```

```{ojs}
radius = width / 6
```

```{ojs}
arc = d3.arc()
    .startAngle(d => d.x0)
    .endAngle(d => d.x1)
    .padAngle(d => Math.min((d.x1 - d.x0) / 2, 0.005))
    .padRadius(radius * 1.5)
    .innerRadius(d => d.y0 * radius)
    .outerRadius(d => Math.max(d.y0 * radius, d.y1 * radius - 1))
```

```{ojs}
d3 = require("d3@7")
```