Skip to content

parser

lacuna.cli.parser

Lacuna CLI argument parser module.

This module provides the argument parser for the Lacuna CLI with a clean subcommand-based structure:

  • lacuna fetch: Download and setup connectomes
  • lacuna run : Run analyses (rd, fnm, snm, afnm)
  • lacuna bidsify: Convert NIfTI files to BIDS format
  • lacuna parcellate: Reduce a connectome to a parcel-level connectivity matrix
  • lacuna collect: Aggregate results across subjects
  • lacuna info: Display available resources (atlases, connectomes)

Functions: build_parser: Build and return the main argument parser.

build_parser(prog=None)

Build the main CLI parser with subcommands.

Creates a parser that supports: - lacuna fetch: Download connectomes - lacuna run : Run analyses - lacuna collect: Aggregate results - lacuna info: Show available resources

Parameters:

Name Type Description Default
prog str

Program name for help text. Defaults to 'lacuna'.

 None

Returns:

Type Description
ArgumentParser

Configured argument parser with subcommands.
Source code in src/lacuna/cli/parser.py 
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
def build_parser(prog: str | None = None) -> ArgumentParser:
    """
    Build the main CLI parser with subcommands.

    Creates a parser that supports:
    - lacuna fetch: Download connectomes
    - lacuna run <analysis>: Run analyses
    - lacuna collect: Aggregate results
    - lacuna info: Show available resources

    Parameters
    ----------
    prog : str, optional
        Program name for help text. Defaults to 'lacuna'.

    Returns
    -------
    ArgumentParser
        Configured argument parser with subcommands.
    """
    from lacuna import __version__

    # Create main parser
    parser = ArgumentParser(
        prog=prog or "lacuna",
        description=f"Lacuna v{__version__}",
        formatter_class=RawDescriptionHelpFormatter,
        epilog=(
            "Commands:\n"
            "  bidsify    Convert a directory of NIfTI masks into BIDS layout\n"
            "  parcellate Reduce a connectome to a parcel-level connectivity matrix\n"
            "  fetch     Download and setup connectomes for analysis\n"
            "  run       Run lesion analyses\n"
            "  collect   Aggregate results across subjects\n"
            "  info      Display available resources (atlases, connectomes)\n"
            "  tutorial  Setup tutorial data for learning Lacuna\n"
            "  check     Validate inputs and check output completeness\n\n"
            "Examples:\n"
            "  lacuna tutorial ./my_tutorial\n"
            "  lacuna bidsify /raw /bids --space MNI152NLin6Asym\n"
            "  lacuna fetch gsp1000 --api-key \\$DATAVERSE_API_KEY\n"
            "  lacuna run rd /bids /output --parcel-atlases schaefer2018parcels100networks7\n"
            "  lacuna run fnm /bids /output --connectome-path /path/to/gsp1000_batches\n"
            "  lacuna collect /output\n"
            "  lacuna info atlases\n"
        ),
    )

    parser.add_argument(
        "--version",
        action="version",
        version=f"lacuna {__version__}",
    )

    # Create subparsers
    subparsers = parser.add_subparsers(
        dest="command",
        title="commands",
        description="Use 'lacuna <command> --help' for more information.",
        metavar="<command>",
    )

    # Add subcommands
    _build_fetch_parser(subparsers)
    _build_run_parser(subparsers)
    _build_collect_parser(subparsers)
    _build_info_parser(subparsers)
    _build_bidsify_parser(subparsers)
    _build_parcellate_parser(subparsers)
    _build_tutorial_parser(subparsers)
    _build_check_parser(subparsers)

    return parser