Skip to content

EFieldAccessor

simnibs_reader.efield.accessor.EFieldAccessor

Lazy wrapper around a NIfTI e-field image on disk.

Parameters:

Name Type Description Default
path str or Path

Path to the .nii.gz file.

 required
Source code in simnibs_reader/efield/accessor.py 
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
class EFieldAccessor:
    """Lazy wrapper around a NIfTI e-field image on disk.

    Parameters
    ----------
    path : str or Path
        Path to the ``.nii.gz`` file.
    """

    def __init__(self, path: str | Path) -> None:
        self.path = Path(path)
        if not self.path.exists():
            raise FileNotFoundError(f"NIfTI file not found: {self.path}")

    # ------------------------------------------------------------------
    # Lazy-loaded image
    # ------------------------------------------------------------------

    @cached_property
    def img(self) -> nib.Nifti1Image:
        """Full nibabel image (loaded once, then cached)."""
        return nib.load(str(self.path))

    @cached_property
    def data(self) -> np.ndarray:
        """Volume data as ``float32`` array."""
        return self.img.get_fdata(dtype=np.float32)

    @property
    def affine(self) -> np.ndarray:
        """4 x 4 affine matrix (voxel → world)."""
        return self.img.affine

    @property
    def shape(self) -> tuple[int, ...]:
        """Shape of the data array."""
        return self.img.shape

    # ------------------------------------------------------------------
    # ROI extraction shortcut
    # ------------------------------------------------------------------

    def get_roi(
        self,
        mask: str | Path | None = None,
        coords: list[float] | None = None,
        radius: float = 10.0,
        atlas: str | None = None,
        region: str | list[str] | None = None,
    ) -> "ROIResult":  # noqa: F821 — forward ref resolved at runtime
        """Extract e-field values within a region of interest.

        Three mutually-exclusive methods:

        1. **mask** — path to an existing binary NIfTI mask.
        2. **coords** + **radius** — spherical ROI in MNI/subject space.
        3. **atlas** + **region** — atlas-based parcel mask.

        Returns
        -------
        ROIResult
            Object holding the extracted 1-D values, the mask image,
            and convenience methods (``.stats()``, ``.postprocess()``,
            ``.save()``, ``.save_nifti()``).
        """
        from .roi import ROIExtractor

        return ROIExtractor(self).extract(
            mask=mask, coords=coords, radius=radius, atlas=atlas, region=region,
        )

    # ------------------------------------------------------------------
    # Dunder
    # ------------------------------------------------------------------

    def __repr__(self) -> str:
        return f"EFieldAccessor('{self.path.name}')"

img cached property

Full nibabel image (loaded once, then cached).

data cached property

Volume data as float32 array.

affine property

4 x 4 affine matrix (voxel → world).

shape property

Shape of the data array.

get_roi(mask=None, coords=None, radius=10.0, atlas=None, region=None)

Extract e-field values within a region of interest.

Three mutually-exclusive methods:

  1. mask — path to an existing binary NIfTI mask.
  2. coords + radius — spherical ROI in MNI/subject space.
  3. atlas + region — atlas-based parcel mask.

Returns:

Type Description
ROIResult

Object holding the extracted 1-D values, the mask image, and convenience methods (.stats(), .postprocess(), .save(), .save_nifti()).
Source code in simnibs_reader/efield/accessor.py 
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
def get_roi(
    self,
    mask: str | Path | None = None,
    coords: list[float] | None = None,
    radius: float = 10.0,
    atlas: str | None = None,
    region: str | list[str] | None = None,
) -> "ROIResult":  # noqa: F821 — forward ref resolved at runtime
    """Extract e-field values within a region of interest.

    Three mutually-exclusive methods:

    1. **mask** — path to an existing binary NIfTI mask.
    2. **coords** + **radius** — spherical ROI in MNI/subject space.
    3. **atlas** + **region** — atlas-based parcel mask.

    Returns
    -------
    ROIResult
        Object holding the extracted 1-D values, the mask image,
        and convenience methods (``.stats()``, ``.postprocess()``,
        ``.save()``, ``.save_nifti()``).
    """
    from .roi import ROIExtractor

    return ROIExtractor(self).extract(
        mask=mask, coords=coords, radius=radius, atlas=atlas, region=region,
    )