# Weighted point series

`WeightedPointSeries` maps x and y observations and converts a supplied weight to
circle area. It does not calculate precision, sample size, effect estimates, or
any statistical summary.

```tsx
import { WeightedPointSeries } from "@pibbl/core/viz";
const assayObservations = [{ concentration: 1, inhibition: 49, precision: 64 }];
<WeightedPointSeries
  data={assayObservations}
  x="concentration"
  y="inhibition"
  weight="precision"
  xScale="concentration"
  yScale="inhibition"
  weightDomain={[0, 100]}
  radiusRange={[0, 10]}
/>;
```

Required props are `data`, `x`, `y`, `weight`, `xScale`, `yScale`, and
`weightDomain`. Coordinate and weight accessors are field keys or synchronous
callbacks. Both coordinate scales follow `PointSeries`: each can be continuous
or categorical where supported by the selected scale.

`weightDomain` is `[0, maximum]`, where `maximum` is finite and positive. The
zero baseline is required so a mark's area is proportional to its supplied
weight. `radiusRange` is `[0, maximumRadius]` and defaults to `[0, 6]` local
units. The radius is `maximumRadius * sqrt(weight / maximum)`. A zero or nullish
weight omits a mark; negative, nonfinite, and out-of-domain weights throw. The
component never clamps or infers a weight.

`style` is shared across marks and supports whole-object and shallow signals.
Its fields are `fill` (default `#087f8c`), `stroke`, `strokeWidth` (default 1),
`opacity` (default 1), and `cursor`. Radius is intentionally derived only from
weight. `defined` omits a record before other accessors run. Missing coordinates
omit that record under the ordinary series contract.

Marks retain source paint order and are batched into one ordinary Pibbl pointer
target. Series event handlers receive ordinary bubbled events rather than an
inferred datum. Use `pointerEvents="none"` for decorative points. Signals update
on Pibbl's scheduler; the component owns no retained resources or inference
state.

## API details from source

<span id="api-WeightedPointSeries"></span>

### WeightedPointSeries

Draws batched circles whose visible area is proportional to supplied weights.

Nullish weights and zero weights omit their marks. Finite positive weights must
fall inside `weightDomain`; the component never clamps or infers weights.
`data` and shared style signals schedule ordinary Pibbl updates. The component
owns no retained resources and returns one ordinary Pibbl pointer target.

```ts
WeightedPointSeries: <D>({ data: input, x: xInput, y: yInput, weight: weightInput, xScale: xId, yScale: yId, weightDomain, radiusRange, defined, style: styleInput, ...events }: WeightedPointSeriesProps<D>) => JSX.Element
```

Related API: [WeightedPointSeries](/reference/components/weighted-point-series/), [WeightedPointSeriesProps](/reference/components/weighted-point-series/), [JSX](/reference/overview/).

#### Parameters

- **`props`** — Supplied observations, coordinate and weight accessors, scales, and paint.
See [WeightedPointSeriesProps](/reference/components/weighted-point-series/).

#### Returns

One batched Pibbl Path whose mark area is proportional to each supplied weight.

#### See also

[WeightedPointSeriesProps](/reference/components/weighted-point-series/)

