Skip to content

API reference#

earthcarekit.stats

Statistics utilities.

Notes#

This module does not depend on other internal modules.

get_hist_mean #

get_hist_mean(values: ArrayLike, centers: ArrayLike) -> float

Estimate mean from a histogram.

Parameters:

Name Type Description Default
values ArrayLike

Values of the histogram (e.g., counts or density).

 required
centers ArrayLike

Sequence of monotonically increasing bin centers of the histogram (length(values)).

 required

Returns:

Name Type Description
float float

The scalar estimated mean.
Source code in earthcarekit/stats/_histogram.py 
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
def get_hist_mean(
    values: ArrayLike,
    centers: ArrayLike,
) -> float:
    """Estimate mean from a histogram.

    Args:
        values (ArrayLike):
            Values of the histogram (e.g., counts or density).
        centers (ArrayLike):
            Sequence of monotonically increasing bin centers of the histogram (length(`values`)).

    Returns:
        float: The scalar estimated mean.
    """
    return float(np.average(np.asarray(centers), weights=np.asarray(values)))

get_hist_median #

get_hist_median(values: ArrayLike, edges: ArrayLike) -> float

Estimate median from a histogram.

Parameters:

Name Type Description Default
values ArrayLike

Values of the histogram (e.g., counts or density).

 required
edges ArrayLike

Sequence of monotonically increasing bin edges of the histogram (length(values)+1).

 required

Returns:

Name Type Description
float float

The scalar estimated median (i.e., 50-th percentile).
Source code in earthcarekit/stats/_histogram.py 
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
def get_hist_median(
    values: ArrayLike,
    edges: ArrayLike,
) -> float:
    """Estimate median from a histogram.

    Args:
        values (ArrayLike):
            Values of the histogram (e.g., counts or density).
        edges (ArrayLike):
            Sequence of monotonically increasing bin edges of the histogram (length(`values`)+1).

    Returns:
        float: The scalar estimated median (i.e., 50-th percentile).
    """
    return get_hist_percentile(values, edges, 50)

get_hist_percentile #

get_hist_percentile(values: ArrayLike, edges: ArrayLike, q: float) -> float

Estimate q-th percentile from a histogram.

Parameters:

Name Type Description Default
values ArrayLike

Values of the histogram (e.g., counts or density).

 required
edges ArrayLike

Sequence of monotonically increasing bin edges of the histogram (length(values)+1).

 required
q float

Percentage of the percentile to compute (0-100).

 required

Returns:

Name Type Description
float float

The scalar estimated q-th percentile.
Source code in earthcarekit/stats/_histogram.py 
 9
10
11
12
13
14
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
def get_hist_percentile(
    values: ArrayLike,
    edges: ArrayLike,
    q: float,
) -> float:
    """Estimate `q`-th percentile from a histogram.

    Args:
        values (ArrayLike):
            Values of the histogram (e.g., counts or density).
        edges (ArrayLike):
            Sequence of monotonically increasing bin edges of the histogram (length(`values`)+1).
        q (float): Percentage of the percentile to compute (0-100).

    Returns:
        float: The scalar estimated `q`-th percentile.
    """
    edges = np.asarray(edges)
    values = np.asarray(values)

    cum_counts = np.cumsum(values)
    total = cum_counts[-1]
    target = (q * 0.01) * total

    idx = np.searchsorted(cum_counts, target)

    lower = edges[idx]
    upper = edges[idx + 1]
    width = upper - lower

    prev_cum_count = 0 if idx == 0 else cum_counts[idx - 1]
    curr_cum_count = values[idx]

    frac = (target - prev_cum_count) / _nan_if_zero(curr_cum_count)

    return float(lower + frac * width)

nan_diff_of_means #

nan_diff_of_means(predictions: ArrayLike, targets: ArrayLike) -> float

Difference between means of target and prediction (i.e., mean(target) - mean(prediction)).

Source code in earthcarekit/stats/_omitna.py 
83
84
85
86
87
88
89
90
def nan_diff_of_means(predictions: ArrayLike, targets: ArrayLike) -> float:
    """Difference between means of target and prediction (i.e., `mean(target) - mean(prediction)`)."""
    predictions = np.asarray(predictions)
    targets = np.asarray(targets)
    with warnings.catch_warnings():  # ignore warings about all-nan values
        warnings.simplefilter("ignore", category=RuntimeWarning)
        result = np.nanmean(targets) - np.nanmean(predictions)
    return result

nan_mae #

nan_mae(predictions: ArrayLike, targets: ArrayLike) -> float

Mean absolute error (MAE)

