Merge pull request #1155 from nipreps/fix/multi-echo-bold

ENH: Large overhaul of the functional workflow w/focus on ME-EPI

docs/source/conf.py

@@ -90,7 +90,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = "en"
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:

mriqc/cli/parser.py

@@ -538,7 +538,7 @@ def parse_args(args=None, namespace=None):
         config.execution.participant_label,
         session_id=config.execution.session_id,
         task=config.execution.task_id,
-        group_echos=False,
+        group_echos=True,
         bids_filters=config.execution.bids_filters,
         queries={mod: DEFAULT_BIDS_QUERIES[mod] for mod in lc_modalities}
     )
@@ -575,7 +575,7 @@ def parse_args(args=None, namespace=None):
     # Estimate the biggest file size / leave 1GB if some file does not exist (datalad)
     with suppress(FileNotFoundError):
         config.workflow.biggest_file_gb = _get_biggest_file_size_gb(
-            [i for sublist in config.workflow.inputs.values() for i in sublist]
+            config.workflow.inputs.values()
         )
 
     # set specifics for alternative populations
@@ -593,11 +593,14 @@ def parse_args(args=None, namespace=None):
 
 
 def _get_biggest_file_size_gb(files):
+    """Identify the largest file size (allows multi-echo groups)."""
+
     import os
 
-    max_size = 0
+    sizes = []
     for file in files:
-        size = os.path.getsize(file) / (1024**3)
-        if size > max_size:
-            max_size = size
-    return max_size
+        if isinstance(file, (list, tuple)):
+            sizes.append(_get_biggest_file_size_gb(file))
+        else:
+            sizes.append(os.path.getsize(file))
+    return max(sizes) / (1024**3)

mriqc/data/bootstrap-func.yml

@@ -26,69 +26,50 @@
 ###########################################################################
 
 packagename: mriqc
-title: '{filename} :: Functional MRIQC report'
+title: "{filename} :: MRIQC's BOLD fMRI report"
 sections:
 - name: Summary
   reportlets:
   - bids: {datatype: figures, desc: summary, extension: [.html]}
-- name: Basic visual report
+- name: Basic echo-wise reports
+  ordering: echo
   reportlets:
-  - bids: {datatype: figures, desc: zoomed}
-    caption: This panel shows a mosaic of the brain. This mosaic is the most suitable to
-      screen head-motion intensity inhomogeneities, global/local noise, signal leakage
-      (for example, from the eyeballs and across the phase-encoding axis), etc.
-    subtitle: Voxel-wise average of BOLD time-series, zoomed-in covering just the brain
   - bids: {datatype: figures, desc: stdev}
     subtitle: Standard deviation of signal through time
     caption: The voxel-wise standard deviation of the signal (variability along time).
   - bids: {datatype: figures, desc: carpet}
     subtitle: Carpetplot and nuisance signals
     caption: The so-called «carpetplot» may assist in assessing head-motion
       derived artifacts and respiation effects.
-- name: Extended visual report
+- name: Extended reports shared across echos
   reportlets:
-  - bids: {datatype: figures, desc: background}
-    caption: This panel shows a mosaic enhancing the background around the head.
-      Artifacts usually unveil themselves in the air surrounding the head, where no signal
-      sources are present.
-    subtitle: View of the background of the voxel-wise average of the BOLD timeseries
-  - bids: {datatype: figures, desc: mean}
-    subtitle: Average signal through time
-    caption: The average signal calculated across the last axis (time).
-  - bids: {datatype: figures, desc: airmask}
-    caption: The <em>hat</em>-mask calculated internally by MRIQC. Some metrics will use this
-      mask, for instance, to find out artifacts and estimate the spread of gaussian noise
-      added to the signal. This mask leaves out the air around the face to avoid measuring
-      noise sourcing from the eyeballs and their movement.
-    subtitle: '&laquo;Hat&raquo;-mask'
-  - bids: {datatype: figures, desc: noisefit}
-    caption: The noise fit internally estimated by MRIQC to calculate the QI<sub>1</sub> index
-      proposed by <a href="https://doi.org/10.1002/mrm.21992" target="_blank">Mortamet et al. (2009)</a>.
-    subtitle: Distribution of the noise within the <em>hat</em> mask
-    style:
-      max-width: 450px
-  - bids: {datatype: figures, desc: artifacts}
-    caption: Mask of artifactual intensities identified within the <em>hat</em>-mask.
-    subtitle: Artifactual intensities on the background
   - bids: {datatype: figures, desc: brainmask}
     caption: Brain mask as internally extracted by MRIQC. Defects on the brainmask could
       indicate problematic aspects of the image quality-wise.
     subtitle: Brain extraction performance
