@graphty/graph-io 0.3.19 → 0.3.21

package/src/formats/cys/tables.ts

@@ -0,0 +1,400 @@
+/**
+ * The tables of a Cytoscape 3 session: the CyCSV `.cytable` files (`research-session-and-style.md`
+ * section 2.4; Cytoscape's `CSVCyReader`) and the virtual columns `tables/cytables.xml` joins into
+ * them. Cells become XGMML att records, typed by the column's Java class, so the XGMML emitter
+ * applies the same column rules (types, widening, equations, hidden columns, renames) to a
+ * session's tables as to an XGMML file's atts.
+ */
+
+import { type ResolvedImportOptions } from "../../common/options.js";
+import { ImportReportBuilder } from "../../common/report.js";
+import { ImportError } from "../../types.js";
+import { CsvRecordReader } from "../csv/records.js";
+import { type AttRec } from "../xgmml/document.js";
+import { CYS_ISSUE, FORMAT } from "./constants.js";
+
+/** The Cytoscape type names of the Java classes a CyCSV column can hold. */
+const JAVA_TYPES: Readonly<Record<string, string>> = {
+    "java.lang.String": "String",
+    "java.lang.Long": "Long",
+    "java.lang.Integer": "Integer",
+    "java.lang.Double": "Double",
+    "java.lang.Boolean": "Boolean",
+};
+
+/** A list column's class: `java.util.List<java.lang.X>`. */
+const LIST_CLASS = /^java\.util\.List<\s*([\w.]+)\s*>$/;
+
+/** One column of a table. */
+interface CyColumn {
+    /** The name. */
+    readonly name: string;
+    /** The Cytoscape type of a scalar column, or of a list's items. */
+    readonly type: string;
+    /** A list column. */
+    readonly list: boolean;
+}
+
+/** One table, read. */
+export interface CyTable {
+    /** The table's path under `tables/` as the archive spells it (what cytables.xml names). */
+    readonly path: string;
+    /** The entry name, for messages. */
+    readonly entry: string;
+    /** The columns; the first is the primary key. */
+    readonly columns: readonly CyColumn[];
+    /** The rows by key text, in file order (the first row of a repeated key). */
+    readonly rows: ReadonlyMap<string, readonly string[]>;
+    /** The line each row starts on, by key. */
+    readonly lines: ReadonlyMap<string, number>;
+}
+
+/** What a table read reports besides its rows. */
+interface RowProblems {
+    short: number;
+    long: number;
+    repeated: number;
+}
+
+/**
+ * Read one CyCSV table. A table that cannot be read at all (an unknown CyCSV version or column
+ * class, a malformed header, broken CSV) is recorded as E_CYS_TABLE and skipped (null); rows with
+ * the wrong number of cells or a repeated key are counted in one W_CYS_TABLE_ROW.
+ * @param bytes - the entry's bytes
+ * @param path - the table's path under `tables/`
+ * @param entry - the entry name, for messages
+ * @param report - the import's report
+ * @param common - cancellation
+ * @returns the table, or null
+ */
+export async function readCyTable(
+    bytes: Uint8Array,
+    path: string,
+    entry: string,
+    report: ImportReportBuilder,
+    common: ResolvedImportOptions,
+): Promise<CyTable | null> {
+    const scratch = new ImportReportBuilder(FORMAT, 0);
+    const reader = new CsvRecordReader(bytes, scratch, { delimiter: ",", encoding: "utf-8", signal: common.signal });
+    const records: { readonly cells: string[]; readonly line: number }[] = [];
+    try {
+        for await (const cells of reader) {
+            records.push({ cells, line: reader.line });
+        }
+    } catch (err) {
+        if (err instanceof ImportError) {
+            return tableError(report, entry, scratch.issues.at(-1)?.message ?? err.message);
+        }
+        throw err;
+    }
+    let at = 0;
+    let version = 0;
+    if (records[0]?.cells.length === 2 && records[0].cells[0] === "CyCSV-Version") {
+        version = Number(records[0].cells[1]);
+        at = 1;
+    }
+    if (version !== 0 && version !== 1) {
+        return tableError(report, entry, `CyCSV version "${records[0].cells[1]}" is not 0 or 1`);
+    }
+    // version 1: names, types, column options, table title; version 0: names, types, table title
+    const headerLines = version === 1 ? 4 : 3;
+    if (records.length < at + headerLines) {
+        return tableError(report, entry, "the table header is incomplete");
+    }
+    const names = records[at].cells;
+    const classes = records[at + 1].cells;
+    if (names.length === 0 || classes.length !== names.length) {
+        return tableError(report, entry, `${names.length} column name(s) but ${classes.length} column class(es)`);
+    }
+    const columns: CyColumn[] = [];
+    for (let i = 0; i < names.length; i++) {
+        const column = columnOf(names[i], classes[i]);
+        if (column === null) {
+            return tableError(
+                report,
+                entry,
+                `column "${names[i]}" has the class "${classes[i]}", which graph-io cannot read`,
+            );
+        }
+        columns.push(column);
+    }
+    const rows = new Map<string, readonly string[]>();
+    const lines = new Map<string, number>();
+    const problems: RowProblems = { short: 0, long: 0, repeated: 0 };
+    for (const record of records.slice(at + headerLines)) {
+        const { cells } = record;
+        if (cells.length < columns.length) {
+            problems.short++;
+        } else if (cells.length > columns.length) {
+            problems.long++;
+        }
+        const key = cells[0];
+        if (rows.has(key)) {
+            problems.repeated++;
+            continue;
+        }
+        rows.set(key, cells.slice(0, columns.length));
+        lines.set(key, record.line);
+    }
+    if (problems.short + problems.long + problems.repeated > 0) {
+        report.warning(
+            "parse-error",
+            CYS_ISSUE.TABLE_ROW,
+            `${entry}: ${problems.short} row(s) with too few cells (the rest are unset), ${problems.long} with too many (the extra cells are ignored), ${problems.repeated} repeating a key (the first row is read)`,
+        );
+    }
+    return { path, entry, columns, rows, lines };
+}
+
+/**
+ * The column of a name and a Java class.
+ * @param name - the name
+ * @param javaClass - the class text
+ * @returns the column, or null for a class graph-io cannot read
+ */
+function columnOf(name: string, javaClass: string): CyColumn | null {
+    const scalar = JAVA_TYPES[javaClass.trim()];
+    if (scalar !== undefined) {
+        return { name, type: scalar, list: false };
+    }
+    const list = LIST_CLASS.exec(javaClass.trim());
+    const item = list === null ? undefined : JAVA_TYPES[list[1]];
+    return item === undefined ? null : { name, type: item, list: true };
+}
+
+/**
+ * Record E_CYS_TABLE for a table that is skipped.
+ * @param report - the report
+ * @param entry - the entry name
+ * @param reason - why
+ * @returns null
+ */
+function tableError(report: ImportReportBuilder, entry: string, reason: string): null {
+    report.error("parse-error", CYS_ISSUE.TABLE, `${entry}: ${reason}; the table is not read`);
+    return null;
+}
+
+/**
+ * The att record of one cell, or null for an unset cell. CyCSV's rules: an empty cell is unset
+ * except in a String column, where it is the empty string; a list cell holds its items separated
+ * by newlines (Java's `split`, so trailing empty items vanish; an empty String-list cell is one
+ * empty item, any other empty list cell unset); a cell starting with `=` is an equation.
+ * @param column - the column
+ * @param text - the cell text
+ * @param line - the row's line
+ * @param namespace - the table namespace the column belongs to (null for the network's own table)
+ * @param hidden - whether the column is hidden (HIDDEN and app tables)
+ * @returns the att, or null
+ */
+export function cellAtt(
+    column: CyColumn,
+    text: string,
+    line: number,
+    namespace: string | null,
+    hidden: boolean,
+): AttRec | null {
+    if (text.startsWith("=")) {
+        return att(column.name, column.list ? "List" : column.type, null, text, line, namespace, hidden, true);
+    }
+    if (!column.list) {
+        if (text.length === 0 && column.type !== "String") {
+            return null;
+        }
+        return att(column.name, column.type, null, text, line, namespace, hidden, false);
+    }
+    if (text.length === 0 && column.type !== "String") {
+        return null;
+    }
+    const list = att(column.name, "List", column.type, null, line, namespace, hidden, false);
+    for (const item of javaSplitLines(text)) {
+        if (item.length === 0 && column.type !== "String") {
+            continue;
+        }
+        list.children.push(att(column.name, column.type, null, item, line, namespace, hidden, false));
+    }
+    return list;
+}
+
+/**
+ * Java's `String.split("\n")`: trailing empty strings are removed, and a text without a newline
+ * is itself (so `""` is one empty item).
+ * @param text - the cell
+ * @returns the items
+ */
+function javaSplitLines(text: string): string[] {
+    if (!text.includes("\n")) {
+        return [text];
+    }
+    const items = text.split("\n");
+    while (items.length > 0 && items[items.length - 1].length === 0) {
+        items.pop();
+    }
+    return items;
+}
+
+/**
+ * An att record.
+ * @param name - the name
+ * @param cyType - the Cytoscape type
+ * @param elementType - a list's item type, or null
+ * @param value - the value, or null
+ * @param line - the line
+ * @param namespace - the table namespace, or null
+ * @param hidden - a hidden column
+ * @param equation - the value is a formula
+ * @returns the record
+ */
+function att(
+    name: string,
+    cyType: string,
+    elementType: string | null,
+    value: string | null,
+    line: number,
+    namespace: string | null,
+    hidden: boolean,
+    equation: boolean,
+): AttRec {
+    return {
+        name,
+        type: null,
+        cyType,
+        elementType,
+        value,
+        hidden,
+        equation,
+        children: [],
+        extra: {},
+        xml: null,
+        hasGraph: false,
+        text: "",
+        line,
+        namespace,
+    };
+}
+
+/** One virtual column of `tables/cytables.xml`. */
+export interface VirtualColumn {
+    /** The column name in the target table. */
+    readonly name: string;
+    /** The target table's path under `tables/`. */
+    readonly targetTable: string;
+    /** The source table's path. */
+    readonly sourceTable: string;
+    /** The source column's name. */
+    readonly sourceColumn: string;
+    /** The join column of the source (normally SUID). */
+    readonly sourceJoinKey: string;
+    /** The join column of the target (normally SUID). */
+    readonly targetJoinKey: string;
+}
+
+/** A resolved virtual column: its type and its value per target row key. */
+interface VirtualValues {
+    readonly column: CyColumn;
+    readonly values: ReadonlyMap<string, string>;
+}
+
+/**
+ * Resolve the virtual columns of one table: each one's values joined from its source table,
+ * following a source that is itself a virtual column. A column whose source table or column is
+ * missing, or whose sources form a cycle, is E_CYS_TABLE and skipped.
+ * @param target - the table
+ * @param virtuals - every virtual column of the session
+ * @param tableOf - reads (and caches) a table by path, null when it cannot be read or is absent
+ * @param report - the report
+ * @returns the virtual columns of the table, in cytables.xml order
+ */
+export async function virtualColumnsOf(
+    target: CyTable,
+    virtuals: readonly VirtualColumn[],
+    tableOf: (path: string) => Promise<CyTable | null>,
+    report: ImportReportBuilder,
+): Promise<VirtualValues[]> {
+    const out: VirtualValues[] = [];
+    for (const virtual of virtuals) {
+        if (virtual.targetTable !== target.path) {
+            continue;
+        }
+        const resolved = await resolve(virtual, virtuals, tableOf, new Set());
+        if (typeof resolved === "string") {
+            report.error(
+                "parse-error",
+                CYS_ISSUE.TABLE,
+                `${target.entry}: the virtual column "${virtual.name}" ${resolved}; the column is not read`,
+            );
+            continue;
+        }
+        const targetKey = target.columns.findIndex((c) => c.name === virtual.targetJoinKey);
+        const values = new Map<string, string>();
+        for (const [key, cells] of target.rows) {
+            const join = targetKey <= 0 ? key : cells[targetKey];
+            const value = join === undefined ? undefined : resolved.values.get(join);
+            if (value !== undefined) {
+                values.set(key, value);
+            }
+        }
+        out.push({ column: { ...resolved.column, name: virtual.name }, values });
+    }
+    return out;
+}
+
+/**
+ * The values of a virtual column's source, by the source's join key.
+ * @param virtual - the virtual column
+ * @param virtuals - every virtual column
+ * @param tableOf - the table reader
+ * @param seen - the virtual columns on the current chain (a cycle check)
+ * @returns the values, or the reason they cannot be read
+ */
+async function resolve(
+    virtual: VirtualColumn,
+    virtuals: readonly VirtualColumn[],
+    tableOf: (path: string) => Promise<CyTable | null>,
+    seen: Set<VirtualColumn>,
+): Promise<VirtualValues | string> {
+    if (seen.has(virtual)) {
+        return "is part of a cycle of virtual columns";
+    }
+    seen.add(virtual);
+    const source = await tableOf(virtual.sourceTable);
+    if (source === null) {
+        return `names the source table "${virtual.sourceTable}", which the session does not hold or cannot read`;
+    }
+    const joinIndex = source.columns.findIndex((c) => c.name === virtual.sourceJoinKey);
+    if (joinIndex < 0) {
+        return `joins on the column "${virtual.sourceJoinKey}", which its source table does not have`;
+    }
+    const joinOf = (key: string, cells: readonly string[]): string | undefined =>
+        joinIndex === 0 ? key : cells[joinIndex];
+    const own = source.columns.findIndex((c) => c.name === virtual.sourceColumn);
+    if (own >= 0) {
+        const values = new Map<string, string>();
+        for (const [key, cells] of source.rows) {
+            const join = joinOf(key, cells);
+            if (join !== undefined && cells[own] !== undefined) {
+                values.set(join, cells[own]);
+            }
+        }
+        return { column: source.columns[own], values };
+    }
+    const chained = virtuals.find((v) => v.targetTable === source.path && v.name === virtual.sourceColumn);
+    if (chained === undefined) {
+        return `names the source column "${virtual.sourceColumn}", which its source table does not have`;
+    }
+    const inner = await resolve(chained, virtuals, tableOf, seen);
+    if (typeof inner === "string") {
+        return inner;
+    }
+    // re-key the chained values (by the chained source's join key) to this source's join key
+    const values = new Map<string, string>();
+    const chainedJoin = source.columns.findIndex((c) => c.name === chained.targetJoinKey);
+    for (const [key, cells] of source.rows) {
+        const lookup = chainedJoin <= 0 ? key : cells[chainedJoin];
+        const value = lookup === undefined ? undefined : inner.values.get(lookup);
+        const join = joinOf(key, cells);
+        if (value !== undefined && join !== undefined) {
+            values.set(join, value);
+        }
+    }
+    return { column: inner.column, values };
+}

