{% extends "base.html" %} {% block title %}Help{% endblock %} {% block content %}

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_idgene_familychromosomestartendstrand
gene_1family_1chr_1403115104−
centro_1centromerechr_182125984760

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:

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.

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.

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

FileContents
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)

FileOne row per…Key columns
analytics_genes_per_family.csvfamily gene_family, on_chromosomes, on_unplaced, total
analytics_family_summary.csvfamily 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.csvfamily × chromosome n_genes, first_start, last_end, span_bp, chrom_length, density_per_mb, n_subtelomeric
analytics_gene_metrics.csvgene 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.csvfamily 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.csvfamily (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.csvfamily (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.csvtandem array gene_family, chromosome, start, end, n_genes, span_bp, gene_ids (;-joined)
analytics_array_summary.csvfamily n_genes, n_tandem_arrays, genes_in_arrays, frac_clustered, largest_array
analytics_duplication_modes.csvfamily n_tandem, n_proximal, n_dispersed, n_genes, frac_tandem, frac_proximal, frac_dispersed, predominant_mode
analytics_ripley.csvfamily × 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.csvfamily × chromosome observed, expected, log2_obs_over_exp, p_value, q_value, enriched, depleted
analytics_strand_bias.csvfamily n_plus, n_minus, frac_plus, p_value, q_value, biased_toward, significant_fdr
analytics_chromosome_richness.csvchromosome chrom_length_bp, n_genes, n_families, shannon_diversity, evenness, dominant_family, dominant_family_frac, genes_per_mb
analytics_positional_profile.csvfamily × bin (plus a (all families) series) bin, bin_center (0–1), n_genes, frac_of_family
analytics_family_proximity.csvfamily (square matrix; first column is the family index) cell = mean cross-nearest-neighbour distance in bp; diagonal = within-family nearest-neighbour distance
analytics_hotspots.csvmerged hotspot region hotspot_id, chromosome, start, end, length_bp, n_genes, n_families, families, genes_per_mb, min_q_value
analytics_hotspots.bedhotspot region (BED6) chrom, start (0-based), end, name (hotspot_n;n=…;fam=…), score (min(1000, −10 log10 q)), strand (.)
analytics_colocalization.csvfamily 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.

{% endblock %}