Safely use subjects_dir input to return SUBJECTS_DIR. Parameters ---------- subjects_dir : path-like | None If a value is provided, return subjects_dir. Otherwise, look for SUBJECTS_DIR config and return the result. raise_error : bool If True, raise a KeyErro
(subjects_dir=None, raise_error=False)
| 523 | |
| 524 | |
| 525 | def get_subjects_dir(subjects_dir=None, raise_error=False): |
| 526 | """Safely use subjects_dir input to return SUBJECTS_DIR. |
| 527 | |
| 528 | Parameters |
| 529 | ---------- |
| 530 | subjects_dir : path-like | None |
| 531 | If a value is provided, return subjects_dir. Otherwise, look for |
| 532 | SUBJECTS_DIR config and return the result. |
| 533 | raise_error : bool |
| 534 | If True, raise a KeyError if no value for SUBJECTS_DIR can be found |
| 535 | (instead of returning None). |
| 536 | |
| 537 | Returns |
| 538 | ------- |
| 539 | value : Path | None |
| 540 | The SUBJECTS_DIR value. |
| 541 | """ |
| 542 | from_config = False |
| 543 | if subjects_dir is None: |
| 544 | subjects_dir = get_config("SUBJECTS_DIR", raise_error=raise_error) |
| 545 | from_config = True |
| 546 | if subjects_dir is not None: |
| 547 | subjects_dir = Path(subjects_dir) |
| 548 | if subjects_dir is not None: |
| 549 | # Emit a nice error or warning if their config is bad |
| 550 | try: |
| 551 | subjects_dir = _check_fname( |
| 552 | fname=subjects_dir, |
| 553 | overwrite="read", |
| 554 | must_exist=True, |
| 555 | need_dir=True, |
| 556 | name="subjects_dir", |
| 557 | ) |
| 558 | except FileNotFoundError: |
| 559 | if from_config: |
| 560 | msg = ( |
| 561 | "SUBJECTS_DIR in your MNE-Python configuration or environment " |
| 562 | "does not exist, consider using mne.set_config to fix it: " |
| 563 | f"{subjects_dir}" |
| 564 | ) |
| 565 | if raise_error: |
| 566 | raise FileNotFoundError(msg) from None |
| 567 | else: |
| 568 | warn(msg) |
| 569 | elif raise_error: |
| 570 | raise |
| 571 | |
| 572 | return subjects_dir |
| 573 | |
| 574 | |
| 575 | @fill_doc |