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) → 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:

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.Surface(name, vertex_range, face_range)

face_range: list[tuple[int, int]]

Alias for field number 2

name: str

Alias for field number 0

vertex_range: list[tuple[int, int]]

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) → None

Main function to generate surfas from the UK Biobank atlas.

Parameters:

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

• all (bool) – 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

• 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.

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 file from the surface mesh representation.

Parameters:

• folder (Path) – Path to the output folde

• name (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

Convert a vtp file to a gmsh mesh file using the surface mesh representation. The surface mesh is coarsened using the gmsh algorithm.

Parameters:

• vtp (Path) – Path to the vtp file

• output (Path) – Path to the output folder

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.

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