Installation

To get started with the MRI reconstruction code, follow these steps. You need Python 3.10 or newer. There is no C++ compilation step: the MEX files of the MATLAB toolbox are replaced by NumPy, SciPy and numba code.

Tip

With Docker, nothing has to be installed but Docker: the image mattechlab/monalisa-python contains Python, every library, JupyterLab and the tutorial. See Running Monalisa in Docker.

Clone the Repository

Clone the repository and navigate into the directory, using your terminal, navigate to the directory where you want to install the monalisa-python folder then run (on Windows, Git for Windows provides git):

git clone https://github.com/MattechLab/monalisa-python.git
cd monalisa-python

Install the Package

The same commands work on Linux, macOS and Windows. Either with pip, in a virtual environment:

python3 -m venv .venv                  # Windows: py -m venv .venv
source .venv/bin/activate              # Windows: .venv\Scripts\activate
pip install -e ".[io,reg,notebook]"

or with conda (everything inside the environment, no admin rights needed):

conda create -n monalisa -c conda-forge python=3.12 matplotlib-base
conda activate monalisa
pip install -e ".[io,reg,notebook]"

The package installs as monalisa-python and is imported as monalisa. It always installs NumPy, SciPy, numba, h5py, matplotlib, napari (viewer and dialogs) and ipywidgets (viewer in notebooks). The extras add:

• io: the raw-data readers (Siemens .dat with twixtools, ISMRMRD .mrd with ismrmrd);

• reg: SimpleITK, for the deformation fields of motion-compensated reconstructions (it replaces MATLAB’s imregdemons);

• notebook: JupyterLab, for the tutorial notebook;

• dev: pytest (with pytest-xdist and pytest-qt), ruff, and reg: pip install -e ".[dev,io]".

Warning

In a conda environment, install matplotlib-base, not conda’s matplotlib: the latter brings PySide6 with a second copy of Qt, whose libraries clash with napari’s (PyQt6) and crash Python as soon as a window opens.

Linux: Library for the Qt Windows

On Linux only (macOS and Windows need nothing more), the napari viewer and the interactive steps use Qt, which needs the library libxcb-cursor (not available from pip). Either:

• in the conda environment: conda install -c conda-forge xcb-util-cursor (monalisa loads it from the environment), or

• system-wide: sudo apt install libxcb-cursor0 (Debian, Ubuntu) or sudo dnf install xcb-util-cursor (Fedora).

Without it, opening a window raises an error that says so; the notebook viewer works without it.

Verify Installation

Test your installation with the unit tests, and run your first reconstruction with the tutorial (see Tutorial 1: Reconstruct MRI rawdata):

python -c "import monalisa; print(monalisa.__version__)"
pip install -e ".[dev,io]"     # pytest, for the tests
pytest tests/unit

Congratulations, you are ready to use Monalisa.

Notes

• Same results as MATLAB: every ported function is compared with recordings of its MATLAB counterpart (see Porting method: oracle-first, function by function).

• MATLAB users: the table Renaming: MATLAB names → Python names gives the Python name of each MATLAB function; in code, monalisa.find_function("bmMathilda") returns it.

• MATLAB files: scipy.io.loadmat reads .mat files saved by MATLAB’s default save; monalisa.io.loadmat73 reads -v7.3 files (HDF5) and the files written by this package.

Follow these steps to set up your environment. If you encounter any issues, consider opening an issue on our GitHub repository. We will do our best to help you.

↑