Swig — GitHub Pages edition

Swig is a static browser interface for SwiftIG. The SwiftIG C++20 annotation core runs as WebAssembly in a bounded worker pool. Query sequences, locally loaded germline sets, and AIRR results are processed in the browser and are not transmitted by Swig. Selecting an online KI collection downloads only the chosen germline FASTA from its provider.

There is no backend, database, authentication layer, or platform-specific hosting configuration in this repository.

Deploy on GitHub Pages

1. Create an empty GitHub repository and place the contents of this directory at its root.
2. Push it to the repository's main branch.
3. Open Settings → Pages in GitHub.
4. Under Build and deployment, choose GitHub Actions as the source.
5. The included Deploy Swig to GitHub Pages workflow will test, build, and publish the application.

The Vite configuration derives the correct base path from GITHUB_REPOSITORY, so both forms work without editing source:

• https://USERNAME.github.io/ from a USERNAME.github.io repository
• https://USERNAME.github.io/REPOSITORY/ from a normal project repository

Local development

Node.js 22.13 or newer is required.

npm ci
npm run dev

Production verification:

npm test
npm run build
npm run preview

The generated static site is written to dist/. It contains the JavaScript/CSS bundles, swiftig.wasm, the compressed reference pack, and an index.html; it can be served by any ordinary static file host.

User flow

Swig is deliberately split into three views:

1. Overview explains the biological and computational workflow before asking for data.
2. Analyze accepts one or more files (or one pasted dataset), assigns sample/donor/cohort/timepoint metadata, configures species/receptor/locus and a composable locus-by-segment reference matrix, and shows measured read, reference-indexing, annotation, and result-indexing progress. Every setting required to start assignment is on this one page; calibrated numerical controls are grouped under clearly labeled advanced sections.
3. Results downloads AIRR data as TSV, CSV, or JSON Lines; opens a repertoire dashboard; explores the local result index (including Double-D evidence); or runs opt-in post-analysis. These three views use a sticky tab bar and retain independent page-scroll positions when switching. A linked Save session file preserves references, options, sparse double-D evidence, working-set masks, collapse counts, lineage assignments, queries, alignments, trees, and downstream figure state without duplicating the main AIRR table. Loading verifies the selected AIRR TSV by columns, record count, and a streaming 128-bit fingerprint before restoring state. Runs of one to three records open directly at the record detail; larger runs remain paged and filterable.

Analysis parameters → Assignment strategy and Calling profile are orthogonal controls. Assignment strategy selects the V-candidate algorithm: AER (Adaptive Exact Refinement, the default), RIAT-MP (Root-Indexed Allele Tree with bounded multipath propagation), or the fixed-depth standard SwiftIG path. All three use the same selected D/J calling profile. AER retains exact allele alignment and increases V refinement depth only for ambiguous seed rankings. RIAT-MP aligns representative V roots and propagates sparse allele differences without descendant V alignments. A structured J prototype was tested, but the released strategies retain exact J alignment because its small, dataset-dependent speed change did not justify an accuracy and cross-reference-set robustness tradeoff. See BENCHMARK_ASSIGNERS_0.20.0.md.

Calling profile separately offers the ground-truth-optimized default, the agreement-only IgBLAST profile, and an IgBLAST-balanced profile. The balanced profile maximizes agreement subject to both mean first-call and ambiguity-aware V/D/J truth accuracy exceeding IgBLAST on the supplied simulation. It uses the agreement-oriented D/J settings and conditionally removes only five-base-supported D calls in very short V-J spans. None of these profiles is an IgBLAST implementation. Both selected controls are shown with the results, retained in saved sessions, and reused for post-analysis query V/J inference. See BENCHMARK_IGBLAST_PROFILE_0.13.2.md and BENCHMARK_IGBLAST_BALANCED_0.13.3.md.

Selecting a record scrolls directly to its detail panel. A shared coordinate view layers the query, IMGT FWR/CDR intervals, and mapped V/D/J/C hits. The same panel provides the stitched V(D)J alignment, individual query-to-germline alignments, junction calls, and every populated AIRR field. Nucleotide and amino-acid modes share one biologically derived rearrangement frame; frames are not optimized independently per segment. Exact co-optimal calls and sparse near-tied candidates are shown with score, identity, and coordinates. Full alternate alignment strings are not duplicated into every AIRR row.

The repertoire dashboard accumulates summaries while AIRR batches are committed, so opening it does not rescan a million-row output. It includes customizable V/D/J/C or isotype frequency bars, CDR3-length and V-identity distributions, and a V–J pairing bubble matrix. Every rendered figure downloads as a standalone SVG and its plotted values as CSV. Ambiguous comma-separated calls can be counted by first call or split fractionally across co-optimal alleles.

Multi-dataset studies and pipeline mode

