JacksonFW/transcriptomics-explorer

1# Transcriptomics Explorer — User Guide2 3This dashboard is a visualisation tool for exploring **RNA-seq differential expression results**. It is designed for researchers, students, and bioinformaticians. No coding required — just upload your data and interact with the plots.4 5**Default behaviour:** The app loads 800 simulated genes on startup so you can explore all features immediately. Upload your own DESeq2/edgeR CSV to replace the demo data across all six tabs at once.6 7---8 9## How to Run10 111. Open Terminal122. Navigate to this folder: `cd path/to/transcriptomics-explorer`133. Install dependencies (first time only): `pip install -r requirements.txt`144. Start the app: `python app.py`155. Open your browser: **http://localhost:7860**166. Press `Ctrl + C` in the terminal to stop.17 18---19 20## Tab 1 — Volcano Plot21 22### What is it?23The core feature of the dashboard. A Volcano plot answers the question:24**"Which genes are significantly turned ON or OFF between two conditions?"**25(e.g. cancer vs. normal tissue, drug-treated vs. untreated cells)26 27Each dot = one gene.28 29### How to read it30 31**X-axis — log₂ Fold Change** (how much expression changed)32- Positive (right) = gene is MORE active in condition B33- Negative (left) = gene is LESS active in condition B34- Value of 1 = 2× more expressed / Value of 2 = 4× more expressed35 36**Y-axis — -log₁₀(adjusted p-value)** (how confident we are)37- Higher = more statistically significant38- ~1.3 = p-value of 0.05 (standard significance cutoff)39 40**Colour coding**41- Red = Significantly UPREGULATED (top-right)42- Blue = Significantly DOWNREGULATED (top-left)43- Grey = Not significant44 45**What to look for:** The most interesting genes are in the top corners.46 47### Interactive controls48- **log₂FC slider** — raise the fold change threshold49- **p-value dropdown** — tighten or loosen significance50- **Gene search box** — type gene names (e.g. TP53, BRCA1) to highlight them as gold stars51- **Box-select on the plot** — draw a rectangle to populate the table below52- **Export CSV** — download the current significant gene list53 54---55 56## Tab 2 — MA Plot57 58### What is it?59A companion to the Volcano plot used for **quality control**. The MA plot shows whether fold changes are consistent across the range of expression levels.60 61Each dot = one gene.62 63### How to read it64 65**X-axis — log₁₀(mean expression)** — how highly expressed the gene is on average66- Left = lowly expressed genes (often less reliable)67- Right = highly expressed genes (more reliable measurements)68 69**Y-axis — log₂ Fold Change** — same as volcano X-axis70 71**Horizontal lines**72- Middle line at y=0 = no change73- Dashed lines at y=±1 = 2× fold change threshold74 75**Colour coding** — Red = up, Blue = down, Grey = not significant76 77**What to look for:**78- Fold changes should be roughly symmetric around y=0 for non-significant genes79- If low-expression genes (left side) show large scatter, that is expected noise — not biology80- Large fold changes at high expression (right side) are the most trustworthy hits81 82---83 84## Tab 3 — PCA (Principal Component Analysis)85 86### What is it?87PCA answers: **"How similar are your samples to each other overall?"**88 89It reduces thousands of gene measurements down to two axes (PC1 and PC2) that capture the most variation. Each dot = one sample.90 91### How to read it92 93**PC1 (X-axis)** — the biggest source of variation in your data94**PC2 (Y-axis)** — the second biggest source of variation95 96The % in each axis label tells you how much of the total variation that component explains.97 98**What to look for:**99- Samples from the same condition (e.g. replicates) should cluster together100- The two conditions should separate along PC1 (the main axis)101- An outlier sample far from its group may indicate a technical problem102 103> **Note:** In this app, PCA is derived from the DE results matrix. For true sample-level PCA, provide a count matrix (genes × samples) as a second upload.104 105---106 107## Tab 4 — Sample Correlation108 109### What is it?110Shows the **Pearson correlation coefficient (r)** between every pair of samples, based on their gene expression profiles.111 112Each cell = pair of samples. The value shown is r (ranges from -1 to +1).113 114### How to read it115 116- **r ≈ 1.0** (dark colour) = samples are nearly identical in expression117- **r ≈ 0.9–0.95** = typical biological replicates — good correlation118- **r < 0.8** = unexpected — possible batch effect or sample swap119- Diagonal is always 1.0 (a sample perfectly correlates with itself)120 121**What to look for:**122- Replicates within the same condition should form a tightly correlated block123- Different conditions should show lower correlation between blocks124- Any sample that correlates poorly with ALL others is an outlier — investigate it125 126---127 128## Tab 5 — Heatmap129 130### What is it?131A heatmap of the **top 50 most variable genes** across all samples.132 133Each row = one gene. Each column = one sample. Colour = Z-scored expression level (how far above or below average that gene is in that sample).134 135### How to read it136 137**Colour scale:**138- Red = higher expression than average (for that gene)139- Blue = lower expression than average140- White = near average141 142**What to look for:**143- Columns that cluster together have similar expression profiles144- Rows that cluster together are co-regulated (turn on/off together)145- A block of red genes in one condition and blue in another = a regulated gene module146 147Genes are Z-scored per row so you can compare patterns regardless of absolute expression level.148 149---150 151## Tab 6 — Pathway Enrichment152 153### What is it?154This tab answers: **"Which biological pathways are most affected in my experiment?"**155 156Genes work together in coordinated groups called pathways (e.g. Cell Cycle, DNA Repair, Apoptosis). If many of your significant DE genes belong to one pathway, that pathway is likely activated or suppressed in your experiment.157 158### How the enrichment is calculated159 160For each pathway:1611. Count how many of your significant genes are in that pathway1622. Calculate a **fold enrichment** = how many more hits you got vs. random chance1633. Separate UP-regulated hits (red bars) from DOWN-regulated hits (blue bars)164 165The chart shows the top 20 pathways sorted by their maximum enrichment score.166 167### How to read it168 169**X-axis** — pathways (KEGG / Reactome)170**Y-axis** — fold enrichment (higher = more enriched than expected by chance)171 172**Red bars** = upregulated genes enriched in that pathway173**Blue bars** = downregulated genes enriched in that pathway174 175**What to look for:**176- A pathway with tall red AND blue bars = mixed regulation (complex response)177- A pathway with only red bars = pathway being activated178- A pathway with only blue bars = pathway being suppressed179 180A summary table below the chart lists hit counts and scores for each pathway.181 182---183 184## Data Format — What to Upload185 186The upload accepts **DESeq2 or edgeR differential expression results** as CSV or TSV. Column names are flexible — common variants are automatically detected.187 188| Column | Accepted names | Example values |189|--------|---------------|----------------|190| Gene symbol | `gene`, `gene_id`, `geneId`, `symbol` | `TP53`, `BRCA1` |191| Log₂ fold change | `log2FoldChange`, `log2fc`, `lfc` | `2.41`, `-1.82` |192| Raw p-value | `pvalue`, `pval`, `p.value` | `0.000032`, `3.2e-10` |193| Adjusted p-value | `padj`, `p.adj`, `fdr` | `0.0012`, `4.0e-08` |194| Base mean (optional) | `baseMean`, `mean_expr`, `avgExpr` | `340.5`, `128.7` |195 196**Example file:**197```198gene,baseMean,log2FoldChange,pvalue,padj199TP53,340.5,2.41,0.000032,0.0012200BRCA1,128.7,-1.82,0.00036,0.014201MYC,892.1,3.10,0.0000000012,0.000000040202GAPDH,4521.0,0.02,0.91,0.99203```204 205A sample test file (`test_data_1000genes.csv`) is included in this folder.206 207**Notes:**208- First row must be a header row with column names209- Missing values (NA, NaN) in `padj` are handled automatically210- No row limit, but files over 100,000 genes may be slow to render211 212---213 214## How Is This Data Obtained?215 216The data visualised here is produced **before** you use this dashboard through a multi-step pipeline:217 2181. **Wet lab** — grow cells/tissue under two conditions, extract RNA2192. **RNA sequencing** — sequencer counts RNA fragments per gene → FASTQ files2203. **Preprocessing** — align sequences to the genome, count per gene → count matrix2214. **DESeq2 / edgeR** (R package) — normalise counts, run statistical tests → results CSV2225. **Upload that CSV here** → this dashboard visualises the results223 224The count matrix (Step 3) is the large file (50–200 GB per sample) requiring HPC computing. The DESeq2/edgeR results CSV (Step 4) is small (a few MB) and is what you upload here. Steps 4–5 run fine on a laptop.225