@inflexa-ai/harness 0.42.2 → 0.43.1

package/dist/report-render/figures/km.js

@@ -0,0 +1,406 @@
+/**
+ * The Kaplan-Meier figure: one step curve for each group, the confidence band as a step band, a tick at each
+ * censored row, the number-at-risk table under the plot, the median lines, and the statistics text.
+ *
+ * The figure plots the precomputed survival of the table, and it fits no curve. It computes two lookups from
+ * the rows, and each one reads the rows of one group alone:
+ *
+ * - The number at risk at each tick of the time axis is the risk of the first row at or after the tick, and 0
+ *   past the last row of the group. A risk table that does not sit at the axis ticks misleads, thus the figure
+ *   sets the ticks itself and reads the table at them.
+ * - The median of a group is the time of the first row whose survival is at or under 0.5. A curve that never
+ *   reaches 0.5 has no median, and it takes no median line.
+ */
+import { err, ok } from "neverthrow";
+import { CHART_BODY_MAX_PX, CHART_BODY_PX, CHART_FONT_STACK, CHART_INK, CHART_PAGE_TEXT_PX } from "../design.js";
+import { categoricalPalette, categoryAxis, categoryName, chartProblem, demandedColumn, firstAppearance, GUIDE_LINE_STYLE, plainColumn, statisticsGraphic, toNumber, valueAxis, valueAxisTitle, withFigureBody, } from "./common.js";
+/** The members of a km block that the figure reads. */
+const KM_READS = new Set(["x", "y", "group", "low", "high", "censor", "risk", "statistics"]);
+/** The Kaplan-Meier survival figure. */
+export const KM_FIGURE = { reads: KM_READS, derive: deriveKm };
+/** The survival at which the median line sits. */
+const MEDIAN_SURVIVAL = 0.5;
+/**
+ * The most ticks of the time axis. The step of the axis is the smallest nice step at or over the last time over
+ * `MAX_TIME_TICKS - 1`, thus the span from 0 to the last time holds five steps at most.
+ */
+const MAX_TIME_TICKS = 6;
+/** The nice steps of the time axis in one decade. */
+const NICE_STEPS = [1, 2, 2.5, 5];
+/**
+ * The tolerance, in steps, under which the end of the time axis counts as a tick. A product such as `3 × 0.2`
+ * gives `0.6000000000000001`, one unit in the last place past the end `0.6`.
+ */
+const TICK_TOLERANCE = 1e-9;
+/** The significant digits of a tick, thus a tick such as `3 × 0.2` reads `0.6`. */
+const TICK_DIGITS = 12;
+/** The opacity of a confidence band. The curve and the band of the other group stay readable through it. */
+const BAND_OPACITY = 0.2;
+/** The stroke width of a survival curve, in pixels. */
+const CURVE_WIDTH_PX = 1.5;
+/** The size of a censor tick in pixels: a thin upright bar across the curve. */
+const CENSOR_TICK_PX = [1.5, 8];
+/**
+ * The layout of the plot and of the number-at-risk table, in percent of the chart.
+ *
+ * The two grids share one left edge and one right edge, thus each count sits under its tick. The axis band
+ * under the plot holds the tick labels and the title of the time axis, and the header band holds the title of
+ * the table. Each group takes one row of the table. A table of more rows than the default body holds grows the
+ * body.
+ */
+const PLOT_TOP = 12;
+const GRID_RIGHT = 5;
+const AXIS_BAND = 14;
+const HEADER_BAND = 7;
+const RISK_ROW = 6;
+const TABLE_BOTTOM = 3;
+const RISK_ROWS_IN_BODY = 3;
+/** The left inset of the table title, in percent of the chart. The title sits over the group names. */
+const HEADER_LEFT = 1;
+/** The title of the number-at-risk table. */
+const TABLE_TITLE = "Number at risk";
+/**
+ * The gap in pixels between a group name and the plot edge of the table. A count at the first tick centers on
+ * the edge, thus the gap holds half of a count of three digits.
+ */
+const TABLE_NAME_GAP_PX = 16;
+/**
+ * The left edge of both grids, in percent of the chart: the least edge, the most edge, the pad, and the share
+ * of one character of a group name.
+ *
+ * The share and the pad read the single journal column, the narrowest place that the figure draws in: one
+ * character of the export text, and the name gap with a margin. Thus the longest group name of the table fits
+ * left of the plot there.
+ */
+const GRID_LEFT_MIN = 10;
+const GRID_LEFT_MAX = 30;
+const GRID_LEFT_PAD = 7;
+const NAME_CHARACTER_PCT = 1.6;
+/** Derive the figure of one km block. */
+function deriveKm(block, rows, context) {
+    const columns = kmColumns(block, rows, context);
+    if (columns.isErr())
+        return err(columns.error);
+    const curves = kmCurves(rows, columns.value, context.blockId);
+    if (curves.isErr())
+        return err(curves.error);
+    const palette = categoricalPalette(curves.value.length);
+    const colorOf = (index) => palette[index % palette.length];
+    const end = timeEnd(curves.value);
+    const step = timeStep(end);
+    const ticks = timeTicks(end, step);
+    const table = columns.value.risk !== undefined;
+    const left = gridLeft(curves.value);
+    const layout = kmLayout(table ? curves.value.length : 0);
+    const legend = curves.value.length > 1;
+    const series = [];
+    for (const [index, curve] of curves.value.entries()) {
+        series.push(...curveSeries(curve, index, colorOf(index), columns.value));
+    }
+    const median = medianSeries(curves.value);
+    if (median !== undefined)
+        series.push(median);
+    if (table) {
+        for (const [index, curve] of curves.value.entries())
+            series.push(riskSeries(curve, index, ticks));
+    }
+    // The time axis ends at the last time of the table. A label at an end that is no tick crowds the last tick, thus it hides.
+    const timeAxis = {
+        ...valueAxis("x", valueAxisTitle(context.labels, columns.value.time), { min: 0, max: end }),
+        interval: step,
+        ...(onTick(end, step) ? {} : { axisLabel: { showMaxLabel: false } }),
+    };
+    const survivalAxis = valueAxis("y", valueAxisTitle(context.labels, columns.value.survival), { min: 0, max: 1 });
+    const plotGrid = { top: pct(layout.top), bottom: pct(layout.plotBottom), left: pct(left), right: pct(GRID_RIGHT) };
+    // The statistics text sits at the top of the plot, and the top of the plot moves with the body.
+    const statistics = statisticsGraphic(context.statistics, "top-right").map((text) => ({ ...text, top: pct(layout.top) }));
+    const graphic = [...statistics, ...(table ? [tableTitle(layout)] : [])];
+    const option = {
+        legend: legend ? { top: 0 } : { show: false },
+        grid: table ? [plotGrid, tableGrid(layout, left)] : plotGrid,
+        xAxis: table ? [timeAxis, tableTimeAxis(end, step)] : timeAxis,
+        yAxis: table ? [survivalAxis, tableGroupAxis(curves.value, colorOf)] : survivalAxis,
+        series,
+        ...(graphic.length > 0 ? { graphic } : {}),
+    };
+    return ok(layout.bodyPx > CHART_BODY_PX ? withFigureBody(option, layout.bodyPx) : option);
+}
+/** A number in percent of the chart, rounded, thus a float residue never reaches the option. */
+function pct(value) {
+    return `${Math.round(value * 1e4) / 1e4}%`;
+}
+/**
+ * The bands of a chart whose table holds some rows. A table past `RISK_ROWS_IN_BODY` rows grows the body by one
+ * row of the default body for each further row, and each band keeps its height in pixels. The body stops at the
+ * largest body, and past it the plot keeps its height and the rows share the rest of the table band.
+ */
+function kmLayout(rows) {
+    const grown = Math.max(0, rows - RISK_ROWS_IN_BODY) * RISK_ROW;
+    const bodyPx = Math.min(CHART_BODY_MAX_PX, (CHART_BODY_PX * (100 + grown)) / 100);
+    const share = CHART_BODY_PX / bodyPx;
+    const fixed = rows > 0 ? PLOT_TOP + AXIS_BAND + HEADER_BAND + TABLE_BOTTOM : PLOT_TOP + AXIS_BAND;
+    const plot = (100 - fixed - Math.min(rows, RISK_ROWS_IN_BODY) * RISK_ROW) * share;
+    return {
+        top: PLOT_TOP * share,
+        plotBottom: 100 - PLOT_TOP * share - plot,
+        tableBottom: TABLE_BOTTOM * share,
+        rows: 100 - fixed * share - plot,
+        header: HEADER_BAND * share,
+        bodyPx,
+    };
+}
+/** The columns of one km block. The time and the survival are demanded, and each other channel is optional. */
+function kmColumns(block, rows, context) {
+    const encoding = block.encoding ?? {};
+    const source = { blockId: context.blockId, rows, columns: context.columns };
+    const time = demandedColumn("km", encoding, "x", source);
+    if (time.isErr())
+        return err(time.error);
+    const survival = demandedColumn("km", encoding, "y", source);
+    if (survival.isErr())
+        return err(survival.error);
+    const optional = {
+        group: undefined,
+        low: undefined,
+        high: undefined,
+        censor: undefined,
+        risk: undefined,
+    };
+    for (const channel of ["group", "low", "high", "censor", "risk"]) {
+        const column = plainColumn("km", encoding, channel, source);
+        if (column.isErr())
+            return err(column.error);
+        optional[channel] = column.value;
+    }
+    return ok({
+        time: time.value,
+        survival: survival.value,
+        ...(optional.group !== undefined ? { group: optional.group } : {}),
+        ...(optional.low !== undefined ? { low: optional.low } : {}),
+        ...(optional.high !== undefined ? { high: optional.high } : {}),
+        ...(optional.censor !== undefined ? { censor: optional.censor } : {}),
+        ...(optional.risk !== undefined ? { risk: optional.risk } : {}),
+    });
+}
+/**
+ * The curves of one table: one for each group in the order of its first row, each in time order.
+ *
+ * A row whose time or survival is not numeric draws nothing. A survival outside 0 to 1 is no probability,
+ * thus it refuses, because the axis holds 0 to 1 and a clip would hide the fault. A bound on the wrong side of
+ * the survival refuses too. The sort is stable, thus two rows at one time keep the order of the table.
+ */
+function kmCurves(rows, columns, blockId) {
+    const groupOf = (row) => (columns.group === undefined ? "" : (row[columns.group] ?? ""));
+    const names = firstAppearance(rows.map(groupOf).map(String));
+    const byName = new Map(names.map((name) => [name, []]));
+    for (const [index, row] of rows.entries()) {
+        const time = toNumber(row[columns.time]);
+        const survival = toNumber(row[columns.survival]);
+        if (time === null || survival === null)
+            continue;
+        if (survival < 0 || survival > 1) {
+            return err(chartProblem(blockId, `The km figure reads a survival between 0 and 1, and the row ${index + 1} holds ${survival} in the "${columns.survival}" column.`));
+        }
+        const low = columns.low === undefined ? null : toNumber(row[columns.low]);
+        const high = columns.high === undefined ? null : toNumber(row[columns.high]);
+        if (low !== null && high !== null && (low > survival || high < survival)) {
+            return err(chartProblem(blockId, `The row ${index + 1} holds the interval from ${low} to ${high} around the survival ${survival}. ` +
+                'The "low" bound sits at or under the survival, and the "high" bound sits at or over it.'));
+        }
+        byName.get(String(groupOf(row)))?.push({
+            time,
+            survival,
+            low,
+            high,
+            censor: columns.censor === undefined ? null : toNumber(row[columns.censor]),
+            risk: columns.risk === undefined ? null : toNumber(row[columns.risk]),
+        });
+    }
+    return ok(names.map((name) => ({ name, points: (byName.get(name) ?? []).sort((a, b) => a.time - b.time) })));
+}
+/** The last time of the table, or 1 for a table with no time past zero. */
+function timeEnd(curves) {
+    let end = 0;
+    for (const curve of curves) {
+        for (const point of curve.points)
+            end = Math.max(end, point.time);
+    }
+    return end > 0 ? end : 1;
+}
+/** The smallest nice step of the time axis at or over the end over `MAX_TIME_TICKS - 1`. */
+function timeStep(end) {
+    const least = end / (MAX_TIME_TICKS - 1);
+    let decade = 10 ** Math.floor(Math.log10(least));
+    for (;;) {
+        for (const nice of NICE_STEPS) {
+            if (nice * decade >= least)
+                return nice * decade;
+        }
+        decade *= 10;
+    }
+}
+/** The ticks of the time axis: each multiple of the step from 0 to the end. */
+function timeTicks(end, step) {
+    const count = Math.floor(end / step + TICK_TOLERANCE);
+    const ticks = [];
+    for (let place = 0; place <= count; place += 1)
+        ticks.push(Number((place * step).toPrecision(TICK_DIGITS)));
+    return ticks;
+}
+/** Whether the end of the time axis sits at a multiple of the step. */
+function onTick(end, step) {
+    return Math.abs(end / step - Math.round(end / step)) < TICK_TOLERANCE;
+}
+/** The left edge of both grids, wide enough for the longest group name in the table column. */
+function gridLeft(curves) {
+    let longest = 0;
+    for (const curve of curves)
+        longest = Math.max(longest, categoryName(curve.name).length);
+    return Math.min(GRID_LEFT_MAX, Math.max(GRID_LEFT_MIN, Math.ceil(GRID_LEFT_PAD + longest * NAME_CHARACTER_PCT)));
+}
+/**
+ * The series of one curve: the step line, the two halves of the step band, and the censor ticks.
+ *
+ * Each series carries the name of the group, thus the legend entry of the group shows and hides all of them.
+ * The band and the ticks are silent, thus the legend takes its icon from the line.
+ */
+function curveSeries(curve, index, color, columns) {
+    const name = categoryName(curve.name);
+    const points = curve.points;
+    const line = points.map((point) => [point.time, point.survival]);
+    if (points.length === 0 || points[0].time > 0)
+        line.unshift([0, 1]);
+    const series = [
+        {
+            type: "line",
+            name,
+            step: "end",
+            showSymbol: false,
+            itemStyle: { color },
+            lineStyle: { color, width: CURVE_WIDTH_PX },
+            z: 3,
+            data: line,
+        },
+    ];
+    if (columns.low !== undefined && columns.high !== undefined) {
+        const lower = [];
+        const span = [];
+        for (const point of points) {
+            if (point.low === null || point.high === null)
+                continue;
+            lower.push([point.time, point.low]);
+            span.push([point.time, point.high - point.low]);
+        }
+        const band = {
+            type: "line",
+            name,
+            stack: `km-band-${index}`,
+            step: "end",
+            showSymbol: false,
+            silent: true,
+            tooltip: { show: false },
+            lineStyle: { opacity: 0 },
+        };
+        series.push({ ...band, data: lower }, { ...band, areaStyle: { color, opacity: BAND_OPACITY }, data: span });
+    }
+    if (columns.censor !== undefined) {
+        series.push({
+            type: "scatter",
+            name,
+            symbol: "rect",
+            symbolSize: [...CENSOR_TICK_PX],
+            silent: true,
+            itemStyle: { color },
+            z: 4,
+            data: points.filter((point) => point.censor !== null && point.censor > 0).map((point) => [point.time, point.survival]),
+        });
+    }
+    return series;
+}
+/** The median of one curve: the time of its first row at or under 0.5, or `undefined` where none reaches it. */
+function medianOf(curve) {
+    return curve.points.find((point) => point.survival <= MEDIAN_SURVIVAL)?.time;
+}
+/**
+ * The median lines as one silent series: a line at 0.5 from time 0 to the latest median, and one drop from 0.5
+ * to the time axis at the median of each curve that crosses 0.5. No curve that crosses gives no series.
+ */
+function medianSeries(curves) {
+    const medians = curves.map(medianOf).filter((median) => median !== undefined);
+    if (medians.length === 0)
+        return undefined;
+    const latest = Math.max(...medians);
+    const lines = [
+        [{ coord: [0, MEDIAN_SURVIVAL] }, { coord: [latest, MEDIAN_SURVIVAL] }],
+        ...medians.map((median) => [{ coord: [median, MEDIAN_SURVIVAL] }, { coord: [median, 0] }]),
+    ];
+    return {
+        type: "line",
+        silent: true,
+        tooltip: { show: false },
+        data: [],
+        markLine: { silent: true, symbol: "none", label: { show: false }, lineStyle: { ...GUIDE_LINE_STYLE }, data: lines },
+    };
+}
+/** The number at risk of one curve at one tick: the risk of its first row at or after the tick, else 0. */
+function riskAt(curve, tick) {
+    for (const point of curve.points) {
+        if (point.time >= tick && point.risk !== null)
+            return point.risk;
+    }
+    return 0;
+}
+/** The counts of one curve in its row of the table: one text at each tick, in the ink of the chart. */
+function riskSeries(curve, index, ticks) {
+    return {
+        type: "scatter",
+        xAxisIndex: 1,
+        yAxisIndex: 1,
+        silent: true,
+        tooltip: { show: false },
+        symbolSize: 0,
+        label: { show: true, position: "inside", formatter: "{b}", color: CHART_INK },
+        data: ticks.map((tick) => ({ name: String(riskAt(curve, tick)), value: [tick, index] })),
+    };
+}
+/** The grid of the table: one row for each group at the bottom of the chart, with the left edge of the plot. */
+function tableGrid(layout, left) {
+    return { bottom: pct(layout.tableBottom), height: pct(layout.rows), left: pct(left), right: pct(GRID_RIGHT) };
+}
+/** The title of the table: one text over the group names, at the left edge of the chart. */
+function tableTitle(layout) {
+    return {
+        type: "text",
+        left: pct(HEADER_LEFT),
+        bottom: pct(layout.tableBottom + layout.rows + layout.header / 4),
+        silent: true,
+        style: { text: TABLE_TITLE, fill: CHART_INK, fontFamily: CHART_FONT_STACK, fontSize: CHART_PAGE_TEXT_PX },
+    };
+}
+/** The time axis of the table: the range and the ticks of the plot, with no line and no label. */
+function tableTimeAxis(end, step) {
+    return {
+        type: "value",
+        gridIndex: 1,
+        min: 0,
+        max: end,
+        interval: step,
+        axisLine: { show: false },
+        axisTick: { show: false },
+        axisLabel: { show: false },
+        splitLine: { show: false },
+    };
+}
+/** The group axis of the table: one row for each group from the top, each name in the color of its curve. */
+function tableGroupAxis(curves, colorOf) {
+    const names = curves.map((curve, index) => ({ value: categoryName(curve.name), textStyle: { color: colorOf(index) } }));
+    return {
+        ...categoryAxis("y", [], { topDown: true }),
+        data: names,
+        gridIndex: 1,
+        axisLine: { show: false },
+        axisTick: { show: false },
+        axisLabel: { margin: TABLE_NAME_GAP_PX },
+        splitLine: { show: false },
+    };
+}

