Jupyter Notebooks ================= While dashboard apps are perfect for setting up *ilumr* and running routine experiments, Jupyter Notebooks provide more flexibility and control over *ilumr*. These Notebooks provide a combination of rich text elements, executable Python code, and inline plot displays. This makes them perfect for creating multi-step experiments, running interactive lab scripts, and developing pulse sequences. .. Add a picture showing the text, code and plot elements For more information on Jupyter Notebooks, the official documentation can be found `here `_. .. We publish three main types of Jupyter Notebooks for the *ilumr* system. .. The following section is confusing and needs to be rewritten .. Things to include: list of example notebooks. compare 1D rare notebook to dashboard, link to the resources GitHub where new notebooks get uploaded .. Update pyhton version number below Programming in Python --------------------- *ilumr* is fully programmable using Python 3, which can be run in a Python Notebook. .. You can create a new Python notebook by Pulse sequences are constructed and experiments are run using our *matipo* Python library (see the *matipo* :ref:`matipo/usage:Usage` section). Other third party python libraries can be used for data processing, plotting, interactive widgets and more. Some useful libraries, which come preinstalled, are: * numpy: https://numpy.org/doc/stable/ * Perform calculations on arrays of data efficiently. Also includes many useful algorithms, e.g. FFT and matrix manipulation. * scipy: https://docs.scipy.org/doc/scipy/ * An extensive library of scientific data processing methods. * matplotlib: https://matplotlib.org/stable/users/index * Easy to use plotting library with an API that will be familiar to MATLAB users. * bokeh: https://docs.bokeh.org/en/latest/ * Create Beautiful interactive visualizations. * panel: https://panel.holoviz.org/ * Build dashboards for experiments with a library of widgets. * ipyvolume: https://ipyvolume.readthedocs.io/en/latest/ * Simple 3D volume data visualization. Example Notebooks ----------------- The best way to familiarise yourself with *ilumr's* Jupyter Notebooks is to work your way through some example Notebooks. On your *ilumr*, you can find example Notebooks in the **user/notebooks/example notebooks** directory. You can also download example Notebooks from our `ilumr Resources GitHub Repository `_ and our `ilumr Courseware GitHub Repository `_. Our courseware is a great example of how you can use these Notebooks to combine diagrams, text, and graphical user interfaces into a single Jupyter Notebook. Running a Jupyter Notebook -------------------------- Notebooks have the .ipynb extension and can be opened by double clicking in the file browser. To run a single cell: Click the play button (1.) at the top of the Notebook or click a code cell and use the **shift+enter** shortcut. Once a cell has been executed, the next cell will be automatically selected. The blue bar (2.) shows the currently selected cell. Pressing the play button repeatedly will execute the cells in order. To run all cells: Click **Run > Run All Cells** (3.) in the top left menu bar. Sometimes code blocks are hidden from view (4.). You can expand these code blocks by clicking the three dots. .. figure:: /images/running_notebook.png :width: 100% :alt: numbered sections of a jupyter notebook Jupyter Notebook .. note:: Having many Notebooks open at once can use a lot of system memory and slow it down, if you notice issues you can use the running sidebar as shown below to shutdown the running kernels of unused Notebooks and free up system resources. Programmatic vs Graphical User Interface (GUI) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ While working through the example Notebooks, you will notice that there are two main ways to run magnetic resonance experiments in the Notebooks: programmatically or through GUIs. To Run a Programmatic Experiment: * Input and edit parameters within the code blocks. * Execute each cell in order to run the experiment. The pulse sequence begins when the code block including "data = await seq.run()" is executed. * Print statements are used to show the experiments progress. * Execute data processing and plotting cells to display plots. * Enter file name then execute code block that includes "np.save(f'{SAVE_DIR}/{SAVE_NAME}', y)" and "seq.savepar(f'{SAVE_DIR}/{SAVE_NAME}.yaml')" to save data. To Run a GUI based Experiment: * Execute code blocks to load the GUI. * Set parameters using user input boxes. * Press green **Run** button to begin experiment. * The experiment progress is shown using a progress bar. * Plots are generated automatically in the GUI. * Enter a file name and press the blue **Save** button to save data. Creating a Notebook ------------------- To create a new Notebook: 1. Click the **+** button in the file browser to open the Launcher tab. 2. Click the **Python 3** button under the **Notebook** heading. .. figure:: /images/new_notebook.png :width: 100% :alt: new notebook button Create New Notebook To copy a Notebook: * Select an existing notebook and **right-click-> duplicate** or **right-click->copy** and **right-click->paste**. * Rename the copy. * Open Notebook for editing. Creating Experiments ^^^^^^^^^^^^^^^^^^^^ Each method for creating and running experiments has its advantages. When developing novel experiments and pulse sequences, it is often more convenient to implement the experiment programmatically. Once you have fully developed the experiment and selected your key plots types, you can then package the experiment into a GUI. A combination of programmatic experiments and GUI based experiments can be created in a single Notebook. Programmatic Experiments """""""""""""""""""""""" The *matipo* library allows you to run programmatic MRI experiments in a Jupyter Notebook. You can view the API reference for this library here: :ref:`matipo/usage:Running A Pulse Sequence` Experiment data can then be processed using `numpy `_ and plotted using `matplotlib `_. .. figure:: /images/nb_exp.gif :width: 100% :alt: python code in a programmatic notebook Programmatic Notebook Experiment GUI Experiments """"""""""""""" The *ilumr* experiment library allows you to create your own custom dashboard-style graphical user interfaces (GUIs) in Jupyter notebooks. This experiment library handles pulse sequence execution, data plotting, input widgets, plot layout, and state preservation. You can view the API reference for this library here: :ref:`matipo/api:Experiment Building Tools` .. figure:: /images/nb_gui.gif :width: 100% :alt: graphical interface experiment notebook GUI Notebook Experiment The `ilumr-courseware repository `_ is a great place to see more examples of how the experiment library can be used to create different GUIs for MRI experiments. Creating Text ^^^^^^^^^^^^^ The text sections of the Notebook are great for writing educational content, creating lab tasks, noting down your MRI experiment setup, and documenting your code. To add a text cell, press the small **+** symbol (1) on the Notebook's top panel and then select **Markdown** in the drop down menu (2). .. figure:: /images/markdown.png :width: 100% :alt: markdown option on drop down menu for notebook cell type Adding Markdown Cells You can use Markdown syntax and HTML styling to add text and images to the cell. Then, run the cell (**shift+enter**) to produce the formatted text output. If you're new to markdown and HTML, the following online guides may be useful: `Markdown Cheat Sheet `_ and `Structuring Content with HTML `_ Below is an example of combining markdown syntax and HTML styling. **Example Code**::
Figure 4: Resonant Circuit
In order to efficiently generate the $\vec B_1$ field and pickup the signal from the net magnetization $\vec M$, the coil is combined with a capacitor to form a resonant circuit shown in the figure on the right. The resonant frequency of an LC circuit is:: $$f = \frac{1}{2\pi\sqrt{LC}} \tag{2}$$ **Output:** .. figure:: /images/text.png :width: 100% :alt: combination of text, equations, and a diagram Rich Text Output