User guide

1. Upload annotation file(s)

GFViewer accepts any mix of the following (detected automatically):

Table — `.xlsx` / `.csv` / `.tsv`

One row per gene, 1-based inclusive coordinates. Header names are matched case-insensitively and common synonyms are accepted (id, family, chrom, …).

gene_id	gene_family	chromosome	start	end	strand
gene_1	family_1	chr_1	4031	15104	−
centro_1	centromere	chr_1	82125	98476	0

Put centromere in gene_family (strand 0) for centromere rows; they are drawn only when “Draw centromeres” is on.

BED — `.bed`

Standard 0-based half-open BED3–BED12; coordinates are converted for you. Family assignment:

One BED file → column 4 (name) is the gene family.
Several BED files → each file’s base name is the family (column 4 becomes the gene id).
One BED + a mapping file (gene_id,gene_family per line) → family looked up from the map.

GFF3 / GTF — `.gff3` / `.gtf`

1-based inclusive. Gene-like feature types are kept (gene, pseudogene, mRNA, transcript). The family is read from an attribute — by default GFViewer looks for gene_family, Family, gene_biotype, Name…; override it with the “GFF/GTF family attribute” box. Feature types named centromere are treated as centromeres.

2. Upload a genome

A FASTA (.fasta/.fa/.fna), a .fai index, a UCSC chrom.sizes, or a plain chromosome,length table. Chromosome identifiers must match the annotation exactly.

3. Colours

The first 20 colours are a fixed, maximally-distinct set; beyond that they are generated automatically. A readability warning appears above ~25 families and a hard limit applies at 40 — enable Collapse rare families to fold the least frequent into a single “Other” category. Supply a colour-map file to override:

MGF1,1            # palette index 1-20
MGF2,#1b9e77      # hex
MGF3,0.2,0.6,0.9  # RGB 0-1 (or 0-255)

4. Refine and export

After the figure renders you can recolour families and pick which families and chromosomes to include (each has its own tick plus a Select all); de-selected families also drop out of the legend. Move the legend and labels, change fonts and mark style, then Regenerate for a clean re-render — the layout and spacing are recomputed for whatever subset you keep. Export to PDF, SVG, PNG, JPG or EPS. Save a style file from the command line (gfviewer --save-style style.yaml …) and re-upload it to reproduce a look.

Titles on image files. By default the exported chromosome figure carries the title you typed, and each analytics chart carries its built-in heading (“Genes per family”, “Positional density profile”, …). Untick “Bake titles into the image files” on the form (or “Titles on image files” in the editor, then Regenerate) to write the figures with no title text at all — handy when the figure will sit under its own caption in a manuscript. On the command line this is --no-titles.

Trim surrounding whitespace. After drawing, GFViewer crops the figure to what was actually rendered — the chromosomes, their gene marks and labels, the title and the legend — so there is no wide dead band around the drawing or between the chromosomes and the legend. The Margin box sets how much white to keep all round (default 0.3 cm; it is also the gap to an outside / bottom legend). Untick “Trim surrounding whitespace” to keep the full reserved page. On the command line this is --no-fit / --margin-cm.

Analytics

When analytics is enabled, GFViewer computes a battery of quantitative tests on the placed genes. Every per-family, per-pair and per-window test carries a raw p-value and a Benjamini–Hochberg q_value (false-discovery-rate); a significant_fdr flag marks rows with q_value ≤ α (default α = 0.05). All permutation nulls re-place a family's genes uniformly at random along the same chromosomes, keeping the per-chromosome count and the gene lengths fixed.

