@graphty/graph-io 0.3.16 → 0.3.18

package/src/common/codes.ts

@@ -108,6 +108,64 @@ export const BAD_OPTIONS_CODE = "W_BAD_OPTIONS";
 /** A repeated edge id in a format whose edge ids are unique; the second edge is skipped. */
 export const DUPLICATE_EDGE_ID_CODE = "E_DUPLICATE_EDGE_ID";
 
+/** A value does not parse as its declared type; the cell is left unset. */
+export const BAD_VALUE_CODE = "E_BAD_VALUE";
+
+/**
+ * A column's dtype was widened (design section 5.1) because a later value did not fit: an i32
+ * column meeting a value above 2^31, two declared types for one attribute.
+ */
+export const WIDENED_CODE = "W_WIDENED";
+
+/**
+ * A reference that is not a containment link (an attribute's element id, a layout or bypass
+ * entry, a subnetwork member, a view's network, an undeclared target) names nothing; reported
+ * once per kind with the count.
+ */
+export const DANGLING_REFERENCE_CODE = "W_DANGLING_REFERENCE";
+
+/** The same attribute twice on one element; one value is kept (the later, unless the format's specification says the first). */
+export const DUPLICATE_ATTRIBUTE_CODE = "W_DUPLICATE_ATTRIBUTE";
+
+/** A containment link would close a parent cycle; that one link is dropped. */
+export const PARENT_CYCLE_CODE = "E_PARENT_CYCLE";
+
+/** A formula (Cytoscape's `=ABS($x)`) is kept as its text; it is never evaluated. */
+export const EQUATION_AS_TEXT_CODE = "W_EQUATION_AS_TEXT";
+
+/**
+ * The file's style rules (defaults, mappings, dependencies, visual property aspects) are not
+ * applied to the snapshot; recorded once per import, the message names what was not applied.
+ */
+export const STYLES_NOT_IMPORTED_CODE = "W_STYLES_NOT_IMPORTED";
+
+/** A CX array member that is not a one-key object holding an array or an object; the block is skipped. */
+export const BAD_ASPECT_BLOCK_CODE = "E_BAD_ASPECT_BLOCK";
+
+/** A CX aspect out of its place (after the post-metadata, a status that is not last, a block buffered for what it depends on). */
+export const ASPECT_ORDER_CODE = "W_ASPECT_ORDER";
+
+/** A declared element count disagrees with what was read. */
+export const COUNT_MISMATCH_CODE = "W_COUNT_MISMATCH";
+
+/** The producer marked the document as failed (CX `status.success: false`): it is incomplete (fatal). */
+export const STATUS_FAILED_CODE = "E_STATUS_FAILED";
+
+/** The producer marked the document as successful but attached an error text. */
+export const STATUS_WARNING_CODE = "W_STATUS_WARNING";
+
+/**
+ * The input is beyond a size limit (a zip's uncompressed total or ratio, a document longer than
+ * one string); the same string as graph-format's E_TOO_LARGE, recorded with category "unsupported".
+ */
+export const TOO_LARGE_CODE = "E_TOO_LARGE";
+
+/** `graphIndex` is beyond the graphs of the input, or `graphName` names none of them (fatal). */
+export const GRAPH_NOT_FOUND_CODE = "E_GRAPH_NOT_FOUND";
+
+/** `graphName` names more than one graph of the input; the message lists their indexes (fatal). */
+export const AMBIGUOUS_GRAPH_NAME_CODE = "E_AMBIGUOUS_GRAPH_NAME";
+
 // ============================================================ exporter loss notes
 
 /** A role column the format has no slot for is written as a plain attribute (the role is lost). */

package/src/common/input.ts

@@ -262,6 +262,22 @@ function startsWithUtf8(bytes: Uint8Array): boolean {
     }
 }
 
