lcmodel-wrapper 0.3.0__tar.gz → 0.3.1__tar.gz

{lcmodel_wrapper-0.3.0 → lcmodel_wrapper-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lcmodel_wrapper
-Version: 0.3.0
+Version: 0.3.1
 Summary: Lightweight Python wrapper for LCModel MRS fitting
 Author-email: Julian Merkofer <j.p.merkofer@tue.nl>
 License: Apache-2.0
@@ -66,39 +66,21 @@ example data used by the tests.
 
 ## 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:
+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. an explicit `path2exec="/path/to/lcmodel"` you pass to `PyLCModel`,
-2. a previously cached download/build (under `~/.cache/lcmodel_wrapper/<os>-<arch>/`, or `%LOCALAPPDATA%` on Windows; override the root with `LCMODEL_CACHE_DIR`),
-3. a download of the matching binary for your OS/architecture from [schorschinho/LCModel](https://github.com/schorschinho/LCModel),
-4. a download of the binary built by this repository's CI and attached to the [GitHub release](https://github.com/julianmer/PyLCModel/releases) matching the installed package version (Linux x86_64/aarch64 fully static, macOS arm64/x86_64 with libgfortran linked statically; each verified against its published SHA-256),
-5. **a container** — if `docker` (or `podman`) is installed and running, the image `ghcr.io/julianmer/lcmodel` is pulled and a small launcher script is cached that runs LCModel from it (Linux, macOS, and Windows),
-6. a build from the LCModel Fortran source via `gfortran` (source fetched on demand).
+1. `path2exec` you pass to `PyLCModel`,
+2. the community binary for your OS/architecture from [schorschinho/LCModel](https://github.com/schorschinho/LCModel),
+3. the binary built by this repository's CI for the installed version ([releases](https://github.com/julianmer/PyLCModel/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`.
 
-Every candidate is **run once before it is accepted** — LCModel is asked to identify itself, and anything that cannot execute or does not answer is moved to `<cache>/quarantine/` so the next source gets a turn. This is what stops a wrong-architecture download from being cached and served forever. Set `LCMODEL_SKIP_VERIFY=1` to bypass the check, or `LCMODEL_VERIFY_TIMEOUT` to change its 60 s bound.
+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.
 
-The cache is keyed by architecture, so a home directory shared across a mixed-architecture cluster does not have nodes fighting over one file.
-
-### Running from a container
-
-The container is the one option that behaves identically everywhere: inside it LCModel is always the same statically linked Linux binary, so nothing depends on your macOS version, Homebrew, or which Apple-silicon generation you have (upstream's macOS builds are tied to the machine they were compiled on, which is why an M1 build does not run on an M4). Docker Desktop, OrbStack, Colima, or rootless podman all work.
-
-On Linux and macOS the launcher bind-mounts your **working directory** and your **home directory** at the same paths inside the container, so the absolute paths in the control file need no translation. On Windows it mounts the **drives** holding those two at `/host/<LETTER>` and the wrapper rewrites the file paths in the control file to match (`C:\Users\me\x.basis` → `/host/C/Users/me/x.basis`); UNC paths are not supported. The one constraint: the basis set and any absolute `save_path` must live under the working or home directory (on Windows: on one of their drives); `PyLCModel` raises a clear error otherwise.
-
-```python
-lcmodel = PyLCModel(path2basis="~/basis/press_3t.basis")        # container used automatically if needed
-lcmodel = PyLCModel(path2basis="...", allow_docker=False)        # never use a container
-```
-
-Environment knobs: `LCMODEL_NO_DOCKER=1` disables the rung, `LCMODEL_DOCKER_IMAGE` overrides the image (e.g. a locally built one), `LCMODEL_PULL_TIMEOUT` bounds the pull (default 900 s), and `LCMODEL_RELEASE_TAG` selects which release (and matching image tag) steps 4 and 5 use instead of the default `v<package version>`. Delete `<cache>/lcmodel-container` to make the resolver try the native sources again.
-
-You can also use the image directly, without Python:
+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:
 ```bash
-docker run --rm -i -v "$PWD:$PWD" -w "$PWD" ghcr.io/julianmer/lcmodel:latest < control.file
+docker run --rm -i -v "$PWD:$PWD" -w "$PWD" ghcr.io/julianmer/lcmodel < control.file
 ```
 
-No LCModel code or binary is bundled — keeping both the repository and the PyPI wheel small. (The only git submodule in this repository is the optional example data under `example_data/`.)
-
 ---
 
 ## Getting Started

{lcmodel_wrapper-0.3.0 → lcmodel_wrapper-0.3.1}/README.md

@@ -43,39 +43,21 @@ example data used by the tests.
 
 ## 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:
+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. an explicit `path2exec="/path/to/lcmodel"` you pass to `PyLCModel`,
-2. a previously cached download/build (under `~/.cache/lcmodel_wrapper/<os>-<arch>/`, or `%LOCALAPPDATA%` on Windows; override the root with `LCMODEL_CACHE_DIR`),
-3. a download of the matching binary for your OS/architecture from [schorschinho/LCModel](https://github.com/schorschinho/LCModel),
-4. a download of the binary built by this repository's CI and attached to the [GitHub release](https://github.com/julianmer/PyLCModel/releases) matching the installed package version (Linux x86_64/aarch64 fully static, macOS arm64/x86_64 with libgfortran linked statically; each verified against its published SHA-256),
-5. **a container** — if `docker` (or `podman`) is installed and running, the image `ghcr.io/julianmer/lcmodel` is pulled and a small launcher script is cached that runs LCModel from it (Linux, macOS, and Windows),
-6. a build from the LCModel Fortran source via `gfortran` (source fetched on demand).
+1. `path2exec` you pass to `PyLCModel`,
+2. the community binary for your OS/architecture from [schorschinho/LCModel](https://github.com/schorschinho/LCModel),
+3. the binary built by this repository's CI for the installed version ([releases](https://github.com/julianmer/PyLCModel/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`.
 
-Every candidate is **run once before it is accepted** — LCModel is asked to identify itself, and anything that cannot execute or does not answer is moved to `<cache>/quarantine/` so the next source gets a turn. This is what stops a wrong-architecture download from being cached and served forever. Set `LCMODEL_SKIP_VERIFY=1` to bypass the check, or `LCMODEL_VERIFY_TIMEOUT` to change its 60 s bound.
+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.
 
-The cache is keyed by architecture, so a home directory shared across a mixed-architecture cluster does not have nodes fighting over one file.
-
-### Running from a container
-
-The container is the one option that behaves identically everywhere: inside it LCModel is always the same statically linked Linux binary, so nothing depends on your macOS version, Homebrew, or which Apple-silicon generation you have (upstream's macOS builds are tied to the machine they were compiled on, which is why an M1 build does not run on an M4). Docker Desktop, OrbStack, Colima, or rootless podman all work.
-
-On Linux and macOS the launcher bind-mounts your **working directory** and your **home directory** at the same paths inside the container, so the absolute paths in the control file need no translation. On Windows it mounts the **drives** holding those two at `/host/<LETTER>` and the wrapper rewrites the file paths in the control file to match (`C:\Users\me\x.basis` → `/host/C/Users/me/x.basis`); UNC paths are not supported. The one constraint: the basis set and any absolute `save_path` must live under the working or home directory (on Windows: on one of their drives); `PyLCModel` raises a clear error otherwise.
-
-```python
-lcmodel = PyLCModel(path2basis="~/basis/press_3t.basis")        # container used automatically if needed
-lcmodel = PyLCModel(path2basis="...", allow_docker=False)        # never use a container
-```
-
-Environment knobs: `LCMODEL_NO_DOCKER=1` disables the rung, `LCMODEL_DOCKER_IMAGE` overrides the image (e.g. a locally built one), `LCMODEL_PULL_TIMEOUT` bounds the pull (default 900 s), and `LCMODEL_RELEASE_TAG` selects which release (and matching image tag) steps 4 and 5 use instead of the default `v<package version>`. Delete `<cache>/lcmodel-container` to make the resolver try the native sources again.
-
-You can also use the image directly, without Python:
+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:
 ```bash
-docker run --rm -i -v "$PWD:$PWD" -w "$PWD" ghcr.io/julianmer/lcmodel:latest < control.file
+docker run --rm -i -v "$PWD:$PWD" -w "$PWD" ghcr.io/julianmer/lcmodel < control.file
 ```
 
-No LCModel code or binary is bundled — keeping both the repository and the PyPI wheel small. (The only git submodule in this repository is the optional example data under `example_data/`.)
-
 ---
 
 ## Getting Started

{lcmodel_wrapper-0.3.0 → lcmodel_wrapper-0.3.1}/lcmodel_wrapper/__init__.py

@@ -24,6 +24,7 @@ __all__ = [
     "from_nifti_mrs",
     "load_signals",
     "binaries",
+    "container",
     "io",
     "control",
     "coord",

{lcmodel_wrapper-0.3.0 → lcmodel_wrapper-0.3.1}/lcmodel_wrapper/_version.py

@@ -1,4 +1,4 @@
 # Single source of truth for the package version. pyproject.toml reads it at build time,
 # and binaries.py derives the GitHub release / container image tag ("v<version>") from
 # it, so every wheel pairs with the LCModel artifacts built alongside it.
-__version__ = "0.3.0"
+__version__ = "0.3.1"

{lcmodel_wrapper-0.3.0 → lcmodel_wrapper-0.3.1}/lcmodel_wrapper/basis.py

@@ -77,14 +77,14 @@ def read_basis(path: str) -> LCModelBasis:
     with open(path, "r", errors="ignore") as fh:
         header_lines = []
         for line in fh:
-            header_lines.append(line)
+            if len(header_lines) < 200:        # scalars live near the top
+                header_lines.append(line)
             # "METABO" lines are sparse; keep scanning the whole file for them.
             # Match exactly "METABO =" (not "METABO_CONTAM" / "METABO_SINGLET").
             m = re.match(r"\s*METABO\s*=\s*'(.*?)'", line)
             if m:
                 basis.names.append(m.group(1).strip())
-
-        header = "".join(header_lines[:200])   # scalars live near the top
+        header = "".join(header_lines)
 
     basis.central_freq = _find_scalar(header, "HZPPPM")
     basis.dwell = _find_scalar(header, "BADELT")

{lcmodel_wrapper-0.3.0 → lcmodel_wrapper-0.3.1}/lcmodel_wrapper/binaries.py

@@ -49,9 +49,9 @@ _RAW_BASE = "https://raw.githubusercontent.com/schorschinho/LCModel/main"
 _BINARIES = {
     "linux-x86_64":   ("binaries/linux/lcmodel.xz", "xz", "lcmodel"),
     # Upstream has no aarch64 Linux build yet. The entry is kept so that the moment one
-    # lands the download path starts working with no release on our side; until then the
-    # fetch 404s and resolution falls through to the gfortran build. The directory name
-    # is what "uname -m" reports, matching the path the upstream Makefile derives.
+    # lands it is used with no release on our side; until then the fetch 404s and the
+    # PyLCModel release below covers it. The directory name is what "uname -m" reports,
+    # matching the path the upstream Makefile derives.
     "linux-aarch64":  ("binaries/linux/aarch64/lcmodel.xz", "xz", "lcmodel"),
     "darwin-arm64":   ("binaries/macos/sequoia/m4/lcmodel.zip", "zip", "lcmodel"),
     "darwin-arm64-monterey": ("binaries/macos/monterey/m1/lcmodel.zip", "zip", "lcmodel"),
@@ -508,20 +508,25 @@ def _container_cli() -> Optional[str]:
     return None
 
 
-def _container_ready(cli: str, timeout: float = 30.0) -> Tuple[bool, str]:
-    """Is the engine actually usable - daemon running, socket reachable, permissions ok?"""
+def _engine(cli: str, *args: str, timeout: float) -> Tuple[int, str]:
+    """Run a container-engine command. Returns (exit code, last stderr line); the code
+    is -1 when the command could not run or time out."""
     try:
-        proc = subprocess.run([cli, "info"], stdin=subprocess.DEVNULL,
+        proc = subprocess.run([cli, *args], stdin=subprocess.DEVNULL,
                               stdout=subprocess.DEVNULL, stderr=subprocess.PIPE,
                               timeout=timeout)
     except subprocess.TimeoutExpired:
-        return False, f"'{cli} info' did not answer within {timeout:.0f}s"
+        return -1, f"'{cli} {args[0]}' did not finish within {timeout:.0f}s"
     except OSError as err:
-        return False, f"cannot run '{cli}': {err}"
-    if proc.returncode != 0:
-        lines = (proc.stderr or b"").decode("utf-8", "replace").strip().splitlines()
-        return False, lines[-1] if lines else f"'{cli} info' exited {proc.returncode}"
-    return True, "ok"
+        return -1, f"cannot run '{cli}': {err}"
+    lines = (proc.stderr or b"").decode("utf-8", "replace").strip().splitlines()
+    return proc.returncode, lines[-1] if lines else f"'{cli} {args[0]}' exited {proc.returncode}"
+
+
+def _container_ready(cli: str, timeout: float = 30.0) -> Tuple[bool, str]:
+    """Is the engine actually usable - daemon running, socket reachable, permissions ok?"""
+    code, why = _engine(cli, "info", timeout=timeout)
+    return code == 0, "ok" if code == 0 else why
 
 
 def is_container_shim(path) -> bool:
@@ -563,37 +568,19 @@ def _container_shim(cache: Path) -> Optional[Path]:
         return None
 
     image = _container_image()
-    if not _image_present(cli, image):
+    # already in the local store (pulled earlier, or built by hand): no network needed,
+    # which keeps this rung working offline
+    if _engine(cli, "image", "inspect", image, timeout=30)[0] != 0:
         print(f"[lcmodel_wrapper] Pulling LCModel container image {image}")
-        try:
-            proc = subprocess.run([cli, "pull", image], stdin=subprocess.DEVNULL,
-                                  stdout=subprocess.DEVNULL, stderr=subprocess.PIPE,
-                                  timeout=_PULL_TIMEOUT)
-        except subprocess.TimeoutExpired:
-            print(f"[lcmodel_wrapper] Pulling {image} did not finish within "
-                  f"{_PULL_TIMEOUT:.0f}s (raise LCMODEL_PULL_TIMEOUT to wait longer)")
-            return None
-        if proc.returncode != 0:
-            lines = (proc.stderr or b"").decode("utf-8", "replace").strip().splitlines()
-            print(f"[lcmodel_wrapper] Could not pull {image}: "
-                  f"{lines[-1] if lines else proc.returncode}")
+        code, why = _engine(cli, "pull", image, timeout=_PULL_TIMEOUT)
+        if code != 0:
+            print(f"[lcmodel_wrapper] Could not pull {image}: {why} "
+                  f"(LCMODEL_PULL_TIMEOUT raises the {_PULL_TIMEOUT:.0f}s bound)")
             return None
 
     return _write_shim(cache, cli, image)
 
 
-def _image_present(cli: str, image: str) -> bool:
-    """Already in the local store (pulled earlier, or built by hand)? Then no network
-    is needed, which keeps the container rung working offline."""
-    try:
-        proc = subprocess.run([cli, "image", "inspect", image], stdin=subprocess.DEVNULL,
-                              stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
-                              timeout=30)
-    except (OSError, subprocess.TimeoutExpired):
-        return False
-    return proc.returncode == 0
-
-
 #*********************#
 #   cache management  #
 #*********************#

{lcmodel_wrapper-0.3.0 → lcmodel_wrapper-0.3.1}/lcmodel_wrapper/control.py

@@ -38,6 +38,10 @@ def resolve_ignore(ignore) -> List[str]:
     raise ValueError("ignore must be a list of metabolite names or a preset string.")
 
 
+def _omit_lines(ignore: List[str]) -> List[str]:
+    return [f"nomit={len(ignore)}"] + [f"chomit({i + 1})='{m}'" for i, m in enumerate(ignore)]
+
+
 #*************************#
 #   build a control set   #
 #*************************#
@@ -45,31 +49,25 @@ def build_control(path2basis: str, n_points: int, bandwidth: float, central_freq
                   ppmlim: Tuple[float, float] = (0.5, 4.2), ignore=DEFAULT_IGNORE,
                   dows: bool = False) -> List[str]:
     """Create a default LCModel control file as a list of lines."""
-    ignore = resolve_ignore(ignore)
-    lines = []
-    lines.append("$LCMODL")
-    lines.append(f"nunfil={n_points}")               # data points
-    lines.append(f"deltat={1.0 / bandwidth}")        # dwell time
-    lines.append(f"hzpppm={central_freq}")           # field strength in MHz
-    lines.append(f"ppmst={ppmlim[1]}")
-    lines.append(f"ppmend={ppmlim[0]}")
-
-    lines.append(f"dows={'T' if dows else 'F'}")     # water scaling
-    lines.append("neach=99")                          # plot each metabolite fit
-
-    lines.append(f"filbas='{os.path.abspath(path2basis)}'")
-    lines.append("filraw='example.raw'")
-    lines.append("filps='example.ps'")
-    lines.append("filcoo='example.coord'")
-    lines.append("filh2o='example.h2o'")
-
-    lines.append("lcoord=9")                           # 9 -> write coord file
-    lines.append(f"nomit={len(ignore)}")
-    for i, met in enumerate(ignore):
-        lines.append(f"chomit({i + 1})='{met}'")
-    lines.append("namrel='Cr+PCr'")
-    lines.append("$END")
-    return lines
+    return [
+        "$LCMODL",
+        f"nunfil={n_points}",                 # data points
+        f"deltat={1.0 / bandwidth}",          # dwell time
+        f"hzpppm={central_freq}",             # field strength in MHz
+        f"ppmst={ppmlim[1]}",
+        f"ppmend={ppmlim[0]}",
+        f"dows={'T' if dows else 'F'}",       # water scaling
+        "neach=99",                           # plot each metabolite fit
+        f"filbas='{os.path.abspath(path2basis)}'",
+        "filraw='example.raw'",
+        "filps='example.ps'",
+        "filcoo='example.coord'",
+        "filh2o='example.h2o'",
+        "lcoord=9",                           # 9 -> write coord file
+        *_omit_lines(resolve_ignore(ignore)),
+        "namrel='Cr+PCr'",
+        "$END",
+    ]
 
 
 #**************************#
@@ -80,24 +78,15 @@ def load_control(control_path: str, path2basis: str, ppmlim: Tuple[float, float]
     """Read an existing control file and override basis, ppm limits and ignored metabolites."""
     ignore = resolve_ignore(ignore)
     with open(control_path, "r") as fh:
-        control = fh.read().split("\n")
-
-    for i, line in enumerate(control):
-        if line.startswith("filbas="):
-            control[i] = f"filbas='{os.path.abspath(path2basis)}'"
-
-    for i, line in enumerate(control):
-        if line.startswith("ppmst="):
-            control[i] = f"ppmst={ppmlim[1]}"
-        if line.startswith("ppmend="):
-            control[i] = f"ppmend={ppmlim[0]}"
-
-    for i, line in enumerate(control):
-        if line.startswith("nomit="):
-            control[i] = f"nomit={len(ignore)}"
-            for j, met in enumerate(ignore):
-                control.insert(i + j + 1, f"chomit({j + 1})='{met}'")
-            break
+        control = [line for line in fh.read().splitlines()
+                   if not line.startswith(("chomit(", "nomit="))]
+
+    set_key(control, "filbas", f"'{os.path.abspath(path2basis)}'")
+    set_key(control, "ppmst", ppmlim[1])
+    set_key(control, "ppmend", ppmlim[0])
+    for line in _omit_lines(ignore):
+        key, _, value = line.partition("=")
+        set_key(control, key, value)
     return control
 
 
@@ -105,16 +94,12 @@ def load_control(control_path: str, path2basis: str, ppmlim: Tuple[float, float]
 #   set a key in a control set   #
 #********************************#
 def set_key(control: List[str], key: str, value) -> List[str]:
-    """Set "key=value" in place; append if the key is absent (before "$END")."""
+    """Set "key=value" in place; insert before "$END" (or append) if the key is absent."""
     prefix = f"{key}="
     for i, line in enumerate(control):
         if line.startswith(prefix):
             control[i] = f"{key}={value}"
             return control
-    # insert before $END if present, else append
-    for i, line in enumerate(control):
-        if line.strip() == "$END":
-            control.insert(i, f"{key}={value}")
-            return control
-    control.append(f"{key}={value}")
+    end = next((i for i, line in enumerate(control) if line.strip() == "$END"), len(control))
+    control.insert(end, f"{key}={value}")
     return control

{lcmodel_wrapper-0.3.0 → lcmodel_wrapper-0.3.1}/lcmodel_wrapper/convert.py

@@ -26,8 +26,6 @@ import numpy as np
 from .io import read_jmrui_txt, jmrui_metadata
 
 
-
-
 #*******************#
 #   .basis writer   #
 #*******************#
@@ -85,8 +83,8 @@ class ParsedBasis(NamedTuple):
     echot: Optional[float]
 
 
-def _stack(parsed: ParsedBasis) -> None:
-    """Validate a ParsedBasis in place (consistent, non-empty point counts)."""
+def _validate(parsed: ParsedBasis) -> None:
+    """Consistent, non-empty point counts across all metabolites."""
     if not parsed.fids:
         raise ValueError("No metabolite FIDs were found in the input.")
     n = parsed.fids[0].size
@@ -108,18 +106,17 @@ def _read_jmrui_folder(folder: str) -> ParsedBasis:
         raise ValueError(f"No .txt files found in jMRUI folder: {folder}")
 
     names, fids = [], []
-    dwell = central = echot = None
+    dwell = central = None
     for f in files:
         fid, meta = read_jmrui_txt(os.path.join(folder, f))
         if fid.size == 0:
             continue
-        d, c, e = jmrui_metadata(meta)
+        d, c = jmrui_metadata(meta)
         dwell = dwell if dwell is not None else d
         central = central if central is not None else c
-        echot = echot if echot is not None else e
         names.append(os.path.splitext(f)[0])
         fids.append(fid)
-    return ParsedBasis(names, fids, dwell, central, echot)
+    return ParsedBasis(names, fids, dwell, central, None)
 
 
 #**************************#
@@ -209,10 +206,7 @@ def _mat_attr(struct, *candidates):
 
 
 def _read_mat(path: str) -> ParsedBasis:
-    try:
-        from scipy.io import loadmat
-    except ImportError as exc:   # pragma: no cover
-        raise ImportError("Reading .mat basis sets requires scipy.") from exc
+    from scipy.io import loadmat
     try:
         mat = loadmat(path, squeeze_me=True, struct_as_record=False)
     except NotImplementedError as exc:   # MATLAB v7.3 (HDF5)
@@ -331,7 +325,7 @@ def convert_to_basis(path: str, out_path: Optional[str] = None, fmt: Optional[st
         raise ValueError(f"Unknown basis format '{fmt}'. Choose from {sorted(_READERS)}.")
 
     parsed = _READERS[key](path)
-    _stack(parsed)
+    _validate(parsed)
 
     d = parsed.dwell if parsed.dwell is not None else dwell
     c = parsed.central if parsed.central is not None else central_freq
@@ -361,4 +355,3 @@ def ensure_basis(path: str, out_path: Optional[str] = None, fmt: Optional[str] =
     return convert_to_basis(
         path, out_path=out_path, fmt=fmt, dwell=dwell, central_freq=central_freq
     )
-

lcmodel_wrapper-0.3.1/lcmodel_wrapper/coord.py

@@ -0,0 +1,115 @@
+####################################################################################################
+#                                            coord.py                                              #
+####################################################################################################
+#                                                                                                  #
+# Authors: J. P. Merkofer (j.p.merkofer@tue.nl)                                                    #
+#                                                                                                  #
+# Created: 26/06/26                                                                                #
+#                                                                                                  #
+# Purpose: Parsers for LCModel ".coord" output files: the concentration / CRLB table, basic QC     #
+#          metrics, and the fitted spectral series (data, fit, baseline, ppm axis).                #
+#                                                                                                  #
+####################################################################################################
+
+import re
+
+import numpy as np
+
+_NUMBER = r"[-+]?\d*\.?\d+(?:[eE][-+]?\d+)?"
+
+# One row of the concentration table: "  7.20E-08 166% 3.9E-02 Ala". The columns are
+# fixed-width, so a wide ratio runs straight into the metabolite name ("0.659Cr+PCr");
+# the regex therefore allows no whitespace between the two.
+_CONC_ROW = re.compile(rf"^\s*({_NUMBER})\s+(\d+)%\s+({_NUMBER})\s*(\S+)\s*$")
+
+# Markers that open a block of numbers in the fitted-series part of the file.
+_SERIES = (
+    ("ppm",         re.compile(r"points on ppm-axis = NY")),
+    ("data",        re.compile(r"NY phased data points follow")),
+    ("completeFit", re.compile(r"NY points of the fit to the data follow")),
+    ("baseline",    re.compile(r"NY background values follow")),
+)
+_SERIES_END = re.compile(r"lines in following|^[ ]+[a-zA-Z0-9]+[ ]+Conc\. = [-+.E0-9]+$")
+
+
+#*****************************#
+#   load LCModel coord data   #
+#*****************************#
+def read_coord(path, coord=True, meta=True):
+    """Read an LCModel ".coord" file.
+
+    Returns the concentration table (metabolites, concentrations, %SD/CRLBs, /ref ratios)
+    and/or the misc. QC metrics (FWHM, S/N, shift, phase) depending on "coord"/"meta".
+    """
+    metabs, concs, crlbs, tcr = [], [], [], []
+    fwhm = snr = shift = phase = None
+
+    with open(path, "r") as fh:
+        conc_rows = misc_rows = 0
+        for line in fh:
+            if "lines in following concentration table" in line:
+                conc_rows = int(line.split(" lines")[0])
+            elif conc_rows > 0:
+                conc_rows -= 1
+                if line.split()[:1] == ["Conc."]:   # header row
+                    continue
+                m = _CONC_ROW.match(line)
+                if m is None:
+                    raise ValueError(f"Could not parse concentration row: {line.strip()!r}")
+                concs.append(float(m.group(1)))
+                crlbs.append(int(m.group(2)))
+                tcr.append(float(m.group(3)))
+                metabs.append(m.group(4))
+            elif "lines in following misc. output table" in line:
+                misc_rows = int(line.split(" lines")[0])
+            elif misc_rows > 0:
+                misc_rows -= 1
+                values = line.split()
+                if "FWHM" in values:
+                    fwhm = float(values[2])
+                    snr = float(values[-1].split("=")[-1])
+                elif "shift" in values:
+                    # a negative shift fuses with the "=": "shift =-0.012 ppm"
+                    shift = float(values[2][1:]) if values[3] == "ppm" else float(values[3])
+                elif "Ph" in values:
+                    phase = float(values[1])
+
+    if coord and meta:
+        return metabs, concs, crlbs, tcr, fwhm, snr, shift, phase
+    if coord:
+        return metabs, concs, crlbs, tcr
+    return fwhm, snr, shift, phase
+
+
+#**************************************#
+#   load LCModel fit from coord data   #
+#**************************************#
+def read_fit(path):
+    """Read the fitted spectral series from an LCModel ".coord" file.
+
+    Returns a dict with keys "ppm", "data", "completeFit" and "baseline".
+    Source: https://gist.github.com/alexcraven/3db2c09f14ec489a31df81dc7b5a0f9c
+    """
+    series = {}
+    current, values = None, []
+
+    def flush():
+        if current and values:
+            series[current] = np.array(values)
+
+    with open(path) as fh:
+        for line in fh:
+            new = next((key for key, pat in _SERIES if pat.search(line)), current)
+            if _SERIES_END.search(line):
+                new = None
+            if new != current:
+                flush()
+                current, values = new, []
+            elif current:
+                for token in re.findall(r"[-+.E0-9]+", line):
+                    try:
+                        values.append(float(token))
+                    except ValueError:
+                        pass
+    flush()
+    return series