Metadata-Version: 2.4
Name: pyamares-xmris
Version: 0.5.0
Summary: PyAMARES repackaged for clean pip installs on Apple Silicon (arm64) and for numpy 2 / pandas 3: a faithful BSD repackage of HawkMRS/pyAMARES carrying only minimal, ledger-documented compatibility fixes (see DIVERGENCE.md); still 'import pyAMARES'.
Author: Jia Xu, MR Research Facility, University of Iowa
Author-email: jia-xu-1@uiowa.edu
License: BSD-3-Clause
Project-URL: Homepage, https://github.com/andrewendlinger/pyAMARES
Project-URL: Upstream (original project), https://github.com/hawkMRS/pyAMARES
Project-URL: Upstream documentation, https://pyamares.readthedocs.io/en/latest/index.html
Project-URL: Divergence from upstream, https://github.com/andrewendlinger/pyAMARES/blob/pyamares-xmris/DIVERGENCE.md
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/x-rst
License-File: LICENSE.txt
Requires-Dist: numpy>=1.18.1
Requires-Dist: scipy>=1.2.1
Requires-Dist: pandas>=1.1.0
Requires-Dist: matplotlib>=3.1.3
Requires-Dist: lmfit
Requires-Dist: sympy
Requires-Dist: nmrglue>=0.12
Requires-Dist: jinja2
Requires-Dist: tqdm
Provides-Extra: matlab
Requires-Dist: mat73; extra == "matlab"
Provides-Extra: excel
Requires-Dist: openpyxl; extra == "excel"
Requires-Dist: xlrd; extra == "excel"
Provides-Extra: hlsvd
Requires-Dist: hlsvdpro>=2.0.0; (platform_machine == "x86_64" or platform_machine == "amd64") and extra == "hlsvd"
Provides-Extra: jupyter
Requires-Dist: notebook; extra == "jupyter"
Requires-Dist: ipykernel; extra == "jupyter"
Requires-Dist: ipython; extra == "jupyter"
Requires-Dist: ipywidgets<8.0.0,>=7.6.0; python_version < "3.11" and extra == "jupyter"
Requires-Dist: ipywidgets>=8.0.0; python_version >= "3.11" and extra == "jupyter"
Requires-Dist: requests; extra == "jupyter"
Requires-Dist: mat73; extra == "jupyter"
Requires-Dist: openpyxl; extra == "jupyter"
Requires-Dist: xlrd; extra == "jupyter"
Provides-Extra: docs
Requires-Dist: sphinx; extra == "docs"
Requires-Dist: nbsphinx; extra == "docs"
Requires-Dist: sphinx_tabs; extra == "docs"
Requires-Dist: sphinx_rtd_theme; extra == "docs"
Requires-Dist: Pygments; extra == "docs"
Requires-Dist: ipywidgets; extra == "docs"
Provides-Extra: ruff
Requires-Dist: ruff; extra == "ruff"
Requires-Dist: pre-commit; extra == "ruff"
Requires-Dist: pytest; extra == "ruff"
Provides-Extra: dev
Requires-Dist: notebook; extra == "dev"
Requires-Dist: ipykernel; extra == "dev"
Requires-Dist: ipython; extra == "dev"
Requires-Dist: ipywidgets<8.0.0,>=7.6.0; python_version < "3.11" and extra == "dev"
Requires-Dist: ipywidgets>=8.0.0; python_version >= "3.11" and extra == "dev"
Requires-Dist: requests; extra == "dev"
Requires-Dist: mat73; extra == "dev"
Requires-Dist: openpyxl; extra == "dev"
Requires-Dist: xlrd; extra == "dev"
Requires-Dist: sphinx; extra == "dev"
Requires-Dist: nbsphinx; extra == "dev"
Requires-Dist: sphinx_tabs; extra == "dev"
Requires-Dist: sphinx_rtd_theme; extra == "dev"
Requires-Dist: Pygments; extra == "dev"
Requires-Dist: ipywidgets; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Dynamic: license-file

