EMAN2 and JupyterLab

This page describes how to use EMAN2 interactive display widgets (2-D images, 3-D volumes, plots, etc.) from within a JupyterLab session. This (the features and the documentation) are a work in progress as of early 2022, targeted for release in EMAN3. To use these features you should compile EMAN2 from source using master on Github or use a recent binary snapshot version.

While we have not managed to create full EMAN2 display widgets within Jupyter, which would be a monumental task, we have created a system where Jupyter can communicate with the EMAN2 environment on the system to do the actual rendering of a wide range of data types. We will strive towards better integration as time goes on, but the current interface is quite usable and convenient even if it isn't everything it could be yet.

The first time you use this system, you MAY need to do the following. This may not be necessary, and only needs to be done once after an EMAN2 installation:

# activate your EMAN2 environment
conda install ipywidgets
jupyter nbextension enable --py widgetsnbextension

To get things started up:

1. Run e2display.py --server &

   • This will open a single window initially.
   • You must leave this running in the background any time you wish to use EMAN2 widgets in Jupyter.
   • A single running instance is sufficient for any number of Jupyter sessions.

2. Run e2.py or e3.py to launch a JupyterLab session

3. If it didn't open the browser automatically, display the JupyterLab session in your browser

4. Create a Python3 Notebook

5. from EMAN2 import * within the notebook

That's it, you are ready to start using EMAN2 widgets from Jupyter. All of the functionality is implemented using:

e3display(data, vtype='auto', vname=None, dname='Unknown')
where:
    data - data object of any (appropriate) type, if None will simply update the widget and return a PNG, 
    vtype - "image","imagemx","volume","plot2d","plot3d","histogram"
    vname - name of a new or existing (type specific) display widget to use, if None 'default' will be used 
    dname - name for the data set, may be used as window title, or to support multiple object display in the same widget

Try this:

img=test_image()
vol=test_image_3d()

Then in separate cells:

e3display(test,"image","Image1")
e3display(vol,"volume","Vol1","test1")

After running all 3 cells, you should see two images in your notebook. The first should contain the standard EMAN2 S shaped test image. The second should include a volume showing 3-D axes in the center. If you switch to the window that opened when you ran e2display.py earlier, you will see 2 entries in the window now, and two additional windows will be open corresponding to the two images in Jupyter. You may interact with these windows in normal EMAN2 fashion (middle-click for control panel, etc), and they will update in real-time whenever the Jupyter session calls e3display.

Note: if you alter the display interactively, by, for example, rotating the 3-D volume, this change will not be immediately made in Jupyter. You will need to re-run the e3display cell to get an updated display. It is possible to display the contents of any current widget without passing data as well, eg-

e3display(None,"volume","Vol1")

will display whatever is currently showing in the widget.

Widgets like volume displays and 2D/3D plots, which can display multiple data sets, can have each data set updated on the fly. The 4th parameter to e3display is the name of a data set. For multi-data windows, simply use a different name for each data set to be displayed. If you use the same name, the corresponding data will be overwritten.

If you need assistance with any of these capabilities, please email sludtke@bcm.edu.