@jbrowse/plugin-config 4.3.0 → 5.0.0-beta.2

package/esm/FromConfigSequenceAdapter/configSchema.js

@@ -1,12 +1,48 @@
 import { ConfigurationSchema } from '@jbrowse/core/configuration';
-function x() { }
+/**
+ * #config FromConfigSequenceAdapter
+ * #trackType ReferenceSequenceTrack
+ * #fileFormat inline | Inline sequence | Each feature's `seq` holds the bases for its region
+ * supplies reference sequence inline in the config; each feature's `seq` holds
+ * the bases for its region
+ *
+ * #example
+ * Used as the adapter of an assembly's `sequence` (a `ReferenceSequenceTrack`):
+ * ```js
+ * {
+ *   type: 'ReferenceSequenceTrack',
+ *   trackId: 'my_refseq',
+ *   adapter: {
+ *     type: 'FromConfigSequenceAdapter',
+ *     features: [
+ *       { uniqueId: 'ctgA', refName: 'ctgA', start: 0, end: 10, seq: 'ATGCATGCAT' },
+ *     ],
+ *   },
+ * }
+ * ```
+ */
 const sequenceConfigSchema = ConfigurationSchema('FromConfigSequenceAdapter', {
+    /**
+     * #slot
+     * stable identifier used as the adapter cache key; avoids hashing the
+     * (potentially large) features array. optional — falls back to hash.
+     */
+    adapterId: {
+        type: 'string',
+        defaultValue: '',
+    },
+    /**
+     * #slot
+     * one entry per reference sequence, each with a `uniqueId`, `refName`,
+     * `start`, `end`, and a `seq` string holding the bases for that span. The
+     * bases live in the config, so this is for small sequences — a plasmid, a
+     * test contig — not a genome.
+     */
     features: {
         type: 'frozen',
         defaultValue: [],
     },
 }, {
     explicitlyTyped: true,
-    implicitIdentifier: 'adapterId',
 });
 export default sequenceConfigSchema;

package/esm/FromConfigSequenceAdapter/index.js

@@ -1,10 +1,10 @@
 import { AdapterType } from '@jbrowse/core/pluggableElementTypes';