+/**
+ * A zip entry name as text (APPNOTE 4.4.17): UTF-8 when the bytes are valid UTF-8, whether or not
+ * the entry sets the language-encoding flag (bit 11), else windows-1252 (WHATWG has no CP437, and
+ * session entry names are ASCII in practice). Never throws: a name is a matching key, never a path,
+ * so an undecodable one still has to name its entry.
+ * @param bytes - the name bytes from the central directory or a local header
+ * @returns the name
+ */
+export function decodeEntryName(bytes: Uint8Array): string {
+    try {
+        return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+    } catch {
+        return new TextDecoder("windows-1252").decode(bytes);
+    }
+}
+
 /**
  * Join byte chunks.
  * @param chunks - the chunks

package/src/common/ontology.ts

@@ -0,0 +1,169 @@
+/**
+ * What the OBO importer and the JSON importer's `obographs` dialect share (design section 1.0, the
+ * `ontology.ts` building block): the OBO column vocabulary (names, dtypes, roles), so the `.obo` and
+ * the `.json` of one ontology give the same columns, and the OBO 1.4 rule for turning the IRIs
+ * OBO Graphs writes back into the identifiers the `.obo` file writes (section 4.6).
+ */
+
+import { type ColumnDecl } from "@graphty/graph-format";
+
+/** The dtypes the OBO vocabulary uses. */
+type OboDtype = "string" | "dict" | "bool" | "list" | "json";
+
+/** One column of the OBO vocabulary. */
+interface OboColumnSpec {
+    /** The dtype. */
+    readonly dtype: OboDtype;
+    /** The role, when the column carries one. */
+    readonly role?: "label" | "kind" | undefined;
+}
+
+/**
+ * The node columns of the OBO vocabulary, keyed by column name (design section 4.2). The names are
+ * the OBO tag names, so a Gene Ontology user finds `namespace`, `def` and `is_obsolete` under the
+ * names the GO documentation uses.
+ */
+export const OBO_NODE_COLUMNS: Readonly<Record<string, OboColumnSpec>> = Object.freeze({
+    type: { dtype: "dict" },
+    name: { dtype: "string", role: "label" },
+    namespace: { dtype: "dict" },
+    def: { dtype: "string" },
+    "def.xrefs": { dtype: "list" },
+    comment: { dtype: "string" },
+    synonym: { dtype: "json" },
+    xref: { dtype: "list" },
+    "xref.descriptions": { dtype: "json" },
+    alt_id: { dtype: "list" },
+    subset: { dtype: "list" },
+    replaced_by: { dtype: "list" },
+    consider: { dtype: "list" },
+    is_obsolete: { dtype: "bool" },
+    is_anonymous: { dtype: "bool" },
+    builtin: { dtype: "bool" },
+    created_by: { dtype: "string" },
+    creation_date: { dtype: "string" },
+    intersection_of: { dtype: "json" },
+    union_of: { dtype: "list" },
+    equivalent_to: { dtype: "list" },
+    disjoint_from: { dtype: "list" },
+    property_value: { dtype: "json" },
+    // Typedef frames, under typedefs: "nodes"
+    domain: { dtype: "string" },
+    range: { dtype: "string" },
+    inverse_of: { dtype: "string" },
+    transitive_over: { dtype: "list" },
+    disjoint_over: { dtype: "list" },
+    holds_over_chain: { dtype: "json" },
+    equivalent_to_chain: { dtype: "json" },
+    expand_assertion_to: { dtype: "json" },
+    expand_expression_to: { dtype: "json" },
+    is_cyclic: { dtype: "bool" },
+    is_reflexive: { dtype: "bool" },
+    is_symmetric: { dtype: "bool" },
+    is_anti_symmetric: { dtype: "bool" },
+    is_asymmetric: { dtype: "bool" },
+    is_transitive: { dtype: "bool" },
+    is_functional: { dtype: "bool" },
+    is_inverse_functional: { dtype: "bool" },
+    is_metadata_tag: { dtype: "bool" },
+    is_class_level: { dtype: "bool" },
+    // OBO Graphs only
+    propertyType: { dtype: "dict" },
+    // what has no column of its own
+    "obo.qualifiers": { dtype: "json" },
+    "obo.unrecognized": { dtype: "json" },
+});
+
+/** The edge columns of the OBO vocabulary. */
+const OBO_EDGE_COLUMNS: Readonly<Record<string, OboColumnSpec>> = Object.freeze({
+    relation: { dtype: "dict", role: "kind" },
+    qualifiers: { dtype: "json" },
+    meta: { dtype: "json" },
+});
+
+/** The node column that marks a node made for an undeclared reference (design section 4.2). */
+export const PLACEHOLDER_COLUMN = "graphty.placeholder";
+
+/**
+ * The declaration of an OBO vocabulary column.
+ * @param domain - node or edge
+ * @param name - the column name (a key of OBO_NODE_COLUMNS / OBO_EDGE_COLUMNS, or the placeholder column)
+ * @returns the declaration, nullable, with origin `{ format: "obo", id: name }`
+ */
+export function oboColumnDecl(domain: "node" | "edge", name: string): ColumnDecl {
+    if (name === PLACEHOLDER_COLUMN) {
+        return { name, dtype: "bool", nullable: true, origin: { format: "graphty", id: "placeholder" } };
+    }
+    const spec = (domain === "node" ? OBO_NODE_COLUMNS : OBO_EDGE_COLUMNS)[name];
+    const decl: ColumnDecl = { name, dtype: spec.dtype, nullable: true, origin: { format: "obo", id: name } };
+    if (spec.dtype === "list") {
+        decl.itemDtype = "string";
+    }
+    if (spec.role !== undefined) {
+        decl.role = spec.role;
+    }
+    return decl;
+}
+
+/** The OBO PURL base every OBO Foundry IRI starts with. */
+const OBO_PURL = "http://purl.obolibrary.org/obo/";
+
+/** The oboInOwl namespace of the OBO-to-OWL mapping's annotation properties. */
+const OBO_IN_OWL = "http://www.geneontology.org/formats/oboInOwl#";
+
+/**
+ * An IRI as the identifier the `.obo` file writes (the OBO 1.4 mapping, section 5.9, read
+ * backwards): `http://purl.obolibrary.org/obo/GO_0008150` is `GO:0008150` (the prefix is the text
+ * before the first underscore), and `http://purl.obolibrary.org/obo/go#regulates` (how the OWL
+ * translation writes an unprefixed OBO id: subsets, relations, synonym types) is `regulates`.
+ * Every other IRI, and an OBO PURL that fits neither form (`.../obo/T/Female`), is kept.
+ * @param iri - the IRI
+ * @returns the CURIE or local id, or the IRI unchanged
+ */
+export function compactOboIri(iri: string): string {
+    if (!iri.startsWith(OBO_PURL)) {
+        return iri;
+    }
+    const rest = iri.slice(OBO_PURL.length);
+    const hash = rest.indexOf("#");
+    if (hash > 0) {
+        const local = rest.slice(hash + 1);
+        return local.length > 0 && !rest.slice(0, hash).includes("/") ? local : iri;
+    }
+    const underscore = rest.indexOf("_");
+    if (underscore <= 0 || rest.includes("/") || underscore === rest.length - 1) {
+        return iri;
+    }
+    return `${rest.slice(0, underscore)}:${rest.slice(underscore + 1)}`;
+}
+
+/** The OBO synonym scopes. */
+export const SYNONYM_SCOPES: ReadonlySet<string> = new Set(["EXACT", "BROAD", "NARROW", "RELATED"]);
+
+/**
+ * The OBO synonym scope of an OBO Graphs synonym predicate (`hasExactSynonym`, with or without the
+ * oboInOwl namespace).
+ * @param pred - the predicate
+ * @returns the scope, or null for a predicate that is not one of the four
+ */
+export function synonymScopeOf(pred: string): string | null {
+    const local = pred.startsWith(OBO_IN_OWL) ? pred.slice(OBO_IN_OWL.length) : pred;
+    const match = /^has(Exact|Broad|Narrow|Related)Synonym$/.exec(local);
+    return match === null ? null : match[1].toUpperCase();
+}
+
+/**
+ * The OBO tag a `basicPropertyValues` predicate of OBO Graphs came from (the OBO-to-OWL mapping of
+ * the tags that are annotations), so the `.json` of an ontology fills the same columns as its
+ * `.obo`. `shorthand` is the relation's short name; every predicate not listed is a
+ * `property_value`.
+ */
+export const OBOGRAPHS_PREDICATE_TAGS: ReadonlyMap<string, string> = new Map([
+    [`${OBO_IN_OWL}hasOBONamespace`, "namespace"],
+    [`${OBO_IN_OWL}hasAlternativeId`, "alt_id"],
+    [`${OBO_IN_OWL}created_by`, "created_by"],
+    [`${OBO_IN_OWL}creation_date`, "creation_date"],
+    [`${OBO_PURL}IAO_0100001`, "replaced_by"],
+    [`${OBO_IN_OWL}consider`, "consider"],
+    [`${OBO_IN_OWL}shorthand`, "shorthand"],
+]);

