SMART_MRS

SMART_MRS is a Python based library (toolbox) for applying simulated artifacts to edited Magnetic Resonance Spectroscopy (MRS) data.

MIT License, Copyright (c) 2024 HarrisBrainLab.

Use of SMART_MRS requires citation. Please see either CITATION.cff or GitHub's "Cite this repository".

For further information on the toolbox, please see SMART MRS Pub

Updates

Current version is 2.1. Previous version 2.0. See CHANGES.md for more details.

Module Descriptions

The SMART_MRS package contains 4 modules: * IO.py (allows for the import and export of specific data formats such as FID-A and nifti-mrs): * getFIDAmatdata() * returnFIDAmatdata() * getniftimrsdata() * returnniftimrsdata()

• support.py (supports data manipulation for the use of other module functions):

  • to_fids()
  • to_specs()
  • interleave()
  • undo_interleave()
  • scale()
  • undo_scale()

• artifacts.py (for the application of various artifacts):

  • addtimedomain_noise()
  • addspurecho_artifact()
  • addeddycurrent_artifact()
  • add_linebroad()
  • addnuisancepeak()
  • add_baseline()
  • addfreqdrift_linear()
  • addfreqshift_random()
  • addzeroorderphaseshift()
  • addfirstorderphaseshift()

• applied.py (allows for specific iterations of the artifacts):

  • addprogressivemotion_artifact()
  • addsubtlemotion_artifact()
  • adddisruptivemotion_artifact()
  • addlipidartifact()

Dependencies

Each of the 4 modules have relative dependencies in addition to the following dependencies: * Nibabel (v.5.2.1) * NumPy (v.1.25.2) * SciPy (v.1.11.4)

SMART_MRS Installation Guide

Create an empty Conda environement for installation: bash conda create -n my_smart_mrs_env python=3.11.9

Activate the Conda environement: bash conda activate my_smart_mrs_env

Install pip into your Conda environement: bash conda install pip

Use pip package manager to install the SMART_MRS library as below: bash python3 -m pip install SMART_MRS

For more information on the versions of dependencies, please consult the smart_env.yml file.

Usage

Below are example uses of functions from each module in SMART_MRS. For further information on specific functions, please consult SupplementaryMaterial.pdf

```python import SMART_MRS import matplotlib.pyplot as plt

IO Functions example getniftimrs_data() - returns FIDs, time, and ppm

DIR = "C:/Users/" fids, time, ppm = SMARTMRS.IO.getniftimrsdata(dirnifti=f"{DIR}jdifferenceniftiSMARTMRS_EX.nii.gz") print(f'Data has {fids.shape[0]} FIDs with {fids.shape[1]} spectral points.')

Support Functions example scale() - returns scaled FIDs and scale factor

rawscaledfids, niftiscale = SMARTMRS.support.scale(fids) fids = np.copy(rawscaledfids)

Artifacts Functions example addnuisancepeak() - returns FIDs and artifact locations within dataset

Apply specific user values

gaussianpeakprofile = { "peaktype": "G", "amp": [0.010, 0.010], "width": [0.85, 0.85],
"resfreq": [1.5, 1.5], "phase": [0, 0], "edited": 1.02 }

When echo is True, will print non-user specified values used (in this case, the locations of the artifacts)

fids, nplocations = SMARTMRS.artifacts.addnuisancepeak(fids=fids, time=time, peakprofile=gaussianpeakprofile, locs=[0,1], cfppm=3, echo=True)

Plot nuisance peak

plt.figure(figsize=(10,5)) plt.suptitle('GABA-Edited Specs Before and After Nuisance Peak Addition')

plt.subplot(121) plt.title('Before', fontsize=10) plt.plot(ppm[::-1], (SMARTMRS.support.tospecs(rawscaledfids)[0, :]-SMARTMRS.support.tospecs(rawscaledfids)[1, :]).real, 'black') plt.xlabel('ppm') plt.xlim(0, 6) plt.gca().invert_xaxis()

plt.subplot(122) plt.title('After', fontsize=10) plt.plot(ppm[::-1], (SMARTMRS.support.tospecs(fids)[0, :]-SMARTMRS.support.tospecs(rawscaledfids)[1, :]).real, 'green') plt.xlabel('ppm') plt.xlim(0, 6) plt.gca().invert_xaxis() plt.show()

Applied Functions example adddisruptivemotion_artifact() - returns FIDs and artifact locations within dataset

use function specific values

fids, motionlocations = SMARTMRS.applied.adddisruptivemotion_artifact(fids=fids, time=time, ppm=ppm, locs=[2,3])

Plot disruptive motion

plt.figure(figsize=(10,5)) plt.suptitle('GABA-Edited Specs Before and After Disruptive Artifact')

plt.subplot(121) plt.title('Before', fontsize=10) plt.plot(ppm[::-1], (SMARTMRS.support.tospecs(rawscaledfids)[2, :]-SMARTMRS.support.tospecs(rawscaledfids)[3, :]).real, 'black') plt.xlabel('ppm') plt.xlim(0, 6) plt.gca().invert_xaxis()

plt.subplot(122) plt.title('After', fontsize=10) plt.plot(ppm[::-1], (SMARTMRS.support.tospecs(fids)[2, :]-SMARTMRS.support.tospecs(fids)[3, :]).real, 'blue') plt.xlabel('ppm') plt.xlim(0, 6) plt.gca().invert_xaxis() plt.show()

Save Fids with Artifacts as original data type

New nifti should be saved under same name "_SMART.niigz" at same location

fids = SMARTMRS.support.undoscale(fids=fids, scalefact=niftiscale) SMARTMRS.IO.returnniftimrsdata(dirnifti=f"{DIR}jdifferenceniftiSMARTMRSEX.nii.gz", fids=fids, edited=True) ``` The above code generates the following plots: _Nuisance Peak Example__

Disruptive Motion Example