# Paired series

`PairedSeries` connects two supplied outcomes in each wide record. Both
endpoints must be observed; an incomplete pair contributes no segment. It does
not match subjects across tables, calculate change, or replace missing outcomes.
Compose `PointSeries` for endpoint circles, including unpaired observations.

```tsx
import { PairedSeries } from "@pibbl/core/viz";
const participants = [
  { id: "P01", baseline: 62, week12: 44 },
  { id: "P02", baseline: 58, week12: null },
];
<PairedSeries
  data={participants}
  before="baseline"
  after="week12"
  beforeX="Baseline"
  afterX="Week 12"
  xScale="endpoint"
  yScale="score"
  style={{ stroke: "#087f8c" }}
/>;
```

Required props are `data`, `before`, `after`, `beforeX`, `afterX`, `xScale`,
and `yScale`. Outcome accessors are numeric field keys or synchronous callbacks.
Endpoint x coordinates are explicit numeric or PointScale category positions.
Missing or nonfinite outcomes omit the entire pair. Unknown PointScale endpoint categories throw under the standard series coordinate contract; continuous x coordinates must be numeric. `defined` excludes a record
before outcome accessors run. Lines retain source encounter order.

Shared `style` supports `stroke` (default `#2563eb`), `strokeWidth` (default
2 local units), `opacity` (default 1), `cursor`, and `lineInteractionWidth`
(default stroke width). Whole-object and shallow field signals schedule updates.
Each component returns one batched ordinary Pibbl Path, with standard events and
`pointerEvents`. Events do not infer a participant or datum. Accessors are
synchronous and cannot call hooks or write signals. The component owns no
retained resources or statistical state.

## API details from source

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

### PairedSeries

Draws a connector for each complete wide-record before/after pair.

The component does not manufacture point marks, calculate change, select a
baseline, or impute missing observations. Compose `PointSeries` for endpoints.

```ts
PairedSeries: <D>({ data: input, before: beforeInput, after: afterInput, beforeX, afterX, xScale: xId, yScale: yId, defined, style: styleInput, ...events }: PairedSeriesProps<D>) => JSX.Element
```

Related API: [PairedSeries](/reference/components/paired-series/), [PairedSeriesProps](/reference/components/paired-series/), [JSX](/reference/overview/).

#### Parameters

- **`props`** — Wide records, endpoint accessors and coordinates, scales, and shared paint.

#### Returns

One batched ordinary Pibbl path containing source-ordered pair connectors.

#### See also

[PairedSeriesProps](/reference/components/paired-series/)

[View source — packages/core/src/features/viz/lib/paired-series.tsx:109](/source/packages/core/src/features/viz/lib/paired-series-tsx/#L109)

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

### PairedSeriesProps

Authored wide-record inputs for PairedSeries.

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

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

[View source — packages/core/src/features/viz/lib/paired-series.tsx:24](/source/packages/core/src/features/viz/lib/paired-series-tsx/#L24)

#### Properties and methods

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


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

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

Source records or a signal containing them.

[View source — packages/core/src/features/viz/lib/paired-series.tsx:27](/source/packages/core/src/features/viz/lib/paired-series-tsx/#L27)

</details>

<span id="api-PairedSeriesProps-before"></span>
<details>
<summary>before</summary>


```ts
readonly before: LineAccessor<D>
```

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

Numeric baseline or first-observation value.

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

</details>

<span id="api-PairedSeriesProps-after"></span>
<details>
<summary>after</summary>


```ts
readonly after: LineAccessor<D>
```

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

Numeric follow-up or second-observation value.

[View source — packages/core/src/features/viz/lib/paired-series.tsx:31](/source/packages/core/src/features/viz/lib/paired-series-tsx/#L31)

</details>

<span id="api-PairedSeriesProps-beforeX"></span>
<details>
<summary>beforeX</summary>


```ts
readonly beforeX: SeriesCoordinate
```

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

Fixed x coordinate used for every `before` endpoint.

[View source — packages/core/src/features/viz/lib/paired-series.tsx:33](/source/packages/core/src/features/viz/lib/paired-series-tsx/#L33)

</details>

<span id="api-PairedSeriesProps-afterX"></span>
<details>
<summary>afterX</summary>


```ts
readonly afterX: SeriesCoordinate
```

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

Fixed x coordinate used for every `after` endpoint.

[View source — packages/core/src/features/viz/lib/paired-series.tsx:35](/source/packages/core/src/features/viz/lib/paired-series-tsx/#L35)

</details>

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


```ts
readonly xScale: ScaleId
```

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

Scale mapping the two endpoint coordinates.

[View source — packages/core/src/features/viz/lib/paired-series.tsx:37](/source/packages/core/src/features/viz/lib/paired-series-tsx/#L37)

</details>

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


```ts
readonly yScale: ScaleId
```

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

Numeric scale mapping both endpoint values.

[View source — packages/core/src/features/viz/lib/paired-series.tsx:39](/source/packages/core/src/features/viz/lib/paired-series-tsx/#L39)

</details>

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


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

Excludes a record before before/after accessors run.

##### Parameters

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

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

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

##### Returns

Whether this record contributes a connector.

[View source — packages/core/src/features/viz/lib/paired-series.tsx:47](/source/packages/core/src/features/viz/lib/paired-series-tsx/#L47)

</details>

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


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

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

Shared connector style, including whole-object and shallow field signals.

[View source — packages/core/src/features/viz/lib/paired-series.tsx:49](/source/packages/core/src/features/viz/lib/paired-series-tsx/#L49)

</details>

<span id="api-PairedSeriesProps-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-PairedSeriesStyle"></span>

### PairedSeriesStyle

Shared connector appearance for PairedSeries.

```ts
type PairedSeriesStyle = TrajectorySeriesStyle
```

Related API: [PairedSeriesStyle](/reference/components/paired-series/), [TrajectorySeriesStyle](/reference/components/trajectory-series/).

[View source — packages/core/src/features/viz/lib/paired-series.tsx:21](/source/packages/core/src/features/viz/lib/paired-series-tsx/#L21)

#### Properties and methods

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


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

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

Path paint. Defaults to `#2563eb`.

[View source — packages/core/src/features/viz/lib/trajectory-series.tsx:23](/source/packages/core/src/features/viz/lib/trajectory-series-tsx/#L23)

</details>

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


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

Visible path width in local units. Defaults to 2.

[View source — packages/core/src/features/viz/lib/trajectory-series.tsx:25](/source/packages/core/src/features/viz/lib/trajectory-series-tsx/#L25)

</details>

<span id="api-PairedSeriesStyle-lineInteractionWidth"></span>
<details>
<summary>lineInteractionWidth (optional)</summary>


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

Pointer targeting width. Defaults to `strokeWidth`.

[View source — packages/core/src/features/viz/lib/trajectory-series.tsx:27](/source/packages/core/src/features/viz/lib/trajectory-series-tsx/#L27)

</details>

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


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

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

Path opacity in [0, 1]. Defaults to 1.

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

</details>

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


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

Cursor while the batched path owns pointer presentation.

[View source — packages/core/src/features/viz/lib/trajectory-series.tsx:31](/source/packages/core/src/features/viz/lib/trajectory-series-tsx/#L31)

</details>

## 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

- [Complete paired endpoint connectors](/minimal-examples/viz/paired-series/): Complete paired endpoint connectors. [Plain source](/minimal/viz/paired-series.tsx)
## Documentation version

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