FIX/DOC: Documentation

[dengemann]

Dear all. I feel over the next release cycle we should chose improving our documentation as a main goal. I know most of us including myself find it more rewarding to add new code. But we must bite that bullet, I feel. If we distribute efforts a bit and get well organized it might be less of a pain.
And importantly, as a project, we'll be making more progress if newcomers find it easy to get started.

This includes at least the following points:

• make more explicit that small examples are actually API examples and shall not be taken too literally (e.g. prevent users from adding random noise-arrays to threir data when doing using spatio-temporal clustering, etc.) WIP, DOC: new doc landing page; clean up doc structure #6694 adds a warning to the top of the examples gallery
• disseminate slide shows, screen casts
• send a user poll to the mailing list
• reorganize examples (e.g. order by intent and processing-step) Reorg examples #2101
• add real tutorials with stronger commitment to the wording / the recommendations [MRG] Added build time to web page footer. Covariance tutorial. #3101
• merge MNE manual with MNE-Python docs

Help users with pitfalls:

• Starting with Python (DOC: Getting started with Python #3265): WIP, DOC: new doc landing page; clean up doc structure #6694 adds an updated "getting started with python" page.
• the use of Montage
• working with a template brain this exists now
• n_jobs=1 to save memory
• freesurfer + source space API, vertex indices, vertex numbers (Transform docs and API #3465)
• morphing and missing vertices (Problem when calculating stc grand average #4034)
• basic Python issues (e.g., paths save video from mne.morph_data #2052)
• +/- in Evoked
• integrate IPython notebooks?
• coversion between float32 and float64 data on read/write (Question: Datatypes and semantics for preload in _BaseRaw #2720)

"Migrating to / working with" section:

• Xfit / Xplotter (@Eric89GXL)
• FieldTrip (Tutorial for migrating from Fieldtrip #3362)
• EEGLAB (@jona-sassenhagen?): explaining the distinction in channel types etc.

Bug reports (from @dengemann):

Set up list of things to check + rule out before filing a bug report, inspired by https://github.com/mxcl/homebrew/wiki/Troubleshooting

Extended tutorials:

• epochs selection and event handling (see MNE events functionality #1963)
• artefact removal These have been expanded / overhauled by @drammock
• group statistics (make explicit 2 (spatial / no spatial prior) X 2 (F/T-test) API, clarify TFCE (it's not another test, but an enhancement method)), clarify that despite t-test inputs, spatio-temporal permutation clustering is not parametric and alos it does not give a multiple comparison corrected t-map, which means it's not just a thresholding to a parametric stat. Also add recent insights on decoding stats. Discuss repeated measure designs and options (hierarchial subtraction with t-test, rANOVA, etc.)
• coreg (ENH: Tutorial on coreg #3358)

Manual:

• time-frequency module: tfr functions vs. psd functions
• saving objects to disk (we discuss reading but not saving/writing ...) many tutorials now include this
• transformations (Transform docs and API #3465)
• decoding section explaining how the API follows the sklearn convention. Subsections for spatial pattern methods & time gen + time decoding

For devs:

• cookbook like this with common idioms, one liners

cc @teonlamont @christianbrodbeck @mainakjas @rgoj @dgwakeman @adykstra @legitta @deep-introspection @olaf @mshamalainen @mluessi @Eric89GXL @agramfort ... and and and ...

[agramfort]

+1e6 ...

The thing is that only users with experience can do this... A small bite of bullet for everyone I guess ....

[dengemann]

The thing is that only users with experience can do this...

you mean using MNE-Python? ;-)

[dengemann]

Kidding, I totally agree. I suggest we have a hangout september with as many people as possisble. Besides all the manual work we need to do some conceptual work as well.

[dengemann]

One minor remark. We should abandon the --pylab pattern in our examples and the contributing / getting started pages. It's not very pythonic to pollute namespaces and I think it's more confusing for newcomers than it actually helps.

Maybe I'll open a separate issue at some point.

[agramfort]

sounds fair to me.

[christianbrodbeck]

One thing that I think would be particularly appreciated by many would be a more detailed explanation of the parameters that have to be selected to construct an inverse solution...

[agramfort]

indeed. Volunteer?

[christianbrodbeck]

@agramfort I will volunteer to write it up if I get the info from people :) I guess I could start a draft/scaffold in a PR? How should it fit in the current docs, are we rearranging the general structure? Could we split the reference section into a API reference and a theoretical reference?

[deep-introspection]

I would be much happy to help but I am still not really knowledgeable about MNE Python.
As a very naive user, I can still help to see if the doc is clear.

Last coding sprint in Paris, I took notes with @dengemann. This can maybe do a 10min "walk in" MNE Python guide.

[christianbrodbeck]

ping, I would like to start that scaffold and start collecting information, how should I add it? A new Section called "Manual" between "Examples" and "Reference", and in it subsections like "Creating the Inverse Solution"?

[agramfort]

I think we should progressively merge the old manual and the new examples adding links from manual to specific examples as done in sklearn. We should do it chapter by chapter. For example there is a section on MNE estimates that covers inverse modeling.

[christianbrodbeck]

The manual currently seems pretty theoretical (i.e. the equations for how things work). What I think would be very useful in addition to that is some sort of recommendations for best practices. What I meant above is slightly different: In our lab meetings regularly questions come up like “What does the SNR component in Lambda squared do, and how should I specify it?” and “What does regularization of the covariance matrix do, and should I do out?”. Nobody here understands the theory behind MNE well enough to answer those questions, and I think a manual section with questions like these would be extremely helpful. So @agramfort

• would you want to “fold” questions like these into the theoretical manual rather than have a separate “practical” section?
• the old manual basically also folds in an MNE-C command reference. would you want to fold Python into this as well? Wouldn’t it get kind of crowded?
• or should each section be expanded to something with subsections like “theory” “practice” “implementation in MNE-C” “Implementation in Python”?

On Sep 26, 2014, at 16:20, Alexandre Gramfort [email protected] wrote:

I think we should progressively merge the old manual and the new examples adding links from manual to specific examples as done in sklearn. We should do it chapter by chapter. For example there is a section on MNE estimates that covers inverse modeling.

—
Reply to this email directly or view it on GitHub.

[agramfort]

The manual currently seems pretty theoretical (i.e. the equations for how things work). What I think would be very useful in addition to that is some sort of recommendations for best practices. What I meant above is slightly different: In our lab meetings regularly questions come up like “What does the SNR component in Lambda squared do, and how should I specify it?” and “What does regularization of the covariance matrix do, and should I do out?”. Nobody here understands the theory behind MNE well enough to answer those questions, and I think a manual section with questions like these would be extremely helpful. So @agramfort

everything is possible. For what you describe first maybe a FAQ page
could do the job.

• would you want to “fold” questions like these into the theoretical manual rather than have a separate “practical” section?

if it's recurrent questions then a FAQ entry page would be nice. It
could point to more advanced doc.

• the old manual basically also folds in an MNE-C command reference. would you want to fold Python into this as well? Wouldn’t it get kind of crowded?

I think we should stop separating the docs between MNE-C and Python.
It means reorganization the C documentation. Eventually more some
parts in the small fonts or advanced pages to keep it short to average
user.

• or should each section be expanded to something with subsections like “theory” “practice” “implementation in MNE-C” “Implementation in Python”?

yes but without separation.

[larsoner]

Moving this to 0.10 unless @agramfort can convince someone to dedicate the hours

[dengemann]

@Eric89GXL let's keep this for rainy summer days in Seattle or so.

[larsoner]

@jona-sassenhagen I actually edited the post to tag you. The idea I had in mind was to include whatever you think would be useful to help EEGLAB users transition to or work with mne-python. A table could work, or just a few paragraphs about major things to think about (object oriented vs not, channel types vs all EEG, etc.). More work on a complete pipeline also sounds cool as a complementary bit in another section.

[jona-sassenhagen]

Yup, I've already written up a lot of this.

[jasmainak]

@jona-sassenhagen : don't hesitate to make a PR early

[larsoner]

FYI I am thinking of revamping the installation page to look more like this:

http://nilearn.github.io/introduction.html#installing-nilearn

[agramfort]

yeah !

[kingjr]

I'm getting a bit confused where I should find info between the manual, examples, tutorials & faq. How about we restrict the FAQ to non-scientific questions (i.e. not covariance, or inverse modeling), and focus on classic setup, i/o, memory, speed & bugs issues?

[choldgraf]

Hey all - just FYI we decided to host a "docathon" at BIDS this coming January. It'll be a weeklong (ish) event that is hackathon-style, but focused on improving documentation and tools for documentation. We'll have folks meeting at Berkeley, but we'll hopefully have a good remote contingent as well (at the very least there are folks at the data science centers of UW and NYU interested).

Just putting this here in case we can come up with a todo list for that event and get some interest from the MNE community.

https://github.com/BIDS/docathon

[larsoner]

Let me / us know when you have some dates and times finalized and I'll try to block off some time to work remotely

[choldgraf]

Cool - it'll be roughly January 27th, planned to last about a week. We'll probably have one joint meeting at the start to assign projects / get people up to speed (maybe have some tutorials and demos, etc), and then some short checkups throughout (or at the end of) the week. So plenty of time for independent working...

[agramfort]

@dengemann please update this issue and eventually close it

[larsoner]

Closing for #6794