Telomere-proximity test — per family, is the mean normalised distance to the nearer chromosome end smaller (telomere- proximal) or larger (interior) than the permutation null?
Centromere-proximity test & arm bias — only when a centromere track is supplied. The first is the centromere analogue of the telomere test; the second is a binomial test of p-arm vs. q-arm gene counts against the arm-length ratio of the chromosomes the family occupies.
Tandem arrays — runs of ≥ 2 same-family genes separated by ≤ --cluster-gap (50 kb). Reported per array and summarised per family (frac_clustered).
Duplication mode — each gene is labelled tandem (nearest same-family paralogue on the chromosome within --cluster-gap), proximal (within --proximal-window, default 5× the cluster gap) or dispersed; aggregated to per-family fractions and a predominant mode.
Multi-scale clustering — 1-D Ripley's K/L — for families with ≥ 5 placed genes, the edge-corrected 1-D Ripley K is estimated at a ladder of scales (1 kb…1 Mb), pooled across chromosomes and converted to L(t) − t. Positive means clustered at that scale, negative means over-dispersed; a permutation envelope and FDR-corrected p-values say where it is significant. The peak scale is the family's characteristic clustering distance.
Chromosome enrichment — per (family, chromosome), a binomial test of the observed gene count against the count expected if the family were spread over the genome in proportion to chromosome length. FDR across all cells; enriched / depleted flags.
Strand bias — per family, binomial test of the +/− split against 0.5.
Chromosome richness — per chromosome, the number of distinct families, Shannon diversity and evenness of the family composition, and the dominant family.
Positional density profile (“metachromosome” plot) — each gene's midpoint is expressed as a fraction of its chromosome length (0 = start telomere, 0.5 = centre, 1 = end telomere) and binned; the table / figure show each family's density along that axis, plus a pooled “all families” curve and the uniform reference.
Family–family proximity — a family × family matrix of the mean distance from a gene of A to the nearest gene of B on the same chromosome (symmetrised; the diagonal is the within-family nearest-neighbour distance). Families are ordered and grouped by average-linkage hierarchical clustering — the blocks are sets of families that tend to sit together.
Multigene-family hotspots — a sliding window (--hotspot-window, 100 kb) scans each chromosome for an excess of multigene-family genes (all families pooled) over a uniform Poisson expectation; FDR-significant windows are merged into regions and written both as a table and as a BED file.
Pairwise co-localization (optional, --colocalization) — for every family pair (A, B), how many genes of A lie within the co-localization window (50 kb) of a gene of B on the same chromosome, vs. the permutation null. Off by default because it is O(families²) pairs × hundreds of permutations with a per-gene inner loop — minutes for a large genome, versus a fraction of a second for the vectorised per-family tests.

The “most clustered family” headline statistic is restricted to families with at least 3 genes, since a 2-gene family is trivially 100 % clustered. Genes on unplaced / stray contigs are counted in genes_per_family but excluded from every chromosome-level test, and are not drawn unless “Also draw unplaced contigs” is ticked.

Downloadable outputs

The results page offers a “All output (ZIP)” button (everything currently produced) and a “Every format (ZIP)” button (re-renders the chromosome figure and every analytics chart as PDF, SVG, PNG, JPG and EPS first). Individual files:

Figures

File	Contents
`gfviewer.<fmt>`	the chromosome ideogram (`.p1`, `.p2`… suffixes for multi-page output; a single multi-page `.pdf`). `fmt` ∈ pdf, svg, png, jpg, eps.
`analytics_genes_per_family.<fmt>`	stacked bar chart: genes on chromosomes vs. on unplaced contigs, per family.
`analytics_positional_profile.<fmt>`	the metachromosome density profile (one line per family + pooled).
`analytics_ripley.<fmt>`	Ripley's `L(t) − t` vs. scale, one line per family; filled markers are FDR-significant scales.
`analytics_family_proximity.<fmt>`	the family–family proximity heat map, clustered ordering, cluster blocks outlined.

Tables (CSV, one header row; `analytics_summary.json` is a nested object)

