Scientific computing with Python
Course material presented at ISMRM 2021 Sunrise Educational Session for Python Programming & Scientific Computing.
📚 3 Notebooks for 3 dimensions of MRI
- 1D-MUSIC.ipynb for basic NumPy operations and SciPy functions to create harmonious MRI melodies.
- 2D-BIDS.ipynb for querying reconstructed images using BIDS layout, loading them using
nibabel,parsing themusingNumPyand creating interactive plots usingPlotly.
- 3D-ISMRMRD.ipynb for reading ISMRM-RD k-space data (16 channels) using
ismrmrd-python, reconstructing them usingSciPyand creating interactive plots usingPlotly.
🕸 You can execute the notebooks online
📥 Instructions for running notebooks on your computer
1. Clone this repository
git clone https://github.com/agahkarakuzu/sunrise.git
2. Choose one of the following options
💻 Local Python environment
Python
If you don't have Python installed on your computer, I highly recommend Anaconda. Simply follow the instructions on the website to install Anaconda, which comes with Jupyter out of the box.
Then all you have to do is simply installing Python dependencies using pip. In a terminal window:
cd /directory/to/sunrise/on/your/computer
pip install -r requirements.txtThat's all! After installing dependencies, run jupyter notebook or jupyter lab command in the terminal (while you are still at the /sunrise directory. Select a notebook, and start making some music using MRI sounds!
Potentially missing dependencies
- If you cannot run Librosa on a Ubuntu OS, you may be missing
libsndfile1package:
sudo apt install libsndfile1
-
Lolviz package (visualizing arrays using a graphical representation) is optional. You can follow the official docs to install its dependencies on different OS.
-
I did not test this on a Windows machine, please open an issue if you run into problems.
🐳 Use with Docker
If you have Docker installed on your computer and running, you can run the code in the same environment described in this repository.
Option-1: Use repo2docker
- Simply install
repo2dockerfrom pyPI:
pip install jupyter-repo2docker
- Run the following command in your terminal:
jupyter-repo2docker https://github.com/agahkarakuzu/sunrise
After building (it might take a while!), it should output in your terminal something like:
Copy/paste this URL into your browser when you connect for the first time,
to login with a token:
http://0.0.0.0:36511/?token=f94f8fabb92e22f5bfab116c382b4707fc2cade56ad1ace0
This should start a Jupyter session on your browser and make all the resources you see when you launch a Binder for this repository.
To re-use your container built by repo2docker, do the following:
- Run
docker imagescommand and copy theIMAGE IDto your clipboard - Run the following command to start the container:
docker run -it --rm -p 8888:8888 `PASTE IMAGE ID HERE` jupyter notebook --ip 0.0.0.0
Option 2: Use Docker image built by this repo's GitHub Actions
This repository builds and pushes its own Docker images on every release!
You can see the available versions here. I will give the instructions for the latest version:
- Pull the docker image
docker pull agahkarakuzu/sunrise:latest
- Start the container
docker run -it --rm -p 8888:8888 agahkarakuzu/sunrise:latest
Special thanks
My friend Bengü Aktas recorded vocals for this project. She's a singer and a visual artist who can also modify Si wafer surfaces to create bio-compatible micro-environments. Thank you Bengü!
Equipment
- Scanner: 3T Siemens Skyra with RTHawk
- Microphone: Audio Technica AT2020usb+
- Acoustic guitar: Taylor 114ce
How to run NORAH JONES pulse sequence on your scanner?
The pulse sequence is publicly available. If you have RTHawk real-time imaging platform, you can run it on a Siemens or GE scanner.
The pulse sequence is a simple SPGR with 4 varying TRs played in succession. The sequence can export ISMRM-RD and BIDS compatible raw and reconstructed images.
Visit qMRPullseq for other pulse sequences made available for quantitative MRI.
What makes this Python course special?
There are hundreds of free Python courses online to learn about NumPy and SciPy. You may ask, why create another one?
- This one is artfully tailored for MRI scientists. I always wanted to make some music with MRI sounds. I took this opportunity to do it in Python and share it with you.
- All the notebooks are given in the context of a typical image processing workflow, with an analogy to cooking:
- Shopping The ingredients we need to work with MRI data are sold in certain formats (DICOM, NIfTI, BIDS, ISMRM-RD etc.) in the marketplace. Without knowing the basics about these ingredients, we can't cook.
- Mise en place Depending on our research question or application, we often need to dice and slice our data in different ways.
NumPyis the brand of our chef's knife and all the utensils to put everything in place.
- SciPy culinary academy You can imagine
SciPy(or any other Python package) as a culinary academy of Michelin Star Chefs, who are willing to cook your meal for free, if you did the preparation.
- Share Everything tastes better when you share. IMHO, sharing our MRI processing recipe with others is a requirement rather than a choice.
- Shopping The ingredients we need to work with MRI data are sold in certain formats (DICOM, NIfTI, BIDS, ISMRM-RD etc.) in the marketplace. Without knowing the basics about these ingredients, we can't cook.
It is always good to know what you eat.
To that end, I equipped this repository with some tools to foster transparency & reproducibility.
Last, but not the least
Almost 1.5 years into the pandemic, I feel more and more like an analog guy in a digital world. I wanted to encourage creativity to take your mind off the stress of seeking an academic degree in a digital world, and to make MRI art while learning some Python.
If we are lucky to see digital-to-analog conversion happening next year, I would like to hear Python-generated MRI musics in the next MRM Highlights Party.
Please feel free to send a pull request to this repository by adding your MRI music in the REMIX folder. It does not matter if you used Python, C++, GarageBand, Logic Pro or even a synthesizer. All contributions are welcome!
Bonus
@mathieuboudreau created a fascinating Spotify playlist: unintentionally ISMRM. I hope that it serves as a source of inspiration for you to create magnetic melodies that are "intentionally ISMRM".
References and useful resources
-
AllenDowney/ThinkDSP was a great source of inspiration, I highly recommend his SciPy 2015 talk.
-
The amazing Pianoputer project
-
Visual NumPy, Pictorial Numpy tutorial, the Visual Guide to NumPy
EarSketch: Make beats & Learn code
I found out about EarSketch while creating this repository. It allows you to:
- Learn coding through music
- Use our sounds or your own (means that you can use files in the
WavMRIfolder!) - Learn Python or JavaScript code
- Produce studio-quality music
All in a web browser. It is a great opportunity to improve your algorithmic thinking skills. You need to create an account and login to be able to upload your sound samples. You can export them to SoundCloud with one click. I gave it a try, it works!
Python projects for MRI scientists by NeuroPoly
Vector illustrations in this project are under Freepik Premium license ag_e843bcd6** (Unlimited use without attribution).