diff --git a/docs/source/conf.py b/docs/source/conf.py index c5d70af..4d28c2d 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -25,6 +25,7 @@ "sphinx.ext.autodoc", "sphinx.ext.autosummary", "sphinx.ext.napoleon", + "sphinxarg.ext", ] templates_path = ["_templates"] @@ -35,7 +36,6 @@ # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output html_theme = "sphinx_rtd_theme" -html_static_path = ["_static"] # -- Options for myst_parser ------------------------------------------------- myst_enable_extensions = ["colon_fence"] diff --git a/docs/source/contributing.md b/docs/source/contributing.md index 29aa39a..fd4fca8 100644 --- a/docs/source/contributing.md +++ b/docs/source/contributing.md @@ -75,7 +75,7 @@ The workflow is the same as code contributions, with some minor differences. 1. Install the `[doc]` dependencies. ```bash -pip install -e .[doc] +pip install -e '.[doc]' ``` 2. After making changes, build the docs locally: @@ -104,7 +104,7 @@ This tells the development team that your pull request is a "work-in-progress", One your PR is ready a member of the development team will review your changes to confirm that they can be merged into the main codebase. -## Making an release +## Making a release Currently this project is not pushed to PyPi. We simply tag the version on the repository so users can reference the version of installation. diff --git a/docs/source/usage.md b/docs/source/usage.md index 59edbc3..95271ed 100644 --- a/docs/source/usage.md +++ b/docs/source/usage.md @@ -1,48 +1,17 @@ # Usage Notes -```bash -usage: giga_connectome [-h] [-v] [--participant_label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]] [-w WORK_DIR] [--atlas ATLAS] - [--denoise-strategy DENOISE_STRATEGY] [--standardize {zscore,psc}] [--smoothing_fwhm SMOOTHING_FWHM] [--reindex-bids] - [--bids-filter-file BIDS_FILTER_FILE] - bids_dir output_dir {participant,group} - -Generate connectome based on denoising strategy for fmriprep processed dataset. - -positional arguments: - bids_dir The directory with the input dataset (e.g. fMRIPrep derivative)formatted according to the BIDS standard. - output_dir The directory where the output files should be stored. - {participant,group} Level of the analysis that will be performed. Only group level is allowed as we need to generate a dataset inclusive brain mask. - -optional arguments: - -h, --help show this help message and exit - -v, --version show program's version number and exit - --participant_label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...] - The label(s) of the participant(s) that should be analyzed. The label corresponds to sub- from the BIDS spec (so it does not include 'sub-'). If this parameter is not provided all subjects should be analyzed. Multiple participants can be specified with a space separated list. - -w WORK_DIR, --work-dir WORK_DIR - Path where intermediate results should be stored. - --atlas ATLAS The choice of atlas for time series extraction. Default atlas choices are: 'Schaefer20187Networks, 'MIST', 'DiFuMo'. User can pass a path to a json file containing configuration for their own choice of atlas. The default is 'MIST'. - --denoise-strategy DENOISE_STRATEGY - The choice of post-processing for denoising. The default choices are: 'simple', 'simple+gsr', 'scrubbing.2', 'scrubbing.2+gsr', 'scrubbing.5', 'scrubbing.5+gsr', 'acompcor50', 'icaaroma'. User can pass a path to a json file containing configuration for their own choice of denoising strategy. The defaultis 'simple'. - --standardize {zscore,psc} - The choice of signal standardization. The choices are z score or percent signal change (psc). The default is 'zscore'. - --smoothing_fwhm SMOOTHING_FWHM - Size of the full-width at half maximum in millimeters of the spatial smoothing to apply to the signal. The default is 5.0. - --reindex-bids Reindex BIDS data set, even if layout has already been created. - --bids-filter-file BIDS_FILTER_FILE - A JSON file describing custom BIDS input filters using PyBIDS.We use the same format as described in fMRIPrep documentation: https://fmriprep.org/en/latest/faq.html#how-do-i-select-only-certain-files-to-be-input-to-fmriprepHowever, the query filed should always be 'bold' +## Command line interface +```{eval-rst} +.. argparse:: + :prog: giga_connectome + :module: giga_connectome.run + :func: global_parser ``` -When performing `participant` level analysis, the output is a HDF5 file per participant that was passed to `--participant_label` or all subjects under `bids_dir`. -The output file name is: `sub-_atlas-_desc-.h5` - -When performing `group` level analysis, the output is a HDF5 file per participant that was passed to `--participant_label` or all subjects under `bids_dir`. -The output file name is: `atlas-_desc-.h5` -The file will contain time series and connectomes of each subject, as well as group average connectomes. - ## Writing configuration files -All preset can be found in `giga_connectome/data` +All preset can be found in [`giga_connectome/data`](https://github.com/SIMEXP/giga_connectome/tree/main/giga_connectome/data). ### Denoising strategy @@ -62,13 +31,14 @@ In a `json` file, define the customised strategy in the following format: } ``` -See examples in `giga_connectome/data/denoise_strategy`. +See examples in [`giga_connectome/data/denoise_strategy`](https://github.com/SIMEXP/giga_connectome/tree/main/giga_connectome/data/denoise_strategy). ### Atlas After the atlas files are organised according to the [TemplateFlow](https://www.templateflow.org/python-client/0.7.1/naming.html) convention. A minimal set up should look like this: + ``` my_atlas/ └──tpl-MNI152NLin2009cAsym/ # template directory of a valid template name @@ -96,4 +66,4 @@ In a `json` file, define the customised atlas. We will use the atlas above as an } ``` -See examples in `giga_connectome/data/atlas`. +See examples in [`giga_connectome/data`](https://github.com/SIMEXP/giga_connectome/tree/main/giga_connectome/data). diff --git a/giga_connectome/run.py b/giga_connectome/run.py index b39365d..b265a32 100644 --- a/giga_connectome/run.py +++ b/giga_connectome/run.py @@ -4,8 +4,7 @@ from giga_connectome import __version__ -def main(argv=None): - """Entry point.""" +def global_parser() -> argparse.ArgumentParser: parser = argparse.ArgumentParser( formatter_class=argparse.RawTextHelpFormatter, description=( @@ -105,6 +104,12 @@ def main(argv=None): "pipeline (option A). The default is False.", action="store_true", ) + return parser + + +def main(argv=None): + """Entry point.""" + parser = global_parser() args = parser.parse_args(argv) diff --git a/pyproject.toml b/pyproject.toml index 66c5fa3..63ae89d 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -45,7 +45,8 @@ test = [ docs = [ "sphinx", "sphinx_rtd_theme", - "myst-parser" + "myst-parser", + "sphinx-argparse" ] # Aliases tests = ["giga_connectome[test]"]