Source code in earthcarekit/stats/_omitna.py 
63
64
65
66
67
68
69
70
def nan_mae(predictions: ArrayLike, targets: ArrayLike) -> float:
    """Mean absolute error (MAE)"""
    predictions = np.asarray(predictions)
    targets = np.asarray(targets)
    with warnings.catch_warnings():  # ignore warings about all-nan values
        warnings.simplefilter("ignore", category=RuntimeWarning)
        result = np.nanmean(np.abs(targets - predictions))
    return result

nan_max #

nan_max(a: ArrayLike, axis: int | None = None) -> NDArray | float

Compute the maximum while ignoring NaNs.

Source code in earthcarekit/stats/_omitna.py 
34
35
36
37
38
39
40
41
42
def nan_max(a: ArrayLike, axis: int | None = None) -> NDArray | float:
    """Compute the maximum while ignoring NaNs."""
    with warnings.catch_warnings():  # ignore warings about all-nan values
        warnings.simplefilter("ignore", category=RuntimeWarning)
        a = np.asarray(a)
        if len(a) > 0:
            return np.nanmax(a, axis=axis)
        else:
            return np.nan

nan_mean #

nan_mean(a: ArrayLike, axis: int | None = None) -> NDArray | float

Compute the mean while ignoring NaNs.

Source code in earthcarekit/stats/_omitna.py 
 7
 8
 9
10
11
12
def nan_mean(a: ArrayLike, axis: int | None = None) -> NDArray | float:
    """Compute the mean while ignoring NaNs."""
    with warnings.catch_warnings():  # ignore warings about all-nan values
        warnings.simplefilter("ignore", category=RuntimeWarning)
        a = np.asarray(a)
        return np.nanmean(a, axis=axis)

nan_mean_diff #

nan_mean_diff(predictions: ArrayLike, targets: ArrayLike) -> float

Mean of element-wise differences (i.e., mean(target - prediction)).

Source code in earthcarekit/stats/_omitna.py 
73
74
75
76
77
78
79
80
def nan_mean_diff(predictions: ArrayLike, targets: ArrayLike) -> float:
    """Mean of element-wise differences (i.e., `mean(target - prediction)`)."""
    predictions = np.asarray(predictions)
    targets = np.asarray(targets)
    with warnings.catch_warnings():  # ignore warings about all-nan values
        warnings.simplefilter("ignore", category=RuntimeWarning)
        result = np.nanmean(targets - predictions)
    return result

nan_min #

nan_min(a: ArrayLike, axis: int | None = None) -> NDArray | float

Compute the minimum while ignoring NaNs.

Source code in earthcarekit/stats/_omitna.py 
23
24
25
26
27
28
29
30
31
def nan_min(a: ArrayLike, axis: int | None = None) -> NDArray | float:
    """Compute the minimum while ignoring NaNs."""
    with warnings.catch_warnings():  # ignore warings about all-nan values
        warnings.simplefilter("ignore", category=RuntimeWarning)
        a = np.asarray(a)
        if len(a) > 0:
            return np.nanmin(a, axis=axis)
        else:
            return np.nan

nan_rmse #

nan_rmse(predictions: ArrayLike, targets: ArrayLike) -> float

Root mean squared error (RMSE)

Source code in earthcarekit/stats/_omitna.py 
53
54
55
56
57
58
59
60
def nan_rmse(predictions: ArrayLike, targets: ArrayLike) -> float:
    """Root mean squared error (RMSE)"""
    predictions = np.asarray(predictions)
    targets = np.asarray(targets)
    with warnings.catch_warnings():  # ignore warings about all-nan values
        warnings.simplefilter("ignore", category=RuntimeWarning)
        result = np.sqrt(np.nanmean((targets - predictions) ** 2))
    return result

nan_sem #

nan_sem(a: ArrayLike, axis: int | None = None) -> NDArray | float

Compute the standard error of the mean while ignoring NaNs.

Source code in earthcarekit/stats/_omitna.py 
45
46
47
48
49
50
def nan_sem(a: ArrayLike, axis: int | None = None) -> NDArray | float:
    """Compute the standard error of the mean while ignoring NaNs."""
    with warnings.catch_warnings():  # ignore warings about all-nan values
        warnings.simplefilter("ignore", category=RuntimeWarning)
        a = np.asarray(a)
        return np.nanstd(a, axis=axis) / np.sqrt(np.size(a, axis=0))

nan_std #

nan_std(a: ArrayLike, axis: int | None = None) -> NDArray | float

Compute the standard deviation while ignoring NaNs.

Source code in earthcarekit/stats/_omitna.py 
15
16
17
18
19
20
def nan_std(a: ArrayLike, axis: int | None = None) -> NDArray | float:
    """Compute the standard deviation while ignoring NaNs."""
    with warnings.catch_warnings():  # ignore warings about all-nan values
        warnings.simplefilter("ignore", category=RuntimeWarning)
        a = np.asarray(a)
        return np.nanstd(a, axis=axis)