API

MeanderViz can be driven by scripts on the page, by links, from a page that embeds it, over a REST API, and from the command line. The web app itself sends nothing anywhere; the REST API is a separate service at meanderviz.org that deletes what it receives after an hour. The same text is in API.md in the downloadable package.

JavaScript: window.MeanderViz

Available on any page that includes MeanderViz, for example in the browser console (F12). Methods that load or navigate return a promise of the current state (see state()).

await MeanderViz.example("sv");
await MeanderViz.goto("chr1:14,200,000-14,650,000");
await MeanderViz.view({ curve: "moore", dim: 3 });
console.table(MeanderViz.findings());
await MeanderViz.export("svg", { content: "figure", width: 3000 });

Events

MeanderViz.on(type, callback) and off. The callback receives a CustomEvent whose detail is the state (or the finding).

Links (URL parameters)

Query parameters open the app in a given state, for example index.html?example=asm&locus=ctg2:20000-24000&mode=syn. MeanderViz.link() builds such a link for the current view.

Embedding with postMessage

Put MeanderViz in an <iframe> and send commands. Every cmd is a method of MeanderViz; the reply is { meanderviz: { id, result } } or { meanderviz: { id, error } }. MeanderViz also posts the load, selection and finding events to its parent as { meanderviz: { event, detail } }.

const frame = document.querySelector("iframe");
frame.contentWindow.postMessage({ meanderviz: { id: 1, cmd: "example", args: ["variants"] } }, "*");
frame.contentWindow.postMessage({ meanderviz: { id: 2, cmd: "goto", args: ["sars-cov-2_variants:23000-24000"] } }, "*");
window.addEventListener("message", (e) => { if (e.data.meanderviz) console.log(e.data.meanderviz); });

REST API

The same analyses as a web service, at https://meanderviz.org/api/v1 (self-hosted: node server/server.js). No login. Files are uploaded, referenced by URL, or taken from the packaged examples; analyses run as jobs; uploaded files and results are deleted after one hour. The full description is at /api/v1/openapi.yaml (OpenAPI 3).