The load control accepts multiple FASTA, FASTQ, or AIRR datasets in one run. A directory may also be selected or dragged onto the data panel. For a nested tree, the first directory below the selected root initializes the donor/subject field for every descendant file. A flat directory opens an explicit same-donor versus separate-donor choice. These are metadata initializers only: every sample and donor value remains editable before and after annotation. Each input is represented as an explicit dataset/library with editable biological sample, donor/subject, cohort, timepoint, and compartment/tissue metadata. Technical-replicate files may share a sample ID; longitudinal or compartmental samples may share a donor ID while retaining distinct sample IDs. Swig writes sample_id and subject_id plus swig_dataset_id, swig_cohort, swig_timepoint, swig_compartment, and swig_source_sequence_id on every combined AIRR row. sequence_id is prefixed by the stable dataset ID to prevent collisions between files. Study facets are indexed and available both in the sequence browser and the downstream repertoire-selection stage. These labels remain editable on the Results page after V(D)J assignment. Applying corrected metadata rebuilds only the compact local metadata index and AIRR export overlay, invalidates stale post-analysis state, and leaves annotation untouched; rerunning collapse, lineage assignment, and downstream analyses then uses the corrected sample and donor boundaries.

Project directories are optional and use browser-granted read/write access to a user-selected local directory. Each analysis creates runs/NNN-name/ with an incrementally written AIRR TSV, an inspectable inputs/datasets.tsv study manifest, state/latest.swig-session.json.gz, numbered state checkpoints named for the furthest completed analysis stage, and an append-only JSON Lines event log. A root README.txt documents the layout. Post-analysis changes are debounced into new checkpoints; manually edited alignments and saved tree inputs follow the same session rules as portable session files. Opening an existing project reads swig-project.json, verifies the linked AIRR table, rebuilds the local indexes, and restores the latest analysis state. Portable session download/load remains available when directory access is unsupported or unwanted.

Study presets make the processing boundaries explicit. Exact collapse and every denoising method have an independently selected hard scope (dataset, sample, subject, cohort, or complete study); candidate generation cannot cross that boundary. The default is biological sample, so distinct longitudinal samples are never denoised together. Collapse uses the V–J-trimmed nucleotide sequence by default and independently partitions on the normalized top constant-gene/isotype call. Thus random constant-tail length does not block collapse, while distinct called constant genes do not merge; an explicit toggle can ignore constant assignments. Records without a C call remain in a separate unassigned partition. Lineage assignment has a separate hard scope. Its longitudinal default is donor/subject, allowing one lineage to span timepoints from the same donor while preventing any edge between donors. Technical replicate datasets can collapse together only when the user deliberately gives them the same sample ID. Sequence-directed expansion inherits the lineage scope, and SHM plots can be stratified by sample, donor, cohort, or timepoint.

Pipeline mode is configured before annotation. It can run annotation → optional repertoire allele pooling/reassignment → collapse/denoise → CHMMAIRRa exclusion → repertoire selection → lineage assignment → SHM → lineage-aware missing-allele hints without intermediate clicks. Pooling is fitted on the complete assigned input first, so a reassigned V/D/J call can correctly affect rearrangement-key collapse and every later call-dependent partition. Subsequent stages commit the same cumulative typed working-set mask used by interactive post-analysis. Collapse method/scope/unresolved-record behavior, CHMMAIRRa segment/model/MSA/threshold, study/call/CDR3/QC filters, allele-pooling boundary/segments/leakage/reassignment policy, lineage scope/identity/call policy, and diagnostics are selected up front. Allele reassignment can apply the posterior best match to every modeled record or retain the original AIRR call unless its best match reaches a configurable confidence threshold (80% by default). Targeted queries, individual lineage alignments, and trees remain on-demand because they require a selected target. The complete manifest, pipeline configuration, typed masks, collapse multiplicities, allele posterior vectors, and lineage assignments are retained by Save session.

Post-analysis

The Post-analysis results tab is opt-in and keeps the full AIRR rows in chunked storage. Its step cards are independently collapsible. Applying a stage collapses it and opens the next stage, while a pulsing next-action button marks the default route through collapse, chimera exclusion, selection, lineage assignment, and diagnostics. It provides:

