Add example notebook demonstrating TV vs TGV (denoising + radial MRI)

[trung-vt]

Add example notebook demonstrating TV vs TGV (denoising + radial MRI)

No API changes; documentation/education-oriented.

Motivation: Demonstrate how mrpro tools can be used to implement TGV minimization and symmetrized gradient for arbitrary dimensions.

As discussed with @koflera, this PR adds an example Jupyter notebook examples/notebooks/tgv_tv_comparison.ipynb that showcases Total Generalised Variation (TGV) side-by-side with Total Variation (TV) on two small problems:

1. Image denoising (additive noise on a simple 2D image)
2. Radial undersampled MRI reconstruction (Fourier operator + radial mask)

TV and TGV are run with comparable settings. TGV is shown to reduce staircasing relative to TV while preserving details.

Implementation notes

• The notebook downloads 2 jpeg images and one .mat file from Zenodo.
• Automatically uses cuda if available.
• Other than downloading, most of the runtime is for running TV and TGV for the two examples, 256 iterations per run.
• Parameters are chosen for clarity rather than exhaustive tuning.

[fzimmermann89]

Thank you for this great contribution! This is, in my opinion, a better approach than the other PR. Unfortunately, I will need some time to go through it in detail.

After skimming through it, I have a couple of general questions and remarks:

• Would it make sense to include the symmetric gradient operator as an Operator in our library, similar to the finite difference operator? It could still use the same logic, but this might be something to put into mrpro proper (as in your previous PR).

• We are an MR group, so I might be a bit picky about MR stuff: You do Cartesian MRI with a pseudo-radial undersampling pattern. Radial MRI would typically use a NUFFT and not have spokes lined up on the Cartesian grid. My suggestion would be to either just do 1D random Cartesian undersampling, i.e., a mask where lines are randomly removed in one direction, or an actual radial trajectory. This would remove the radial_mask code from this example.

• Data formats: I think it might be nicer to either a) save the data as a reshaped PyTorch tensor already on Zenodo, or, even better, use an ISMRMD file with a proper header, undersampling information, etc. This would remove some of this "boilerplate" from the example notebook. Do you think you have the capacity to try your code on one of the datasets we use in the other examples? There are examples using radial acquisitions, where the FourierOp detects that a non-uniform Fourier operator should be used, and examples using Cartesian data.

• Would you be okay with removing the image denoising example and focusing only on the MR example for the example notebook?

• If not, can image loading using PIL and torchvision be simplified by only using torchvision's decode_image?

• For the comparative TV reconstruction, you could even use the existing TV reconstruction in mrpro.algorithms. We already have a notebook explaining the background behind TV reconstruction, so here I think it would be good to focus on the TGV reconstruction by removing as much as possible of the "non-interesting," i.e., non-TGV code.

I think this would make this example even more educational. If you don't have the bandwidth to do this, we could also postpone some of these suggestions, and I can try to help you at some point (or maybe @koflera can continue to help).

Cheers,
Felix

[github-actions]

Coverage Report

