Calendar Heatmap

설명 / Description

캘린더 히트맵은 달력의 구조를 그대로 본뜬 격자 위에 데이터를 배치합니다: 열은 주(week)를, 행은 요일(월요일부터 일요일까지)을 나타내며, 각 셀은 해당 날짜의 값 크기에 따라 색이 칠해집니다. 그 결과 일별 패턴, 주간 리듬, 계절적 추세, 이상치를 한눈에 드러내는 조밀하고 친숙한 레이아웃이 만들어집니다. 이 차트 형태는 깃허브(GitHub)의 기여 그래프(contribution graph)로 대중화되었으며, 이후 시간에 따른 활동을 보여주는 널리 알려진 방식이 되었습니다.

A calendar heatmap arranges data on a grid that mirrors the structure of a calendar: columns represent weeks, rows represent days of the week (Monday through Sunday), and each cell is colored by the magnitude of a value for that day. The result is a dense, familiar layout that reveals daily patterns, weekly rhythms, seasonal trends, and anomalies at a glance. This chart form was popularized by GitHub's contribution graph and has since become a widely recognized way to show activity over time.

달력 레이아웃은 두 가지 강력한 지각 메커니즘을 동시에 활용합니다. 첫째, 격자의 공간적 규칙성 덕분에 군집, 연속된 흐름, 공백을 쉽게 알아볼 수 있습니다 — 활동이 많은 한 주는 밝은 세로 띠로 나타나고, 평일과 주말의 차이는 가로 줄무늬로 드러납니다. 둘째, 달력이라는 은유는 누구나 보편적으로 이해하기 때문에, 독자는 축을 따로 확인하지 않고도 셀을 곧바로 특정 날짜와 연결할 수 있습니다.

The calendar layout leverages two powerful perceptual mechanisms simultaneously. First, the spatial regularity of the grid makes it easy to spot clusters, streaks, and gaps -- a week of high activity appears as a bright vertical band, while weekday vs. weekend differences emerge as horizontal stripes. Second, the calendar metaphor is universally understood, so readers can immediately map cells to specific dates without consulting an axis.

캘린더 히트맵은 몇 달에서 몇 년에 걸친 기간의 일별 단위 데이터에 가장 잘 어울립니다. 요일 효과, 공휴일로 인한 감소, 계절적 주기, 연도별 비교처럼 달력 구조 자체와 결부된 패턴을 보여주는 데 특히 강점을 발휘합니다. 더 세밀한 단위(시간별)나 더 거친 단위(월별) 데이터에는 선 그래프나 일반 히트맵 같은 다른 차트 형태가 더 적합합니다.

Calendar heatmaps work best for data with daily granularity over periods of months to a few years. They excel at showing patterns that are tied to the calendar structure itself: day-of-week effects, holiday dips, seasonal cycles, and year-over-year comparisons. For data at finer granularity (hourly) or coarser granularity (monthly), other chart forms like line graphs or standard heatmaps are more appropriate.

언제 사용하나 / When to Use

• 1년 이상에 걸친 일별 활동, 기여, 이벤트를 보여줄 때
• Showing daily activity, contributions, or events over a year or more
• 요일 패턴, 계절적 추세, 공휴일 효과를 드러낼 때
• Revealing day-of-week patterns, seasonal trends, and holiday effects
• 습관, 운동, 커밋, 매출 등 일별 단위로 측정되는 지표를 추적할 때
• Tracking habits, exercise, commits, sales, or any metric with daily granularity
• 달력이라는 은유가 맥락을 더해줄 때(독자가 구체적인 날짜에 관심을 가질 때)
• When the calendar metaphor adds context (readers care about specific dates)

이럴 땐 피하세요 / When NOT to Use

• 하루보다 세밀한 데이터(시간별, 분 단위)의 경우 -- 시/분 축을 사용하는 히트맵을 사용하세요
• For sub-daily data (hourly, minute-level) -- use a heatmap with hour/minute axes
• 패턴 감지보다 정확한 값 비교가 더 중요할 때 -- 선 그래프나 막대 차트를 사용하세요
• When precise value comparison matters more than pattern detection -- use a line graph or bar chart
• 일 단위 해상도로 여러 해에 걸친 데이터의 경우 -- 차트가 매우 넓어지므로 연도별 패널로 나누는 것을 고려하세요
• For data spanning many years at daily resolution -- the chart becomes very wide; consider year-by-year panels
• 데이터에 의미 있는 요일별 또는 계절적 구조가 없을 때 -- 달력 레이아웃이 추가적인 통찰을 주지 못합니다
• When the data has no meaningful day-of-week or seasonal structure -- the calendar layout adds no insight

구조 / Anatomy

• 일별 셀: 하루당 하나씩 표시되는 작은 사각형 또는 둥근 정사각형으로, 값의 강도에 따라 색이 칠해집니다.
• Day cells: Small rectangles or rounded squares, one per day, colored by value intensity.
• 주 단위 열: 연중 각 주마다 7개의 셀이 세로로 쌓인 열입니다.
• Week columns: Vertical stacks of 7 cells, one per week of the year.
• 요일 행: 평일과 주말을 비교할 수 있게 해주는 가로 정렬 그룹(월-일)입니다.
• Day-of-week rows: Horizontal alignment groups (Mon-Sun) enabling weekday/weekend comparison.
• 월 레이블: 격자 위나 아래에 표시되어 월의 경계를 나타내는 텍스트입니다.
• Month labels: Text above or below the grid marking month boundaries.
• 색상 스케일: 낮은 값에서 높은 값까지를 매핑하는 순차적 스케일(밝은색에서 어두운색으로)입니다. 범례는 필수적입니다.
• Color scale: A sequential scale (light to dark) mapping low to high values. A legend is essential.
• 연도 레이블: 달력이 다루는 연도(또는 날짜 범위)를 표시합니다.
• Year label: Identifies which year (or date range) the calendar covers.

변형 / Variations

• 다년도 캘린더: 여러 해를 세로로 쌓아 연도별 비교를 가능하게 합니다.
• Multi-year calendar: Multiple years stacked vertically for year-over-year comparison.
• 원형 캘린더: 순환적 패턴을 강조하기 위해 날짜를 나선형이나 방사형으로 배치합니다.
• Circular calendar: Days arranged in a spiral or radial layout to emphasize cyclical patterns.
• 범주형 캘린더: 연속적인 스케일 대신 카테고리(예: 활동 유형)에 따라 셀에 색을 입힙니다.
• Categorical calendar: Cells colored by category (e.g., type of activity) rather than a continuous scale.
• 인터랙티브 캘린더: 셀을 클릭하면 해당 날짜의 상세 데이터가 표시되거나, 브러싱으로 날짜 범위를 선택할 수 있습니다.
• Interactive calendar: Clicking a cell shows detailed data for that day, or brushing selects a range of days.
• 월별 격자 캘린더: 연속적인 주 단위 열 대신 월별 격자로 셀을 배치하는 전통적인 달력 레이아웃입니다.
• Month-grid calendar: A traditional calendar layout with cells arranged by month grids rather than continuous week columns.

코드 레퍼런스 / Code Reference

// Observable Plot - calendar heatmap
Plot.plot({
  marks: [
    Plot.cell(data, {
      x: d => d3.utcWeek.count(d3.utcYear(d.date), d.date),
      y: d => d.date.getUTCDay(),
      fill: "value",
      tip: true,
      inset: 0.5
    })
  ],
  x: { axis: null },
  y: {
    tickFormat: d => ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"][d],
    label: null
  },
  color: {
    scheme: "Greens",
    legend: true,
    label: "Contributions"
  }
})