Update output names to match BIDS derivatives RC2 conventions

[emdupre]

Now that BIDS Derivatives has released the RC2 status, it's quite close to stable.

We should, therefore, update our naming conventions to match these so that we can more easily interoperate with the broader BIDS community.

[tsalo]

This is brought up in the Roadmap PR, but since this issue already exists I figured I'd ask about it there.

I haven't read the full specification, but my understanding is that derivatives should follow the format <pipeline_name>/sub-<participant_label>/func/<BIDSRawBase>[_keyword-<value>]_<suffix>.<ext>. Unless we enforce BIDS-compatibility from the input data, how will we derive BIDSRawBase?

Also, since tedana operates on derivatives, how should the filename from the input derived data be incorporated into the tedana output? For example, if we were using fMRIPrep output (I know that fMRIPrep will integrate tedana, but it's a good example with well-known outputs):

Inputs:

• sub-01_task-rest_run-01_echo-1_space-MNI152NLin2009cAsym_desc-preproc_bold.nii.gz
• sub-01_task-rest_run-01_echo-2_space-MNI152NLin2009cAsym_desc-preproc_bold.nii.gz
• sub-01_task-rest_run-01_echo-3_space-MNI152NLin2009cAsym_desc-preproc_bold.nii.gz

Output possibilities:

• sub-01_task-rest_run-01_space-MNI152NLin2009cAsym_desc-preproc_desc-dnoc_bold.nii.gz
  • Duplicate "desc" keyword.
• sub-01_task-rest_run-01_space-MNI152NLin2009cAsym_desc-dnoc_bold.nii.gz
  • Removes original "desc" keyword. We won't know what the original derivative was from the filename.
• sub-01_task-rest_run-01_space-MNI152NLin2009cAsym_desc-preproc_desc2-dnoc_bold.nii.gz
  • Uses new keyword in addition to input derivative's keyword. Doesn't have to be "desc2".
• sub-01_task-rest_run-01_space-MNI152NLin2009cAsym_preprocDesc-preproc_desc-dnoc_bold.nii.gz
  • Replaces input derivative's description field with a new one, so tedana can add its own "desc". Doesn't have to be "preprocDesc".

[tsalo]

Here is a list of tedana's outputs (copied from #17). I think it's comprehensive, but if not just let me know and I can add missing derivatives. This is just a first pass, and I have no clue how many of the derivatives should be named.

Current name	Content	BIDS-compatible suffix
t2sv.nii.gz	Limited estimated T2* 3D map.	T2starmap.nii.gz
s0v.nii.gz	Limited S0 3D map.	S0map.nii.gz
ts_OC.nii.gz	Optimally combined time series.	desc-optcom_bold.nii.gz
dn_ts_OC.nii.gz	Denoised optimally combined time series.	desc-optcomDenoised_bold.nii.gz
lowk_ts_OC.nii.gz	Combined time series from "low-Kappa" rejected components.	desc-optcomRejected_bold.nii.gz
midk_ts_OC.nii.gz	Combined time series from "mid-Kappa" rejected components.	desc-optcomRejectedMidK_bold.nii.gz
hik_ts_OC.nii.gz	Combined time series from "high-Kappa" accepted components.	desc-optcomAccepted_bold.nii.gz
t2svG.nii.gz	Full T2* map/time series.	desc-full_T2starmap.nii.gz
s0vG.nii.gz	Full S0 map/time series.	desc-full_S0map.nii.gz
pca_decomposition.json	TEDPCA component table.	desc-TEDPCA_decomposition.json
pca_mixing.tsv	Mixing matrix (component time series) from PCA decomposition.	desc-TEDPCA_mixing.tsv (based on fMRIPrep MELODIC mixing matrix outputs)
pca_components.nii.gz	PCA component maps.	desc-TEDPCA_components.nii.gz (based on fMRIPrep MELODIC component outputs)
ica_decomposition.json	TEDICA component table.	desc-TEDICA_decomposition.json
ica_mixing.tsv	Mixing matrix (component time series) from ICA decomposition.	desc-TEDICA_mixing.tsv (based on fMRIPrep MELODIC mixing matrix outputs)
ica_components.nii.gz	ICA spatial component maps (beta values).	desc-TEDICA_components.nii.gz
betas_hik_OC.nii.gz	High-Kappa ICA coefficient feature set	desc-TEDICAAccepted_components.nii.gz
feats_OC2.nii.gz	Z-normalized spatial maps for high-Kappa components	desc-TEDICAAcceptedZ_components.nii.gz (based on fMRIPrep MELODIC component outputs)
T1gs.nii.gz	Spatial global signal	???
glsig.1D	Time series of global signal from optimally combined data.	desc-globalSignal_regressors.tsv
tsoc_orig.nii.gz	Optimally combined time series with global signal retained.	desc-optcomWithGlobalSignal_bold.nii.gz
tsoc_nogs.nii.gz	Optimally combined time series with global signal removed. Same as ts_OC.nii when GSR is used.	desc-optcomNoGlobalSignal_bold.nii.gz
sphis_hik.nii.gz	T1-like effect	desc-optcomAccepted_min.nii.gz
hik_ts_OC_T1c.nii.gz	T1-GS corrected high-Kappa time series by regression	desc-optcomAcceptedT1cDenoised_bold.nii.gz
dn_ts_OC_T1c.nii.gz	T1-GS corrected denoised time series	desc-optcomT1cDenoised_bold.nii.gz
betas_hik_OC_T1c.nii.gz	T1-GS corrected high-kappa components	desc-TEDICAAcceptedT1cDenoised_components.nii.gz
meica_mix_T1c.1D	T1-GS corrected mixing matrix	desc-TEDICAT1cDenoised_mixing.tsv
hik_ts_e[echo].nii.gz	High-Kappa time series for echo number echo	echo-[echo]_desc-optcomAccepted_bold.nii.gz
midk_ts_e[echo].nii.gz	Mid-Kappa time series for echo number echo	echo-[echo]_desc-optcomRejectedMidK_bold.nii.gz
lowk_ts_e[echo].nii.gz	Low-Kappa time series for echo number echo	echo-[echo]_desc-optcomRejected_bold.nii.gz
dn_ts_e[echo].nii.gz	Denoised time series for echo number echo	echo-[echo]_desc-optcomDenoised_bold.nii.gz
adaptive_mask.nii.gz	Adaptive mask. Each voxel has value corresponding to number of echoes with good signal.	desc-adaptiveGoodSignal_mask.nii.gz
tsoc_whitened.nii.gz	Optimally combined data after dimensionality reduction with PCA.	desc-optcomTEDPCAReduced_bold.nii.gz

Old outputs

Current name	Content	BIDS-compatible suffix
t2ss.nii.gz	Voxel-wise T2* estimates using ascending numbers of echoes, starting with 2.	desc-ascendingEstimates_T2starmap.nii.gz
s0vs.nii.gz	Voxel-wise S0 estimates using ascending numbers of echoes, starting with 2.	desc-ascendingEstimates_S0map.nii.gz
ica_model_betas_catd.nii.gz	Echo-specific weight maps for each of the ICA components.	echo-[echo]_desc-TEDICA_components.nii.gz
ica_model_F_R2.nii.gz	R2 F-statistic maps for each of the ICA components.	desc-TEDICA_kappa.nii.gz
ica_model_F_S0.nii.gz	S0 F-statistic maps for each of the ICA components.	desc-TEDICA_rho.nii.gz
ica_model_metric_weights.nii.gz	Weight maps used to average metrics (R2 F, S0 F, predicted R2 model values, and predicted S0 model values) in the same manner as fitmodels_direct.
ica_model_R2_pred.nii.gz	Echo-specific maps of predicted values for R2 model for each component.
ica_model_S0_pred.nii.gz	Echo-specific maps of predicted values for S0 model for each component.

[emdupre]

We should add comments to the BEP012 draft to make sure all of our derivatives are covered ! I'll go through these later this week, myself, with that in mind.

[jbteves]

@tsalo @emdupre How can I assist with this? I see that there's already an open PR. If I can help get this issue closed I'd like to do so, especially since it's mostly renaming (which is something that I think even my limited Python abilities can handle).

[tsalo]

As in #540, I think it makes sense to just not include naming information from the original files in the output files. So instead of sub-X_ses-Y_task-Z_T2starmap.nii.gz, we just have T2starmap.nii.gz. Since the outputs are in their own folder, any BIDS-compatible workflows that use tedana can rename those files according to the convention. The file names we use will still be a good start for those workflows though. I've updated the table in the third comment to reflect this.

[stale]

This issue has been automatically marked as stale because it has not had any activity in 90 days. It will be closed in 600 days if no further activity occurs. Thank you for your contributions to tedana:tada: !

[Shotgunosine]

It might be nice to have a note in the documentation that the bids convention won't include the base filename. I've just stumbled on the fact that if you're not careful when running over multiple sessions or runs, outputs will get overwritten.

[tsalo]

I can incorporate that into #822. Thanks for bringing it up!

[tsalo]

@Shotgunosine WDYT of this? The warning admonition in the middle, specifically.

[Shotgunosine]

Looks great, thanks!

…

On Fri, Dec 3, 2021 at 1:58 PM Taylor Salo ***@***.***> wrote: @Shotgunosine <https://github.com/Shotgunosine> WDYT of this? [image: image] <https://user-images.githubusercontent.com/8228902/144657971-c9d6a114-2314-4ae1-a6f7-0d9037e19051.png> — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#146 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABILLGBGG64WPMVQ3SMCE3TUPEHPHANCNFSM4GAG5YSA> . Triage notifications on the go with GitHub Mobile for iOS <https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675> or Android <https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub>.