File	One row per…	Key columns
`analytics_genes_per_family.csv`	family	`gene_family, on_chromosomes, on_unplaced, total`
`analytics_family_summary.csv`	family	`n_genes, n_chromosomes, mean/median_gene_length, n_subtelomeric, frac_subtelomeric, mean_norm_dist_to_telomere, frac_plus_strand, genes_per_mb_genome, n_on_chromosomes, n_on_unplaced`
`analytics_family_by_chromosome.csv`	family × chromosome	`n_genes, first_start, last_end, span_bp, chrom_length, density_per_mb, n_subtelomeric`
`analytics_gene_metrics.csv`	gene	`gene_id, gene_family, chromosome, start, end, strand, mid, length, dist_to_telomere, norm_dist_to_telomere, subtelomeric, dup_mode` and, with centromeres, `dist_to_centromere, norm_dist_to_centromere, arm`
`analytics_telomere_bias.csv`	family	`n_genes, observed_mean_norm_dist, null_mean_norm_dist, null_sd, p_toward_telomere, p_toward_interior, direction, q_value, significant, significant_fdr, n_permutations`
`analytics_centromere_bias.csv`	family (centromere track only)	`n_genes, observed/null_mean_norm_dist_cen, direction (pericentromeric / centromere-distal), p_pericentromeric, p_distal, q_value, significant_fdr`
`analytics_arm_bias.csv`	family (centromere track only)	`n_p_arm, n_q_arm, expected_frac_p, observed_frac_p, p_value, q_value, biased_toward_arm, significant_fdr`
`analytics_tandem_arrays.csv`	tandem array	`gene_family, chromosome, start, end, n_genes, span_bp, gene_ids` (`;`-joined)
`analytics_array_summary.csv`	family	`n_genes, n_tandem_arrays, genes_in_arrays, frac_clustered, largest_array`
`analytics_duplication_modes.csv`	family	`n_tandem, n_proximal, n_dispersed, n_genes, frac_tandem, frac_proximal, frac_dispersed, predominant_mode`
`analytics_ripley.csv`	family × scale	`scale_bp, L_minus_t_obs, L_minus_t_null_mean, env_lo, env_hi, p_clustered, p_dispersed, pattern, q_clustered, significant_fdr`
`analytics_chromosome_enrichment.csv`	family × chromosome	`observed, expected, log2_obs_over_exp, p_value, q_value, enriched, depleted`
`analytics_strand_bias.csv`	family	`n_plus, n_minus, frac_plus, p_value, q_value, biased_toward, significant_fdr`
`analytics_chromosome_richness.csv`	chromosome	`chrom_length_bp, n_genes, n_families, shannon_diversity, evenness, dominant_family, dominant_family_frac, genes_per_mb`
`analytics_positional_profile.csv`	family × bin (plus a `(all families)` series)	`bin, bin_center (0–1), n_genes, frac_of_family`
`analytics_family_proximity.csv`	family (square matrix; first column is the family index)	cell = mean cross-nearest-neighbour distance in bp; diagonal = within-family nearest-neighbour distance
`analytics_hotspots.csv`	merged hotspot region	`hotspot_id, chromosome, start, end, length_bp, n_genes, n_families, families, genes_per_mb, min_q_value`
`analytics_hotspots.bed`	hotspot region (BED6)	`chrom, start (0-based), end, name (hotspot_n;n=…;fam=…), score (min(1000, −10 log10 q)), strand (.)`
`analytics_colocalization.csv`	family pair (with `--colocalization`)	`family_a, family_b, observed_close_pairs, null_mean, p_value, q_value, significant, significant_fdr`
`analytics_summary.json`	—	genome / family / chromosome counts, the headline families (largest, densest, most clustered), and JSON versions of the telomere-bias, centromere-bias, arm-bias, duplication-mode, Ripley-clustering, chromosome-enrichment hits, strand-biased families, hotspot regions and family-proximity clusters.

Command line

Everything on this page is also available as the pip-installable gfviewer command — the same engine, plus batch options for scripting:

python -m pip install gfviewer
gfviewer -d genes.csv -g genome.fasta -o out/ --analytics -cen
gfviewer --help

See the installation & command-line guide for isolated-environment setup, every flag with worked examples, and troubleshooting. Direct links: PyPI · GitHub source · release downloads · guide as Markdown.