@jbrowse/graph-walks 1.0.0 → 1.1.0

package/README.md

@@ -27,11 +27,7 @@ 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 url = 'https://example.org/hprc-v2.1-mc-grch38.GRCh38.walks.bed.gz'
@@ -46,7 +42,7 @@ 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)
 ```
@@ -73,6 +69,18 @@ const tables = graph.tables(kept, fragments)
 
 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
 

package/esm/index.d.ts

@@ -1,7 +1,8 @@
-export { BUDGET_NAMES, WalkGraph, byteBudgetError, chunkQueryStart, joinPieces, keptStepsError, lookbackChunks, stepBudgetError, walkCut, walkHeader, walkNameFilter, } 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 { WalkFormatError, WalkReader } from './walkReader.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, panSNHaplotype, panSNMatchesPrefix, } from './util.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, joinPieces, keptStepsError, lookbackChunks, stepBudgetError, walkCut, walkHeader, walkNameFilter, } from "./walkRows.js";
-export { WalkFormatError, WalkReader } from "./walkReader.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, panSNHaplotype, panSNMatchesPrefix, } from "./util.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/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
@@ -27,6 +31,7 @@ export interface 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;
@@ -52,6 +57,7 @@ export type WalkReaderHeader = WalkHeader & {
  */
 export declare class WalkReader {
     private headerRead;
+    private lookupRead;
     private readonly walks;
     constructor(walks: TabixSource);
     header(opts?: {
@@ -60,6 +66,14 @@ export declare class WalkReader {
     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,3 +1,4 @@
+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
@@ -12,6 +13,8 @@ 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() {
@@ -21,7 +24,7 @@ export class WalkFormatError extends Error {
 }
 // @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`);
     }
@@ -87,6 +90,24 @@ export class WalkReader {
     referenceSequences(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);

package/esm/walkRows.d.ts

@@ -58,6 +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;
+/**
+ * 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;

package/esm/walkRows.js

@@ -1,4 +1,4 @@
-import { RegionTooLargeError, bpString, panSNMatchesPrefix } from "./util.js";
+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);
@@ -53,6 +53,15 @@ export function walkNameFilter(wanted, referenceHaplotype) {
         : (name) => panSNMatchesPrefix(name, referenceHaplotype) ||
             wanted.some(prefix => panSNMatchesPrefix(name, prefix));
 }
+/**
+ * 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();
     for (const row of rows) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jbrowse/graph-walks",
-  "version": "1.0.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": {