@jbrowse/launch-args 5.0.0-beta.17 → 5.0.0-beta.19

package/esm/comparative.d.ts

@@ -0,0 +1,62 @@
+import type { Adapter } from './fileAdapter.ts';
+import type { Assembly, Track } from './fileInput.ts';
+import type { Entry } from './parseArgv.ts';
+/** The comparison flags, each naming the adapter that reads its file. */
+export declare const syntenyFlagAdapters: {
+    readonly paf: 'PAFAdapter';
+    readonly blasttab: 'BlastTabularAdapter';
+    readonly chain: 'ChainAdapter';
+    readonly delta: 'DeltaAdapter';
+};
+export type SyntenyFlag = keyof typeof syntenyFlagAdapters;
+export declare const syntenyFlags: SyntenyFlag[];
+export declare function isSyntenyFlag(key: string): key is SyntenyFlag;
+/**
+ * What an entry is to a comparative view: a genome (`--genome`, `--fasta`,
+ * `--chromSizes` or a bare genome file), a comparison (a comparison flag or a
+ * bare file the format table reads as a SyntenyTrack), or neither. A bare
+ * file's role comes from its name alone.
+ */
+export declare function comparativeRole([key, [file]]: Entry): "genome" | "synteny" | undefined;
+/**
+ * Whether a command line describes a comparative view: a second genome, or a
+ * comparison file. A lone genome is a linear view.
+ */
+export declare function hasComparativeArgs(entries: Entry[]): boolean;
+/**
+ * The SyntenyTrack for a comparison file between two stacked genomes, upper
+ * first. The adapter's file format decides which is the query.
+ */
+export declare function syntenyTrack(adapter: Adapter, file: string, upperAssembly: string, lowerAssembly: string, name?: string): Track;
+/** One row of a comparative view, as a session spec's `views` lists it. */
+export interface ComparativeRow {
+    assembly: string;
+    loc?: string;
+}
+export interface ComparativeData {
+    /** each genome file once, in the order the command line first names it */
+    assemblies: Assembly[];
+    /**
+     * each `--genome` once, whose assembly and comparisons come from its hosted
+     * config: see `hostedComparative`
+     */
+    hosted: string[];
+    /** in stacking order: the first is the top row and a dotplot's x axis */
+    rows: ComparativeRow[];
+    syntenyTracks: Track[];
+}
+/**
+ * The genomes and comparisons of a comparative view, in command-line order.
+ *
+ * - Each genome opens a row, at its `loc:` or whole, with its `aliases:` and
+ *   `cytobands:`, named after its file, and two files of one name throw.
+ * - One file named twice is a self-comparison, two rows of one assembly that
+ *   take its `aliases:` and `cytobands:` from the first row.
+ * - A `--genome` opens a row of a hosted genome, at its `loc:` or whole, and
+ *   throws on a genome file of the same name.
+ * - A comparison file binds to the gap between the genome before it and the
+ *   next one; a trailing one, written after both, clamps to the last gap.
+ * - A comparison takes `name:`; any other modifier, on it or on a genome,
+ *   throws.
+ */
+export declare function buildComparative(entries: Entry[]): ComparativeData;

package/esm/comparative.js

