Metadata-Version: 2.4
Name: basisremy
Version: 0.1.3
Summary: A tool for generating study-specific MR spectroscopy basis sets directly from raw MRS data.
Author-email: "J. P. Merkofer" <j.p.merkofer@tue.nl>
Keywords: MRS,spectroscopy,basis set,simulation,FID-A,FSL-MRS,MRSCloud,Vespa,PyGAMMA,spant,Spinach
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: brukerapi==0.1.8
Requires-Dist: docker>=6.0.0
Requires-Dist: matplotlib==3.10.7
Requires-Dist: numpy==2.3.3
Requires-Dist: oct2py==5.8.0
Requires-Dist: pandas==2.3.3
Requires-Dist: pillow>=10.0.0
Requires-Dist: pyMapVBVD==0.6.1
Requires-Dist: scipy>=1.10.0
Requires-Dist: spec2nii==0.8.7
Requires-Dist: nicegui>=2.0.0
Requires-Dist: pywebview>=5.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pytest-xdist>=3.0.0; extra == "dev"
Requires-Dist: pytest-timeout>=2.1.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"

<div align="center">
  <img src="https://raw.githubusercontent.com/julianmer/BasisREMY/main/basisremy/assets/imgs/basisremy_logo_round.png" alt="BasisREMY Logo" width="120" style="margin-bottom: -10px;"/>
  <h1 style="margin-top: 5px; margin-bottom: 5px;">BasisREMY</h1>
  <p style="margin-top: 0px;"><em>A Unified Framework for Study-Specific Basis Set Generation in MR Spectroscopy</em></p>
  
  [![PyPI](https://img.shields.io/pypi/v/basisremy.svg)](https://pypi.org/project/basisremy/)
  [![Python](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/)
  [![Tests](https://github.com/julianmer/BasisREMY/actions/workflows/tests.yml/badge.svg)](https://github.com/julianmer/BasisREMY/actions/workflows/tests.yml)
  [![ISMRM 2026](https://img.shields.io/badge/ISMRM-Abstract%20%2301716-lightgrey.svg)](https://archive.ismrm.org)
</div>

---

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!

<div align="center">
  <img src="https://raw.githubusercontent.com/julianmer/BasisREMY/main/basisremy/assets/imgs/basisremy_workflow_v2.png" alt="BasisREMY Workflow" width="750"/>
</div>

---

## Prerequisites

For the recommended [`uvx`](https://docs.astral.sh/uv/) quick start you do **not**
need to install Python yourself — `uv` downloads a compatible Python automatically.
You only need:

- **[`uv`](https://docs.astral.sh/uv/)**: installs Python and all dependencies into
  an isolated environment (one-line installer in *Quick Start* below). Nothing is
  installed globally.

- **[`git`](https://git-scm.com/)**: used the first time you run a simulation to
  fetch the third-party simulation toolboxes (and for cloning if you develop).

- **Octave Runtime** *(simulation backends only)*: Version 4.0 or higher.

  **You have two options:**
  
  1. **Docker** (Recommended) - Automatic setup, works everywhere
  2. **Local Octave** - Traditional installation
  
  **📖 See the [Octave Setup Guide](basisremy/assets/OCTAVE_SETUP.md) for detailed installation instructions.**
  
  > **Note**: BasisREMY automatically detects and uses Docker if available, otherwise falls back to local Octave. Data extraction and parameter configuration work without an Octave runtime; only the simulation step requires it.

> **Python 3.11+** is only required if you skip `uv` and install manually with
> `pip` (see *Setting Up the Python Environment* below).

---

## Quick Start (for users)

The fastest way to run BasisREMY is with [`uv`](https://docs.astral.sh/uv/) — a single
tool that installs Python for you (no manual Python, `pip`, or conda setup required).

**1. Install `uv`** (one time):

```bash
# 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:

```bash
uvx basisremy
```

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

```bash
uv tool install basisremy
basisremy
```

To run the latest development state instead of the release:

```bash
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](#examples-no-gui) 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.

> **Note on simulation backends**: The simulation backends
> rely on third-party toolboxes that cannot be redistributed inside the wheel. The first time you run a
> simulation, BasisREMY fetches the toolbox it needs (at a pinned version) into a
> per-user data directory (`~/.basisremy`, overridable via `$BASISREMY_HOME`).

---

## Developer Setup

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

```bash
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`](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`.

---

## 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](https://www.docker.com/products/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](https://octave.org/) 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](basisremy/assets/OCTAVE_SETUP.md) 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:

| Variable | Effect |
| --- | --- |
| `BASISREMY_OCTAVE_WORKERS` | Octave processes used to simulate metabolites in parallel (default: half the CPUs, at most 4). |
| `BASISREMY_NO_DOCKER` | Set to `1` to ignore Docker entirely and use only a local Octave. |
| `BASISREMY_SPANT_RUNTIME` | `docker` or `local` to force the Spant runtime (default: Docker, then your own R). |

---

## Troubleshooting

- **GUI doesn't open / `ModuleNotFoundError: No module named 'nicegui'`** — the
  front-end is [NiceGUI](https://nicegui.io) shown in a native desktop window via
  [pywebview](https://pywebview.flowrl.com). They install automatically with the
  project (`uv sync` / `uvx --from . basisremy`); if you installed manually, run
  `pip install nicegui pywebview`. These are pure-pip packages, so no system
  `tcl/tk` is required.
- **Window stays blank or pywebview errors** — without `pywebview` the UI falls
  back to opening in your browser; install it (`pip install pywebview`) for the
  native window. On Linux a system WebKitGTK package may be needed.
- **Simulation fails / "Octave not found"** — start Docker Desktop/Engine, or
  install local Octave. See the [Octave Setup Guide](basisremy/assets/OCTAVE_SETUP.md).
- **`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.

---

## Setting Up the Python Environment (manual / pip)

> The `uv` quick start above is the recommended path. The steps below remain
> available if you prefer a manual `venv` + `pip` workflow.

It is recommended to use a virtual environment to isolate project dependencies. Start by cloning the repository.
```bash
git clone --recurse-submodules https://github.com/julianmer/BasisREMY.git
cd BasisREMY
```

### Create and Activate the Virtual Environment

**Windows:**
```bash
python -m venv --prompt basisREMY .venv
.venv\Scripts\activate
```

**macOS/Linux:**
```bash
python3 -m venv --prompt basisREMY .venv
source .venv/bin/activate
```

### Install Required Python Packages
Upgrade pip and install the required packages by running:

```bash
pip install --upgrade pip
pip install -r requirements.txt
```

---

## Running BasisREMY
With all dependencies installed and your basisREMY environment activated, run the application:
```bash
python -m basisremy
```
This will launch the BasisREMY GUI. (Inside the repo you can equivalently use `uv run basisremy`.)

### 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** — Choose a simulation **backend** (grouped by category), review
   the auto-filled parameters, and tick the **metabolites** to include (**Select
   all** toggles the whole list). 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, 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](https://github.com/igweckay/MRS-Basis-Set-Conversion-Toolbox).

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


### Examples (No GUI)

Want to use BasisREMY programmatically? Check out the **[examples/](examples/)** folder!

**Quick start:**
```bash
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

---

## Related References
The project builds upon the methodologies used in existing tools. Some references include:
- [REMY](https://github.com/agudmundson/mrs_in_mrs) and related literature ([nbm.70039](https://analyticalsciencejournals.onlinelibrary.wiley.com/doi/10.1002/nbm.70039))
- [FID-A](https://github.com/CIC-methods/FID-A) and related literature ([mrm.26091](https://doi.org/10.1002/mrm.26091))
- [FSL-MRS](https://github.com/wtclarke/fsl_mrs) and related literature ([mrm.28630](https://doi.org/10.1002/mrm.28630))
- [MRSCloud](https://github.com/shui5/MRSCloud) and related literature ([mrm.29370](https://doi.org/10.1002/mrm.29370))
- [Vespa](https://github.com/vespa-mrs/vespa) and related literature ([mrm.29686](https://doi.org/10.1002/mrm.29686))
- [Spant](https://github.com/martin3141/spant) and related literature ([mrm.28385](https://doi.org/10.1002/mrm.28385))
- [Spinach](https://github.com/IlyaKuprov/Spinach) and related literature ([jmr.2010.11.008](https://doi.org/10.1016/j.jmr.2010.11.008))
- [MRS Basis Set Conversion Toolbox](https://github.com/igweckay/MRS-Basis-Set-Conversion-Toolbox)
- [Custom Basis Set Simulation](https://github.com/arcj-hub/BasisSetSimulation/tree/main)

---

<div align="center">
  <sub>Built with ❤️ for the MRS community</sub>
</div>
