pyamares-xmris 0.3.33

PyAMARES repackaged for clean pip installs on Apple Silicon (arm64): hlsvdpro is made platform-conditional. A faithful BSD repackage of HawkMRS/pyAMARES with zero algorithm changes; still 'import pyAMARES'.

Note

This is pyamares-xmris, a repackage — not the original project. It is a faithful BSD repackage of HawkMRS/pyAMARES whose only substantive difference is that hlsvdpro is declared with a PEP 508 environment marker, so that pip install succeeds on Apple Silicon (arm64). There are no source or algorithm changes, and the import name is still import pyAMARES.

Every difference from upstream, every known dependency limitation, and the open questions not yet decided are recorded in DIVERGENCE.md. Note in particular that this package cannot be installed alongside upstream pyAMARES — both occupy site-packages/pyAMARES/. Please cite the original authors.

The full documentation for pyAMARES can be found at pyAMARES Documentation.

What is pyAMARES?

The pyAMARES package provides the MRS community with an open-source, easy-to-use MRS fitting method in Python. It imports prior knowledge from Excel or CSV spreadsheets as initial values and constraints for fitting MRS data according to the AMARES model function.

Getting Started

Requirements

Note

PyAMARES requires Python 3.8 or newer. We recommend using Python 3.11 or newer. If you are using an older version of Python, you will need to upgrade to use pyAMARES.

Warning

If you require Python 3.6 or 3.7 compatibility for older systems, please use the legacy2025 branch (version 0.3.29):

python -m pip install git+https://github.com/HawkMRS/pyAMARES.git@legacy2025#egg=pyAMARES

The legacy branch is maintained for critical bug fixes only. For the latest features and improvements, we strongly recommend upgrading to Python 3.11 or newer.

Installation

pip install pyamares-xmris

(The import name remains pyAMARES. To install the original upstream distribution instead, use pip install pyAMARES — note that it does not install on arm64.)

See the Installation Guide for detailed information.

Run pyAMARES in any web browser

New: PyAMARES now offers a user-friendly web interface for fitting AMARES models without writing any code. The web app provides a graphical interface to:

• Upload your FID data file

• Upload the prior knowledge spreadsheet (Excel or CSV)

• Edit the prior knowledge spreadsheet as needed

• Set MR parameters (MHz, spectrum width, deadtime, etc)

• Visualize results with interactive plots

• Download fitted results and figures

No installation required - just visit the link and start fittting your MRS data right away!

Run pyAMARES as standard-alone script

amaresFit -f ./pyAMARES/examples/fid.txt -p  ./pyAMARES/examples/example_human_brain_31P_7T.csv --MHz 120.0 --sw 10000 --deadtime 300e-6 --ifplot --xlim 10 -20 -o simple_example

Run pyAMARES in a Jupyter Notebook

Try Jupyter Notebook on Google Colab here

import pyAMARES
# Load FID from a 2-column ASCII file, and set the MR parameters
MHz = 120.0 # 31P nuclei at 7T
sw = 10000 # spectrum width in Hz
deadtime = 300e-6 # 300 us begin time for the FID signal acquisition

fid = pyAMARES.readmrs('./pyAMARES/examples/fid.txt')
# Load Prior Knowledge
FIDobj = pyAMARES.initialize_FID(fid=fid,
                                 priorknowledgefile='./pyAMARES/examples/example_human_brain_31P_7T.csv',
                                 MHz=MHz,
                                 sw=sw,
                                 deadtime=deadtime,
                                 preview=False,
                                 normalize_fid=False,
                                 xlim=(10, -20))# Region of Interest for visualization, -20 to 10 ppm

# Initialize the parameter using Levenberg-Marquard method
out1 = pyAMARES.fitAMARES(fid_parameters=FIDobj,
                           fitting_parameters=FIDobj.initialParams,
                           method='leastsq',
                           ifplot=False)

# Fitting the MRS data using the optimized parameter

out2 = pyAMARES.fitAMARES(fid_parameters=out1,
                          fitting_parameters=out1.fittedParams, # optimized parameter for last step
                          method='least_squares',
                          ifplot=False)

# Save the data
out2.styled_df.to_html('simple_example.html') # Save highlighted table to an HTML page
                                              # Python 3.6 does not support to_html.
out2.result_sum.to_csv('simple_example.csv') # Save table to CSV spreadsheet
out2.plotParameters.lb = 2.0 # Line Broadening factor for visualization
out2.plotParameters.ifphase = True # Phase the spectrum for visualization
pyAMARES.plotAMARES(fid_parameters=out1, filename='simple_example.svg') # Save plot to SVG

Fitting Result for Example 31P MRS data

Contributing

PyAMARES is currently in its early stages of development and is actively being improved. We welcome contributions to pyAMARES! Please see our CONTRIBUTING.rst guidelines for more information on how to get started.

How to cite

If you use pyAMARES in your research, please cite:

Xu, J.; Vaeggemose, M.; Schulte, R.F.; Yang, B.; Lee, C.-Y.; Laustsen, C.; Magnotta, V.A. PyAMARES, an Open-Source Python Library for Fitting Magnetic Resonance Spectroscopy Data. Diagnostics 2024, 14, 2668. https://doi.org/10.3390/diagnostics14232668