Launching a processing

Commands

The main file is located in workflows and is called segment_skull.py and should be called like a python script:

$ python workflows/segment_skull.py

N.B. if you have installed the pypi version (e.g. using pip install macapype) or a docker/singularity version, you can replace the previous command by the following command:

$ segment_skull

For container (docker and singularity), here are some examples - add your proper bindings:

$ docker run -B binding_to_host:binding_guest macatools/skullto3d:latest segment_skull

$ singularity run -v binding_to_host:binding_guest /path/to/containers/skullto3d_v0.0.4.1.sif segment_skull

Expected input data

All the data have to be in BIDS format to run properly (see BIDS specification for more details)

In particular:

  • _T1w (BIDS) extension is expected for T1 weighted images (BIDS)

  • _T2w (BIDS) extension is expected for T2 weighted images (BIDS)

  • _PDw (BIDS) or petra (non-BIDS) extensions are expected for petra images

Note : All files with the same extension (T1w, T2w or PDw) will be aligned to the first one and averaged

  • _acq-CT_T2star (BIDS, but non canonical) extension is expected for CT images

  • _angio extension is expected for angiography images

_images/BIDS_orga_skullTo3d.jpg

Command line parameters

All parameters available for macapype are also available in skullTo3d. These parameters are recalled here

mandatory parameters

  • -data : path to your data dataset (existing BIDS format directory)

  • -out : path to the output results (an existing path)

  • -soft : can be one of these : SPM or ANTS ( NB: SPM requires a specific version of macapype/skullTo3d, not available by default)

    For -soft value, it is possible to add some key words (e.g. -soft ANTS_robustreg_prep) all these options are available (to place after SPM or ANTS, e.g) and will change the brain extraction:

    • _4animal : will use bet4animal (FSL) for brain extraction, for faster computation (by default atlas_brex is used)

    • _quick : will use hd-bet (Deep Learning) for brain extraction, for faster computation (by default atlas_brex is used)

    NB: hd-bet requires a specific version of macapype/skullTo3d, not available by default


This option should be used if the coregistration to template in preparation is not performed correctly:

  • _robustreg (at the end) to have a more robust registration (in two steps)


Finally, these option are available (to place after SPM or ANTS) and will modify the parameters but can be launched in sequence:

  • _test : (at the end) to check if the full pipeline is coherent (will only generate the graph.dot and graph.png)

  • _prep (at the end) will perform data preparation (no brain extraction and segmentation)

  • _noseg (at the end) will perform data preparation and brain extraction (no segmentation)


Some options are specific to skullTo3d:

  • _skull after SPM or ANTS if you want to process skull or angio specific to skullTo3d; otherwise the main pipelines of macapype will be launched (only brain segmentation will be performed)

NB : _skullnoisypetra instead of _skull available for macaque with issues on petra

NB : -soft skull without processing brain is possible, but is still experimental. It only works if -skull_dt CT petra and -deriv and -padback are NOT defined

  • _noskullmask (at the end) will perform realignement to stereo and headmask (only realignement for CT)

  • _noheadmask (at the end) will perform only realignement to stereo

exclusive parameters

(but one is mandatory)

  • -params : (mandatory if -species is omitted) a json file specifiying the global parameters of the analysis. See Parameters for more details

  • -species : (mandatory if -params is omitted) followed the NHP species corresponding to the image, e.g. {macaque | marmo }

NB marmoT2 can be used for segmenting from the T2w image (by default, T1w is used for marmo) NB macaque_0p5 is available to use downsampled template (faster results)

optional parameters

(but highly recommanded)

  • -brain_dt equivalent to -dt in macapype

specifies the datatype available to perform brain segmentation (can be “T1”, or “T1 T2”).

NB : default is T1 if the attribute is omitted

  • -skull_dt specific to skullTo3d

specifies the datatype available for skull segmentation (can be, “T1”, “petra”, “CT”, “angio” or a combination of the latter (with space(s) in between).

NB : default is T1 if the attribute is omitted.

  • -deriv : creates a derivatives directory, with all important files, properly named following BIDS derivatives convertion. See Derivatives for a descrition of the outputs

  • -padback : exports most important files in native (original) space

more optional parameters

  • -indiv or -indiv_params : a json file overwriting the default parameters (both macapype default and parameters specified in -params json file) for specific subjects/sessions. See Individual Parameters for more details

  • -sub (-subjects), -ses (-sessions), -acq (-acquisions), -rec (-reconstructions) allows to specifiy a subset of the BIDS dataset respectively to a range of subjects, session, acquision types and reconstruction types. The arguments can be listed with space seperator. Note if not specified, the full BIDS dataset will be processed

  • -nprocs : an integer, to specifiy the number of processes that should be allocated by the parralel engine of macapype

    • typically equals to the number of subjects*session (i.e. iterables).

    • can be multiplied by 2 if T1*T2 pipelines are run (the first steps at least will benefit from it)

    • default = 4 if unspecified ; if is put to 1, then the sequential processing is used

  • -mask allows to specify a precomputed binary mask file (skipping brain extraction). The best usage of this option is: precomputing the pipeline till brain_extraction_pipe, modify by hand the mask and use the mask for segmentation. Better if only one subject*session is specified (one file is specified at a time…).

Warning: the mask should be in the same space as the data. And only works with -soft ANTS so far

The following parameters are optional

  • -indiv or -indiv_params : a json file overwriting the default parameters (both macapype default and parameters specified in -params json file) for specific subjects/sessions. See Individual Parameters for more details

  • -sub (-subjects), -ses (-sessions), -acq (-acquisions), -rec (-reconstructions) allows to specifiy a subset of the BIDS dataset respectively to a range of subjects, session, acquision types and reconstruction types. The arguments can be listed with space seperator. Note if not specified, the full BIDS dataset will be processed

  • -mask allows to specify a precomputed binary mask file (skipping brain extraction). The best usage of this option is: precomputing the pipeline till brain_extraction_pipe, modify by hand the mask and use the mask for segmentation. Better if only one subject*session is specified (one file is specified at a time…).

Warning: the mask should be in the same space as the data. And only works with -soft ANTS so far

  • -nprocsan integer, to specifiy the number of processes that should be allocated by the parralel engine of macapype

    • typically equals to the number of subjects*session (i.e. iterables).

    • can be multiplied by 2 if T1*T2 pipelines are run (the first steps at least will benefit from it)

    • default = 4 if unspecified ; if is put to 0, then the sequential processing is used (equivalent to -soft with _seq, see before)

Command line examples

$ python workflows/segment_skull.py -data ~/Data_maca -out ./local_test -soft ANTS_skull -params params.json

$ python workflows/segment_skull.py -data ~/Data_maca -out ./local_test -soft ANTS_skull_robustreg -species macaque

$ python workflows/segment_skull.py -data ~/Data_maca -out ./local_test -soft ANTS_skull -params params.json -sub Apache Baron -ses 01 -rec mean -deriv -padback