lcmodel-wrapper 0.2.0

Lightweight Python wrapper for LCModel MRS fitting

PyLCModel

A lightweight Python wrapper for LCModel spectral fitting in MR spectroscopy

PyLCModel is a lightweight Python wrapper that streamlines the use of LCModel for least-squares spectral fitting in MRS. It automates control-file generation, handles flexible data input, manages the LCModel executable for you, and parses the output (with single- and multi-core processing).

---

Features

• Zero-setup binaries — the LCModel executable is resolved automatically (download, build from source, or your own path); nothing is bundled in the wheel.
• Flexible input — NumPy arrays, NIfTI-MRS, jMRUI text, and LCModel .RAW, in time or frequency domain.
• Automated control files — generated to match your data, or templated from an existing one.
• Basis conversion (experimental) — jMRUI, FSL-MRS, LCModel .RAW, and Osprey/FID-A basis sets to .basis.
• Batch fitting — single- or multi-core, with full output parsing (concentrations, CRLBs, QC, fitted series).

---

Installation

From PyPI

pip install lcmodel-wrapper

Enter your API token:

From Source

git clone https://github.com/julianmer/PyLCModel.git
cd PyLCModel
pip install -e .

---

How the LCModel binary is handled

The LCModel program is not part of this package and is not shipped in the wheel. On first use, the binary is resolved in this order:

1. an explicit path2exec="/path/to/lcmodel" you pass to PyLCModel,
2. a previously cached download/build (under ~/.cache/lcmodel_wrapper, or %LOCALAPPDATA% on Windows; override with LCMODEL_CACHE_DIR),
3. a download of the matching binary for your OS/architecture from schorschinho/LCModel,
4. a build from the LCModel Fortran source via gfortran (source fetched on demand).

There is no git submodule and no bundled lcmodel/ folder — keeping both the repository and the PyPI wheel small.

---

Getting Started

from lcmodel_wrapper import PyLCModel

# Initialize the wrapper with your basis set (the LCModel binary is resolved automatically)
lcmodel = PyLCModel(path2basis="/path/to/your/basis_set.basis")

# `data` can be a NumPy array of FIDs (time domain), a NIfTI-MRS path, etc.
concentrations, crlbs = lcmodel(data)

print("Fitted Metabolite Concentrations:", concentrations)
print("CRLBs:", crlbs)

Frequency-domain input or a custom executable:

lcmodel = PyLCModel(
    path2basis="/path/to/basis.basis",
    domain="freq",                 # pass spectra instead of FIDs
    path2exec="/path/to/lcmodel",  # optional: use your own binary
)

Experimental basis conversion (other formats -> .basis):

# Auto-detect the source format (jMRUI/AQSES/QUEST .txt folder, FSL-MRS .json folder,
# LCModel .RAW folder, or Osprey/FID-A .mat):
lcmodel = PyLCModel(path2basis="/path/to/basis_folder", convert_basis=True)

# ...or force a format and supply parameters the source does not carry:
lcmodel = PyLCModel(
    path2basis="/path/to/raw_folder",
    convert_basis=True,
    basis_format="raw",          # "jmrui" | "fsl" | "raw" | "mat"
    bandwidth=4000, central_freq=123.25,
)

# Or convert directly without fitting:
from lcmodel_wrapper import convert_to_basis
convert_to_basis("/path/to/jmrui_folder", out_path="out.basis")

Basis conversion is experimental and not validated. For a dedicated, more complete tool, see the MRS Basis Set Conversion Toolbox.

---

Licensing

This wrapper (the Python code) is released under the Apache License 2.0 (see LICENSE).

LCModel itself is a separate program by Dr. Stephen Provencher, distributed under the BSD 3-Clause License (see LICENSE.lcmodel). This package does not bundle LCModel; when it downloads, builds, or runs the LCModel executable, that BSD-3-Clause license and the attributions in NOTICE apply. See the LCModel home page for details.

---

Acknowledgements

• LCModel binaries: schorschinho/LCModel (Georg Oeltzschner and contributors)
• Basis conversion reference: MRS Basis Set Conversion Toolbox (Kay Igwe)
• NIfTI-MRS: spec2nii, NIfTI-MRS Pyhton tools (Will Clarke)

---

_{Built with ❤️ for the MRS community}