[View source — packages/core/src/features/viz/lib/weighted-point-series.tsx:175](/source/packages/core/src/features/viz/lib/weighted-point-series-tsx/#L175)

<span id="api-WeightedPointSeriesProps"></span>

### WeightedPointSeriesProps

Authored inputs for WeightedPointSeries.

Weights are supplied data, not calculated precision, sample size, or evidence.
The zero baseline and squared-radius interpolation make displayed area linear in
the supplied weight.

```ts
interface WeightedPointSeriesProps<D> extends PibblEventHandlers, PibblEventParticipationOptions
```

Related API: [WeightedPointSeriesProps](/reference/components/weighted-point-series/), [PibblEventHandlers](/reference/types/events/#pibbleventhandlers), [PibblEventParticipationOptions](/reference/types/events/#pibbleventparticipationoptions).

[View source — packages/core/src/features/viz/lib/weighted-point-series.tsx:52](/source/packages/core/src/features/viz/lib/weighted-point-series-tsx/#L52)

#### Properties and methods

<span id="api-WeightedPointSeriesProps-data"></span>
<details>
<summary>data</summary>


```ts
readonly data: SignalValue<readonly D[]>
```

Related API: [SignalValue](/reference/types/signal-inputs/#signalvalue).

Readonly data or a signal containing it.

[View source — packages/core/src/features/viz/lib/weighted-point-series.tsx:55](/source/packages/core/src/features/viz/lib/weighted-point-series-tsx/#L55)

</details>

<span id="api-WeightedPointSeriesProps-x"></span>
<details>
<summary>x</summary>


```ts
readonly x: SeriesAccessor<D>
```

Related API: [SeriesAccessor](/reference/components/line-series/).

Horizontal coordinate property or synchronous accessor.

[View source — packages/core/src/features/viz/lib/weighted-point-series.tsx:57](/source/packages/core/src/features/viz/lib/weighted-point-series-tsx/#L57)

</details>

<span id="api-WeightedPointSeriesProps-y"></span>
<details>
<summary>y</summary>


```ts
readonly y: SeriesAccessor<D>
```

Related API: [SeriesAccessor](/reference/components/line-series/).

Vertical coordinate property or synchronous accessor.

[View source — packages/core/src/features/viz/lib/weighted-point-series.tsx:59](/source/packages/core/src/features/viz/lib/weighted-point-series-tsx/#L59)

</details>

<span id="api-WeightedPointSeriesProps-weight"></span>
<details>
<summary>weight</summary>


```ts
readonly weight: WeightAccessor<D>
```

Related API: [WeightAccessor](/reference/components/weighted-point-series/).

Nonnegative supplied weight property or synchronous accessor.

[View source — packages/core/src/features/viz/lib/weighted-point-series.tsx:61](/source/packages/core/src/features/viz/lib/weighted-point-series-tsx/#L61)

</details>

<span id="api-WeightedPointSeriesProps-xScale"></span>
<details>
<summary>xScale</summary>


```ts
readonly xScale: ScaleId
```

Related API: [ScaleId](/reference/components/scale/).

Scale used to map x coordinates.

[View source — packages/core/src/features/viz/lib/weighted-point-series.tsx:63](/source/packages/core/src/features/viz/lib/weighted-point-series-tsx/#L63)

</details>

<span id="api-WeightedPointSeriesProps-yScale"></span>
<details>
<summary>yScale</summary>


```ts
readonly yScale: ScaleId
```

Related API: [ScaleId](/reference/components/scale/).

Scale used to map y coordinates.

[View source — packages/core/src/features/viz/lib/weighted-point-series.tsx:65](/source/packages/core/src/features/viz/lib/weighted-point-series-tsx/#L65)

</details>

<span id="api-WeightedPointSeriesProps-weightDomain"></span>
<details>
<summary>weightDomain</summary>


```ts
readonly weightDomain: readonly [0, number]
```

Supplied inclusive weight extent. The lower bound must be zero.

[View source — packages/core/src/features/viz/lib/weighted-point-series.tsx:67](/source/packages/core/src/features/viz/lib/weighted-point-series-tsx/#L67)

</details>

<span id="api-WeightedPointSeriesProps-radiusRange"></span>
<details>
<summary>radiusRange (optional)</summary>


```ts
readonly radiusRange?: readonly [0, number] | undefined
```

Radius extent `[0, maximumRadius]`; defaults to `[0, 6]`.

[View source — packages/core/src/features/viz/lib/weighted-point-series.tsx:69](/source/packages/core/src/features/viz/lib/weighted-point-series-tsx/#L69)

</details>

<span id="api-WeightedPointSeriesProps-defined"></span>
<details>
<summary>defined (optional)</summary>


```ts
readonly defined?: ((datum: D, index: number, data: readonly D[]) => boolean) | undefined
```

Excludes a datum before coordinate and weight accessors run.

##### Parameters

- **`datum`** — Candidate source datum.

- **`index`** — Zero-based source index.

- **`data`** — Complete source data array.

##### Returns

Whether this datum contributes a mark.

[View source — packages/core/src/features/viz/lib/weighted-point-series.tsx:77](/source/packages/core/src/features/viz/lib/weighted-point-series-tsx/#L77)

</details>

<span id="api-WeightedPointSeriesProps-style"></span>
<details>
<summary>style (optional)</summary>


```ts
readonly style?: SignalValue<Readonly<{ readonly fill?: SignalValue<FillStyle | undefined>; readonly stroke?: SignalValue<StrokeStyle | undefined>; readonly strokeWidth?: SignalValue<number | undefined>; readonly opacity?: SignalValue<number | undefined>; readonly cursor?: SignalValue<string | undefined>; }>> | undefined
```

Related API: [SignalValue](/reference/types/signal-inputs/#signalvalue), [FillStyle](/reference/types/styles/#fillstyle), [StrokeStyle](/reference/types/styles/#strokestyle), [opacity](/reference/types/filters/#opacity).

Shared presentation. Whole-object and shallow field signals are supported.

[View source — packages/core/src/features/viz/lib/weighted-point-series.tsx:79](/source/packages/core/src/features/viz/lib/weighted-point-series-tsx/#L79)

</details>

<span id="api-WeightedPointSeriesProps-pointerEvents"></span>
<details>
<summary>pointerEvents (optional)</summary>


```ts
readonly pointerEvents?: PibblPointerEvents | undefined
```

Related API: [PibblPointerEvents](/reference/types/events/#pibblpointerevents).

Whether this content participates in pointer targeting. See PibblPointerEvents.

[View source — packages/core/src/lib/events/types.ts:126](/source/packages/core/src/lib/events/types-ts/#L126)

</details>

<span id="api-WeightedPointSeriesStyle"></span>

### WeightedPointSeriesStyle

Shared presentation for WeightedPointSeries.

```ts
interface WeightedPointSeriesStyle
```

Related API: [WeightedPointSeriesStyle](/reference/components/weighted-point-series/).

[View source — packages/core/src/features/viz/lib/weighted-point-series.tsx:32](/source/packages/core/src/features/viz/lib/weighted-point-series-tsx/#L32)

#### Properties and methods

<span id="api-WeightedPointSeriesStyle-fill"></span>
<details>
<summary>fill (optional)</summary>


```ts
readonly fill?: FillStyle | undefined
```

Related API: [FillStyle](/reference/types/styles/#fillstyle).

Paint used for point interiors. Defaults to `#087f8c`.

[View source — packages/core/src/features/viz/lib/weighted-point-series.tsx:34](/source/packages/core/src/features/viz/lib/weighted-point-series-tsx/#L34)

</details>

<span id="api-WeightedPointSeriesStyle-stroke"></span>
<details>
<summary>stroke (optional)</summary>


```ts
readonly stroke?: StrokeStyle | undefined
```

Related API: [StrokeStyle](/reference/types/styles/#strokestyle).

Paint used for point outlines. Defaults to no outline.

[View source — packages/core/src/features/viz/lib/weighted-point-series.tsx:36](/source/packages/core/src/features/viz/lib/weighted-point-series-tsx/#L36)

</details>

<span id="api-WeightedPointSeriesStyle-strokeWidth"></span>
<details>
<summary>strokeWidth (optional)</summary>


```ts
readonly strokeWidth?: number | undefined
```

Outline width in local coordinate units. Defaults to 1.

[View source — packages/core/src/features/viz/lib/weighted-point-series.tsx:38](/source/packages/core/src/features/viz/lib/weighted-point-series-tsx/#L38)

</details>

<span id="api-WeightedPointSeriesStyle-opacity"></span>
<details>
<summary>opacity (optional)</summary>


```ts
readonly opacity?: number | undefined
```

Related API: [opacity](/reference/types/filters/#opacity).

Opacity in the inclusive range [0, 1]. Defaults to 1.

[View source — packages/core/src/features/viz/lib/weighted-point-series.tsx:40](/source/packages/core/src/features/viz/lib/weighted-point-series-tsx/#L40)

</details>

<span id="api-WeightedPointSeriesStyle-cursor"></span>
<details>
<summary>cursor (optional)</summary>


```ts
readonly cursor?: string | undefined
```

Pointer cursor while the series owns a target.

[View source — packages/core/src/features/viz/lib/weighted-point-series.tsx:42](/source/packages/core/src/features/viz/lib/weighted-point-series-tsx/#L42)

</details>

<span id="api-WeightAccessor"></span>

### WeightAccessor

A data property or callback extracting a nonnegative research weight.

```ts
type WeightAccessor<D> = LineAccessor<D>
```

Related API: [WeightAccessor](/reference/components/weighted-point-series/), [LineAccessor](/reference/components/line-series/).

#### See also

[WeightedPointSeriesProps](/reference/components/weighted-point-series/)

[View source — packages/core/src/features/viz/lib/weighted-point-series.tsx:29](/source/packages/core/src/features/viz/lib/weighted-point-series-tsx/#L29)

## Implementation guidance for agents

Read the [Data visualization companion](/agents/topics/visualization/) for ownership, adaptation, failure modes, and verification. [Agent start](/agents/) provides the version-selection workflow.

## Complete minimal examples

- [Supplied weights mapped to marker area](/minimal-examples/viz/weighted-point-series/): Supplied weights mapped to marker area. [Plain source](/minimal/viz/weighted-point-series.tsx)
## Documentation version

Documentation built with @pibbl/core 0.0.2, revision dd39ce2. ALPHA — NOT FOR PRODUCTION USE.