Storage requirements of Python scripts

The Python scripts provided with MRtrix3 generate their own scratch directory in which to store various data files and image manipulations generated during their operation. In some cases - typically due to use of a temporary RAM-based file system with limited size, and/or a failure to clean up old temporary files - the location where this scratch directory is created may run out of storage space, resulting in the script crashing.

A few pointers for anybody who encounters this issue:

  • When these scripts fail to complete due to an error, they will typically not erase the scratch directory, instead allowing the user to investigate the contents of that directory to see what went wrong, potentially fixing any issues and continuing the script from that point. While this behaviour may be useful in this context by retaining the progress the script had made thus far, it also means that these very scripts may be contributing to filling up your storage and thus creating further issues! We recommend that users manually delete such directories as soon as they are no longer required.

  • The location where the scratch directory is created for the script will influence the amount of storage space available. For instance, the location /tmp/ is frequently created as a temporary RAM-based file system, such that files are never actually written to disk and are therefore read & written very quickly; it is however also likely to have a smaller capacity than a physical hard drive. Setting the scratch directory location to such a drive may therefore improve performance, but increase the risk of script non-completion.

The location to be used by the Python scripts when they generate a scratch directory can be set manually in two different ways:

  • In the MRtrix config file, the ScriptScratchDir entry can be used to set the location where such scratch directories will be created by default.

  • When executing the script, command-line option -scratch can be used to set the location of the scratch directory for that particular script execution.

In the absence of either of these settings, MRtrix3 will now create this scratch directory in the working directory (i.e. the location the terminal was navigated to when the script was called), as this is most likely to possess enough storage space for the script to operate (in the absence of any other information). Users working across a network, or using a job scheduler, may need to experiment with this.

The storage requirements can vary considerably between different scripts. For instance, dwibiascorrect only needs to generate a couple of intermediate images per execution; whereas population_template must store non-linear warp fields across many subjects. This may be the reason why some users report that one script crashed when other scripts have completed successfully.