Troubleshooting¶

`mmseqs: command not found`¶

evaluate-splits needs MMseqs2 on your PATH; it is not a Python dependency and pip will not install it. Take a precompiled binary — see installing MMseqs2.

evaluate-classes does not need it, so if you only want the class checks you can skip this entirely.

Everything came back `Unknown`¶

Your classes are smaller than 250 sequences each, which is the floor below which nothing is scored. This is not a failure — it is the tool declining to make a claim it cannot support. See how a flag is decided.

It does not mean the dataset is clean. The plots, per-class statistics and descriptive tables are still computed from all of your data, so open the report and compare by eye. That is often enough to see an obvious problem.

The floor is not adjustable. --min-coverage 0 removes the fraction rule for per-position checks but leaves the 250 in place.

The per-position plot stops before my sequences end¶

Expected on variable-length data. Positions are only flagged where at least 25% of each class still reaches them, and the figures draw the flagged window. Everything past it is Unknown.

--min-coverage 0 extends it as far as the 250-sequence floor allows. Read the window section first — the reason for the rule is not sample size, and widening it changes what the numbers mean.

MMseqs2 runs out of memory¶

Cap the prefilter structures:

gb-qc evaluate-splits ... --split-memory-limit 10G

Unset, there is no limit. On a large training set this is the thing that exhausts the machine.

`--input a.csv b.csv` does not work¶

Repeat the option instead:

gb-qc evaluate-classes --input a.csv --input b.csv --out-folder qc-out

Same for --sequence-column and --label-list. This catches everyone once.

Several `--input` files did not become several classes¶

For CSV/TSV they are pooled and classes come from the label column. One file or ten, the classes are whatever is in --label-column.

FASTA is the opposite: it carries no labels, so each file is a class and its filename stem becomes the label. See fasta-classes.

It refused to infer my classes¶

--label-list infer stops at 50 distinct values. Every pair of classes gets its own comparison, so the work is quadratic — 600 values is 179,700 reports — and a column with that many values is nearly always a continuous target or the sequence column, not a label column.

Three ways on, and the error names all three: --regression splits a numeric target at its median, --label-column points at a different column, and --label-list names the classes to compare. An explicit list is not capped.

My class labels are not the directory names I expected¶

Directory names are lowercased and stripped of characters unsafe on some filesystems, then ordered alphabetically — so the same dataset gives the same paths whatever order you passed the files in. noncodingRNA becomes noncodingrna. Labels shown inside the reports keep their original spelling.

If two names would collide, gb-qc makes them unique and warns which name it used. Worth grepping the log for at scale.

`--regression` exited with an error¶

The label column is split at its median into high and low. If that does not produce two non-empty classes — a constant column, or one that is mostly a single value — there is nothing to compare and the run stops. Non-numeric rows are dropped with a warning first, so check how many survived.

A check fails but I think it is the biology¶

Quite likely, and the tool cannot tell the difference. A splice-site dataset should fail its per-position check at the splice site — see hidden-motif.

What the flag tells you is that a trivial model does well on that feature. Whether that is signal or leakage is your call. Either way the useful move is the same: treat the flagged feature's AU-ROC as the floor your model has to beat, and report it.

Can I get the raw numbers?¶

Add json to --report-types for per-class statistics — counts, GC, lengths, base and dinucleotide frequencies — at <out-folder>/class/<column>/per-class/<class>.json.

The gb-qc-report.csv beside every report carries every flag and score, including the per-base and per-position breakdown. For leakage, mmseqs/mmseqs2_search_result.tsv has every pair at or above the similarity threshold. See using it in CI for the CSV's shape.