Node reference

Bulk RNA-seq nodes.

Bulk RNA-seq from the file your facility gave you: a generic count matrix, featureCounts or STAR ReadsPerGene output, or Kallisto abundance.tsv / Salmon quant.sf (one file per sample, combined with Merge Data). Attach the sample sheet with Merge Cell Meta or Define Groups, run sample-level QC, filter lowly expressed genes, normalize, and test with PyDESeq2 (t-test fallback). GSEA / ORA and the PROGENy / Hallmark / CollecTRI activity nodes follow.

09 nodesCategory · bulkin 3 templates

Common pitfalls

Genes-as-rows count matrices need transpose. Most bulk exports are genes × samples; Load Count Matrix expects samples × genes unless told otherwise.

Differential Expression wants raw counts. Bulk Normalize always keeps them in layers["counts"]; PyDESeq2 reads those, not the normalised values.

The condition column comes from the sample sheet. Set condition_col and the reference level in Differential Expression after Merge Cell Meta has attached it.

Load Count Matrix

loadCountMatrix

Load a generic bulk count matrix (CSV/TSV/H5AD). Genes × samples typically — enable Transpose.

Node LibraryBulk RNA-seq

OutAnnData (samples × genes)

Parameters (4)

Name	Type	Default	Description
`file_path`	file (.csv, .tsv, .txt, .h5ad)	—	Path to count matrix.
`transpose`	checkbox	`true`	Convert genes-rows → samples-rows.
`meta_file`	file (.csv, .tsv, .txt)	—	Optional sample-metadata CSV/TSV. Adds extra columns into adata.obs joined on sample name.
`sample_col`	text	—	Column in meta_file that contains sample identifiers (matched against obs_names). Empty = first column of meta_file.

Load featureCounts

loadFeatureCounts

featureCounts .txt or STAR ReadsPerGene.out.tab. Auto-handles header lines and STAR strand selection.

Node LibraryBulk RNA-seq

OutAnnData (samples × genes)

Parameters (4)

Name	Type	Default	Description
`file_path`	file (.txt, .tsv, .tab)	—	featureCounts or STAR output.
`strand_column`	select	`1`	STAR ReadsPerGene count column: 1=unstranded, 2=forward-stranded, 3=reverse-stranded. Numeric values are canonical; legacy strings such as 'auto' (treated as unstranded) and '2 - Forward-stranded' are accepted safely. Ignored for featureCounts matrices.
`meta_file`	file (.csv, .tsv, .txt)	—	Optional sample-metadata CSV/TSV. Adds columns into adata.obs when sample names match.
`sample_col`	text	—	Column in meta_file that contains sample identifiers (matched against obs_names). Empty = first column.

Load Abundance (Kallisto/Salmon)

loadAbundancesince v0.9.0-beta.41

Load Kallisto abundance.tsv or Salmon quant.sf. Format auto-detected. Single-file loader; merge per-sample with Merge Data.

Node LibraryBulk RNA-seq

OutAnnData (1 sample × N transcripts)

Parameters (7)

Name	Type	Default	Description
`file_path`	file (.tsv, .sf, .txt)	—	Path to abundance.tsv or quant.sf.
`directory_path`	directory	—	Folder of per-sample subdirectories, each containing abundance.tsv or quant.sf. Loads every sample into one AnnData; sample names come from the subdirectory names.
`value_type`	select	`tpm`	"tpm" (viz) or "counts" (DESeq2).
`sample_name`	text	—	Override obs_name (empty = file stem).
`tx2gene_file`	file (.csv, .tsv, .txt)	—	Optional 2-column CSV/TSV mapping transcript id (first column) to gene id (second column). When given, transcript rows are summed into genes: TPM is summed, counts follow counts_from_abundance, and effective length becomes the abundance-weighted average per gene. A header row is detected and skipped.
`counts_from_abundance`	select	`no`	'no' = gene count is the sum of the transcript counts. 'lengthScaledTPM' = tximport's length-scaled counts (gene TPM × gene length, rescaled so each sample's total matches the original count total). Requires tx2gene_file.
`round_counts`	checkbox	`true`	Round layers['counts'] to integers. Kallisto/Salmon report fractional counts and PyDESeq2 refuses them, so this is on by default.