• Explicit cumulative working set: deduplication, CHMMAIRRa exclusion, and a composable repertoire-selection stage are separately applyable. The selection stage combines dataset/sample/donor/cohort/timepoint, sequence ID, locus, V/D1/D2/J/C/isotype calls, CDR3 nucleotide or amino-acid substrings, literal/IUPAC/regular-expression motifs, productivity/completeness/frame/stop/D/CDR3 states, CDR3 lengths, V/J identities, V mutation fraction, and double-D positive/negative status. Fields commit on Enter or blur; a scan happens only when Preview count is pressed, and the retained/excluded count must then be explicitly applied. Lineage assignment, SHM, reference diagnostics, initial sequence queries, and single-linkage expansion consume the same current working set. Positive double-D selection uses the sparse evidence index rather than scanning unrelated AIRR rows. Reset restores all assigned records; the underlying AIRR result is not deleted.
• Repertoire-level allele pooling: an optional first post-assignment stage refines ambiguous calls against an overcomplete reference set before collapse or filtering. Literal co-optimal calls begin equally; retained alternatives and bounded database neighbours form sparse evidence rows. Same-length substitution neighbours receive SHM-adaptive evidence odds min(cap, zero-SHM floor + sensitivity × mu/[3(1-mu)]); indel neighbours receive baseline leakage only. Independent variational Dirichlet mixtures are fitted by donor/subject (default), locus, and segment without allocating a dense reads-by-reference matrix. All samples for one donor share the default fit; cross-donor cohort/study pooling is an explicit override. V and J are enabled by default; D is experimental. An interactive reference-kernel inspector shows how tuning changes every non-primary candidate probability beside a compact nucleotide/difference-highlighted alignment. Fitted pools include paired hard-count bars: each modeled record contributes its complete configured weight to its local-evidence best allele before pooling and to the policy-selected allele afterward. Filters expose changed counts and alleles that vanish under the selected policy; complete count data and the figure export as CSV and SVG. These are hard argmax projections, not Dirichlet posterior means or summed variational responsibilities. Fitting never changes calls by itself. The user can apply the posterior MAP to every modeled record or apply it only above a confidence gate (80% by default); below the gate, the immutable original AIRR call is retained. Applying or changing the upstream policy clears stale downstream partitions, while later stages preserve the selected calls. Reset restores all original calls. Model, per-record sidecar, provenance-preserving refined AIRR, and current-policy surviving-reference FASTA exports are available. The complete method is documented in public/REPERTOIRE_ALLELE_REFINEMENT.md.
• Exact collapse or denoising with abundance: method A performs exact deduplication by full input sequence, VDJ-aligned sequence (the default), locus + CDR3 nucleotide, or locus + V/J calls + CDR3. All four methods keep different normalized constant-gene/isotype calls in separate partitions by default without adding constant-tail bases or length to the comparison key; this policy can be disabled explicitly. Method B reproduces FAD's corrected 6-mer distance and abundance/Poisson template rule, including the published nearest-centroid assignment, while partitioning by locus/V/J and replacing dense all-pairs scans with a complete radius index plus an exact VP-tree nearest-neighbor index. Method C is a conservative experimental alternative: it generates exact Hamming candidates with a d+1 block index, applies a sequence-specific Poisson error model, retains isolated singletons, and never forces a read onto a distant centroid. Method D extends C to one- or two-edit Levenshtein neighborhoods: a complete length-aware d+1 segment join generates candidates, an allocation-bounded banded dynamic program reports the exact substitution/insertion/deletion path, low-abundance indel paths use a configurable parent:child abundance ratio, and substitution-only paths retain C's Poisson rule. Method D never performs a distant-centroid assignment and reports indel and substitution merges separately. Call resolution, ambiguity handling, error rate, alpha, parent abundance, ambiguous-base policy, and method-specific radii are configurable. Records without a usable selected key (exact collapse) or without both a trimmed sequence and V/J partition (denoising) are discarded from the downstream representative set by default; an adjacent control can retain them unchanged instead. The result card reports the affected count before the user applies the working-set filter. Trimmed VDJ sequence is streamed into a two-bit chunked arena; temporary profiles exist for one V/J/C partition at a time. The UI reports streamed ingestion, indexed-variant resolution, and representative materialization as separate progress stages; the latter two are emitted directly by the denoising worker. Existing and newly collapsed duplicate_count values are summed and propagated into lineage weights, exports, and phylogeny bubbles.
• CHMMAIRRa: a browser implementation of the CHMMera structured HMM can be run after assignment on V (default) or J. It runs only on the current cumulative working set, and reports both its working-set input and the count excluded upstream. IG defaults to the per-reference Baum–Welch model; TCR defaults to the discretized Bayesian model with a fixed 0.005 mutation-rate state. The default posterior threshold is 0.95, chimera prior 0.05, and minimum distance-from-reference is one. The exact V or J FASTA used for initial assignment can be aligned with Kalign WASM, or an equal-length aligned FASTA MSA can be loaded from file. CHMMAIRRa has no separate allele-exclusion control: allele inclusion is defined once in the initial assignment reference matrix. Clicking a high-posterior record reruns a detailed Viterbi trace on demand and opens an SVG-downloadable alignment with standard nucleotide coloring or an identity-only highlighter: red means query matches parent A only, blue parent B only, and gray both/neither. Tile colors never use the Viterbi state path; the inferred breakpoint remains a dashed labeled line. Columns that are gaps in the query and both displayed parents are hidden only in the visualization. Results export as a separate TSV rather than mutating the original assignment table.
• Lineage assignment: records are partitioned by locus, compatible V/J assignments, and exact CDR3 nucleotide length. Default gene-level ambiguity handling accepts any overlapping call, then performs single-linkage clustering at 85% CDR3 nucleotide identity. A pigeonhole d+1 block index generates candidates, exact normalized Hamming distance verifies every retained edge, and union–find constructs components. Call resolution, ambiguity policy, productivity, identity, and the pathological-bucket comparison cap are configurable. The lineage module remains open after assignment. Its table filters by sample breadth, presence in any/all/only selected samples, locus, V/J text, abundance, unique members, CDR3 length, and SHM thresholds; headers sort by these fields and by SHM mean, maximum, or upper 95% quantile. Assignments can be exported as an AIRR table with clone_id; records excluded by the selected criteria retain an empty value.
• Sequence- and lineage-directed retrieval: the final post-analysis module searches one or more CDR3 nucleotide, CDR3 amino-acid, or full VDJ-aligned queries by exact match, substring, bounded Hamming distance, banded edit distance, or a compact 7-mer MinHash estimate. Constraints can be manual or inferred independently for every complete nucleotide seed by running the same SwiftIG caller with the run's composed references, identity floor, strand setting, and ambiguity-aware V/J output; inferred constraints are displayed and remain overrideable. Single-linkage expand set starts from the current sequence matches and follows CDR3 nucleotide edges to a fixed point or a user-visible result cap. After lineage assignment, lineage mode ranks every lineage by its best match to any member sequence and opens a selected hit directly in the lineage workbench.
• Lineage figures, neighbours, and merges: abundance distribution, largest components, and V/J use are rendered as customizable SVG figures with CSV data exports. A selected lineage can search separate assigned lineages by exact V/J-aware CDR3 distance below the clustering cutoff, by inferred-lineage-germline identity, or by either route. Germline search uses a compact per-lineage MinHash only as a shortlist: every reported hit is re-verified against a multi-member inferred lineage germline, with N treated as unknown. Candidates can be selected and viewed/aligned/treed together without changing assignments, or explicitly merged. A merge adds swig_merged_lineage_id; the original AIRR clone_id is retained unchanged and both are saved/exported.
• SHM analysis: V nucleotide mutation counts/rates, amino-acid replacement counts/rates, synonymous codons, CDR1/2 mutation rates, and framework mutation rates can be calculated on the selected population. Imported or collapsed duplicate_count weights every repertoire summary. Publication-oriented SVG views include weighted lineage violins, a repertoire distribution, lineage abundance-versus-SHM bubbles, V-gene summaries, optional strata, and a lineage-by-sample heatmap using mean, median, maximum, or upper 95% quantile. Sample order can be edited manually or sorted by input order, timepoint, compartment, or sample ID and is retained in sessions. Record and plotted data export as TSV, CSV, or JSON Lines. Plot/session samples are bounded globally and per lineage–sample cell while scalar input/abundance counts cover the complete selected set.
• Possible missing-V warning: this high-specificity diagnostic is intentionally narrower than IgDiscover/TIgGER/partis genotype inference and never uses records as independent evidence. Pass 1 chooses one lowest-SHM representative per assigned lineage and proposes substitution sets only when the complete set co-occurs on the same molecule across multiple lineages. Pass 2 streams every retained member of those lineages: a parent-reference nucleotide at any proposed site vetoes that lineage, as does a third nucleotide state or inconsistent V assignment. Candidates must retain configurable support, joint coverage, fraction, low-SHM and screening-tail evidence; span distinct CDR3 nucleotide sequences, CDR3 lengths, and J calls; include near-germline representatives with few other V mismatches; and keep third nucleotide states below a configurable cross-lineage fraction (2% by default). AIRR v_germline_start supplies the absolute V coordinate, while . and - remain alignment gaps. Exact known-reference sequences are suppressed and AID WRCY/RGYW contexts are flagged. Output includes an SVG, CSV/TSV/JSON Lines evidence tables with supporting lineage IDs and veto counts, all-candidate FASTA, selected-candidate FASTA, and a downloadable augmented V reference made from explicitly selected candidates. The augmented copy retains every original record; a selected candidate inherits SWIGMETA only from its exact parent and receives explicit candidate/parent/substitution header tags. The completed run is never silently re-annotated, and selection is retained in saved sessions. Saved diagnostics from the older one-pass algorithm are invalidated on load and must be rerun.
• Double-D explorer: supported VDDJ calls are explored within the Sequences view, beside the ordinary record filters, rather than in a redundant top-level results tab. The explorer retains D1/D2/score/span filters, D1→D2 pair summaries, a sparse evidence table, and clickable full V–D1–D2–J nucleotide/amino-acid alignments. “Only double-D positive” is also a prominent indexed sequence filter and a repertoire-selection criterion used before lineage assignment. After assignment, the lineage explorer can independently select lineages containing any, all, or no Double-D-positive active members and reports both positive unique members and multiplicity-weighted abundance.
• On-demand alignment and phylogeny: the default is the reference-anchored quick view built from existing AIRR alignment coordinates; Kalign 3.3.1 WASM nucleotide and codon-aware modes remain explicit alternatives. Large lineage member lists use a deterministic bounded reservoir rather than the first records in file order, and combined-lineage views then sample round-robin across original lineages. This avoids allowing an early dataset or large source lineage to crowd longitudinal samples/neighbours out of the working MSA. The compact alignment preview has no inter-sequence vertical padding. Nucleotide and amino-acid views use standard Alivibe palettes. Germline/UCA construction defaults to the single loaded member with the best equal-weight matched-region V and J identity, with deterministic combined-identity, coverage, and AIRR-order tie-breaks; that member supplies the germline template and trimming endpoints. For a lineage containing safely projectable Double-D evidence, the closest-member candidates are restricted to those VDDJ-aware rows: the unchanged baseline single-D junction is cleared, D1 and D2 are projected through the gapped combined query coordinates, and NP1/NP2/NP3 remain N. An explicit alternative uses equal-weight member voting over AIRR-anchored germline columns (80% known-base agreement and 20% endpoint coverage); VDDJ lineages vote only across safely projected Double-D rows so a baseline single-D composite cannot erase D2. The root panel reports whether V–D1–D2–J construction succeeded and warns rather than silently partially projecting incomplete imported sidecars. In both modes unresolved junction N remains unknown for tree parsimony and a separate comparison UCA may fill it from the selected member or supported member consensus. The current alignment opens in a pinned, bundled Alivibe copy for manual/codon-preserving correction. A versioned same-origin bridge forces Alivibe into NT mode and snapshots the complete ordered state.viewSequences records used by its NT canvas and full NT FASTA export; the system clipboard is never used. Each editor is bound to its originating lineage set and alignment fingerprint, and a stale editor cannot overwrite a later alignment. The initial AA phase is carried from the selected lineage-root member's AIRR sequence_frame, v_sequence_start, and V-reference padding; nucleotide Kalign reprojects that same anchor into output columns, while codon-projected alignment starts at column one. Gap patterns are only a fallback for legacy saved inputs and never override an annotated newly generated alignment. The Alivibe frame selector remains editable in both nucleotide and amino-acid modes, and a user-selected phase is returned and saved separately from nucleotide characters. Corrected FASTA without separate frame metadata retains the current explicit phase. Only a complete --- triplet in the active phase renders as an AA gap; mixed base/gap codons remain X. Swig accepts deletion of bad biological rows, alignment columns, and nucleotide characters while rejecting added/renamed rows, substitutions, and reordered content; the N-masked germline must remain. Manually corrected alignments, including deletions and their AA frame, are saved per original-lineage set in session files and restored on load; reproducible unedited alignments are omitted unless required as the exact input of a saved tree. Before every request, the complete current MSA is explicitly rewritten into the WASM filesystem; FastTree 2.1.11's double-precision build then consumes those exact bytes. The UI records the command, dimensions, source and fingerprint, and downloads both the named MSA and exact numeric-label input. Newick serialization writes an explicit length for every non-root edge, including :0 for zero-length terminal branches. Germline rerooting places the root exactly at the N-masked germline (0 root-edge length) and assigns the complete original connecting length to the ingroup side, preserving pairwise patristic distances. The complete germline-rooted FastTree resolution is shown by default; internal branches at or below 1e-8 substitutions/site can optionally be collapsed because they are at the FastTreeDbl numerical floor. The untouched raw FastTree Newick also remains inspectable and downloadable. Phylogram mode preserves retained branch lengths, and topology-only cladogram mode is explicit.
• Coordinated tree/alignment workbench: the exact named FastTree input is drawn to the right of its tree with leaf rows vertically locked and dotted tip-to-sequence connectors. Alignment rows have no vertical inter-sequence padding. Fractional substitution/site branch lengths are normalized to the observed root-to-tip maximum, so the deepest tip uses the complete tree span. Width and tip-spacing sliders reach zero without a hidden geometry floor; Newick order, large-clade-first ladderization, and small-clade-first ladderization are selectable. Tip bubble area reflects duplicate_count. Tip bubbles can be colored by sample, original lineage, isotype, constant gene, donor, cohort, timepoint, compartment, V gene, J gene, productivity, or double-D status, or drawn uniformly. Sample mode uses the centrally editable Results-page palette; other categorical modes use stable deterministic colors. The active category legend is embedded in the exported SVG as well as shown in the interface. Users can select FWR/CDR presets, arbitrary alignment or Kabat ranges, or only motif-matched columns; every non-contiguous displayed run receives a half-residue blank separator. Custom-region and motif drafts are applied on Enter or blur so keystrokes do not rebuild the SVG. Cells can use standard nucleotide/amino-acid palettes or motif colors; tree width, row height, and residue width are independently scalable; the complete composition can enter full screen and export as one SVG.
• Ancestral mutation mapping and numbering: an equal-cost nucleotide parsimony pass reconstructs internal nodes on demand. Known reconstructed-germline bases constrain the UCA; germline N is treated as an unknown A/C/G/T state and inferred from descendants, while gaps remain an explicit indel state. Branch labels follow the active viewer mode: nucleotide mode shows nucleotide changes, while amino-acid mode compares reconstructed parent/child codons, emits one amino-acid replacement per changed codon, and omits every synonymous nucleotide change and unresolved X codon. Labels can be toggled, are restricted to the displayed region, and are centered along the branches where changes occur. The user controls both the number shown before a +N summary and the mutation font size; both settings are serialized into SVG export. IG amino-acid views can switch from alignment coordinates to Kabat numbering computed locally with the MIT-licensed Immunum WASM engine; multiple lineage members vote on each aligned Kabat column. A terminal partial codon or stop codon produces a visible reliability warning rather than disabling Kabat for the complete alignment. Kabat is not offered for TCR chains because the scheme is defined for IGH/IGK/IGL.