-  - bids: {datatype: figures, desc: head}
-    caption: A mask of the head calculated internally by MRIQC.
-    subtitle: Head mask
-  - bids: {datatype: figures, desc: segmentation}
-    caption: Brain tissue segmentation, as internally extracted by MRIQC.
-      Defects on this segmentation, as well as noisy tissue labels could
-      indicate problematic aspects of the image quality-wise.
-    subtitle: Brain tissue segmentation
   - bids: {datatype: figures, desc: norm}
     caption: This panel shows a <em>quick-and-dirty</em> nonlinear registration into
       the <code>MNI152NLin2009cAsym</code> template accessed with
       <a href="https://templateflow.org/browse" target="_blank"><em>TemplateFlow</em></a>.
     subtitle: Spatial normalization of the anatomical image
     static: false
 
+- name: Extended echo-wise reports
+  ordering: echo
+  reportlets:
+  - bids: {datatype: figures, desc: background}
+    caption: This panel shows a mosaic enhancing the background around the head.
+      Artifacts usually unveil themselves in the air surrounding the head, where no signal
+      sources are present.
+    subtitle: View of the background of the voxel-wise average of the BOLD timeseries
+  - bids: {datatype: figures, desc: mean}
+    subtitle: Average signal through time
+    caption: The average signal calculated across the last axis (time).
+  - bids: {datatype: figures, desc: zoomed}
+    caption: This panel shows a mosaic of the brain. This mosaic is the most suitable to
+      screen head-motion intensity inhomogeneities, global/local noise, signal leakage
+      (for example, from the eyeballs and across the phase-encoding axis), etc.
+    subtitle: Voxel-wise average of BOLD time-series, zoomed-in covering just the brain
 
 - name: About
   nested: true

mriqc/data/testdata/group_bold.tsv

@@ -1,10 +1,10 @@
 bids_name	aor	aqi	dummy_trs	dvars_nstd	dvars_std	dvars_vstd	efc	fber	fd_mean	fd_num	fd_perc	fwhm_avg	fwhm_x	fwhm_y	fwhm_z	gcor	gsr_x	gsr_y	size_t	size_x	size_y	size_z	snr	spacing_tr	spacing_x	spacing_y	spacing_z	summary_bg_k	summary_bg_mad	summary_bg_mean	summary_bg_median	summary_bg_n	summary_bg_p05	summary_bg_p95	summary_bg_stdv	summary_fg_k	summary_fg_mad	summary_fg_mean	summary_fg_median	summary_fg_n	summary_fg_p05	summary_fg_p95	summary_fg_stdv	tsnr
