search

mne-tools / mne-python

MNE: Magnetoencephalography (MEG) and Electroencephalography (EEG) in Python
https://mne.tools
BSD 3-Clause "New" or "Revised" License
2.67k stars 1.31k forks source link

FIX/DOC: Documentation #1495

Closed dengemann closed 3 years ago

dengemann commented 10 years ago

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:

Help users with pitfalls:

"Migrating to / working with" section:

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:

Manual:

For devs:

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

agramfort commented 10 years ago

+1e6 ...

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

dengemann commented 10 years ago

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

you mean using MNE-Python? ;-)

dengemann commented 10 years ago

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 commented 10 years ago

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 commented 10 years ago

sounds fair to me.

christianbrodbeck commented 10 years ago

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 commented 10 years ago

indeed. Volunteer?

christianbrodbeck commented 10 years ago

@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 commented 10 years ago

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 commented 10 years ago

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 commented 10 years ago

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 commented 9 years ago

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

On Sep 26, 2014, at 16:20, Alexandre Gramfort notifications@github.com 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 commented 9 years ago

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 commented 9 years ago

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

dengemann commented 9 years ago

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

jasmainak commented 8 years ago

I had to look at the EEGLAB documentation while I was working on my PR https://github.com/mne-tools/mne-python/pull/2676. If I can have @agramfort 's blessing at some point, I could revamp the documentation a bit. I think it needs some love. More text, less code, more screenshots, and walking through everything step-by-step. I also see missing pages on the manual: http://martinos.org/mne/stable/manual/preprocessing/filter.html and http://martinos.org/mne/stable/manual/preprocessing/bads.html. If I was a user, I would see this as a bad sign and wouldn't use the software just seeing this.

larsoner commented 8 years ago

It would be great if you had time to work on it, there's quite a list at the top to work with. Feel free to add items.

agramfort commented 8 years ago

+1e4 !

jona-sassenhagen commented 8 years ago

@dengemann what format do you mean wrt. EEGLAB conversion? A wiki or something like that? iPython notebook, wiki style, ...?

One thing (different thing) I would like to see, and would be willing to write, is a more extended example of how to get from raw files to a simple full analysis, including group statistics, for the most simple thing EEG/ERP guys will think of: just two conditions, import, data cleaning, ERP plotting, stats. Preferably just an iPython notebook.

agramfort commented 8 years ago

what have now tutorials in mne using block execution of sphinx-gallery

see for example:

https://github.com/mne-tools/mne-python/blob/master/tutorials/plot_creating_data_structures.py

but it can be a notebook / blog post to start.

deep-introspection commented 8 years ago

+1 for the notebook format!

agramfort commented 8 years ago

FYI sphinx-gallery will offer a notebook download link even if the file you write is a plain py file in the version control system.

jona-sassenhagen commented 8 years ago

I'll write a sphinx example for group-level traditional ERP analysis okay?

For the caveats-when-migrating-from-EEGLAB thing, wiki format seems more appropriate ...

agramfort commented 8 years ago

I'll write a sphinx example for group-level traditional ERP analysis okay?

yes but what data do you plan to use? it must be available as a dataset.

For the caveats-when-migrating-from-EEGLAB thing, wiki format seems more appropriate ...

rst + github offers almost the same as a wiki. You can directly edit on github.

jasmainak commented 8 years ago

@jona-sassenhagen : what would be really cool is to have a table like this: http://mathesaurus.sourceforge.net/matlab-numpy.html with roughly equivalent functions (from EEGLAB and MNE-Python) in the same row along with cross-refs (to MNE-Python functions). It should be easy to do and would be super-useful for anyone migrating. Wdyt? +1 for a simple tutorial .. please don't make it too complicated.

jona-sassenhagen commented 8 years ago

I could share 3 or 5 or so downsampled files from my brain and language paper, which was a very simple experiment, and show how to basically reproduce the analysis up to the plots (too lazy to do the single-trial stats). I'll also think about an eeglab-to-mne table, although, while this a cool idea in principle, a lot of this is not about stuff with clearly equivalent functions due to the object oriented nature of mne vs eeglab's matlab style.  Won't come around to the files before xmas though. 

larsoner commented 8 years ago

@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 commented 8 years ago

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

jasmainak commented 8 years ago

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

larsoner commented 8 years ago

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

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

agramfort commented 8 years ago

yeah !

kingjr commented 8 years ago

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 commented 7 years ago

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 commented 7 years ago

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 commented 7 years ago

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 commented 7 years ago

@dengemann please update this issue and eventually close it

larsoner commented 3 years ago

Closing for #6794