Add examples

[shnizzedy]

Your idea

Related to

Related to openjournals/joss-reviews#7061

Rationale

Clarify input data requirements

I'm unclear on what is necessary / required for the input data for giga_connectome. I'm able to successfully run the main branch and unstable Docker container with the example data from

giga_connectome/tox.ini

Lines 26 to 45 in fb6f5d1

	[testenv:test_data]
	description = install test data
	skip_install = true
	allowlist_externals =
	mkdir
	wget
	tar
	rm
	commands =
	mkdir -p giga_connectome/data/test_data
	wget --retry-connrefused \
	--waitretry=5 \
	--read-timeout=20 \
	--timeout=15 \
	-t 0 \
	-q \
	-O giga_connectome/data/test_data/ds000017.tar.gz \
	"https://zenodo.org/record/8091903/files/ds000017-fmriprep22.0.1-downsampled-nosurface.tar.gz?download=1"
	tar -xzf giga_connectome/data/test_data/ds000017.tar.gz -C giga_connectome/data/test_data/
	rm giga_connectome/data/test_data/ds000017.tar.gz

, but with this filetree of fMRIPrep outputs from another project, I'm getting

Traceback (most recent call last):
  File "/Users/jon.clucas/opt/mambaforge/envs/giga_connectome3.12/bin/giga_connectome", line 8, in <module>
    sys.exit(main())
             ^^^^^^
  File "/Users/jon.clucas/opt/mambaforge/envs/giga_connectome3.12/lib/python3.12/site-packages/giga_connectome/run.py", line 160, in main
    workflow(args)
  File "/Users/jon.clucas/opt/mambaforge/envs/giga_connectome3.12/lib/python3.12/site-packages/giga_connectome/workflow.py", line 82, in workflow
    subject_mask_nii, subject_seg_niis = generate_gm_mask_atlas(
                                         ^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/jon.clucas/opt/mambaforge/envs/giga_connectome3.12/lib/python3.12/site-packages/giga_connectome/mask.py", line 38, in generate_gm_mask_atlas
    subject, _, _ = utils.parse_bids_name(masks[0].path)
                                          ~~~~~^^^
IndexError: list index out of range

and it's not obvious to me what the discrepancy is.

JOSS review criteria

Example usage

The authors should include examples of how to use the software (ideally to solve real-world analysis problems).

― https://joss.readthedocs.io/en/latest/review_criteria.html#example-usage

The current "Usage Notes" in the giga_connectome documentation are mostly hypothetical, like

FMRIPREP_DIR=/path/to/fmriprep_output
OUTPUT_DIR=/path/to/connectom_output
WORKING_DIR=/path/to/working_dir
DENOISE_CONFIG=/path/to/denoise_config.json

GIGA_CONNECTOME=/path/to/giga-connectome.simg

apptainer run \
    --bind ${FMRIPREP_DIR}:/data/input \
    --bind ${OUTPUT_DIR}:/data/output \
    --bind ${WORKING_DIR}:/data/working \
    --bind ${DENOISE_CONFIG}:/data/denoise_config.json \
    ${GIGA_CONNECTOME} \
    -w /data/working \
    --denoise-strategy /data/denoise_config.json \
    /data/input \
    /data/output \
    participant

Even if it's just with the data used for testing, a real example would be helpful.

[shnizzedy]

Related: #171