@jbrowse/core 4.3.0 → 5.0.0-beta.10

package/esm/data_adapters/BaseAdapter/BaseFeatureDataAdapter.js

@@ -1,41 +1,100 @@
 import { firstValueFrom, merge } from 'rxjs';
 import { toArray } from 'rxjs/operators';
-import { BaseAdapter } from "./BaseAdapter.js";
-import { aggregateQuantitativeStats, calculateFeatureDensityStats, } from "./stats.js";
-import { ObservableCreate } from "../../util/rxjs.js";
-import { blankStats, scoresToStats } from "../../util/stats.js";
+import { asTable } from '../../util/featureTable.js';
+import { createStatusFanOut } from '../../util/progress.js';
+import { blankStats, scoresToStats } from '../../util/stats.js';
+import { BaseAdapter } from './BaseAdapter.js';
+import { isSubAdapterConfig } from './featureDensity.js';
+import { aggregateQuantitativeStats } from './stats.js';
+import { isFeatureAdapter } from './util.js';
+/**
+ * Base class for feature adapters to extend. Defines some methods that
+ * subclasses must implement.
+ */
+/** #adapterBase BaseFeatureDataAdapter | features overlapping a region — genes, reads, variants. The common case */
 export class BaseFeatureDataAdapter extends BaseAdapter {
+    /**
+     * Return "header info" that is fetched from the data file, or other info
+     * that would not simply be in the config of the file. The return value can
+     * be `{tag:string, data: any}[]` e.g. list of tags with their values which
+     * is how VCF,BAM,CRAM return values for getInfo or it can be a nested JSON
+     * object
+     */
     async getHeader(_opts) {
         return null;
     }
+    /**
+     * Return info that is primarily used for interpreting the data that is there,
+     * primarily in reference to being used for augmenting feature details panels
+     */
     async getMetadata(_opts) {
         return null;
     }
-    getFeaturesInRegion(region, opts = {}) {
-        return ObservableCreate(async (observer) => {
-            const hasData = await this.hasDataForRefName(region.refName, opts);
-            if (!hasData) {
-                observer.complete();
-            }
-            else {
-                this.getFeatures(region, opts).subscribe(observer);
-            }
-        });
-    }
+    /**
+     * Adapters that are frequently called on multiple regions simultaneously
+     * may want to implement a more efficient custom version of this method.
+     *
+     * The regions are fetched concurrently, so each gets its own
+     * {@link createStatusFanOut} slot rather than the caller's raw
+     * `statusCallback`: they all report the same phases ("Downloading
+     * features"), and sharing one status field meant the last writer won and the
+     * first region to finish cleared the label while the rest were still
+     * downloading. Aggregated, N regions read as one Σbytes bar — the same helper
+     * `callEachRegion` uses to give the per-region RPCs on the main thread a slot
+     * apiece.
+     */
     getFeaturesInMultipleRegions(regions, opts = {}) {
-        return merge(...regions.map(region => this.getFeaturesInRegion(region, opts)));
+        const slot = createStatusFanOut(opts.statusCallback);
+        return merge(...regions.map(region => this.getFeatures(region, { ...opts, statusCallback: slot() })));
+    }
+    /**
+     * Convenience wrapper that collects {@link getFeatures} for a region into an
+     * array — the common shape across RPC methods (RenderFeatureData, Manhattan,
+     * Wiggle, etc.). Pass `opts` so `statusCallback`/`signal` reach the
+     * adapter; omitting them means no download progress and a fetch that can't be
+     * interrupted mid-flight.
+     */
+    getFeaturesArray(region, opts = {}) {
+        return firstValueFrom(this.getFeatures(region, opts).pipe(toArray()));
     }
+    /**
+     * The features overlapping a region as the table a mark's declaration runs
+     * over: by default a table over {@link getFeaturesArray}. An adapter that
+     * already holds its rows as typed arrays answers a `ColumnTable` over them
+     * instead, and makes no object per row.
+     */
+    async getFeatureTable(region, opts = {}) {
+        return asTable(await this.getFeaturesArray(region, opts));
+    }
+    /**
+     * {@link getFeaturesArray} across multiple regions — collects
+     * {@link getFeaturesInMultipleRegions} into an array. The common shape in
+     * matrix/comparative RPC methods (variants, synteny, dotplot, breakpoint).
+     */
+    getFeaturesInMultipleRegionsArray(regions, opts = {}) {
+        return firstValueFrom(this.getFeaturesInMultipleRegions(regions, opts).pipe(toArray()));
+    }
+    /**
+     * Check if the store has data for the given reference name.
+     * @param refName - Name of the reference sequence
+     * @returns Whether data source has data for the given reference name
+     */
     async hasDataForRefName(refName, opts = {}) {
         const refNames = await this.getRefNames(opts);
         return refNames.includes(refName);
     }
+    /**
+     * Calculates the minimum score, maximum score, and other statistics from
+     * features over a region, primarily used for quantitative tracks
+     */
     async getRegionQuantitativeStats(region, opts) {
-        const feats = this.getFeatures(region, {
-            ...opts,
-            statsEstimationMode: true,
-        });
+        const feats = this.getFeatures(region, opts);
         return scoresToStats(region, feats);
     }
+    /**
+     * Calculates the minimum score, maximum score, and other statistics from
+     * features over multiple regions, primarily used for quantitative tracks
+     */
     async getMultiRegionQuantitativeStats(regions = [], opts) {
         if (!regions.length) {
             return blankStats();
@@ -43,25 +102,101 @@ export class BaseFeatureDataAdapter extends BaseAdapter {
         const stats = await Promise.all(regions.map(region => this.getRegionQuantitativeStats(region, opts)));
         return aggregateQuantitativeStats(stats);
     }
-    getRegionFeatureDensityStats(region, opts) {
-        return calculateFeatureDensityStats(region, (region2, opts2) => this.getFeatures(region2, opts2), opts);
+    /**
+     * Cheap upper bound on the compressed bytes a fetch of `regions` would pull,
+     * derived from an index without downloading or parsing any features. The
+     * default returns `undefined` ("no cheap estimate"); indexed adapters (tabix)
+     * override it, and an adapter that caps what it returns at screen resolution
+     * (BigWig, HiC, sequence) simply doesn't — no estimate means no byte gate.
+     *
+     * The one byte-estimate entry point, used by both halves of the region-too-large
+     * gate: the pre-flight `CoreGetRegionByteEstimate` RPC and the in-fetch
+     * short-circuit in `executeRenderFeatureData`. The byte *budget* it is compared
+     * against is read on the main thread from the adapter's `fetchSizeLimit` config
+     * slot, so it never crosses the worker boundary — see
+     * agent-docs/reference/REGION_TOO_LARGE.md.
+     */
+    async getRegionByteSize(_regions, _opts) {
+        return undefined;
     }
-    async getMultiRegionFeatureDensityStats(regions, opts) {
-        if (!regions.length) {
-            throw new Error('No regions supplied');
+    /**
+     * The bp/px interval over which this adapter answers a fetch from the same
+     * zoom level it answers `opts.bpPerPx` from, so a display holding the answer
+     * refetches only when the view leaves it. The default, `undefined`, is an
+     * answer that does not depend on the zoom, which a display never refetches
+     * for a zoom. An adapter that reads `bpPerPx` declares its range here
+     * (`BigWigAdapter` from its header's zoom levels).
+     */
+    async getZoomRange(_opts) {
+        return undefined;
+    }
+    /**
+     * The interval every value this adapter answers lies in by definition, as a
+     * fraction lies in [0, 1], which a value scale's unpinned ends stand at
+     * rather than following the loaded data, so the axis reads alike at every
+     * locus. The default, `undefined`, is a quantity with no such bounds, whose
+     * axis autoscales. `GCContentAdapter` declares [0, 1] for GC content and none
+     * for skew.
+     */
+    async getValueDomain(_opts) {
+        return undefined;
+    }
+    /**
+     * Features per bin over each region, at the view's `bpPerPx`, for the density
+     * tier the display draws where the region-too-large gate refused the
+     * features. The default reads the `densityAdapter` sidecar slot
+     * (`densityAdapterConfigSchemaFields`) through `getSubAdapter`; `undefined`
+     * means no tier, and the banner stands. ADR-102 records why no index
+     * estimate stands in for a missing sidecar.
+     */
+    async getFeatureDensity(regions, opts) {
+        const sidecar = this.getConf(['densityAdapter']);
+        const resolved = isSubAdapterConfig(sidecar) && this.getSubAdapter
+            ? (await this.getSubAdapter(sidecar)).dataAdapter
+            : undefined;
+        if (resolved && !isFeatureAdapter(resolved)) {
+            throw new Error(`densityAdapter ${isSubAdapterConfig(sidecar) ? sidecar.type : ''} is not a feature adapter`);
         }
-        return this.getRegionFeatureDensityStats(regions[0], opts);
+        return resolved
+            ? Promise.all(regions.map(async (region) => {
+                const features = await resolved.getFeaturesArray(region, opts);
+                const starts = new Uint32Array(features.length);
+                const ends = new Uint32Array(features.length);
+                const scores = new Float32Array(features.length);
+                features.forEach((feature, i) => {
+                    const score = feature.get('score');
+                    starts[i] = feature.get('start');
+                    ends[i] = feature.get('end');
+                    scores[i] = score === undefined ? 0 : score;
+                });
+                return { starts, ends, scores };
+            }))
+            : undefined;
     }
-    async getSources(regions) {
-        const features = await firstValueFrom(this.getFeaturesInMultipleRegions(regions).pipe(toArray()));
+    async getSources(regions, opts = {}) {
+        const features = await this.getFeaturesInMultipleRegionsArray(regions, opts);
         const sources = new Set();
         for (const f of features) {
-            sources.add(f.get('source'));
+            const source = f.get('source');
+            if (source !== undefined) {
+                sources.add(source);
+            }
         }
         return [...sources].map(source => ({
             name: source,
         }));
     }
+    /**
+     * Export data from the adapter in a specified format for given regions.
+     * Some adapters (like VcfAdapter) can efficiently export raw data directly
+     * from the file without parsing to features.
+     *
+     * @param regions - Regions to export data from
+     * @param formatType - The format to export to (e.g. 'vcf', 'sam', 'bedgraph')
+     * @param opts - Feature adapter options
+     * @returns Promise resolving to the exported data as a string, or undefined
+     *          if the adapter does not support direct export for this format
+     */
     async getExportData(_regions, _formatType, _opts) {
         return undefined;
     }

package/esm/data_adapters/BaseAdapter/BaseRefNameAliasAdapter.d.ts

@@ -5,6 +5,7 @@ export interface Alias {
     aliases: string[];
     override?: boolean;
 }
+/** #adapterBase BaseRefNameAliasAdapter | refName aliases, e.g. `chr1` for `1` */
 export interface BaseRefNameAliasAdapter extends BaseAdapter {
     getRefNameAliases(opts: BaseOptions): Promise<Alias[]>;
 }

package/esm/data_adapters/BaseAdapter/BaseSequenceAdapter.d.ts

@@ -1,11 +1,19 @@
 import { BaseFeatureDataAdapter } from './BaseFeatureDataAdapter.ts';
-import type { BaseOptions } from './types.ts';
+import type { AnyConfigurationModel } from '../../configuration/index.ts';
 import type { NoAssemblyRegion } from '../../util/index.ts';
 import type { RegionsAdapter } from '../BaseAdapter/index.ts';
-export declare abstract class BaseSequenceAdapter extends BaseFeatureDataAdapter implements RegionsAdapter {
-    getMultiRegionFeatureDensityStats(): Promise<{
-        featureDensity: number;
-    }>;
+import type { BaseOptions } from './types.ts';
+/** #adapterBase BaseSequenceAdapter | a region list plus the sequence for a queried region; extends the feature adapter */
+export declare abstract class BaseSequenceAdapter<CONF extends AnyConfigurationModel = AnyConfigurationModel> extends BaseFeatureDataAdapter<CONF> implements RegionsAdapter {
+    /**
+     * Fetches a list of 'regions' with refName, start, and extends
+     */
     abstract getRegions(opts: BaseOptions): Promise<NoAssemblyRegion[]>;
+    /**
+     * Fetches the sequence string for a given region
+     * @param region - Region to fetch sequence for
+     * @param opts - Adapter options
+     * @returns The sequence string for the region
+     */
     getSequence(region: NoAssemblyRegion, opts?: BaseOptions): Promise<string | undefined>;
 }

package/esm/data_adapters/BaseAdapter/BaseSequenceAdapter.js

@@ -1,12 +1,14 @@
-import { firstValueFrom } from 'rxjs';
-import { toArray } from 'rxjs/operators';
-import { BaseFeatureDataAdapter } from "./BaseFeatureDataAdapter.js";
+import { BaseFeatureDataAdapter } from './BaseFeatureDataAdapter.js';
+/** #adapterBase BaseSequenceAdapter | a region list plus the sequence for a queried region; extends the feature adapter */
 export class BaseSequenceAdapter extends BaseFeatureDataAdapter {
-    async getMultiRegionFeatureDensityStats() {
-        return { featureDensity: 0 };
-    }
+    /**
+     * Fetches the sequence string for a given region
+     * @param region - Region to fetch sequence for
+     * @param opts - Adapter options
+     * @returns The sequence string for the region
+     */
     async getSequence(region, opts) {
-        const features = await firstValueFrom(this.getFeatures({ ...region, assemblyName: '' }, opts).pipe(toArray()));
+        const features = await this.getFeaturesArray({ ...region, assemblyName: '' }, opts);
         return features[0]?.get('seq');
     }
 }

package/esm/data_adapters/BaseAdapter/BaseTextSearchAdapter.d.ts

@@ -1,6 +1,7 @@
+import type BaseResult from '../../TextSearch/BaseResults.ts';
 import type { BaseAdapter } from './BaseAdapter.ts';
 import type { BaseTextSearchArgs } from './types.ts';
-import type BaseResult from '../../TextSearch/BaseResults.ts';
+/** #adapterBase BaseTextSearchAdapter | search-box hits out of a text index */
 export interface BaseTextSearchAdapter extends BaseAdapter {
     searchIndex(args: BaseTextSearchArgs): Promise<BaseResult[]>;
 }

package/esm/data_adapters/BaseAdapter/CytobandAdapter.d.ts

@@ -0,0 +1,7 @@
+import type { Feature } from '../../util/index.ts';
+import type { BaseAdapter } from './BaseAdapter.ts';
+import type { BaseOptions } from './types.ts';
+/** #adapterBase CytobandAdapter | cytoband features for the ideogram */
+export interface CytobandAdapter extends BaseAdapter {
+    getData(opts?: BaseOptions): Promise<Feature[]>;
+}

package/esm/data_adapters/BaseAdapter/RegionsAdapter.d.ts

@@ -1,6 +1,7 @@
+import type { NoAssemblyRegion } from '../../util/index.ts';
 import type { BaseAdapter } from './BaseAdapter.ts';
 import type { BaseOptions } from './types.ts';
-import type { NoAssemblyRegion } from '../../util/index.ts';
+/** #adapterBase RegionsAdapter | which regions an assembly has, and how long each is */
 export interface RegionsAdapter extends BaseAdapter {
     getRegions(opts: BaseOptions): Promise<NoAssemblyRegion[]>;
 }

package/esm/data_adapters/BaseAdapter/featureDensity.d.ts

@@ -0,0 +1,40 @@
+/**
+ * A density source's intervals over one region, the payload of the density
+ * tier that stands in for the features a gated fetch refused: features per bin
+ * for a `make-density` sidecar, whatever the bigWig measures otherwise, each
+ * value a level over its span so a zoomed read means the same thing. Absolute
+ * genomic coordinates.
+ */
+export interface FeatureDensity {
+    starts: Uint32Array;
+    ends: Uint32Array;
+    scores: Float32Array;
+}
+/**
+ * The slot a feature adapter spreads to take a density sidecar — a
+ * quantitative sub-adapter (typically a BigWig of feature starts per bin) the
+ * display reads at the view's bp/px in place of features the region-too-large
+ * gate refused. Mirrors MAF's `summaryAdapter`: on the adapter, so the tier
+ * names the file it summarizes.
+ */
+export declare const densityAdapterConfigSchemaFields: {
+    /**
+     * #slot
+     */
+    readonly densityAdapter: {
+        readonly type: 'maybeFrozen';
+        readonly description: 'optional quantitative sub-adapter (e.g. a BigWigAdapter over a features-per-bin bigWig) drawn as a density band where the region is too large to fetch features; leave it unset to disable';
+    };
+};
+/**
+ * Whether the `densityAdapter` slot holds something a sub-adapter can be built
+ * from. Beside the slot because both ends of the tier ask it and they have to
+ * agree: the display, deciding the band stands in, and `getFeatureDensity`,
+ * resolving the sidecar. They disagreed — the display took any object, the
+ * adapter wanted a type — so the shorthand every location slot accepts
+ * (`{ uri }`) turned the band on for a read that answered `undefined`, which
+ * commits nothing, and the phase then waited on bins no read would ever bring.
+ */
+export declare function isSubAdapterConfig(value: unknown): value is Record<string, unknown> & {
+    type: string;
+};

package/esm/data_adapters/BaseAdapter/featureDensity.js

@@ -0,0 +1,31 @@
+/**
+ * The slot a feature adapter spreads to take a density sidecar — a
+ * quantitative sub-adapter (typically a BigWig of feature starts per bin) the
+ * display reads at the view's bp/px in place of features the region-too-large
+ * gate refused. Mirrors MAF's `summaryAdapter`: on the adapter, so the tier
+ * names the file it summarizes.
+ */
+export const densityAdapterConfigSchemaFields = {
+    /**
+     * #slot
+     */
+    densityAdapter: {
+        type: 'maybeFrozen',
+        description: 'optional quantitative sub-adapter (e.g. a BigWigAdapter over a features-per-bin bigWig) drawn as a density band where the region is too large to fetch features; leave it unset to disable',
+    },
+};
+/**
+ * Whether the `densityAdapter` slot holds something a sub-adapter can be built
+ * from. Beside the slot because both ends of the tier ask it and they have to
+ * agree: the display, deciding the band stands in, and `getFeatureDensity`,
+ * resolving the sidecar. They disagreed — the display took any object, the
+ * adapter wanted a type — so the shorthand every location slot accepts
+ * (`{ uri }`) turned the band on for a read that answered `undefined`, which
+ * commits nothing, and the phase then waited on bins no read would ever bring.
+ */
+export function isSubAdapterConfig(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'type' in value &&
+        typeof value.type === 'string');
+}

package/esm/data_adapters/BaseAdapter/getAdapterId.d.ts

@@ -0,0 +1,2 @@
+import type { AnyConfigurationModel } from '../../configuration/index.ts';
+export declare function getAdapterId(config: AnyConfigurationModel): string;

package/esm/data_adapters/BaseAdapter/getAdapterId.js

@@ -0,0 +1,9 @@
+import { getSnapshot, isStateTreeNode } from '@jbrowse/mobx-state-tree';
+import idMaker from '../../util/idMaker.js';
+// extracted into its own module so tests can swap it out via jest's
+// moduleNameMapper for a stable 'test' id, keeping the test detection out
+// of the production class
+export function getAdapterId(config) {
+    const data = isStateTreeNode(config) ? getSnapshot(config) : config;
+    return idMaker(data);
+}

package/esm/data_adapters/BaseAdapter/index.d.ts

@@ -1,13 +1,35 @@
-import type { AnyDataAdapter } from './util.ts';
 import type PluginManager from '../../PluginManager.ts';
-import type { AnyConfigurationModel } from '../../configuration/index.ts';
+import type { AnyConfigurationSchemaType } from '../../configuration/index.ts';
 import type { getSubAdapterType } from '../dataAdapterCache.ts';
-export * from './util.ts';
-export * from './types.ts';
+import type { AnyDataAdapter } from './util.ts';
+import type { Instance } from '@jbrowse/mobx-state-tree';
+export { type AnyDataAdapter, isFeatureAdapter, isRefNameAliasAdapter, isRegionsAdapter, isSequenceAdapter, isTextSearchAdapter, } from './util.ts';
+export type { BaseOptions, BaseTextSearchArgs, LodTier, SearchType, ZoomRange, } from './types.ts';
 export { BaseAdapter } from './BaseAdapter.ts';
+export { cachedSetup } from '../../util/cachedSetup.ts';
 export { BaseFeatureDataAdapter } from './BaseFeatureDataAdapter.ts';
+export { type FeatureDensity, densityAdapterConfigSchemaFields, isSubAdapterConfig, } from './featureDensity.ts';
 export { BaseSequenceAdapter } from './BaseSequenceAdapter.ts';
 export type { BaseTextSearchAdapter } from './BaseTextSearchAdapter.ts';
-export type { BaseRefNameAliasAdapter } from './BaseRefNameAliasAdapter.ts';
+export type { Alias, BaseRefNameAliasAdapter, } from './BaseRefNameAliasAdapter.ts';
 export type { RegionsAdapter } from './RegionsAdapter.ts';
-export type AnyAdapter = new (config: AnyConfigurationModel, getSubAdapter?: getSubAdapterType, pluginManager?: PluginManager) => AnyDataAdapter;
+export type { CytobandAdapter } from './CytobandAdapter.ts';
+/**
+ * The adapter class that goes with SCHEMA — the class whose `config` is that
+ * schema's node. `AdapterType` is generic over the schema so registering the
+ * two together checks that they are the same adapter's; the pairing is
+ * otherwise only a shared `type` string, and nothing reports a class reading
+ * slots its declared schema never had.
+ *
+ * see
+ * https://www.typescriptlang.org/docs/handbook/2/classes.html#abstract-construct-signatures
+ * for why this is the abstract construct signature
+ */
+export type AdapterClassFor<SCHEMA> = new (config: SCHEMA extends AnyConfigurationSchemaType ? Instance<SCHEMA> : any, getSubAdapter?: getSubAdapterType, pluginManager?: PluginManager, sequenceAdapterConfig?: Record<string, unknown>) => AnyDataAdapter;
+/**
+ * An adapter class with its schema forgotten, which is what the registry holds
+ * and `dataAdapterCache` constructs: the config node it has in hand came from
+ * the `AdapterType` the same `type` name resolved to, and that lookup is the
+ * only thing tying the two together.
+ */
+export type AnyAdapter = AdapterClassFor<any>;

package/esm/data_adapters/BaseAdapter/index.js

@@ -1,5 +1,6 @@
-export * from "./util.js";
-export * from "./types.js";
-export { BaseAdapter } from "./BaseAdapter.js";
-export { BaseFeatureDataAdapter } from "./BaseFeatureDataAdapter.js";
-export { BaseSequenceAdapter } from "./BaseSequenceAdapter.js";
+export { isFeatureAdapter, isRefNameAliasAdapter, isRegionsAdapter, isSequenceAdapter, isTextSearchAdapter, } from './util.js';
+export { BaseAdapter } from './BaseAdapter.js';
+export { cachedSetup } from '../../util/cachedSetup.js';
+export { BaseFeatureDataAdapter } from './BaseFeatureDataAdapter.js';
+export { densityAdapterConfigSchemaFields, isSubAdapterConfig, } from './featureDensity.js';
+export { BaseSequenceAdapter } from './BaseSequenceAdapter.js';

package/esm/data_adapters/BaseAdapter/rowSources.d.ts

@@ -0,0 +1,37 @@
+import type { BaseOptions } from './types.ts';
+/**
+ * #api
+ * One row an adapter lists: `name` is a value of the listing's field, and
+ * `label` and `color` are what the adapter names and colours that row with.
+ */
+export interface ListedRowSource {
+    name: string;
+    label?: string;
+    color?: string;
+}
+/**
+ * #api
+ * Every row an adapter has, in its own order, whatever the loaded regions hold,
+ * so a row display gives a row with nothing in view its place, label and
+ * colour.
+ */
+export interface RowSourceListing {
+    /** The feature field the listed names are values of: `source` on a multi-BigWig, `alignments` on a MAF, whose per-species record is keyed by them. */
+    field: string;
+    sources: ListedRowSource[];
+    /** A guide tree over the names, as Newick, where the adapter ships one. */
+    tree?: string;
+}
+/**
+ * #api
+ * An adapter that lists its rows without reading a region: a multi-BigWig its
+ * files, a MAF its species.
+ */
+export interface RowSourceLister {
+    listRowSources(opts?: BaseOptions): Promise<RowSourceListing>;
+}
+/**
+ * #api
+ * Whether an adapter implements {@link RowSourceLister}.
+ */
+export declare function listsRowSources(adapter: object): adapter is RowSourceLister;

package/esm/data_adapters/BaseAdapter/rowSources.js

@@ -0,0 +1,7 @@
+/**
+ * #api
+ * Whether an adapter implements {@link RowSourceLister}.
+ */
+export function listsRowSources(adapter) {
+    return (typeof adapter.listRowSources === 'function');
+}

package/esm/data_adapters/BaseAdapter/stats.d.ts

@@ -1,10 +1,42 @@
-import { type Observable } from 'rxjs';
-import type { BaseOptions } from './BaseOptions.ts';
-import type { FeatureDensityStats } from './types.ts';
 import type { Feature } from '../../util/simpleFeature.ts';
 import type { RectifiedQuantitativeStats } from '../../util/stats.ts';
 import type { AugmentedRegion as Region } from '../../util/types/index.ts';
+import type { BaseOptions } from './types.ts';
+import type { Observable } from 'rxjs';
+/**
+ * What a caller that will *judge* the density knows and the probe does not: how
+ * wide a window has to be before its count can settle that judgement, and when
+ * a count has settled it. Supplying it turns the ladder below from "grow until
+ * the estimate is precise" into "grow until the verdict is decided", which at
+ * whole-genome zoom is one window instead of thirteen.
+ *
+ * The probe stays ignorant of what the budget means — `plugins/canvas`'s
+ * `densityProbeGate` owns both numbers, so the comparison that refuses a region
+ * lives beside the one the banner re-derives rather than in a second copy here.
+ */
+export interface DensityProbeGate {
+    /** First window to sample: the narrowest one whose count can settle it. */
+    initialInterval: number;
+    /** Whether this many admitted features in this many bp decides the verdict. */
+    settled: (admitted: number, sampledBp: number) => boolean;
+}
+/**
+ * The adapter options a probe forwards, plus the two things only its caller
+ * knows. Named rather than trailing positionals: `BaseOptions` has no required
+ * member, so every one of its slots structurally accepts anything, and an
+ * `admit` handed to the `opts` slot typechecks and then never filters.
+ */
+export interface DensityProbeOptions extends BaseOptions {
+    /**
+     * The caller's feature-admission predicate (config filters, type gates, ...).
+     * See the note on the growth/report asymmetry below.
+     */
+    admit?: (feature: Feature) => boolean;
+    /** Stop as soon as the verdict is decided rather than when it is precise. */
+    gate?: DensityProbeGate;
+}
 export declare function aggregateQuantitativeStats(stats: RectifiedQuantitativeStats[]): RectifiedQuantitativeStats;
-export declare function sampleFeaturesForInterval(region: Region, interval: number, getFeatures: (region: Region, opts?: BaseOptions) => Observable<Feature>, opts?: BaseOptions): Promise<Feature[]>;
-export declare function calculateFeatureDensityStats(region: Region, getFeatures: (region: Region, opts?: BaseOptions) => Observable<Feature>, opts?: BaseOptions): Promise<FeatureDensityStats>;
+export declare function calculateFeatureDensityStats(region: Region, getFeatures: (region: Region, opts?: BaseOptions) => Observable<Feature>, { admit, gate, ...opts }?: DensityProbeOptions): Promise<{
+    featureDensity: number;
+}>;
 export { blankStats } from '../../util/stats.ts';