JTF-WaveNet is dual-domain (time adn fequency) deep learning model designed for processing complex-valued NMR (Nuclear Magnetic Resonance) spectra. It employs a WaveNet-inspired architecture to reconstruct high-quality spectra from paired inputs (e.g., high-field and low-field spectra) while providing per-point uncertainty estimates.
JTF-WaveNet addresses the challenge of reconstructing NMR spectra affected by artifacts such as vibrations or low signal-to-noise ratios. The model takes paired complex-valued spectra as input and outputs:
- Reconstructed Spectrum: Artifacts corrected HRR spectrum.
- Uncertainty Estimates: Per-point standard deviation (σ) values that quantify the model's confidence in each prediction.
The training process is divided into two stages to ensure stability and interpretability:
- Stage 1: Trains the reconstruction (mean) branch using Mean Squared Error (MSE).
- Stage 2: Trains the uncertainty branch while keeping the mean branch frozen, using uncertainty-aware loss functions.
This approach enables physically meaningful uncertainty quantification, which is crucial for scientific applications requiring reliable error bounds.
Reproducing the manuscript figures or analysing your own data: see Analysis and analysis/README.md.
Add badges from somewhere like: shields.io
Clone the project
git clone https://github.com/your-repo/JTF-WaveNet.gitGo to the project directory:
cd JTF-WaveNetCreate virtual environment adn activate it:
# macOS/Linux
python3.10 -m venv .venv
source .venv/bin/activate
# Windows
py -3.10 -m venv .venv
.venv\Scripts\activateUpgrade pip and install build tools:
python -m pip install --upgrade pip setuptools wheelInstall the package in editable mode:
pip install -e .Verify the installation:
python -c "import jtf_wavenet; print('JTF-WaveNet imported successfully')"For additional features, install optional dependencies:
# Development tools
pip install -e ".[dev]"
# Visualization enhancements
pip install -e ".[viz]"
# Machine learning utilities
pip install -e ".[ml]"
# Experiment tracking
pip install -e ".[tracking]"
# Web applications
pip install -e ".[apps]"For Apple Silicon Macs, use the macOS-specific TensorFlow build:
pip install -e ".[mac]"Input:
- Format: Complex-valued numpy arrays or TensorFlow tensors
- Shape:
[batch_size, time_points, 2, 2]where:time_points: Number of spectral points (e.g., 4096)- First
2: Real and imaginary components - Second
2: Paired spectra (e.g., reference HF and HRR spectra)
Output:
- Reconstructed Spectrum: Shape
[batch_size, time_points, 2](real, imaginary) - Uncertainty: Shape
[batch_size, time_points, 2](σ_real, σ_imaginary)
Data Flow:
- Load paired NMR spectra - process spectra in NMRPipe or any other software
- Preprocess (We need 2D arrays as input, NORMALIZATION)
- Feed to model for inference
- Post-process outputs (denormalize, apply IFFT (remember model's output is in frequncy domian))
Some "good to know" infos
We developed the testing scripts, all of them are in scripts/ and can be used to visualise the singal, vibrations, to check the model shapes, hyperparametrs...! Again all of them are using default_config.json file but if you wish to evaluate your generator please define the path to your own config.json
Running the model on real NMR data, and everything that turns data into the figures of the manuscript, is in analysis/:
raw data (Bruker) -> NMRPipe -> phased FIDs -> network -> integration / fits -> figures
1a_nmrpipe.sh 1b_organize_fids.py 2_predict.py 3_integrate.py, 4_fit.py 5_plot_*.py
See analysis/README.md (overview), analysis/experimental/README.md (step by step: NMRPipe, normalisation, prediction, integration,
fit results, plots) and analysis/synthetic/README.md. The model needs the data normalised (done inside 2_predict.py).
In case you want to use the model and train on new data (chage some parameters, or even modify the signal fucntion)
Each training run lives in its own directory:
mkdir -p train/RUN_001Expected structure:
train/RUN_001/
config.json
train.pyPrepare the generator config
cp configs/default_generator.json train/RUN_001/config.jsonAll synthetic data generation parameters are defined only in this JSON file:
spectrum – points, field strength, spectral width, echo times
peaks – number of peaks and all parameter distributions
vibration – vibration amplitudes, frequencies, relaxation
acquisition – noise, water peak, windowing, baseline (if enabled)
python3 train/RUN_001/train.pyBe carefull - It will automatically run the stage1 training but you can config it (easy, easy) to run stage2 by just changing it in main!
if __name__ == "__main__":
# options: "stage1", "stage2"
main(stage="stage2")All outputs are written inside the run folder.
train/RUN_001/outputs/
checkpoints/
final_net_stage1.txt
final_net_stage2.txt
learning_rate_log.csvEach run is fully self-contained.
We provide the eval.py script that you can find in scripts/ that calls the model, reads the checkpoints, geenrates new data, and outputs the predictions (in case you want to see some examples).
This script can be used for your own data - just define new checkpoints path, config path (where you define all values useed in your new geenrator)
Evaluate trained models using the evaluation script:
python scripts/eval_model.py \
--stage stage2 \
--binning soft \
--ckpt checkpoints/stage2 \
--output_dir runs/$(date +%Y-%m-%d_%H-%M-%S)Command-line Arguments:
--stage: Model stage to evaluate (stage1orstage2)--binning: Binning method for uncertainty calibration (softorhard)--ckpt: Path to model checkpoint directory--output_dir: Directory to save evaluation results
There is list of arguments and defaults are all listed at the end of the eval.py script (HAVE A LOOK!!! 🫵)
The analysis/ folder turns data into the manuscript figures (synthetic and experimental). Our final results are shipped in data/, so the figures need no
model, checkpoint or raw data:
pip install -e .
python analysis/figures/make_figures.py list # every figure, with its manuscript number (Fig. 3, Fig. S5, ...)
python analysis/figures/make_figures.py paper # draw all main-text and SI figures -> outputs/figures/<date_time>/{Main,SI}/*.svgTo analyse your own data (NMRPipe processing, network prediction, integration, fitting, plots) follow
analysis/README.md: it has step-by-step commands, where to put the checkpoint, and what is saved where.
Every run writes a new folder in outputs/; the shipped results in data/ are never overwritten.
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
If you use JTF-WaveNet in your research, please cite:
@software{jtf_wavenet,
title = {Joint time-frequency WaveNet architecture for signal processing: application to vibration artifact suppression in high resolution relaxometry experiments},
author = {R. Pejanovic, L. Siemons, A. Ruda, V. Thalakottoor, G. Bouvignies, P. Pelupessy, J. A.
Villanueva-Garibay, D. F. Hansen, and F. Ferrage},
year = {2026},
url = {https://github.com/Raaaii/JTF-WaveNet}
}