Kalign and FastTree are provided through the bioWASM Aioli runtime. Their program modules are downloaded on first use. Sequence data are mounted in the worker's browser-local virtual filesystem and are not transmitted to bioWASM.

Large-run behavior

• Input is read incrementally from File.stream(). Gzip is decompressed through DecompressionStream; FASTA, multiline FASTQ, and AIRR rows are parsed without making a decompressed whole-file string.
• An optional collapsed FASTQ-QC stage computes each read's expected errors as sum(10^(-Q/10)) (default maximum 0.01). A configurable 3′ terminal-window trim may run first; the retained length is checked and expected errors are evaluated only on retained bases. FASTA and AIRR inputs pass through this stage unchanged with an explicit format notice. Quality filtering occurs before random reservoir subsampling and before any WASM assignment batch is allocated.
• Optional seeded random subsampling uses exact reservoir sampling. It scans the complete stream, retains only k records in memory, preserves their original order, and annotates/outputs only that uniform sample.
• A coordinator schedules one active batch per independent WASM worker. Results may compute out of order but are committed in input order. Compute may run one batch ahead of storage, with a strict high-water mark of twice the worker count—not the number of input records. Multi-dataset runs process datasets sequentially while giving each dataset the complete configured worker pool; this avoids multiplying worker count and memory by the number of loaded files.
• Main annotation, result finalization, CHMMAIRRa, denoising, lineage/query operations, MSA, and FastTree acquire a same-origin active-run Web Lock when the browser provides the API. This keeps Chrome Energy Saver from freezing the browsing-context group merely because the tab is hidden and prevents two Swig tabs from saturating the same machine simultaneously. Batch scan yields use scheduler.yield() or MessageChannel, not throttled background timers. The UI reports whether the lock is held. A browser/operating system can still discard a page under exceptional memory pressure, so unattended runs should use Chrome's site exception if that behavior must be ruled out.
• In Auto mode, known-large runs offer a save location before annotation and write the AIRR TSV incrementally while computation is running. Otherwise AIRR batches are gzip-compressed in IndexedDB. A service worker exposes those batches as a streaming TSV download without assembling a full result Blob. On Chromium/HTTPS, converted CSV/JSONL and post-analysis tables stream through the File System Access API; small-result Blob fallback is used when that API is unavailable.
• The table renders 50 records at a time. Exact locus, productivity, V/D/J/C allele, and isotype filters use browser-local indexes; ID, CDR3 substring, identity, length, and QC filters scan the narrowed candidate set on demand and are cancellable.
• Additional filters cover V/D/J/C identity floors, CDR3 amino-acid length, D/CDR3 presence, supported double-D evidence, receptor locus, and productivity.
• Full alignment rows are retrieved only after a record is opened.
• Post-analysis scans chunked AIRR rows into a dedicated worker and retains compact sequence fingerprints, call/CDR3 keys, and typed assignment arrays—not full AIRR rows or a million-row DOM. Denoising adds a two-bit sequence arena and processes one V/J partition's neighbor profiles at a time. The 32 MB-per-million VDJ MinHash array is allocated only if full VDJ sketch search is requested.
• CHMMAIRRa uses a bounded batch per worker and stores posterior/DFR outputs in 6 bytes per input record plus a bounded high-posterior list. Its TSV writer rescans sequence IDs batchwise.
• Lineage alignment and trees are never precomputed repertoire-wide. At most the first 500 records of an opened lineage are retrieved, and the alignment limit defaults to 200.
• Every input still receives one lightweight IndexedDB record for filtering. Full AIRR rows and alignments remain in chunked storage and are read only for the selected query.
• Direct-to-disk output uses the File System Access API (Chromium-family browsers in a secure context). Other modern browsers use compressed IndexedDB plus the streaming download service worker. A conventional Blob is only the small-result fallback.

