Improve documentation

[fzimmermann89]

A bunch of fixes and improvements to the documentation.

• more content on landing page
• some warnings fixed
• fix default_factory rendering in dataclases (Dataclass field types are not rendered when factories are used sphinx-doc/sphinx#10893)
• fix properties in (for example in Rotation) not always getting new lines
• enable intersphinx to link to toch.Tensor dumentation etc
• replace source links with github links
• use github style for code examples (not sure about this, came as a side effect of the GitHub links)
• make the navigation on the top level navigation bar expandable
• remove iterative reconstruction from basic example, add fourier op
• links in examples
• more text in examples
• removed T2* example, as it does not really show anything new
• add descriptions to algorithms
• fix a lot of small issues

[github-actions]

Coverage Report

File	Stmts	Miss	Cover	Missing
src/mrpro/algorithms/csm
inati.py	24	1	96%	44
walsh.py	16	1	94%	52
src/mrpro/algorithms/dcf
dcf_voronoi.py	53	4	92%	15, 55–56, 89
src/mrpro/algorithms/optimizers
adam.py	20	1	95%	106
src/mrpro/algorithms/reconstruction
DirectReconstruction.py	28	16	43%	59–79, 93
IterativeSENSEReconstruction.py	13	1	92%	79
Reconstruction.py	50	22	56%	42, 54–56, 80–87, 108–117
RegularizedIterativeSENSEReconstruction.py	41	17	59%	97–101, 115–140
src/mrpro/data
AcqInfo.py	128	3	98%	26, 169, 207
CsmData.py	29	3	90%	15, 84–86
DcfData.py	45	8	82%	18, 66, 78–83
IData.py	67	9	87%	119, 125, 129, 159–167
IHeader.py	75	7	91%	75, 109, 127–131
KData.py	214	25	88%	111–112, 127, 134, 144, 152, 206–207, 245, 250–251, 270–281, 435, 437, 500, 515, 552, 583, 592
KHeader.py	153	17	89%	25, 119–123, 150, 199, 210, 217–218, 221, 228, 260–271
KNoise.py	31	15	52%	39–52, 56–61
KTrajectory.py	81	12	85%	109–114, 117–119, 204–208
MoveDataMixin.py	140	18	87%	28, 126, 142, 156–158, 220, 336–338, 351, 430, 450–451, 453, 468–469, 471
QData.py	39	7	82%	42, 65–73
Rotation.py	674	35	95%	100, 198, 335, 433, 477, 495, 581, 583, 592, 626, 628, 691, 768, 773, 776, 791, 808, 813, 889, 1077, 1082, 1085, 1109, 1113, 1241, 1243, 1251–1252, 1316, 1398, 1691, 1845, 1880, 1884, 1995
SpatialDimension.py	232	21	91%	34, 104, 141, 148, 154, 274–276, 289–291, 325, 343, 356, 369, 382, 395, 404–405, 420, 429
acq_filters.py	12	1	92%	47
src/mrpro/data/traj_calculators
KTrajectoryCalculator.py	25	2	92%	23, 45
KTrajectoryIsmrmrd.py	13	2	85%	41, 50
KTrajectoryPulseq.py	23	1	96%	55
src/mrpro/operators
CartesianSamplingOp.py	89	3	97%	118, 157, 280
ConstraintsOp.py	60	2	97%	46, 48
EndomorphOperator.py	65	2	97%	228, 234
FiniteDifferenceOp.py	27	2	93%	40, 105
FourierOp.py	158	3	98%	274, 392, 397
Functional.py	71	5	93%	20–22, 117, 119
GridSamplingOp.py	136	9	93%	72–73, 82–83, 90–91, 94, 96, 98
LinearOperator.py	168	10	94%	55, 108, 212, 242, 283, 292, 300, 309, 317, 351
LinearOperatorMatrix.py	158	16	90%	82, 119, 152, 161, 166, 175–178, 191–194, 203, 215, 304, 331, 359
MultiIdentityOp.py	13	2	85%	43, 48
Operator.py	78	2	97%	31, 80
ProximableFunctionalSeparableSum.py	39	3	92%	50, 103, 110
SliceProjectionOp.py	173	8	95%	44, 61, 63, 69, 206, 227, 260, 300
WaveletOp.py	120	5	96%	152, 170, 205, 210, 233
ZeroPadOp.py	16	1	94%	30
src/mrpro/utils
filters.py	62	2	97%	44, 49
reshape.py	60	1	98%	191
slice_profiles.py	46	6	87%	20, 36, 113–116, 149
sliding_window.py	34	1	97%	34
split_idx.py	10	2	80%	43, 47
summarize_tensorvalues.py	11	9	18%	20–29
typing.py	21	11	48%	8–23
zero_pad_or_crop.py	31	6	81%	26, 30, 54, 57, 60, 63
TOTAL	4895	360	93%

Tests	Skipped	Failures	Errors	Time
2263	0 💤	0 ❌	0 🔥	1m 9s ⏱️

[github-actions]

📚 Documentation

📁 Download as zip
🔍 View online

[ckolbPTB]

These three references should also be changed into something like [KABS], [WAHB], [MAG2018]

mrpro/src/mrpro/data/Rotation.py

Line 1824 in 4acaff1

.. [1] https://en.wikipedia.org/wiki/Kabsch_algorithm

[ckolbPTB]

Any idea why the background is not black for the all the code in the notebooks:

[fzimmermann89]

"use github style for code examples (not sure about this)"

[ckolbPTB]

"use github style for code examples (not sure about this)"

But even for the github style the background should depend on the browser settings, shouldn't it?

[fzimmermann89]

Added a short intro and the docstrings to modules, making the subsection redundant

[fzimmermann89]

ruff formatted

[fzimmermann89]

removed some of the comments from the tutorial.

[fzimmermann89]

makes torch.Tensor etc clickable links

[fzimmermann89]

used to supports default_factory=lambda: torch.ones(1,1,1,1,1) etc in rewrite_dataclass_init_default_factories

[fzimmermann89]

ruff and jupytext sometimes disagree on formatting.
but our ipynbs are autogeneratred anyways.

[fzimmermann89]

the directory including any files in it will be deleted when tmp goes out of scope (also on interpreter shutdown.)
downside is that this will print a warning on shutdown to the console

[fzimmermann89]

We always use zenodo get now

[ckolbPTB]

But this means we download a lot of data we don't need....

[fzimmermann89]

a bit cleaner dictionary matching

[fzimmermann89]

I added some description to the algorithms that describes what they do

[ckolbPTB]

Some comments, still have to go through the docu

• keep the T2* example as it was part of the challenge and should be somewhere for reproducibility reasons
• keep the iterative SENSE in the basics example or create a new notebook which shows how to get the coil maps from the reference data - this is not covered anywhere else

[fzimmermann89]

Some comments, still have to go through the docu

• keep the T2* example as it was part of the challenge and should be somewhere for reproducibility reasons

The notebook has changed anyways. The results do not match the challenge submission anymore. I would suggest to link the award mentions to the specific version of the notebooks in git used to create the results. And remove the T2* example.
Examples is not the right place to but "everything" we want to preserve, but only stuff that helps the documentation.

• keep the iterative SENSE in the basics example or create a new notebook which shows how to get the coil maps from the reference data - this is not covered anywhere else

I want to remove iterative SENSE from "basic". We still use the CSMs from the reference scan with the manual or direct reconstruction, right?

[ckolbPTB]

I want to remove iterative SENSE from "basic". We still use the CSMs from the reference scan with the manual or direct reconstruction, right?

No, everywhere else we use self-calibrated SENSE

[lrlunin]

Suggested change

	You can easily launch notebooks via the |colab-badge| badge and give the notebooks a try without having to
	install anything.
	You can launch the notebooks using the |colab-badge| badge and explore them directly in browser — no installation required.

[ckolbPTB]

Missing dimensions/shape formatting:

mrpro/src/mrpro/data/KNoise.py

Line 21 in e029d5e

"""K-space data of noise measurements. Shape (...other coils k2 k1 k0)"""

mrpro/src/mrpro/data/Data.py

Line 17 in e029d5e

"""Data. Shape (...other coils k2 k1 k0)"""

mrpro/src/mrpro/data/KData.py

Line 379 in e029d5e

"""Rearrange kdata from (... k2 k1 ...) to (... 1 (k2 k1) ...).

mrpro/src/mrpro/data/KData.py

Line 478 in e029d5e

K-space data (other coils k2 k1 k0)

ff

mrpro/src/mrpro/data/KData.py

Line 650 in e029d5e

K-space data (other coils k2 k1 k0)

ff

[ckolbPTB]

I would suggest to change the order to
user_guide
examples
contributor_guide
api
faq

[ckolbPTB]

This list is not displayed correctly

[ckolbPTB]

List not working

[ckolbPTB]

I think dcf is missing here

[ckolbPTB]

Wiki link not displayed correctly

[ckolbPTB]

Links not displayed correctly here and below

[ckolbPTB]

IMO does not look nice in the docu

[ckolbPTB]

shape formating

[ckolbPTB]

Why would we want to hide this cell?

[ckolbPTB]

this leads to a fail on colab:
RuntimeError: Expected all tensors to be on the same device, but found at least two devices, cuda:0 and cpu!

[ckolbPTB]

b and y not displayed correctly

[ckolbPTB]

Formatting missing:

mrpro/src/mrpro/operators/functionals/L1Norm.py

Line 16 in e029d5e

In most cases, consider setting divide_by_n to true to be independent of input size.

Can you please also unify the use of l1 norm, L1 norm and L1-norm here?

Similar issue here:

mrpro/src/mrpro/operators/functionals/L1NormViewAsReal.py

Line 18 in e029d5e

In most cases, consider setting divide_by_n to true to be independent of input size.

mrpro/src/mrpro/operators/functionals/L2NormSquared.py

Line 18 in e029d5e

In most cases, consider setting divide_by_n to true to be independent of input size.

[ckolbPTB]

(… other, coils, z, y, x) and (time … other, coils, z, y, x) need to be correctly formatted for all signal models

[ckolbPTB]

Remove double quotes here?

mrpro/src/mrpro/operators/models/TransientSteadyStateWithPreparation.py

Line 32 in e029d5e

``m0_scaling_preparation`` and :math:`\Delta t` is ``delay_after_preparation``. The effective longitudinal

[ckolbPTB]

Formatting missing here:

mrpro/src/mrpro/phantoms/EllipsePhantom.py

Line 20 in e029d5e

if None, defaults to three ellipses

mrpro/src/mrpro/phantoms/EllipsePhantom.py

Line 30 in e029d5e

if None, defaults to three ellipses with different parameters.

mrpro/src/mrpro/phantoms/EllipsePhantom.py

Line 89 in e029d5e

This is a 2D simulation so the output will be (1 1 1 image_dimensions.y image_dimensions.x)

[lrlunin]

Wrong code formatting

Suggested change

	New exciting applications of MRpro can be added in ```examples``` as only ```.py``` files with code-cells. These can, for example, be used in VSCode with the python extension, or in JupyterLab with the `jupytext <https://jupytext.readthedocs.io/en/latest/>`_ extension.
	New exciting applications of MRpro can be added in ``examples`` as only ``.py`` files with code-cells. These can, for example, be used in VSCode with the python extension, or in JupyterLab with the `jupytext <https://jupytext.readthedocs.io/en/latest/>`_ extension.

[lrlunin]

Same on the line 87:
You can build the documentation locally via running ```make html``` in the docs folder. The documentation will also be build in each PR and can be viewed online.

[lrlunin]

And line 100:

Release Strategy
================
We are still in pre-release mode and do not guarantee a stable API / strict semantic versioning compatibility. We currently use ```0.YYMMDD``` as versioning and release in regular intervals to `pypi  <https://pypi.org/project/mrpro/>`_.