-sub-ds205s03_task-functionallocalizer_run-01_bold	0.006175853658536585	0.00782700987804878	0	23.982385659135808	1.1029845019753086	1.0482825533333335	0.5579308153780409	899.73681640625	0.26118389619646404	32	39.02439024390244	2.043014166666667	1.92755	2.1932675	2.008225	0.0592534	-0.00898530799895525	0.04696183279156685	82	53	53	27	4.774209217164637	2.200000047683716	4.0	4.0	4.0	26.65223575628058	7.067350153923593	48.65173053536583	25.51134490966797	55113.0	18.871950149536133	173.51107788085938	62.96822585876589	0.598545770862756	139.55821373035255	769.8158763353686	765.2284240722656	20730.0	494.1331787109375	1041.6568603515625	160.27993998869655	56.32470703125
-sub-ds205s03_task-view_run-01_bold	0.0038563043478260866	0.010398965217391304	0	21.001368679560443	1.0080583680219781	0.9704656724175822	0.555268631792101	955.6907958984375	0.16520736608810047	18	19.565217391304348	1.9890683333333332	1.86912	2.1692175	1.9288675	0.0188429	-0.008540591225028038	0.04196126013994217	92	53	53	27	4.8924206716943655	2.200000047683716	4.0	4.0	4.0	24.78328036616209	7.284480140006654	48.01004600493635	25.337934494018555	55115.0	13.708492279052734	173.4195098876953	63.24374935408871	0.6193718723673731	135.63136294470496	785.625103328459	783.30322265625	20728.0	509.40557861328125	1057.23828125	160.10158982252509	56.46196937561035
-sub-ds205s03_task-view_run-02_bold	0.000538804347826087	0.00718998347826087	0	23.167324632417582	0.9661779338461531	0.9044185629670329	0.5566515976243607	906.2960815429688	0.22854716046970905	44	47.82608695652174	2.0270425000000003	1.898665	2.1941825	1.98828	0.350186	-0.008191297762095928	0.045305926352739334	92	53	53	27	4.819771892578718	2.200000047683716	4.0	4.0	4.0	24.552996566765586	7.135003381683008	48.0985481401069	25.58615016937256	55126.0	16.843839645385742	171.75970458984375	61.92351887941012	0.654934961442704	137.18513622307717	774.2342621452095	770.2647094726562	20717.0	498.0149230957031	1046.4920654296875	159.8096624186355	44.19522476196289
-sub-ds205s07_task-functionallocalizer_run-01_bold	0.005997083333333333	0.0056276609722222225	0	21.73490091760564	1.1161214411267604	1.0305108769014089	0.5398076828636086	979.1392822265625	0.1550487344317312	15	20.833333333333332	1.7913891666666668	1.7012025	1.8870975	1.7858675	0.0356344	-0.006339103449136019	0.029900137335062027	72	53	53	27	5.051380236662852	2.200000047683716	4.0	4.0	4.0	23.998434132266535	6.359841724478726	40.97200099097582	22.96632194519043	56199.0	13.510886192321777	148.19041442871094	54.7943334817377	0.42502710232227514	134.22454681982717	722.5941279030118	718.6438293457031	19644.0	477.47076416015625	953.461181640625	142.26320406635728	68.8161506652832
-sub-ds205s07_task-view_run-01_bold	0.0037941304347826085	0.009004425434782607	0	21.771277794505497	1.0383257392307694	0.9654323329670328	0.5374363883770776	996.05810546875	0.1520993052375479	15	16.304347826086957	1.8006975	1.698995	1.8907725	1.812325	0.0408048	-0.005473143886774778	0.029460299760103226	92	53	53	27	5.072217446804501	2.200000047683716	4.0	4.0	4.0	27.23682449098333	6.229042844827164	39.84597218066951	22.68582057952881	56266.0	13.13893985748291	139.88406372070312	53.19358553170623	0.3440927682297894	134.06510192792	720.2195639126317	715.9733276367188	19577.0	476.44183349609375	949.2680053710938	141.1522768548468	57.291603088378906
-sub-ds205s07_task-view_run-02_bold	0.001657826086956522	0.008996689347826086	0	21.519903371868143	1.03221585	0.9588135309890113	0.5394046827226318	978.5082397460938	0.15451170465747024	18	19.565217391304348	1.8057741666666667	1.7069875	1.8966275	1.8137075	0.0433865	-0.006386041175574064	0.03140100836753845	92	53	53	27	5.056518385567245	2.200000047683716	4.0	4.0	4.0	29.670872739050793	6.462488049835068	40.8786782498388	22.991168975830078	56204.0	13.375846862792969	145.70977783203125	55.307788548732276	0.4335730121828525	135.24980824168193	723.5399965684157	719.189453125	19639.0	481.1661376953125	953.2984008789062	142.22654558293314	59.76730728149414
-sub-ds205s09_task-view_acq-LR_run-01_bold	0.002976986301369863	0.013025251780821916	0	21.405761824861116	1.0611945656944441	0.9949810694444441	0.513063203363028	1207.71533203125	0.3258302280827085	45	61.64383561643836	1.7912675	1.6990475	1.91971	1.755045	0.0362147	-0.005499124526977539	0.01900400035083294	73	53	53	27	5.854353348400624	2.200000047683716	4.0	4.0	4.0	25.199608221336092	5.712747254148226	39.895556611046395	23.25909996032715	58097.0	15.119007110595703	139.44947814941406	56.095377999258176	1.178096485114681	117.15050549333893	796.3205729290771	808.3048706054688	17746.0	526.5880737304688	995.4718627929688	138.0651368134319	58.34690284729004
-sub-ds205s09_task-view_acq-LR_run-02_bold	0.005996575342465754	0.015215327260273973	0	34.39419094722222	1.6192232063888892	1.6501877419444442	0.5136460861041277	1192.3255615234375	0.3345943377548133	47	64.38356164383562	1.7920308333333335	1.6996125	1.920615	1.755865	0.0313875	-0.005142268259078264	0.018914325162768364	73	53	53	27	5.851459215059082	2.200000047683716	4.0	4.0	4.0	25.07199243533304	5.957362424448292	40.199861866481136	23.448966026306152	58096.0	15.263423919677734	139.87855529785156	56.15791257667716	1.1742077271466247	117.28293886411426	797.5247600734042	809.6943969726562	17747.0	526.8685302734375	997.0792846679688	138.3708840384822	51.352577209472656
-sub-ds205s09_task-view_acq-RL_run-01_bold	0.02578232876712329	0.02322782465753425	0	30.880940159027773	1.2222362369444444	1.0929697275	0.5115397239733915	1229.69287109375	0.5699059645824405	53	72.6027397260274	1.8186083333333334	1.72236	1.9520325	1.7814325	0.0447734	-0.003605152480304241	0.017525115981698036	73	53	53	27	5.840571587502318	2.200000047683716	4.0	4.0	4.0	28.28470212917516	5.378516442052904	39.71076207043191	23.19632911682129	58165.0	17.226463317871094	134.9324951171875	56.23862202860845	1.1305372215596474	117.89153513001754	800.2769560314895	813.4251403808594	17678.0	528.4014892578125	1001.2677612304688	139.26755646464403	45.58633995056152
+sub-ds205s03_task-functionallocalizer_run-01_bold	0.0038873170731707324	0.007676269512195123	0	23.556566426419753	1.111688350987654	1.037835274938272	0.5480388108408939	946.6738891601562	0.26118389619646404	32	39.02439024390244	2.460305	2.3309525	2.749775	2.3001875	0.0680646	-0.009326859377324581	0.05734974890947342	82	53	53	27	4.452167473312103	2.200000047683716	4.0	4.0	4.0	32.7759659672557	7.720380258975168	49.68507569151857	24.975608825683594	55688.0	2.341463327407837	179.5365753173828	79.87659545341923	1.3897322764135298	138.87641036027622	767.1765602872674	768.451171875	20155.0	461.5243835449219	1042.731689453125	172.5973051795346	60.897049377672374
+sub-ds205s03_task-view_run-01_bold	0.004324782608695651	0.008262664456521738	0	21.120018382857136	1.0831709981318685	1.0370256236263742	0.5459090166346154	1002.2031860351562	0.16520736608810047	18	19.565217391304348	2.342805	2.234215	2.613075	2.181125	0.0235103	-0.0050179013051092625	0.04793250188231468	92	53	53	27	4.4829699247170405	2.200000047683716	4.0	4.0	4.0	29.71988008857921	7.139052847581331	46.66574967004908	24.7608699798584	55362.0	0.032608695328235626	164.9891357421875	71.66784333938988	1.596677545134333	133.64368600192023	779.8773281882851	783.8695678710938	20481.0	457.5434875488281	1054.61962890625	174.85070038268285	62.58223795099184
+sub-ds205s03_task-view_run-02_bold	0.0012682608695652171	0.007114478586956522	0	33.47404192791209	1.3371308202197805	0.9764774098901093	0.5494999624875053	955.73681640625	0.22854716046970905	44	47.82608695652174	2.4598116666666665	2.3444425	2.7437	2.2912925	0.359354	-0.009432817809283733	0.052887145429849625	92	53	53	27	4.419438774661141	2.200000047683716	4.0	4.0	4.0	29.03249120482654	7.7192010499810335	49.54353785439428	24.934783935546875	55415.0	0.20652174949645996	181.78260803222656	80.45599936028407	1.4009872052560288	139.07454009400536	768.1427012059421	770.8587036132812	20428.0	459.5326232910156	1046.8260498046875	174.42029972293017	45.2559957196936
+sub-ds205s07_task-functionallocalizer_run-01_bold	0.006487361111111111	0.006664996805555556	0	26.95528650943662	1.4143280252112678	1.3278985984507037	0.5345065899755163	1009.7532348632812	0.1550487344317312	15	20.833333333333332	2.2598908333333334	2.16087	2.40925	2.2095525	0.0386767	-0.005986093543469906	0.03482493385672569	72	53	53	27	4.598492679701605	2.200000047683716	4.0	4.0	4.0	35.90517987432788	6.32165175453679	43.5521938439157	22.56944465637207	56450.0	0.0	157.3333282470703	77.35003442698779	1.656221989802022	134.60795658544046	716.0395720200634	717.1805419921875	19393.0	440.0694580078125	951.6666870117188	155.95589707318132	73.35539675597101
+sub-ds205s07_task-view_run-01_bold	0.005007608695652174	0.010561140108695653	0	26.932940011208803	1.2896941338461543	1.168551503516483	0.5321868933927048	1023.4715576171875	0.1520993052375479	15	16.304347826086957	2.266245	2.184035	2.4189475	2.1957525	0.0478984	-0.006112692411988974	0.03277275711297989	92	53	53	27	4.595802249004055	2.200000047683716	4.0	4.0	4.0	33.63529478261993	6.2365988314754315	42.79862974194479	22.380435943603516	56588.0	0.3804347813129425	153.56521606445312	75.85331035278197	1.585165284213823	135.14239559316104	713.6245609062549	715.9891357421875	19255.0	437.3913269042969	947.5869750976562	155.78793525432897	63.332828449318185
+sub-ds205s07_task-view_run-02_bold	0.0027991304347826083	0.008415782065217392	0	27.396022419560428	1.345632817142857	1.2136871409890106	0.5333849667366366	1016.1077880859375	0.15451170465747024	18	19.565217391304348	2.271710833333333	2.1726275	2.433375	2.20913	0.0505144	-0.005830460228025913	0.03532366082072258	92	53	53	27	4.598664236595992	2.200000047683716	4.0	4.0	4.0	36.078683930448996	6.575017673595487	43.39332640278381	22.565217971801758	56589.0	1.22826087474823	155.56521606445312	75.49560044499137	1.6540993322199018	136.17376514793506	717.751513360383	719.2989501953125	19254.0	443.8260803222656	952.5978393554688	156.41069531029106	64.89047080953605
+sub-ds205s09_task-view_acq-LR_run-01_bold	0.003159041095890411	0.010028379999999998	0	20.396152721388898	1.090989740416667	1.0059027894444443	0.5048353890125871	1243.320556640625	0.3258302280827085	45	61.64383561643836	2.0852608333333333	2.0588275	2.2995125	1.8974425	0.0461463	-0.0019858605228364468	0.021903924643993378	73	53	53	27	5.292682271102816	2.200000047683716	4.0	4.0	4.0	33.98009379704732	5.949264906571304	39.07313696894552	22.956466674804688	58369.0	1.0936830043792725	132.37034606933594	62.99641049623399	2.7398312528413937	115.58686871143783	791.6591133225957	809.4622802734375	17474.0	483.6707458496094	994.6715698242188	152.93552051211557	66.51667785644531
+sub-ds205s09_task-view_acq-LR_run-02_bold	0.005322328767123288	0.012026137260273973	0	33.41256753611111	1.7174510266666663	1.7695175424999998	0.5052536160578726	1231.6690673828125	0.3345943377548133	47	64.38356164383562	2.0866866666666666	2.0591175	2.3078075	1.893135	0.0393612	-0.0014911222970113158	0.021568207070231438	73	53	53	27	5.293464753553317	2.200000047683716	4.0	4.0	4.0	33.28261057706237	6.199152583273201	39.20170865624716	23.102066040039062	58361.0	1.1750245094299316	131.959716796875	62.4980652302799	2.7186948010130694	115.65690863557867	792.8781950379683	810.7703247070312	17482.0	484.3922119140625	996.912109375	153.16001398016576	59.753475189208984
+sub-ds205s09_task-view_acq-RL_run-01_bold	0.015073150684931508	0.015836369041095893	0	34.205267455972226	1.4370176472222222	1.2820233763888884	0.5044353080190683	1274.420654296875	0.5699059645824405	53	72.6027397260274	2.08056	2.068795	2.288455	1.88443	0.0560156	-0.0013055995805189013	0.018262900412082672	73	53	53	27	5.229556365898414	2.200000047683716	4.0	4.0	4.0	31.57766555712935	5.840893620522815	38.89056185642749	22.814455032348633	58350.0	3.888171911239624	132.03933715820312	61.89358205002823	2.599912401497959	117.24294190485038	794.526159305144	814.4539184570312	17493.0	471.96441650390625	999.9562377929688	155.73608576273267	52.76657485961914