Bulk QC

bulkQC

Sample-level QC — library size, gene count, IQR-based outlier detection.

Node LibraryBulk RNA-seq

InAnnData

OutAnnData (obs library_size/n_genes_detected/is_outlier)

Parameters (4)

Name	Type	Default	Description
`min_library_size`	number	`100000`	Min total reads per sample.
`min_detected_genes`	number	`500`	Minimum number of genes with at least 1 count to keep a sample.
`min_count_threshold`	number	`1`	Per-gene count floor used when computing 'detected_genes' (a gene must have at least this many counts to be counted as detected).
`mode`	select	`label`	"label" or "filter".

Bulk Normalize

bulkNormalize

CPM / TMM / DESeq2 size-factor / VST. Raw counts always saved to layers["counts"].

Node LibraryBulk RNA-seq

InAnnData (raw counts)

OutAnnData (normalized X, layers["counts"])

Parameters (4)

Name	Type	Default	Description
`method`	select	`cpm`	cpm/tmm/deseq2/vst.
`log_transform`	checkbox	`true`	log1p after normalization.
`pseudocount`	number	`1.0`	Pseudocount added before log2 (avoids log(0)). 1.0 is standard.
`condition_col`	obs column	—	Optional obs column used as the PyDESeq2 design factor for VST. Ignored by CPM, TMM, and the standalone DESeq2 size-factor normalization. Empty uses a synthetic single group; a non-empty missing column is rejected.

Filter Low Expressed

filterLowExpressed

Remove lowly expressed genes (e.g. CPM > 1 in ≥2 samples).

Node LibraryBulk RNA-seq

InAnnData (normalized)

OutAnnData (filtered)

Parameters (7)

