Skip to content

Statistics

simnibs_reader.nifti.stats.compute_stats(values)

Descriptive statistics for a 1-D array of e-field values.

NaN and non-finite values are silently ignored.

Parameters:

Name Type Description Default
values ndarray

1-D array (e.g. voxel values inside an ROI).

 required

Returns:

Type Description
dict

Keys: mean, median, std, min, max, p5, p95, n_voxels.
Source code in simnibs_reader/nifti/stats.py 
15
16
17
18
19
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
def compute_stats(values: np.ndarray) -> dict[str, float | int]:
    """Descriptive statistics for a 1-D array of e-field values.

    NaN and non-finite values are silently ignored.

    Parameters
    ----------
    values : np.ndarray
        1-D array (e.g. voxel values inside an ROI).

    Returns
    -------
    dict
        Keys: ``mean``, ``median``, ``std``, ``min``, ``max``,
        ``p5``, ``p95``, ``n_voxels``.
    """
    v = np.asarray(values, dtype=np.float64).ravel()
    v = v[np.isfinite(v)]

    if v.size == 0:
        return {
            "mean": np.nan,
            "median": np.nan,
            "std": np.nan,
            "min": np.nan,
            "max": np.nan,
            "p5": np.nan,
            "p95": np.nan,
            "n_voxels": 0,
        }

    return {
        "mean": float(np.mean(v)),
        "median": float(np.median(v)),
        "std": float(np.std(v)),
        "min": float(np.min(v)),
        "max": float(np.max(v)),
        "p5": float(np.percentile(v, 5)),
        "p95": float(np.percentile(v, 95)),
        "n_voxels": int(v.size),
    }

simnibs_reader.nifti.stats.compute_ratio(intra_values, extra_values, method='mean')

Compute the intra-ROI / extra-ROI e-field ratio.

Parameters:

Name Type Description Default
intra_values ndarray

1-D arrays of e-field values inside and outside the ROI.

 required
extra_values ndarray

1-D arrays of e-field values inside and outside the ROI.

 required
method ('mean', 'median')

Summary statistic used for numerator and denominator.

 "mean"

Returns:

Type Description
float

Ratio. Returns np.nan if method is unsupported or the denominator is near zero.
Source code in simnibs_reader/nifti/stats.py 
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
def compute_ratio(
    intra_values: np.ndarray,
    extra_values: np.ndarray,
    method: str = "mean",
) -> float:
    """Compute the intra-ROI / extra-ROI e-field ratio.

    Parameters
    ----------
    intra_values, extra_values : np.ndarray
        1-D arrays of e-field values inside and outside the ROI.
    method : {"mean", "median"}
        Summary statistic used for numerator and denominator.

    Returns
    -------
    float
        Ratio.  Returns ``np.nan`` if *method* is unsupported or
        the denominator is near zero.
    """
    intra = np.asarray(intra_values, dtype=np.float64).ravel()
    extra = np.asarray(extra_values, dtype=np.float64).ravel()
    intra = intra[np.isfinite(intra)]
    extra = extra[np.isfinite(extra)]

    _agg = {"mean": np.mean, "median": np.median}
    fn = _agg.get(method)
    if fn is None:
        return np.nan

    num = float(fn(intra)) if intra.size > 0 else 0.0
    den = float(fn(extra)) if extra.size > 0 else 0.0

    if abs(den) < 1e-10:
        den = 1e-10
    return num / den