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, container image, 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

From Source

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

Add --recursive to the clone (or run git submodule update --init) to also fetch the ISMRM 2016 fitting challenge example data used by the tests.

How the LCModel binary is handled

LCModel is not shipped in the wheel. On first use it is found in this order, and the first one that works is cached:

1. path2exec you pass to PyLCModel,
2. the community binary for your OS/architecture from schorschinho/LCModel,
3. the binary built by this repository's CI for the installed version (releases; Linux x86_64/aarch64 and macOS arm64/x86_64, all statically linked),
4. the container image ghcr.io/julianmer/lcmodel, if Docker or podman is running,
5. a build from source with gfortran.

Each candidate is run once before it is accepted, so a binary that cannot run on your machine is skipped rather than cached. Useful switches: allow_download, allow_docker, allow_build on PyLCModel, and the LCMODEL_EXEC / LCMODEL_CACHE_DIR environment variables.

With the container, LCModel sees your working directory and your home directory; keep the basis set and any save_path under one of them. The image also works on its own:

docker run --rm -i -v "$PWD:$PWD" -w "$PWD" ghcr.io/julianmer/lcmodel < control.file

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 source code: created and made available free of charge (Stephen Provencher).
• LCModel binaries: schorschinho/LCModel (Georg Oeltzschner and contributors)
• Basis conversion reference: MRS Basis Set Conversion Toolbox (Kay Igwe)
• NIfTI-MRS: spec2nii, NIfTI-MRS Python tools (Will Clarke)
• Example data: ISMRM 2016 MRS Fitting Challenge (Małgorzata Marjańska, Dinesh Deelchand, Roland Kreis), mirrored via wtclarke/mrs_fitting_challenge