@@ -0,0 +1,187 @@
+import path from 'node:path';
+import { fileNameOf } from '@jbrowse/add-track-core';
+import { adapterTypeByName, syntenyAdapterTypes } from './fileAdapter.js';
+import { fileAdapter, genomeAssembly, isGenomeFlag, isSequenceAdapter, } from './fileInput.js';
+import { FILE_FLAG, isUrl, modifierValue, splitModifier } from './parseArgv.js';
+/** The comparison flags, each naming the adapter that reads its file. */
+export const syntenyFlagAdapters = {
+    paf: 'PAFAdapter',
+    blasttab: 'BlastTabularAdapter',
+    chain: 'ChainAdapter',
+    delta: 'DeltaAdapter',
+};
+export const syntenyFlags = Object.keys(syntenyFlagAdapters);
+/**
+ * Whether a comparison file's query is the upper of the two genomes it sits
+ * between, the one written first, keyed by the adapter that reads it.
+ *
+ * - PAF, PIF, MashMap and BLAST list the query first, as minimap2 and blast
+ *   align a query against a target, so the upper genome is the query.
+ * - A chain or delta file maps target to query (a UCSC
+ *   `targetToQuery.over.chain` maps FROM the target), so the upper genome is
+ *   the target. Getting it backwards mis-maps every coordinate and most
+ *   alignments drop out.
+ */
+const upperIsQuery = {
+    PAFAdapter: true,
+    PairwiseIndexedPAFAdapter: true,
+    MashMapAdapter: true,
+    BlastTabularAdapter: true,
+    ChainAdapter: false,
+    DeltaAdapter: false,
+};
+export function isSyntenyFlag(key) {
+    return Object.hasOwn(syntenyFlagAdapters, key);
+}
+/**
+ * What an entry is to a comparative view: a genome (`--genome`, `--fasta`,
+ * `--chromSizes` or a bare genome file), a comparison (a comparison flag or a
+ * bare file the format table reads as a SyntenyTrack), or neither. A bare
+ * file's role comes from its name alone.
+ */
+export function comparativeRole([key, [file]]) {
+    if (key === 'genome' || isGenomeFlag(key)) {
+        return 'genome';
+    }
+    else if (isSyntenyFlag(key)) {
+        return 'synteny';
+    }
+    const type = key === FILE_FLAG && file ? adapterTypeByName(file) : undefined;
+    return !type
+        ? undefined
+        : isSequenceAdapter({ type })
+            ? 'genome'
+            : syntenyAdapterTypes.has(type)
+                ? 'synteny'
+                : undefined;
+}
+/**
+ * Whether a command line describes a comparative view: a second genome, or a
+ * comparison file. A lone genome is a linear view.
+ */
+export function hasComparativeArgs(entries) {
+    const roles = entries.map(comparativeRole);
+    return (roles.includes('synteny') || roles.filter(r => r === 'genome').length > 1);
+}
+/**
+ * The SyntenyTrack for a comparison file between two stacked genomes, upper
+ * first. The adapter's file format decides which is the query.
+ */
+export function syntenyTrack(adapter, file, upperAssembly, lowerAssembly, name = fileNameOf(file)) {
+    const queryFirst = upperIsQuery[adapter.type];
+    if (queryFirst === undefined) {
+        throw new Error(`${file} is a ${adapter.type} file, which the command line cannot place between two genomes; add it as a track in the app`);
+    }
+    const queryAssembly = queryFirst ? upperAssembly : lowerAssembly;
+    const targetAssembly = queryFirst ? lowerAssembly : upperAssembly;
+    return {
+        type: 'SyntenyTrack',
+        trackId: fileNameOf(file),
+        name,
+        // [query, target], as comparative-adapters reads it
+        assemblyNames: [queryAssembly, targetAssembly],
+        adapter: { ...adapter, queryAssembly, targetAssembly },
+    };
+}
+const ASSEMBLY_MODIFIERS = ['aliases', 'cytobands'];
+// local paths compare resolved, so `./a.fa` and `a.fa` are one file
+function sameFile(a, b) {
+    return (a === b || (!isUrl(a) && !isUrl(b) && path.resolve(a) === path.resolve(b)));
+}
+// whether a repeat row sets `key:` to a value its first row did not
+function changes(firstMods, mods, key) {
+    const value = modifierValue(mods, key);
+    const was = modifierValue(firstMods, key);
+    return value !== undefined && (was === undefined || !sameFile(was, value));
+}
+/**
+ * The genomes and comparisons of a comparative view, in command-line order.
+ *
+ * - Each genome opens a row, at its `loc:` or whole, with its `aliases:` and
+ *   `cytobands:`, named after its file, and two files of one name throw.
+ * - One file named twice is a self-comparison, two rows of one assembly that
+ *   take its `aliases:` and `cytobands:` from the first row.
+ * - A `--genome` opens a row of a hosted genome, at its `loc:` or whole, and
+ *   throws on a genome file of the same name.
+ * - A comparison file binds to the gap between the genome before it and the
+ *   next one; a trailing one, written after both, clamps to the last gap.
+ * - A comparison takes `name:`; any other modifier, on it or on a genome,
+ *   throws.
+ */
+export function buildComparative(entries) {
+    const assemblies = [];
+    const genomes = new Map();
+    const hosted = new Set();
+    const rows = [];
+    const comparisons = [];
+    const pushRow = (assembly, mods) => {
+        const loc = modifierValue(mods, 'loc');
+        rows.push(loc ? { assembly, loc } : { assembly });
+    };
+    for (const entry of entries) {
+        const [key, vals] = entry;
+        const [file = '', ...mods] = vals;
+        const role = comparativeRole(entry);
+        const label = key === FILE_FLAG ? file : `--${key} ${file}`;
+        if (key === 'genome') {
+            if (!file) {
+                throw new Error('--genome requires a genome name, such as hg38');
+            }
+            const extra = mods.filter(mod => splitModifier(mod)?.[0] !== 'loc');
+            if (extra.length) {
+                throw new Error(`${label} takes loc:, not ${extra.join(' ')}; its hosted config supplies the rest`);
+            }
+            const sameName = genomes.get(file);
+            if (sameName) {
+                throw new Error(`${sameName.file} and --genome ${file} are both named ${file}; rename or link the file`);
+            }
+            hosted.add(file);
+            pushRow(file, mods);
+        }
+        else if (role === 'genome') {
+            const { assembly, unused } = genomeAssembly(key, vals, assemblies.length === 0 ? 'refseq' : `${fileNameOf(file)}-refseq`);
+            const extra = unused.filter(mod => splitModifier(mod)?.[0] !== 'loc');
+            if (extra.length) {
+                throw new Error(`${label} takes loc:, aliases: and cytobands:, not ${extra.join(' ')}`);
+            }
+            const first = genomes.get(assembly.name);
+            if (hosted.has(assembly.name)) {
+                throw new Error(`--genome ${assembly.name} and ${file} are both named ${assembly.name}; rename or link the file`);
+            }
+            else if (!first) {
+                genomes.set(assembly.name, { file, mods });
+                assemblies.push(assembly);
+            }
+            else if (!sameFile(first.file, file)) {
+                throw new Error(`${first.file} and ${file} are both named ${assembly.name}, and a genome takes its file's name; rename or link one of them`);
+            }
+            else if (ASSEMBLY_MODIFIERS.some(key => changes(first.mods, mods, key))) {
+                throw new Error(`${label} repeats ${assembly.name}, which takes its aliases: and cytobands: on its first row; a repeat row takes loc:, or restates them unchanged`);
+            }
+            pushRow(assembly.name, mods);
+        }
+        else if (role === 'synteny') {
+            if (!file) {
+                throw new Error(`--${key} requires a file argument`);
+            }
+            const extra = mods.filter(mod => splitModifier(mod)?.[0] !== 'name');
+            if (extra.length) {
+                throw new Error(`${label} takes name:, not ${extra.join(' ')}`);
+            }
+            comparisons.push({ entry, before: rows.length });
+        }
+    }
+    const numLevels = rows.length - 1;
+    const syntenyTracks = comparisons.map(({ entry, before }) => {
+        const [key, [file = '', ...mods]] = entry;
+        if (numLevels < 1) {
+            throw new Error(`${file} compares two genomes, and this command line names one; add another FASTA, 2bit, .chrom.sizes or --genome`);
+        }
+        const level = Math.min(Math.max(before - 1, 0), numLevels - 1);
+        const adapter = fileAdapter(file, {
+            adapterType: isSyntenyFlag(key) ? syntenyFlagAdapters[key] : undefined,
+        });
+        return syntenyTrack(adapter, file, rows[level].assembly, rows[level + 1].assembly, modifierValue(mods, 'name'));
+    });
+    return { assemblies, hosted: [...hosted], rows, syntenyTracks };
+}

