cfREF

A reference-conditioned neural network for cross-cohort cancer detection using cell-free DNA fragmentomics.

cfREF investigates how non-cancer reference samples from a target cohort can inform cancer detection when fragmentation profiles differ between development and target populations.

Release status

This repository is being prepared for the cfREF 0.2.0a1 source-code release.

The initial release is intended to provide training and prediction code, synthetic examples, and software tests. It does not include pretrained model checkpoints or all materials required to reproduce the manuscript.

The software starts from precomputed feature matrices or fragment counts. It does not implement a complete FASTQ/BAM processing pipeline.

Model description

cfREF uses a shared multilayer perceptron to encode query samples and non-cancer reference samples.

For a query embedding e, the prediction head receives:

• The query embedding.
• Its difference from the reference embedding mean.
• Its difference from the reference mean divided by the reference embedding standard deviation.

The reference set therefore conditions predictions without updating network parameters at inference.

The model outputs a logit score. Binary predictions use a threshold estimated from source-cohort non-cancer samples. Scores are not calibrated cancer probabilities.

Intended use

cfREF is intended for researchers studying:

• Cross-cohort cfDNA cancer classification.
• Transferability of source-derived decision thresholds.
• Reference-conditioned prediction.
• Effects of reference-set size and composition.
• Sensitivity–specificity trade-offs under cohort shift.

It is a research implementation and has not been validated for clinical diagnosis or population screening.

Inputs and outputs

Inputs

Training requires:

• A samples-by-features matrix.
• Binary labels: 0 for non-cancer and 1 for cancer.
• Source-cohort identifiers.
• Ordered feature names.

Prediction requires:

• Query features.
• A separate set of target-cohort non-cancer reference features.
• Feature definitions and ordering consistent with training.

Reference controls must be excluded from evaluation queries. The matrix prediction interface cannot independently verify sample identity or reference labels.

Outputs

• decision_function: reference-conditioned logit scores.
• predict: binary classifications using the source-derived threshold.
• save and load: persistence of model weights, configuration, feature names, scaling parameters, and threshold.

Installation and quick start

The following instructions apply after the source files have been uploaded.

From the directory containing pyproject.toml:

python -m pip install .
python examples/quickstart.py
python -m unittest discover -s tests -v

If the source is uploaded inside a cfref_package directory, enter that directory first.

Requirements:

• Python >= 3.10
• NumPy >= 1.23
• pandas >= 1.5
• scikit-learn >= 1.2
• PyTorch >= 2.0

The current estimator uses CPU execution.

API example

The arrays below must be prepared by the user; this example illustrates the interface.

from cfref import CFREF

model = CFREF(seed=0)

model.fit(
    X_train,
    y_train,
    source_cohorts,
    feature_names=feature_names,
)

scores = model.decision_function(
    X_query,
    target_controls,
    feature_names=feature_names,
)

predictions = model.predict(
    X_query,
    target_controls,
    feature_names=feature_names,
)

model.save("model.cfref")
restored = CFREF.load("model.cfref")

The estimator fits its scaler on training data and applies the saved parameters during prediction. Do not standardise prediction inputs separately.

Default threshold construction requires at least one source cohort with 23 non-cancer samples.

Training

Training uses source-cohort episodes. Each episode samples non-cancer references and disjoint query samples from the same source cohort.

Default settings include:

• Binary cross-entropy with logits.
• AdamW optimiser.
• Learning rate: 0.001.
• Weight decay: 0.0001.
• Training episodes: 3,000.
• Query batch size: up to 32.
• Hidden dimension: 128.
• Embedding dimension: 48.

The fixed-capacity CFREF estimator and the nested_lopo evaluation workflow are distinct interfaces. Nested evaluation selects network capacity using inner source-cohort splits.

Evaluation

Software workflow

The current nested_lopo implementation evaluates:

1. cfREF.
2. Logistic regression with a fixed source-derived threshold.
3. Logistic regression with target-cohort quantile calibration.

Methods are evaluated on identical query samples within each reference draw.

The moment-standardised logistic-regression comparator reported in the manuscript is not included in the current validation interface.

Manuscript study

The manuscript reports a retrospective evaluation of 361 plasma samples from four published cohorts, comprising 185 cancer and 176 non-cancer samples.

Non-cancer groups include healthy participants and participants with nonmalignant conditions.

In paired nested evaluation using five reference controls, the reported cfREF summaries were:

Target cohort	Specificity	Sensitivity
Cristiano	0.971	0.341
Jiang	0.954	0.333

These values are means across seeds of seed-specific reference-draw medians. They are not prospective clinical estimates or population confidence intervals.

Higher specificity than target-cohort quantile calibration was accompanied by lower sensitivity. Comparisons with moment standardisation and the three-cohort unthinned-count analysis showed that advantages depended on the comparator and source–target configuration.

Limitations

• Performance depends on the source cohorts and target reference population.
• The method does not guarantee a specified specificity or sensitivity in a new population.
• Five reference controls should not be interpreted as a universally sufficient reference-set size.
• Repeated reference draws overlap and are not independent patient cohorts.
• Reference-draw percentiles describe conditional variability, not population confidence intervals.
• The manuscript's four-cohort matrix includes historically thinned Snyder samples. The three-cohort unthinned analysis also changes source composition and does not isolate the effect of thinning.
• Complete patient-level grouping for possible repeated samples was not established in the manuscript.
• Source thresholds use in-sample control scores rather than cross-fitted calibration scores.
• Synthetic software tests do not establish biological or clinical validity.

Reproducibility

Exact numerical reproduction may depend on data ordering, dependency versions, hardware, and thread settings.

The source package includes tests for model persistence, reference-order invariance, fixed scaling, and aspects of the nested evaluation workflow.

Complete manuscript reproduction additionally requires the relevant input matrices, metadata, analysis scripts, and configuration records.

License

A software license has not yet been specified. Public repository access does not itself grant an open-source license.

Associated manuscript

cfREF: a reference-conditioned neural network for cross-cohort cancer detection using cell-free DNA fragmentomics

Publication details and citation information will be added when available.