Changelog

All notable changes to nf-cellbender. The format follows Keep a Changelog. Releases are tagged YY-DDD: the year and the day of the year.

Unreleased

QC report (cellgeni/cellbender/qc@0.2.0): a PCA of CellBender’s latent gene expression of cells, coloured by soup fraction; a soup fraction histogram, overlaid for all samples in MultiQC; a per-gene raw vs corrected plot that lists the features that lost the most UMIs; and a top_ambient_genes summary column.

The iRODS download module is now a registry module, cellgeni/irods/loadcatalog. It skips nothing when no extensions are given, matches extensions literally after a dot (fastq.gz no longer matches fastqXgz), no longer fails when every file in a collection is skipped but does fail on any other grep error, and calls ils2paths.awk through awk -f, so it works even when the executable bit is lost on install.
--ignore_extensions accepts only letters, digits, _, . and - in each extension.
The QC cell probability plot is now CellBender’s own: the UMI curve by barcode rank with the cell probability on a second axis. In MultiQC it replaces the cell probability line graph.
--qc_mode 3 now reads every sample’s CellBender input, not only the 0.2 ones, for the UMI curve and the gene removal plot. It reads 10x .h5 and .mtx inputs in chunks.
CellBender reserves more GPU memory on each retry (8 GB times the attempt), so a sample that ran out of GPU memory moves to a larger card.
Temporarily, CellBender jobs avoid the host farm-gpu0203, whose GPU 3 fails every job with CUDA errors.
The work folder nf-work/ is kept after a successful run (no more cleanup = true), so a finished run can be resumed. Delete it yourself once the results are checked.

The QC cell probability plot and Top-10 min cell prob (mode 3) rank barcodes by their raw UMI count. They used CellBender’s stored barcode order, which is not exactly the UMI order, and drew a solid black block for samples with many intermediate probabilities.

Nextflow 26.04 or later is required (was >=25.04.4, <25.10.0).
--sample_table is renamed --samples, and --output_dir is renamed --outdir. The example tables are now examples/samples*.csv.
Combinations that used to be silently ignored now fail validation:
- --costcode with the gpu queue;
- --estimator, --force_empty_umi_prior or --mapper_preset with CellBender 0.2;
- --exclude_features other than All with 0.2, or All with 0.3;
- only one of --cells / --droplets with 0.2;
- --ignore_extensions without --on_irods.
The QC report is a summary TSV, one PDF and a MultiQC HTML report, replacing train.pdf, prob.pdf, soup.pdf and the per-sample .rds files.
Process names changed: CELLBENDER_REMOVEBACKGROUND is now CELLBENDER:CELLBENDER_REMOVEBACKGROUND_V02 or _V03, and QualityControl is now CELLBENDER_QC plus MULTIQC. Custom configs that select processes by name need updating.

--gpuqueue (gpu, cub22-inference, tiger22-inference; default gpu) and --costcode, which is required on cub and tiger queues, then trimmed, lowercased and passed to LSF as -G.
Parameter and samples table validation with nf-schema 3.0.0. --help, --help <param> and --helpFull are generated from nextflow_schema.json, and running without --samples prints a short usage message.
Separate CellBender 0.2 and 0.3 modules, each pinned to its container, published to the Nextflow registry as cellgeni/cellbender/removebackground_v02 and _v03.
A Python QC module, cellgeni/cellbender/qc, and a MultiQC module, cellgeni/multiqc, both published to the registry.
index/cellbender.csv and index/raw.csv in the output, in the samples table format, and a versions.yml for the whole run.
This documentation site.

Outputs are published through Nextflow workflow outputs instead of per-process publishDir.
Per-process settings live in configs/<process>.config. The pipeline is split into main.nf and a CELLBENDER subworkflow in workflow/main.nf.
On retry only memory grows; CPUs stay fixed.
--ignore_failed now drops a sample only after its final attempt. It used to give up one attempt early.
--estimator and --ignore_extensions default to unset. CellBender 0.3 still uses mckp, and the iRODS skip list is unchanged.
The CellBender GPU request is 8,000 MB of GPU memory (was 6,000 MB).
QC soup fraction statistics are computed over called cells for both CellBender versions.
MultiQC keeps its temporary files in the work folder, which avoids “Disk quota exceeded” from files copied out of /tmp with the wrong group.

--ignore_failed had no effect because the parameter was misspelt (ingore_failed).
The QC now reads the 0.2 log’s “Prior on counts in empty droplets”.
The manifest’s home page and description no longer point to nf-irods-to-fastq.

An nf-core style CellBender module that recognises CellRanger count, multi, ARC and ATAC, STARsolo, .h5 and .mtx inputs by their folder structure, including CellRanger folders without outs/.
A mapper preset that estimates expected cells, total droplets and the low-count threshold from the mapper output (preset.sh, count_cells.awk, sort_cells.awk).
--starsolo_mapper to choose the STARsolo matrix type, and --force_empty_umi_prior.
Several --exclude_features types at once.
IRODS_LOADCATALOG, which downloads whole iRODS collections with retries and restart files and skips unwanted extensions (--ignore_extensions).
An nf-test suite with snapshots, meta.yml files for the modules, and an LSF script that runs the tests in parallel.
New example tables and scripts, and an updated resume/ script.

The samples table is a .tsv file, and input and output are carried in a single channel so samples cannot be mixed up.
Execution reports go to execution-reports/, and the work folder is called nf-work.
The help message, parameter handling and resources of the CellBender process were reworked.

Clearer handling of the samples file, file permissions, and a re-enabled work folder cleanup.
README and RESUME-cellbender updates, including the missing -r flag.

First release: CellBender on farm22 through Nextflow for a table of samples, with the R QC script, a Dockerfile, a resume script and example tables.