package/esm/displaySettings.d.ts

@@ -0,0 +1,160 @@
+import { mergeSettings } from './slotPath.ts';
+/**
+ * The family of display a track opens as, which says which modifiers write
+ * keys that display declares. `other` takes the all-tracks modifiers and slot
+ * writes alone.
+ */
+export type Category = 'alignments' | 'wiggle' | 'feature' | 'variant' | 'hic' | 'other';
+export { mergeSettings };
+export declare const ALL_CATEGORIES: readonly ["alignments", "wiggle", "feature", "variant", "hic", "other"];
+export declare const categorizedDisplayTypes: string[];
+export declare function displayCategory(displayType: string | undefined): Category;
+export declare const ALIGNMENTS_COLOR_FIELDS: readonly ['strand', 'firstOfPairStrand', 'mapq', 'insertSize', 'pairOrientation', 'insertSizeAndOrientation', 'mateRefName', 'mateAssembly'];
+export declare const FACET_ONLY_FIELDS: readonly ['pairing', 'split', 'spliced', 'svSignal'];
+export declare const COLOR_SCHEMES: readonly ['viridis', 'magma', 'inferno', 'cividis', 'juicebox', 'fall', 'reds', 'blues', 'redblue', 'purpleorange', 'redgreyblue', 'redyellowblue'];
+/** The alignments compactness presets' read heights. */
+export declare const ALIGNMENTS_COMPACTNESS: {
+    readonly normal: 7;
+    readonly compact: 3;
+    readonly 'super-compact': 1;
+};
+export declare const HEIGHT_MODES: readonly ['fixed', 'grow', 'fit'];
+export declare const READ_CATEGORY_KEYS: readonly ['spliced', 'svSignal', 'alone', 'split'];
+type Scalar = string | number | boolean;
+/**
+ * One entry of a display's `filter`, core's `FieldPredicate` (ADR-238): the
+ * tests a record's `field` must pass. On an alignments display (ADR-240) the
+ * bare `{ field }` clears the field, defaults included.
+ */
+export interface FilterEntry {
+    field: string;
+    equal?: Scalar;
+    lt?: number;
+    lte?: number;
+    gt?: number;
+    gte?: number;
+    oneOf?: Scalar[];
+    valid?: boolean;
+}
+/**
+ * A `filter` list as a JSON bag or a `filter=` write gives it, each entry
+ * checked as the config schema checks one and a string read as its
+ * shorthand. Throws on what the schema would refuse, v4's object form
+ * included.
+ */
+export declare function filterEntriesOf(list: unknown): FilterEntry[];
+export interface ColorScaleObject {
+    type?: string;
+    domain?: unknown[];
+    range?: string[];
+    names?: string[];
+    scheme?: string;
+    reverse?: boolean;
+    unknown?: string;
+    invalid?: string;
+}
+/** A color channel as written; a bare string is the field. */
+export interface ColorObject {
+    value?: string;
+    field?: string;
+    scale?: ColorScaleObject;
+    legend?: {
+        title?: string;
+        descending?: boolean;
+    };
+}
+export type ColorChannel = string | ColorObject;
+/**
+ * The settings the named modifiers write. Every other setting is a
+ * `path=value` slot write, which the display validates itself.
+ */
+export interface DisplaySnapshot {
+    height?: number;
+    forceLoad?: boolean;
+    mark?: {
+        height?: number;
+    };
+    displayMode?: 'normal' | 'compact' | 'superCompact';
+    heightMode?: (typeof HEIGHT_MODES)[number];
+    growMaxHeight?: number;
+    sort?: string | {
+        field: string;
+        pos: number;
+        refName: string;
+        within?: number;
+    };
+    pileup?: {
+        mark?: {
+            height?: number;
+        };
+        bases?: {
+            show?: boolean;
+            encoding?: {
+                color?: string;
+            };
+            unmodified?: {
+                show?: boolean;
+            };
+        };
+    };
+    readConnections?: {
+        show?: boolean;
+        mark?: 'link' | 'rule';
+        placement?: 'up' | 'down';
+    };
+    sashimi?: {
+        show?: boolean;
+        placement?: 'up' | 'down' | 'auto';
+    };
+    filter?: FilterEntry[];
+    encoding?: {
+        color?: ColorChannel;
+    };
+    legend?: {
+        show?: boolean;
+    };
+    variantLayout?: 'genomic' | 'columns';
+}
+/**
+ * A track's modifiers read into display settings. `sort` is the center-line
+ * sort's field, which needs the view's center to become a setting, and
+ * `displayType` the display `display:` picks.
+ */
+export interface DisplaySettings {
+    snap: DisplaySnapshot;
+    sort?: {
+        field: string;
+    };
+    displayType?: string;
+}
+/** The display a `display:` modifier asks for; the last one given wins. */
+export declare function requestedDisplayType(modifiers: string[]): string | undefined;
+/** The named track modifiers; any other setting is a `path=value` write. */
+export declare const trackModifierNames: string[];
+/**
+ * A track's modifiers read into display settings for `displayType`, the
+ * display the track opens as. A named modifier writes only slots that display
+ * declares. Without a display type, a modifier whose write depends on it
+ * throws, and every other one writes its setting for the display to accept or
+ * refuse. A member write is `memberWrites`'s, and `warn` hears of a modifier
+ * that does nothing on the display.
+ */
+export declare function buildDisplaySnapshot(displayType: string | undefined, opts: string[], warn?: (message: string) => void): DisplaySettings;
+/**
+ * Throws for a modifier no kind of track takes: an unknown name, a malformed
+ * slot write, or a value each display it applies to refuses. An app that
+ * applies the modifiers only once the track is open checks them first, so the
+ * command line fails rather than the open.
+ */
+export declare function checkModifiers(opts: string[]): void;
+/**
+ * A track's member writes: each `encoding.color.field=…` modifier, and a hic
+ * track's `color:<scheme>`, which names one member of the color channel the
+ * track already configures.
+ */
+export declare function memberWrites(displayType: string | undefined, opts: string[]): string[];
+/**
+ * The patch a track's member writes make: each write applied over the value
+ * `configured` gives the setting it names, so the rest of that setting stays.
+ */
+export declare function memberPatch(members: string[], configured: (setting: string) => unknown): Record<string, unknown>;