_parsers.py

from __future__ import annotations

from argparse import ArgumentParser, HelpFormatter
from pathlib import Path

from bidsmreye._version import __version__
from bidsmreye.defaults import available_models, default_model


def _base_parser(formatter_class: type[HelpFormatter] = HelpFormatter) -> ArgumentParser:
    parser = ArgumentParser(
        description=(
            "BIDS app using deepMReye to decode eye motion for fMRI time series data."
        ),
        epilog="""
        For a more readable version of this help section,
        see the online https://bidsmreye.readthedocs.io/.
        """,
        formatter_class=formatter_class,
    )
    parser.add_argument(
        "--version",
        action="version",
        help="show program's version number and exit",
        version=f"\nbidsMReye version {__version__}\n",
    )
    parser.add_argument(
        "bids_dir",
        help="""
Fullpath to the directory with the input dataset
formatted according to the BIDS standard.
The dataset should contain 'minimally processed'
(meaning at least 'realigned').
The output of fMRIprep or bidspm should be acceptable inputs.

For "qc", this lust be the fullpath to the directory
with the output generated by bidsmreye
that should be quality controlled.
        """,
        nargs=1,
    )
    parser.add_argument(
        "output_dir",
        help="""
        Fullpath to the directory where the output files will be stored.
        """,
        nargs=1,
    )
    parser.add_argument(
        "analysis_level",
        help="""
        Level of the analysis that will be performed.
        Multiple participant level analyses can be run independently
        (in parallel) using the same ``output_dir``.
        """,
        choices=["participant", "group"],
        default="participant",
        type=str,
        nargs=1,
    )

    return parser


def _add_common_arguments(parser: ArgumentParser) -> ArgumentParser:
    parser.add_argument(
        "--participant_label",
        help="""
The label(s) of the participant(s) that should be analyzed.
The label corresponds to sub-<participant_label> from the BIDS spec
(so it does not include "sub-").

If this parameter is not provided, all subjects will be analyzed.
Multiple participants can be specified with a space separated list.
        """,
        nargs="+",
    )
    parser.add_argument(
        "--task",
        help="""
The label of the task that will be analyzed.

The label corresponds to task-<task_label> from the BIDS spec
so it does not include "task-").
        """,
        nargs="+",
    )
    parser.add_argument(
        "--run",
        help="""
The label of the run that will be analyzed.

The label corresponds to run-<task_label> from the BIDS spec
so it does not include "run-").
        """,
        nargs="+",
    )
    parser.add_argument(
        "--space",
        help="""
The label of the space that will be analyzed.

The label corresponds to space-<space_label> from the BIDS spec
(so it does not include "space-").
        """,
        nargs="+",
    )
    parser.add_argument(
        "-v",
        "--verbose",
        dest="log_level",
        action="append_const",
        const=-1,
    )
    parser.add_argument("--debug", help="Switch to debug mode", action="store_true")
    parser.add_argument(
        "--reset_database",
        help="""
Resets the database of the input dataset.
        """,
        action="store_true",
    )
    parser.add_argument(
        "--bids_filter_file",
        help="""
A JSON file describing custom BIDS input filters using PyBIDS.
For further details, please check out TBD.
        """,
    )
    parser.add_argument(
        "--force",
        help="""
Overwrite previous output.
        """,
        action="store_true",
    )
    return parser


def common_parser(formatter_class: type[HelpFormatter] = HelpFormatter) -> ArgumentParser:
    """Execute the main script."""
    parser = _base_parser(formatter_class=formatter_class)
    subparsers = parser.add_subparsers(
        dest="command",
        help="Choose a subcommand",
        required=True,
    )

    prepare_parser = subparsers.add_parser(
        "prepare",
        help="""
Preprocessing data for classification.
Extract the data coming from the eyes from the fMRI images.
If your data is not in MNI space, bidsmreye will also register the data to MNI.
""",
        formatter_class=parser.formatter_class,
    )
    prepare_parser = _add_common_arguments(prepare_parser)
    # TODO make it possible to pass path to a model ?
    prepare_parser.add_argument(
        "--linear_coreg",
        help="""
Uses a less aggressive (and linear) alignment procedure
to the deepmreye template.

May lead to worse results so check your outputs.
""",
        action="store_true",
    )

    generalize_parser = subparsers.add_parser(
        "generalize",
        help="""Run classification.
Use the extracted timeseries to predict the eye movements
using the default pre-trained model of deepmreye.
        """,
        formatter_class=parser.formatter_class,
    )
    generalize_parser = _add_common_arguments(generalize_parser)
    # TODO make it possible to pass path to a model ?
    generalize_parser.add_argument(
        "--model",
        help=f"Model to use. Default model: {default_model()}.",
        choices=available_models(),
        default=default_model(),
    )

    all_parser = subparsers.add_parser(
        "all",
        help="""Run prepare, generalize.""",
        formatter_class=parser.formatter_class,
    )
    all_parser = _add_common_arguments(all_parser)
    # TODO make it possible to pass path to a model ?
    all_parser.add_argument(
        "--linear_coreg",
        help="""
Uses a less aggressive (and linear) alignment procedure
to the deepmreye template.

May lead to worse results so check your outputs.
""",
        action="store_true",
    )
    # TODO make it possible to pass path to a model ?
    all_parser.add_argument(
        "--model",
        help=f"Model to use. Default model: {default_model()}.",
        choices=available_models(),
        default=default_model(),
    )

    qc_parser = subparsers.add_parser(
        "qc",
        help="""Run quality control on output.""",
        formatter_class=parser.formatter_class,
    )
    qc_parser = _add_common_arguments(qc_parser)

    return parser


def download_parser(
    formatter_class: type[HelpFormatter] = HelpFormatter,
) -> ArgumentParser:
    """Execute the main script."""
    parser = ArgumentParser(
        description="Download deepmreye pretrained model from OSF.",
        epilog="""
For a more readable version of this help section,
see the online https://bidsmreye.readthedocs.io/.
        """,
        formatter_class=formatter_class,
    )
    parser.add_argument(
        "--model",
        help=f"Model to download. Default model: {default_model()}.",
        choices=available_models(),
        default=default_model(),
    )
    parser.add_argument(
        "--output_dir",
        help="""
The directory where the model files will be stored.
        """,
        default=Path.cwd() / "models",
    )

    return parser