package/dist/report-render/figures/label-room.d.ts

@@ -0,0 +1,130 @@
+/**
+ * The place of the names that a figure of one unit draws on its data: the sample names of a PCA, and the
+ * category names of an embedding.
+ *
+ * The chart runtime moves a label that overlaps another one only where the label states its own absolute
+ * place, and the option holds no function that could state one. Thus the derivation places each name itself,
+ * before the draw, in the units of the data. The square of the figure spans one length of data on each axis,
+ * thus one estimate of the square size converts a text size in pixels to a size in data units on both axes.
+ *
+ * The estimate reads a square smaller than the square of the page, because the column export draws a smaller
+ * square at a text size that shrinks less. A name that clears its neighbor at the estimate clears it at each
+ * size. The place is a pure function of the points and the names, thus the same rows give the same places.
+ */
+import { CHART_EXPORT_SIZES } from "../design.js";
+/** The gap between a point and its name, in pixels. */
+export declare const NAME_GAP_PX = 4;
+/** One box in data units, or in pixels. */
+export interface Box {
+    readonly left: number;
+    readonly right: number;
+    readonly bottom: number;
+    readonly top: number;
+}
+/** True when two boxes share an area. */
+export declare function overlaps(a: Box, b: Box): boolean;
+/** The range of the two axes of a plot, in data units. */
+export interface PlotRange {
+    readonly x: {
+        readonly min: number;
+        readonly max: number;
+    };
+    readonly y: {
+        readonly min: number;
+        readonly max: number;
+    };
+}
+/** One named point: its place in data units and its name. */
+export interface NamedPoint {
+    readonly x: number;
+    readonly y: number;
+    readonly text: string;
+}
+/** The four sides of a point where its name can sit, in the order that the figure tries them. */
+export declare const NAME_SIDES: readonly ["right", "left", "top", "bottom"];
+/** One side of a point. */
+export type NameSide = (typeof NAME_SIDES)[number];
+/**
+ * The side of each point where its name sits, in the order of the points.
+ *
+ * Each name takes the first side, in the order right, left, top, bottom, where it stays inside the plot on that
+ * side and covers no earlier name and no point. A name that finds no free side sits at the right. `plot` is the range of
+ * the two axes in data units, and `pointPx` is the diameter of a point in pixels.
+ */
+export declare function pointNameSides(points: readonly NamedPoint[], plot: PlotRange, pointPx: number): NameSide[];
+/**
+ * The place of each category name on the data, in the order of the names, or `undefined` for a name that
+ * finds no free place.
+ *
+ * A name sits centered on its anchor, for example the median of its cells. A heavier name places first, thus
+ * the name of a large cluster keeps its anchor. A name that covers an earlier name moves along y by whole
+ * lines, up first, while its box stays inside the y range of `plot`, until it covers none. A name that covers
+ * an earlier name at each such place draws nothing, thus no two names overlap. `weights` gives the weight of
+ * each name, for example its cell count, and the x range of `plot` gives the length that sizes a name.
+ */
+export declare function nameAnchors(names: readonly NamedPoint[], weights: readonly number[], plot: PlotRange): Array<{
+    readonly x: number;
+    readonly y: number;
+} | undefined>;
+/**
+ * The plot of one render, where a dense figure measures its names: the plot size in pixels and the text size of
+ * the render.
+ *
+ * Each frame is a little smaller than the plot that the chart runtime draws for a figure of one grid at that
+ * size. A smaller frame puts the names nearer to each other than the drawn plot does, thus a name that clears
+ * its neighbors in the frame clears them in the drawn plot.
+ */
+export interface NameFrame {
+    readonly widthPx: number;
+    readonly heightPx: number;
+    readonly textPx: number;
+}
+/** The width of one text in pixels at one text size: the estimate of each figure that places its own text. */
+export declare function textWidthPx(text: string, textPx: number): number;
+/** The frame of the page: the plot inside the 900 by 400 pixel chart body of a window 1280 pixels wide. */
+export declare const PAGE_PLOT_FRAME: NameFrame;
+/** The frame of the single-column export: the plot inside the 336 by 253 pixel chart, and the 7 pt text. */
+export declare const COLUMN_PLOT_FRAME: NameFrame;
+/** The frame of the double-column export: the plot inside the 692 by 348 pixel chart, and the 7 pt text. */
+export declare const DOUBLE_COLUMN_PLOT_FRAME: NameFrame;
+/** The frame of the slide export: the plot inside the 1920 by 1080 pixel chart, and the slide text. */
+export declare const SLIDE_PLOT_FRAME: NameFrame;
+/** The frame of each export size. A new export size joins with the frame of its plot. */
+export declare const EXPORT_PLOT_FRAMES: Readonly<Record<keyof typeof CHART_EXPORT_SIZES, NameFrame>>;
+/**
+ * The three places of a name beside its anchor: the text starts at the anchor, the text ends at the anchor,
+ * or the text centers over the anchor.
+ */
+export type LeaderSide = "right" | "left" | "top";
+/** The anchor of one name in data units, and the side of the anchor where the text sits. */
+export interface LeaderName {
+    readonly x: number;
+    readonly y: number;
+    readonly side: LeaderSide;
+}
+/** The points that no name can cover: the plotted pair of each row, and the diameter of the largest point. */
+export interface NameObstacles {
+    readonly xs: readonly (number | null)[];
+    readonly ys: readonly (number | null)[];
+    readonly pointPx: number;
+}
+/**
+ * The anchor of each name, in the order of the names, or `undefined` for a name that finds no free place.
+ *
+ * The names come in the order of their weight, thus the most important name places first. Each name tries the
+ * sides in the given order, first beside its point, then one line further away at each step, up before down.
+ * A leader line joins each point to the anchor of its name. A place is free when the name stays inside the
+ * plot, when the name and its leader line cross no earlier name and no earlier leader line, and when they cover
+ * no point. Where no place is free, the name takes the first place clear of the earlier names and leader lines
+ * that covers the fewest points. A name that finds no place clear of them draws nothing.
+ *
+ * The geometry runs in pixels of `frame`, and each point enters a grid of cells one line high. Thus a test of
+ * one place reads the points of a few cells alone, and a table of many thousand points costs one pass to index.
+ * `plot` is the range of the two axes in data units. `top` is the highest y in data units that the text of a
+ * name can reach, because the chart runtime can end the y axis at the largest point. `reserved` holds the boxes
+ * in data units that other text of the figure takes, for example the label of a guide line, and no name covers
+ * one. A leader line can pass one, because a point can lie under the text.
+ */
+export declare function placeLeaderNames(names: readonly NamedPoint[], obstacles: NameObstacles, plot: PlotRange, sides: readonly LeaderSide[], top: number, frame?: NameFrame, reserved?: readonly Box[]): Array<LeaderName | undefined>;
+/** The box of one placed name in data units, for a test that a name covers no neighbor and no point. */
+export declare function leaderNameBox(name: LeaderName, text: string, plot: PlotRange, frame?: NameFrame): Box;