GFViewer accepts any mix of the following (detected automatically):
.xlsx / .csv / .tsvOne 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.
.bedStandard 0-based half-open BED3–BED12; coordinates are converted for you. Family assignment:
name) is the gene family.gene_id,gene_family per line)
→ family looked up from the map..gff3 / .gtf1-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.
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.
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)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.
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.
--cluster-gap (50 kb). Reported
per array and summarised per family (frac_clustered).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.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.enriched /
depleted flags.+/− split against 0.5.--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.--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.
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:
| 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. |
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
( |
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. |
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 --helpSee 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.