Incorrect fold_change semantics in pdex >=0.2.0 break cell-eval metrics

[LeonHafner]

Hi,

we identified a bug in cell-eval caused by a change in pdex starting from version >= 0.2.0.

Previously, the fold_change column in pdex output contained linear fold changes computed as target_mean / ref_mean. In newer versions, pdex now outputs log2 fold changes, but the column name remains fold_change.

cell-eval expects linear fold changes unless a log2_fold_change column is present. If that column is missing, it computes log2 values from fold_change. Because pdex now already provides log2-transformed values under the same column name, this results in applying log2 twice:

cell-eval/src/cell_eval/_types/_de.py

Lines 100 to 111 in 2db6b9c

	# Add log2 fold change columns if not present
	if self.log2_fold_change_col not in self.data.columns:
	self.data = self.data.with_columns(
	pl.col(self.fold_change_col)
	.log(base=2)
	.alias(self.log2_fold_change_col)
	.fill_nan(0.0)
	).with_columns(
	pl.col(self.log2_fold_change_col)
	.abs()
	.alias(self.abs_log2_fold_change_col)
	)

• First transformation (in pdex): FC → log2(FC)
• Second transformation (in cell-eval): log2(FC) → log2(log2(FC))

This leads to:

• Values between 0 and 1 becoming negative after the first log2
• Invalid values (NaN) after the second log2
• NaNs being replaced with 0.0 in cell-eval (see line 106 above)

As a result, roughly 50% of fold change values are set to zero, which significantly affects downstream metrics, including:

• overlap_at_*
• precision_at_*
• de_direction_match

Two ways to fix that:

1. Revert pdex to output linear fold changes in fold_change column, maintaining current naming
2. Alternatively, update pdex by changing the name of the output column from fold_change to log2_fold_change

The second option may introduce compatibility issues with downstream tools expecting the fold_change column.

Thanks

[LeonHafner]

Slacked with @alexdobin and was asked to loop in @sullivanj91 and @noamteyssier. Thanks guys!

[noamteyssier]

@LeonHafner @alexdobin @sullivanj91

third option (and what I would suggest is done) is to update cell-eval to use fold_change column as-is as log2 without reverting pdex. I don't think there are usages of fold-change without the expectation that it is log.

[sullivanj91]

@LeonHafner @alexdobin @sullivanj91

third option (and what I would suggest is done) is to update cell-eval to use fold_change column as-is as log2 without reverting pdex. I don't think there are usages of fold-change without the expectation that it is log.

confirmed with @nick-youngblut that we updated our data loaders to accommodate the log2 fold change already, so I'm supportive of option #3.

[LeonHafner]

Totally agree that cell-eval is the easier fix and log2FC is what people actually want anyway.

The thing that bugs me is the column name. DESeq2 calls it log2FoldChange, edgeR uses logFC, scanpy uses logfoldchanges, so across the field, log-transformed values are explicitly labeled as logs. Anyone reading the column in pdex is going to assume it's linear FC. Renaming in pdex is more annoying short-term, but it stops people running into this same confusion down the line.
That's why I'd push for renaming the pdex column to log2_fold_change.

[alexdobin]

I agree with Leon that it would be best to change the name of the column to log2_fold_change - this will avoid confusion and potential silent errors. We could also have both fold_change (old values) and log2_fold_change columns for reverse compatibility.

[LeonHafner]

I agree, having a dual-column approach for the next release cycle would be good.

Concrete proposal for the pdex release cycle:

0.2.2 — add log2_fold_change and deprecate fold_change

• Add log2_fold_change column (accurately named, holds the log2 values)
• Keep fold_change as-is (still log2 values, unchanged from 0.2.x)
• Mark fold_change as deprecated in the changelog and README, pointing users to log2_fold_change
• Update cell-eval in the same cycle to read log2_fold_change

0.3.0 — remove fold_change

• Drop the column entirely

The reason for keeping fold_change unchanged in 0.2.2 (rather than flipping it back to linear) is that tools like the data loaders @sullivanj91 mentioned above are currently built against 0.2.x and are reading log2 values from that column. If we restore linear semantics, those tools would silently break before we have a chance to update them. Leaving it as log2 for one release cycle gives downstream tools a window to migrate cleanly, with the deprecation warning pointing them at the right column. Then 0.3.0 removes it and anyone who hasn't migrated gets a loud KeyError instead of silent corruption.

Happy to handle the pdex PR and the matching cell-eval update if you agree with that.

[alexdobin]

I agree with Leon's proposal; it's a good compromise.

[sullivanj91]

sounds like a good plan to me! thanks Leon