@jbrowse/graph-walks 0.1.0 → 1.1.0

package/README.md

@@ -4,11 +4,13 @@ Cuts a window out of a pangenome graph stored as
 [gfa-to-tabix](https://github.com/GMOD/gfa-to-tabix) walk files, by range
 requests.
 
-- **In:** a `gfa-to-tabix --walks` file set and a region on its reference
+- **In:** a `gfa-to-tabix --walks` file, `<prefix>.<sample>.walks.bed.gz` with
+  its `.tbi`, and a region on its reference
 - **Out:** the reference over the region, every haplotype's walk through it, and
   the nodes and links they visit, as typed arrays
-- Reads format 1 (`.walks.bed.gz` with `.nodes.bed.gz` and `.links.bed.gz`) and
-  format 2 (`.walks.bed.gz` alone), each with its `.tbi`
+- Reads walk format 2, which gfa-to-tabix writes from 1.0. The reader refuses a
+  format 1 file, from gfa-to-tabix 0.12 or earlier, with a `WalkFormatError`
+  asking for a rebuild
 - Has no runtime dependencies: it reads through any object with
   [@gmod/tabix](https://github.com/GMOD/tabix-js)'s `TabixIndexedFile` methods
 
@@ -25,29 +27,22 @@ npm install @jbrowse/graph-walks @gmod/tabix
 
 ```ts
 import { TabixIndexedFile } from '@gmod/tabix'
-import {
-  WalkReader,
-  panSNHaplotype,
-  walkNameFilter,
-} from '@jbrowse/graph-walks'
+import { WalkReader, walksKept } from '@jbrowse/graph-walks'
 import { RemoteFile } from 'generic-filehandle2'
 
-const file = (url: string) =>
+const url = 'https://example.org/hprc-v2.1-mc-grch38.GRCh38.walks.bed.gz'
+const reader = new WalkReader(
   new TabixIndexedFile({
     filehandle: new RemoteFile(url),
     tbiFilehandle: new RemoteFile(`${url}.tbi`),
-  })
-const prefix = 'https://jbrowse.org/demos/hprc/hprc-v2.1-mc-grch38.GRCh38'
-const reader = new WalkReader({
-  walks: file(`${prefix}.walks.bed.gz`),
-  nodes: file(`${prefix}.nodes.bed.gz`),
-})
+  }),
+)
 
 const refName = 'GRCh38#0#chr6'
 const { graph, kept, fragments } = await reader.cut(
   refName,
   { start: 160_614_798, end: 160_647_758 },
-  { keep: walkNameFilter(['HG00097', 'HG00133'], panSNHaplotype(refName)) },
+  { keep: walksKept(['HG00097', 'HG00133'], refName) },
 )
 const tables = graph.tables(kept, fragments)
 ```
@@ -68,18 +63,35 @@ const tables = graph.tables(kept, fragments)
 | `context`    | bp of reference kept past each end of the region; default 1000            |
 | `stepBudget` | The most steps a cut keeps; no limit by default                           |
 | `byteBudget` | The most compressed bytes a cut fetches; no limit by default              |
-| `links`      | `false` leaves the link file unread                                       |
-| `sequences`  | Keep each node's bases in `graph.sequences`, from `--sequences` files     |
+| `links`      | `false` lists no links, for a caller that draws no edges                  |
+| `sequences`  | Keep each node's bases in `graph.sequences`, from a `--sequences` file    |
 | `signal`     | An `AbortSignal` that stops the reads                                     |
 
 A cut over a budget throws a `RegionTooLargeError`. Its `fitsBp` holds about how
 wide a window would fit, and JBrowse shows it as a zoom-in notice.
+`WALK_BUDGETS` holds the step and byte budgets the JBrowse plugin and BandageJS
+cut by.
+
+## Naming the window
+
+- `reader.sequenceFor(sample, refName)` gives the walk file's sequence for a
+  contig on a sample: `chr6` on `GRCh38` is `GRCh38#0#chr6`, and a pggb file's
+  `chm13#chr1` is `chr1` on `chm13`
+- `walksKept(haplotypes, refName)` is the `keep` filter for a cut on `refName`:
+  its own walk and those of the haplotypes named
+- `refNameLookup` and `resolveRefName` resolve a contig the same way against any
+  tabix file's sequence names
 
 ## How a cut works
 
+- A chunk holds the reference's path through it once, each way a haplotype
+  leaves that path once, and every other path's piece as the list of ways it
+  takes; gfa-to-tabix's
+  [walks-format.md](https://github.com/GMOD/gfa-to-tabix/blob/main/docs/walks-format.md)
+  describes the rows
 - A cut reads every chunk under the region, and the chunks before it as far as
   the header's `maxnode` reaches, since a node is filed under the chunk holding
-  its start
+  its start, and decodes each chunk once
 - A haplotype that leaves the reference near the region is followed to where it
   rejoins, and the reference is cut out as far as those rejoins reach
 - A walk the read cuts off goes on in the chunk its row names (`pv:`/`nx:`

package/esm/index.d.ts

@@ -1,7 +1,8 @@
-export { BUDGET_NAMES, WalkGraph, byteBudgetError, chunkQueryStart, decodeSteps, joinPieces, keptStepsError, lookbackChunks, parseWalkRow, stepBudgetError, walkCut, walkHeader, walkNameFilter, walkRowName, } from './walkRows.ts';
+export { BUDGET_NAMES, WalkGraph, byteBudgetError, chunkQueryStart, joinPieces, keptStepsError, lookbackChunks, stepBudgetError, walkCut, walkHeader, walkNameFilter, walksKept, } from './walkRows.ts';
 export type { BudgetNames, WalkChunk, WalkFragment, WalkHeader, WalkNode, WalkRow, WalkRun, WalkWindow, } from './walkRows.ts';
-export { WalkReader } from './walkReader.ts';
-export { referenceNodes } from './walkFormat2.ts';
-export type { TabixSource, WalkCutOptions, WalkFileSet, WalkReaderHeader, } from './walkReader.ts';
-export { RegionTooLargeError, bpString, panSNHaplotype, panSNMatchesPrefix, } from './util.ts';
+export { WALK_BUDGETS, WalkFormatError, WalkReader, checkRange, } from './walkReader.ts';
+export { refNameLookup, resolveRefName } from './refNames.ts';
+export { referenceNodes } from './walkChunk.ts';
+export type { TabixSource, WalkCutOptions, WalkReaderHeader, } from './walkReader.ts';
+export { RegionTooLargeError, bpString, panSNContig, panSNHaplotype, panSNMatchesPrefix, panSNSample, } from './util.ts';
 export type { GraphTables } from './util.ts';

package/esm/index.js

@@ -1,4 +1,5 @@
-export { BUDGET_NAMES, WalkGraph, byteBudgetError, chunkQueryStart, decodeSteps, joinPieces, keptStepsError, lookbackChunks, parseWalkRow, stepBudgetError, walkCut, walkHeader, walkNameFilter, walkRowName, } from "./walkRows.js";
-export { WalkReader } from "./walkReader.js";
-export { referenceNodes } from "./walkFormat2.js";
-export { RegionTooLargeError, bpString, panSNHaplotype, panSNMatchesPrefix, } from "./util.js";
+export { BUDGET_NAMES, WalkGraph, byteBudgetError, chunkQueryStart, joinPieces, keptStepsError, lookbackChunks, stepBudgetError, walkCut, walkHeader, walkNameFilter, walksKept, } from "./walkRows.js";
+export { WALK_BUDGETS, WalkFormatError, WalkReader, checkRange, } from "./walkReader.js";
+export { refNameLookup, resolveRefName } from "./refNames.js";
+export { referenceNodes } from "./walkChunk.js";
+export { RegionTooLargeError, bpString, panSNContig, panSNHaplotype, panSNMatchesPrefix, panSNSample, } from "./util.js";

package/esm/refNames.d.ts

@@ -0,0 +1,12 @@
+/**
+ * A file's sequence names under each spelling a caller may ask by: the file's
+ * own (`GRCh38#0#chr6`), and a PanSN name's contig under its sample (`chr6`
+ * on `GRCh38`) and under its haplotype (`chr6` on `GRCh38#0`). A pggb name
+ * with no haplotype field, `chm13#chr1`, is `chr1` on `chm13`.
+ */
+export declare function refNameLookup(names: string[]): Map<string, string>;
+/**
+ * The file's name for `refName` on `assemblyName`, a sample or a haplotype,
+ * else for `refName` as the file spells it; undefined when it holds neither
+ */
+export declare function resolveRefName(lookup: Map<string, string>, assemblyName: string, refName: string): string | undefined;

package/esm/refNames.js

@@ -0,0 +1,35 @@
+import { panSNContig, panSNHaplotype, panSNSample } from "./util.js";
+// A tab can occur in neither half: both come out of BED columns
+function qualifiedKey(assemblyName, refName) {
+    return `${assemblyName}\t${refName}`;
+}
+/**
+ * A file's sequence names under each spelling a caller may ask by: the file's
+ * own (`GRCh38#0#chr6`), and a PanSN name's contig under its sample (`chr6`
+ * on `GRCh38`) and under its haplotype (`chr6` on `GRCh38#0`). A pggb name
+ * with no haplotype field, `chm13#chr1`, is `chr1` on `chm13`.
+ */
+export function refNameLookup(names) {
+    const lookup = new Map();
+    for (const name of names) {
+        lookup.set(name, name);
+        const sample = panSNSample(name);
+        if (sample !== name) {
+            const contig = panSNContig(name);
+            lookup.set(qualifiedKey(sample, contig), name);
+            const haplotype = panSNHaplotype(name);
+            if (haplotype !== undefined) {
+                lookup.set(qualifiedKey(haplotype, contig), name);
+            }
+        }
+    }
+    return lookup;
+}
+/**
+ * The file's name for `refName` on `assemblyName`, a sample or a haplotype,
+ * else for `refName` as the file spells it; undefined when it holds neither
+ */
+export function resolveRefName(lookup, assemblyName, refName) {
+    var _a;
+    return (_a = lookup.get(qualifiedKey(assemblyName, refName))) !== null && _a !== void 0 ? _a : lookup.get(refName);
+}

package/esm/util.d.ts

@@ -34,6 +34,8 @@ export declare class RegionTooLargeError extends Error {
     readonly fitsBp: number;
     constructor(message: string, limit: number, windowBp: number, fitsBp: number);
 }
+export declare function panSNSample(refName: string): string;
+export declare function panSNContig(refName: string): string;
 export declare function panSNHaplotype(refName: string): string | undefined;
 export declare function panSNMatchesPrefix(refName: string, prefix: string | undefined): boolean;
 export declare function bpString(bp: number): string;

package/esm/util.js

@@ -14,6 +14,19 @@ export class RegionTooLargeError extends Error {
     }
 }
 const SEP = '#';
+// `grape#1#chr1` -> `grape`
+export function panSNSample(refName) {
+    return refName.split(SEP)[0];
+}
+// `grape#1#chr1` and `grape#chr1` -> `chr1`
+export function panSNContig(refName) {
+    const parts = refName.split(SEP);
+    return parts.length >= 3
+        ? parts.slice(2).join(SEP)
+        : parts.length === 2
+            ? parts[1]
+            : refName;
+}
 export function panSNHaplotype(refName) {
     const parts = refName.split(SEP);
     return parts.length >= 3 ? `${parts[0]}${SEP}${parts[1]}` : undefined;

package/esm/{walkFormat2.d.ts → walkChunk.d.ts}

@@ -24,7 +24,7 @@ export declare class RefPath {
 }
 export declare class WalkRowError extends Error {
 }
-export interface Format2Chunk {
+export interface Chunk {
     path: RefPath;
     routes: Route[];
     walks: {
@@ -34,6 +34,7 @@ export interface Format2Chunk {
     lengths: Map<number, number>;
 }
 export interface DecodedChunk {
+    sequences: Map<number, string>;
     rows: WalkRow[];
     nodes: Map<number, PlacedNode>;
     ends: {
@@ -43,13 +44,13 @@ export interface DecodedChunk {
         first: number;
         last: number;
     }[];
-    chunk: Format2Chunk;
+    chunk: Chunk;
 }
 /**
  * Decodes one chunk's rows, each split on tabs. `keep` names the walk rows
  * whose steps a cut wants, undefined for every one.
  */
-export declare function decodeChunk(rows: string[][], keep: ((name: string) => boolean) | undefined): DecodedChunk;
+export declare function decodeChunk(rows: string[][], keep: ((name: string) => boolean) | undefined, withSequences?: boolean): DecodedChunk;
 /**
  * The positions of the cut's nodes off R, and the links among the cut's
  * nodes, from the chunks a cut read: `kept` holds the node ids the cut draws.
@@ -57,7 +58,7 @@ export declare function decodeChunk(rows: string[][], keep: ((name: string) => b
  * those visiting it in the chunks read, at its earliest offset, as format 1's
  * node rows had it. Links are R's and the routes', both ends in the cut.
  */
-export declare function placeAndLink(chunks: Format2Chunk[], kept: Set<number>, place: (id: number, node: PlacedNode) => void, link: (a: number, b: number) => void): void;
+export declare function placeAndLink(chunks: Chunk[], kept: Set<number>, place: (id: number, node: PlacedNode) => void, link: (a: number, b: number) => void): void;
 export declare function referenceNodes(rows: string[][]): (PlacedNode & {
     id: number;
 })[];

package/esm/{walkFormat2.js → walkChunk.js}

@@ -1,5 +1,5 @@
-// Format 2 of gfa-to-tabix --walks, one file per reference (that repo's
-// docs/walks-format.md). A chunk lists its `ref` rows, which joined in
+// A chunk of gfa-to-tabix's walk format 2, one file per reference (that
+// repo's docs/walks-format.md). A chunk lists its `ref` rows, which joined in
 // hapOffset order are the chunk's reference path R; a `nodes` row with the
 // lengths of the nodes its routes visit; `route` rows, each a way off R; and a
 // `walk` row per piece of every other path, naming the routes it takes in
@@ -286,16 +286,31 @@ function decodeWalk(path, routes, cols, choices, n) {
     }
     return { ids, rev };
 }
+// The bases an SQ:Z: tag at or after column `from` joins, one node's per
+// length, as `ids` names them
+function sliceBases(cols, from, ids, lengths, out) {
+    const tag = cols.slice(from).find(c => c.startsWith('SQ:Z:'));
+    if (tag === undefined) {
+        return;
+    }
+    let at = 5;
+    for (let k = 0; k < ids.length; k++) {
+        const length = lengths[k];
+        out.set(ids[k], tag.slice(at, at + length));
+        at += length;
+    }
+}
 /**
  * Decodes one chunk's rows, each split on tabs. `keep` names the walk rows
  * whose steps a cut wants, undefined for every one.
  */
-export function decodeChunk(rows, keep) {
+export function decodeChunk(rows, keep, withSequences = false) {
     var _a, _b, _c;
     const path = new RefPath();
     const lengths = new Map();
     const routes = [];
     const out = {
+        sequences: new Map(),
         rows: [],
         nodes: new Map(),
         ends: [],
@@ -309,6 +324,9 @@ export function decodeChunk(rows, keep) {
         const nodeLengths = numbers(cols[10]);
         const hapOffset = +cols[6];
         path.add(handles, nodeLengths);
+        if (withSequences) {
+            sliceBases(cols, 11, handles.map(idOf), nodeLengths, out.sequences);
+        }
         let start = hapOffset;
         for (let k = 0; k < handles.length; k++) {
             const id = idOf(handles[k]);
@@ -339,7 +357,6 @@ export function decodeChunk(rows, keep) {
                 hapOffset,
                 piece: +cols[7],
                 n: handles.length,
-                enc: '',
                 steps: {
                     ids: Int32Array.from(handles, idOf),
                     rev: Uint8Array.from(handles, h => h & 1),
@@ -355,8 +372,12 @@ export function decodeChunk(rows, keep) {
             let id = 0;
             for (let k = 0; k < ids.length; k++) {
                 id += ids[k];
+                ids[k] = id;
                 lengths.set(id, nodeLengths[k]);
             }
+            if (withSequences) {
+                sliceBases(cols, 6, ids, nodeLengths, out.sequences);
+            }
         }
         else if (cols[3] === 'route') {
             const entry = tokens(cols[4], previous, []);
@@ -423,7 +444,6 @@ export function decodeChunk(rows, keep) {
                 hapOffset: +cols[6],
                 piece: +cols[7],
                 n,
-                enc: '',
                 steps: decodeWalk(path, routes, cols, choices, n),
                 ...tags(cols, 12, cols[0]),
             });

package/esm/walkReader.d.ts

@@ -1,5 +1,9 @@
 import { WalkGraph } from './walkRows.ts';
 import type { BudgetNames, WalkHeader } from './walkRows.ts';
+export declare const WALK_BUDGETS: {
+    stepBudget: number;
+    byteBudget: number;
+};
 /**
  * A Tabix-indexed file as the reader uses one: @gmod/tabix's
  * TabixIndexedFile is one. `bytesForRegions` estimates the compressed bytes a
@@ -24,11 +28,10 @@ export interface TabixSource {
         signal?: AbortSignal;
     }): Promise<number>;
 }
-export interface WalkFileSet {
-    walks: TabixSource;
-    nodes?: TabixSource;
-    links?: TabixSource;
+export declare class WalkFormatError extends Error {
+    name: string;
 }
+export declare function checkRange(refName: string, start: number, end: number): void;
 export interface WalkCutOptions {
     signal?: AbortSignal;
     keep?: (name: string) => boolean;
@@ -44,24 +47,33 @@ export type WalkReaderHeader = WalkHeader & {
     lookback: number;
 };
 /**
- * A walk-indexed graph's three files, read a window at a time: one read of
- * each over whole chunks, from the lookback chunks before the window to its
- * end. The indexes first estimate the bytes those reads fetch, and a window
- * past the byte budget reads no row. Only the walks `keep` accepts are
- * decoded. The step budget bounds the steps the cut keeps, and rows holding
- * READ_STEPS_PER_KEPT times as many stop the reads, which go out together.
+ * A `gfa-to-tabix --walks` file, `<prefix>.<sample>.walks.bed.gz`, read a
+ * window at a time: one read over whole chunks, from the lookback chunks
+ * before the window to its end, each chunk decoded once. The index first
+ * estimates the bytes the read fetches, and a window past the byte budget
+ * reads no row. Only the walks `keep` accepts are decoded. The step budget
+ * bounds the steps the cut keeps, and rows holding READ_STEPS_PER_KEPT times
+ * as many stop the read.
  */
 export declare class WalkReader {
     private headerRead;
-    private readonly files;
-    private readonly chunkWithoutHeader;
-    constructor(files: WalkFileSet, chunkWithoutHeader?: number);
+    private lookupRead;
+    private readonly walks;
+    constructor(walks: TabixSource);
     header(opts?: {
         signal?: AbortSignal;
     }): Promise<WalkReaderHeader>;
     referenceSequences(opts?: {
         signal?: AbortSignal;
     }): Promise<string[]>;
+    /**
+     * The walk file's sequence for `refName` on `sample`, or for `refName` as
+     * the file spells it: `chr6` on `GRCh38` is `GRCh38#0#chr6`. Undefined when
+     * the file holds neither.
+     */
+    sequenceFor(sample: string, refName: string, opts?: {
+        signal?: AbortSignal;
+    }): Promise<string | undefined>;
     queryStart(start: number, opts?: {
         signal?: AbortSignal;
     }): Promise<number>;

package/esm/walkReader.js

@@ -1,5 +1,6 @@
-import { decodeChunk, pieceLinks } from "./walkFormat2.js";
-import { WalkGraph, byteBudgetError, chunkQueryStart, joinPieces, keptStepsError, lookbackChunks, parseWalkRow, stepBudgetError, walkCut, walkHeader, walkRowName, } from "./walkRows.js";
+import { refNameLookup, resolveRefName } from "./refNames.js";
+import { decodeChunk, pieceLinks } from "./walkChunk.js";
+import { WalkGraph, byteBudgetError, chunkQueryStart, joinPieces, keptStepsError, lookbackChunks, stepBudgetError, walkCut, walkHeader, } from "./walkRows.js";
 // A window reads whole chunks and keeps the steps on it, so a narrow window
 // reads several times what it keeps: 464 haplotypes across the 1.5 kb ABCA7
 // repeat read 5.0 M steps and keep 1.16 M, and the cut takes 0.4 s from warm
@@ -12,17 +13,22 @@ const FOLLOW_ROUNDS = 3;
 const FOLLOW_CHUNKS = 4;
 // bp of reference a cut keeps past each end of the window
 const WALK_CONTEXT = 1000;
+// The budgets the JBrowse graph plugin and BandageJS cut a browser's window by
+export const WALK_BUDGETS = { stepBudget: 4000000, byteBudget: 8000000 };
+// A walk file gfa-to-tabix 0.12 or earlier wrote, which the reader refuses
+export class WalkFormatError extends Error {
+    constructor() {
+        super(...arguments);
+        this.name = 'WalkFormatError';
+    }
+}
 // @gmod/tabix loops forever on a NaN end and reads nothing for a NaN start
 // (GMOD/tabix-js#157), so every query refuses a range that is not finite first
-function checkRange(refName, start, end) {
+export function checkRange(refName, start, end) {
     if (!Number.isFinite(start) || !Number.isFinite(end)) {
         throw new Error(`${refName}:${start}-${end} is not a finite range to query the graph's index for`);
     }
 }
-function getLines(file, refName, start, end, opts) {
-    checkRange(refName, start, end);
-    return file.getLines(refName, start, end, opts);
-}
 // Settles like `promise` unless `signal` aborts first
 function raceAbort(promise, signal) {
     if (!signal) {
@@ -42,26 +48,29 @@ function raceAbort(promise, signal) {
     });
 }
 /**
- * A walk-indexed graph's three files, read a window at a time: one read of
- * each over whole chunks, from the lookback chunks before the window to its
- * end. The indexes first estimate the bytes those reads fetch, and a window
- * past the byte budget reads no row. Only the walks `keep` accepts are
- * decoded. The step budget bounds the steps the cut keeps, and rows holding
- * READ_STEPS_PER_KEPT times as many stop the reads, which go out together.
+ * A `gfa-to-tabix --walks` file, `<prefix>.<sample>.walks.bed.gz`, read a
+ * window at a time: one read over whole chunks, from the lookback chunks
+ * before the window to its end, each chunk decoded once. The index first
+ * estimates the bytes the read fetches, and a window past the byte budget
+ * reads no row. Only the walks `keep` accepts are decoded. The step budget
+ * bounds the steps the cut keeps, and rows holding READ_STEPS_PER_KEPT times
+ * as many stop the read.
  */
 export class WalkReader {
-    constructor(files, chunkWithoutHeader = 65536) {
-        this.files = files;
-        this.chunkWithoutHeader = chunkWithoutHeader;
+    constructor(walks) {
+        this.walks = walks;
     }
     // The header, read once for every caller: one caller giving up stops only
     // its own wait, and a read that fails is tried again by the next caller
     header(opts = {}) {
         if (!this.headerRead) {
-            const read = this.files.walks.getHeaderLines().then(lines => {
+            const read = this.walks.getHeaderLines().then(lines => {
                 var _a;
                 const header = walkHeader(lines);
-                const chunk = (_a = header.chunk) !== null && _a !== void 0 ? _a : this.chunkWithoutHeader;
+                if (header.format !== 2) {
+                    throw new WalkFormatError('This walk file is format 1, from gfa-to-tabix 0.12 or earlier; rebuild it with gfa-to-tabix 1.0 or later');
+                }
+                const chunk = (_a = header.chunk) !== null && _a !== void 0 ? _a : 65536;
                 return {
                     ...header,
                     chunk,
@@ -79,36 +88,40 @@ export class WalkReader {
     }
     // The reference sequences the walk file holds windows on
     referenceSequences(opts = {}) {
-        return this.files.walks.getReferenceSequenceNames(opts);
+        return this.walks.getReferenceSequenceNames(opts);
+    }
+    /**
+     * The walk file's sequence for `refName` on `sample`, or for `refName` as
+     * the file spells it: `chr6` on `GRCh38` is `GRCh38#0#chr6`. Undefined when
+     * the file holds neither.
+     */
+    async sequenceFor(sample, refName, opts = {}) {
+        if (!this.lookupRead) {
+            const read = this.walks.getReferenceSequenceNames().then(refNameLookup);
+            read.catch(() => {
+                if (this.lookupRead === read) {
+                    this.lookupRead = undefined;
+                }
+            });
+            this.lookupRead = read;
+        }
+        const lookup = await raceAbort(this.lookupRead, opts.signal);
+        return resolveRefName(lookup, sample, refName);
     }
     async queryStart(start, opts = {}) {
         const { chunk, lookback } = await this.header(opts);
         return chunkQueryStart(start, chunk, lookback);
     }
     async cut(refName, region, opts = {}) {
-        const { signal, keep, context = WALK_CONTEXT, stepBudget = Infinity, byteBudget = Infinity, } = opts;
-        const { chunk, lookback, format } = await this.header({ signal });
-        // format 2 holds the whole cut in its walk file
-        const format2 = format === 2;
-        const nodeFile = this.files.nodes;
-        const linkFile = opts.links === false ? undefined : this.files.links;
-        if (!format2 && !nodeFile) {
-            throw new Error('A format 1 walk file needs its node file: open it with `nodes`');
-        }
-        const links = format2 ? opts.links !== false : linkFile !== undefined;
+        var _a;
+        const { signal, keep, context = WALK_CONTEXT, stepBudget = Infinity, byteBudget = Infinity, links = true, } = opts;
+        const { chunk, lookback } = await this.header({ signal });
         const from = chunkQueryStart(region.start, chunk, lookback);
-        const files = format2
-            ? [this.files.walks]
-            : [this.files.walks, nodeFile, ...(linkFile ? [linkFile] : [])];
-        const budgeted = Number.isFinite(byteBudget) &&
-            files.every(file => file.bytesForRegions !== undefined);
-        const bytesFor = async (spans) => {
-            if (!budgeted) {
-                return 0;
-            }
-            const sizes = await Promise.all(files.map(file => file.bytesForRegions(spans.map(span => ({ refName, ...span })), { signal })));
-            return sizes.reduce((sum, bytes) => sum + bytes, 0);
-        };
+        const bytesForRegions = (_a = this.walks.bytesForRegions) === null || _a === void 0 ? void 0 : _a.bind(this.walks);
+        const budgeted = Number.isFinite(byteBudget) && bytesForRegions !== undefined;
+        const bytesFor = async (spans) => budgeted
+            ? bytesForRegions(spans.map(span => ({ refName, ...span })), { signal })
+            : 0;
         const tooLarge = budgeted
             ? await byteBudgetError(async (end) => {
                 checkRange(refName, from, end);
@@ -133,49 +146,39 @@ export class WalkReader {
             context,
             sequences: opts.sequences,
         });
-        const read = (file, lineCallback, start = from, end = region.end) => getLines(file, refName, start, end, {
-            signal: reads.signal,
-            lineCallback,
-        });
-        const addRow = (line) => {
-            if (keep === undefined || keep(walkRowName(line))) {
-                rows.push(parseWalkRow(line));
-            }
-        };
-        const addNode = (line) => {
-            graph.addNode(line);
-        };
-        const addLink = (line) => {
-            graph.addLink(line);
-        };
         const decoded = new Set();
         const ends = [];
-        // Format 2: each chunk read is decoded once, into the rows, nodes and
-        // links format 1 would have filed, and the links between pieces read
-        const readChunks = async (start = from, end = region.end) => {
+        // each chunk read is decoded once, into its rows, nodes and the links
+        // between pieces
+        const readChunks = async (start, end) => {
+            checkRange(refName, start, end);
             const byChunk = new Map();
-            await read(this.files.walks, line => {
-                const cols = line.split('\t');
-                const cs = +cols[1];
-                const held = byChunk.get(cs);
-                if (held) {
-                    held.push(cols);
-                }
-                else {
-                    byChunk.set(cs, [cols]);
-                }
-            }, start, end);
+            await this.walks.getLines(refName, start, end, {
+                signal: reads.signal,
+                lineCallback: line => {
+                    const cols = line.split('\t');
+                    const cs = +cols[1];
+                    const held = byChunk.get(cs);
+                    if (held) {
+                        held.push(cols);
+                    }
+                    else {
+                        byChunk.set(cs, [cols]);
+                    }
+                },
+            });
             for (const [cs, chunkRows] of byChunk) {
                 if (decoded.has(cs)) {
                     continue;
                 }
                 decoded.add(cs);
-                const chunkCut = decodeChunk(chunkRows, keep);
+                const chunkCut = decodeChunk(chunkRows, keep, opts.sequences);
                 rows.push(...chunkCut.rows);
                 for (const [id, node] of chunkCut.nodes) {
                     graph.placeNode(id, node);
                 }
-                graph.addFormat2Chunk(chunkCut.chunk);
+                graph.addSequences(chunkCut.sequences);
+                graph.addChunk(chunkCut.chunk);
                 ends.push(...chunkCut.ends);
             }
             if (links) {
@@ -184,20 +187,12 @@ export class WalkReader {
                 }
             }
         };
-        const checkSteps = () => {
-            const error = stepBudgetError(rows, stepBudget, READ_STEPS_PER_KEPT, region, chunk, keep !== undefined, opts.budgetNames);
-            if (error) {
-                throw error;
-            }
-        };
         try {
-            await (format2
-                ? readChunks().then(checkSteps)
-                : Promise.all([
-                    read(this.files.walks, addRow).then(checkSteps),
-                    read(nodeFile, addNode),
-                    ...(linkFile ? [read(linkFile, addLink)] : []),
-                ]));
+            await readChunks(from, region.end);
+            const tooManyRead = stepBudgetError(rows, stepBudget, READ_STEPS_PER_KEPT, region, chunk, keep !== undefined, opts.budgetNames);
+            if (tooManyRead) {
+                throw tooManyRead;
+            }
             // the chunks read, first to last, which a follow widens to the
             // farthest chunk a cut-off walk goes on in, so the reference between
             // is read too
@@ -224,13 +219,7 @@ export class WalkReader {
                 }
                 first = Math.min(first, ...starts);
                 last = Math.max(last, ...starts);
-                await Promise.all(spans.flatMap(({ start, end }) => format2
-                    ? [readChunks(start, end)]
-                    : [
-                        read(this.files.walks, addRow, start, end),
-                        read(nodeFile, addNode, start, end),
-                        ...(linkFile ? [read(linkFile, addLink, start, end)] : []),
-                    ]));
+                await Promise.all(spans.map(({ start, end }) => readChunks(start, end)));
                 cut = walkCut(joinPieces(rows), graph.nodes, refName);
             }
         }

package/esm/walkRows.d.ts

@@ -1,14 +1,13 @@
 import { RegionTooLargeError } from './util.ts';
 import type { GraphTables } from './util.ts';
-import type { Format2Chunk } from './walkFormat2.ts';
+import type { Chunk } from './walkChunk.ts';
 export interface WalkRow {
     name: string;
     fragStart: number;
     hapOffset: number;
     piece: number;
     n: number;
-    enc: string;
-    steps?: {
+    steps: {
         ids: Int32Array;
         rev: Uint8Array;
     };
@@ -34,8 +33,6 @@ export interface WalkWindow {
     context: number;
     sequences?: boolean;
 }
-export declare function walkRowName(line: string): string;
-export declare function parseWalkRow(line: string): WalkRow;
 export interface WalkHeader {
     format?: number;
     chunk?: number;
@@ -44,11 +41,10 @@ export interface WalkHeader {
     haplotypes: string[];
 }
 /**
- * What a walk file's header states: its chunk size in a
- * `#walks\tchunk:i:65536` line, from gfa-to-tabix 0.4.0 a
- * `#reference\tGRCh38` line per reference sample and a
- * `#haplotype\tHG002#1` line per other haplotype with rows, and from 0.5.0
- * the longest node in bp as `maxnode:i:1024` beside the chunk size
+ * What a walk file's header states: a `#walks` line with the format, the
+ * chunk size and the longest node in bp, `format:i:2\tchunk:i:65536\tmaxnode:i:1024`,
+ * a `#reference\tGRCh38` line naming the reference sample and a
+ * `#haplotype\tHG002#1` line per other haplotype with rows
  */
 export declare function walkHeader(lines: string[]): WalkHeader;
 /**
@@ -62,10 +58,12 @@ export declare function walkHeader(lines: string[]): WalkHeader;
 export declare function lookbackChunks(maxNode: number | undefined, chunk: number): number;
 export declare function chunkQueryStart(start: number, chunk: number, lookback?: number): number;
 export declare function walkNameFilter(wanted: string[] | undefined, referenceHaplotype: string | undefined): ((name: string) => boolean) | undefined;
-export declare function decodeSteps(enc: string, n: number, ids?: Int32Array<ArrayBuffer>, rev?: Uint8Array<ArrayBuffer>, at?: number): {
-    ids: Int32Array<ArrayBuffer>;
-    rev: Uint8Array<ArrayBuffer>;
-};
+/**
+ * The walks a cut on `refName` decodes: its own and those `wanted` names. A
+ * pggb P-line names a reference with no haplotype field (`chm13#chr1`), so the
+ * filter matches the reference by its whole name.
+ */
+export declare function walksKept(wanted: string[] | undefined, refName: string): ((name: string) => boolean) | undefined;
 export interface WalkRun {
     name: string;
     hapOffset: number;
@@ -103,24 +101,20 @@ export declare function walkCut(runs: WalkRun[], nodes: Map<number, WalkNode>, r
     open: WalkChunk[];
 };
 /**
- * The node and link rows a walk cut reads, parsed as they arrive, and the
- * tables of the cut they make with its walks. A node filed under two chunks
- * arrives twice and is read once; columns past a node row's eighth (LN:i:,
- * SQ:Z: and whatever follows) are read only for the bases a window asks for.
+ * The nodes and links of the chunks a cut reads, and the tables of the cut
+ * they make with its walks. A node in two chunks is placed once.
  */
 export declare class WalkGraph {
     readonly nodes: Map<number, WalkNode>;
     readonly sequences: Map<number, string>;
     private links;
-    private readonly format2;
-    private readonly t;
+    private readonly chunks;
     private readonly window;
     constructor(window: WalkWindow);
-    addNode(line: string): void;
     placeNode(id: number, node: Omit<WalkNode, 'onWindow'>): void;
     addLinkEnds(source: number, target: number): void;
-    addFormat2Chunk(chunk: Format2Chunk): void;
-    addLink(line: string): void;
+    addChunk(chunk: Chunk): void;
+    addSequences(sequences: Map<number, string>): void;
     /**
      * The cut as typed arrays, which the worker transfers rather than copies:
      * nodes by reference position, each link once in the order its L line

package/esm/walkRows.js

@@ -1,52 +1,14 @@
-import { RegionTooLargeError, bpString, panSNMatchesPrefix } from "./util.js";
-import { placeAndLink } from "./walkFormat2.js";
-// The name column, read without splitting the steps, so a row the cut does
-// not want costs a few indexOf calls
-export function walkRowName(line) {
-    let at = -1;
-    for (let k = 0; k < 3; k++) {
-        at = line.indexOf('\t', at + 1);
-    }
-    return line.slice(at + 1, line.indexOf('\t', at + 1));
-}
-export function parseWalkRow(line) {
-    const c = line.split('\t');
-    const row = {
-        chunkStart: +c[1],
-        name: c[3],
-        fragStart: +c[4],
-        hapOffset: +c[5],
-        piece: +c[6],
-        n: +c[7],
-        enc: c[8],
-    };
-    for (let k = 9; k < c.length; k++) {
-        const tag = c[k];
-        const side = tag.startsWith('pv:')
-            ? 'prev'
-            : tag.startsWith('nx:')
-                ? 'next'
-                : undefined;
-        if (side) {
-            const at = tag.lastIndexOf(':');
-            row[side] = {
-                refName: tag[3] === 'Z' ? tag.slice(5, at) : c[0],
-                start: +tag.slice(at + 1),
-            };
-        }
-    }
-    return row;
-}
+import { RegionTooLargeError, bpString, panSNHaplotype, panSNMatchesPrefix, } from "./util.js";
+import { placeAndLink } from "./walkChunk.js";
 function integerTag(line, tag) {
     const match = new RegExp(`(?:^|\\t)${tag}:i:(\\d+)`).exec(line);
     return match ? +match[1] : undefined;
 }
 /**
- * What a walk file's header states: its chunk size in a
- * `#walks\tchunk:i:65536` line, from gfa-to-tabix 0.4.0 a
- * `#reference\tGRCh38` line per reference sample and a
- * `#haplotype\tHG002#1` line per other haplotype with rows, and from 0.5.0
- * the longest node in bp as `maxnode:i:1024` beside the chunk size
+ * What a walk file's header states: a `#walks` line with the format, the
+ * chunk size and the longest node in bp, `format:i:2\tchunk:i:65536\tmaxnode:i:1024`,
+ * a `#reference\tGRCh38` line naming the reference sample and a
+ * `#haplotype\tHG002#1` line per other haplotype with rows
  */
 export function walkHeader(lines) {
     var _a, _b, _c;
@@ -91,30 +53,14 @@ export function walkNameFilter(wanted, referenceHaplotype) {
         : (name) => panSNMatchesPrefix(name, referenceHaplotype) ||
             wanted.some(prefix => panSNMatchesPrefix(name, prefix));
 }
-export function decodeSteps(enc, n, ids = new Int32Array(n), rev = new Uint8Array(n), at = 0) {
-    let prev = 0;
-    let i = at;
-    let v = 0;
-    let neg = false;
-    for (let p = 0; p <= enc.length; p++) {
-        const ch = p < enc.length ? enc.charCodeAt(p) : 44;
-        if (ch === 44) {
-            const d = neg ? -v : v;
-            const r = d & 1;
-            rev[i] = r;
-            prev += (d - r) / 2;
-            ids[i++] = prev;
-            v = 0;
-            neg = false;
-        }
-        else if (ch === 45) {
-            neg = true;
-        }
-        else {
-            v = v * 10 + (ch - 48);
-        }
-    }
-    return { ids, rev };
+/**
+ * The walks a cut on `refName` decodes: its own and those `wanted` names. A
+ * pggb P-line names a reference with no haplotype field (`chm13#chr1`), so the
+ * filter matches the reference by its whole name.
+ */
+export function walksKept(wanted, refName) {
+    var _a;
+    return walkNameFilter(wanted, (_a = panSNHaplotype(refName)) !== null && _a !== void 0 ? _a : refName);
 }
 export function joinPieces(rows) {
     const byPath = new Map();
@@ -148,13 +94,8 @@ function decodeRun(pieces) {
     const rev = new Uint8Array(n);
     let at = 0;
     for (const p of pieces) {
-        if (p.steps) {
-            ids.set(p.steps.ids, at);
-            rev.set(p.steps.rev, at);
-        }
-        else {
-            decodeSteps(p.enc, p.n, ids, rev, at);
-        }
+        ids.set(p.steps.ids, at);
+        rev.set(p.steps.rev, at);
         at += p.n;
     }
     const first = pieces[0];
@@ -308,50 +249,19 @@ export function walkCut(runs, nodes, refName) {
     }
     return { kept, fragments, open: [...open.values()] };
 }
-// The positions of a line's first `n` tabs, -1 past the last
-function tabs(line, n, out) {
-    let at = -1;
-    for (let k = 0; k < n; k++) {
-        at = at === -1 && k > 0 ? -1 : line.indexOf('\t', at + 1);
-        out[k] = at;
-    }
-    return out;
-}
 /**
- * The node and link rows a walk cut reads, parsed as they arrive, and the
- * tables of the cut they make with its walks. A node filed under two chunks
- * arrives twice and is read once; columns past a node row's eighth (LN:i:,
- * SQ:Z: and whatever follows) are read only for the bases a window asks for.
+ * The nodes and links of the chunks a cut reads, and the tables of the cut
+ * they make with its walks. A node in two chunks is placed once.
  */
 export class WalkGraph {
     constructor(window) {
         this.nodes = new Map();
         this.sequences = new Map();
         this.links = [];
-        // format 2's chunks, whose nodes off R and links tables() fills in
-        this.format2 = [];
-        this.t = [];
+        // the chunks read, whose nodes off R and links tables() fills in
+        this.chunks = [];
         this.window = window;
     }
-    addNode(line) {
-        const t = tabs(line, 8, this.t);
-        const id = +line.slice(t[2] + 1, t[3]);
-        if (!this.nodes.has(id)) {
-            if (this.window.sequences) {
-                const at = line.indexOf('\tSQ:Z:');
-                if (at >= 0) {
-                    const end = line.indexOf('\t', at + 1);
-                    this.sequences.set(id, line.slice(at + 6, end < 0 ? undefined : end));
-                }
-            }
-            this.placeNode(id, {
-                rank: +line.slice(t[3] + 1, t[4]),
-                refName: line.slice(t[4] + 1, t[5]),
-                start: +line.slice(t[5] + 1, t[6]),
-                end: +line.slice(t[6] + 1, t[7] === -1 ? undefined : t[7]),
-            });
-        }
-    }
     // A node with its position, unless the cut already holds it
     placeNode(id, node) {
         if (this.nodes.has(id)) {
@@ -370,13 +280,16 @@ export class WalkGraph {
     addLinkEnds(source, target) {
         this.links.push(source, target);
     }
-    addFormat2Chunk(chunk) {
-        this.format2.push(chunk);
+    addChunk(chunk) {
+        this.chunks.push(chunk);
     }
-    // An endpoint is held as id * 2 + 1 when reversed
-    addLink(line) {
-        const t = tabs(line, 5, this.t);
-        this.links.push(endpoint(line, t[2] + 1, t[3]), endpoint(line, t[3] + 1, t[4] === -1 ? line.length : t[4]));
+    // Bases of nodes a chunk's rows give, for a window that asks for them
+    addSequences(sequences) {
+        if (this.window.sequences) {
+            for (const [id, bases] of sequences) {
+                this.sequences.set(id, bases);
+            }
+        }
     }
     /**
      * The cut as typed arrays, which the worker transfers rather than copies:
@@ -386,8 +299,8 @@ export class WalkGraph {
      * for the same rows.
      */
     tables(kept, fragments) {
-        if (this.format2.length > 0) {
-            placeAndLink(this.format2, kept, (id, node) => {
+        if (this.chunks.length > 0) {
+            placeAndLink(this.chunks, kept, (id, node) => {
                 const held = this.nodes.get(id);
                 if (held) {
                     this.nodes.set(id, { ...held, ...node });
@@ -498,9 +411,6 @@ export class WalkGraph {
             (a.name < b.name ? -1 : a.name > b.name ? 1 : a.hapStart - b.hapStart));
     }
 }
-function endpoint(line, from, to) {
-    return (+line.slice(from, to - 1) * 2 + (line.charCodeAt(to - 1) === 45 ? 1 : 0));
-}
 export const BUDGET_NAMES = {
     steps: 'the step budget',
     bytes: 'a byte budget of',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jbrowse/graph-walks",
-  "version": "0.1.0",
+  "version": "1.1.0",
   "description": "Read gfa-to-tabix walk files by range requests and cut a window of a pangenome graph: the reference, every haplotype's walk through it, and the nodes and links they visit",
   "license": "MIT",
   "author": {
@@ -20,39 +20,25 @@
     "haplotype"
   ],
   "type": "module",
-  "packageManager": "pnpm@11.20.0",
   "exports": {
-    ".": "./src/index.ts"
+    ".": {
+      "types": "./esm/index.d.ts",
+      "default": "./esm/index.js"
+    }
   },
   "publishConfig": {
-    "access": "public",
-    "exports": {
-      ".": {
-        "types": "./esm/index.d.ts",
-        "default": "./esm/index.js"
-      }
-    }
+    "access": "public"
   },
   "files": [
     "esm"
   ],
-  "scripts": {
-    "build": "rm -rf esm && tsc -p tsconfig.build.json",
-    "typecheck": "tsc --noEmit",
-    "lint": "eslint --report-unused-disable-directives --max-warnings 0",
-    "format": "prettier --write .",
-    "format:check": "prettier --check .",
-    "test": "vitest run",
-    "prepack": "pnpm build",
-    "preversion": "pnpm lint && pnpm format:check && pnpm typecheck && pnpm test && pnpm build",
-    "postversion": "git push --follow-tags"
-  },
   "engines": {
     "node": ">=20"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@gmod/tabix": "^3.10.1",
+    "@types/node": "^26.6.5",
     "eslint": "^10.12.0",
     "eslint-plugin-import-x": "^4.17.1",
     "generic-filehandle2": "^2.5.0",
@@ -60,5 +46,15 @@
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.71.1",
     "vitest": "^5.0.3"
+  },
+  "scripts": {
+    "build": "rm -rf esm && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint --report-unused-disable-directives --max-warnings 0",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "test": "vitest run",
+    "preversion": "pnpm lint && pnpm format:check && pnpm typecheck && pnpm test && pnpm build",
+    "postversion": "git push --follow-tags"
   }
-}
+}