Mne-python: Link to workshop/tutorial/other tutorial notebooks?

[jona-sassenhagen]

For my workshops, I use a set of notebooks which are fairly self consistent and documented:

https://github.com/jona-sassenhagen/mne_workshop_amsterdam

I am sure others have their own, too. Maybe we should link to a set of tutorial notebooks from the website?

[agramfort]

I fear these get out of date quickly unless part of the main doc using CI
checks.

If some stuff on not part of the main doc I would see what can be added.

[larsoner]

We could a new root level "workshop" directory (rendered on CI by SG) that contains py files that, when downloaded as ipynb files converted by SG, are what we follow when running workshops.

[agramfort]

this is what we did in sklearn :
http://scikit-learn.org/stable/tutorial/index.html

it started from a workshop / tutorial.

I am however not sure about the overhead / doc duplication it will generate.

[larsoner]

I am however not sure about the overhead / doc duplication it will generate.

I don't see this as too much of a problem. Hopefully our core APIs will not change too much so code dup won't be too much of a maintenance burden. I see the divide as:

1. workshop: if I want to start from scratch and follow a progression, follow these.
2. tutorials: if I want to do something specific, this is a good place to look for explanations and narratives.
3. examples: if I want to do something specific, this is a good place for advanced use case examples.

To make this clear to users, already doc/documentation.rst (where users should go for all understanding) unites (2) and (3) under topic-based headings. We can make it advertise (1) at the top with:

.. note:: Are you starting from scratch with MNE? We provide a scripted set of
          step-by-step workshop-style tutorials, see `auto_tutorials/index.html`.

@choldgraf you think about these things frequently, WDYT?

[dengemann]

I would not bother too much about syncing in specific workshop materials
here. If I would do that it would flood everything. Second, nowadays the
website as it is is the main resource for teaching. However we can still
improve our tutorials.
On Tue 7 Aug 2018 at 23:41, Eric Larson [e-mail] wrote:

I am however not sure about the overhead / doc duplication it will
generate.

I don't see this as too much of a problem. Hopefully our core APIs will
not change too much so code dup won't be too much of a maintenance burden.
I see the divide as:

1. workshop: if I want to start from scratch and follow a progression,
   follow these.
2. tutorials: if I want to do something specific, this is a good place
   to look for explanations and narratives.
3. examples: if I want to do something specific, this is a good place
   for advanced use case examples.

To make this clear to users, already doc/documentation.rst (where users
should go for all understanding) unites (2) and (3) under topic-based
headings. We can make it advertise (1) at the top with:

.. note:: Are you starting from scratch with MNE? We provide a scripted set of
step-by-step workshop-style tutorials, see auto_tutorials/index.html.

@choldgraf https://github.com/choldgraf you think about these things
frequently, WDYT?

—
You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub
https://github.com/mne-tools/mne-python/issues/5406#issuecomment-411212039,
or mute the thread
https://github.com/notifications/unsubscribe-auth/AB0fiulv-3XOZ6f6LAJX5Hhu21baCQWRks5uOgmBgaJpZM4VvV8X
.

[larsoner]

I would not bother too much about syncing in specific workshop materials
here. If I would do that it would flood everything.

You mean having multiple sets? I agree we should not. I think we should have one set.

[jona-sassenhagen]

My suggestion would be to be low-effort and just have a link section where people can put links to GitHub pages. It could be version tagged too, so 0.17 only links to 0.17-compatible tutorials.

[larsoner]

My suggestion would be to be low-effort and just have a link section where people can put links to GitHub pages.

Why is this less effort than what I propose? If it's because we don't have to maintain the tutorials, then that's a downside IMO because it means they will become out of date. When we release 0.18, the 0.17 are out of date and not that useful anymore, and people will bother us to update to 0.18 anyway, etc.

If there is a set of tutorials everyone tends to use for workshops, updating as necessary, I don't know why we wouldn't 1) continuously keep them up to date, and 2) expose them to users in case they want to follow their own step-by-step progression.

[jona-sassenhagen]

I'm not sure I'll use the same workshop slides Alex does. I'm not doing MEG workshops, I'm not talking about source localisation. Keeping stuff decentralised and up to each individual, and just giving links to individual materials, means the effort on part of the MNE team itself qua MNE team is rather low.
It's comparatively more effort for the individuals offering the tutorials though.

If the new release doesn't even have any links to tutorials, I think people can't really complain they're not updated :)

[larsoner]

Okay if they really are tailored to each workshop for the most part then maybe there isn't much point in trying to integrate them continuously. I'm fine with adding a page to the doc with links to these materials like you suggest -- we just need to make it clear which version they work with (as you suggest) and what they cover so people can decide which they'd like to follow, if any.

