Usage: Web UI

Web UI usage

  • Select a bundled reference genome or upload a custom reference file (.fa, .fasta, .fa.gz, .fasta.gz).
  • Optionally select or upload a gene annotation GFF3 file.
  • Optionally select or upload a repeat-masking GFF3 file.
  • Optionally upload BAM/BAI files in Settings for raw alignment inspection.
  • Upload a Twitcher CSV file.
  • Use the processed table to inspect events.
  • Click event action buttons to open:
    • Twitcher SVG visualization
    • JBrowse view
    • IGV view, if configured
    • DNA fold comparison
    • Raw BAM slice, if BAM/BAI files are loaded

Visualization controls:

  • Scroll → zoom
  • Drag → pan
  • F → fit
  • Esc → close, where supported

See Reference/annotation data for how to prepare and place reference genome, gene annotation, and repeat-mask files so they appear in the dropdowns.

Filter presets in the web UI

The web UI supports user-created filter presets.

Typical workflow:

  • Add filters using the filter controls.
  • Click Save current filters.
  • Give the preset a name.
  • Reuse the preset later from the preset list/dropdown.
  • Export presets to JSON to share with another user or reuse from the CLI.
  • Import preset JSON files from another user.

Imported presets are added to the preset library. They are not applied automatically. Select an imported preset and apply it explicitly when needed.

The web UI also supports an explicit filter-combination mode:

  • Match all filters (AND) requires every separate filter to match.
  • Match any filter (OR) requires at least one separate filter to match.

For multi-value categorical fields, has_any means OR within one cell and has_all means AND within one cell. For example, gene_names has_all BRCA1,TP53 requires the same observation’s pipe-separated gene_names field to contain both values.

When reproducing a web filter in the CLI, pass the corresponding -A all or -A any option explicitly — see Usage: CLI.

Preset JSON files use frontend-style filter objects, for example:

{
  "schema": "twitcher_filter_presets",
  "version": 1,
  "exportedAt": "2026-06-03T11:02:00.000Z",
  "presets": [
    {
      "id": "preset_1780492344850_ybn021t5lg",
      "name": "Perfect 30bp identity",
      "filters": [
        {
          "col": "identity_30bp_upstream",
          "op": "eq",
          "val": "1"
        },
        {
          "col": "identity_30bp_downstream",
          "op": "eq",
          "val": "1"
        }
      ]
    }
  ]
}

Supported filter operators are:

eq, neq, contains, not_contains, starts_with, ends_with,
gt, lt, gte, lte, empty, notempty, in, notin,
has_any, has_all, has_none,
region_overlaps, region_within, region_contains, region_distance_lt

See “Supported filter operators” in docs/usage-cli.md for the full list with usage notes, including the region and CIGAR operators for columns such as cluster_region, ts_1_4_region, and ts_cigar_ctx.