FACCT-CNN

FACCT-CNN (Fixed-Anchor Counterfactual Consistency Training for CNNs) is a research workflow for detecting and suppressing non-chemical shortcuts in full-chromatogram classification.

A highly accurate CNN may classify chromatograms from baseline curvature, boundary effects, detector noise, or other nuisance signals. FACCT-CNN separates each aligned chromatogram into an estimated background, a positive peak component, and a non-positive remainder for evidence auditing while keeping the measured raw signal as the CNN input. It then constructs component-swapped counterfactuals and trains a shared CNN to preserve its prediction when the background is changed. Every derived input reuses the recipient sample's original q95 normalization anchor, preventing intervention-dependent renormalization from becoming an alternative signal.

Main capabilities

• Raw full-chromatogram Standard and Consistency CNN training.
• One-time AsLS decomposition used for auditing, not for replacing the CNN input.
• Fixed-anchor opposite-class background and peak interventions.
• Same-class donor controls and AsLS/swap-strength sensitivity analysis.
• Independently retrained raw, peak-only, and background-only representation audits.
• Held-out, non-overlapping individual-peak ablation.
• Locked-model external validation without refitting or threshold tuning.
• TXT and AIA/ANDI NetCDF3 CDF input, including mixed-format external sets.
• Publication-oriented CSV tables and PDF/PNG figures.

Installation

Python 3.9 or newer is supported; a fresh virtual environment is strongly recommended.

git clone https://github.com/christalho22/FACCT-CNN.git
cd FACCT-CNN
python -m venv .venv

Windows PowerShell:

.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install -e .

For NVIDIA GPU training, install the PyTorch build matching your CUDA version from the official PyTorch instructions before pip install -e ..

Input layout

data_root/
  Class_A/
    sample_01.txt
    sample_02.cdf
  Class_B/
    sample_01.txt
    sample_02.cdf

TXT files must contain retention time and detector response as the first two numeric columns. CDF files must follow AIA/ANDI NetCDF3 conventions. Class names and sample counts are provided on the command line; no medicine-specific labels are hard-coded.

1. Train and audit one binary task

python scripts\run_facct.py `
  --data-root D:\chromatograms `
  --class0 Class_A --class1 Class_B `
  --expected0 15 --expected1 15 `
  --output-dir D:\facct_results\A_vs_B `
  --device cuda

--expected0 and --expected1 are optional integrity checks. Use --device cpu if CUDA is unavailable. The full publication protocol uses 5-fold cross-validation repeated five times and can take hours; run python scripts/run_facct.py --help for all options.

2. Sensitivity and donor-control audit

python scripts\run_sensitivity.py `
  --data-root D:\chromatograms `
  --result-dir D:\facct_results\A_vs_B `
  --output-dir D:\facct_results\A_vs_B_sensitivity `
  --class0 Class_A --class1 Class_B `
  --expected0 15 --expected1 15 `
  --device cuda

This locked-model audit varies AsLS parameters and swap strength and compares opposite-class with same-class donors.

3. Individual-peak audit

python scripts\run_peak_audit.py `
  --result-dir D:\facct_results\A_vs_B `
  --output-dir D:\facct_results\A_vs_B_peaks `
  --class0 Class_A --class1 Class_B `
  --expected0 15 --expected1 15 `
  --source0-dir D:\chromatograms\Class_A `
  --source1-dir D:\chromatograms\Class_B `
  --device cuda

Peak apices are detected from the pooled positive residual without labels or model saliency. Non-overlapping peak windows are deleted one at a time and evaluated only on held-out outer-fold samples.

4. Locked external validation

python scripts\run_external_validation.py `
  --result-dir D:\facct_results\A_vs_B `
  --class0-name Class_A --class1-name Class_B `
  --class0-dir D:\external\Class_A `
  --class1-dir D:\external\Class_B `
  --output-dir D:\facct_results\A_vs_B_external `
  --device cuda

External samples are never used for refitting, model selection, or threshold tuning. If TXT and CDF detector units differ, use evidence-based --txt-response-scale or --cdf-response-scale; the script stops when component mixing remains unit-incompatible.

Output structure

The training command creates:

• config.json and sample_manifest.csv for provenance;
• preprocessed_chromatograms.npz with aligned signals and cached decomposition;
• models/ with outer-fold Standard and Consistency checkpoints;
• tables/ with performance, sufficiency, nuisance-only, and intervention summaries;
• figures/ with PDF and PNG diagnostics;
• automatic_interpretation_guide.txt.

Reproducibility and interpretation

• Default random seed: 2026.
• CNN input: aligned measured detector response; no AsLS subtraction or Savitzky-Golay smoothing.
• Audit identity: raw = background + positive peaks + remainder.
• Counterfactual normalization: the recipient's original q95 anchor is fixed for the raw input and every derived intervention.
• Same-class donor swaps are negative controls for generic reconstruction or donor replacement effects.
• Peak importance denotes model-level causal control at a retention-time apex, not chemical identification. Structural assignments require independent analytical confirmation.

See docs/METHODS.md for the computational protocol and scope of inference.

Quick software check

python examples\make_synthetic_data.py --output examples\synthetic_data
python -m pytest -q

The synthetic data are for software verification only and must not be used to support scientific claims.

License

MIT License. See LICENSE.