# upload, then analyse (JSON in, JSON or CSV out)
FID=$(curl -s -X PUT -H "X-Filename: tumour.bedgraph" --data-binary @tumour.bedgraph https://meanderviz.org/api/v1/files | jq -r .id)
curl -s -X POST -H "Content-Type: application/json" \
     -d "{\"sample\":\"$FID\",\"reference\":\"examples/reference.bedgraph\",\"chrom\":\"chr1\",\"wait\":true}" \
     https://meanderviz.org/api/v1/findings | jq .result

# a job, polled, result as CSV
JOB=$(curl -s -X POST -H "Content-Type: application/json" -d '{"alignment":"examples/sars-cov-2_spike.fasta","reference":"Wuhan-Hu-1/2019","min":3}' https://meanderviz.org/api/v1/sites | jq -r .id)
curl -s https://meanderviz.org/api/v1/jobs/$JOB
curl -s "https://meanderviz.org/api/v1/jobs/$JOB/result?format=csv"

Limits: 120 requests per minute per address, two analyses at a time, uploads up to 2 GB, jobs stopped after 30 minutes. URLs given to the API must point to public hosts. Python: requests.put(url + "/files", data=open(f, "rb"), headers={"X-Filename": f}), then requests.post(url + "/findings", json={...}).

Node.js and the command line

src/core.js is the engine, with no dependence on the page: space-filling curves in 2D and 3D, readers for BAM/BAI, bedGraph, WIG, FASTA, BEDPE, VCF, BED, GTF, PAF, alignments and gene matrices, and the analyses. In Node.js:

global.pako = require("./vendor/pako.min.js");
const MC = require("./src/core.js");
MC.d2xy(9, 12345);                   // [x, y] on the 512 x 512 Hilbert curve
MC.CURVES.moore.xy2d(9, 100, 200);   // curve index of a pixel
MC.hilbertNd(500, 6, 3);             // 3D Hilbert curve, 64^3 voxels

Files are given to the readers as objects with name, size and slice(a, b), like the browser File; bin/meanderviz-cli.js wraps a path that way. The command line tool prints CSV and uses the same thresholds and rules as the web app:

node bin/meanderviz-cli.js findings --sample tumour.bedgraph --reference normal.bedgraph --pairs tumour.bedpe --chrom chr1
node bin/meanderviz-cli.js sites --alignment genomes.fasta --reference Wuhan-Hu-1 --min 10
node bin/meanderviz-cli.js assembly --fasta draft.fa --depth reads.bam
node bin/meanderviz-cli.js hilbert --order 9 --d 12345

Both are in the downloadable package (About).

Try it

Run a command against the data that are loaded now. Arguments are a JSON array.

–

Help

MeanderViz folds a whole chromosome, genome or alignment onto a Hilbert curve so that it can be seen at once, at about 250 times the resolution of a linear track. It has four modes. Structural variants combines read depth and paired-end evidence. Genomic signal works with any per-position measurement, such as ChIP-seq or ATAC-seq coverage, DNA methylation, replication timing, GC content or conservation scores, together with feature annotations such as genes. Assembly checks a genome assembly against its reads and compares it with another assembly. Alignment shows multiple sequence alignments of DNA, RNA or protein, and gene presence/absence matrices of pangenomes and metagenomes. This page explains how to load data, how to read the pictures and how far to trust them.

Quick start

1. On the Home page, choose what you want to explore: structural variants, genomic signals and DNA, genome assemblies, or alignments and pangenomes. Each card says which files it needs.
2. Press Try an example to see live output with a short guide above the panel, or Open your files. You can also drop files onto the Data tab of Explore at any time. MeanderViz recognises the file types and suggests a role for each; change a role with the menu next to the file name, then press Analyse.
3. Explore. Hover over the square to read positions and values. Scroll or use + and − to zoom, drag to pan. The linear tracks below show the whole sequence and the region in view, in order. The table below lists what MeanderViz found; click a row to go there.
4. Undo and redo any step with the arrow buttons in the toolbar, or Ctrl+Z and Ctrl+Shift+Z (⌘Z and ⌘⇧Z on a Mac).

The workspace

Examples

The ten example datasets live on the Examples page, grouped by kind of data. Each opens as live output with a three-step guide above the panel and can be downloaded as the original files, to see the formats. Elsewhere, "Examples" always links to that page.

Reading the Hilbert view

The main panel is 512 by 512 pixels, so a chromosome is split into 262,144 equal bins, one per pixel. For human chromosome 1 that is about 950 base pairs per pixel, compared with about 200,000 per pixel for a 1,200-pixel linear track. A 40 kb deletion covers a single column of a linear track but about 40 pixels here, forming a visible patch.

The curve starts in the top-left corner and ends in the top-right. The genome frame around the panel shows every chromosome in order, clockwise from the top-left, with the current one highlighted.

Colour by log2 ratio. Blue pixels have more reads than the reference and orange pixels fewer. The stronger the colour, the larger the change. A heterozygous deletion gives a log2 ratio near −1, a single-copy gain on a diploid background near +0.58, a homozygous deletion a strongly negative value. White means no reads in either sample, typically a centromere or assembly gap.

Colour by read depth. Darker pixels have deeper coverage, up to the depth colour limit.

One caution: two pixels that touch are not always close on the chromosome. Where the curve turns between large quadrants, positions millions of bases apart can sit side by side. Hover to check coordinates before concluding that two patches belong to one event. The linear view below the panel shows the true order.

Structural variants

For structural variants, MeanderViz combines two independent signals: read depth, which falls in deletions and rises in duplications, and read pairs that map too far apart or in the wrong orientation. Load up to four samples and a reference (for example tumour subclones and the matched normal); MeanderViz compares each sample with the reference, draws the pairs, and lists candidates in the table.

Paired-end signatures

For a standard forward-reverse library, pairs whose mapping disagrees with the expected distance or orientation point to rearrangements. MeanderViz estimates the expected insert size from properly paired reads (median plus five times the robust spread) and classifies the rest:

Pairs are grouped into clusters when both ends fall within the clustering window (1 kb by default). Only clusters with at least the minimum number of pairs (3 by default) are drawn, which removes most chimeric and mis-mapped pairs.

Candidate variants and regions that differ

In structural variant mode, the table lists candidates for the current chromosome, built from two independent signals:

• Pairs: a cluster of discordant pairs.
• Depth: a run of windows whose mean log2 ratio stays beyond the read-depth threshold (0.4 by default). MeanderViz chooses the smallest window, a power of two in pixels, at which the noise (robust standard deviation) is below a quarter of the threshold, so a change at the threshold stands about four standard deviations above noise. A run needs at least two windows. Regions where the reference has less than 20% of its median depth are ignored.

A deletion or duplication cluster whose span also shows lower or higher depth is marked Pairs and depth and drawn as a filled diamond. This double evidence is the most reliable class. Inversions and balanced translocations do not change depth, so they are always Pairs only.

Save the table as CSV, or as BED to load it into IGV or the UCSC browser. The download button saves images in PNG, JPEG, SVG or PDF (see SessionsSaving images).

Genomic signals

Choose Genomic signal in the Data tab for any measurement along the genome. MeanderViz then treats values differently from read depth:

• Missing data stays blank. A bin is averaged only over the bases that have a value, so sparse data such as CpG methylation or unmappable regions appear as gaps, not as zero.
• Values are coloured with the viridis scale by default, from dark purple (low) to yellow (high), up to the value colour limit (the 98th percentile at the default setting). Signals with negative values, such as conservation scores, are shown with the blue and orange scale around zero.
• Comparison of a sample with the reference uses the log2 ratio for positive signals such as coverage, or the difference in units of its typical spread for signals that can be zero or negative. Without a reference, each sample is compared with its own median, which highlights domains of enrichment or depletion.
• Regions that differ are found with the same noise-adaptive method as read-depth changes (see below). The table lists the features they overlap, which answers questions such as which genes lie in a domain that gained signal after treatment.

Features from BED or GTF files are drawn as outlines in the main panel and as bars in the linear tracks. Switch each file on or off under Features in the View tab. Type a feature name, such as a gene symbol, into Go to region to jump to it.

DNA sequence and other linear data

Open a FASTA file (.fa, .fasta, .fna, plain or gzip) to see a genome's sequence itself. MeanderViz derives four tracks from it:

• GC content, with a Bases colouring: each pixel mixes the colours of the bases it covers (A green, C blue, G orange, T red). Where a pixel covers one base or less, you see the sequence letter by letter; further out, the mixture shows AT- and GC-rich stretches.
• GC skew, (G − C)/(G + C), which changes sign at replication origins and termini in bacteria and organelles.
• CpG observed/expected, high in CpG islands and in genomes without CpG methylation.
• Cumulative GC skew along the chromosome, whose minimum and maximum mark the origin and terminus of replication in many bacteria.

The derived tracks use a sliding window (DNA composition window in the Settings tab; 0 chooses about eight whole-chromosome pixels, at least 100 bp). Plain FASTA is read by position, like samtools faidx, so large genomes work; lines within a sequence must have equal length. Gzip FASTA is held in memory, so use it for small genomes.

The Arabidopsis chloroplast example is a real genome: 154,478 bp (NC_000932.1) with its genes and its four structural regions, which MeanderViz's comparison finds from the sequence alone. The two inverted repeats come out GC-rich (42% against 34% in the large and 29% in the small single-copy region).

Any other one-dimensional measurement works the same way when written as bedGraph or WIG: conservation, recombination rate, mappability, replication timing, or values along a protein or any sequence with positions.

The 3D view folds the chromosome onto a Hilbert curve for display. A Hilbert-like fractal globule has been proposed as an idealised model of how chromatin folds, but the 3D view is a layout, not the physical structure of the DNA in the nucleus.

Genome assemblies

Choose Assembly in the Data tab, or open a PAF file and MeanderViz switches to it. Give it the assembly's FASTA, and optionally reads mapped to it (BAM with BAI, or bedGraph) and its alignment to another assembly or a reference (PAF). The contigs are joined end to end, longest first by default, so the whole assembly fits one square; the frame around the panel shows the contigs, and positions everywhere are given as contig:position. Type a contig name in the locus box to go to it.

Checking an assembly with its reads

• Collapsed repeats: stretches with 1.6 times the median read depth or more, where copies of a repeat were assembled into one. The table estimates how many copies.
• No read coverage and low coverage: stretches the reads do not support.
• Possible misjoins: read pairs from inside a contig whose mates continue in another contig; the join inside the contig is suspect.
• Contig links: pairs joining the ends of two contigs, which show how contigs could be ordered into scaffolds.
• Scaffold gaps: runs of N in the FASTA. The Assembly tab also lists the number of contigs, N50, L50, the largest contig and GC.

Comparing with another assembly

• Synteny colours (Show: Synteny): each pixel is coloured by where it lies in the other assembly, along a rainbow from its start to its end. Where the order is kept the colours change smoothly; a sudden change of colour is a break; stripes mark the reverse strand; paler colours, lower identity; blank, no alignment. Dashed lines join places that are next to each other in the other assembly but not here.
• Identity: a track of the identity of the alignment at every position.
• Dot plot, in the Overview tab on the right: this assembly along the bottom, the other up the side. Diagonals going up are the same strand, going down the reverse strand. Click a segment to go to it.
• The table adds the breakpoints: joins different sequences (a contig containing parts of two chromosomes, often a misjoin), out of order, orientation changes, aligns twice (a repeat present once here and twice there, typical of collapsed repeats), not in the other assembly and low identity.

The same view shows synteny between species: align one genome to the other with minimap2 (-x asm20 for closely related species) or another whole-genome aligner that writes PAF.

Multiple sequence alignments

Open an alignment (Clustal, Stockholm or aligned FASTA; nucleotide or protein, detected automatically) and MeanderViz switches to Alignment mode. The alignment's columns take the place of positions along a chromosome, so everything on this page, from zooming and selections to the 3D view, works on alignments too. A 30,000-column virus alignment fits the panel at about nine pixels per column; zoom in until a column fills 16 by 16 pixels.

What you see

• Main panel. Colour by Residues to see one sequence on the curve, in base colours (A, C, G, T) or protein colours (Clustal, Zappo or hydrophobicity). With Show only differences from the reference, residues that match are faded, so a sequence that differs in a few places shows a few bright points. Colour by Value to see one of four tracks computed from the alignment: Conservation (the fraction of sequences with the most common residue), Diversity (Shannon entropy in bits), Gaps and missing, and the Differences of the shown sequence from the reference.
• Alignment of the region in view, under the panel: the classic view, one row per sequence, with the consensus and the reference at the top. Columns follow the main panel. Letters appear when a column is wide enough; matching residues show as dots when only differences are shown. Hover for the residue and the sequence's details, click a row to show that sequence, drag to select columns.
• Sequences, in the Overview tab on the right: every sequence as its own small 64 by 64 curve, coloured where it differs from the reference and grey where data are missing. Because all squares use the same curve, a change shared by many sequences appears at the same spot in each. Filter by name, country or date; click a square to show that sequence.
• Variable sites, the table: every column where at least the chosen number of sequences differ from the reference, most frequent first, with the change in reference coordinates (such as A23403G or D614G), the alternative residues and their counts, missing data and overlapping features. Click a site to zoom to it and show the first sequence that carries it.

Choices

• Compare sequences with: a reference sequence, or the consensus of all sequences. Changing it recomputes differences, sites and the small curves.
• Order sequences by: file order (for example tree order), similarity to the reference, or any metadata field in the headers, such as date, clade, lineage or country. Colour marks by colours the mark beside each name and under each small curve by a metadata field, such as WHO variant name or clade, with a legend.
• Features from a BED file, such as genes or protein domains, must be in alignment columns; any sequence name in the file is accepted.

3D

• Stack of sequences: each sequence is one layer of the same 2D curve, ordered as in the list, top to bottom. Differences from the reference are points in residue colours. A change carried by many sequences forms a vertical pillar through the stack, and when the stack is ordered by date you can see when a change appeared and how it spread. Show values beyond becomes the minimum share of sequences that carry a change; lower it to see rare changes. Hover a point for the sequence and the change; click to show it in 2D.
• Columns on a 3D curve: the alignment's columns folded onto the 3D Hilbert curve, coloured by the track shown, as for genomes.

Alignments are held in memory: a few hundred sequences of 30,000 columns take about 13 MB. MeanderViz does not align sequences; use MAFFT, MUSCLE, Clustal Omega or Nextclade first.

Pangenomes and metagenomes

Open a gene presence/absence table (the gene_presence_absence.Rtab or .csv of Roary, Panaroo or PIRATE) and MeanderViz treats it like an alignment whose rows are genomes and whose columns are genes. Everything in the alignment section applies.

• Genomes, in the Overview tab on the right: one small square per genome, coloured where the genome differs from the majority. Genes gained are blue, genes lost orange. Because genes that occur together are placed next to each other, a genomic island shared by a group of genomes appears as the same patch in each of their squares.
• Order genes by: presence pattern (the default; genes with the same pattern of presence side by side, core genes first), frequency, file order, or genome order when a Roary table gives the genome fragment and order of each gene.
• Accessory genes, the table: every gene not in all genomes, classed as soft core (95–99% of genomes), shell (15–95%) or cloud (under 15%), with its annotation. The heading counts core, soft-core, shell and cloud genes.
• Add the genomes' tree (Newick) to order them by Tree order; the 3D stack then shows which clades gained or lost which genes.

Metagenomes: any table with features in rows (species, genes, bins or contigs) and samples in columns works the same way. Numbers such as read counts or relative abundances are shown on a nine-step log scale, with blanks where a feature is absent, so the squares compare the make-up of the samples.

Navigating like a genome browser

The toolbar above the main panel works like the one in a genome browser.

• Locus box. It always shows the region in view. Type a region (chr1:14,200,000-14,650,000, chr1:14200000 or just chr2) or a feature name such as a gene symbol, and press Enter. Press / to jump to the box.
• Previous and next region (the arrows, or [ and ]) move along the chromosome by the amount of genome in view. Zoomed out, they switch to the previous or next chromosome.
• Previous and next candidate (P and N) step through the table in genomic order.
• Genome frame. The line around the panel shows every chromosome in proportion. Click it anywhere to open that chromosome at that position, as you would click an ideogram.
• Sample views in the Overview tab double as overview maps: the box shows where you are, and clicking the sample that is shown jumps there.
• Bookmarks (B) keep the selected candidate, selection or region in view. Click one to return; save them all as a BED file.
• Large view (F, the corners button) fills the window with the panel and places the linear tracks beside it. Label size in the View tab scales every label in the panel and the linear tracks, for reading on a large screen or for figures. The large view shows the same 512 by 512 grid bigger; zoom in for finer detail.
• Guides. The coordinate grid divides the panel into squares that are each a continuous stretch of the chromosome and labels where each one starts. Curve direction draws arrows through the squares in reading order. Feature labels name the genes or other features large enough to label.

Selecting in the Hilbert panel

Choose a pointer tool above the panel:

• Move (M): drag to pan, click for the values at a pixel.
• Select (S): drag a rectangle. Shift+drag selects with any tool.
• Wand (W): click a coloured patch to select all touching pixels of the same colour, at least a third of the colour limit strong. This picks out an event exactly as you see it.

Hold Ctrl (⌘ on a Mac) to add to the current selection. Dragging in a linear track also selects. Because a rectangle on a space-filling curve covers several stretches of the chromosome, a selection is a list of stretches; the Details tab on the right shows how many, their total length, the candidates and features inside, and the mean value of every sample in the selection with its change against the baseline. From there you can zoom to the selection, bookmark it or save the stretches as a BED file. Esc clears the selection. Selections are part of the undo history.

Comparing samples

The Samples tab on the left lists every loaded sample.

• Untick a sample to leave it out of the main panel, the small views and the table.
• Click a name to rename it; the new name is used everywhere, including exported files.
• Compare each sample with sets the baseline: the reference, any other sample, or each sample's own median. Comparing two subclones directly, for example, shows only the changes that differ between them: events they share disappear, and events unique to one remain.

In the Overview tab, below the small views, a matrix shows how similar the samples are. The upper right gives the correlation of their comparison profiles along the chromosome; the lower left counts the candidates they share. Click a cell to compare that pair directly: the row sample is shown and the column sample becomes the baseline.

Space-filling curves

How a chromosome is folded into the square decides which positions end up side by side. Choose the curve under View. The numbers below were measured on the 512 by 512 panel: how often one step along the chromosome moves to a touching pixel, and how far apart on the chromosome touching pixels are (in pixels; multiply by the bases per pixel).

Switching curves keeps your position. Comparing the same event under different curves is a quick way to see why Hilbert curves are used: a deletion that is one compact patch under Hilbert may split in two under Z-order and become a thin line under serpentine. The Peano curve, used in some earlier work, divides the square into 3 by 3 blocks and so does not fit the 512-pixel grid; it is not offered.

3D view

Choose 3D in the toolbar (View) to fold the chromosome onto a three-dimensional Hilbert curve (or Z-order curve) of 64 × 64 × 64 voxels. That is 262,144 voxels, exactly one for each pixel of the whole-chromosome 2D view, so the resolution is the same.

• Show values beyond hides voxels whose colour would be weaker than the chosen fraction of the colour limit. Raise it to see only the strongest changes inside the cube.
• Drag to rotate, scroll to zoom, Rotate to spin slowly. Curve draws the coarse 8 × 8 × 8 path from teal (start) to pink (end).
• The region in view in 2D, or your selection, is shown in pink. Hover a voxel to see its position and value in the linear tracks; click it to open that position in 2D.

Three dimensions keep more positions close together than two, but hide the interior, so the 3D view is best for seeing how many separate events a sample has and how they cluster. Use 2D for reading positions.

Microbiome maps

Open a taxonomic abundance table (species in rows with their lineage, as MetaPhlAn writes it: k__Bacteria|p__Firmicutes|…|s__Species, samples in columns) and, optionally, a sample metadata table (a file whose name contains metadata: samples in rows or in columns, with fields such as diagnosis, site or time point). MeanderViz then draws microbiome maps in the sense of Valdes et al. (2023): each pixel is one taxon, coloured by its abundance in the sample shown, on a nine-step log scale.

• Taxonomy order (the default when lineages are present) places related taxa next to each other along the curve, so that phyla, classes, orders, families and genera form nested neighbourhoods. Each rank is a feature track: switch outlines and labels on or off under Features in the View tab.
• Condition order (Genomes tab › Order genes by) assigns each taxon to the condition where its mean abundance is highest, in the field chosen under Colour marks by, and orders the taxa by condition, then taxonomy. A sample from one condition then lights up mostly one neighbourhood. The "Condition" track outlines them.
• The Overview tab shows every sample as its own small map, with the metadata colour marks; Play steps through the samples in the current order (by time point, for a longitudinal study), and Save all maps writes one PNG per sample into a zip, ready for a movie.
• Click a pixel for the taxon's lineage, its abundance in the sample and across samples, and links to NCBI Taxonomy and genomes.
• The 3D stack shows all samples at once: a taxon abundant in a group of samples is a vertical pillar.

The HMP2 example holds 124 real gut microbiome samples of an inflammatory bowel disease study.

Colours, resolution and layout

• Colours (Colours tab): the comparison scale (blue and orange by default; red and blue; green and purple; blue and yellow; green and red, which many colour-blind readers cannot tell apart), the value scale (single colour, viridis, magma, inferno, plasma), colours for variant types, features and bases (including the colour-blind safe Okabe–Ito set), and a white or black panel background. The choice applies to the main panel, the sample views, the linear tracks, the 3D view, the legend and the table.
• Panel resolution: 512, 1024 or 2048 pixels per side. Higher resolutions show four or sixteen times more detail in the same square and take longer to draw; while you drag, the panel is drawn at 512 and refined when you let go. The finest level still reaches about one base per pixel.
• 3D resolution: 64³ voxels (the same number as the 512 panel) or 128³, eight times as many. Region in view fills the cube with just the region shown in 2D or your selection; when the data in memory are too coarse, MeanderViz reads that region from the file at full resolution. In value colouring the 3D view shows the voxels that depart most from the median; in comparison colouring, the largest changes.
• Tabs and collapsing: the left and right columns are organised in tabs, and every section in a tab can be folded with its chevron. The two toolbar buttons at the ends hide the left or right column; with both hidden, the main panel grows and the linear tracks move beside it. In 3D, Hide controls clears the control bar from the view.

Mouse and keyboard

Input files

MeanderViz accepts files straight from common pipelines. No conversion or pre-processing step is needed. Every text format may be plain or compressed with gzip or bgzip.

Examples

# bedGraph: chrom  start  end  depth
chr1	14200000	14200500	61.4
chr1	14200500	14201000	58.9

# samtools depth: chrom  position  depth
chr1	14200001	61
chr1	14200002	61

# BEDPE: chrom1 start1 end1 chrom2 start2 end2 name score strand1 strand2
chr1	14199700	14199800	chr1	14500200	14500300	DUP	60	-	+
chr1	18299700	18299800	chr3	2100200	2100300	TRA	60	+	-

# WIG
fixedStep chrom=chr1 start=1000001 step=100 span=100
0.62
0.71

# BED features: chrom start end name score strand
chr1	5999100	6012400	Gn0051	0	+

# VCF (columns 1 to 8)
chr1	14200001	call2	N	<DUP>	55	PASS	SVTYPE=DUP;END=14500000

A reference is optional. With a reference, samples are compared with it. Without one, each sample is compared with its own median depth, which works for copy-number changes against a mostly diploid background.

Public databases and web addresses

The Import data tab adds public annotations to the data you are exploring, fetches files from web addresses, and holds the examples.

• Public databases. Genes (NCBI RefSeq through the UCSC Genome Browser, or Ensembl for any species it covers), CpG islands, ENCODE candidate regulatory elements, known structural variants from the Database of Genomic Variants, or any other UCSC track by name. Choose the assembly that matches your data and import for the current chromosome, the region in view or all chromosomes. Imported tracks behave like BED files: outlines, labels, the Features column and search by name. Known structural variants in the Features column show at a glance whether a candidate is a common population variant.
• Web addresses. Any supported file on a server that allows cross-site downloads.

Only the assembly name and coordinates are sent to the databases, never your data. The online preview on claude.ai cannot reach other sites, so imports work in the hosted MeanderViz site and in the self-hosted package.

Checks and messages

Every file is checked as soon as it is added: that it is not empty, that a file named .gz is really compressed, that a BAM is a BAM (not a SAM), that an index is an index, and that the first lines look like the format the name suggests. A file that fails is marked in the Data tab and skipped; the others still load. Warnings appear in the Data tab and briefly at the bottom right of the window, for example:

• a BAM without an index, or not sorted by coordinate (slower reading);
• chromosome names that differ between files, such as chr1 in one and 1 in another, with the fix;
• chromosomes present in some samples only, or a sample with no data on the chromosome shown;
• no reference sample (samples are compared with their own median), no matching contigs in a PAF, alignments with many missing residues, a PAF without CIGAR tags.

While files are read, a progress bar runs under each file in the Data tab and in the panel. Reading can be cancelled from the panel.

Sessions

Save session in the Data tab writes a small JSON file with the list of files, every setting, the view, the selection, the bookmarks, the sample names and any features imported from public databases. The data files themselves are not included, so nothing private leaves your computer. Load session reads it back: for an example, the session opens at once; for your own files, MeanderViz lists the files it needs, applies the session once you have added them and pressed Analyse. Scripts can do the same with MeanderViz.session() and MeanderViz.loadSession().

Saving images

The download button in the toolbar opens the export dialog. Choose the format, the area (the main panel with its overlays; a figure with the title line, the panel, the linear tracks and the legend; the 3D view; the alignment viewer; the dot plot), the resolution (1× at 96 dpi for screens up to 6× at 576 dpi, or a custom width up to 16,000 pixels), the background, and whether to leave out the selection and highlighting:

• PNG: lossless; keeps the pixel grid crisp at any width; can have a transparent background.
• SVG: the data as a crisp image and everything else, lines, markers, labels and the genome frame, as vectors, so it can be edited in Inkscape or Illustrator. Available for the panel and the figure.
• JPEG, WebP and PDF: flattened images, handy for slides, the web and manuscripts; the PDF is one page at the image size.

Two zoom sliders help: the Zoom slider in the toolbar zooms the curve view, and the Linear zoom slider above the lower track zooms the linear view on its own, so the panel can show the whole chromosome while the track shows a few kilobases. The width can be up to 16,000 pixels. The panel is drawn from its current data resolution (512, 1024 or 2048 pixels, set in the View tab), so for the finest data raise that first. Scripts can save the same images with MeanderViz.export("svg", { content: "figure", width: 3000 }).

Scripts, links and the command line

MeanderViz can be driven without the mouse. The full reference, with a console to try commands, is on the API page; in short:

• Links. Add parameters to the address to open a view directly: ?example=asm&locus=ctg2:20000-24000&mode=syn, or ?url=https://…/a.bedgraph,https://…/a.bedpe&kind=sv for files on a server that allows cross-site downloads. In the browser console, MeanderViz.link() gives the link for the current view.
• Scripts. window.MeanderViz offers load, example, goto, select, view, settings, findings, csv, export, state and events (load, view, selection, finding).
• Embedding. In an <iframe>, the same commands can be sent with postMessage; MeanderViz replies and reports events to the embedding page.
• Command line. node bin/meanderviz-cli.js runs the engine without a browser: findings for structural variants, sites for alignments, assembly for assembly checks and hilbert for curve coordinates, all printing CSV. The engine itself, src/core.js, can be required from Node.js.

Interpreting results

MeanderViz is a visual exploration tool. The candidate list is a guide to where to look, not a validated call set. Things worth keeping in mind:

• Depth alone is noisy. GC content, mappability and repeat regions change coverage without any real variant. Depth-only candidates next to gaps or centromeres deserve extra caution. Differences between two samples sequenced the same way are more robust than a single sample compared with its median.
• Pairs alone can mislead. Mis-mapped reads in segmental duplications produce clusters. Raise the minimum pairs per cluster or the mapping quality if many small clusters appear.
• Check the example. In the example data, subclone 2 has a tandem duplication at chr1:14.20–14.50 Mb with a flanking deletion. Both appear with pairs and depth and are marked unique. The 40 kb deletion in subclone 4 on chr2 is nearly invisible in the linear view but forms a clear patch in the Hilbert view.
• Confirm important findings by inspecting reads in a genome browser, with an orthogonal method, or with a dedicated SV caller.

Privacy and limits

Everything runs in your browser. Files are read from your disk and are never sent to a server, so MeanderViz can be used with sensitive human data. The site sets no cookies and uses no tracking. Closing the tab discards all data.

MeanderViz keeps one chromosome in memory at a time, about 17 MB per sample. Reading a whole-genome BAM without an index can take several minutes, so provide the .bai file where possible. Tested in current versions of Chrome, Firefox, Safari and Edge on Windows, macOS and Linux.

Questions

Can I use bigWig files?

Not yet. Convert them with bigWigToBedGraph from the UCSC tools, or use bedGraph or WIG directly.

Do I need a reference sample?

No. Without one, each sample is compared with its own median depth. A matched normal or parental sample gives cleaner ratios.

Why is my chromosome mostly white?

Probably low coverage or the wrong chromosome names. MeanderViz treats chr1 and 1 as different chromosomes, so files from different pipelines must use the same naming.