Metrics¶

tinax.metrics computes validated binary-classification and regression metrics from explicit one-dimensional NumPy arrays, rejecting non-array inputs, shape mismatches, non-finite values, and invalid label or probability values at the public boundary instead of returning silently wrong numbers.

import numpy as np

from tinax.metrics import best_f1_threshold, binary_metrics

labels = np.array([0, 0, 1, 1])
probabilities = np.array([0.1, 0.4, 0.6, 0.9])

threshold = best_f1_threshold(labels, probabilities)
report = binary_metrics(labels, probabilities, threshold=threshold)
print(report.f1)

BinaryMetrics `dataclass` ¶

BinaryMetrics(
    accuracy: float,
    f1: float,
    precision: float,
    recall: float,
    threshold: float,
)

Binary-classification metrics at one decision threshold.

Attributes:

Name	Type	Description
`accuracy`	`float`	Fraction of predictions that match the label.
`f1`	`float`	Harmonic mean of precision and recall, `0.0` when either is undefined.
`precision`	`float`	Fraction of predicted positives that are true positives, `0.0` when there are no predicted positives.
`recall`	`float`	Fraction of actual positives that are predicted positives, `0.0` when there are no actual positives.
`threshold`	`float`	Decision threshold used to produce the predictions.

RegressionMetrics `dataclass` ¶

RegressionMetrics(rmse: float, mae: float, r2: float)

Regression error metrics over finite target and prediction arrays.

Attributes:

Name	Type	Description
`rmse`	`float`	Root mean squared error.
`mae`	`float`	Mean absolute error.
`r2`	`float`	Coefficient of determination, `0.0` when the targets have zero variance.

best_f1_threshold ¶

best_f1_threshold(
    labels: ndarray, probabilities: ndarray
) -> float

Find the smallest probability threshold that maximizes binary F1.

Candidate thresholds are the unique values in probabilities, and each candidate treats every entry with probabilities >= candidate as positive. The sweep runs in O(n log n) time and breaks F1 ties toward the smallest candidate.

Parameters:

Name	Type	Description	Default
`labels`	`ndarray`	One-dimensional array of 0/1 labels. Booleans are accepted.	required
`probabilities`	`ndarray`	One-dimensional array of finite probabilities in `[0, 1]` with the same shape as `labels`.	required

Returns:

Type	Description
`float`	The candidate threshold with the highest F1 score as a plain `float`.

Raises:

Type	Description
`TypeError`	If an argument is not a `numpy.ndarray` or does not have a real numeric dtype.
`ValueError`	If the arrays have different shapes, are not one-dimensional, are empty, or violate the label or probability value contracts.

binary_metrics ¶

binary_metrics(
    labels: ndarray,
    probabilities: ndarray,
    *,
    threshold: float = 0.5,
) -> BinaryMetrics

Compute binary-classification metrics at an explicit decision threshold.

Entries with probabilities >= threshold are predicted positive. Precision, recall, and F1 fall back to 0.0 when their denominator is zero.

Parameters:

Name	Type	Description	Default
`labels`	`ndarray`	One-dimensional array of 0/1 labels. Booleans are accepted.	required
`probabilities`	`ndarray`	One-dimensional array of finite probabilities in `[0, 1]` with the same shape as `labels`.	required
`threshold`	`float`	Decision threshold in `[0, 1]`. Defaults to `0.5`.	`0.5`

Returns:

Type	Description
`BinaryMetrics`	A `BinaryMetrics` holding accuracy, F1, precision, recall, and the
`BinaryMetrics`	validated threshold.

Raises:

Type	Description
`TypeError`	If `labels` or `probabilities` is not a `numpy.ndarray`, an array does not have a real numeric dtype, or `threshold` is not a real number (booleans are rejected).
`ValueError`	If the arrays have different shapes, are not one-dimensional, are empty, or violate the label or probability value contracts, or if `threshold` is not a finite number within `[0, 1]`.

regression_metrics ¶

regression_metrics(
    targets: ndarray, predictions: ndarray
) -> RegressionMetrics

Compute RMSE, MAE, and R2 for finite regression targets and predictions.

r2 is 1 - SSE / SST and 0.0 when the targets have zero variance.

Parameters:

Name	Type	Description	Default
`targets`	`ndarray`	One-dimensional array of finite target values.	required
`predictions`	`ndarray`	One-dimensional array of finite predictions with the same shape as `targets`.	required

Returns:

Type	Description
`RegressionMetrics`	A `RegressionMetrics` holding RMSE, MAE, and R2 as plain floats.

Raises:

Type	Description
`TypeError`	If `targets` or `predictions` is not a `numpy.ndarray` or does not have a real numeric dtype.
`ValueError`	If the arrays have different shapes, are not one-dimensional, are empty, or contain non-finite values.

Metrics¶

BinaryMetrics dataclass ¶

RegressionMetrics dataclass ¶

best_f1_threshold ¶

binary_metrics ¶

regression_metrics ¶

BinaryMetrics `dataclass` ¶

RegressionMetrics `dataclass` ¶