package/src/common/options.ts

@@ -7,8 +7,14 @@
 
 import { type DuplicatePolicy, GraphFormatError, type GraphSink, type IdCoercion } from "@graphty/graph-format";
 
-import { type CommonExportOptions, type CommonImportOptions } from "../types.js";
-import { OPTION_IGNORED_CODE, SINK_OPTION_CODE } from "./codes.js";
+import { type CommonExportOptions, type CommonImportOptions, type GraphChoiceOptions } from "../types.js";
+import {
+    AMBIGUOUS_GRAPH_NAME_CODE,
+    GRAPH_NOT_FOUND_CODE,
+    NO_GRAPH_CODE,
+    OPTION_IGNORED_CODE,
+    SINK_OPTION_CODE,
+} from "./codes.js";
 import { canonicalEncoding } from "./input.js";
 import { type ImportReportBuilder } from "./report.js";
 
@@ -188,6 +194,76 @@ export function reportUnusedOptions(
     return recorded;
 }
 
+/**
+ * The graph an importer reads from an input that holds several: the one `graphIndex` or
+ * `graphName` names, else the first. A choice that names no graph is E_GRAPH_NOT_FOUND, a name two
+ * graphs share is E_AMBIGUOUS_GRAPH_NAME, and an input with no graph at all is E_NO_GRAPH, each
+ * fatal (the report fails with ImportError).
+ * @param names - each graph's name (null for an unnamed graph), in document order
+ * @param options - the caller's graphIndex / graphName
+ * @param report - the report a failure is recorded in
+ * @returns the index of the graph to read; E_UNSUPPORTED for an option of the wrong type, or both
+ */
+export function chooseGraph(
+    names: readonly (string | null)[],
+    options: GraphChoiceOptions | undefined,
+    report: ImportReportBuilder,
+): number {
+    const { graphIndex, graphName } = options ?? {};
+    if (
+        graphIndex !== undefined &&
+        (typeof graphIndex !== "number" || !Number.isInteger(graphIndex) || graphIndex < 0)
+    ) {
+        throw new GraphFormatError(
+            "E_UNSUPPORTED",
+            `option graphIndex: ${describe(graphIndex)} is not a non-negative integer`,
+            {
+                option: "graphIndex",
+                found: graphIndex,
+            },
+        );
+    }
+    if (graphName !== undefined && typeof graphName !== "string") {
+        throw new GraphFormatError("E_UNSUPPORTED", `option graphName: ${describe(graphName)} is not a string`, {
+            option: "graphName",
+            found: graphName,
+        });
+    }
+    if (graphIndex !== undefined && graphName !== undefined) {
+        throw new GraphFormatError("E_UNSUPPORTED", "options graphIndex and graphName both choose a graph; pass one", {
+            option: "graphName",
+            found: graphName,
+        });
+    }
+    if (names.length === 0) {
+        return report.fail(NO_GRAPH_CODE, "the input holds no graph");
+    }
+    if (graphName !== undefined) {
+        const matches = names.flatMap((name, i) => (name === graphName ? [i] : []));
+        if (matches.length > 1) {
+            return report.fail(
+                AMBIGUOUS_GRAPH_NAME_CODE,
+                `graphName ${JSON.stringify(graphName)} names the graphs at indexes ${matches.join(", ")}; pass graphIndex`,
+                { element: graphName },
+            );
+        }
+        if (matches.length === 0) {
+            return report.fail(
+                GRAPH_NOT_FOUND_CODE,
+                `graphName ${JSON.stringify(graphName)} names none of the ${names.length} graph(s)`,
+                { element: graphName },
+                { names: [...names] },
+            );
+        }
+        return matches[0];
+    }
+    const index = graphIndex ?? 0;
+    if (index >= names.length) {
+        return report.fail(GRAPH_NOT_FOUND_CODE, `graphIndex ${index} is beyond the ${names.length} graph(s)`);
+    }
+    return index;
+}
+
 /**
  * Apply the design section 8.4 defaults to an importer's common options and check every enum
  * value. Format-specific options in the same object are ignored here.

package/src/formats/json/dialect.ts

@@ -32,17 +32,19 @@ export const JSON_DIALECTS: readonly JsonDialect[] = Object.freeze([
 ]);
 
 /**
- * The dialects the importer reads: every JsonDialect plus two it only reads, NetworkX
- * adjacency_data (`nodes` plus one neighbour list per node under `adjacency`) and tree_data (a
- * nested `id` / `children` record). The exporter writes neither; write node-link instead.
+ * The dialects the importer reads: every JsonDialect plus three it only reads, NetworkX
+ * adjacency_data (`nodes` plus one neighbour list per node under `adjacency`), tree_data (a
+ * nested `id` / `children` record) and OBO Graphs (`graphs[]` of `sub` / `pred` / `obj` edges, the
+ * JSON form of the Gene Ontology and the OBO Foundry ontologies). The exporter writes none of them.
  */