mriqc/data/tests/ds000005/sub-01/func/sub-01_task-mixedgamblestask_run-01_bold.json

@@ -0,0 +1,3 @@
+{
+	"EchoTime": 0.030
+}

mriqc/data/tests/ds000005/sub-01/func/sub-01_task-mixedgamblestask_run-02_bold.json

@@ -0,0 +1 @@
+sub-01_task-mixedgamblestask_run-01_bold.json

mriqc/data/tests/ds000005/sub-01/func/sub-01_task-mixedgamblestask_run-03_bold.json

@@ -0,0 +1 @@
+sub-01_task-mixedgamblestask_run-01_bold.json

mriqc/interfaces/bids.py

@@ -49,6 +49,7 @@ class IQMFileSinkInputSpec(DynamicTraitedSpec, BaseInterfaceInputSpec):
     rec_id = traits.Either(None, Str, usedefault=True)
     run_id = traits.Either(None, traits.Int, usedefault=True)
     dataset = Str(desc="dataset identifier")
+    dismiss_entities = traits.List(["part"], usedefault=True)
     metadata = traits.Dict()
     provenance = traits.Dict()
 
@@ -111,6 +112,17 @@ def _gen_outfile(self):
                 break
         in_file = str(path.relative_to(bids_root))
 
+        if (
+            isdefined(self.inputs.dismiss_entities)
+            and (dismiss := self.inputs.dismiss_entities)
+        ):
+            for entity in dismiss:
+                bids_chunks = [
+                    chunk for chunk in path.name.split("_")
+                    if not chunk.startswith(f"{entity}-")
+                ]
+                path = path.parent / "_".join(bids_chunks)
+
         # Build path and ensure directory exists
         bids_path = out_dir / in_file.replace("".join(Path(in_file).suffixes), ".json")
         bids_path.parent.mkdir(parents=True, exist_ok=True)