Phylogenetic UCA inference

The HMM-source viewer collapses route/register duplicates of the same allele into nucleotide-mixture rows, color-codes segment classes, keeps labels visible during horizontal scrolling, and reports numeric source/nucleotide masses on hover. Best-path mode retains spatial V→NT→D-block→NT→J rows. Marginalized mode sums all non-template mass into one NT mixture at the top, then shows V, D, and J allele rows ordered by posterior-mass location. Both the complete track canvas and the exact currently scrolled track viewport export as SVG. The Additional-D control accepts 0 through 1, and one reset button restores all UCA settings.

After preparing or manually correcting a lineage alignment, the workbench can run an optional fixed-tree empirical-Bayes UCA analysis. It removes the N-masked germline guide, infers a double-precision FastTree from observed rows only, and computes directed Felsenstein messages on every edge. The default cheap starting screen evaluates multiple interior points per edge with an independent nucleotide mixture over the fixed V/J allele projections; selected edges and every refinement step are then recomputed under the complete recombination HMM. Setting the full-HMM edge count to zero searches every edge. A tree map shows every discrete branch-interior point retained for marginalization, its UCA pendant length, raw ΔLL, exp(ΔLL) color, and posterior weight. A factorized V–N–D–N–J HMM marginalizes broad member-level V/J hypothesis unions, every active D, uncertain trimming, non-templated bases, and up to three D segments by default. It reports a joint Viterbi UCA/recombination path, marginal nucleotide probabilities, exact 125-state codon posteriors, exact amino-acid marginals, local placement uncertainty, and a UCA-rooted tree. CDR1/CDR2/CDR3 bands appear below the logo numbering. The codon calculation preserves dependence induced by shared germline candidates and recombination paths; it does not multiply site marginals.

