# Censored point series

`CensoredPointSeries` draws supplied numerical observations as circles and
reporting limits as open directional markers. It is designed for assay and
laboratory datasets where a result may be reported as below an LLOQ or above a
ULOQ without inventing an exact measurement.

```tsx
import { Absolute } from "@pibbl/core";
import { CensoredPointSeries, LinearScale, LogScale } from "@pibbl/core/viz";

const samples = [
  { hour: 0.25, concentration: 0.5, reporting: "below" as const },
  { hour: 2, concentration: 12.8, reporting: "observed" as const },
  { hour: 24, concentration: 50, reporting: "above" as const },
];

<Absolute style={{ left: 64, top: 32, width: 600, height: 320 }}>
  <LinearScale id="time" domain={[0, 24]} range={[0, 600]}>
    <LogScale id="concentration" domain={[0.25, 100]} range={[320, 0]}>
      <CensoredPointSeries
        data={samples}
        x="hour"
        y="concentration"
        censoring="reporting"
        xScale="time"
        yScale="concentration"
      />
    </LogScale>
  </LinearScale>
</Absolute>;
```

Required inputs are `data`, `x`, `y`, `censoring`, `xScale`, and `yScale`.
`x` and `y` are numeric property keys or synchronous accessors. `censoring`
is a property key or callback returning one of `"observed"`, `"below"`, or
`"above"`. Both scales are ancestor continuous scales: linear, UTC, log, or
symlog.

For `below` and `above`, the supplied `y` is the laboratory reporting limit,
not a replacement observation. `below` points toward decreasing y-domain values;
`above` points toward increasing y-domain values. Direction stays semantically
correct for reversed ranges and reversed domains. The component performs no
imputation, substitution, model fitting, or inference.

Rows with a nullish/non-finite coordinate or status are omitted. Unknown
non-null statuses throw. A log scale rejects nonpositive reporting limits under
its normal scale contract. `defined` runs before the accessors and can exclude a
row. Accessors cannot call hooks or write signals during rendering.

`style` accepts a whole-object signal and shallow field signals. `radius`
defaults to 4 pixels, `fill` (observed circles only) and `stroke` default to
`#087f8c`, `strokeWidth` defaults to 1.5 pixels, and `opacity` defaults to 1.
The censor markers are always open. Zero radius hides all marks. Records retain
source paint order and use two ordinary batched `Path` targets. Series event
handlers receive ordinary bubbled mark events; they do not infer a datum.

