[MRG] Improve limo doc and regression example

[JoseAlanis]

Reference issue

Example: Picks up on #6710.

What does this implement/fix?

• Improves documentation and infos on the LIMO dataset.
• Fixes minor issues in the LIMO fetcher.

Additional information

Hey guys, sorry for the long description.
As suggested in #6710, I'm adding a bunch of changes to improve the documentation in the LIMO dataset.

I also extended the corresponding example, now taking a deeper look at how the data looks like and what information is provided in the metadata of the LIMO epochs.

The second part of the example (~ line 255) picks up on some of the work I did during my GSoC project on improving linear regression functionality (also refer to #6710 for details).

One of the major changes was to use sklearn to fit the linear models, wich would provide some extra degree of flexibility when handling the output of the linear models. I included a proposal for how to wrap sklearn's LinearRegression in a class (~ 300) line, which allows to keep the results of the first level (i.e., subject level) analysis all together. Then we could use this class to compute specific outputs. Currently for instance, one can extract an evoked object containing the beta coefficients of the subject level analysis or one can extract the "raw" beta coefficients as an array, which could be later used for group-level analysis. Getting the "raw" beta values would also allow us to compute inference measures on a group-level or a subjects levels (e.g., r-squared to find best fitting electrodes for subjects, etc.).

For convenience, I define the linear regression class in the example.

Looking forward to hear your comments (cc @dengemann, @jona-sassenhagen).

[codecov]

Codecov Report

Merging #6783 into master will increase coverage by 0.01%.
The diff coverage is 0%.

@@            Coverage Diff             @@
##           master    #6783      +/-   ##
==========================================
+ Coverage   89.67%   89.69%   +0.01%     
==========================================
  Files         430      430              
  Lines       77005    76973      -32     
  Branches    12546    12527      -19     
==========================================
- Hits        69058    69042      -16     
+ Misses       5140     5134       -6     
+ Partials     2807     2797      -10

[jona-sassenhagen]

Need to fix merge conflicts ...

[jona-sassenhagen]

It looks like the only things that failed on the first run were pep violations:

examples/datasets/plot_limo_data.py:8:59: W291 trailing whitespace
examples/datasets/plot_limo_data.py:10:81: W291 trailing whitespace
examples/datasets/plot_limo_data.py:11:28: W291 trailing whitespace
examples/datasets/plot_limo_data.py:12:55: W291 trailing whitespace
examples/datasets/plot_limo_data.py:19:64: W291 trailing whitespace
examples/datasets/plot_limo_data.py:21:77: W291 trailing whitespace
examples/datasets/plot_limo_data.py:22:79: W291 trailing whitespace
examples/datasets/plot_limo_data.py:26:79: W291 trailing whitespace
examples/datasets/plot_limo_data.py:27:78: W291 trailing whitespace
examples/datasets/plot_limo_data.py:28:67: W291 trailing whitespace
examples/datasets/plot_limo_data.py:248:80: E501 line too long (80 > 79 characters)
examples/datasets/plot_limo_data.py:335:80: E501 line too long (80 > 79 characters)

Should be easy to fix and merge, I think you should do it ASAP @JoseAlanis

[JoseAlanis]

oops, sorry, I thought my editor would automatically strip the trailing spaces on save. Thanks @jona-sassenhagen!

[JoseAlanis]

Hey guys, I'm sorry, I messed up my branch while trying to fix some merge conflicts. @larsoner @jona-sassenhagen, should I reset to my previous commit and force push? or what's the best solution here.

[larsoner]

I would:

1. get your branch back to the state it was in before
2. squash to a single commit -- for example if you had 5 commits you would do git rebase -i HEAD~5 and set all except the topmost commit to s/squash instead of p/pick
3. git fetch upstream
4. git rebase upstream/master
5. git mergetool
6. git rebase --continue

Then push force

[JoseAlanis]

thanks @larsoner, looks like it worked :)

[larsoner]

@JoseAlanis why is this marked WIP, is there more to do from your end? If you think it's ready for review/merge you can set the title to MRG, otherwise people will assume you're still looking at it and probably not review.

I've pushed a few small commits to fix small problems. @jona-sassenhagen can you take a look and let us know if you're happy?

[JoseAlanis]

alright, thanks @larsoner, no, I think we're good to go for now. I'll try to be more careful with these type of issues next time.

[jona-sassenhagen]

A few stylistic comments.

[larsoner]

@drammock can you review and merge if you're happy?

[drammock]

I'll make a PR into @JoseAlanis's branch with some edits to the flow of the prose in the example. Separate from that, there's this issue:

Do you want to set the path:
    /home/drmccloy/mne_data
as the default LIMO dataset path in the mne-python config [y]/n? y
<ipython-input-2-17d5b26ed105>:1: RuntimeWarning: Setting non-standard config type: "MNE_DATASETS_LIMO_PATH"

So you'll need to add MNE_DATASETS_LIMO_PATH as a valid config variable.

[drammock]

I've made a PR into your branch with some mild-to-moderate changes to the prose and the code. In addition to that, there are two larger issues (commented on here) that need to be addressed before this is ready to merge.

[JoseAlanis]

@drammock ready for review.

[agramfort]

@drammock ok for you?

[drammock]

OK, here are a bunch of suggested changes. Most are minor wording clarifications or code simplifications. Assuming CIs still come back green after incorporating these, I'm +1 for merge.

[JoseAlanis]

OK, here are a bunch of suggested changes. Most are minor wording clarifications or code simplifications. Assuming CIs still come back green after incorporating these, I'm +1 for merge.

thanks @drammock, I really appreaciate the comments and sugesstions.

[drammock]

here's the rendered example, looks good:
https://16376-1301584-gh.circle-artifacts.com/0/dev/auto_examples/datasets/plot_limo_data.html

[drammock]

thanks @JoseAlanis !

[jona-sassenhagen]

Thanks for extensive reviews @drammock

[JoseAlanis]

Thanks everybody!