trix-js
Read UCSC Trix indexes in pure JavaScript
Install
npm install @gmod/trix
Usage
import Trix from '@gmod/trix'
import { RemoteFile } from 'generic-filehandle2'
// generic-filehandle2 also has LocalFile for files on disk
const trix = new Trix(
new RemoteFile('https://jbrowse.org/genomes/GRCh38/trix/hg38.ixx'),
new RemoteFile('https://jbrowse.org/genomes/GRCh38/trix/hg38.ix'),
)
const results = await trix.search('oca')
// => [[term, record], ...]
API
new Trix(ixxFile, ixFile, maxResults?)
ixxFile- filehandle for the.ixxfileixFile- filehandle for the.ixfilemaxResults- most results a search returns, default 20. Also settable afterwards astrix.maxResults
Any object with read(length, position, opts?) resolving to a Uint8Array and
readFile({ encoding: 'utf8' }) resolving to a string works, which includes
every generic-filehandle2 handle. The exported Filehandle type describes it.
trix.search(searchString, opts?)
Prefix-searches the index and resolves to [term, record][], where term is
the indexed word that matched and record is the key it points to. Records are
deduplicated, so two terms hitting the same record yield one result.
searchString- the query. Each whitespace-separated word is prefix-searched and a record is returned when every word finds it, in any order. A word of a multi-word query is read for at most 200 records (ormaxResults, if larger), and one with more cannot rule a record out:b brca2answers with thebrca2recordsopts.signal- anAbortSignalto cancel the underlying reads
Reading over HTTP
A search fetches the .ixx once, then reads the .ix from the matching checkpoint, 256 KiB first
and doubling after that. A typeahead's consecutive keystrokes read nearby offsets, so
typing spd_00 into the 1.7 MB test index makes six reads at three distinct
offsets. With
@gmod/range-cache-filehandle
under both filehandles, four 256 KiB chunks serve all six, and backspacing
needs no new fetch:
import { RemoteFileWithRangeCache } from '@gmod/range-cache-filehandle'
const trix = new Trix(
new RemoteFileWithRangeCache(`${url}.ixx`),
new RemoteFileWithRangeCache(`${url}.ix`),
)
Reference
See the UCSC trix documentation
for the concepts, and ixixx-js for a
JavaScript implementation of the ixIxx command that builds these indexes.
See CONTRIBUTING.md for development and release steps.