File	Stmts	Miss	Cover	Missing
src/mrpro
_version.py	6	2	67%	7–8
src/mrpro/algorithms/csm
inati.py	25	1	96%	43
src/mrpro/algorithms/dcf
dcf_voronoi.py	55	4	93%	15, 55–56, 89
src/mrpro/algorithms/optimizers
adam.py	30	6	80%	108, 125–129
cg.py	52	1	98%	139
pdhg.py	81	3	96%	178–179, 185
pgd.py	53	4	92%	107, 152–155
src/mrpro/algorithms/reconstruction
DirectReconstruction.py	28	6	79%	62, 65, 70, 77–79
IterativeSENSEReconstruction.py	13	1	92%	79
Reconstruction.py	50	13	74%	54–56, 80–87, 109, 112
RegularizedIterativeSENSEReconstruction.py	51	26	49%	104–108, 122–161
src/mrpro/data
AcqInfo.py	165	7	96%	49, 56, 134–135, 137, 243, 367
CsmData.py	43	2	95%	233–235
Dataclass.py	312	26	92%	59, 320, 336, 402, 460–462, 475, 570, 590–591, 593, 608–609, 611, 658–659, 664–665, 852–853, 878, 885, 890–891, 893
DcfData.py	33	1	97%	62
EncodingLimits.py	97	3	97%	37, 127, 130
IData.py	138	6	96%	125, 185, 231, 244, 249, 293
IHeader.py	130	7	95%	69–72, 255, 259, 263, 267
KData.py	228	24	89%	122–123, 138, 145, 156–167, 178, 186, 197, 236, 258–260, 304–305, 377, 543, 545, 617
KHeader.py	176	13	93%	115–121, 148, 196, 203–204, 231–238
KNoise.py	22	1	95%	44
KTrajectory.py	95	3	97%	163, 165, 185
QData.py	32	1	97%	43
Rotation.py	735	42	94%	104, 202, 339, 437, 481, 499, 586, 588, 597, 631, 633, 696, 773, 778, 781, 796, 813, 818, 894, 1082, 1087, 1090, 1114, 1118, 1142, 1262, 1264, 1272–1273, 1337, 1419, 1623, 1630–1632, 1691, 1787, 1939, 1974, 1978, 2154, 2175
SpatialDimension.py	150	19	87%	34, 103, 146, 158, 278–280, 293–295, 329, 347, 360, 373, 386, 399, 408–409, 437
src/mrpro/data/traj_calculators
KTrajectoryCalculator.py	26	2	92%	84, 95
KTrajectoryCartesian.py	31	4	87%	129–132, 136
KTrajectoryIsmrmrd.py	19	1	95%	57
KTrajectorySpiral2D.py	57	13	77%	63–66, 69, 71, 73, 75, 77, 105, 107, 134–136
src/mrpro/operators
AveragingOp.py	36	2	94%	72, 113
CartesianSamplingOp.py	112	4	96%	152, 191, 266, 387
ConjugateGradientOp.py	89	7	92%	62, 64, 100, 106, 228, 230, 233
ConstraintsOp.py	85	4	95%	78, 80, 250, 255
EndomorphOperator.py	28	2	93%	71, 77
FiniteDifferenceOp.py	29	2	93%	40, 126
FourierOp.py	101	6	94%	186–187, 206, 251, 315, 320
Functional.py	70	2	97%	116, 118
GridSamplingOp.py	165	15	91%	72–73, 82–83, 90–91, 94, 96, 98, 282, 290–291, 303, 309–310
LinearOperator.py	202	6	97%	217, 255, 296, 305, 313, 330
LinearOperatorMatrix.py	174	19	89%	98, 135, 168, 177, 182, 191–194, 207–210, 218–219, 224–225, 237, 346, 376, 403
MultiIdentityOp.py	16	2	88%	58, 63
NonUniformFastFourierOp.py	195	10	95%	68, 95, 217, 219, 257, 259, 336, 393, 467, 472
Operator.py	88	3	97%	82, 115, 125
PatchOp.py	49	3	94%	93, 129, 144
ProximableFunctionalSeparableSum.py	44	3	93%	117, 208, 219
SliceProjectionOp.py	178	10	94%	45, 62, 64, 70, 154, 180, 216, 253, 290, 330
WaveletOp.py	121	5	96%	168, 186, 230, 235, 258
ZeroPadOp.py	18	1	94%	30
src/mrpro/operators/functionals
SSIM.py	73	7	90%	60–80, 82, 86, 114, 147
src/mrpro/operators/models
EPG.py	212	44	79%	31–32, 105–120, 168–172, 192–195, 216–221, 284, 289, 305–307, 327–328, 333, 357, 362, 387, 392, 508, 609, 636
src/mrpro/phantoms
EllipsePhantom.py	43	2	95%	66, 131
brainweb.py	297	40	87%	276, 290–294, 349–359, 398, 454–457, 479–480, 485–486, 488–489, 493, 501, 508–509, 550, 621, 624–625, 644, 653–656, 667, 669, 700–701, 715, 723
fastmri.py	106	10	91%	50–51, 59, 65, 162, 169–171, 174–175, 189
m4raw.py	74	4	95%	58–59, 74, 76
mdcnn.py	71	7	90%	58, 62–63, 70, 82, 88, 135
src/mrpro/utils
RandomGenerator.py	156	15	90%	23–24, 36, 38, 188, 212, 428, 446, 528, 799, 829–832, 895, 898
filters.py	62	2	97%	44, 49
indexing.py	177	1	99%	321
pad_or_crop.py	32	6	81%	27, 31, 62, 65, 68, 71
reshape.py	139	9	94%	112, 308, 420–422, 443, 445, 452, 467
slice_profiles.py	49	6	88%	21, 37, 119–122, 155
split_idx.py	10	2	80%	43, 47
summarize.py	57	7	88%	40–41, 70–73, 77, 81
unit_conversion.py	72	15	79%	34, 44, 51, 53, 62, 69, 71, 78, 80, 89, 100, 121, 123, 144, 146
TOTAL	7636	525	93%

Tests	Skipped	Failures	Errors	Time
2964	0 💤	0 ❌	0 🔥	2m 2s ⏱️

[github-actions]

📚 Documentation

📁 Download as zip
🔍 View online

[trung-vt]

Hi Felix, thank you for the review! Would #904 be a more suitable addition? There is a new SymmetrizedGradientOp class. The example notebook now follows closely the TV reconstruction example: it downloads the ISMRMD file from Zenodo, applies NUFFT for radial MRI, and removes the image denoising example.

Best wishes,
Trung