Skip to content

Configs

Nipoppy docs are moving

Nipoppy is undergoing a major refactor to move from scripts to a command-line interface (CLI) and Python API. The new documentation website (work in progress) can be found at https://nipoppy.readthedocs.io/.

If you are using the (soon-to-be legacy) scripts from Nipoppy 0.1.0, this is still the correct place to be. But we encourage you to check out the new website!

Global files

Nipoppy requires two global files for specifying local data/container paths and recruitment manifest.

Global configs: global_configs.json

  • This is a dataset-specific file and needs to be modified based on local configs and paths
  • This file is used as an input to all workflow runscripts to read, process and track available data
  • Copy, rename, and populate sample_global_configs.json
  • This file contains:
    • Name of the Nipoppy dataset (DATASET_NAME, e.g., PPMI)
    • Path to the Nipoppy dataset (DATASET_ROOT)
    • Path to a local CONTAINER_STORE comprising containers used by several workflow scripts
    • Path to a Singularity executable (SINGULARITY_PATH)
    • Path to a TemplateFlow directory, if using fMRIPrep (TEMPLATEFLOW_DIR)
    • List of session IDs (SESSION, for MRI data) and visit IDs (VISITS, for tabular data)
    • Containers + versions for BIDS conversion: HeuDiConv, BIDS validator (BIDS)
    • List of processing pipelines + versions (PROC_PIPELINES)
    • Information about tabular data (TABULAR)
      • Version and path to the data dictionary (data_dictionary)

Note

Nipoppy uses the term "session" to refer to a session ID string with the "ses-" prefix. For example, ses-01 is a session, and 01 is the session ID associated with this session.

Suggestion

Although not mandatory, for consistency the preferred location would be: <DATASET_ROOT>/proc/global_configs.json.

Sample global_configs.json

{
    "DATASET_NAME": "MyDataset",
    "DATASET_ROOT": "/path/to/MyDataset",
    "CONTAINER_STORE": "/path/to/container_store",
    "SINGULARITY_PATH": "singularity",
    "TEMPLATEFLOW_DIR": "/path/to/templateflow",

    "SESSIONS": ["ses-1","ses-5","ses-7","ses-9","ses-11"],

    "BIDS": {
        "heudiconv": {
            "VERSION": "0.11.6",    
            "CONTAINER": "heudiconv_{}.sif",
            "URL": ""
        },
        "validator":{
            "CONTAINER": "bids_validator.sif",
            "URL": ""

        }
    },

    "PROC_PIPELINES": {
        "mriqc": {
            "VERSION": "",
            "CONTAINER": "mriqc_{}.sif",
            "URL": ""
        },
        "fmriprep": {
            "VERSION": "20.2.7",
            "CONTAINER": "fmriprep_{}.sif",
            "URL": ""
        },
        "freesurfer": {
            "VERSION": "6.0.1",
            "CONTAINER": "fmriprep_{}.sif",
            "URL": ""
        }
    }
}

Participant manifest: manifest.csv

  • This list serves as the ground truth for subject and visit (i.e. session) availability
  • Create the manifest.csv in <DATASET_ROOT>/tabular/ comprising following columns:
    • participant_id: ID assigned during recruitment (at times used interchangeably with subject_id)
    • visit: label to denote participant visit for data acquisition
      • Note: we recommend that visits describe a timeline if possible, for example BL, M12, M24 (for Baseline, Month 12, and Month 24 respectively).
        • Alternatively, visits should be ordinal and ideally named with the V prefix (e.g., V01, V02)
    • session: alternative naming for visit - typically used for imaging data to comply with BIDS standard
    • datatype: a list of acquired imaging datatype as defined by BIDS standard
  • New participant are appended upon recruitment as new rows
  • Participants with multiple visits (i.e. sessions) should be added as separate rows

Sample manifest.csv

participant_id visit session datatype
001 V01 ses-01 ["anat","dwi","fmap","func"]
001 V02 ses-02 ["anat"]
002 V01 ses-01 ["anat","dwi"]
002 V03 ses-03 ["anat","dwi"]