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.