Sector Charts¶

Sector charts divide a whole into angular parts, making the total-and-parts relationship visually explicit; this family includes pie charts, donut charts, and polar-area charts. They are most useful when showing simple composition with a small number of categories, especially when the main message is share of a whole rather than precise comparison between similar values.

Dataface sector charts use a small set of top-level shorthand fields. In most cases, you only need query, type: pie, theta, and color to get started.

A chart's control surface is the full set of authored properties available on a single chart. In Dataface, that surface is primarily top-level chart fields plus the typed style object.

This page is intentionally family-oriented rather than exhaustive. For the implementation-backed source of truth, including default ownership and lower-level property coverage, see the Single-Chart Property Catalog.

Minimum Required for a Sector Chart¶

These are the minimum fields required to render a basic sector chart in Dataface.

Dataface field	Maps to Vega-Lite	Allowed values	Notes
`query`	`data.values`	Query name or query reference	Supplies the dataset.
`type: pie`	`mark.type: "arc"`	Literal `pie`	Selects the standard pie form.
`theta`	`encoding.theta.field`	Field name	Numeric field that sets wedge size.
`color`	`encoding.color.field`	Field name	Category field that splits the whole into slices.

Minimum Example¶

charts:
  revenue_share_minimal:
    query: _doc_examples.yaml#sales_by_category
    type: pie
    title: Revenue Share by Category
    theta: revenue
    color: category
rows:
  - revenue_share_minimal

▶

Top-Level Chart Fields¶

These are the top-level chart properties you set directly on a sector chart before you get into nested properties under style.

Dataface field	Maps to Vega-Lite	Allowed values	Notes
`query`	`data.values`	Query name or query reference	Query results become the plotted dataset.
`type: pie`	`mark.type: "arc"`	Literal `pie`	Standard pie chart.
`inner_radius`	`mark.innerRadius`	`0`–`1`	Inner radius ratio. Use `0.5` for a donut appearance.
`title`	`title.text`	String	Chart title.
`description`	metadata	String	Available for tooling and docs.
`theta`	`encoding.theta.field`	Field name	Required wedge-size field.
`color`	`encoding.color.field`	Field name	Category shorthand for slice grouping.
### Pie Forms

This example shows a standard pie alongside a donut (pie with inner_radius: 0.5).

charts:
  revenue_share_pie:
    query: _doc_examples.yaml#sales_by_category
    type: pie
    title: Revenue Share
    theta: revenue
    color: category

  revenue_share_donut:
    query: _doc_examples.yaml#sales_by_category
    type: pie
    inner_radius: 0.5
    title: Revenue Share (Donut)
    theta: revenue
    color: category
rows:
  - revenue_share_pie
  - revenue_share_donut

▶

Composition by Category¶

This example keeps the top-level definition compact while showing a typical composition chart with title, description, theta, and color.

charts:
  revenue_share_composition:
    query: _doc_examples.yaml#sales_by_category
    type: pie
    inner_radius: 0.5
    title: Product Mix
    description: Share of total revenue by product category.
    theta: revenue
    color: category
rows:
  - revenue_share_composition

▶

Style Fields¶

Use style for Dataface shorthand properties that affect presentational defaults such as legend visibility.

Dataface field	Maps to Vega-Lite	Allowed values	Notes
`style.legend`	`encoding.color.legend`	`show` or `hide`	Convenience shorthand for legend display when color is used.
`style.background`	chart SVG background wrapper	Color value	Applies a chart-level background fill behind the rendered SVG.

Legend Visibility¶

This example shows the small style surface for sector charts without changing the underlying data bindings.

charts:
  revenue_share_legend:
    query: _doc_examples.yaml#sales_by_category
    type: pie
    title: Revenue Share with Hidden Legend
    theta: revenue
    color: category
    style:
      legend:
        disable: true
rows:
  - revenue_share_legend

▶

Authored Surface¶

Dataface pie charts are authored with type: pie plus top-level channels such as theta and color. Use inner_radius for a donut appearance. Arbitrary Vega-Lite spec, mark, encoding, config, transform, params, and composition blocks are rejected on the authored surface. Use top-level Dataface fields and the typed style: object.