Custom adapters

import {
  BaseFeatureDataAdapter,
  cachedSetup,
} from '@jbrowse/core/data_adapters/BaseAdapter'
import { fetchAndMaybeUnzip } from '@jbrowse/core/util'
import { openLocation } from '@jbrowse/core/util/io'
import {
  groupLinesByRef,
  makeFeatureIntervalTreeMap,
} from '@jbrowse/core/util/parseLineByLine'
import { ObservableCreate } from '@jbrowse/core/util/rxjs'
import { parseLinesLazy } from 'gff-nostream'

import { Gff3Feature } from '../Gff3Feature.ts'

import type { Gff3AdapterConfig } from './configSchema.ts'
import type { BaseOptions } from '@jbrowse/core/data_adapters/BaseAdapter'
import type { Feature } from '@jbrowse/core/util/simpleFeature'
import type { NoAssemblyRegion } from '@jbrowse/core/util/types'

export default class Gff3Adapter extends BaseFeatureDataAdapter<Gff3AdapterConfig> {
  // the whole file is resident after one load, so the fetch/parse status comes
  // from inside the load itself rather than a label wrapped around it
  private loadData = cachedSetup({
    setup: async (opts: BaseOptions) => {
      const buffer = await fetchAndMaybeUnzip(
        openLocation(this.getConf('gffLocation'), this.pluginManager),
        opts,
      )

      const { headerLines, linesByRef } = groupLinesByRef(
        buffer,
        opts.statusCallback,
      )

      const intervalTreeMap = makeFeatureIntervalTreeMap(
        linesByRef,
        // lines are already split and comment/FASTA-filtered by
        // groupLinesByRef, so feed them straight to parseLinesLazy rather than
        // re-joining and re-splitting through parseStringSync.
        //
        // Lazy because the whole file stays resident for the session: leaving
        // column 9 as text rather than an object per attribute is what keeps
        // that resident set small (8.5x on GENCODE-shaped input), and the
        // render path reads only a handful of attributes anyway — see
        // Gff3Feature.
        //
        // The id the tree entry carries is minted here, beside the feature
        // rather than stamped onto it, so the parsed feature is the library's
        // shape and Gff3Feature serializes it identically for both adapters.
        (lines, refName) =>
          parseLinesLazy(lines).map((feature, i) => ({
            start: feature.start,
            end: feature.end,
            feature,
            uniqueId: `${this.id}-${refName}-${i}`,
          })),
        'Parsing GFF data',
      )

      return { header: headerLines.join('\n'), intervalTreeMap }
    },
  })

  public async getRefNames(opts: BaseOptions = {}) {
    const { intervalTreeMap } = await this.loadData(opts)
    return Object.keys(intervalTreeMap)
  }

  public async getHeader(opts: BaseOptions = {}) {
    const { header } = await this.loadData(opts)
    return header
  }

  public getFeatures(query: NoAssemblyRegion, opts: BaseOptions = {}) {
    // no try/catch: ObservableCreate forwards a rejected callback to
    // observer.error itself
    return ObservableCreate<Feature>(async observer => {
      const { start, end, refName } = query
      const { intervalTreeMap } = await this.loadData(opts)
      const tree = intervalTreeMap[refName]
      if (tree) {
        for (const { feature, uniqueId } of tree(opts.statusCallback).search([
          start,
          end,
        ])) {
          observer.next(new Gff3Feature(feature, uniqueId))
        }
      }
      observer.complete()
    }, opts.signal)
  }
}

public async configure() {
  // the assembly's sequence, unless the config names another one
  return getSequenceSubAdapter(this, this.getConf('sequenceAdapter'))
}

import AdapterType from '@jbrowse/core/pluggableElementTypes/AdapterType'

import configSchema, { normalizeSnapshot } from './configSchema.ts'

import type PluginManager from '@jbrowse/core/PluginManager'

export default function BedGraphAdapterF(pluginManager: PluginManager) {
  pluginManager.addAdapterType(
    () =>
      new AdapterType({
        name: 'BedGraphAdapter',
        displayName: 'BedGraph adapter',
        normalizeSnapshot,
        configSchema,
        getAdapterClass: () =>
          import('./BedGraphAdapter.ts').then(r => r.default),
      }),
  )
}

export const NoAssemblyRegion = types
  .model('NoAssemblyRegion', {
    refName: types.string,
    start: types.number,
    end: types.number,
    reversed: types.optional(types.boolean, false),
  })
  .actions(self => ({
    setRefName(newRefName: string): void {
      self.refName = newRefName
    },
  }))