The character process is site-independent: automatic mode uses nucleotide GTR4 unless an internal tip gap occurs. Leading and trailing gap padding is always missing sequence coverage; only gaps between a tip's first and last observed nucleotide become explicit fifth-state observations under the A/C/G/T/gap GTR5 approximation. Columns missing at every tip are excluded from FastTree fitting but restored as missing data for the full-width posterior, preserving codon phase. It does not use a 5-mer/context likelihood. Complete algorithm, parameter, gap-state, complexity, export, and limitation details are in public/PHYLO_UCA_INFERENCE.md. The panel includes a fixed-height, non-entropy-scaled posterior frequency logo with nucleotide, exact codon, and exact amino-acid views plus SVG export. It also exports UCA FASTA, nucleotide/codon posterior TSVs, placed Newick, complete JSON, and the standard tree-viewer SVG; Save session retains the result against the exact lineage/alignment/frame fingerprint.

Supported biology and formats

• FASTA, FASTQ, and AIRR Rearrangement TSV input, optionally gzip-compressed
• AIRR Rearrangement TSV, CSV, and JSON Lines table output
• aligned FASTA, Clustal, relaxed PHYLIP, Stockholm, and NEXUS alignment output; Newick and NEXUS tree output
• BCR: IGH, IGK, and IGL
• TCR: TRA, TRB, TRD, and TRG
• D-segment search for IGH, TRB, and TRD
• optional double-D/VDDJ evidence screening for IGH, TRB, and TRD: off by default; either all eligible junctions or only inter-V/J spans at or above a configurable threshold
• independent V, D, J, and optional C source selection or local FASTA loading for every active locus
• constant-region calls require at least 30 aligned nucleotides; the derived isotype AIRR extension additionally requires at least 65% identity
• 64 species/strain reference sets derived from the IMGT-gapped all-species file in IMGT/GENE-DB release 202632-7

