UKB-Atlas

class ukb.atlas.AtlasFile(*args, **kwargs)

class ukb.atlas.Points(ED, ES)

ED: ndarray

Alias for field number 0

ES: ndarray

Alias for field number 1

ukb.atlas.compute_S(hdf: AtlasFile | File, mode: int = -1, std: float = 1.5, score: ndarray | None = None) → ndarray

Compute the shape matrix S from the PCA atlas.

Parameters:

• hdf (h5py.File) – HDF5 file containing the PCA atlas.

• 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

• score (np.ndarray | None, optional) – PCA scores to generate points from. If None, use the mode and std parameters to generate points. By default None

Returns:

Shape matrix S.

Return type:

np.ndarray

ukb.atlas.download_atlas(outdir: Path, all: bool = False) → 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 to the downloaded file.

Return type:

Path

References

[1] (1,2)

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.

ukb.atlas.generate_points(filename: Path, mode: int = -1, std: float = 1.5, score: ndarray | None = None) → 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

• score (np.ndarray | None, optional) – PCA scores to generate points from. If None, use the mode and std parameters to generate points. By default None

Returns:

Named tuple containing the end-diastolic (ED) and end-systolic (ES) points.

Return type:

Points

ukb.atlas.generate_points_burns(filename: Path, mode: int = -1, std: float = 1.5, score: ndarray | None = None) → Points

Generate points from the Burns atlas.

Parameters:

• filename (Path) – Path to the Burns 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

• score (np.ndarray | None, optional) – PCA scores to generate points from. If None, use the mode and std parameters to generate points. By default None

Returns:

Named tuple containing the end-diastolic (ED) and end-systolic (ES) points.

Return type:

Points

class ukb.surface.Recipe(surfaces: dict[str, tuple[str, ...]], volumes: dict[str, tuple[str, ...]])

A geometry made of template regions.

Parameters:

• surfaces (dict[str, tuple[str, ...]]) – Physical surface name -> template regions it is made of

• volumes (dict[str, tuple[str, ...]]) – Physical volume name -> names of the surfaces enclosing it

surfaces: dict[str, tuple[str, ...]]

Alias for field number 0

volumes: dict[str, tuple[str, ...]]

Alias for field number 1

ukb.surface.main(folder: Path, all: bool = False, mode: int = -1, std: float = 1.5, verbose: bool = False, cache_dir: Path = PosixPath('/github/home/.ukb'), case: Literal['ED', 'ES', 'both'] = 'ED', burns_path: Path | None = None, custom_points: Points | None = None, score: ndarray | None = None, geometry: str = 'biv') → None

Main function to generate surfas from the UK Biobank atlas.

Parameters:

• folder (Path) – Directory to save the generated points.

• all (bool) – Use the PCA atlas derived from all 4,329 subjects from the UK Biobank Study. This is not supported and raises a NotImplementedError. If false (default), use the PCA atlas derived from 630 healthy reference subjects from the UK Biobank Study (see [1])

• mode (int) – 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) – Standard deviation to scale the mode by, by default 1.5

• verbose (bool) – If true, print verbose output.

• cache_dir (Path) – Directory to save the downloaded atlas.

• case (str) – Case to generate surfaces for.

• burns_path (Path | None) – Path to the burns atlas file. This will be a .mat file which will be loaded using scipy.io.loadmat.

• custom_points (atlas.Points | None) – If not None, use these points instead of generating points from the atlas.

• score (np.ndarray | None) – If not None, use these scores to generate points from the atlas instead of using the mode and std parameters. This will override the mode and std parameters if provided.

• geometry (str) – Name of the geometry (see RECIPES) to generate surfaces for, by default “biv”

ukb.surface.read_manifest(folder: Path, case: str) → tuple[dict[str, list[Path]], dict[str, list[str]]]

Return the surface files and volumes for the given case.

Returns:

• files (dict[str, list[Path]]) – Surface name -> files the surface is made of

• volumes (dict[str, list[str]]) – Volume name -> names of the surfaces enclosing it

Raises:

FileNotFoundError – If no surfaces were generated for this case in folder

ukb.surface.write_manifest(folder: Path, geometry: str, volumes: dict[str, tuple[str, ...]], files: dict[str, dict[str, list[str]]]) → None

Record the volumes of the geometry and which files make up each surface, for each case.

Cases from an earlier run with the same geometry are kept, so that ED and ES can be generated by separate calls.

ukb.mesh.add_parser_arguments(parser: ArgumentParser) → None

Add parser arguments for mesh generation.

Parameters:

parser (ArgumentParser) – The argument parser to add arguments to.

ukb.mesh.create_clipped_mesh(folder: Path, case: Literal['ED', 'ES', 'both'] = 'ED', char_length_max: float = 5.0, char_length_min: float = 5.0, verbose: bool = False) → None

Create a gmsh mesh from the clipped surfaces written by ukb-atlas clip.

Parameters:

• folder (Path) – Path to the output folder

• case (str) – Case name

• char_length_max (float) – Maximum characteristic length of the mesh elements

• char_length_min (float) – Minimum characteristic length of the mesh elements

• verbose (bool, optional) – Print verbose output, by default False

ukb.mesh.create_mesh_geo(folder: Path, char_length_max: float, char_length_min: float, case: Literal['ED', 'ES', 'both'] = 'ED') → None

Create a mesh by writing a .geo file and running the gmsh binary.

Parameters:

• folder (Path) – Folder with the surfaces generated by ukb-atlas surf

• char_length_max (float) – Maximum characteristic length of the mesh elements

• char_length_min (float) – Minimum characteristic length of the mesh elements

• case (str) – Case name, by default “ED”

ukb.mesh.find_gmsh() → tuple[str, str] | None

Return the path of a working gmsh binary and the output of gmsh -info.

Returns None if there is no gmsh on the PATH or it cannot be run (e.g. the launcher script installed by the gmsh wheel on Windows).

ukb.mesh.geo_script(files: dict[str, list[Path]], volumes: dict[str, list[str]], char_length_max: float, char_length_min: float, netgen: bool = True) → str

Return a gmsh .geo script that meshes the volumes enclosed by files.

Each merged file becomes one surface whose tag is its (1-based) merge position, which is used for the volumes and the physical groups. The Netgen optimizer is only enabled if netgen is true.

ukb.mesh.main(folder: Path, case: Literal['ED', 'ES', 'both'] = 'ED', char_length_max: float = 5.0, char_length_min: float = 5.0, verbose: bool = False, clipped: bool = False) → None

Create a gmsh mesh file from the surface mesh representation.

The surfaces listed for case in the manifest written by ukb-atlas surf are merged, and each becomes a physical surface with the same name. The enclosed volume is the physical volume “Wall”.

Parameters:

• folder (Path) – Path to the output folder

• case (str) – Case name, by default “ED”

• char_length_max (float) – Maximum characteristic length of the mesh elements, by default 5.0

• char_length_min (float) – Minimum characteristic length of the mesh elements, by default 5.0

• verbose (bool, optional) – Print verbose output, by default False

• clipped (bool, optional) – Create a clipped mesh, by default False

ukb.mesh.with_retries(create: Callable[[], None]) → None

Call create until it succeeds, at most MAX_ATTEMPTS times.