BasisREMY

A Unified Framework for Study-Specific Basis Set Generation in MR Spectroscopy

A tool for generating study-specific basis sets directly from raw MRS data, integrating real pulse shapes and acquisition parameters. This project is in its early development stages, and contributions, testing, and feedback are highly welcomed!

Prerequisites

• uv — installs Python and all dependencies into an isolated environment (one-line installer below); nothing is installed globally.
• git — fetches the simulation toolboxes the first time you simulate (and clones the repository if you develop).
• Docker or Octave (only for simulating) — Docker Desktop (recommended) or a local Octave 4.0+; see Docker / Octave Requirements.

Quick Start (for users)

The fastest way to run BasisREMY is with uv — a single tool that installs Python for you (no manual Python, pip, or conda setup required).

1. Install uv (one time):

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

2. Launch BasisREMY — the released version, straight from PyPI:

uvx basisremy

Or, for repeated use, install the command once and then run it by name:

uv tool install basisremy
basisremy

To run the latest development state instead of the release:

uvx --from git+https://github.com/julianmer/BasisREMY basisremy

Using BasisREMY from Python instead of the GUI? The package is on PyPI — pip install basisremy gives you the programmatic API (see Examples below) without any GUI setup.

uv automatically downloads a compatible Python and all dependencies into an isolated environment — nothing is installed globally and your data never leaves your machine.

First run: the first simulation with an engine on a new machine sets that engine up (its toolbox at a pinned version into ~/.basisremy or $BASISREMY_HOME, and its Docker image if needed) and can take a few minutes; after that it starts in seconds. Ran BasisREMY before? uvx basisremy@latest gets the newest release.

Usage Overview

BasisREMY guides you through a simple three-step workflow, shown as a numbered stepper at the top of the window (Data → Parameters → Simulate). You can click any completed step to go back and make changes. A light/dark theme toggle sits in the top-right corner and follows your system setting by default.

1. Data — Drop your MRS data file onto the upload area (or click it to browse). Click Continue to automatically read the file and pre-fill the acquisition parameters, or Skip to configure everything manually.
2. Parameters — One layout for every engine: pick the Engine and the Sequence, optionally a Sequence file (any pulse or whole-sequence file), then check the timings, the acquisition values and the metabolites to include. Each value is marked by where it comes from: from the data file, recommended / default (for design values no header holds, such as the echo split; hover for the source), set by you, or missing (Simulate stays blocked until you fill it). When the required fields are set, click Simulate basis set.
3. Simulate — A progress bar shows the simulation status. When it finishes, an interactive spectrum plot appears and you can click Export basis… to save the basis set in LCModel (.basis or .RAW), jMRUI, FSL-MRS, Osprey, FID-A, INSPECTOR, ProFit, MARSS, MRSCloud, or SpinWizard/JET format. Format writing is handled by the bundled MRS Basis Set Conversion Toolbox.

Every input has a small (?) help icon — hover it for a short explanation of that parameter.

Sequence designer (new, in testing) — the wand next to the sequence file opens the designer: choose the sequence, its timings and a pulse per role (ideal, a standard shape, or a pulse file in any format; the scan's own pulse where the data header stores it), see the timeline, and save the design as a Pulseq .seq (in ~/BasisREMY/sequences/). The saved file is selected right away; the engine chips show which engines run the design as is, with differences, or not at all.

Examples (No GUI)

Want to use BasisREMY programmatically? Check out the examples/ folder!

Quick start:

python examples/basic_usage.py

The example shows how to:

• Load MRS data and extract parameters automatically
• Configure and run simulations without the GUI
• Customize metabolite lists and output settings

In your own scripts, call basisremy.prepare_runtime() first and give file paths as absolute paths: the simulation engines run from BasisREMY's runtime folder, as in the GUI.

Developer Setup

Clone the repository (with submodules) and let uv create the environment:

git clone --recurse-submodules https://github.com/julianmer/BasisREMY.git
cd BasisREMY
uv sync            # creates .venv and installs all dependencies
uv run basisremy   # launches the GUI

uv sync reads pyproject.toml, provisions a matching Python, and installs everything into .venv. You do not need to activate the environment — uv run handles that automatically. To include development tools (pytest, coverage), run uv sync --extra dev.

Prefer pip? pip install basisremy for the Python API, or pip install -e . in a clone.

Docker / Octave Requirements

Simulation backends execute MATLAB/Octave code and therefore need an Octave runtime. BasisREMY supports two interchangeable options and selects one automatically:

1. Docker (recommended) — install Docker Desktop (macOS/Windows) or Docker Engine (Linux), and make sure it is running. BasisREMY pulls/builds an Octave container on demand.
2. Local Octave — install Octave 4.0+ directly; it is used as a fallback when Docker is unavailable.

Whether an Octave runtime is needed is backend-dependent: data extraction and parameter configuration work without it; only the simulation step requires it. See the Octave Setup Guide for detailed instructions.

The Spant backend needs R in the same way: Docker (BasisREMY builds an R image with the spant package on first use) or an R installation of your own, into which the package is installed on first use. The Vespa backend needs neither — it runs in a Python side-environment or Docker.

Three environment variables tune the runtimes:

Troubleshooting

• Window stays blank or pywebview errors (You must have either QT or GTK) — the desktop window needs a display and, on Linux, a system WebKitGTK package. Run basisremy --browser (or uvx basisremy --browser) to use the UI in your web browser at http://localhost:8080 instead; without a display this happens automatically.
• Running on a server (SSH) — start uvx basisremy on the server, then on your own machine run ssh -L 8080:localhost:8080 user@server and open http://localhost:8080 in a browser. Use --port if 8080 is taken.
• Simulation fails / "Octave not found" — start Docker Desktop/Engine, or install local Octave. See the Octave Setup Guide.
• uv: command not found — re-open your terminal after installing uv, or add its install location to your PATH.
• Backends can't find externals/... — the simulation toolboxes are fetched on first use into ~/.basisremy (or $BASISREMY_HOME); make sure git is installed and you have network access the first time you run a simulation. In a cloned repository the existing submodules under externals/ are used as-is.

Related References

The project builds upon the methodologies used in existing tools. Some references include:

• REMY and related literature (nbm.70039)
• FID-A and related literature (mrm.26091)
• FSL-MRS and related literature (mrm.28630)
• MRSCloud and related literature (mrm.29370)
• Vespa and related literature (mrm.29686)
• Spant and related literature (mrm.28385)
• Spinach and related literature (jmr.2010.11.008)
• MRS Basis Set Conversion Toolbox
• Custom Basis Set Simulation