Name	Type	Default	Description
`mode`	select	`cpm`	'cpm' = CPM >= min_cpm in >= min_samples samples (the historical rule). 'filter_by_expr' = edgeR filterByExpr equivalent using min_count / min_total_count / group_col.
`min_cpm`	number	`1.0`	Min CPM threshold.
`min_samples`	number	`2`	Min samples passing threshold.
`group_col`	obs column	—	[filter_by_expr mode] obs column whose smallest level size becomes the required number of samples. Empty = treat all samples as one group (edgeR's behaviour without a group/design).
`min_count`	number	`10`	[filter_by_expr mode] Reads required at the median library size; the CPM cutoff is derived as min_count / median_library_size * 1e6.
`min_total_count`	number	`15`	[filter_by_expr mode] Minimum summed count across all samples for a gene to be kept.
`use_counts_layer`	checkbox	`true`	If True, read raw counts from adata.layers['counts'] for the CPM calculation (preserves adata.X if it's already normalized/log).

Differential Expression

differentialExpression

PyDESeq2 differential expression between two conditions (t-test fallback).

Node LibraryBulk RNA-seq

InAnnData (with raw counts in layers["counts"])

OutAnnData (uns["de_results"])

Parameters (8)

Name	Type	Default	Description
`condition_col`	obs column	—	Column in adata.obs containing group labels (e.g., 'condition', 'treatment').
`reference_group`	obs value	—	Reference (denominator).
`test_group`	obs value	—	Test/comparison group name (numerator). E.g., 'Treated', 'KO'. Positive log2FC = higher in test_group.
`covariates`	text	—	Comma-separated adata.obs column names added to the design ahead of the condition factor, e.g. 'donor' for a paired design or 'batch, age'. Numeric columns with more than two distinct values become continuous factors; everything else is categorical. Empty = single-factor design.
`lfc_shrink`	checkbox	`true`	Apply PyDESeq2's apeGLM shrinkage to the tested coefficient. log2fc then holds the shrunken estimate and log2fc_mle the unshrunken one; p-values are unchanged. Turn off to report raw maximum-likelihood fold changes.
`alpha`	number	`0.05`	FDR threshold.
`lfc_threshold`	number	`1.0`	Absolute log2 fold-change threshold (slider 0 .. 4) for marking genes as 'significant' in de_results.
`min_count`	number	`10`	Pre-filter genes whose summed raw count across all samples is below this. Lower = keep more low-expressed genes (and risk more false positives).

GSEA / ORA

gsea

Bulk pathway enrichment (gseapy) — preranked GSEA or ORA.

Node LibraryscRNA-seqBulk RNA-seq

InAnnData (with de_results)

OutAnnData (uns["gsea_results"])

Parameters (11)

Name	Type	Default	Description
`analysis_type`	select	`ora`	Analysis method: 'ora' (over-representation, significant genes only) or 'gsea' (preranked, all genes).
`ranking_metric`	select	`signed_p`	[gsea] Gene ranking statistic: 'signed_p' (-log10(pvalue) × sign(log2fc), the historical default), 'stat' (DESeq2 Wald statistic), or 'log2fc'. 'stat' falls back to 'signed_p' with a warning when the DE source has no Wald column (e.g. single-cell rank_genes_groups).
`ora_background`	select	`tested_genes`	[ora] Universe for the over-representation test: 'tested_genes' (the genes present in de_results — the standard choice) or 'genome' (Enrichr's implicit whole-genome background). A universe smaller than 50 genes falls back to 'genome' with a warning.
`gene_sets`	select	`GO_Biological_Process_2023`	Gene set library.
`gene_sets_custom`	text	—	Free-form library name(s). Only used when gene_sets = '__custom__'. Comma-separated values run multi-library enrichment.
`organism`	select	`Human`	"Human" or "Mouse".
`cluster`	text	—	Single-cell only: which group in adata.uns['rank_genes_groups'] to enrich. Empty = first group. Ignored for bulk (de_results) input.
`alpha`	number	`0.05`	FDR / p-value significance threshold for selecting genes (ORA) or reporting pathways (GSEA).
`min_size`	number	`15`	Minimum number of genes a gene set must have to be tested.
`max_size`	number	`500`	Maximum gene set size — filters out generic ontology terms with thousands of genes.
`n_permutations`	number	`1000`	Number of permutations for GSEA significance estimation. 1000 is the standard.

Bulk Visualization

bulkVisualization

Volcano, MA, DEG heatmap, sample distance, library size.

Node LibraryBulk RNA-seq

InAnnData (bulk + DE)

OutPNG image

Plots (7)volcanomaheatmapsample_distsample_corrpcalibrary_size

Parameters (11)

Name	Type	Default	Description
`plot_type`	text	`volcano`	volcano/ma/heatmap/sample_dist/library_size.
`y_axis`	select	`padj`	[volcano] Which p-value column drives the y axis, the point colours and the dashed cutoff line: 'padj' (default) or 'pvalue'. All three used to disagree — y was the raw p-value while colours and the line came from padj.
`scale_rows`	checkbox	`true`	[heatmap] Convert each gene row to a z-score before plotting. Off = plot the matrix as-is (only meaningful when X is already centred).
`metric`	select	`euclidean`	[sample_dist] 'euclidean' (default) or 'pearson' (plots 1 - Pearson r).
`color_by`	text	—	[pca] obs column used to colour and legend the PCA points. Empty = a single colour.
`n_top_genes`	number	`50`	Top DEGs in heatmap.
`lfc_threshold`	number	`1.0`	log2FC threshold for highlighting.
`alpha`	number	`0.05`	Adjusted p-value (padj) threshold for calling genes significant. Applies to volcano, ma_plot, and heatmap gene selection.
`n_label`	number	`20`	[volcano/ma] Number of top significant genes to label with their names.
`show_gene_labels`	checkbox	`true`	[volcano/ma] Draw gene name labels on the most significant points.
`use_plotly`	checkbox	`false`	[volcano/ma] Render an interactive Plotly figure instead of a static matplotlib PNG.

Spatial

Methylation