Output RMSE map and time series for decay model fit

[tsalo]

Closes #861.

Changes proposed in this pull request:

• Add a function to calculate RMSE 4D time series from monoexponential model fit.
• Add RMSE mean brain and time series plots to the HTML report.
• Combine RMSE time series and global signal time series (when calculated) into a desc-confounds_timeseries.tsv file. This removes the global signal time series file (desc-globalSignal_timeseries.tsv).

[codecov]

Codecov Report

Attention: Patch coverage is 94.25287% with 5 lines in your changes missing coverage. Please review.

Project coverage is 89.91%. Comparing base (af5e99a) to head (730354a).
Report is 22 commits behind head on main.

Files with missing lines	Patch %	Lines
tedana/decay.py	93.33%	1 Missing and 1 partial ⚠️
tedana/io.py	84.61%	1 Missing and 1 partial ⚠️
tedana/workflows/tedana.py	80.00%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1044      +/-   ##
==========================================
+ Coverage   89.80%   89.91%   +0.11%     
==========================================
  Files          26       26              
  Lines        3540     3621      +81     
  Branches      621      629       +8     
==========================================
+ Hits         3179     3256      +77     
- Misses        212      214       +2     
- Partials      149      151       +2     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[tsalo]

@madisoth gave me the thumbs up on this offline, so I'm opening it up for review.

[tsalo]

Here's the mean RMSE image for the 3-echo dataset:

Here's the timeseries plot (with +/- 1 SD) for the same dataset:

[handwerkerd]

I've made a bunch of suggested changes. The core of them is that I was looking at the mean & standard deviation time series in the report and didn't find the standard deviation informative, particularly since the low end was usually less than 0. I made a bunch of changes to store percentiles and plot the median and percentiles. To me showing the 2nd, 25th, median, 75th, and 98th percentiles is much more useful to understanding how RMSE varies over time & shows the extremes. For example, it make clear that the stdev was so large because the upper extrema can be very high. I also scaled the RMSE map to the 2nd-98th percentile. To make this change, it was easier to make the dataframe that is stored in the confounds file within rmse_of_fit_decay_ts

To highlight another comment below, the new function add_df_to_file had problems when used with the --overwrite option.

When this is all stabilized, a final example of the figures to the RTD documentation.

[handwerkerd]

add_df_to_file is not working when the model fit parameters and the global signal are both added to the confounds file.

This issue is visible in the output to the four echo integration test. The RMSE time series has an x-axis that is 2X the length of the time series. If you then look four-echo/sub-01_desc-confounds_timeseries.tsv it's clear what's happening. The columns are correct, but the added global_signal row is added as additional rows instead of as a new column in the existing rows.

rmse_mean	rmse_std	rmse_min	rmse_percentile02	rmse_percentile25	rmse_median	rmse_percentile75	rmse_percentile98	rmse_max	global_signal
186.89540100097656	260.73809814453125	0.6601158976554871	32.20176605224609	76.92352294921875	114.16072845458984	194.17686462402344	871.355974121094	11025.56640625	n/a
182.03968811035156	259.11785888671875	2.6228444576263428	30.978440475463863	74.24501037597656	109.76451873779295	186.53372192382812	865.50345703125	11128.96484375	n/a
183.68148803710935	258.3427734375	0.9386183619499208	31.656584701538087	75.49459838867188	111.54019165039062	189.2429656982422	868.1957470703127	11059.314453125	n/a
...
n/a	n/a	n/a	n/a	n/a	n/a	n/a	n/a	n/a	-0.5895119545327093
n/a	n/a	n/a	n/a	n/a	n/a	n/a	n/a	n/a	1.0792854501988267
n/a	n/a	n/a	n/a	n/a	n/a	n/a	n/a	n/a	-0.24254657799560972

[tsalo]

That's fixed in my most recent commit.

[tsalo]

@handwerkerd I think everything should be good now. Would you mind taking another look?

[handwerkerd]

LGTM! Thanks for humoring all my suggested changes.

[tsalo]

Thanks @handwerkerd!

Here's what the updated 3-echo timeseries plot looks like, for posterity.