Usage Guide

Skullduggery is a command-line tool for automated defacing of anatomical MRI images in BIDS datasets. This guide covers how to use the tool from the command line.

Installation

Basic Installation

pip install skullduggery

With Optional Features

For git-annex metadata tracking (DataLad integration):

pip install skullduggery[datalad]

Basic Usage

Minimal Command

To deface all anatomical images in a BIDS dataset:

skullduggery /path/to/bids/dataset

This command:

  • Processes all participants in the dataset

  • Uses the default template (MNI152NLin2009cAsym)

  • Saves defaced images alongside originals

  • Processes T1w reference images by default

What Gets Processed

By default, skullduggery:

  • Searches for: All anatomical images (anat datatype)

  • Reference series: Uses T1w weighted images as the registration reference

  • Output: Saves defaced images with _defaced suffix

Common Command-Line Options

Filter Participants and Sessions

Process specific participants:

skullduggery /path/to/bids/dataset --participant-label 01 02 05

Process specific sessions:

skullduggery /path/to/bids/dataset --session-label 01 02

Combine filters:

skullduggery /path/to/bids/dataset \
  --participant-label 01 02 03 \
  --session-label 01

Template Selection

Use different registration template:

skullduggery /path/to/bids/dataset --template MNI152NLin6Asym

For pediatric data (age-specific templates):

skullduggery /path/to/bids/dataset --template MNIInfant:cohort-07m09m

When participants.tsv lacks age data:

skullduggery /path/to/bids/dataset \
  --template MNIInfant:cohort-06m09m \
  --default-age 6:months

Output Options

Save masks for all defaced series:

skullduggery /path/to/bids/dataset --save-all-masks

By default, only the mask for the reference series is saved. Use this flag to save masks for all defaced images.

Generate HTML reports with visualizations:

skullduggery /path/to/bids/dataset \
  --report-dir ./defacing_reports

Creates an HTML report showing:

  • Defacing masks overlaid on images

  • Before/after mosaic views

  • Processing status for each image

Image Selection Filters

Using BIDS Filters

Process only T2w weighted images:

skullduggery /path/to/bids/dataset \
  --other-bids-filters '{"suffix": "T2w", "datatype": "anat"}'

Process specific anatomical contrasts:

skullduggery /path/to/bids/dataset \
  --other-bids-filters '{"suffix": ["T1w", "T2w"], "datatype": "anat"}'

Use filter from JSON file:

skullduggery /path/to/bids/dataset \
  --other-bids-filters /path/to/filters.json

Where filters.json contains:

{
  "suffix": "T1w",
  "datatype": "anat"
}

Reference Series Filters

Change reference series for registration:

skullduggery /path/to/bids/dataset \
  --ref-bids-filters '{"suffix": "T2w", "datatype": "anat"}'

The reference series determines which image is used for template registration. All other anatomical images are defaced using the transformed mask.

Advanced Options

Force BIDS Reindexing

If you’ve recently added files to your BIDS dataset:

skullduggery /path/to/bids/dataset --force-reindex

This forces pyBIDS to re-scan the directory instead of using cached metadata.

DataLad Integration

Update distribution restrictions metadata:

skullduggery /path/to/bids/dataset --datalad

This option:

  • Updates git-annex metadata to mark files as defaced

  • Commits changes automatically

  • Useful for DataLad-managed repositories

Git-annex Sensitive Selection

Select series using git-annex metadata:

skullduggery /path/to/bids/dataset --deface-sensitive

Selects images marked as sensitive in git-annex metadata.

Debug Output

Enable debug logging:

skullduggery /path/to/bids/dataset --debug info

Enables verbose logging to help troubleshoot issues. Use one of: debug, info, warning, error.

Exit Codes

  • 0: All participants processed successfully

  • 1: One or more errors occurred during processing

Check the log output to identify specific failures.

Tips and Best Practices

  1. Test first: Try on a single participant before processing the whole dataset

    skullduggery /path/to/bids/dataset --participant-label 01

  2. Generate reports: Always create visual reports for quality assurance

    skullduggery /path/to/bids/dataset --report-dir ./defacing_reports

  3. Back up before running: Ensure you have a backup before defacing in-place modifications

  4. Use participant labels without prefix: The sub- prefix is optional

    # These are equivalent:
skullduggery /path/to/bids/dataset --participant-label 01
skullduggery /path/to/bids/dataset --participant-label sub-01

  5. Process sessions consistently: If using longitudinal data, process all sessions

    skullduggery /path/to/bids/dataset --session-label 01 02 03

Getting Help

View all available options:

skullduggery --help

Check version:

python -c "import skullduggery; print(skullduggery.__version__)"