**PyAMARES**, an Open-Source Python Library for Fitting Magnetic Resonance Spectroscopy Data
********************************************************************************************

.. note::

   **This is** ``pyamares-xmris``, **a repackage — not the original project.** It is a
   faithful BSD repackage of `HawkMRS/pyAMARES <https://github.com/hawkMRS/pyAMARES>`_ with
   corrected dependency metadata — the default install does not declare ``hlsvdpro``, so
   ``pip install`` succeeds on Apple Silicon (arm64), and it installs only what the fitting
   engine actually imports (see Installation below) — and carries **only minimal, individually documented
   compatibility fixes** — from 0.4.0, the ones that make the source correct under numpy 2,
   pandas 3 and Python 3.14. The fitting algorithms are untouched, 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 <https://github.com/andrewendlinger/pyAMARES/blob/pyamares-xmris/DIVERGENCE.md>`_.
   Note in particular that this package **cannot be installed alongside upstream**
   ``pyAMARES`` — both occupy ``site-packages/pyAMARES/``. Please cite the original authors.

.. image:: https://raw.githubusercontent.com/HawkMRS/pyAMARES/main/pyAMARES_logo.svg
   :width: 400

The full documentation for pyAMARES can be found at `pyAMARES Documentation <https://pyamares.readthedocs.io/en/latest/index.html>`_.

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
------------

.. image:: https://img.shields.io/badge/Python-3.8+%20(3.11+%20recommended)-blue.svg
   :target: https://python.org
   :alt: Python Version

.. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json
   :target: https://github.com/astral-sh/ruff
   :alt: Ruff

.. 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):
   
   .. code-block:: bash
   
      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
------------

.. code-block:: bash

   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.)

That is the **fitting engine only**: numpy, scipy, pandas, matplotlib, lmfit, sympy,
nmrglue, jinja2 and tqdm. Everything else lives behind an extra, and each one is additive:

.. code-block:: bash

   pip install 'pyamares-xmris[jupyter]'   # the notebooks and interactive workflows: Jupyter, requests, and the matlab/excel extras below
   pip install 'pyamares-xmris[matlab]'    # mat73, for reading MATLAB v7.3 (HDF5) .mat files
   pip install 'pyamares-xmris[excel]'     # openpyxl and xlrd, for .xlsx / .xls prior knowledge spreadsheets
   pip install 'pyamares-xmris[hlsvd]'     # hlsvdpro, the optional native HSVD backend (x86_64 only; unused on numpy 2+)

Prior knowledge in CSV form and MATLAB files older than v7.3 need no extra. If an extra is
missing, the function that needs it raises an ``ImportError`` naming the one to install.
The HSVD path never needs ``[hlsvd]``: without it pyAMARES uses its own bundled pure-Python
implementation, which is what every numpy 2 install has used all along.

See the `Installation Guide <https://pyamares.readthedocs.io/en/latest/install.html>`_ for detailed information.

Run pyAMARES in any web browser
-------------------------------

**New:** PyAMARES now offers `a user-friendly web interface <https://pyamares.streamlit.app/>`_ 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

.. image:: https://static.streamlit.io/badges/streamlit_badge_black_white.svg
   :target: https://pyamares.streamlit.app/
   :alt: Streamlit App

No installation required - just visit the `link <https://pyamares.streamlit.app/>`_ and start fittting your MRS data right away!

Run pyAMARES as standard-alone script
-------------------------------------


.. code-block:: bash

   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 <https://colab.research.google.com/drive/184_7MJ6O1BgGYyqNvnXXqtri4_0N4ySw?usp=sharing>`_

.. code-block:: python

   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
------------------------------------------

.. image:: https://raw.githubusercontent.com/HawkMRS/pyAMARES/main/pyAMARES/examples/simple_example.svg
   :width: 400

.. image:: https://raw.githubusercontent.com/HawkMRS/pyAMARES/main/pyAMARES/examples/simple_example_html.jpeg
   :width: 400

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 <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 <https://doi.org/10.3390/diagnostics14232668>`_