-export type JsonImportDialect = JsonDialect | "adjacency" | "tree";
+export type JsonImportDialect = JsonDialect | "adjacency" | "tree" | "obographs";
 
 /** Every dialect the importer reads, for option checking and messages. */
 export const JSON_IMPORT_DIALECTS: readonly JsonImportDialect[] = Object.freeze([
     ...JSON_DIALECTS,
     "adjacency",
     "tree",
+    "obographs",
 ]);
 
 /** The key under `meta.extra` that holds the shape record (design section 8.5). */
@@ -116,8 +118,9 @@ export function isJsonImportDialect(value: unknown): value is JsonImportDialect
 
 /**
  * The dialect of a parsed JSON document, by the shape rules of design section 8.2 (Cytoscape:
- * `elements` or a top-level array of `{ data }` elements; JGF: `graph.nodes` / `graph.edges` or
- * `graphs[]`; graphology: `options.type` / `options.multi`, `key` nodes without `id`, edges with
+ * `elements` or a top-level array of `{ data }` elements; OBO Graphs: `graphs[]` whose first graph
+ * has an edge with `sub` (or `subj`) and `obj` or a `pred`, or a node with `lbl`, `meta` or an OWL
+ * `type`; JGF: `graph.nodes` / `graph.edges` or any other `graphs[]`; graphology: `options.type` / `options.multi`, `key` nodes without `id`, edges with
  * `undirected` or an `attributes` record; vis: edges with `from` / `to`; d3: `links` without
  * `directed` / `multigraph` / `graph`; NetworkX adjacency_data: `nodes` and `adjacency` without
  * `links` / `edges`; NetworkX tree_data: `children` without `nodes` / `links` / `edges`; else
@@ -141,7 +144,7 @@ export function sniffJsonDialect(root: unknown): JsonImportDialect | null {
         return "jgf";
     }
     if (Array.isArray(root.graphs)) {
-        return "jgf";
+        return isOboGraph(firstJsonObject(root.graphs)) ? "obographs" : "jgf";
     }
     if (!hasKey(root, "edges") && !hasKey(root, "links")) {
         if (hasKey(root, "nodes") && hasKey(root, "adjacency")) {
@@ -171,6 +174,31 @@ export function sniffJsonDialect(root: unknown): JsonImportDialect | null {
     return bare && hasKey(root, "links") ? "d3" : "node-link";
 }
 
+/** The node types of OBO Graphs (the OWL entity kinds). */
+const OBOGRAPHS_NODE_TYPES: ReadonlySet<unknown> = new Set(["CLASS", "INDIVIDUAL", "PROPERTY"]);
+
+/**
+ * Whether a graph of a `graphs[]` document is an OBO Graphs graph rather than JGF: anywhere in its
+ * nodes or edges, an edge with `sub` (or the outdated `subj`) and `obj`, or a `pred`, or a node
+ * with `lbl`, `meta` or a `type` of CLASS / INDIVIDUAL / PROPERTY (design 1.6: looking only at the
+ * first node and edge misses graphs with no edges and graphs whose first node has no `lbl`).
+ * @param graph - the first graph, or null
+ * @returns true for OBO Graphs
+ */
+function isOboGraph(graph: Record<string, unknown> | null): boolean {
+    if (graph === null) {
+        return false;
+    }
+    const isEdge = (e: unknown): boolean =>
+        isJsonObject(e) && ((hasKey(e, "obj") && (hasKey(e, "sub") || hasKey(e, "subj"))) || hasKey(e, "pred"));
+    const isNode = (n: unknown): boolean =>
+        isJsonObject(n) && (hasKey(n, "lbl") || hasKey(n, "meta") || OBOGRAPHS_NODE_TYPES.has(n.type));
+    return (
+        (Array.isArray(graph.edges) && graph.edges.some(isEdge)) ||
+        (Array.isArray(graph.nodes) && graph.nodes.some(isNode))
+    );
+}
+
 /**
  * The first object of an array, or null.
  * @param value - maybe an array
@@ -223,6 +251,8 @@ export const DIALECT_DEFAULT_DIRECTED: Readonly<Record<JsonImportDialect, boolea
     // networkx adjacency_data declares `directed`; tree_graph always builds a DiGraph
     adjacency: false,
     tree: true,
+    // OBO Graphs edges point from the subject (child) to the object (parent)
+    obographs: true,
 });
 
 /**