# `Latu.ML.Evaluation`
[🔗](https://github.com/zero-one-group/latu_ml/blob/v0.4.2/lib/latu/ml/evaluation.ex#L1)

Evaluators: one metric over a scored frame.

An evaluator is neither fitted nor applied. It reads the columns a model wrote and answers
with one number, and `metric_name:` is what picks which number.

Every constructor here is generated from PySpark 4.2.0's own param table, and every
accessor module from the server's own attribute allowlist. Nothing in this file is
hand-written but the words you are reading — see `Latu.ML.operators/1` for the table it all
comes from.

# `binary_classification_evaluator`

```elixir
@spec binary_classification_evaluator(keyword()) :: Latu.ML.Evaluator.t()
```

Evaluator for binary classification, which expects input columns rawPrediction, label and an
optional weight column. The rawPrediction column can be of type double (binary 0/1
prediction, or probability of label 1) or of type vector (length-2 vector of raw
predictions, scores, or label probabilities).

An evaluator scores a frame and answers with one number. The verb that runs one is not
written yet, so for now this builds the operator and its params — and the command behind
it is already pinned against PySpark's own bytes.

*Status `:probed`* — `dev/probe_ml.exs` applied it against a live Spark 4.2.0 server, and
every allowlisted attribute it could ask answered.

## Params

  * `:label_col` — label column name. Default `"label"`.
  * `:metric_name` — metric name in evaluation (areaUnderROC|areaUnderPR) Default `"areaUnderROC"`.
  * `:num_bins` — Number of bins to down-sample the curves (ROC curve, PR curve) in area computation. If 0, no down-sampling will occur. Must be >= 0. Default `1000`.
  * `:raw_prediction_col` — raw prediction (a.k.a. confidence) column name. Default `"rawPrediction"`.
  * `:weight_col` — weight column name. If this is not set or empty, we treat all instance weights as 1.0.

Defaults are documented, never sent: a param the caller did not set and a param sent with
its default value are different requests, and only the first is right. A value's **kind** is
refused here; its **range** is Spark's own `ParamValidators` to refuse, with a better
message than this package could write.

# `clustering_evaluator`

```elixir
@spec clustering_evaluator(keyword()) :: Latu.ML.Evaluator.t()
```

Evaluator for Clustering results, which expects two input columns: prediction and features.
The metric computes the Silhouette measure using the squared Euclidean distance.

An evaluator scores a frame and answers with one number. The verb that runs one is not
written yet, so for now this builds the operator and its params — and the command behind
it is already pinned against PySpark's own bytes.

*Status `:probed`* — `dev/probe_ml.exs` applied it against a live Spark 4.2.0 server, and
every allowlisted attribute it could ask answered.

## Params

  * `:distance_measure` — The distance measure. Supported options: 'squaredEuclidean' and 'cosine'. Default `"squaredEuclidean"`.
  * `:features_col` — features column name. Default `"features"`.
  * `:metric_name` — metric name in evaluation (silhouette) Default `"silhouette"`.
  * `:prediction_col` — prediction column name. Default `"prediction"`.
  * `:weight_col` — weight column name. If this is not set or empty, we treat all instance weights as 1.0.

Defaults are documented, never sent: a param the caller did not set and a param sent with
its default value are different requests, and only the first is right. A value's **kind** is
refused here; its **range** is Spark's own `ParamValidators` to refuse, with a better
message than this package could write.

# `multiclass_classification_evaluator`

```elixir
@spec multiclass_classification_evaluator(keyword()) :: Latu.ML.Evaluator.t()
```

Evaluator for Multiclass Classification, which expects input columns: prediction, label,
weight (optional) and probabilityCol (only for logLoss).

An evaluator scores a frame and answers with one number. The verb that runs one is not
written yet, so for now this builds the operator and its params — and the command behind
it is already pinned against PySpark's own bytes.

*Status `:probed`* — `dev/probe_ml.exs` applied it against a live Spark 4.2.0 server, and
every allowlisted attribute it could ask answered.

## Params

  * `:beta` — The beta value used in weightedFMeasure|fMeasureByLabel. Must be > 0. The default value is 1. Default `1.0`.
  * `:eps` — log-loss is undefined for p=0 or p=1, so probabilities are clipped to max(eps, min(1 - eps, p)). Must be in range (0, 0.5). The default value is 1e-15. Default `1.0e-15`.
  * `:label_col` — label column name. Default `"label"`.
  * `:metric_label` — The class whose metric will be computed in truePositiveRateByLabel|falsePositiveRateByLabel|precisionByLabel|recallByLabel|fMeasureByLabel. Must be >= 0. The default value is 0. Default `0.0`.
  * `:metric_name` — metric name in evaluation (f1|accuracy|weightedPrecision|weightedRecall|weightedTruePositiveRate| weightedFalsePositiveRate|weightedFMeasure|truePositiveRateByLabel| falsePositiveRateByLabel|precisionByLabel|recallByLabel|fMeasureByLabel| logLoss|hammingLoss) Default `"f1"`.
  * `:prediction_col` — prediction column name. Default `"prediction"`.
  * `:probability_col` — Column name for predicted class conditional probabilities. Note: Not all models output well-calibrated probability estimates! These probabilities should be treated as confidences, not precise probabilities. Default `"probability"`.
  * `:weight_col` — weight column name. If this is not set or empty, we treat all instance weights as 1.0.

Defaults are documented, never sent: a param the caller did not set and a param sent with
its default value are different requests, and only the first is right. A value's **kind** is
refused here; its **range** is Spark's own `ParamValidators` to refuse, with a better
message than this package could write.

# `multilabel_classification_evaluator`

```elixir
@spec multilabel_classification_evaluator(keyword()) :: Latu.ML.Evaluator.t()
```

Evaluator for Multilabel Classification, which expects two input columns: prediction and
label.

An evaluator scores a frame and answers with one number. The verb that runs one is not
written yet, so for now this builds the operator and its params — and the command behind
it is already pinned against PySpark's own bytes.

*Status `:probed`* — `dev/probe_ml.exs` applied it against a live Spark 4.2.0 server, and
every allowlisted attribute it could ask answered.

## Params

  * `:label_col` — label column name. Default `"label"`.
  * `:metric_label` — The class whose metric will be computed in precisionByLabel|recallByLabel|f1MeasureByLabel. Must be >= 0. The default value is 0. Default `0.0`.
  * `:metric_name` — metric name in evaluation (subsetAccuracy|accuracy|hammingLoss|precision|recall|f1Measure|precisionByLabel|recallByLabel|f1MeasureByLabel|microPrecision|microRecall|microF1Measure) Default `"f1Measure"`.
  * `:prediction_col` — prediction column name. Default `"prediction"`.

Defaults are documented, never sent: a param the caller did not set and a param sent with
its default value are different requests, and only the first is right. A value's **kind** is
refused here; its **range** is Spark's own `ParamValidators` to refuse, with a better
message than this package could write.

# `ranking_evaluator`

```elixir
@spec ranking_evaluator(keyword()) :: Latu.ML.Evaluator.t()
```

Evaluator for Ranking, which expects two input columns: prediction and label.

An evaluator scores a frame and answers with one number. The verb that runs one is not
written yet, so for now this builds the operator and its params — and the command behind
it is already pinned against PySpark's own bytes.

*Status `:probed`* — `dev/probe_ml.exs` applied it against a live Spark 4.2.0 server, and
every allowlisted attribute it could ask answered.

## Params

  * `:k` — The ranking position value used in meanAveragePrecisionAtK|precisionAtK|ndcgAtK|recallAtK. Must be > 0. The default value is 10. Default `10`.
  * `:label_col` — label column name. Default `"label"`.
  * `:metric_name` — metric name in evaluation (meanAveragePrecision|meanAveragePrecisionAtK|precisionAtK|ndcgAtK|recallAtK) Default `"meanAveragePrecision"`.
  * `:prediction_col` — prediction column name. Default `"prediction"`.

Defaults are documented, never sent: a param the caller did not set and a param sent with
its default value are different requests, and only the first is right. A value's **kind** is
refused here; its **range** is Spark's own `ParamValidators` to refuse, with a better
message than this package could write.

# `regression_evaluator`

```elixir
@spec regression_evaluator(keyword()) :: Latu.ML.Evaluator.t()
```

Evaluator for Regression, which expects input columns prediction, label and an optional
weight column.

An evaluator scores a frame and answers with one number. The verb that runs one is not
written yet, so for now this builds the operator and its params — and the command behind
it is already pinned against PySpark's own bytes.

*Status `:probed`* — `dev/probe_ml.exs` applied it against a live Spark 4.2.0 server, and
every allowlisted attribute it could ask answered.

## Params

  * `:label_col` — label column name. Default `"label"`.
  * `:metric_name` — metric name in evaluation - one of: rmse - root mean squared error (default) mse - mean squared error r2 - r^2 metric mae - mean absolute error var - explained variance. Default `"rmse"`.
  * `:prediction_col` — prediction column name. Default `"prediction"`.
  * `:through_origin` — whether the regression is through the origin. Default `false`.
  * `:weight_col` — weight column name. If this is not set or empty, we treat all instance weights as 1.0.

Defaults are documented, never sent: a param the caller did not set and a param sent with
its default value are different requests, and only the first is right. A value's **kind** is
refused here; its **range** is Spark's own `ParamValidators` to refuse, with a better
message than this package could write.

---

*Consult [api-reference.md](api-reference.md) for complete listing*