Troubleshooting, versions and citation

Common problems#

Version notices#

This handbook documents version 0.34.0. Confirm its platform packages are available on the official release page before downloading.

• 0.34.0: Pooled-effect rem_padj is now BH-adjusted across every estimable pooled test, including opposite-sign and neutral genes. Older pooled-effect adjusted values need recomputation. The distinct matching-sign combined-p family, meta_sig, raw pooled estimates and enrichment selection keep their prior definitions. The meta ledger records the executed contrast, study eligibility and both family sizes; reports distinguish combined evidence from independent replication. Synthetic and independent numerical checks support this correction; the nine bundled biological datasets have not been rerun under 0.34.0. Direct Entrez IDs on OrgDb routes now retain their mapping; rerun an older enrichment that failed there. Custom ORA reports now separate supplied from effective annotated populations without changing their selection or p-values. See cross-study methods, upgrade guidance and the 0.34.0 release record.
• 0.33.0: KEGG enrichment now runs for 17 catalogue organisms whose identity check it failed, both bundled Fusarium datasets among them, and organisms without an annotation package get annotation-transfer enrichment from STRING, with eggNOG-mapper and KofamScan imports; these change enrichment output, while counts and differential-expression tables are unchanged. Two bundled datasets were added. See the 0.33.0 release notes.
• 0.32.1: documentation, command-line and interface corrections; analysis outputs are unchanged from 0.32.0. A config/config.yaml that cannot be read or does not validate now makes bulkseq exit 3 instead of failing with exit 1, and bulkseq check reports the most severe finding as its overall status whatever the order of the findings. See the 0.32.1 release notes.
• 0.32.0: Count-matrix imports reject malformed, negative and undeclared fractional cells before conversion, and microarray probes assigned to multiple distinct genes are excluded before MaxMean collapse. GSEA admits an additional missing-adjusted-p row only with a finite route-specific rank and finite raw p-value, while leaving the ORA family unchanged; legacy adjusted-p-finite rows retain their supported eligibility. Fallback KEGG rankings reduce source aliases once in final GeneID space, so an already-ranked alias group can change. edgeR, limma-voom and microarray limma now use positional numeric contrasts, preserving distinct condition labels that share an R-safe spelling and preventing a metadata grp column from shadowing the configured contrast factor. Cross-study enrichment applies the configured per-study FDR and absolute log2-fold-change thresholds before the shared-universe and accepted-mapping restrictions; exact zero remains neutral at a zero effect threshold. Explicitly admitted RSEM/tximport estimates retain the documented rounding route. Microarray mapping evidence retains every candidate and reports ambiguous, unknown and missing-annotation exclusions. Synthetic regressions establish these contracts; no real count-matrix, GEO microarray, enrichment or meta-analysis study was rerun under 0.32.0. See the 0.32.0 release notes. The 0.32.0 interface update gives critical accession, design, output, figure-preview and PPI edge-filter controls specific Qt accessible names and descriptions, associates composite labels with their fields, and restores Tab navigation from the multiline accession editor. The current-view edge filter maps slider values 0–100 to displayed confidence 0.00–1.00 without rebuilding the network. Focused tests query the Qt accessibility interface and keyboard focus; no native screen-reader session has been performed.
• 0.31.0: several outputs changed. The edgeR and limma-voom routes now carry ncbi_geneid, so KEGG enrichment reaches an organism keyed on NCBI GeneIDs that has no OrgDb instead of returning empty tables; those routes and microarray limma also gain the padj_lfc_ge_threshold companion column, computed with each method's own interval test (edgeR glmTreat, limma and limma-voom treat), and write pca_coordinates.csv, so the covariate screen (check 23) now runs on every locally fitted engine and can reach a different verdict on each. Check 23 replaces its fixed adjusted-R² floor of 0.5 with the value only 5% of random label assignments reach at that number of samples and groups. The fixed floor was the stricter of the two from seven samples upward in two groups, so a sample-sheet column that 0.30.1 reported as within chance can now come back review-required. limma-voom now reports lfcSE. Check 23 also stops comparing the sheet's descriptive label columns, so a study whose sample titles happened to group the way the contrast does can lose a review-required finding it previously reported. Sample sheets may carry an optional library_name column, which is descriptive only and changes no result. Check 08 reports review-required for a DESeq2 interaction design, naming the coefficient actually tested; check 10 escalates when the KEGG key form cannot be measured or a GeneID-keyed organism is reached from a route without usable GeneIDs; a project configuring more than one contrast now states which one was analysed; and the wording of checks 21 and 23 changed. Re-run affected analyses; see 0.31.0.
• 0.30.1: command-line runs synchronize outdated workflow copies. Record the actual software/workflow used; see 0.30.1.
• 0.30.0: per-sample strandedness and an organism-specific KEGG GeneID bridge changed relevant outputs. Mixed-library projects and affected KEGG analyses require renewed review; see 0.30.0.
• 0.29.0: changes included signed-statistic GSEA ranking, direction-balanced STRING seeds, meta p-value calculation and figure scales/coordinates. Earlier enrichment, network membership and figure ordering can differ; see 0.29.0.
• Before 0.26.6: meta-analysis adjusted the wrong reported family before removing direction-discordant genes. Re-run affected meta-analysis outputs; see the 0.26.6 release.

Citation and license#

BulkSeq Studio is distributed under the MIT License. Cite the exact software version that produced your analysis and its release record; include the exported method/tool references applicable to your route.

Report a problem#

Use the issue tracker with the application version, platform, input route, operation and sanitized error. Remove private paths, sample/donor identifiers and restricted study content. A minimal synthetic example is preferable to sharing raw research data.