Repository

Installation

MCMRSimulator is an application written in the Julia language. You can run simulations either directly from the Julia REPL, in a Jupyter notebook, or using the command line interface.

Temporary installation instructions

MCMRSimulator is currently incompatible with Julia 1.12 and the newest version of the Makie plotting library. While this is being fixed, here are some updated installation instructions:

  1. Install juliaup as explained on the official website.
  2. Use juliaup to install Julia 1.11 (not 1.12): $ juliaup add 1.11.
  3. Download the "Project.toml". This file defines a virtual environment, which was used to generate all the plots in the paper. Put this file inside your working directory (you might need to backup the old "Project.toml").
  4. Run the following command, which will set up the virtual environment on your computer: 
    julia +1.11 --project="working directory with downloaded Project.toml" -e "using Pkg; Pkg.instantiate()"
  5. Start julia within this virtual environment using $ julia +1.11 --project="working directory with downloaded Project.toml"

(Outdated) Installing the simulator for a specific project

  1. First install julia from the official website.
  2. Create a directory for the project for which you are going to use the simulator. We will install MCMRSimulator in isolation just for this project. This ensures that if we install a newer version of the simulator for another project in the future, it will not interfere with the reproducibility of the results of this project. We will refer to this newly created project directory below as "<project_dir>".
  3. Start the julia REPL in a terminal ($ julia --project=<project_dir>). The --project flag ensures that we create and activate a Julia environemnt just for this project. This will create a "Project.toml" and "Manifest.toml" inside the directory specifying the installed packages (such as the MCMR simulator).
  4. Enter the package manager by pressing "]"
    • First install the required MRIBuilder.jl using pkg> add https://git.fmrib.ox.ac.uk/ndcn0236/mribuilder.jl.git.
    • Then install MCMRSimulator.jl using pkg> add https://git.fmrib.ox.ac.uk/ndcn0236/mcmrsimulator.jl.git#v1.0.0.
    • (Optional) Install one of the Makie backends for plotting (e.g., pkg> add CairoMakie).
    • (Optional) If you want to use a Jupyter notebook for this project, you will also have to install an IJulia kernel. You can find instructions to do so below.
    • Press "[backspace]" to leave the package manager.
  5. (Optional) To install the MCMRSimulator command line interface (CLI) run the following in the main julia REPL: using MCMRSimulator; MCMRSimulator.install_cli(destdir="..."), where destdir is the target directory for the executable (called mcmr by default). Ensure that the destdir is a directory that is in your PATH variable.

Running MCMRSimulator

After this installation process, you can run MCMRSimulator in one of the following ways:

  • Julia REPL: Start the REPL in a terminal by typing $ julia --project=<project_dir>. Afterwards type using MCMRSimulator to import the simulator. You can now follow the steps in the MCMRSimulator tutorial using Julia.
  • Jupyter notebook: Make sure that you install IJulia using the instructions below. This will allow you to start a notebook in jupyter running in Julia. Within this notebook, you can follow the steps in the MCMRSimulator tutorial using Julia.
  • Command line interface: If you followed the instructions in step 4 above, you can run the MCMRSimulator command line interface simply by typing mcmr in the terminal. If it is not working, you might want to redo step 4 above and pay attention to any warning messages. With this alias set up, you can now follow the command line tutorial.

Updating MCMRSimulator

First check the CHANGELOG to find a list of changes since your current version. If you decide to update:

  1. Start the julia REPL again in a terminal ($ julia --project=<project_dir>)
  2. Enter the package manager by pressing "]"
  3. Update all installed packages using by typing update and pressing enter (pkg> update).

Sharing your MCMRSimulator installation

To share the exact environment used by your installation of MCMRSimulator, simply go to the <project_dir> directory and locate the files named "Project.toml" and "Manifest.toml". Transfer these files to any other computer, to ensure that they install the exact same version of all Julia packages used (see https://pkgdocs.julialang.org/v1/environments/ for more details).

Running MCMRSimulator in a Jupyter notebook

Installing the Julia kernel

You only have to run the following once:

julia -e "import Pkg; Pkg.add(\"IJulia\"); Pkg.build(\"IJulia\")"

This line installs and builds IJulia in the main, global environment. This will create a new jupyter kernel just for Julia. This global environment is available within any local environments, so we only have to do this once across any number of Julia projects.

To test whether this has worked, start a Jupyter notebook (or Jupyter lab). If you have FSL installed, you can do so using fslpython -m notebook. Within the Jupyter notebook interface press "New". The Julia kernel should show up here with its version number.

Using the simulator with this Julia kernel

If you followed the steps in the previous section, the Julia kernel will be installed in its own environment separate from the simulator. To use the simulator using this kernel, we simply start a notebook and then switch to an environment that has the MCMR simulator installed (i.e., created as described above). You can do this by including a block at the top of the notebook with the following code:

import Pkg
Pkg.activate("<project dir>")

where "<project_dir>" is the directory where we installed the simulator.