Formalize output naming in the BIDS specification

[HippocampusGirl]

Are there any plans to formalize the naming of model outputs in the BIDS standard? I think this may be quite useful for meta-analyses and tools working with the outputs in general.

fitlins/fitlins/workflows/base.py

Lines 111 to 130 in d223f6b

	image_pattern = 'reports/[sub-{subject}/][ses-{session}/]figures/[run-{run}/]' \
	'[sub-{subject}_][ses-{session}_][task-{task}_][acq-{acquisition}_]' \
	'[rec-{reconstruction}_][run-{run}_][echo-{echo}_]' \
	'{suffix<design|corr|contrasts>}{extension<.svg>|.svg}'
	contrast_plot_pattern = 'reports/[sub-{subject}/][ses-{session}/]figures/[run-{run}/]' \
	'[sub-{subject}_][ses-{session}_][task-{task}_][acq-{acquisition}_]' \
	'[rec-{reconstruction}_][run-{run}_][echo-{echo}_][space-{space}_]' \
	'contrast-{contrast}_stat-{stat<effect|variance|z|p|t|F|FEMA>}_ortho{extension<.png>|.png}'
	design_matrix_pattern = '[sub-{subject}/][ses-{session}/]' \
	'[sub-{subject}_][ses-{session}_][task-{task}_][acq-{acquisition}_]' \
	'[rec-{reconstruction}_][run-{run}_][echo-{echo}_]_{suffix<design>}{extension<.tsv>|.tsv}'
	contrast_pattern = '[sub-{subject}/][ses-{session}/]' \
	'[sub-{subject}_][ses-{session}_][task-{task}_][acq-{acquisition}_]' \
	'[rec-{reconstruction}_][run-{run}_][echo-{echo}_][space-{space}_]' \
	'contrast-{contrast}_stat-{stat<effect|variance|z|p|t|F|FEMA>}_' \
	'statmap{extension<.nii.gz|.dscalar.nii>}'
	model_map_pattern = '[sub-{subject}/][ses-{session}/]' \
	'[sub-{subject}_][ses-{session}_][task-{task}_][acq-{acquisition}_]' \
	'[rec-{reconstruction}_][run-{run}_][echo-{echo}_][space-{space}_]' \
	'stat-{stat<rSquare|logLikelihood|tsnr|errorts|a|b|lam|LjungBox|residtsnr|residsmoothness|residwhstd>}_statmap{extension<.nii.gz|.dscalar.nii|.tsv>}'

[effigies]

Would be good to loop in @tsalo. We should start up a small BEP.

[shashankbansal6]

@effigies Just an fyi, for the new bids stats model, I had to update these patterns to include level and nodename -

fitlins/fitlins/workflows/base.py

Lines 149 to 177 in c05c33f

	image_pattern = (
	"reports/[sub-{subject}/][ses-{session}/]figures/[run-{run}/]"
	"[level-{level}_][name-{name}_][sub-{subject}_][ses-{session}_][task-{task}_][acq-{acquisition}_]"
	"[rec-{reconstruction}_][run-{run}_][echo-{echo}_]"
	"{suffix<design|corr|contrasts>}{extension<.svg>|.svg}"
	)
	contrast_plot_pattern = (
	"reports/[sub-{subject}/][ses-{session}/]figures/[run-{run}/]"
	"[level-{level}_][name-{name}_][sub-{subject}_][ses-{session}_][task-{task}_][acq-{acquisition}_]"
	"[rec-{reconstruction}_][run-{run}_][echo-{echo}_][space-{space}_]"
	"contrast-{contrast}_stat-{stat<effect|variance|z|p|t|F|Meta>}_ortho{extension<.png>|.png}"
	)
	design_matrix_pattern = (
	"[sub-{subject}/][ses-{session}/]"
	"[level-{level}_][name-{name}_][sub-{subject}_][ses-{session}_][task-{task}_][acq-{acquisition}_]"
	"[rec-{reconstruction}_][run-{run}_][echo-{echo}_]_{suffix<design>}{extension<.tsv>|.tsv}"
	)
	contrast_pattern = (
	"[sub-{subject}/][ses-{session}/]"
	"[level-{level}_][name-{name}_][sub-{subject}_][ses-{session}_][task-{task}_][acq-{acquisition}_]"
	"[rec-{reconstruction}_][run-{run}_][echo-{echo}_][space-{space}_]"
	"contrast-{contrast}_stat-{stat<effect|variance|z|p|t|F|Meta>}_"
	"statmap{extension<.nii.gz|.dscalar.nii>}"
	)
	model_map_pattern = (
	"[sub-{subject}/][ses-{session}/]"
	"[level-{level}_][name-{name}_][sub-{subject}_][ses-{session}_][task-{task}_][acq-{acquisition}_]"
	"[rec-{reconstruction}_][run-{run}_][echo-{echo}_][space-{space}_]"
	"stat-{stat<rSquare|logLikelihood|tsnr|errorts|a|b|lam|LjungBox|residtsnr|residsmoothness|residwhstd>}_statmap{extension<.nii.gz|.dscalar.nii|.tsv>}"

This was for 2 reasons:

1. In the dataset level analysis, the default entities provided by pybids are usually just {contrast: <contrast_name>} and the output files in the report are overwritten from one dataset node to another.
2. Currently since the dataset level files are not unique, its not possible to find and use them in the reports.

We could probably add a dataset directory to these common patterns but we will still need a unique set of entities to create the files. I think adding the level and the node name as entities will probably something we'll need to consider if we plan to support several subject/dataset level nodes.

[tsalo]

@effigies would this BEP just cover GLM outputs or other types of models?

[effigies]

The glm is our main use case, but I don't see any reason to stop there.

[tsalo]

I haven't really added anything to this one other than a tentative title and the filename patterns, but here's a GDoc we can use: https://docs.google.com/document/d/1KHzp-yk8KXvkUIhtN71WU0m4P4kKT9C1yvI-i9_kNeY/edit?usp=sharing

EDIT: I've also opened bids-standard/bids-specification#887.