Swig runs SwiftIG, not IgBLAST. Receptor behavior is determined from the selected IG/TR locus and locus-bearing gene identifiers rather than an IgBLAST ig_seqtype setting. The bundled pack retains light-chain C-REGION records and assembles IMGT's exon-level IGH/TCR constant records into one secreted/coding reference per allele; membrane-only and UTR exons are not mixed into that path. A matching C FASTA can still be supplied independently.

The double-D screen is deliberately a separate opt-in pass. With screening off, the legacy swig_annotate WebAssembly entry point is used. With it on, the baseline V(D)J annotation and normal AIRR TSV remain byte-for-byte the same; a sparse sidecar records supported ordered D1/D2 calls. The default evidence rule requires an exact 11-nt seed from each D, extends each seed independently, requires non-overlap and a configurable pair-score improvement over the best supported single D, and rejects pairs explainable by the IgScout-style single-D pseudo-tandem Δ-distance test (5-nt trim; distance ≤3 by default). Screening can run on every eligible D-bearing junction or only when the baseline V-end/J-start interval is long. The separate TSV uses AIRR 2 fields such as d2_call, D2 coordinates/CIGAR/alignment, and np3, plus swig_* evidence fields and an AIRR-row ordinal. Interactive detail and alignment views show D1 and D2 while labeling the unchanged baseline composite.

Germline databases and preprocessing

The Database selector uses a compatible KI collection by default where one is available: KIARVA for human IGH, the KI human TCR collection for human TR loci, and KIMDB for rhesus or cynomolgus macaque IGH. IMGT/GENE-DB is the default elsewhere and remains the fallback for loci or segments absent from a partial KI collection. Incompatible entries are not shown; for example, no KI entry is shown for cat. Applying a database is a preset operation, not an all-or-nothing switch: it changes only the locus/segment cells supplied by that resource and leaves every other cell unchanged. The compatible alternatives are:

Collection	Scope	Delivery
KIARVA	human IGH V/D/J	fetched from the KIARVA API when selected; KIARVA data are published under CC BY-NC 4.0
KI human TCR database	human TRA, TRB, TRD, and TRG V/D/J as applicable	fetched from the publisher's HTTPS FASTA endpoint when selected
KIMDB 1.1	rhesus and cynomolgus macaque IGH V/D/J	bundled unchanged because the publisher endpoint is HTTP-only and cannot be fetched by an HTTPS page

The reference matrix has loci as rows and V/D/J/C as columns. Every applicable cell independently selects IMGT, a compatible published database, or a local FASTA. Thus a combined BCR run can use KIARVA for IGH V/D/J while retaining IMGT for IGK/IGL, and a single cell such as IGH J can then be replaced again without changing IGH V or D. Each cell also has a visible Exclude alleles… action. Its searchable browser removes exact FASTA identifiers only from that locus/segment before the composed references are compiled and indexed for initial SwiftIG assignment; removed alleles cannot become primary or alternative calls. Exclusion counts appear in the cell and run summary, changing a cell's source clears that cell's exclusions, and session/project state records both the resulting exact FASTA and the exclusion map. Custom and remotely loaded FASTA use the same in-browser preprocessing worker. The preprocessor:

• validates identifiers, locus/segment consistency, nucleotide symbols, duplicate names, and embedded SWIGMETA coordinates;
• reads exact FWR/CDR boundaries from an IMGT-gapped V record when present and anchors FWR3 on the nearest frame-consistent conserved V cysteine, accommodating species-specific IMGT gap counts;
• otherwise aligns each V allele to a fully delineated, locus-matched relative, beginning with the selected species and progressively broadening the taxonomic search, then projects the IMGT intervals through that nucleotide alignment and re-verifies the mapped V-cysteine anchor;
• resolves J frame and CDR3-stop metadata by homologous anchor transfer when possible and re-verifies the mapped conserved F/W–G motif in the submitted sequence;
• ignores functional, ORF, and pseudogene labels when selecting coordinate donors;
• leaves a record without region or junction metadata if it does not span the necessary interval or the mapped anchor cannot be verified. It does not substitute a motif-derived or fixed-coordinate default silently.

No BLAST database files or IgBLAST edit_imgt_file.pl/makeblastdb step is required because SwiftIG indexes normalized FASTA directly. The IMGT gap layout is used only to derive coordinate metadata before the sequence is ungapped for SwiftIG's index.

