User Guide

The main documentation of all the proposed scripts.

Tutorial

Tutorial is available as a Jupyter notebook (Jupyter is the new name for IPython notebook).

To run it, the following must be done:

  • CAPSUL installation.

  • have IPython installed.

  • run the tutorial ipython notebook server, with Qt GUI support:

    jupyter notebook --gui=qt my_tutorial.ipynb

Running Capsul

Running as commandline

CAPSUL has a commandline program to run any process, pipeline, or process iteration. It can be used from a shell, or a script. It allows to run locally, either sequentially or in parallel, or on a remote processing server using Soma-Workflow.

The program is a python module/script:

python -m capsul <parameters>

It can accept a variety of options to control configuration settings, processing modes, iterations, and process parameters either through file names or via attributes and parameters completion system.

To get help, you may run it with the -h or --help option:

python -m capsul -h

Ex:

python -m capsul --swf -i /home/data/study_data --studyconfig /home/data/study_data/study_config.json -a subject=subjet01 -a center=subjects morphologist.capsul.morphologist.Morphologist

will run the Morphologist pipeline on data located in the directory /home/data/study_data using Soma-Workflow on the local computer, for subject subject01

Ex with iteration:

python -m capsul --swf -i /home/data/study_data --studyconfig /home/data/study_data/study_config.json -a subject='["subjet01", "subject02", "subject03"]' -a center=subjects -I t1mri morphologist.capsul.morphologist.Morphologist

will iterate the same process 3 times, for 3 different subjects.

To work correctly, StudyConfig settings have to be correctly defined in study_config.json including FOM completion parameters, external software, formats, etc.

Alternatively, or in addition to attributes, it is possible to pass process parameters as additional options after the process name. They can be passed either as positional arguments (given in the order the process expects), or as “keyword” arguments:

python -m capsul --swf -i /home/data/study_data --studyconfig /home/data/study_data/study_config.json -a subject=subjet01 -a center=subjects morphologist.capsul.morphologist.Morphologist /home/data/raw_data/subject01.nii.gz pipeline_steps='{"importation": True, "orientation": True}'

To get help about a process, its parameters, and available attributes to control its completion:

python -m capsul --process-help morphologist.capsul.morphologist.Morphologist

Configuration:

Capsul configuration may be specified via the --config option, or the older --studyconfig option:

python -m capsul --config engine.json -a subject=subjet01 -a center=subjects morphologist.capsul.morphologist.Morphologist

The config may be imported from BrainVisa/Axon config using the process capsul.engine.write_engine_config:

axon-runprocess capsul://capsul.engine.write_engine_config engine.json

XML Specifications

Processes may be functions with XML specifications for their parameters.

Pipelines can be saved and loaded as XML files.

The specs of XML definitions can be found on this page.

Documenting CAPSUL processes and pipelines with Sphinx

Sphinx documentation can be built automatically for all Capsul processes. See capsul.sphinxext.

Hints may be stored in process classes to point to the documentation. This doc may be accessed through the PipelineDevelopperView pipeline viewer (at least). Several mechanisms can be used to find the HTML documentation of a process or node:

  • a Process or Node class (or instance) may contain a _doc_path attribute. It points to the HTML document corresponding to the process documentation. The path may be absolute (/path/to/file.html), or an URL (https://populse.github.io/capsul/api/pipeline.html#leaveoneoutnode), or a relative URL. In the latter case the link is relative to to root of the project documentation, found via the process or node modules hierarchy. See below.

  • a module containing processes or nodes docs may contain a _doc_path attribute. It can be in any module / package level above the process / node to be documented (it will be searched upwards, starting form the process module). If found it should point to the root directory of the documentation of the project. It may be an absolute path (/path/to/project), or an URL (https://populse.github.io/capsul). Individual process / node docs will be appended to this prefix.

  • If a process or node class does not provide a _doc_path attribute, but one is found in one of its parent modules, then the documentation can be looked for, following the organization of the docs auto-generated by capsul.sphinxext.

If a process HTML documentation is not found, then it may be replaced in documentation browsers with the process help (from its docstring).

Advanced usage

More advanced features can be found on this page.