package/src/formats/dot/exporter.ts

@@ -70,6 +70,8 @@ export const DOT_LOSS = Object.freeze({
     EMPTY_COLUMN_DROPPED: LOSS.EMPTY_COLUMN,
     /** A role-less column named `label` reads back with the label role. */
     ROLE_ASSUMED: LOSS.ROLE_ASSUMED,
+    /** A parent that is a plain node is written as a node and a cluster of one name; it reads back marked as a cluster. */
+    CLUSTER_MARKED: "W_DOT_CLUSTER_MARKED",
 });
 
 /** The roles DOT has a slot for (the label attribute, key, ports, clusters); every other role is reported. */
@@ -510,6 +512,21 @@ class ExportPlan {
                 }
             }
         }
+        let unmarked = 0;
+        for (let i = 0; i < snapshot.nodeCount; i++) {
+            const marked = this.cluster !== null && this.cluster.isSet(i) && this.cluster.value(i) === true;
+            if (!marked && this.children.childrenOf(i).length > 0) {
+                unmarked++;
+            }
+        }
+        if (unmarked > 0) {
+            note(
+                DOT_LOSS.CLUSTER_MARKED,
+                `${unmarked} parent node(s) are written as a node and a cluster of the same name and read back with "${CLUSTER_COLUMN}" true`,
+                CLUSTER_COLUMN,
+                unmarked,
+            );
+        }
         const mutual = this.folding.mutualCount;
         if (mutual > 0) {
             note(

package/src/formats/dot/importer.ts

@@ -69,7 +69,7 @@ import {
     resolveImportOptions,
 } from "../../common/options.js";
 import { ImportReportBuilder } from "../../common/report.js";
-import { parseTextCell, TextCellWriter, WIDENING_UNSUPPORTED_CODE } from "../../common/text.js";
+import { inferTextDtype, parseTextCell, TextCellWriter, WIDENING_UNSUPPORTED_CODE } from "../../common/text.js";
 import { parseWeightText } from "../../common/weights.js";
 import { type CommonImportOptions, type GraphImporter, type ImportInput, type ImportReport } from "../../types.js";
 import {
@@ -1474,7 +1474,11 @@ class DotParser {
             if (attribute.name === LABEL_ATTRIBUTE) {
                 this.sink.setGraphValue(attribute.name, attribute.value, { dtype: "string", origin: DOT_ORIGIN });
             } else {
-                this.sink.setGraphValue(attribute.name, parseTextCell(attribute.value), { origin: DOT_ORIGIN });
+                // the dtype comes from the text's grammar, so "20.0" stays f64 as it does in a node column
+                this.sink.setGraphValue(attribute.name, parseTextCell(attribute.value), {
+                    dtype: inferTextDtype(attribute.value),
+                    origin: DOT_ORIGIN,
+                });
             }
         } catch (err) {
             this.report.recordError(err, { line: attribute.line, element: attribute.name });

package/src/formats/gexf/importer.ts

@@ -148,7 +148,6 @@ export const VIZ_VALUE_CODE = "W_GEXF_VIZ_VALUE";
 export const OPEN_BOUND_CONFLICT_CODE = "W_GEXF_OPEN_BOUND_CONFLICT";
 
 export {
-    DUPLICATE_ATTRIBUTE_CODE,
     DUPLICATE_NODE_CODE,
     ID_MERGED_CODE,
     MISSING_ENDPOINT_CODE,

package/src/formats/gml/exporter.ts

@@ -830,17 +830,6 @@ function countMangled(snapshot: GraphSnapshot): number {
 
 // ============================================================ writing
 
-/**
- * The GML text of a real: the shortest text of the dtype with a decimal point guaranteed
- * (`2.0`, `1.0e-7`), the NetworkX spellings `+INF` / `-INF` / `NAN` for the non-finite values.
- * @param value - the value
- * @param dtype - the dtype the value came from (f32 uses the fround-shortest text)
- * @returns the text
- */
-export function gmlRealText(value: number, dtype: "f32" | "f64" | "i32" | "u32" | "u8" = "f64"): string {
-    return formatGmlReal(value, dtype);
-}
-
 /**
  * The GML text of a number by the dtype and origin of its column: an integer text for the integer
  * dtypes and for an f64 column that came from GML `int` values, a real text otherwise.
@@ -855,12 +844,12 @@ function numberText(value: number, meta: ColumnMeta): string {
         case "u8":
             return formatInteger(value);
         case "f32":
-            return gmlRealText(value, "f32");
+            return formatGmlReal(value, "f32");
         default:
             if (meta.origin?.type === "int" && Number.isInteger(value)) {
                 return formatInteger(value);
             }
-            return gmlRealText(value, "f64");
+            return formatGmlReal(value, "f64");
     }
 }
 
@@ -873,7 +862,7 @@ function numberText(value: number, meta: ColumnMeta): string {
 function jsonScalarText(value: number | string | boolean): string {
     switch (typeof value) {
         case "number":
-            return Number.isInteger(value) ? formatInteger(value) : gmlRealText(value, "f64");
+            return Number.isInteger(value) ? formatInteger(value) : formatGmlReal(value, "f64");
         case "boolean":
             return value ? "1" : "0";
         default:
@@ -897,13 +886,13 @@ function itemText(item: unknown, itemDtype: string, meta: ColumnMeta): string {
                 case "u8":
                     return formatInteger(item);
                 case "f32":
-                    return gmlRealText(item, "f32");
+                    return formatGmlReal(item, "f32");
                 case "json":
                     return jsonScalarText(item);
                 default:
                     return meta.origin?.type === "int" && Number.isInteger(item)
                         ? formatInteger(item)
-                        : gmlRealText(item, "f64");
+                        : formatGmlReal(item, "f64");
             }
         case "boolean":
             return item ? "1" : "0";
@@ -1234,7 +1223,7 @@ function originalIdText(id: NodeId): string {
     if (typeof id === "string") {
         return quoteGmlString(id);
     }
-    return Number.isSafeInteger(id) ? formatInteger(id) : gmlRealText(id, "f64");
+    return Number.isSafeInteger(id) ? formatInteger(id) : formatGmlReal(id, "f64");
 }
 
 /**
@@ -1308,7 +1297,7 @@ function* gmlParts(context: WriteContext): Generator<string, void, undefined> {
             const text =
                 integerWeights && Number.isInteger(weight)
                     ? formatInteger(weight)
-                    : gmlRealText(weight, context.weights.dtype);
+                    : formatGmlReal(weight, context.weights.dtype);
             w.line("    ", plan.weightKey, text);
         }
         for (const { column, key } of context.edgeColumns) {

package/src/formats/json/exporter.ts

@@ -23,6 +23,7 @@ import { type Column, GraphFormatError, type GraphSnapshot, INVALID_INDEX, type
 import { type PairFolding, pairFolding } from "../../common/direction.js";
 import { checkCapabilities, countMixedEdges, LOSS } from "../../common/export.js";
 import { formatF32, formatF64 } from "../../common/format.js";
+import { flipY } from "../../common/json-elements.js";
 import { type ResolvedExportOptions, resolveExportOptions } from "../../common/options.js";
 import { explicitWeights } from "../../common/weights.js";
 import { encodeChunks, joinText } from "../../common/writer.js";
@@ -1520,7 +1521,8 @@ function* writeCytoscape(snapshot: GraphSnapshot, p: Plan): Generator<string, vo
                 w.key("position");
                 w.open("{");
                 w.member("x", numberText(value[0], f32, c.nonfinite));
-                w.member("y", numberText(value[1], f32, c.nonfinite));
+                // stored y-up; Cytoscape's y grows downward
+                w.member("y", numberText(flipY(value[1]), f32, c.nonfinite));
                 w.close("}");
             }
         }

package/src/formats/json/importer.ts

@@ -66,7 +66,7 @@ import {
 import { DirectionResolver, type EdgeKind } from "../../common/direction.js";
 import { ID_MERGED_CODE, IdCoercer } from "../../common/ids.js";
 import { readText, textChunks, throwIfAborted } from "../../common/input.js";
-import { MAYBE_UNSAFE_INTEGER, reviveNonstandard, rewriteNumbers } from "../../common/json-elements.js";
+import { flipY, MAYBE_UNSAFE_INTEGER, reviveNonstandard, rewriteNumbers } from "../../common/json-elements.js";
 import {
     chooseGraph,
     type ImportFormatDefaults,
@@ -2669,7 +2669,8 @@ function importCytoscape(ctx: ImportContext, root: unknown): void {
             if (position !== undefined && position !== null) {
                 if (isJsonObject(position) && typeof position.x === "number" && typeof position.y === "number") {
                     point[0] = position.x;
-                    point[1] = position.y;
+                    // Cytoscape's y grows downward; positions are stored y-up (the exporter flips back)
+                    point[1] = flipY(position.y);
                     ctx.nodes.set(positionColumn, index, point);
                 } else {
                     report.error(