Rebuild the WebAssembly core

Install WASI SDK 25 or a compatible newer SDK, then run:

WASI_SDK=/path/to/wasi-sdk npm run build:wasm
npm test

The build uses -O3, LTO, WebAssembly SIMD, bulk-memory operations, section garbage collection, and a pinned Binaryen wasm-opt -O4 convergence pass. RIAT-MP is compiled with three selected V-root alignments, at most two root tracebacks within four raw-score units, and a 1,024-state traceback cap. The GitHub Pages workflow downloads the pinned SDK and rebuilds this optimized core before testing and publishing. The vendored SwiftIG source and browser ABI are under wasm/. The upstream MIT license is retained in LICENSE and wasm/LICENSE.swiftig.

Performance and stress verification

The supplied 100,000-record simulated human IGH tuning benchmark, exact scoring definitions, selected D/J parameters, ambiguity rates, IgBLAST comparison, input hashes, and limitations are recorded in BENCHMARK_DJ_0.13.1.md. Those values are tuning-set results, not a substitute for evaluation on independent data.

The independently selectable IgBLAST-agreement profile and its agreement-only parameter search are reported in BENCHMARK_IGBLAST_PROFILE_0.13.2.md. Truth columns were excluded from that search; the report still uses the same supplied data and is not held-out validation.

The constrained IgBLAST-balanced profile is reported in BENCHMARK_IGBLAST_BALANCED_0.13.3.md. Its small truth advantage and high agreement are tuning-set measurements, not held-out validation.

The AER, RIAT-MP, fixed-depth standard, and structured-J experiments are reported in BENCHMARK_ASSIGNERS_0.20.0.md. The report includes V/D/J and joint first-pick and ambiguity-aware scores against truth and IgBLAST, deterministic sample selection, throughput, and the reason exact J was retained.

npm run benchmark:50k runs 50,000 annotations through the same one-batch-per-worker scheduling bound used by the browser. The deliberately heavy profile uses all full-length human IGH references, both strands, complete AIRR formatting and transfer. This is not the same workload as SwiftIG's published 5,242 reads/s native benchmark, which mixes short and full IGH/IGK/IGL reads and uses 396 NCBI alleles; do not treat the two rates as a Web/native ratio.

npm run benchmark:denoise-50k runs 50,000 synthetic assigned reads through the FAD-compatible streaming, V/J partition, exact-radius, and nearest-centroid path and reports throughput, verified candidate comparisons, and V8 heap delta.

npm run benchmark:indel-denoise-50k runs the same 50,000-record shape through method D with one-base insertion children. In the final verification run it retained 1,000 representatives across 100 V/J partitions, verified 1,000 candidates in 246 ms (about 203,000 input records/s), and increased measured V8 heap use by 8 MiB. This synthetic benchmark is intended to detect indexing or memory regressions, not to estimate biological correction accuracy; elapsed time and garbage-collector-dependent heap deltas vary between runs.

The normal test suite also pushes 50,000 gzip FASTA records through the incremental parser and 50,000 synthetic AIRR records through chunk compression, IndexedDB indexing, filtering, detail retrieval, and batchwise export. It asserts a 1,000-record parser high-water mark. Scaling from 50,000 to one million increases durable IndexedDB/file data and lightweight index rows, but not the number of resident query or AIRR batches.

Update the IMGT reference pack

After downloading the official IMGT-gapped all-species IMGT/GENE-DB FASTA:

npm run build:references -- \
  /path/to/IMGTGENEDB-ReferenceSequences.fasta \
  RELEASE_ID \
  YYYY-MM-DD \
  public/references/imgt-RELEASE_ID.json.gz

Update the filename in src/reference-pack.ts when the release ID changes. The bundled file is a compact, segment-organized derivative; IMGT attribution and terms apply.

Scientific scope

SwiftIG/Swig 0.25.2 is research software. Benchmark study-critical calls and post-analysis thresholds against an independently validated workflow for the organism, assay, read length, somatic-hypermutation regime, and germline set relevant to the analysis. The AER and RIAT-MP comparisons use the supplied simulated human-IGH tuning data and are not held-out validation. The 85% CDR3 identity lineage threshold, neighbour-search/merge criteria, method D's abundance ratio, double-D evidence defaults, calling-profile evidence boundaries, FASTQ expected-error/trim thresholds, missing-allele evidence thresholds, phylogenetic-UCA priors, and repertoire-level allele-pooling evidence kernel are starting values, not universal biological constants. The allele-pooling result estimates expressed rearrangement usage rather than genomic genotype frequency; its 1% zero-SHM neighbour floor is an explicit assignment-evidence leakage parameter, not a sequencing-error estimate. The hurdle model's active state means detectable expressed-repertoire use, and its inclusion probability is a fast conditional active-set approximation rather than an exhaustive genotype posterior. The phylogenetic UCA implementation fixes the observed tree, uses a context-averaged nucleotide model, treats terminal tip gaps as missing coverage, and treats only internal gaps as a fifth fixed-alignment character when required; important UCA sequences should be checked for sensitivity to alignment and prior choices. Public germline coverage is not available for every animal species; arbitrary or partial new sets can be supplied with the per-segment local-file controls.