pylottone 0.2.2__tar.gz

pylottone-0.2.2/.gitignore

@@ -0,0 +1,177 @@
+# Project specific
+output_recons/
+config.toml
+saved_figures/
+figures/
+configs/
+*.h5
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+# pixi environments
+.pixi
+*.egg-info
+
+# editor
+.vscode/
+.zed/

pylottone-0.2.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Magnetic Resonance Engineering Laboratory
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pylottone-0.2.2/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.5
+Name: pylottone
+Version: 0.2.2
+Summary: PylotToneMRI is a Python Toolbox with an emphasis on high-amplitude pilot tone applied to spiral MR imaging.
+Author-email: Bilal Tasdelen <tasdelen@usc.edu>
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: joblib>=1.3
+Requires-Dist: matplotlib>=3.10.5
+Requires-Dist: numba
+Requires-Dist: numpy>=2.3.2
+Requires-Dist: pyfftw>=0.15.0
+Requires-Dist: scikit-learn
+Requires-Dist: scipy
+Requires-Dist: sktime
+Provides-Extra: gpu
+Requires-Dist: cupy-cuda12x>=13.6.0; extra == 'gpu'
+Provides-Extra: mrd
+Requires-Dist: ismrmrd>=1.14.1; extra == 'mrd'
+Provides-Extra: segmentation
+Requires-Dist: mpl-image-segmenter>=0.2.1; extra == 'segmentation'
+Provides-Extra: ui
+Requires-Dist: ipywidgets>=8; extra == 'ui'
+Requires-Dist: pyside6>=6.9.1; extra == 'ui'
+Description-Content-Type: text/markdown
+
+# HAPTIC: High-amplitude Pilot Tone with Interference Cancellation
+PylotToneMRI is a Python Toolbox with an emphasis on high-amplitude pilot tone applied to spiral MR imaging.
+
+# Installation
+
+Create an isolated environment using your favorite software (`uv`, `venv`, `conda`, etc.). This project provides an `uv.lock` for the exact replication of the environment via `uv`. Example for `venv`:
+
+```bash
+python -m venv ${venv_name}
+source ${venv_name}/bin/activate
+```
+
+### For development:
+Clone this repository and navigate into it:
+```bash
+git clone https://github.com/usc-mrel/PylotToneMRI.git
+cd PylotToneMRI
+```
+
+Install via `pip` in dev mode:
+
+```bash
+pip install -e .
+```
+
+If you need ISMRMRD file I/O, waveform injection, or reconstruction tooling, install the MRD extra:
+
+```bash
+pip install -e '.[mrd]'
+```
+
+To enable GPU acceleration for EDITER, install the optional GPU extra:
+
+```bash
+pip install -e '.[gpu]'
+```
+## For usage as a library:
+
+It can be directly installed from `PyPI` via `pip`:
+```bash
+pip install pylottone
+```
+
+If you need ISMRMRD-backed workflows from the GitHub install, use:
+
+```bash
+pip install 'pylottone[mrd]'
+```
+
+If you want EDITER GPU support from the GitHub install, use:
+
+```bash
+pip install 'pylottone[gpu]'
+```
+
+**Note:** Toolbox is only tested for Python>=3.11 and Python<=3.12.
+
+### For ECG guided PT and fusion algorithm:
+
+ECG guided PT extraction (`examples/main_pilottone_extract_exercise.py`) requires `torch` library, which can be installed separately before running the script.
+
+# Usage
+
+Most inputs and outputs are in [ISMRMRD](https://ismrmrd.readthedocs.io/en/latest/) format. Base `pylottone` installs now leave ISMRMRD optional; install `pylottone[mrd]` for MRD file I/O, waveform editing, and reconstruction tooling. Some scripts do modify the input raw data, so in case something goes wrong, it is important to back-up original raw data. For a more detailed explanation of raw data, please refer to subsection [Directory Hierarchy for Raw Data](#directory-hierarchy-for-raw-data).
+
+Most scripts take the configuration file in `toml` format, for specifying input data and some important parameters. An example config file, `example_config.toml` can be used as the template.
+
+Example for supplying the config file: `python script_to_run.py -c config_file_path.toml`. If no input config is supplied, `config.toml` is used as the default path.
+
+Most scripts also accepts list of inputs to be processed as a list of filepaths using `-f` or `--filepaths` switch. If no filepath is provided, scripts will open a UI to select one or multiple files for processing.
+ 
+## Summary of important notebooks/scripts
+
+### Following are under `examples/` directory:
+
+`main_pilottone_extract.py`: This is the main script that loads the raw data, extracts pilot tone, and saves the extracted waveforms back into the same raw data as an MRD waveform. Later parts of this notebook assumes ECG is acquired in the raw data, so if it is not the case, one can also run the parts that extract pilot tone, without comparing to ECG. **Note:** This script provides a pipeline for a spiral acquisiton, as implemented here: [Real Time Spiral sequences in PyPulseq](https://github.com/usc-mrel/rtspiral_pypulseq). Can be used as a template for other type of acquisitions.
+
+`main_editer_correct.py`: This script will process the raw data using EDITER and saves the corrected raw data. 
+
+`run_all.py`: A convenience script that applies pilot tone extraction and EDITER processing on the supplied raw data, and send the results to reconstruction server.
+
+`main_process_reference.py`: Can be used to process raw data with no PT.
+
+### Following are under `tools/` directory:
+
+`respiratory_from_image.py`: From reconstructed images in MRD format, asks the user to place a line plot, which is then used for estimating respiratory waveform from the reconstructed images.
+
+`remove_waveform.py`: Removes the waveforms with given ID from one or more MRD raw data files. You can pass files on the command line, including glob patterns, or select multiple files in the UI. It can also repack the data to reclaim space.
+
+`truncate_acquisitions.py`: Truncates the raw data to shorten the acquisiton time.
+
+-----
+
+`send_to_recon_server.py`: This script is part of the package and also provides an entry point that can be called as `send_to_recon_server`. It configures and runs the MRD client, which in turn sends the waveforms and the raw data to the reconstruction server. This workflow requires the `mrd` extra. A server toolkit that includes some reconstructions, including several ones capable of processing pilot tone is provided [here](https://github.com/usc-mrel/python-ismrmrd-server).
+
+There are several notebooks under `notebooks/` directory for mostly debugging or interactive usage purposes.
+
+## Directory Hierarchy for Raw Data
+
+The code expect raw data in the following hierarchy:
+
+    DATA_ROOT\
+        |- data_folder\
+            |- SEQUENCEHASH.mat
+            |- raw\
+                |- h5\
+                    |- raw_file.h5
+                |- h5_proc\
+                    |- raw_file_editer.h5
+                    |- raw_file_ptsub.h5
+                |- noise\
+                    |- noise_raw_file.h5
+
+`SEQUENCEHASH.mat` is the metadata file generated during sequence design. Refer to [rtspiral_pypulseq](https://github.com/usc-mrel/rtspiral_pypulseq) for the details.
+
+Processed raw data (either by EDITER or model subtraction) is put into `h5_proc` folder, with appropriate suffix to the file name.

pylottone-0.2.2/README.md

@@ -0,0 +1,116 @@
+# HAPTIC: High-amplitude Pilot Tone with Interference Cancellation
+PylotToneMRI is a Python Toolbox with an emphasis on high-amplitude pilot tone applied to spiral MR imaging.
+
+# Installation
+
+Create an isolated environment using your favorite software (`uv`, `venv`, `conda`, etc.). This project provides an `uv.lock` for the exact replication of the environment via `uv`. Example for `venv`:
+
+```bash
+python -m venv ${venv_name}
+source ${venv_name}/bin/activate
+```
+
+### For development:
+Clone this repository and navigate into it:
+```bash
+git clone https://github.com/usc-mrel/PylotToneMRI.git
+cd PylotToneMRI
+```
+
+Install via `pip` in dev mode:
+
+```bash
+pip install -e .
+```
+
+If you need ISMRMRD file I/O, waveform injection, or reconstruction tooling, install the MRD extra:
+
+```bash
+pip install -e '.[mrd]'
+```
+
+To enable GPU acceleration for EDITER, install the optional GPU extra:
+
+```bash
+pip install -e '.[gpu]'
+```
+## For usage as a library:
+
+It can be directly installed from `PyPI` via `pip`:
+```bash
+pip install pylottone
+```
+
+If you need ISMRMRD-backed workflows from the GitHub install, use:
+
+```bash
+pip install 'pylottone[mrd]'
+```
+
+If you want EDITER GPU support from the GitHub install, use:
+
+```bash
+pip install 'pylottone[gpu]'
+```
+
+**Note:** Toolbox is only tested for Python>=3.11 and Python<=3.12.
+
+### For ECG guided PT and fusion algorithm:
+
+ECG guided PT extraction (`examples/main_pilottone_extract_exercise.py`) requires `torch` library, which can be installed separately before running the script.
+
+# Usage
+
+Most inputs and outputs are in [ISMRMRD](https://ismrmrd.readthedocs.io/en/latest/) format. Base `pylottone` installs now leave ISMRMRD optional; install `pylottone[mrd]` for MRD file I/O, waveform editing, and reconstruction tooling. Some scripts do modify the input raw data, so in case something goes wrong, it is important to back-up original raw data. For a more detailed explanation of raw data, please refer to subsection [Directory Hierarchy for Raw Data](#directory-hierarchy-for-raw-data).
+
+Most scripts take the configuration file in `toml` format, for specifying input data and some important parameters. An example config file, `example_config.toml` can be used as the template.
+
+Example for supplying the config file: `python script_to_run.py -c config_file_path.toml`. If no input config is supplied, `config.toml` is used as the default path.
+
+Most scripts also accepts list of inputs to be processed as a list of filepaths using `-f` or `--filepaths` switch. If no filepath is provided, scripts will open a UI to select one or multiple files for processing.
+ 
+## Summary of important notebooks/scripts
+
+### Following are under `examples/` directory:
+
+`main_pilottone_extract.py`: This is the main script that loads the raw data, extracts pilot tone, and saves the extracted waveforms back into the same raw data as an MRD waveform. Later parts of this notebook assumes ECG is acquired in the raw data, so if it is not the case, one can also run the parts that extract pilot tone, without comparing to ECG. **Note:** This script provides a pipeline for a spiral acquisiton, as implemented here: [Real Time Spiral sequences in PyPulseq](https://github.com/usc-mrel/rtspiral_pypulseq). Can be used as a template for other type of acquisitions.
+
+`main_editer_correct.py`: This script will process the raw data using EDITER and saves the corrected raw data. 
+
+`run_all.py`: A convenience script that applies pilot tone extraction and EDITER processing on the supplied raw data, and send the results to reconstruction server.
+
+`main_process_reference.py`: Can be used to process raw data with no PT.
+
+### Following are under `tools/` directory:
+
+`respiratory_from_image.py`: From reconstructed images in MRD format, asks the user to place a line plot, which is then used for estimating respiratory waveform from the reconstructed images.
+
+`remove_waveform.py`: Removes the waveforms with given ID from one or more MRD raw data files. You can pass files on the command line, including glob patterns, or select multiple files in the UI. It can also repack the data to reclaim space.
+
+`truncate_acquisitions.py`: Truncates the raw data to shorten the acquisiton time.
+
+-----
+
+`send_to_recon_server.py`: This script is part of the package and also provides an entry point that can be called as `send_to_recon_server`. It configures and runs the MRD client, which in turn sends the waveforms and the raw data to the reconstruction server. This workflow requires the `mrd` extra. A server toolkit that includes some reconstructions, including several ones capable of processing pilot tone is provided [here](https://github.com/usc-mrel/python-ismrmrd-server).
+
+There are several notebooks under `notebooks/` directory for mostly debugging or interactive usage purposes.
+
+## Directory Hierarchy for Raw Data
+
+The code expect raw data in the following hierarchy:
+
+    DATA_ROOT\
+        |- data_folder\
+            |- SEQUENCEHASH.mat
+            |- raw\
+                |- h5\
+                    |- raw_file.h5
+                |- h5_proc\
+                    |- raw_file_editer.h5
+                    |- raw_file_ptsub.h5
+                |- noise\
+                    |- noise_raw_file.h5
+
+`SEQUENCEHASH.mat` is the metadata file generated during sequence design. Refer to [rtspiral_pypulseq](https://github.com/usc-mrel/rtspiral_pypulseq) for the details.
+
+Processed raw data (either by EDITER or model subtraction) is put into `h5_proc` folder, with appropriate suffix to the file name.

pylottone-0.2.2/environment.yml

@@ -0,0 +1,22 @@
+name: pilottone
+channels:
+  - ismrmrd
+  - conda-forge
+  - defaults
+dependencies:
+  - python=3.12
+  - ismrmrd::ismrmrd-python=1.14.1
+  - ismrmrd::siemens_to_ismrmrd=1.2.12
+  - boost=1.80.0         # For ismrmrd
+  - libxml2=2.10.3       # For ismrmrd
+  - h5py=3.7.0           # For ismrmrd
+  - matplotlib=3.8.4     # used by rgb.py and provides various visualization tools including colormaps
+  - numpy=1.26.4
+  - pyside2=5.15.5       # For UI in respiratory_from_image.py
+  - git
+  - ipykernel
+  - pandas
+  - pyfftw
+  - hyperspy
+  - pip
+  - cupy # For GPU acceleration at EDITER processing.

pylottone-0.2.2/example_config.toml

@@ -0,0 +1,60 @@
+# File Path config
+data_folder     = ""
+DATA_ROOT       = "/"
+
+# Reconstruction control
+[reconstruction]
+recon_type      = "viewsharing" # 'viewsharing', 'ttv', 'xdgrasp'
+server_port     = 9028  # Port that server is currently running on.
+show_images     = true  # Whether or not to show images after reconstruction.
+output_folder   = "output_recons"
+
+# EDITER control
+[editer]
+prewhiten           = true
+autosniffer_select  = false
+sensing_coils       = [1, 15, 16, 17] # Coils to use for sensing.
+gpu_device          = 1     # GPU device to use for EDITER, -1 for CPU.
+# Note: If the configured GPU is unavailable or CuPy is not installed,
+# the EDITER implementation will automatically fall back to the CPU path.
+interference_freq   = 24e6  # Frequency of the interference signal, to be used in autosniffer_select.
+denoise_rank        = 1     # Number of singular components to keep for per-window sniffer denoising.
+
+[pilottone]
+pt_freq = 24e6
+prewhiten = true
+discard_badcoils = true # Uses the same algorithm as autosniffer_select to discard bad coils.
+sensing_coils       = [15, 16, 17] # Coils to use for sensing.
+show_outputs    = false # Whether or not to show the outputs of the pilottone extraction.
+golay_filter_len = 81 # Golay filter length for initial denoising.
+source_selection_method = "spectral" # "spectral" or "model" for SOBI navigator source selection.
+
+[pilottone.model_source_selection]
+force_navpred = true # Force one respiratory and one cardiac source when using model source selection.
+# classifier_path = "" # Optional path to a custom joblib-compatible navigator classifier.
+
+[pilottone.respiratory]
+freq_start          = 0.05 # [Hz] Lower frequency limit for respiratory bandpass filter
+freq_stop           = 0.9 # [Hz] Upper frequency limit for respiratory bandpass filter
+corr_threshold      = 0.9 # Correlation threshold for respiratory coil selection
+initial_channel      = -1 # Initial guess for the respiratory coil selection
+separation_method = "sobi" # SOBI or PCA
+
+[pilottone.cardiac]
+freq_start          = 1 # [Hz] Lower frequency limit for cardiac bandpass filter
+freq_stop           = 20 # [Hz] Upper frequency limit for cardiac bandpass filter
+corr_threshold      = 0.9 # Correlation threshold for cardiac coil selection
+initial_channel     = 'Body_6:1:B13' # Initial guess for the cardiac coil selection
+separation_method = "pca" # SOBI or PCA
+sign = 1   # When cardiac signal is not stable enough, sign detection fails. This will flip the signal in case cardiac signal is flipped.
+
+[pilottone.debug]
+selected_coils = [0,1]
+show_plots = false
+no_normalize = true
+
+[saving]
+remove_os               = false # Remove 2x oversampling when saving the raw data
+save_model_subtracted   = false # Whether or not to save PT model subtracted data in main_pilottone_extract script.
+save_pt_waveforms       = false # Whether or not to save pilottone waveforms in main_pilottone_extract script.
+save_pt_separate        = true # Whether or not to save pilottone waveforms in separate npz files.