Support pre-generated maps in CorrelationDecoder

[JulioAPeraza]

Closes #781.

Changes proposed in this pull request:

• New method: load_imgs. Load pre-generated meta-analytic maps for decoding.
• New attribute: results_. MetaResult object containing masker, meta-analytic maps, and tables. This attribute replaces masker, features_, and images_.

[codecov]

Codecov Report

Patch coverage: 100.00% and project coverage change: +0.17 🎉

Comparison is base (4b14bcb) 88.74% compared to head (5646893) 88.92%.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #782      +/-   ##
==========================================
+ Coverage   88.74%   88.92%   +0.17%     
==========================================
  Files          41       41              
  Lines        4825     4856      +31     
==========================================
+ Hits         4282     4318      +36     
+ Misses        543      538       -5     

Impacted Files	Coverage Δ
nimare/decode/base.py	93.18% <ø> (+2.07%)	⬆️
nimare/decode/continuous.py	96.87% <100.00%> (+2.08%)	⬆️

... and 2 files with indirect coverage changes

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

☔ View full report in Codecov by Sentry.
📢 Do you have feedback about the report comment? Let us know in this issue.

[JulioAPeraza]

@adelavega I think this is ready for review. Thanks!

[adelavega]

@JulioAPeraza can we test this PR on the pre-generated gene decoding maps? Would be interesting to see if they get the same results that NeuroVault would have previously spit out.

let's not let that prevent this merge though

[adelavega]

Looks good, but now that I've thought about it more my only concern is what happens when somebody is using CorrelationalDecoder w/ prefitted images and decoding various images?

In that case, it doesn't seem that helpful to keep returning MetaResult with all the images in transform.

We could either:

1. Only return df in transform-- assuming its rare to want to save alongside MetaResult or
2. Make it configurable what transform should return (probably w/ default to df, in my opinion). This adds a small amount of complexity.

[adelavega]

My only question is whether we should allow this to be configurable and allow only the data frame the returned?

This would prevent a lot of copies of the MetaResult object and images if somebody is doing multiple decodings and doesn't want to save the images.

Also-- what happens when you save a MetaResult object? Do the images get saved or also the tables?

[JulioAPeraza]

can we test this PR on the pre-generated gene decoding maps?

Sure!

In that case, it doesn't seem that helpful to keep returning MetaResult with all the images in transform.

I agree, I like the number 1 option. It is true that users would prefer to access the DataFrame directly instead of getting the meta-analytics map every time they run the transformer. And with that, we avoid the braking change in this PR.

This would prevent a lot of copies of the MetaResult object and images if somebody is doing multiple decodings and doesn't want to save the images.

I was wondering if at some point it would be a good idea to allow the parameter img in transform to be a list of Nifti images (similar to what nilearn does with the NiftiMasker transformer) or even a list of paths, allowing users to run multiple decoding in a single call.

Also-- what happens when you save a MetaResult object? Do the images get saved or also the tables?

MetaResult object can be saved using pickle. The images and tables are saved if we call save_maps and save_tables.

[adelavega]

Great! Lets go w/ #1

I would also be open to adding list as input

[adelavega]

LGTM!

[adelavega]

Anything holding this up?

[JulioAPeraza]

I wasn't sure I was allowed to merge this PR, because it has 1 change requested.
Merging now. Thanks!