export const Region = types.compose(
  'Region',
  NoAssemblyRegion,
  types.model({
    assemblyName: types.string,
  }),
)

export interface BaseOptions {
  signal?: AbortSignal
  bpPerPx?: number
  sessionId?: string
  // The single out-of-band status transport. A plain string is an indeterminate
  // phase label; a StatusWithProgress object adds a determinate fraction
  // (`current`/`total` are units-agnostic — bytes for a download, blocks for an
  // unzip, features for a scan). Adapters wrap the raw byte counts from the
  // index reader (@gmod/tabix, @gmod/bam, @gmod/cram) into this object form.
  statusCallback?: StatusCallback
  // What the adapter wants a reader told about this answer that the features
  // cannot show — an index SNP no LD record names, say — appended here and
  // carried back on the fetch's result to the display's corner notice.
  notices?: string[]
  headers?: Record<string, string>
  // Which side of a pairing to answer getRefNames for; single-assembly
  // adapters ignore it.
  assemblyName?: string
  // Which level-of-detail tier to read, for adapters that expose more than one
  // (e.g. PIF's per-row CIGAR fine tier vs its no-CIGAR coarse tier). Absent, the
  // fine tier is served; adapters without tiering ignore it entirely.
  //
  // This is a *resolved* tier, never the user's 'auto' setting: resolving auto
  // needs a zoom, and it happens on the main thread in a display getter that
  // feeds the fetch cache key (`resolveLodTier` in @jbrowse/synteny-core).
  // Resolving it here instead hides a fetch input from that key, which is how
  // a zoom across the threshold came to leave a view holding the wrong tier.
  lodMode?: LodTier
  // The lanes a multi-genome source is asked about, spelled as it spells them.
  // A source that declares its lanes (`headerLanes`) reads only these lanes'
  // files for its header and refNames as it does for its features; absent,
  // every lane.
  haplotypes?: string[]
  // "I read only top-level features", so an adapter may skip work that exists
  // to complete SUBFEATURE lists. A request, not an instruction: only the
  // adapter knows whether its format's top-level set is even a function of the
  // lines it read — `Gff3TabixAdapter` honours it by dropping the redispatch
  // flanks, `GtfTabixAdapter` declines because it synthesizes genes from the
  // transcripts it fetched, and both say why at the call.
  //
  // Set by the pre-fetch density probe, which counts and draws nothing. Not a
  // rendering mode: a caller that will lay features out wants the whole tree.
  topLevelOnly?: boolean
}

export interface ComparativeOptions extends BaseOptions {
  // The assembly on the *other* side of a synteny band, set by the synteny
  // render RPC from the target view. Lets a multi-genome adapter (e.g.
  // MultiGenomePAFAdapter) whose config lists all N assemblies isolate the exact
  // pair a band draws — `assemblyName` alone can't, since one file backs every
  // pair. Pairwise adapters (which already know their pair) ignore it.
  targetAssemblyName?: string
  // This side of the band, when it is not the region's assembly: a region on
  // the anchor of a source that holds every lane inside the anchor's window (a
  // pangenome graph, indexed on its reference alone) asks for this lane and
  // `targetAssemblyName` aligned to each other, read inside that window. The
  // records are on this lane's coordinates. An adapter declares that it
  // answers these with the `lanePairsOnAnchor` capability.
  queryAssemblyName?: string
  // A multi-genome adapter answering a no-target query folds the pairs
  // anchored on one query feature into one feature carrying `mates: [...]`,
  // each mate with its own pairwise `orientation`. Absent, one `mate`-carrying
  // feature per pair.
  mateShape?: 'grouped'
  // Each alignment record comes back cut to the region that fetched it, on both
  // axes, with its alignment string dropped: a liftOver chain spans tens of Mb,
  // and a display fitting a lane to whole records saw 80x the window. Honoured
  // by `ComparativeAdapterBase.getFeaturesInMultipleRegions`, for records that
  // ARE alignments — a gene-pair table's rows are genes and stay whole.
  clipToRegion?: boolean
  // With `clipToRegion`, each clipped record is further cut at every insertion
  // or deletion of this many bp or more, into one record per gap-free run —
  // ids and `syntenyId` suffixed per run — so a display that draws a record as
  // one straight placement draws the runs the alignment actually has rather
  // than a ribbon across a 25 kb indel. Read off the alignment string the clip
  // walks anyway; a record with none is one run.
  splitAtGapBp?: number
  // With `clipToRegion`, each piece keeps its own stretch of the alignment as
  // packed ops in `alignmentOps`, for a display that draws the indels between
  // two lanes.
  keepAlignment?: boolean
}