Split a Label into two or more parts. Parameters ---------- label : Label | str Label which is to be split (Label object or path to a label file). parts : int >= 2 | tuple of str A sequence of strings specifying label names for the new labels (from posterior
(label, parts=2, subject=None, subjects_dir=None, freesurfer=False)
| 1321 | |
| 1322 | @fill_doc |
| 1323 | def split_label(label, parts=2, subject=None, subjects_dir=None, freesurfer=False): |
| 1324 | """Split a Label into two or more parts. |
| 1325 | |
| 1326 | Parameters |
| 1327 | ---------- |
| 1328 | label : Label | str |
| 1329 | Label which is to be split (Label object or path to a label file). |
| 1330 | parts : int >= 2 | tuple of str |
| 1331 | A sequence of strings specifying label names for the new labels (from |
| 1332 | posterior to anterior), or the number of new labels to create (default |
| 1333 | is 2). If a number is specified, names of the new labels will be the |
| 1334 | input label's name with div1, div2 etc. appended. |
| 1335 | %(subject_label)s |
| 1336 | %(subjects_dir)s |
| 1337 | freesurfer : bool |
| 1338 | By default (``False``) ``split_label`` uses an algorithm that is |
| 1339 | slightly optimized for performance and numerical precision. Set |
| 1340 | ``freesurfer`` to ``True`` in order to replicate label splits from |
| 1341 | FreeSurfer's ``mris_divide_parcellation``. |
| 1342 | |
| 1343 | Returns |
| 1344 | ------- |
| 1345 | labels : list of Label, shape (n_parts,) |
| 1346 | The labels, starting from the lowest to the highest end of the |
| 1347 | projection axis. |
| 1348 | |
| 1349 | Notes |
| 1350 | ----- |
| 1351 | Works by finding the label's principal eigen-axis on the spherical surface, |
| 1352 | projecting all label vertex coordinates onto this axis and dividing them at |
| 1353 | regular spatial intervals. |
| 1354 | """ |
| 1355 | label, subject, subjects_dir = _prep_label_split(label, subject, subjects_dir) |
| 1356 | |
| 1357 | # find the parts |
| 1358 | if np.isscalar(parts): |
| 1359 | n_parts = int(parts) |
| 1360 | if label.name.endswith(("lh", "rh")): |
| 1361 | basename = label.name[:-3] |
| 1362 | name_ext = label.name[-3:] |
| 1363 | else: |
| 1364 | basename = label.name |
| 1365 | name_ext = "" |
| 1366 | name_pattern = f"{basename}_div%i{name_ext}" |
| 1367 | names = tuple(name_pattern % i for i in range(1, n_parts + 1)) |
| 1368 | else: |
| 1369 | names = parts |
| 1370 | n_parts = len(names) |
| 1371 | |
| 1372 | if n_parts < 2: |
| 1373 | raise ValueError(f"Can't split label into {n_parts} parts.") |
| 1374 | |
| 1375 | # find the spherical surface |
| 1376 | surf_fname = ".".join((label.hemi, "sphere")) |
| 1377 | surf_path = op.join(subjects_dir, subject, "surf", surf_fname) |
| 1378 | surface_points, surface_tris = read_surface(surf_path) |
| 1379 | # find the label coordinates on the surface |
| 1380 | points = surface_points[label.vertices] |