-import configSchema from "./configSchema.js";
+import configSchema from './configSchema.js';
 export default function FromConfigSequenceAdapterF(pluginManager) {
     pluginManager.addAdapterType(() => new AdapterType({
         name: 'FromConfigSequenceAdapter',
         configSchema,
-        getAdapterClass: () => import("./FromConfigSequenceAdapter.js").then(r => r.default),
+        getAdapterClass: () => import('./FromConfigSequenceAdapter.js').then(r => r.default),
         adapterMetadata: {
             hiddenFromGUI: true,
         },

package/esm/NcbiSequenceReportAliasAdapter/NcbiSequenceReportAliasAdapter.d.ts

@@ -1,9 +1,10 @@
 import { BaseAdapter } from '@jbrowse/core/data_adapters/BaseAdapter';
-import type { BaseRefNameAliasAdapter } from '@jbrowse/core/data_adapters/BaseAdapter';
-export default class NcbiSequenceReportAliasAdapter extends BaseAdapter implements BaseRefNameAliasAdapter {
-    getRefNameAliases(): Promise<{
+import type { NcbiSequenceReportAliasAdapterConfig } from './configSchema.ts';
+import type { BaseOptions, BaseRefNameAliasAdapter } from '@jbrowse/core/data_adapters/BaseAdapter';
+export default class NcbiSequenceReportAliasAdapter extends BaseAdapter<NcbiSequenceReportAliasAdapterConfig> implements BaseRefNameAliasAdapter {
+    getRefNameAliases(opts?: BaseOptions): Promise<{
         refName: string;
         aliases: string[];
-        override: any;
+        override: boolean;
     }[]>;
 }

package/esm/NcbiSequenceReportAliasAdapter/NcbiSequenceReportAliasAdapter.js

@@ -1,38 +1,42 @@
 import { BaseAdapter } from '@jbrowse/core/data_adapters/BaseAdapter';
-import { openLocation } from '@jbrowse/core/util/io';
+import { readAliasRows } from '../aliasUtils.js';
+// locate a column by its header name, throwing a column-specific error if a
+// required one is absent
+function requireColumn(header, name) {
+    const idx = header.indexOf(name);
+    if (idx === -1) {
+        throw new Error(`sequence_report.tsv header is missing required column "${name}"`);
+    }
+    return idx;
+}
 export default class NcbiSequenceReportAliasAdapter extends BaseAdapter {
-    async getRefNameAliases() {
-        const loc = this.getConf('location');
-        if (loc.uri === '' || loc.uri === '/path/to/my/sequence_report.tsv') {
+    async getRefNameAliases(opts) {
+        const rows = await readAliasRows(this.getConf('location'), this.pluginManager, opts);
+        if (rows.length === 0) {
             return [];
         }
         const override = this.getConf('useNameOverride');
-        const results = await openLocation(loc, this.pluginManager).readFile('utf8');
-        const lines = results
-            .split(/\n|\r\n|\r/)
-            .filter(f => !!f.trim())
-            .map(row => row.split('\t'));
-        const r = lines[0] || [];
-        const genBankIdx = r.indexOf('GenBank seq accession');
-        const refSeqIdx = r.indexOf('RefSeq seq accession');
-        const ucscIdx = r.indexOf('UCSC style name');
-        const seqNameIdx = r.indexOf('Sequence name');
-        if (genBankIdx === -1 || refSeqIdx === -1 || ucscIdx === -1) {
-            throw new Error('Header line must include "GenBank seq accession", "RefSeq seq accession", "UCSC style name", and "Sequence name"');
-        }
-        return lines
-            .slice(1)
-            .filter(cols => !!cols[ucscIdx] || !!cols[seqNameIdx])
+        const header = rows[0];
+        const dataRows = rows.slice(1);
+        const genBankIdx = requireColumn(header, 'GenBank seq accession');
+        const refSeqIdx = requireColumn(header, 'RefSeq seq accession');
+        const ucscIdx = requireColumn(header, 'UCSC style name');
+        // Sequence name is optional; -1 means absent
+        const seqNameIdx = header.indexOf('Sequence name');
+        const seqName = (cols) => seqNameIdx === -1 ? undefined : cols[seqNameIdx];
+        // refName comes from the UCSC name, falling back to the Sequence name; the
+        // filter guarantees one is present, so every mapped row has a truthy refName
+        return dataRows
+            .filter(cols => !!cols[ucscIdx] || !!seqName(cols))
             .map(cols => ({
-            refName: (cols[ucscIdx] || cols[seqNameIdx]),
+            refName: (cols[ucscIdx] || seqName(cols)),
             aliases: [
                 cols[genBankIdx],
                 cols[refSeqIdx],
                 cols[ucscIdx],
-                cols[seqNameIdx],
+                seqName(cols),
             ].filter((f) => !!f),
             override,
-        }))
-            .filter(f => !!f.refName);
+        }));
     }
 }

package/esm/NcbiSequenceReportAliasAdapter/configSchema.d.ts

@@ -1,15 +1,83 @@
+import { normalizeUriSnapshot } from '../normalizeUriSnapshot.ts';
+import type { Instance } from '@jbrowse/mobx-state-tree';
+export declare const normalizeSnapshot: typeof normalizeUriSnapshot;
+/**
+ * #config NcbiSequenceReportAliasAdapter
+ * can read "sequence_report.tsv" type files from NCBI
+ *
+ * #example
+ * Goes on an ASSEMBLY, under `refNameAliases` — not on a track. The file ships
+ * beside any RefSeq assembly on NCBI datasets and aliases the RefSeq, GenBank
+ * and UCSC-style names of every sequence at once, so it replaces a
+ * hand-maintained chromAlias table:
+ * ```js
+ * {
+ *   name: 'GCF_000001405.40',
+ *   sequence: {
+ *     type: 'ReferenceSequenceTrack',
+ *     trackId: 'GCF_000001405.40-ReferenceSequenceTrack',
+ *     adapter: {
+ *       type: 'BgzipFastaAdapter',
+ *       uri: 'https://example.com/GCF_000001405.40.fa.gz',
+ *     },
+ *   },
+ *   refNameAliases: {
+ *     adapter: {
+ *       type: 'NcbiSequenceReportAliasAdapter',
+ *       uri: 'https://example.com/GCF_000001405.40_sequence_report.tsv',
+ *     },
+ *   },
+ * }
+ * ```
+ *
+ * #example keeping the FASTA's own names
+ * With an NCBI FASTA (`NC_000001.11`), the default displays UCSC-style names
+ * (`chr1`) while still fetching bases under the accession. Set
+ * `useNameOverride: false` to display the accessions instead, with `chr1` left
+ * searchable as an alias:
+ * ```js
+ * {
+ *   name: 'GCF_000001405.40',
+ *   sequence: {
+ *     type: 'ReferenceSequenceTrack',
+ *     trackId: 'GCF_000001405.40-ReferenceSequenceTrack',
+ *     adapter: {
+ *       type: 'BgzipFastaAdapter',
+ *       uri: 'https://example.com/GCF_000001405.40.fa.gz',
+ *     },
+ *   },
+ *   refNameAliases: {
+ *     adapter: {
+ *       type: 'NcbiSequenceReportAliasAdapter',
+ *       uri: 'https://example.com/GCF_000001405.40_sequence_report.tsv',
+ *       useNameOverride: false,
+ *     },
+ *   },
+ * }
+ * ```
+ */
 declare const NcbiSequenceReportAliasAdapterConfigSchema: import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaType<{
-    location: {
-        type: string;
-        defaultValue: {
-            uri: string;
-            locationType: string;
+    /**
+     * #slot
+     * location of the `sequence_report.tsv` NCBI publishes with an assembly. It
+     * carries the RefSeq, GenBank and UCSC-style name of every sequence, so one
+     * file aliases them all without hand-writing a chromAlias table.
+     */
+    readonly location: {
+        readonly type: "fileLocation";
+        readonly defaultValue: {
+            readonly uri: "/path/to/my/sequence_report.tsv";
+            readonly locationType: "UriLocation";
         };
     };
-    useNameOverride: {
-        type: string;
-        defaultValue: boolean;
-        description: string;
+    /**
+     * #slot
+     */
+    readonly useNameOverride: {
+        readonly type: "boolean";
+        readonly defaultValue: true;
+        readonly description: "forces usage of the UCSC names over the NCBI style names from a FASTA";
     };
 }, import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaOptions<undefined, undefined>>;
+export type NcbiSequenceReportAliasAdapterConfig = Instance<typeof NcbiSequenceReportAliasAdapterConfigSchema>;
 export default NcbiSequenceReportAliasAdapterConfigSchema;

package/esm/NcbiSequenceReportAliasAdapter/configSchema.js

@@ -1,6 +1,68 @@
 import { ConfigurationSchema } from '@jbrowse/core/configuration';
-function x() { }
+import { normalizeUriSnapshot } from '../normalizeUriSnapshot.js';
+export const normalizeSnapshot = normalizeUriSnapshot;
+/**
+ * #config NcbiSequenceReportAliasAdapter
+ * can read "sequence_report.tsv" type files from NCBI
+ *
+ * #example
+ * Goes on an ASSEMBLY, under `refNameAliases` — not on a track. The file ships
+ * beside any RefSeq assembly on NCBI datasets and aliases the RefSeq, GenBank
+ * and UCSC-style names of every sequence at once, so it replaces a
+ * hand-maintained chromAlias table:
+ * ```js
+ * {
+ *   name: 'GCF_000001405.40',
+ *   sequence: {
+ *     type: 'ReferenceSequenceTrack',
+ *     trackId: 'GCF_000001405.40-ReferenceSequenceTrack',
+ *     adapter: {
+ *       type: 'BgzipFastaAdapter',
+ *       uri: 'https://example.com/GCF_000001405.40.fa.gz',
+ *     },
+ *   },
+ *   refNameAliases: {
+ *     adapter: {
+ *       type: 'NcbiSequenceReportAliasAdapter',
+ *       uri: 'https://example.com/GCF_000001405.40_sequence_report.tsv',
+ *     },
+ *   },
+ * }
+ * ```
+ *
+ * #example keeping the FASTA's own names
+ * With an NCBI FASTA (`NC_000001.11`), the default displays UCSC-style names
+ * (`chr1`) while still fetching bases under the accession. Set
+ * `useNameOverride: false` to display the accessions instead, with `chr1` left
+ * searchable as an alias:
+ * ```js
+ * {
+ *   name: 'GCF_000001405.40',
+ *   sequence: {
+ *     type: 'ReferenceSequenceTrack',
+ *     trackId: 'GCF_000001405.40-ReferenceSequenceTrack',
+ *     adapter: {
+ *       type: 'BgzipFastaAdapter',
+ *       uri: 'https://example.com/GCF_000001405.40.fa.gz',
+ *     },
+ *   },
+ *   refNameAliases: {
+ *     adapter: {
+ *       type: 'NcbiSequenceReportAliasAdapter',
+ *       uri: 'https://example.com/GCF_000001405.40_sequence_report.tsv',
+ *       useNameOverride: false,
+ *     },
+ *   },
+ * }
+ * ```
+ */
 const NcbiSequenceReportAliasAdapterConfigSchema = ConfigurationSchema('NcbiSequenceReportAliasAdapter', {
+    /**
+     * #slot
+     * location of the `sequence_report.tsv` NCBI publishes with an assembly. It
+     * carries the RefSeq, GenBank and UCSC-style name of every sequence, so one
+     * file aliases them all without hand-writing a chromAlias table.
+     */
     location: {
         type: 'fileLocation',
         defaultValue: {
@@ -8,6 +70,9 @@ const NcbiSequenceReportAliasAdapterConfigSchema = ConfigurationSchema('NcbiSequ
             locationType: 'UriLocation',
         },
     },
+    /**
+     * #slot
+     */
     useNameOverride: {
         type: 'boolean',
         defaultValue: true,
@@ -15,16 +80,18 @@ const NcbiSequenceReportAliasAdapterConfigSchema = ConfigurationSchema('NcbiSequ
     },
 }, {
     explicitlyTyped: true,
-    preProcessSnapshot: snap => {
-        return snap.uri
-            ? {
-                ...snap,
-                location: {
-                    uri: snap.uri,
-                    baseUri: snap.baseUri,
-                },
-            }
-            : snap;
-    },
+    /**
+     * #preProcessSnapshot
+     *
+     *
+     * preprocessor to allow minimal config:
+     * ```json
+     * {
+     *   "type": "NcbiSequenceReportAliasAdapter",
+     *   "uri": "sequence_report.tsv"
+     * }
+     * ```
+     */
+    preProcessSnapshot: normalizeSnapshot,
 });
 export default NcbiSequenceReportAliasAdapterConfigSchema;

package/esm/NcbiSequenceReportAliasAdapter/index.js

@@ -1,11 +1,12 @@
 import { AdapterType } from '@jbrowse/core/pluggableElementTypes';
-import configSchema from "./configSchema.js";
+import configSchema, { normalizeSnapshot } from './configSchema.js';
 export default function NcbiSequenceReportAliasAdapterF(pluginManager) {
     pluginManager.addAdapterType(() => {
         return new AdapterType({
             name: 'NcbiSequenceReportAliasAdapter',
+            normalizeSnapshot,
             configSchema,
-            getAdapterClass: () => import("./NcbiSequenceReportAliasAdapter.js").then(r => r.default),
+            getAdapterClass: () => import('./NcbiSequenceReportAliasAdapter.js').then(r => r.default),
             adapterMetadata: {
                 hiddenFromGUI: true,
             },

package/esm/RefNameAliasAdapter/RefNameAliasAdapter.d.ts

@@ -1,7 +1,8 @@
 import { BaseAdapter } from '@jbrowse/core/data_adapters/BaseAdapter';
-import type { BaseRefNameAliasAdapter } from '@jbrowse/core/data_adapters/BaseAdapter';
-export default class RefNameAliasAdapter extends BaseAdapter implements BaseRefNameAliasAdapter {
-    getRefNameAliases(): Promise<{
+import type { RefNameAliasAdapterConfig } from './configSchema.ts';
+import type { BaseOptions, BaseRefNameAliasAdapter } from '@jbrowse/core/data_adapters/BaseAdapter';
+export default class RefNameAliasAdapter extends BaseAdapter<RefNameAliasAdapterConfig> implements BaseRefNameAliasAdapter {
+    getRefNameAliases(opts?: BaseOptions): Promise<{
         refName: string;
         aliases: string[];
     }[]>;

package/esm/RefNameAliasAdapter/RefNameAliasAdapter.js

@@ -1,36 +1,30 @@
 import { BaseAdapter } from '@jbrowse/core/data_adapters/BaseAdapter';
-import { openLocation } from '@jbrowse/core/util/io';
+import { readAliasRows } from '../aliasUtils.js';
+// header lines start with '#'; the leading marker belongs to the first column
+const isComment = (cols) => !!cols[0]?.startsWith('#');
+// column names from a '#'-prefixed header row, with the marker stripped
+const headerNames = (cols) => cols.map((col, i) => (i === 0 ? col.slice(1) : col).trim());
 export default class RefNameAliasAdapter extends BaseAdapter {
-    async getRefNameAliases() {
-        const loc = this.getConf('location');
-        if (loc.uri === '' || loc.uri === '/path/to/my/aliases.txt') {
-            return [];
-        }
-        const results = await openLocation(loc, this.pluginManager).readFile('utf8');
+    async getRefNameAliases(opts) {
+        const rows = await readAliasRows(this.getConf('location'), this.pluginManager, opts);
         const refColumn = this.getConf('refNameColumn');
         const refColumnHeaderName = this.getConf('refNameColumnHeaderName');
-        const lines = results
-            .trim()
-            .split(/\n|\r\n|\r/)
-            .filter(f => !!f);
-        const header = lines.filter(f => f.startsWith('#'));
-        const headerCol = refColumnHeaderName && header.length
-            ? header
-                .at(-1)
-                .slice(1)
-                .split('\t')
-                .map(t => t.trim())
-                .indexOf(refColumnHeaderName)
+        const lastHeader = rows.filter(isComment).at(-1);
+        const headerCol = refColumnHeaderName && lastHeader
+            ? headerNames(lastHeader).indexOf(refColumnHeaderName)
             : refColumn;
-        return lines
-            .filter(f => !f.startsWith('#'))
-            .map(row => {
-            const aliases = row.split('\t');
-            const refName = aliases[headerCol];
-            return {
-                refName: refName,
-                aliases: aliases.filter(f => !!f.trim()),
-            };
+        if (headerCol === -1) {
+            throw new Error(`refNameColumnHeaderName "${refColumnHeaderName}" not found in alias file header`);
+        }
+        return rows
+            .filter(cols => !isComment(cols))
+            .flatMap(cols => {
+            // a blank refName column (short/ragged row, leading tab) would map every
+            // alias to an empty canonical name in buildRefNameMaps; drop such rows
+            const refName = cols[headerCol]?.trim();
+            return refName
+                ? [{ refName, aliases: cols.filter(f => !!f.trim()) }]
+                : [];
         });
     }
 }

package/esm/RefNameAliasAdapter/configSchema.d.ts

@@ -1,19 +1,94 @@
+import { normalizeUriSnapshot } from '../normalizeUriSnapshot.ts';
+import type { Instance } from '@jbrowse/mobx-state-tree';
+export declare const normalizeSnapshot: typeof normalizeUriSnapshot;
+/**
+ * #config RefNameAliasAdapter
+ * can read "chromAliases" type files from UCSC or any tab separated file of
+ * refName aliases
+ *
+ * #example
+ * Goes on an ASSEMBLY, under `refNameAliases` — not on a track. Writing
+ * `refNameAliases: { uri: '...' }` is shorthand for exactly this adapter:
+ * ```js
+ * {
+ *   name: 'hg38',
+ *   sequence: {
+ *     type: 'ReferenceSequenceTrack',
+ *     trackId: 'hg38-ReferenceSequenceTrack',
+ *     adapter: {
+ *       type: 'BgzipFastaAdapter',
+ *       uri: 'https://example.com/hg38.fa.gz',
+ *     },
+ *   },
+ *   refNameAliases: {
+ *     adapter: {
+ *       type: 'RefNameAliasAdapter',
+ *       uri: 'https://example.com/hg38.chromAlias.txt',
+ *     },
+ *   },
+ * }
+ * ```
+ *
+ * #example named column
+ * When the primary column — the one whose values match your FASTA — is not the
+ * first, name it. `refNameColumnHeaderName` reads the last `#`-prefixed line as
+ * the header; `refNameColumn` takes a zero-based index instead.
+ * ```js
+ * {
+ *   name: 'hg38',
+ *   sequence: {
+ *     type: 'ReferenceSequenceTrack',
+ *     trackId: 'hg38-ReferenceSequenceTrack',
+ *     adapter: {
+ *       type: 'BgzipFastaAdapter',
+ *       uri: 'https://example.com/hg38.fa.gz',
+ *     },
+ *   },
+ *   refNameAliases: {
+ *     adapter: {
+ *       type: 'RefNameAliasAdapter',
+ *       uri: 'https://example.com/aliases.txt',
+ *       refNameColumnHeaderName: 'ucsc',
+ *     },
+ *   },
+ * }
+ * ```
+ */
 declare const RefNameAliasAdapter: import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaType<{
-    location: {
-        type: string;
-        defaultValue: {
-            uri: string;
-            locationType: string;
+    /**
+     * #slot
+     * location of the alias table: a UCSC `chromAlias.txt`, or any
+     * tab-separated file whose rows each list the alternate names of one
+     * reference sequence (`chr1<TAB>1<TAB>NC_000001.11`). It is what lets a
+     * `1`-named file load against a `chr1`-named assembly.
+     */
+    readonly location: {
+        readonly type: "fileLocation";
+        readonly defaultValue: {
+            readonly uri: "/path/to/my/aliases.txt";
+            readonly locationType: "UriLocation";
         };
     };
-    refNameColumn: {
-        type: string;
-        defaultValue: number;
+    /**
+     * #slot
+     * by default, the "ref names that match the fasta" are assumed to be in the
+     * first column (0), change this variable if needed
+     */
+    readonly refNameColumn: {
+        readonly type: "number";
+        readonly defaultValue: 0;
+        readonly advanced: true;
     };
-    refNameColumnHeaderName: {
-        type: string;
-        description: string;
-        defaultValue: string;
+    /**
+     * #slot
+     * refNameColumnHeaderName
+     */
+    readonly refNameColumnHeaderName: {
+        readonly type: "string";
+        readonly description: "alternative to refNameColumn, instead looks at header (starts with # and finds column name)";
+        readonly defaultValue: "";
+        readonly advanced: true;
     };
 }, import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaOptions<undefined, undefined>>;
+export type RefNameAliasAdapterConfig = Instance<typeof RefNameAliasAdapter>;
 export default RefNameAliasAdapter;

package/esm/RefNameAliasAdapter/configSchema.js

@@ -1,6 +1,67 @@
 import { ConfigurationSchema } from '@jbrowse/core/configuration';
-function x() { }
+import { normalizeUriSnapshot } from '../normalizeUriSnapshot.js';
+export const normalizeSnapshot = normalizeUriSnapshot;
+/**
+ * #config RefNameAliasAdapter
+ * can read "chromAliases" type files from UCSC or any tab separated file of
+ * refName aliases
+ *
+ * #example
+ * Goes on an ASSEMBLY, under `refNameAliases` — not on a track. Writing
+ * `refNameAliases: { uri: '...' }` is shorthand for exactly this adapter:
+ * ```js
+ * {
+ *   name: 'hg38',
+ *   sequence: {
+ *     type: 'ReferenceSequenceTrack',
+ *     trackId: 'hg38-ReferenceSequenceTrack',
+ *     adapter: {
+ *       type: 'BgzipFastaAdapter',
+ *       uri: 'https://example.com/hg38.fa.gz',
+ *     },
+ *   },
+ *   refNameAliases: {
+ *     adapter: {
+ *       type: 'RefNameAliasAdapter',
+ *       uri: 'https://example.com/hg38.chromAlias.txt',
+ *     },
+ *   },
+ * }
+ * ```
+ *
+ * #example named column
+ * When the primary column — the one whose values match your FASTA — is not the
+ * first, name it. `refNameColumnHeaderName` reads the last `#`-prefixed line as
+ * the header; `refNameColumn` takes a zero-based index instead.
+ * ```js
+ * {
+ *   name: 'hg38',
+ *   sequence: {
+ *     type: 'ReferenceSequenceTrack',
+ *     trackId: 'hg38-ReferenceSequenceTrack',
+ *     adapter: {
+ *       type: 'BgzipFastaAdapter',
+ *       uri: 'https://example.com/hg38.fa.gz',
+ *     },
+ *   },
+ *   refNameAliases: {
+ *     adapter: {
+ *       type: 'RefNameAliasAdapter',
+ *       uri: 'https://example.com/aliases.txt',
+ *       refNameColumnHeaderName: 'ucsc',
+ *     },
+ *   },
+ * }
+ * ```
+ */
 const RefNameAliasAdapter = ConfigurationSchema('RefNameAliasAdapter', {
+    /**
+     * #slot
+     * location of the alias table: a UCSC `chromAlias.txt`, or any
+     * tab-separated file whose rows each list the alternate names of one
+     * reference sequence (`chr1<TAB>1<TAB>NC_000001.11`). It is what lets a
+     * `1`-named file load against a `chr1`-named assembly.
+     */
     location: {
         type: 'fileLocation',
         defaultValue: {
@@ -8,27 +69,40 @@ const RefNameAliasAdapter = ConfigurationSchema('RefNameAliasAdapter', {
             locationType: 'UriLocation',
         },
     },
+    /**
+     * #slot
+     * by default, the "ref names that match the fasta" are assumed to be in the
+     * first column (0), change this variable if needed
+     */
     refNameColumn: {
         type: 'number',
         defaultValue: 0,
+        advanced: true,
     },
+    /**
+     * #slot
+     * refNameColumnHeaderName
+     */
     refNameColumnHeaderName: {
         type: 'string',
         description: 'alternative to refNameColumn, instead looks at header (starts with # and finds column name)',
         defaultValue: '',
+        advanced: true,
     },
 }, {
     explicitlyTyped: true,
-    preProcessSnapshot: snap => {
-        return snap.uri
-            ? {
-                ...snap,
-                location: {
-                    uri: snap.uri,
-                    baseUri: snap.baseUri,
-                },
-            }
-            : snap;
-    },
+    /**
+     * #preProcessSnapshot
+     *
+     *
+     * preprocessor to allow minimal config:
+     * ```json
+     * {
+     *   "type": "RefNameAliasAdapter",
+     *   "uri": "yourfile.chromAlias.txt"
+     * }
+     * ```
+     */
+    preProcessSnapshot: normalizeSnapshot,
 });
 export default RefNameAliasAdapter;