Repository navigation
[Idea] Using Jupyterlite for interactive tutorials and workshops #13616
Description
Activity
this could be a good GSOC project as well. I would be happy to mentor if we went that route.
sphinx-gallery has some support for this, it's worth checking out at some point!
very neat! just stumbled upon this demo: https://github.com/jupyterlite/sphinx-demo
@teonbrooks I'd love to see a GSoC that brought interactive tutorials to MNE's website. We might even be able to get an additional mentor from one of the other Scientific Python projects... there's a lot of expertise there. Alternatively we could consider trying to tackle this at the next Scientific Python developer summit; they usually happen early summer. Would you be interested that? If so we can touch base off-list about dates, funding, etc.
@drammock yes, I would be interested, feel free to loop me in :)
Reacted by Daniel McCloyHi everyone! I am interested in this project for GSoC 2026 and am currently working on my proposal for it. I have been going through the
sphinx-demo linkand thejupyterlite-sphinx documentationto understand the implementation.
Would it be fine if I open a discussion for this on the forum? That way I can keep my questions and ideas in one place without cluttering this issue. Thank you!I think this issue is probably a better place than the forum. The forum is more for usage questions, and GitHub is more for doc/code issues, which JupyterLite fits into I think
Reacted by AniketI've gone through the docs mentioned, but I think starting with a small demo and seeing where I get stuck will be a better way to understand things rather than only going through docs. So i'll start with small setup to see how it works, As I'm exploring so I think I should keep in my own fork and if I run into any questions, I will reach out here, I'll move with
Pyodide (and pip), @larsoner please let me know if you have any pointers or things I should keep in mind before I start. Thanks!
Just done with demo setup using Pyodide kernel, didn't face much difficulty and it's working,
import mneworks andraw.plot()renders a EEG signal in the browser. I think now I can dive more and plan things for this development.I apologize if I should not share screenshots here, as some communities prefer not to, I just shared to show progress and get guidance.
Reacted by Daniel McCloy and Teon L BrooksWhile testing the MNE dependencies in the
JupyterLite/Pyodideenvironment, I tried importing the required packages and installing the missing ones.From what I understand, for packages that are not present by default, we can use these approaches:-
- micropip
- piplite
- pre-bundling packages
I would love to hear your thoughts on which approach we should prefer, or if there is another way to handle this. Thanks!
@Aniketsy, thanks for the exploratory work!
since mne-python is a pure Python package, it works seamlessly with Jupyterlite and you can use some jupyter magic command like
% pip install mneat the beginning of the notebook and it will install it so that when you import it, it will be available.do you have a PR of the work that you have been doing or would like to have one. I can help iterate on it with you if you prefer.
Reacted by Aniket@teonbrooks Thanks! currently i’m exploring things locally and have built a small demo and diving deeper into the components required for this project. I’m not sure if I’m allowed to open a PR for this yet, but if it’s okay, I’d be happy to open one and start iterating on it, so I can share my progress and ask for help if I get stuck.
I’ve also mostly completed a draft of my GSoC proposal. Would it be helpful to attach screenshots of the demo in the proposal, or is describing what I have explored so far sufficient? If you’re open to it, I would really appreciate if you could review the proposal draft and share any feedback for improvement.
ah yes, GSoC proposal. yes, feel free to share what you are thinking about for your proposal. i would be happy to share some feedback
@teonbrooks thank you! where would be the best place for me to share the proposal draft for feedback? Should I provide a link to the document, or should I submit it on the GSoC portal and then update it based on the feedback.
Hi @teonbrooks @larsoner @drammock,
I've been working on PR #13666 which adds optionalJupyterLitesupport to the documentation, happy to share what I've learned so far.
The main technical blocker I hit was aLiteBuildConfigdict serialization bug injupyterlite_sphinx:the library passes the parsed configdictdirectly to the CLI instead of serializing it back to a JSON string, raisingAssertionError:Expected all commands arguments to be a str. The workaround is removingjupyter_lite_config.jsonfrom conf.py entirely, which works but means theJupyterLitebuild runs with default configuration. I'm planning to upstream a fix tojupyterlite_sphinxor find the right hook to pass config safely.
For example selection,tutorials/simulation/10_array_objs.py(numpy+mneonly, no downloads) is the clearest starting point as @drammock suggested. Before I build out a full categorization of which examples can run inPyodide,I wanted to ask...is the goal to make every compatible example interactive, or to focus on a curated subset(e.g. getting started and simulation tutorials) and leave the rest for future work?
I'm applying for GSoC 2026 for this project...happy to share my draft proposal for feedback if that's helpfulI wanted to ask...is the goal to make every compatible example interactive, or to focus on a curated subset(e.g. getting started and simulation tutorials) and leave the rest for future work?
I don't think we want/need this on every page. Given that we require sample data for the vast majority of our tutorial docs, it will be annoying for users to have to re-download example data for every page that they want to explore interactively.
SciPy has "try it in your browser" buttons on some (but not all) docstring pages that have
Examplessections. (e.g., https://scipy.github.io/devdocs/reference/generated/scipy.interpolate.SmoothSphereBivariateSpline.__call__.html) NumPy is similar (https://numpy.org/doc/stable/reference/arrays.ndarray.html) and also has a big interactive embed on their homepage.MNE-Python doesn't have many
Examplessections in our docstrings, so something like a "try it in your browser" button for our tutorials/examples makes sense. SciPy has I think a global "on" switch with a list of pages to exclude (see https://scipy.github.io/devdocs/dev/core-dev/index.html#interactive-examples-in-docstrings), but I think we would probably want the opposite (a single allowlist of examples/tutorials to enable it for, at least at first).@larsoner @teonbrooks do you agree? Happy to be convinced otherwise!
Reacted by AniketMNE-Python doesn't have many
Examplessections in our docstrings, so something like a "try it in your browser" button for our tutorials/examples makes sense. SciPy has I think a global "on" switch with a list of pages to exclude (see https://scipy.github.io/devdocs/dev/core-dev/index.html#interactive-examples-in-docstrings), but I think we would probably want the opposite (a single allowlist of examples/tutorials to enable it for, at least at first).as a small suggestion, we can also have tag like(
# jupyter_lite: true), for those we want to have allowlist . As we're already adding tags on tutorials/examples.thanks @drammock
an allowlist approach is cleaner to start with and avoids the re-download friction for data-heavy tutorials.
For the allowlist mechanism, I was thinking of using sphinx-gallery's existingfirst_notebook_cellor a customconf.pykey rather than inline tags, since that keeps the example files themselves cleanhey, i'm currently traveling but will be able to follow up here on Thursday
Reacted by AniketHi I am Mohammad Abuzar. I am applying for GSoC 2026. My proposal is about improving documentation interactivity. It is project number 4.
I read through this conversation. I think the plan is to use sphinx-gallerys JupyterLite support. This way we can add launch buttons to existing example pages. These pages will run fully in the browser.
I have a problem, with the sample dataset. It is very large 1.5 GB. In my proposal I will talk about this issue. My idea is to create a small demo dataset. I will include it in the JupyterLite build. This way examples can run without downloading files. I would like to know if this is an approach or if there is a better way.
I am also looking into Xeus-Python. It can be used if MNEs C extensions do not work with Pyodides WASM environment.
I am happy to discuss this. I will post a link to my draft proposal when it is ready.
sorry, I was away longer than expected due to family reasons. I hope everyone was able to submit their proposals. thanks for your interest in MNE-Python and improving the tutorial experience. we will be reviewing the applications through GSoC.
Reacted by Aniket@teonbrooks happy to see you back, and hoping everything is fine .
I hope everyone was able to submit their proposals. thanks for your interest in MNE-Python and improving the tutorial experience.
yes, please let me know if there are any pointers from your side. i'd love to explore in demo, to get familiar with blockers , which can be faced during implementation . Thank you! 😊
Creating this issue to get my thoughts out on paper. Something I have been thinking about for a while that would go along with the Education objective of the MNE Roadmap.
A long wild back I added support for MNE to Pyodide. It has since added pip support for all pure Python packages so it's now up-to-date with the latest released version with no updates needed.
Jupyterlite has greatly matured as a project and is at a point where we could consider adopting for interactive tutorials. Jupyterlite takes the Jupyterlab ecosystem and wires it up with either Pyodide (and pip) or Xeus-Python (and conda+pip)
I think a bit of work would be needed to ensure the sample dataset could be added to the workspace.
We could use this setup for workshops to get up and going quickly.
Some few examples of Jupyterlite:
cc: @larsoner