@jbrowse/graph-walks 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Colin Diesh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,94 @@
-# Temporary Holding Version
+# @jbrowse/graph-walks
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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, `<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 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
+
+The JBrowse graph plugin, BandageJS and the sequenceTubeMap fork read walk files
+through it.
+
+## Install
+
+```bash
+npm install @jbrowse/graph-walks @gmod/tabix
+```
+
+## Usage
+
+```ts
+import { TabixIndexedFile } from '@gmod/tabix'
+import {
+  WalkReader,
+  panSNHaplotype,
+  walkNameFilter,
+} from '@jbrowse/graph-walks'
+import { RemoteFile } from 'generic-filehandle2'
+
+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 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)) },
+)
+const tables = graph.tables(kept, fragments)
+```
+
+- `tables` lists the nodes with their lengths and reference positions, the links
+  between them, and each walk's steps. `graphTablesGFA` in
+  [@jbrowse/bandage-core](https://github.com/GMOD/bandage-core) writes it as GFA
+- `reader.header()` lists the reference sample and every haplotype with rows,
+  read from the walk file's first block
+- `reader.referenceSequences()` lists the sequences a region can be on, in full
+  PanSN: `GRCh38#0#chr6`
+
+## Cut options
+
+| Option       | Effect                                                                    |
+| ------------ | ------------------------------------------------------------------------- |
+| `keep`       | Which walks to decode, by `sample#haplotype#contig`; every one by default |
+| `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` 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.
+
+## 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, 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:`
+  tags); the cut reads on to that chunk, in up to three rounds
+
+## License
+
+MIT

package/esm/index.d.ts

@@ -0,0 +1,7 @@
+export { BUDGET_NAMES, WalkGraph, byteBudgetError, chunkQueryStart, joinPieces, keptStepsError, lookbackChunks, stepBudgetError, walkCut, walkHeader, walkNameFilter, } from './walkRows.ts';
+export type { BudgetNames, WalkChunk, WalkFragment, WalkHeader, WalkNode, WalkRow, WalkRun, WalkWindow, } from './walkRows.ts';
+export { WalkFormatError, WalkReader } from './walkReader.ts';
+export { referenceNodes } from './walkChunk.ts';
+export type { TabixSource, WalkCutOptions, WalkReaderHeader, } from './walkReader.ts';
+export { RegionTooLargeError, bpString, panSNHaplotype, panSNMatchesPrefix, } from './util.ts';
+export type { GraphTables } from './util.ts';

package/esm/index.js

@@ -0,0 +1,4 @@
+export { BUDGET_NAMES, WalkGraph, byteBudgetError, chunkQueryStart, joinPieces, keptStepsError, lookbackChunks, stepBudgetError, walkCut, walkHeader, walkNameFilter, } from "./walkRows.js";
+export { WalkFormatError, WalkReader } from "./walkReader.js";
+export { referenceNodes } from "./walkChunk.js";
+export { RegionTooLargeError, bpString, panSNHaplotype, panSNMatchesPrefix, } from "./util.js";

package/esm/util.d.ts

@@ -0,0 +1,39 @@
+export interface GraphTables {
+    nodes: {
+        names: string[];
+        lengths: Int32Array;
+        refs: Int32Array;
+        starts: Float64Array;
+        ranks: Int32Array;
+        refNames: string[];
+    };
+    links: {
+        from: Int32Array;
+        to: Int32Array;
+        strands: Uint8Array;
+    };
+    walks: {
+        names: string[];
+        starts: Float64Array;
+        ends: Float64Array;
+        offsets: Int32Array;
+        steps: Int32Array;
+        reversed: Uint8Array;
+    };
+}
+/**
+ * A window too large to cut. `regionTooLarge` and the name are what JBrowse
+ * and @jbrowse/bandage-core read a zoom-in notice by; `fitsBp` is about how
+ * wide a window would fit.
+ */
+export declare class RegionTooLargeError extends Error {
+    readonly regionTooLarge = true;
+    name: string;
+    readonly limit: number;
+    readonly windowBp: number;
+    readonly fitsBp: number;
+    constructor(message: string, limit: number, windowBp: number, fitsBp: number);
+}
+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

@@ -0,0 +1,34 @@
+/**
+ * A window too large to cut. `regionTooLarge` and the name are what JBrowse
+ * and @jbrowse/bandage-core read a zoom-in notice by; `fitsBp` is about how
+ * wide a window would fit.
+ */
+export class RegionTooLargeError extends Error {
+    constructor(message, limit, windowBp, fitsBp) {
+        super(message);
+        this.regionTooLarge = true;
+        this.name = 'NodeLimitError';
+        this.limit = limit;
+        this.windowBp = windowBp;
+        this.fitsBp = fitsBp;
+    }
+}
+const SEP = '#';
+export function panSNHaplotype(refName) {
+    const parts = refName.split(SEP);
+    return parts.length >= 3 ? `${parts[0]}${SEP}${parts[1]}` : undefined;
+}
+export function panSNMatchesPrefix(refName, prefix) {
+    return (prefix !== undefined &&
+        (refName === prefix || refName.startsWith(prefix + SEP)));
+}
+const precise = (n) => Number.parseFloat(n.toPrecision(3));
+// `1.5Kbp`, `12Mbp`, `850bp`, as JBrowse writes a span
+export function bpString(bp) {
+    const mb = precise(bp / 1000000);
+    return mb >= 1
+        ? `${mb.toLocaleString('en-US')}Mbp`
+        : bp >= 1000
+            ? `${precise(bp / 1000).toLocaleString('en-US')}Kbp`
+            : `${Math.floor(bp)}bp`;
+}

package/esm/walkChunk.d.ts

@@ -0,0 +1,65 @@
+import type { WalkRow } from './walkRows.ts';
+export interface Route {
+    entry: number;
+    interior: number[];
+    exit: number;
+}
+export interface PlacedNode {
+    refName: string;
+    start: number;
+    end: number;
+    rank: number;
+}
+export declare function canonicalLink(a: number, b: number): [number, number];
+export declare class RefPath {
+    readonly handles: number[];
+    readonly before: number[];
+    readonly occurrences: Map<number, number[]>;
+    add(handles: number[], lengths: number[]): void;
+    bp(i: number): number;
+    first(handle: number): number | undefined;
+    nearest(handle: number, i: number): number | undefined;
+    reach(i: number, h: number, target: number): number | undefined;
+    handleAt(i: number, forward: boolean): number;
+}
+export declare class WalkRowError extends Error {
+}
+export interface Chunk {
+    path: RefPath;
+    routes: Route[];
+    walks: {
+        cols: string[];
+        choices: number[];
+    }[];
+    lengths: Map<number, number>;
+}
+export interface DecodedChunk {
+    sequences: Map<number, string>;
+    rows: WalkRow[];
+    nodes: Map<number, PlacedNode>;
+    ends: {
+        name: string;
+        fragStart: number;
+        piece: number;
+        first: number;
+        last: number;
+    }[];
+    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, 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.
+ * A node off R takes its position from the path whose name sorts first among
+ * 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: 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;
+})[];
+export declare function pieceLinks(ends: DecodedChunk['ends']): [number, number][];