ukb-atlas 0.1.0__tar.gz

ukb_atlas-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Computational Physiology at Simula Research Laboratory
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ukb_atlas-0.1.0/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.1
+Name: ukb_atlas
+Version: 0.1.0
+Summary: Generate meshes from UK Biobank data
+Author-email: Henrik Finsberg <henriknf@simula.no>
+License: MIT License
+        
+        Copyright (c) 2024 Computational Physiology at Simula Research Laboratory
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: h5py
+Requires-Dist: meshio
+Requires-Dist: numpy
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Provides-Extra: dev
+Requires-Dist: bump-my-version; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: jupyter-book; extra == "docs"
+Requires-Dist: jupytext; extra == "docs"
+Requires-Dist: jupyter; extra == "docs"
+Requires-Dist: pyvista[all]>=0.43.0; extra == "docs"
+Requires-Dist: trame-vuetify; extra == "docs"
+Requires-Dist: ipywidgets; extra == "docs"
+
+[![DOI](https://zenodo.org/badge/846706235.svg)](https://doi.org/10.5281/zenodo.13927883)
+
+# UK Biobank atlas - mesh generation
+
+Generate meshes using the UK Biobank atlas (https://www.cardiacatlas.org/biventricular-modes/)
+
+## Install
+Install with `pip`
+```
+python3 -m pip install git+https://github.com/ComputationalPhysiology/ukb-atlas
+```
+or with [`pipx`](https://github.com/pypa/pipx)
+```
+pipx install git+https://github.com/ComputationalPhysiology/ukb-atlas.git
+```
+
+## Usage
+```
+$ ukb-atlas --help
+usage: ukb-atlas [-h] [-a] [-m MODE] [-s STD] [--mesh] [--char_length_max CHAR_LENGTH_MAX] [--char_length_min CHAR_LENGTH_MIN] outdir
+
+Generate surfaces and meshes from UK Biobank atlas.
+
+positional arguments:
+  outdir                Directory to save the generated surfaces and meshes.
+
+options:
+  -h, --help            show this help message and exit
+  -a, --all             Download the PCA atlas derived from all 4,329 subjects from the UK Biobank Study.
+  -m MODE, --mode MODE  Mode to generate points from. If -1, generate points from the mean shape. If between 0 and the number of modes, generate points from the
+                        specified mode. By default -1
+  -s STD, --std STD     Standard deviation to scale the mode by, by default 1.5
+  --mesh                Create gmsh mesh files from the generated surfaces.
+  --char_length_max CHAR_LENGTH_MAX
+                        Maximum characteristic length of the mesh elements.
+  --char_length_min CHAR_LENGTH_MIN
+                        Minimum characteristic length of the mesh elements.
+```
+For example, by running the following command
+```
+ukb-atlas data --mesh
+```
+The tool will generate the following files
+```
+data
+├── AV_ED.stl
+├── AV_ES.stl
+├── ED.msh
+├── EPI_ED.stl
+├── EPI_ES.stl
+├── ES.msh
+├── LV_ED.stl
+├── LV_ES.stl
+├── MV_ED.stl
+├── MV_ES.stl
+├── PV_ED.stl
+├── PV_ES.stl
+├── RVFW_ED.stl
+├── RVFW_ES.stl
+├── RV_ED.stl
+├── RV_ES.stl
+├── TV_ED.stl
+├── TV_ES.stl
+├── UKBRVLV.h5
+└── parameters.json
+```
+Which are surfaces for both the end diastolic (ED) and the end systolic (ES) shapes, the PCA atlas (`UKBRVLV.h5`) and the parameters used to generate the surfaces.
+
+## Citing
+If you use this tool to create meshes please cite
+```
+@software{Finsberg_fenics-beat_2024,
+author = {Henrik Finsberg and Lisa R Pankewitz},
+doi = {10.5281/zenodo.13927883},
+title = {UK Biobank atlas - mesh generation},
+url = {https://github.com/ComputationalPhysiology/ukb-atlas},
+version = {0.1.0},
+year = {2024}
+}
+```
+
+The templates used to generate the meshes are described where developed as part of the following publication (so please cite this paper if you use the templates)
+```
+@article{PANKEWITZ2024103091,
+title = {A universal biventricular coordinate system incorporating valve annuli: Validation in congenital heart disease},
+journal = {Medical Image Analysis},
+volume = {93},
+pages = {103091},
+year = {2024},
+issn = {1361-8415},
+doi = {https://doi.org/10.1016/j.media.2024.103091},
+url = {https://www.sciencedirect.com/science/article/pii/S1361841524000161},
+author = {Lisa R Pankewitz and Kristian G Hustad and Sachin Govil and James C Perry and Sanjeet Hegde and Renxiang Tang and Jeffrey H Omens and Alistair A Young and Andrew D McCulloch and Hermenegild J Arevalo},
+keywords = {Cardiac geometry, Coordinates, Congenital Heart Disease, Mapping},
+}
+```
+
+## License
+MIT

ukb_atlas-0.1.0/README.md

@@ -0,0 +1,99 @@
+[![DOI](https://zenodo.org/badge/846706235.svg)](https://doi.org/10.5281/zenodo.13927883)
+
+# UK Biobank atlas - mesh generation
+
+Generate meshes using the UK Biobank atlas (https://www.cardiacatlas.org/biventricular-modes/)
+
+## Install
+Install with `pip`
+```
+python3 -m pip install git+https://github.com/ComputationalPhysiology/ukb-atlas
+```
+or with [`pipx`](https://github.com/pypa/pipx)
+```
+pipx install git+https://github.com/ComputationalPhysiology/ukb-atlas.git
+```
+
+## Usage
+```
+$ ukb-atlas --help
+usage: ukb-atlas [-h] [-a] [-m MODE] [-s STD] [--mesh] [--char_length_max CHAR_LENGTH_MAX] [--char_length_min CHAR_LENGTH_MIN] outdir
+
+Generate surfaces and meshes from UK Biobank atlas.
+
+positional arguments:
+  outdir                Directory to save the generated surfaces and meshes.
+
+options:
+  -h, --help            show this help message and exit
+  -a, --all             Download the PCA atlas derived from all 4,329 subjects from the UK Biobank Study.
+  -m MODE, --mode MODE  Mode to generate points from. If -1, generate points from the mean shape. If between 0 and the number of modes, generate points from the
+                        specified mode. By default -1
+  -s STD, --std STD     Standard deviation to scale the mode by, by default 1.5
+  --mesh                Create gmsh mesh files from the generated surfaces.
+  --char_length_max CHAR_LENGTH_MAX
+                        Maximum characteristic length of the mesh elements.
+  --char_length_min CHAR_LENGTH_MIN
+                        Minimum characteristic length of the mesh elements.
+```
+For example, by running the following command
+```
+ukb-atlas data --mesh
+```
+The tool will generate the following files
+```
+data
+├── AV_ED.stl
+├── AV_ES.stl
+├── ED.msh
+├── EPI_ED.stl
+├── EPI_ES.stl
+├── ES.msh
+├── LV_ED.stl
+├── LV_ES.stl
+├── MV_ED.stl
+├── MV_ES.stl
+├── PV_ED.stl
+├── PV_ES.stl
+├── RVFW_ED.stl
+├── RVFW_ES.stl
+├── RV_ED.stl
+├── RV_ES.stl
+├── TV_ED.stl
+├── TV_ES.stl
+├── UKBRVLV.h5
+└── parameters.json
+```
+Which are surfaces for both the end diastolic (ED) and the end systolic (ES) shapes, the PCA atlas (`UKBRVLV.h5`) and the parameters used to generate the surfaces.
+
+## Citing
+If you use this tool to create meshes please cite
+```
+@software{Finsberg_fenics-beat_2024,
+author = {Henrik Finsberg and Lisa R Pankewitz},
+doi = {10.5281/zenodo.13927883},
+title = {UK Biobank atlas - mesh generation},
+url = {https://github.com/ComputationalPhysiology/ukb-atlas},
+version = {0.1.0},
+year = {2024}
+}
+```
+
+The templates used to generate the meshes are described where developed as part of the following publication (so please cite this paper if you use the templates)
+```
+@article{PANKEWITZ2024103091,
+title = {A universal biventricular coordinate system incorporating valve annuli: Validation in congenital heart disease},
+journal = {Medical Image Analysis},
+volume = {93},
+pages = {103091},
+year = {2024},
+issn = {1361-8415},
+doi = {https://doi.org/10.1016/j.media.2024.103091},
+url = {https://www.sciencedirect.com/science/article/pii/S1361841524000161},
+author = {Lisa R Pankewitz and Kristian G Hustad and Sachin Govil and James C Perry and Sanjeet Hegde and Renxiang Tang and Jeffrey H Omens and Alistair A Young and Andrew D McCulloch and Hermenegild J Arevalo},
+keywords = {Cardiac geometry, Coordinates, Congenital Heart Disease, Mapping},
+}
+```
+
+## License
+MIT

ukb_atlas-0.1.0/pyproject.toml

@@ -0,0 +1,121 @@
+[build-system] # Require setuptool version due to https://github.com/pypa/setuptools/issues/2938
+requires = ["setuptools>=61.0.0", "wheel"]
+
+[project]
+name = "ukb_atlas"
+version = "0.1.0"
+description = "Generate meshes from UK Biobank data"
+authors = [{name = "Henrik Finsberg", email = "henriknf@simula.no"}]
+license = {file = "LICENSE"}
+requires-python = ">= 3.8"
+readme = "README.md"
+dependencies = [
+    "h5py", "meshio", "numpy"
+]
+
+[project.scripts]
+ukb-atlas = "ukb.cli:main"
+
+[project.optional-dependencies]
+test = [
+    "pytest",
+    "pytest-cov",
+]
+dev = [
+    "bump-my-version",
+    "pre-commit",
+]
+docs = [
+    "jupyter-book",
+    "jupytext",
+    "jupyter",
+    "pyvista[all]>=0.43.0",
+    "trame-vuetify",
+    "ipywidgets",
+]
+
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+ukb = ["connectivity.txt"]
+
+[tool.aliases]
+test = "pytest"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+
+[tool.mypy]
+files = ["src/ukb", "tests"]
+ignore_missing_imports = true
+
+
+[tool.ruff]
+
+# Exclude a variety of commonly ignored directories.
+exclude = [
+    "examples",
+    ".bzr",
+    ".direnv",
+    ".eggs",
+    ".git",
+    ".hg",
+    ".mypy_cache",
+    ".nox",
+    ".pants.d",
+    ".pytype",
+    ".ruff_cache",
+    ".svn",
+    ".tox",
+    ".venv",
+    "__pypackages__",
+    "_build",
+    "buck-out",
+    "build",
+    "dist",
+    "node_modules",
+    "venv",
+]
+
+# Same as Black.
+line-length = 100
+
+# Assume Python 3.10.
+target-version = "py310"
+
+[tool.ruff.lint]
+# Enable pycodestyle (`E`) and Pyflakes (`F`) codes by default.
+select = ["E", "F"]
+ignore = ["E402", "E741", "E743", "E731"]
+
+# Allow autofix for all enabled rules (when `--fix`) is provided.
+fixable = ["A", "B", "C", "D", "E", "F"]
+unfixable = []
+
+# Allow unused variables when underscore-prefixed.
+dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
+
+
+[tool.ruff.lint.mccabe]
+# Unlike Flake8, default to a complexity level of 10.
+max-complexity = 10
+
+
+[tool.bumpversion]
+allow_dirty = false
+commit = true
+message = "Bump version: {current_version} → {new_version}"
+tag = true
+sign_tags = false
+tag_name = "v{new_version}"
+tag_message = "Bump version: {current_version} → {new_version}"
+current_version = "0.1.0"
+
+
+[[tool.bumpversion.files]]
+filename = "pyproject.toml"
+search = 'version = "{current_version}"'
+replace = 'version = "{new_version}"'

ukb_atlas-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ukb_atlas-0.1.0/src/ukb/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ukb_atlas-0.1.0/src/ukb/atlas.py

@@ -0,0 +1,113 @@
+from typing import NamedTuple
+from pathlib import Path
+import logging
+import h5py
+import numpy as np
+
+logger = logging.getLogger(__name__)
+
+
+class Points(NamedTuple):
+    ED: np.ndarray
+    ES: np.ndarray
+
+
+unwanted_nodes = (5630, 5655, 5696, 5729)
+
+
+def download_atlas(outdir: Path, all: bool = True) -> Path:
+    """Download the UK Biobank atlas from the Cardiac Atlas Project.
+
+    Parameters
+    ----------
+    outdir : Path
+        Directory to download the atlas to.
+    all : bool, optional
+        If true, download the PCA atlas derived from all 4,329 subjects
+        from the UK Biobank Study. If false, downlaod PCA atlas derived
+        from 630 healthy reference subjects from the UK Biobank Study
+        (see [1]_) by default False
+
+    Returns
+    -------
+    Path
+        Path to the downloaded file.
+
+    References
+    ----------
+    .. [1] Petersen, Steffen E., et al. "Reference ranges for cardiac
+        structure and function using cardiovascular magnetic resonance
+        (CMR) in Caucasians from the UK Biobank population cohort.
+        " Journal of cardiovascular magnetic resonance 19.1 (2016): 18.
+
+    """
+    from urllib.request import urlretrieve
+    import zipfile
+
+    outdir = Path(outdir)
+    outdir.mkdir(exist_ok=True)
+
+    if all:
+        url = "https://www.cardiacatlas.org/share/download.php?id=59&token=CUfi3eWV41LrIL6ZtlMf7bvHEkiiWpVu&download"
+        path = outdir / "UKBRVLV_ALL.zip"
+    else:
+        url = "https://www.cardiacatlas.org/share/download.php?id=60&token=AR3JSoaxJ9Ev9n8QAkvV4BHJUniyttqm&download"
+
+        path = outdir / "UKBRVLV.zip"
+
+    if not path.with_suffix(".h5").exists():
+        logger.info(f"Downloading {url} to {path}. This may take a while.")
+        urlretrieve(url, path)
+        with zipfile.ZipFile(path, "r") as zip_ref:
+            zip_ref.extractall(outdir)
+        path.unlink()
+
+        logger.info("Done downloading.")
+
+    return path.with_suffix(".h5")
+
+
+def generate_points(filename: Path, mode: int = -1, std: float = 1.5) -> Points:
+    """Generate points from the UK Biobank atlas.
+
+    Parameters
+    ----------
+    filename : Path
+        Path to the UK Biobank atlas file.
+    mode : int, optional
+        Mode to generate points from. If -1, generate points from the mean
+        shape. If between 0 and the number of modes, generate points from
+        the specified mode. By default -1
+    std : float, optional
+        Standard deviation to scale the mode by, by default 1.5
+
+    Returns
+    -------
+    Points
+        Named tuple containing the end-diastolic (ED) and end-systolic (ES)
+        points.
+    """
+    logger.info(f"Generating points from {filename} using mode {mode} and std {std}")
+    with h5py.File(filename, "r") as hdf:
+        mu = np.transpose(hdf["MU"])
+        if mode == -1:
+            S = mu
+        else:
+            if mode < 0 or mode >= hdf["COEFF"].shape[0]:
+                raise ValueError(
+                    f"Mode {mode} is out of bounds. Needs to be between "
+                    f"0 and {hdf['COEFF'].shape[0] - 1}"
+                )
+            eigenvalue = hdf["LATENT"][0, mode]
+            eigenvector = hdf["COEFF"][mode, :]
+            S = np.transpose(hdf["MU"]) + (std * np.sqrt(eigenvalue) * eigenvector)
+
+        # First half is ED and second half is ES
+        N = S.shape[1] // 2
+        ed = np.reshape(S[0, :N], (-1, 3))
+        es = np.reshape(S[0, N:], (-1, 3))
+
+    return Points(
+        ED=np.delete(ed, unwanted_nodes, axis=0),
+        ES=np.delete(es, unwanted_nodes, axis=0),
+    )

ukb_atlas-0.1.0/src/ukb/cli.py

@@ -0,0 +1,133 @@
+from __future__ import annotations
+import typing
+import json
+import hashlib
+from pathlib import Path
+import logging
+import argparse
+
+from . import atlas, surface, mesh
+
+
+def get_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Generate surfaces and meshes from UK Biobank atlas."
+    )
+    parser.add_argument(
+        "outdir",
+        type=Path,
+        help="Directory to save the generated surfaces and meshes.",
+    )
+    parser.add_argument(
+        "--subdir",
+        type=Path,
+        default=None,
+        help="Directory to save the generated surfaces and meshes.",
+    )
+    parser.add_argument(
+        "-a",
+        "--all",
+        action="store_true",
+        help="Download the PCA atlas derived from all 4,329 subjects from the UK Biobank Study.",
+    )
+    parser.add_argument(
+        "-m",
+        "--mode",
+        type=int,
+        default=-1,
+        help=(
+            "Mode to generate points from. If -1, generate points from the mean "
+            "shape. If between 0 and the number of modes, generate points from "
+            "the specified mode. By default -1"
+        ),
+    )
+    parser.add_argument(
+        "-s",
+        "--std",
+        type=float,
+        default=1.5,
+        help="Standard deviation to scale the mode by, by default 1.5",
+    )
+    parser.add_argument(
+        "--mesh",
+        action="store_true",
+        help="Create gmsh mesh files from the generated surfaces.",
+    )
+    parser.add_argument(
+        "--char_length_max",
+        type=float,
+        default=5.0,
+        help="Maximum characteristic length of the mesh elements.",
+    )
+    parser.add_argument(
+        "--char_length_min",
+        type=float,
+        default=5.0,
+        help="Minimum characteristic length of the mesh elements.",
+    )
+    parser.add_argument(
+        "-v",
+        "--verbose",
+        action="store_true",
+        help="Print verbose output.",
+    )
+
+    return parser
+
+
+def main(argv: typing.Sequence[str] | None = None) -> int:
+    parser = get_parser()
+    args = vars(parser.parse_args(argv))
+
+    logging.basicConfig(level=logging.DEBUG if args["verbose"] else logging.INFO)
+
+    main_outdir = args["outdir"]
+    main_outdir.mkdir(exist_ok=True, parents=True)
+
+    args_json = json.dumps(
+        args,
+        indent=4,
+        sort_keys=True,
+        default=lambda o: str(o),
+    )
+
+    if args["subdir"]:
+        outdir = main_outdir / args["subdir"]
+    else:
+        unique_id = hashlib.md5(args_json.encode()).hexdigest()
+        outdir = main_outdir / unique_id
+    outdir.mkdir(exist_ok=True, parents=True)
+
+    (outdir / "parameters.json").write_text(args_json)
+
+    filename = atlas.download_atlas(main_outdir, args["all"])
+
+    points = atlas.generate_points(filename=filename, mode=args["mode"], std=args["std"])
+
+    for case in ["ED", "ES"]:
+        epi = surface.get_epi_mesh(
+            points=getattr(points, case),
+        )
+        epi.write(str(outdir / f"EPI_{case}.stl"))
+
+        for valve in ["MV", "AV", "TV", "PV"]:
+            valve_mesh = surface.get_valve_mesh(surface_name=valve, points=getattr(points, case))
+            valve_mesh.write(str(outdir / f"{valve}_{case}.stl"))
+
+        for chamber in ["LV", "RV", "RVFW"]:
+            chamber_mesh = surface.get_chamber_mesh(
+                surface_name=chamber,
+                points=getattr(points, case),
+            )
+            chamber_mesh.write(str(outdir / f"{chamber}_{case}.stl"))
+
+        if args["mesh"]:
+            mesh.create_mesh(
+                outdir=outdir,
+                char_length_max=args["char_length_max"],
+                char_length_min=args["char_length_min"],
+                case=case,
+                verbose=args["verbose"],
+            )
+
+    return 0