19  Troubleshooting

Something went wrong, or a result looks strange. This chapter says where to look first, explains the most common messages, and points to the chapter that explains the cause. The messages are quoted as EpiNexus 1.2.3 shows them.

19.1 Where to look first

1. The run page, tab Overview. A red box shows why a run failed. A yellow box lists warnings. The Steps table shows each step’s state; a skipped step shows its reason (Chapter 4).
2. The Review step of the run wizard, before you launch. Errors under Fix before launching stop the run from starting. Warnings under Design notes are kept with the run (Chapter 2).
3. The tab Logs, for the full output of the tools.
4. The report’s Methods section, which says what the run actually did: which samples were kept, which normalisation was used, and which steps were skipped (Chapter 18).

Many messages end with “Ask the EpiNexus team”. These are problems you cannot fix yourself, such as a missing genome or a machine limit. Write to the team with the run’s name.

Figure 19.1 shows the Overview tab of the CUT&RUN run of Chapter 15.

Figure 19.1: Warnings and steps of the CUT&RUN run (71a4d9cc). The yellow box lists seven warnings: the shared IgG, the missing super-enhancer marks, the E. coli spike-in, the samples kept although they failed QC, and two skipped steps. In the Steps table, three steps were skipped, each with its reason. EpiNexus 1.2 interface; not covered by the book’s licence.

19.2 Before the run starts: design checks

Table 19.1: Design errors that stop a run from starting.

Message (shortened)	What it means	What to do
“The reference genome … isn’t installed yet”	The genome is not on this service	Choose an installed genome, or ask the team (Appendix B)
“DNA-methylation analysis from FASTQ needs the Bismark index for …”	The bisulfite index is missing	Ask the team; or upload Bismark .cov files
“The spike-in genome … is the same species as the run’s genome”	A spike-in must come from another species	Choose another spike-in genome (Chapter 10)
“The samples look like different library types — RRBS: …; WGBS: …”	Some samples look like RRBS, others like WGBS	Choose the library type, or analyse them in separate runs
“GoPeaks needs paired-end reads”	GoPeaks cannot use single-end data	Choose SEACR or MACS (Chapter 7)
“Comparison … names condition ‘…’, but no … sample has that condition”	A comparison does not match the samples	Check the conditions on the Samples page

Common design notes, which do not stop the run:

• “only 1 condition — no differential analysis will run for this mark”: give the samples their real conditions (Chapter 4).
• “no biological replicates for … — differential results are exploratory”: with one sample per condition, variation cannot be estimated (Chapter 2).
• “No input/IgG control samples”: peaks will be called without background, which gives more false peaks in open chromatin (Chapter 7).
• “… is filed as “…” in the public archive, but this run analyses it as …”: you may have imported samples of another assay from the same GEO series (Chapter 3).
• “… has 2 samples per group: dmrseq can compare it with only 2 sample-swapped versions of the data”: with two methylation samples per group, few or no DMRs is a common, honest result (Chapter 17).

19.3 Importing and uploading

Table 19.2: Common import and upload messages.

Message (shortened)	What to do
“The archives (GEO/ENA) did not answer within … s. ENA is sometimes slow; try again”	Click Look up again; replies already received are kept
“… a controlled-access study (dbGaP/EGA) … cannot be imported here”	Apply for access to the data; then upload it yourself
“GEO lists no sequencing runs for this sample (processed data only)”	The sample has no raw reads in the archives
“Storage quota exceeded: … GB used of … GB”	Delete files or runs you no longer need, or import fewer samples
“… is not a file type EpiNexus reads”	Check the file ending (Appendix C)
“This file is being imported from a public archive. Wait for the import to finish”	Wait, or cancel the import
“Upload incomplete: expected … bytes, found …”	Upload the file again

19.4 The run fails

No compute machine, time limit, memory. Each run gets its own compute machine. The run page then says, for example: “EpiNexus couldn’t get a compute machine for this run, so it didn’t start and nothing was analysed”, “The analysis reached the time limit for one run” or “The analysis ran out of memory on its compute machine”. Ask the EpiNexus team; a large run may need a longer limit or a larger machine. While a run waits for a machine, its step reads “Waiting for a compute machine — the run starts automatically when one is free”.

A tool failed on a file. The message names the step and gives a hint, then the tool’s own last lines. The common hints are:

• “R1 and R2 contain different numbers of reads (a mate file is truncated, or the two files are not a pair)”: check that read 1 and read 2 belong together, and upload them again.
• “a FASTQ file is truncated or corrupt (the upload may be incomplete)”: upload the file again.
• “a file named .gz is not gzip-compressed” or “a FASTQ file is malformed”: the file is not what its name says.

If the alignment step fails, the later steps are not run.

The run is too large. “This run needs ~… GB of scratch disk for … samples, more than this server allows”: split the samples into smaller runs, or ask the team.

19.5 A step was skipped

A skipped step is not an error. It means the step did not apply to this run.

Table 19.3: Common reasons why a step was skipped.

Step	Reason shown	What it means
Differential analysis	“the samples have fewer than two conditions to compare”	Give the samples their conditions (Chapter 9)
GO enrichment	“GO annotation is not staged for …”	Ask the team to install it
Super-enhancers	“no H3K27ac, MED1 or BRD4 samples”	Super-enhancers need an active-enhancer mark (Chapter 13)
Enhancer–gene links	“ABC needs an activity measure: chromatin accessibility (ATAC-seq or DNase-seq) or H3K27ac”	Other marks are not linked (Chapter 13)
Integration	“needs differential results for H3K27ac and H3K27me3 in this run”	Analyse both marks, with the same conditions, in one run
Motifs in changed regions	“… regions — at least 50 are needed for a motif test”	The set is too small (Chapter 12)
Signal profiles	“needs signal tracks, which only FASTQ runs produce”	Runs from BAM files have no signal tracks

19.6 The results look wrong or empty

All samples fail QC. Read which metrics fail, and look at the other signs: enrichment, replicate agreement and a result you can predict. Low library complexity, for example, costs depth but does not make the results wrong (Chapter 16). If the run’s QC gate excludes failing samples, the run’s warnings name the samples it left out (Chapter 6).

No differential regions, or very few. Check the design notes: one condition, no replicates, or only two replicates per condition all limit what a test can find (Chapter 2). Look at the MA plot (Chapter 9): if the cloud of unchanged regions is not centred on zero, the normalisation does not fit the data.

“Spike-in … was requested but no sample reached … spike-in fragments”: none of the samples had enough spike-in reads, so EpiNexus used ordinary normalisation instead. The run, its warnings and its methods text say so (Chapter 10).

No DMRs. With two samples per group, dmrseq can compare the result with only two sample-swapped versions of the data. Modest differences, or replicates that differ from each other, then often give no DMRs (Chapter 17).

Few reproducible (IDR) peaks. Compare the number with ENCODE’s expectation for the assay. For ATAC-seq in EpiNexus 1.2, the IDR set can be much smaller than expected; keep the default regions for the differential analysis (Chapter 16).

Strange GO terms. Check the genes behind each term. Terms from one gene family, or from a few genes, say little about the experiment (Chapter 11).

Many gained regions when most sites close. Check the normalisation: scaling by reads in peaks can shift all fold changes when many regions change one way (Chapter 16).

19.7 Asking for help

When you write to the EpiNexus team, give:

• the project and the run (its name and the first eight characters of its ID);
• the message, copied exactly;
• what you expected, and what you saw.

The run record (Chapter 18) lets the team see exactly what ran.