Trajectory series

Read as Markdown

TrajectorySeries draws separate participant paths from interleaved long-form records. group is a string/number field or synchronous accessor. Each group’s source order is preserved; the component never sorts visits or calculates a summary. Supply rows for missed scheduled visits with null coordinates so the path breaks. An absent row cannot communicate that a scheduled visit was missed.

import { TrajectorySeries } from "@pibbl/core/viz";
const visits = [
  { participant: "P01", week: 0, change: 0 },
  { participant: "P01", week: 4, change: null },
  { participant: "P01", week: 12, change: -18 },
];
<TrajectorySeries
  data={visits}
  group="participant"
  x="week"
  y="change"
  xScale="week"
  yScale="change"
  style={{ stroke: "#087f8c" }}
/>;

Required props are data, group, x, y, xScale, and yScale. X coordinates use continuous numeric or categorical PointScale positions; y outcomes use numeric scales. Missing or nonfinite coordinates split only their group’s current run; one-point runs have no connecting segment. Nullish group keys omit a row. Other group keys must be strings or finite numbers. defined=false breaks the identified group’s run before coordinate accessors are evaluated.

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

TrajectorySeries

Draws one shared-style path connecting each participant or specimen trajectory.

A missing, excluded, or non-finite coordinate ends only that group’s current run. Interleaved groups retain their source encounter order; trajectories are never sorted by either actual or scheduled time.

TrajectorySeries: <D>({ data: input, group: groupInput, x: xInput, y: yInput, xScale: xId, yScale: yId, defined, style: styleInput, ...events }: TrajectorySeriesProps<D>) => JSX.Element

Related API: TrajectorySeries, TrajectorySeriesProps, JSX.

Parameters

• props — Observations, identities, coordinates, scales, and shared path paint.

Returns

One batched ordinary Pibbl path containing source-ordered trajectory segments.

See also

TrajectorySeriesProps

View source — packages/core/src/features/viz/lib/trajectory-series.tsx:148

TrajectorySeriesProps

Authoring inputs for TrajectorySeries.

Rows are connected in source encounter order within each group. The component neither sorts time values nor invents visits, summaries, or missing values.

interface TrajectorySeriesProps<D> extends PibblEventHandlers, PibblEventParticipationOptions

Related API: TrajectorySeriesProps, PibblEventHandlers, PibblEventParticipationOptions.

View source — packages/core/src/features/viz/lib/trajectory-series.tsx:62

Properties and methods

data

readonly data: SignalValue<readonly D[]>

Related API: SignalValue.

Source observations or a signal containing them.

View source — packages/core/src/features/viz/lib/trajectory-series.tsx:65

group

readonly group: TrajectoryGroupAccessor<D>

Related API: TrajectoryGroupAccessor.

Stable participant or specimen identity. Nullish identities omit that row.

View source — packages/core/src/features/viz/lib/trajectory-series.tsx:67

x

readonly x: SeriesAccessor<D>

Related API: SeriesAccessor.

Encounter-time or scheduled-visit coordinate.

View source — packages/core/src/features/viz/lib/trajectory-series.tsx:69

y

readonly y: LineAccessor<D>

Related API: LineAccessor.

Numeric observed outcome coordinate.

View source — packages/core/src/features/viz/lib/trajectory-series.tsx:71

xScale

readonly xScale: ScaleId

Related API: ScaleId.

Scale mapping encounter-time or visit coordinates.

View source — packages/core/src/features/viz/lib/trajectory-series.tsx:73

yScale

readonly yScale: ScaleId

Related API: ScaleId.

Numeric scale mapping outcomes.

View source — packages/core/src/features/viz/lib/trajectory-series.tsx:75

defined (optional)

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

Ends that group’s current run without reading coordinate accessors.

Parameters

• datum — Candidate source datum.

• index — Zero-based source index.

• data — Complete source data array.

Returns

Whether this datum contributes a coordinate to its group.

View source — packages/core/src/features/viz/lib/trajectory-series.tsx:83

style (optional)

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, StrokeStyle, opacity.

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

View source — packages/core/src/features/viz/lib/trajectory-series.tsx:85

pointerEvents (optional)

readonly pointerEvents?: PibblPointerEvents | undefined

Related API: PibblPointerEvents.

Whether this content participates in pointer targeting. See PibblPointerEvents.

View source — packages/core/src/lib/events/types.ts:126

TrajectorySeriesStyle

Shared path appearance for TrajectorySeries.

interface TrajectorySeriesStyle

Related API: TrajectorySeriesStyle.

View source — packages/core/src/features/viz/lib/trajectory-series.tsx:21

Properties and methods

stroke (optional)

readonly stroke?: StrokeStyle | undefined

Related API: StrokeStyle.

Path paint. Defaults to #2563eb.

View source — packages/core/src/features/viz/lib/trajectory-series.tsx:23

strokeWidth (optional)

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

lineInteractionWidth (optional)

readonly lineInteractionWidth?: number | undefined

Pointer targeting width. Defaults to strokeWidth.

View source — packages/core/src/features/viz/lib/trajectory-series.tsx:27

opacity (optional)

readonly opacity?: number | undefined

Related API: opacity.

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

View source — packages/core/src/features/viz/lib/trajectory-series.tsx:29

cursor (optional)

readonly cursor?: string | undefined

Cursor while the batched path owns pointer presentation.

View source — packages/core/src/features/viz/lib/trajectory-series.tsx:31

TrajectoryGroupAccessor

A participant or specimen identity property or callback.

Nullish identities deliberately omit a row. Numeric identities must be finite.

type TrajectoryGroupAccessor<D> = | {
      [K in keyof D]-?: D[K] extends string | number | null | undefined
        ? K
        : never;
    }[keyof D]
  | ((
      datum: D,
      index: number,
      data: readonly D[],
    ) => string | number | null | undefined)

Related API: TrajectoryGroupAccessor.

Parameters

• datum — Source observation.

• index — Zero-based source index.

• data — Complete source data array.

Returns

A finite numeric or string identity, or a nullish omitted identity.

See also

TrajectorySeriesProps

View source — packages/core/src/features/viz/lib/trajectory-series.tsx:44

Implementation guidance for agents

Read the Data visualization companion for ownership, adaptation, failure modes, and verification. Agent start provides the version-selection workflow.

Complete minimal examples

• Participant trajectories with explicit missing visits: Participant trajectories with explicit missing visits. Plain source

Documentation version

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