@rho-workspace/rho 0.5.6 → 0.5.7

package/node_modules/@rho-workspace/plugin-figures/README.md

@@ -0,0 +1,191 @@
+# Figures
+
+`@rho-workspace/plugin-figures` 0.4.0 keeps the plots a project's live R or Python session
+draws as figures whose marks know the rows they were drawn from. It is built into Rho and
+needs the Notebook (`kernel`).
+
+## What it does
+
+The Notebook's host hands `r/figures.R` to each local R session it starts. When a cell ends,
+the session draws each ggplot page again, off screen, and writes a figure record
+(`rho.figure/1`) next to the plot's PNG. Every ggplot is described the same way, whatever
+built it: ggplot2 itself and packages built on it (ggtree, enrichplot, Seurat, patchwork
+compositions, ggrepel labels). Nothing in the describer knows a package or a domain.
+
+- Each layer's geom is cloned for the drawing, so the plot's own objects are not changed.
+  The clone numbers the rows ggplot2 built (`handle_na`) and tags each panel's grob with
+  the plot, layer, panel and rows it drew (`draw_layer`). The picture is rendered as SVG
+  through svglite, and each drawn element is given `data-rho="unit.element"`.
+- A drawn element stands for one built row (a point, a bar, a text label, a segment) or
+  for a group (a line, a polygon, a box). A label drawn in several parts (a ggrepel label
+  and its halo) is bound by its text. Parts that cannot be matched are reported in the
+  layer's `unbound` reasons; they are never guessed.
+- An extra aesthetic carries each data row's number through the layer's statistic. Where
+  the statistic keeps its input rows (identity, jitter, most position adjustments), a mark
+  links to its row of the plot's data; where it computes new rows (counts, boxes,
+  densities) the mark keeps its computed values and no row. The source's key is its row
+  names, else a unique text column, else a numeric `id` or `node` column.
+- Positions are read back through the scale's inverse, so a box on `scale_y_log10()` reads
+  in counts. The statistic still ran on the transformed values: the median drawn between
+  1100 and 1200 on a log scale is their geometric mean, and that is what is recorded.
+- The session is left as the cell left it: the random number state is restored, and the
+  describer's own output, messages and warnings are discarded.
+
+A ggplot saved to a project file with `ggsave()` in a Notebook cell is kept as a figure of
+that file. When the page starts on ggsave's device, `saved_page()` names the plot, ggsave's
+file and the device's size; when the cell ends the page is described at that size and the
+record is kept with the cell's plots. The cell's `saved` list names the file with its bytes
+and SHA-256. A page that shows the file names it by those bytes, so the figure holds only
+while the file keeps them: once anything writes the file again it is a picture, until a
+cell saves it as a figure again. A file outside the project is not kept, nor one a session on
+a server saved.
+
+A page drawn on a file the code opened itself (`png()`, `jpeg()`, `tiff()`, `bmp()`, `svg()`,
+`pdf()`, `cairo_pdf()`) and closed with `dev.off()` is kept the same way: DESeq2's `plotMA`,
+a ComplexHeatmap's `draw()` or a ggplot's `print()` written to `results/ma.png`. The Notebook's
+runner names the file and records the page as it is drawn; the extension describes the
+recorded page (base graphics, a heatmap) or the plot `page_object()` named (a ggplot) at the
+device's size. A file name numbered with `%d` is a figure for each page; a PDF of several pages
+is not described and says so; any other file keeps its last page. A device left open in one
+cell keeps drawing in the next, as in the R console, and its file is described in the cell
+that closes it. A page no describer knows (a lattice page) stays a picture without a problem.
+
+A page drawn with base graphics (`plot`, `points`, `text`, `barplot`, `abline`, `image` and
+the functions built on them) is described from its recording. gridGraphics makes the page
+into grobs named after what drew them, and each drawn part in a plot's window is a layer:
+points, text, rect, lines, polygon, segments, circles or a reference line. Each element is a
+mark that keeps the values it was drawn at, in the data's units (a log axis is read back).
+A bar is named by the axis label at its middle. Axes, boxes and titles are drawn and not
+bound. Points, labels and lines whose x and y are two columns of a table in the session (a
+data frame, a Bioconductor `DataFrame`, a numeric matrix or a named vector) are bound to its
+rows, value for value and in the table's order. Rows that were not drawn are skipped. The
+layer's `mapping` names the two columns, and its `notes` count marks drawn at another
+value, such as points clipped to the axis limit. A position drawn through `-log10`, `log10`,
+`log2`, `log2(x + 1)` or `log1p` of a column is matched through it, and the mapping says so:
+`plot(res$log2FoldChange, -log10(res$padj))` is bound as `y: -log10(padj)`. Columns drawn as
+they are come first, and a value that is not finite (`-log10(0)`) matches only itself. When an
+earlier layer of the same plot draws the same column on the same axis through another
+transform, the later layer's note says so: points added at `log2(res$baseMean)` over
+`plotMA`, whose x axis draws `baseMean` on a log scale, are placed on another scale than the
+plot's own points. A part drawn from other computed values matches no table and keeps only its
+drawn values.
+
+A ComplexHeatmap is described from the heatmap list it laid out. `draw()` starts the page
+before it lays the heatmaps out, so the describer keeps the frame of its method when the
+page starts and reads the laid-out list when the cell ends: the rows and columns in the order
+and slices drawn, and the matrix. The page is drawn again from its recording, and each cell
+rectangle of a heatmap body is a mark naming its row, column, value and slices, with the
+matrix row as its source (named after the session's matrix when one is identical). Cells
+drawn as one image (`use_raster`) are not bound; annotations, dendrograms and names are
+drawn and not bound.
+
+A matplotlib figure in a live Python session (and what draws through matplotlib: seaborn,
+pandas `.plot`) is described by `py/figures.py`, which the Notebook's host hands to each local
+Python session. matplotlib keeps what each Axes drew as artists, so nothing is read from
+pixels: a scatter's points are a collection with their offsets, a line keeps its vertices,
+each bar is a rectangle, a heatmap (`pcolormesh`, seaborn's `heatmap` and `clustermap`) a mesh
+of cells, a label its text and position. Each artist is given an id for the drawing, the
+figure is written as SVG at its own size, and the elements matplotlib wrote for each artist
+are named after its marks; when they cannot be matched one for one, the layer says why. An
+artist drawn `rasterized=True` (a large scatter, to keep its file small) is drawn as vectors
+for the figure; the figure and its picture are left as the code made them.
+
+- Points, line vertices and labels keep the values they were drawn at, in the data's units
+  (a log axis reads in counts). Where their x and y are two columns of a table in the session
+  (a DataFrame, a numeric Series with its index, a 2-D numeric array), they are bound to its
+  rows in the table's order, skipping rows not drawn. A position drawn through `-log10`,
+  `log10`, `log2`, `log2(x + 1)` or `log1p` of a column is matched through it, and the
+  layer's mapping says so (`y: -log10(padj)`). When an earlier layer of the same Axes draws
+  the same column on the same axis through another transform, the later layer's note says so,
+  as in R: points added at `np.log2(sig.baseMean)` over an MA plot whose x axis draws
+  `baseMean` on a log scale. Marks all drawn at one value of the other axis (genes not
+  tested, drawn at 0) are bound by their own axis alone, and noted. Tables the cell's code
+  assigns, then those it reads, are compared first. A DataFrame is keyed by its
+  text index (named after the index's name), else a unique text column.
+- A label (`ax.text`, `ax.annotate`) drawn at a bound point's position names that point's row,
+  whatever order the labels were drawn in; otherwise one whose text names rows of a table
+  another layer of the plot is bound to is bound by its text, wherever it was moved to. A text
+  placed in the axes' own coordinates (a note in a corner) is a layer of its own.
+- A heatmap cell names its row, column and value. When a table of the session holds the same
+  values, also with rows and columns reordered (a clustered heatmap), the cell's source row
+  is that table's row, and tick labels that name other rows of it than the values they sit
+  beside are noted (*29 of 30 rows are labelled with another row of heat_z: row 1 is labelled
+  SPARCL1 and draws the values of PDPN*). Otherwise the drawn matrix is the source, named by
+  its tick labels; labels set on the cells' edges, one for each, are read in their order and
+  noted.
+- A bar is named by the category drawn at its middle; positions on an axis of categories are
+  named by their category. Horizontal and vertical reference lines (`axhline`, `axvline`)
+  keep their intercept. Segments and polygons keep their ends and extents.
+- The legend and colour bar are the plot's scales; a seaborn facet's title (`dex = trt`) is
+  its facet.
+- What the describer notices (marks drawn elsewhere than their values, a column drawn on
+  another scale than an earlier layer draws it, labels naming other rows) is kept as the
+  layer's `notes`, carried in the cell's plot output for the Agent and shown under the figure.
+
+A figure saved with `savefig()` to a file in the project is kept as a figure of that file,
+like a ggplot saved with `ggsave()`: the Notebook's runner watches `Figure.savefig`, the figure
+is described as it was saved (with its `bbox_inches`), and the cell's `saved` list names the
+file with its bytes when the cell ends, also when the cell closed the figure.
+
+Other grid drawings and images drawn with `imshow` stay pictures. A plot output nothing
+described has neither `figure` nor `figureProblem`: nothing failed, nothing described them.
+
+## Who uses it
+
+- **The person** points at a mark to read its row, clicks or drags to select marks in the
+  Notebook and in the Plots view, reads the selected rows in a table, and asks the Agent
+  about them. The selection is kept and travels with the next message.
+- **The Agent** sees each plot output's summary (layers, marks, how many are bound) in
+  `kernel.run` and `kernel.read`. It reads the figure with `figure.read`, finds marks by
+  condition (`where`), reads the rows of the person's selection, and points back with
+  `figure.select`. Its marks are shown highlighted, with its note, on the original plot.
+
+## Operations
+
+A figure is named by `{cellId, plot}`, a plot a cell drew, or by a file a cell saved it as:
+`{path}` reads the file as it is now, `{sha256}` names exact bytes (a page passes the
+version it shows).
+
+`figure.read {cellId, plot | path | sha256, form?, marks?, selection?, where?, limit?}` returns the summary
+of a figure (or, with `form: 'view'`, the whole record for drawing it), the selections kept
+for it, and rows for marks named directly, by a kept selection or by a condition.
+
+`figure.select {cellId, plot | path | sha256, marks, note?, changeId}` keeps a selection. It is
+immutable and named by the figure, the principal and its `changeId`; a saved file's selections
+follow its bytes: the same request returns the same
+selection, and the same `changeId` with other marks is refused.
+
+## Limits
+
+The protected resource is the session's time and the project's state folder.
+
+| Limit | Value | When it is exceeded |
+| --- | --- | --- |
+| Marks in a figure (`maxMarks`) | 50 000 | The plot stays a picture; `figureProblem` says why. |
+| Time to describe (`maxSeconds`) | 20 s | Describing stops; the plot stays a picture. |
+| Record size (`maxBytes`, kernel `maxFigureBytes`) | 16 MiB | The record is not kept; `figureProblem` says how large it was. |
+| Columns kept for a source or a layer (`maxColumns`) | 40 | Later columns are left out of the record. |
+| Session tables compared with a base graphics or matplotlib layer (`maxTables`) | 64 | Later tables are not compared; the layer keeps its drawn values. |
+| Numeric columns of one table compared with a layer (`maxComparedColumns`) | 64 | Later columns are not compared. A table with fewer rows than the layer's marks is not compared. |
+| Cells of one compared table (`maxTableCells`) | 5 000 000 | A larger table is not compared. |
+| Characters of a text value (`maxCellChars`) | 160 | The value is cut and ends with `…`. |
+| Marks in a selection | 5 000 | The selection is refused. |
+| Saved files described per cell (kernel `maxPlots`) | 8 | Later files stay pictures. |
+| Selections kept per figure | 32 | The oldest are removed. |
+| Rows in one read | 500 (50 by default) | The rest are counted in `rowsTotal`. |
+
+## Check
+
+```sh
+npm run test:figures
+```
+
+It describes real ggplot2 and patchwork plots, base graphics pages and a ComplexHeatmap in
+R, and matplotlib and seaborn figures in Python, through the Notebook and reads, matches and
+selects their marks. It saves plots with
+`ggsave()` as PNG and PDF, and writes base graphics, ggplot and heatmap pages to files the
+cell opens with `png()`, `pdf()` and `svg()`, and reads them by path and by bytes until the
+file is written again. Without R and ggplot2, svglite, xml2 and jsonlite the checks are skipped, not passed;
+so are the base graphics check without gridGraphics and the heatmap check without
+ComplexHeatmap. The Python checks run `RHO_PYTHON` (else `python3`) and are skipped without
+matplotlib, numpy and pandas; the seaborn check without seaborn.

package/node_modules/@rho-workspace/plugin-figures/dist/index.d.ts

@@ -0,0 +1,236 @@
+import { type Where } from './record.js';
+export { parseRecord, figureSummary, markRow, matchMarks, markName, parseMark, elementMarks } from './record.js';
+export type { FigureRecord, FigureLayer, FigureSource, MarkRef, MarkRow, Where } from './record.js';
+export declare const rExtension: string;
+export declare const pythonExtension: string;
+export interface FigureCell {
+    cellId: string;
+    number: number;
+    by: string;
+    purpose: string | null;
+    code: string;
+    language: string;
+    endedAt: string | null;
+    sessionId: string;
+}
+export interface FigureSourcePort {
+    record(cellId: string, plot: number): Promise<{
+        cell: FigureCell;
+        output: unknown;
+        bytes: Uint8Array;
+    }>;
+    saved?(sha256: string): Promise<{
+        cell: FigureCell;
+        output: unknown;
+        bytes: Uint8Array;
+    }>;
+}
+export type FigureRef = {
+    cellId?: string;
+    plot?: number;
+    path?: string;
+    sha256?: string;
+};
+export declare const figureLimits: {
+    maxSelectionMarks: number;
+    maxNoteChars: number;
+    keptSelections: number;
+    maxRows: number;
+    defaultRows: number;
+    matchMarks: number;
+};
+export type FigureLimits = typeof figureLimits;
+export interface Selection {
+    selectionId: string;
+    cellId: string;
+    plot?: number;
+    path?: string;
+    sha256?: string;
+    digest: string;
+    by: string;
+    at: string;
+    changeId: string;
+    note: string;
+    count: number;
+    layers: Array<{
+        layer: number;
+        geom: string;
+        marks: number;
+    }>;
+    marks: string[];
+}
+export declare class Figures {
+    private root;
+    private port;
+    private limits;
+    constructor(root: string, port: FigureSourcePort, limits?: Partial<FigureLimits>);
+    private folder;
+    private resolve;
+    private selections;
+    read(input: FigureRef & {
+        form?: 'summary' | 'view' | 'selections';
+        marks?: string[];
+        selection?: string;
+        where?: Where[];
+        limit?: number;
+    }): Promise<Record<string, unknown>>;
+    select(input: FigureRef & {
+        marks: string[];
+        note?: string;
+        changeId: string;
+    }, by: string): Promise<{
+        selection: Selection;
+    }>;
+    brief(ref: FigureRef, selectionId: string, rows: number): Promise<{
+        cell: number;
+        purpose: string | null;
+        selectionId: string;
+        count: number;
+        note: string;
+        layers: {
+            layer: number;
+            geom: string;
+            marks: number;
+        }[];
+        rows: ({
+            values: Record<string, import("./record.js").Cell>;
+            facets?: Record<string, string> | undefined;
+            mark: string;
+            geom: string;
+        } | {
+            built: Record<string, import("./record.js").Cell>;
+            facets?: Record<string, string> | undefined;
+            mark: string;
+            geom: string;
+        } | null)[];
+        plot: number;
+        cellId: string;
+    } | {
+        cell: number;
+        purpose: string | null;
+        selectionId: string;
+        count: number;
+        note: string;
+        layers: {
+            layer: number;
+            geom: string;
+            marks: number;
+        }[];
+        rows: ({
+            values: Record<string, import("./record.js").Cell>;
+            facets?: Record<string, string> | undefined;
+            mark: string;
+            geom: string;
+        } | {
+            built: Record<string, import("./record.js").Cell>;
+            facets?: Record<string, string> | undefined;
+            mark: string;
+            geom: string;
+        } | null)[];
+        path: string | undefined;
+        sha256: string | undefined;
+        cellId: string;
+    }>;
+}
+export declare const plugin: {
+    entryVersion: "1.0";
+    id: string;
+    package: string;
+    version: string;
+    requires: string[];
+    capabilities: string[];
+    presentation: import("@rho-workspace/plugin-contracts").PluginPresentation;
+    operations: ({
+        requires: string[];
+        inputSchema: {
+            type: string;
+            additionalProperties: boolean;
+            properties: Record<string, unknown>;
+            required: string[];
+        };
+        outputSchema: {
+            type: string;
+            additionalProperties: boolean;
+            properties: Record<string, unknown>;
+            required: string[];
+        };
+        effect: "read";
+        method: string;
+        presentation: {
+            order: number;
+            displayName: string;
+            description: string;
+            readOnly: true;
+            runsCode: false;
+        } | {
+            order: number;
+            displayName: string;
+            description: string;
+            readOnly: false;
+            runsCode: false;
+        };
+        version: "2.0";
+    } | {
+        requires: string[];
+        inputSchema: {
+            type: string;
+            additionalProperties: boolean;
+            properties: Record<string, unknown>;
+            required: string[];
+        };
+        outputSchema: {
+            type: string;
+            additionalProperties: boolean;
+            properties: Record<string, unknown>;
+            required: string[];
+        };
+        effect: "metadata";
+        method: string;
+        presentation: {
+            order: number;
+            displayName: string;
+            description: string;
+            readOnly: true;
+            runsCode: false;
+        } | {
+            order: number;
+            displayName: string;
+            description: string;
+            readOnly: false;
+            runsCode: false;
+        };
+        version: "2.0";
+    })[];
+    skills: {
+        id: string;
+        version: string;
+        content: string;
+        digest: string;
+        presentation: import("@rho-workspace/plugin-contracts").EntryPresentation;
+        intent: string;
+        requires: string[];
+        example: {
+            method: string;
+            input: {
+                cellId: string;
+                plot: number;
+                where: {
+                    column: string;
+                    op: string;
+                    value: number;
+                }[];
+                limit: number;
+            };
+        };
+        failureRecipes: {
+            kind: string;
+            message: string;
+            next: string;
+        }[];
+        verify: {
+            command: string;
+            description: string;
+        };
+    }[];
+    components: unknown[];
+};

package/node_modules/@rho-workspace/plugin-figures/dist/index.js

@@ -0,0 +1,165 @@
+import * as fs from 'node:fs/promises';
+import { createReadStream } from 'node:fs';
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { atomicJson, confined, digest, now, readJson, requireThat, stateDirectory } from '@rho-workspace/plugin-contracts';
+import { operationContracts } from './operations.js';
+import { operationPresentation, presentation, skillPresentation } from './presentation.js';
+import { figureSummary, markName, markRow, matchMarks, parseMark, parseRecord } from './record.js';
+export { parseRecord, figureSummary, markRow, matchMarks, markName, parseMark, elementMarks } from './record.js';
+// The R file a live R session sources to describe what its plots draw (see r/figures.R), and the
+// Python file a live Python session runs to describe its matplotlib figures (py/figures.py). The
+// Notebook's host hands them to each local session it starts.
+export const rExtension = fileURLToPath(new URL('../r/figures.R', import.meta.url));
+export const pythonExtension = fileURLToPath(new URL('../py/figures.py', import.meta.url));
+const sha256Pattern = /^[a-f0-9]{64}$/;
+async function fileDigest(file) {
+    const hash = createHash('sha256');
+    for await (const chunk of createReadStream(file))
+        hash.update(chunk);
+    return hash.digest('hex');
+}
+// The protected resource is the project's state folder. A selection keeps at most
+// maxSelectionMarks marks and a note of maxNoteChars; the newest keptSelections of each figure
+// are kept and older ones are removed. A read returns at most maxRows rows (defaultRows unless
+// asked) and names at most matchMarks of the marks a condition matched, saying how many there
+// were in all.
+export const figureLimits = { maxSelectionMarks: 5000, maxNoteChars: 500, keptSelections: 32, maxRows: 500, defaultRows: 50, matchMarks: 5000 };
+export class Figures {
+    root;
+    port;
+    limits;
+    constructor(root, port, limits = {}) {
+        this.root = root;
+        this.port = port;
+        this.limits = { ...figureLimits, ...limits };
+    }
+    folder(key) { return stateDirectory(this.root, `.rho/plugins/figures/${key}`); }
+    // The record a reference names, with the name its selections are kept under.
+    async resolve(ref) {
+        if (ref.cellId !== undefined || ref.plot !== undefined) {
+            requireThat(typeof ref.cellId === 'string' && Number.isInteger(ref.plot) && ref.path === undefined && ref.sha256 === undefined, 'invalid', 'Name a figure by cellId and plot, or by path or sha256 of a saved file.');
+            const found = await this.port.record(ref.cellId, ref.plot);
+            return { ...found, id: { cellId: ref.cellId, plot: ref.plot }, key: `${ref.cellId}-${ref.plot}`, parts: [ref.cellId, String(ref.plot)] };
+        }
+        requireThat(ref.path !== undefined || ref.sha256 !== undefined, 'invalid', 'Name a figure by cellId and plot, or by path or sha256 of a saved file.');
+        requireThat(this.port.saved, 'not_found', 'Figures saved to files are not kept here.');
+        let sha256 = ref.sha256;
+        if (sha256 === undefined) {
+            const file = await confined(this.root, ref.path);
+            const stat = await fs.stat(file).catch(() => null);
+            requireThat(stat?.isFile(), 'not_found', `${ref.path} is not a file in the project.`);
+            sha256 = await fileDigest(file);
+        }
+        requireThat(sha256Pattern.test(sha256), 'invalid', 'sha256 is the hex SHA-256 of the file\'s bytes.');
+        const found = await this.port.saved(sha256);
+        const saved = found.output;
+        return { ...found, id: { path: ref.path ?? saved.path ?? '', sha256, cellId: found.cell.cellId }, key: `file-${sha256.slice(0, 32)}`, parts: ['file', sha256] };
+    }
+    async selections(key) {
+        const folder = await this.folder(key);
+        const names = (await fs.readdir(folder)).filter(n => /^f-[a-f0-9]{16}\.json$/.test(n));
+        const all = await Promise.all(names.map(n => readJson(path.join(folder, n)).catch(() => null)));
+        return all.filter((s) => !!s).sort((a, b) => b.at.localeCompare(a.at));
+    }
+    async read(input) {
+        const { cell, output, bytes, id, key } = await this.resolve(input);
+        const record = parseRecord(bytes), figureDigest = digest(bytes);
+        const selections = await this.selections(key);
+        const view = input.form === 'view';
+        if (input.form === 'selections')
+            return { figure: { ...id, digest: figureDigest }, selections };
+        const result = {
+            figure: { ...id, digest: figureDigest, cell: { number: cell.number, by: cell.by, purpose: cell.purpose, language: cell.language, endedAt: cell.endedAt, code: view ? undefined : cell.code }, output },
+            selections: selections.map(s => view ? s : { ...s, marks: undefined }),
+            ...(view ? { record } : { summary: figureSummary(record) }),
+        };
+        let refs = null;
+        if (input.selection) {
+            const chosen = selections.find(s => s.selectionId === input.selection);
+            requireThat(chosen, 'not_found', 'This figure keeps no such selection; it may have been one of the oldest and removed.');
+            refs = chosen.marks.map(m => parseMark(m)).filter(Boolean);
+        }
+        if (input.marks) {
+            const named = input.marks.map(m => parseMark(m));
+            requireThat(named.every(r => r && r.layer < record.figure.layers.length && r.mark < record.figure.layers[r.layer].marks), 'invalid', 'A mark names no layer or row of this figure. Marks are "layer.row", both from 0, as figure.read names them.');
+            refs = named;
+        }
+        if (input.where) {
+            const known = new Set([...record.sources.flatMap(s => s.columns.map(c => c.name)), ...record.marks.flatMap(m => m.columns.map(c => c.name))]);
+            for (const w of input.where)
+                requireThat(known.has(w.column), 'invalid', `No source or built column is named ${w.column}. The summary lists each source's columns and each layer's built columns.`);
+            const matched = matchMarks(record, input.where, this.limits.matchMarks);
+            result.matched = { total: matched.total, marks: matched.marks.map(markName), cut: matched.total > matched.marks.length };
+            if (!refs)
+                refs = matched.marks;
+        }
+        if (refs) {
+            const limit = Math.min(input.limit ?? this.limits.defaultRows, this.limits.maxRows);
+            result.rowsTotal = refs.length;
+            result.rows = refs.slice(0, limit).map(r => markRow(record, r)).filter(Boolean);
+        }
+        return result;
+    }
+    // A selection never changes once kept. The same changeId from the same principal names the
+    // same selection; with other marks it is refused.
+    async select(input, by) {
+        const { bytes, id, key, parts } = await this.resolve(input);
+        const record = parseRecord(bytes), figureDigest = digest(bytes);
+        const marks = [...new Set(input.marks)];
+        requireThat(marks.length <= this.limits.maxSelectionMarks, 'limit', `A selection keeps at most ${this.limits.maxSelectionMarks} marks.`, { limit: 'maxSelectionMarks', maximum: this.limits.maxSelectionMarks });
+        const refs = marks.map(m => parseMark(m));
+        requireThat(refs.every(r => r && r.layer < record.figure.layers.length && r.mark < record.figure.layers[r.layer].marks), 'invalid', 'A mark names no layer or row of this figure. Marks are "layer.row", both from 0, as figure.read names them.');
+        const note = (input.note ?? '').trim();
+        requireThat(note.length <= this.limits.maxNoteChars, 'limit', `A note has at most ${this.limits.maxNoteChars} characters.`);
+        const selectionId = 'f-' + digest([...parts, by, input.changeId].join('\u0000')).slice(0, 16);
+        const folder = await this.folder(key), file = path.join(folder, selectionId + '.json');
+        const known = await readJson(file, null);
+        if (known) {
+            requireThat(known.marks.length === marks.length && known.marks.every((m, i) => m === marks[i]) && known.note === note, 'conflict', 'This change identity already names a different selection.');
+            return { selection: known };
+        }
+        const byLayer = new Map();
+        for (const r of refs)
+            byLayer.set(r.layer, (byLayer.get(r.layer) ?? 0) + 1);
+        const selection = { selectionId, ...id, digest: figureDigest, by, at: now(), changeId: input.changeId, note, count: marks.length,
+            layers: [...byLayer].map(([layer, n]) => ({ layer, geom: record.figure.layers[layer].geom, marks: n })), marks };
+        await atomicJson(file, selection);
+        const all = await this.selections(key);
+        for (const old of all.slice(this.limits.keptSelections))
+            await fs.rm(path.join(folder, old.selectionId + '.json'), { force: true });
+        return { selection };
+    }
+    // A short reading of one selection, for a message that carries it: what it is and its first rows.
+    async brief(ref, selectionId, rows) {
+        const read = await this.read({ ...ref, selection: selectionId, limit: rows });
+        const selection = read.selections.find(s => s.selectionId === selectionId);
+        const figure = read.figure;
+        return { cellId: figure.cellId, ...(figure.plot !== undefined ? { plot: figure.plot } : { path: figure.path, sha256: figure.sha256 }), cell: figure.cell.number, purpose: figure.cell.purpose, selectionId, count: selection.count, note: selection.note, layers: selection.layers,
+            rows: read.rows.map(r => r && ({ mark: r.mark, geom: r.geom, ...(Object.keys(r.facets).length ? { facets: r.facets } : {}), ...(r.values ? { values: r.values } : { built: r.built }) })) };
+    }
+}
+const content = [
+    'Plots drawn in the project\'s live R session are kept as figures: every ggplot (ggplot2 and what is built on it, such as ggtree, enrichplot, Seurat and patchwork) is described after its cell, with each drawn point, bar, box, line or label bound to the built row it draws and, where the layer\'s statistic keeps its input rows, to the row of the plot\'s data. A page drawn with base graphics (plot, points, text, barplot, abline) is described from what it drew: each drawn part is a layer (points, text, rect, lines, abline) whose marks keep the values they were drawn at, in the data\'s units, and points or labels whose x and y are two columns of a table in the session (a data frame, a DataFrame, a matrix) are bound to its rows, directly or through -log10, log10, log2, log2(x + 1) or log1p; the layer\'s mapping names those columns (y: "-log10(padj)"), and its notes say how many marks were drawn elsewhere (clipped to the axis), or that an earlier layer of the plot draws the same column on the same axis through another transform, so the two layers place their marks on different scales. A ComplexHeatmap is described cell by cell: each cell names its row, column, value and slice, and its row of the matrix. A figure drawn with matplotlib in the live Python session (and what draws through it: seaborn, pandas .plot) is described from its artists: scatter points, line vertices, bars, heatmap cells (pcolormesh, seaborn heatmap and clustermap), segments, polygons and text labels are marks keeping the values they were drawn at; points, lines and labels whose x and y are two columns of a table in the session (a DataFrame, a Series, a 2-D array), directly or through -log10, log10, log2, log2(x + 1) or log1p, are bound to its rows, and the layer\'s mapping says which (y: "-log10(padj)"); a label drawn at a bound point names that point\'s row, or is bound by its text; a heatmap cell names its row, column and value, and its row of the session table drawn. A layer\'s notes say what the describer noticed: marks drawn elsewhere than their values, a column drawn on the same axis through another transform than an earlier layer of the plot draws it, or heatmap labels that name other rows than the values beside them; the cell\'s plot output carries them. A cell\'s plot output names its layers and marks when it was described, or figureProblem when it was not; other grid drawings and images (imshow) stay pictures. A ggplot the cell saved to a project file with ggsave(), a page drawn on a file the cell opened with png(), pdf() or svg() and closed with dev.off() (plotMA, a heatmap\'s draw(), a ggplot\'s print()), or a matplotlib figure saved with savefig(), is kept as a figure of that file too (the cell\'s saved list): name it by {path} instead of {cellId, plot} in both operations. It holds while the file keeps the bytes the cell saved; a file written again since is a picture.',
+    '',
+    '1. figure.read {cellId, plot} returns the summary: each layer (counted from 0) with its geom, stat, mapping, constants, the data source its marks came from, how many marks it drew and whether they are bound to rows or groups (and why not); the plots, panels and facets; legend scales; and each source\'s columns and key column. Use it to check that a plot shows what you meant: the marks drawn against the source\'s rows, a mapping, a layer drawn from computed values.',
+    '2. Rows behind marks: pass marks ["L.M"] (layer L, built row M), selection (the person\'s selection named in their message), or where [{column, op, value}] with op eq, ne, lt, le, gt, ge, in or contains, on a source column or a built column (count, x). Each row gives the mark\'s built values and its source row with the key column (a gene, a cell barcode, a tree node).',
+    '3. To point the person at marks, figure.select {cellId, plot, marks, note, changeId}: they are shown highlighted in the plot with your note. It changes neither the plot nor its data; draw a new plot to change what is shown.',
+    '',
+    'A mark is named only within its figure. Speak about the same things across figures by the source key (gene, barcode, ID). An R figure is drawn again from the plot object at 7 × 5 in, so labels placed at random (ggrepel) may sit slightly differently from the picture; a matplotlib figure is drawn at its own size. A selected mark is what was drawn; what it means is still for you and the person to establish.',
+].join('\n');
+export const plugin = {
+    entryVersion: '1.0', id: 'figures', package: '@rho-workspace/plugin-figures', version: '0.5.1', requires: ['kernel'], capabilities: ['figures'], presentation,
+    operations: Object.entries(operationContracts).map(([method, contract]) => ({ method, presentation: operationPresentation[method], version: '2.0', ...structuredClone(contract), requires: [...contract.requires] })),
+    skills: [{ id: 'figures.read', version: '1.0', content, digest: digest(content), presentation: skillPresentation,
+            intent: 'Read what a plot drew and the rows behind its marks, and point the person at marks.', requires: ['figure.read', 'figure.select'],
+            example: { method: 'figure.read', input: { cellId: 'k-0123456789abcdef', plot: 1, where: [{ column: 'padj', op: 'lt', value: 0.01 }], limit: 20 } },
+            failureRecipes: [
+                { kind: 'not_found', message: 'This plot is a picture only: nothing described what it draws.', next: 'Only ggplot2, base graphics and ComplexHeatmap pages, and matplotlib figures, drawn in a Notebook cell are described. Draw it with one of them to make its marks selectable, or read the picture with kernel.plot.' },
+                { kind: 'not_found', message: 'No Notebook cell saved a figure as this file with these bytes: it is a picture only.', next: 'Save the plot in a Notebook cell (kernel.run): ggsave(), png() or pdf() and dev.off() in R, savefig() in Python. A file written by a script outside the live session is not described, nor a PDF of several pages.' },
+                { kind: 'invalid', message: 'A mark names no layer or row of this figure.', next: 'Read the summary first; marks are "layer.row" counted from 0 within this figure.' },
+            ],
+            verify: { command: 'npm run test:figures', description: 'Describes real ggplot2, ggtree, Seurat-style and patchwork plots in R, and matplotlib and seaborn figures in Python, and reads, matches and selects their marks.' } }],
+    components: [],
+};

package/node_modules/@rho-workspace/plugin-figures/dist/operations.d.ts

@@ -0,0 +1,44 @@
+export declare const selectionId: {
+    type: string;
+    pattern: string;
+};
+export declare const selectionSchema: {
+    type: string;
+    additionalProperties: boolean;
+    properties: Record<string, unknown>;
+    required: string[];
+};
+export declare const operationContracts: {
+    'figure.read': {
+        inputSchema: {
+            type: string;
+            additionalProperties: boolean;
+            properties: Record<string, unknown>;
+            required: string[];
+        };
+        outputSchema: {
+            type: string;
+            additionalProperties: boolean;
+            properties: Record<string, unknown>;
+            required: string[];
+        };
+        requires: string[];
+        effect: "read";
+    };
+    'figure.select': {
+        inputSchema: {
+            type: string;
+            additionalProperties: boolean;
+            properties: Record<string, unknown>;
+            required: string[];
+        };
+        outputSchema: {
+            type: string;
+            additionalProperties: boolean;
+            properties: Record<string, unknown>;
+            required: string[];
+        };
+        requires: string[];
+        effect: "metadata";
+    };
+};