The [censored concentration-time assay](/playground/#/examples/composition/viz-censored-assay)
shows synthetic LLOQ and ULOQ results with an application-owned accessible table.

## API details from source

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

### CensoredPointSeries

Draws supplied numeric observations as circles and below/above reporting limits as open arrows.

`below` points toward decreasing y-domain values and `above` toward increasing y-domain values,
including when the y scale uses a reversed domain or range. The supplied `y` value remains the
reporting limit; this component never substitutes a measurement, imputes a value, or fits a model.

```ts
CensoredPointSeries: <D>({ data: input, x: xInput, y: yInput, censoring: censoringInput, xScale: xId, yScale: yId, defined, style: styleInput, pointerEvents, ...events }: CensoredPointSeriesProps<D>) => JSX.Element
```

Related API: [CensoredPointSeries](/reference/components/censored-point-series/), [CensoredPointSeriesProps](/reference/components/censored-point-series/), [JSX](/reference/overview/).

#### Parameters

- **`props`** — Supplied observations, coordinates, reporting statuses, scales, and paint.
See [CensoredPointSeriesProps](/reference/components/censored-point-series/).

#### Returns

Two ordinary batched paths for observed and open censored marks.

#### See also

[CensoredPointSeriesProps](/reference/components/censored-point-series/)

[View source — packages/core/src/features/viz/lib/censored-point-series.tsx:131](/source/packages/core/src/features/viz/lib/censored-point-series-tsx/#L131)

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

### CensoringStatus

A supplied assay reporting status. `below` and `above` retain the supplied reporting limit.

```ts
type CensoringStatus = "observed" | "below" | "above"
```

Related API: [CensoringStatus](/reference/components/censored-point-series/).

#### See also

[CensoredPointSeriesProps](/reference/components/censored-point-series/)

[View source — packages/core/src/features/viz/lib/censored-point-series.tsx:19](/source/packages/core/src/features/viz/lib/censored-point-series-tsx/#L19)

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

### CensoringAccessor

Extracts an observation's supplied reporting status.

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

Related API: [CensoringAccessor](/reference/components/censored-point-series/), [CensoringStatus](/reference/components/censored-point-series/).

#### Parameters

- **`datum`** — Original record being read.

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

- **`data`** — Complete supplied record array.

#### Returns

The supplied status, or a nullish sentinel that omits the record.

#### See also

[CensoringStatus](/reference/components/censored-point-series/)

[View source — packages/core/src/features/viz/lib/censored-point-series.tsx:28](/source/packages/core/src/features/viz/lib/censored-point-series-tsx/#L28)

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

### CensoredPointSeriesProps

Authored inputs for supplied observed and censored numeric observations.

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

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

#### See also

[CensoredPointSeries](/reference/components/censored-point-series/)

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

#### Properties and methods

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


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

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

Original records, or a signal of records. The series performs no imputation or inference.

[View source — packages/core/src/features/viz/lib/censored-point-series.tsx:62](/source/packages/core/src/features/viz/lib/censored-point-series-tsx/#L62)

</details>

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


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

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

Property or callback supplying the numeric horizontal coordinate.

[View source — packages/core/src/features/viz/lib/censored-point-series.tsx:64](/source/packages/core/src/features/viz/lib/censored-point-series-tsx/#L64)

</details>

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


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

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

Property or callback supplying the numeric vertical value or reporting limit.

[View source — packages/core/src/features/viz/lib/censored-point-series.tsx:66](/source/packages/core/src/features/viz/lib/censored-point-series-tsx/#L66)

</details>

<span id="api-CensoredPointSeriesProps-censoring"></span>
<details>
<summary>censoring</summary>


```ts
readonly censoring: CensoringAccessor<D>
```

Related API: [CensoringAccessor](/reference/components/censored-point-series/).

Property or callback yielding `observed`, `below`, or `above`.

[View source — packages/core/src/features/viz/lib/censored-point-series.tsx:68](/source/packages/core/src/features/viz/lib/censored-point-series-tsx/#L68)

</details>

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


```ts
readonly xScale: ScaleId
```

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

Ancestor continuous numeric scale mapping x.

[View source — packages/core/src/features/viz/lib/censored-point-series.tsx:70](/source/packages/core/src/features/viz/lib/censored-point-series-tsx/#L70)

</details>

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


```ts
readonly yScale: ScaleId
```

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

Ancestor continuous numeric scale mapping y and its reporting limit.

[View source — packages/core/src/features/viz/lib/censored-point-series.tsx:72](/source/packages/core/src/features/viz/lib/censored-point-series-tsx/#L72)

</details>

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


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

Optional synchronous predicate; excluded rows contribute no mark.

##### Parameters

- **`datum`** — Original record being tested.

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

- **`data`** — Complete supplied record array.

##### Returns

Whether this record contributes a mark.

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

</details>

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


```ts
readonly style?: SignalValue<Readonly<{ readonly radius?: SignalValue<number | undefined>; 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 style; whole-object and shallow field signals are observed by the series.

[View source — packages/core/src/features/viz/lib/censored-point-series.tsx:81](/source/packages/core/src/features/viz/lib/censored-point-series-tsx/#L81)

</details>

<span id="api-CensoredPointSeriesProps-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-CensoredPointSeriesStyle"></span>

### CensoredPointSeriesStyle

Shared mark paint and local-pixel geometry for CensoredPointSeries.

```ts
interface CensoredPointSeriesStyle
```

Related API: [CensoredPointSeriesStyle](/reference/components/censored-point-series/).

[View source — packages/core/src/features/viz/lib/censored-point-series.tsx:41](/source/packages/core/src/features/viz/lib/censored-point-series-tsx/#L41)

#### Properties and methods

<span id="api-CensoredPointSeriesStyle-radius"></span>
<details>
<summary>radius (optional)</summary>


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

Circle and open censor marker radius in local pixels; defaults to 4.

[View source — packages/core/src/features/viz/lib/censored-point-series.tsx:43](/source/packages/core/src/features/viz/lib/censored-point-series-tsx/#L43)

</details>

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


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

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

Fill for observed circles; defaults to #087f8c. Censor markers remain open.

[View source — packages/core/src/features/viz/lib/censored-point-series.tsx:45](/source/packages/core/src/features/viz/lib/censored-point-series-tsx/#L45)

</details>

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


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

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

Outline for circles and open directional censor markers; defaults to #087f8c.

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

</details>

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


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

Outline width in local pixels; defaults to 1.5.

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

</details>

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


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

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

Shared paint opacity from zero to one; defaults to 1.

[View source — packages/core/src/features/viz/lib/censored-point-series.tsx:51](/source/packages/core/src/features/viz/lib/censored-point-series-tsx/#L51)

</details>

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


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

Cursor for painted mark targets.

[View source — packages/core/src/features/viz/lib/censored-point-series.tsx:53](/source/packages/core/src/features/viz/lib/censored-point-series-tsx/#L53)

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

- [Supplied assay reporting limits](/minimal-examples/viz/censored-point-series/): Supplied assay reporting limits. [Plain source](/minimal/viz/censored-point-series.tsx)
## Documentation version

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