[choldgraf]

My 2 cents on this is that having the right content there is much more important than the particular structure of the content. So I'd first ask "do we have all of the content in the "tutorials" section that would be needed to quickly put together a day-long intro to MNE-Python? If no, then we should focus on filling in the missing gaps there, and not worry about whether it's under a new section or not.

As a separate issue, we could discuss whether to define specific "workshop" materials for this (e.g. with practice notebooks or something). In my mind, this would ideally be largely a curated list of links to tutorials that users are expected to follow linearly, to avoid the need to curate a new set of material.

So my question is: do we have enough content in "tutorials" to cover an intro-level workshop?

[agramfort]

fully agree with @choldgraf

maybe an option is to create an mne-workshops github org and put all the repos there...

[larsoner]

Sounds like a repo with all workshop materials is the way to go. @jona-sassenhagen if I create the repo could you 1) add yours as a starting point and 2) update the mne-python docs to link to it somewhere (probably from documentation.rst)?

[jona-sassenhagen]

Sure. For the release?

[larsoner]

Yes, so in the next couple of weeks

[massich]

just some questions:

1. whats the difference between examples and tutorials?
2. if we have a tutorials section shouldn't we have a direct link in the website bar?
   

[massich]

maybe tutorials should only be some narrative linking examples.

[larsoner]

Tutorials generally have more narrative and explanation of core concepts, examples generally are more script demos to show how to do something more advanced

[larsoner]

Not a blocker, moving to 0.18

[drammock]

hey all, I'm working with @larsoner and Samu to improve and expand on the mne-python tutorials. Eric suggested I start by collecting everyone's past workshop materials so I'm not duplicating past effort. I can see from above thread that it's a bit contentious whether people's workshop materials should be part of the main mne documentation or not... So right now all I'm asking is that people share with me (a link to) their workshop materials, either here or by email, so I can build on others' work rather than reinventing the wheel. The thread started with @jona-sassenhagen's link to his amsterdam workshop materials, can others provide theirs please? cc @jasmainak @christianbrodbeck @kingjr @teonbrooks (anyone else I should CC?)

[dengemann]

hey all, I'm working with @larsoner and Samu to improve and expand on the mne-python tutorials. Eric suggested I start by collecting everyone's past workshop materials so I'm not duplicating past effort. I can see from above thread that it's a bit contentious whether people's workshop materials should be part of the main mne documentation or not...

I stopped a good while ago to make explicit workshop notebooks. Enriching the main documentation with tutorials was also motivated by making it easier to do workshops.

Checkout several branches here:
https://github.com/dengemann/mne-python-notebooks

Warning -- they are outdated. As I said I stopped a while ago to make separate notebooks.

[dengemann]

@drammock also please keep me in the loop. I give workshops frequently and I think updating + adding tutorials would be really important. Perhaps we can work together on this.

[drammock]

@dengemann thanks, I will keep you apprised of our plans / progress.

[dengemann]

@dengemann thanks, I will keep you apprised of our plans / progress.

It would be specifically good to interact right after workshops and discuss based on fresh impressions what is important. I often see a lot but then don't have time to share my impressions or contribute to the tutorials.

[dengemann]

@drammock btw. our next workshop will be in Frankfurt in 10 days with @jona-sassenhagen. Perhaps we can take this as an occasion pull off some good activity.

[drammock]

Maybe after Frankfurt @dengemann and @jona-sassenhagen you can share with me your impressions of what was not very smooth, what was missing, etc. and I'll add those improvements to the queue.

[agramfort]

here is one https://www.dropbox.com/s/esyfs1x8s5zt44b/MNE_brussels_2017.zip?dl=0
from my tuto in brussels in 2017

[larsoner]

I now have a decent collection of notebooks:

• 2016_05_Halifax
• 2017_03_Brussels
• 2018_06_Amsterdam
• 2019_04_Birmingham
• 2019_04_Brown
• 2019_05_NIH (WIP)

I could create a mne-workshops repo and put the ipynb files in there so that people have a place to go to find these files. @dengemann @jona-sassenhagen @drammock @agramfort sound good?

[jona-sassenhagen]

Fine with me.

[agramfort]

fine with me too

>

[dengemann]

ok

On 29 May 2019, at 13:31, Alexandre Gramfort [e-mail] wrote:

fine with me too

>
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub, or mute the thread.

[jasmainak]

+1 and I would add a small Travis checker :)

[larsoner]

Done:

https://github.com/mne-tools/mne-workshops

Let's try to remember to add to this when workshops end!