ML Commons supports various algorithms to help train and predict machine learning (ML) models or test data-driven predictions without a model. This page outlines the algorithms supported by the ML Commons plugin and the API operations they support.
K-means is a simple and popular unsupervised clustering ML algorithm built on top of [Tribuo](https://tribuo.org/) library. K-means will randomly choose centroids, then calculate iteratively to optimize the position of the centroids until each observation belongs to the cluster with the nearest mean.
distance_type | enum, such as `EUCLIDEAN`, `COSINE`, or `L1` | The type of measurement from which to measure the distance between centroids | `EUCLIDEAN`
Linear regression maps the linear relationship between inputs and outputs. In ML Commons, the linear regression algorithm is adopted from the public machine learning library [Tribuo](https://tribuo.org/), which offers multidimensional linear regression models. The model supports the linear optimizer in training, including popular approaches like Linear Decay, SQRT_DECAY, [ADA](https://www.jmlr.org/papers/volume12/duchi11a/duchi11a.pdf), [ADAM](https://tribuo.org/learn/4.1/javadoc/org/tribuo/math/optimisers/Adam.html), and [RMS_DROP](https://tribuo.org/learn/4.1/javadoc/org/tribuo/math/optimisers/RMSProp.html).
momentumFactor | Double | The extra weight factors that accelerate the rate at which the weight is adjusted. This helps move the minimization routine out of local minima. | 0
epsilon | Double | The value for stabilizing gradient inversion. | 1.00E-06
beta1 | Double | The exponential decay rates for the moment estimates. | 0.9
beta2 | Double | The exponential decay rates for the moment estimates. | 0.99
decayRate | Double | The Root Mean Squared Propagation (RMSProp). | 0.9
momentumType | MomentumType | The defined Stochastic Gradient Descent (SGD) momentum type that helps accelerate gradient vectors in the right directions, leading to a fast convergence.| STANDARD
optimizerType | OptimizerType | The optimizer used in the model. | SIMPLE_SGD
ML Commons only supports the linear Stochastic gradient trainer or optimizer, which cannot effectively map the non-linear relationships in trained data. When used with complicated datasets, the linear Stochastic trainer might cause some convergence problems and inaccurate results.
[Random Cut Forest](https://github.com/aws/random-cut-forest-by-aws) (RCF) is a probabilistic data structure used primarily for unsupervised anomaly detection. Its use also extends to density estimation and forecasting. OpenSearch leverages RCF for anomaly detection. ML Commons supports two new variants of RCF for different use cases:
For FIT RCF, you can train the model with historical data and store the trained model in your index. The model will be deserialized and predict new data points when using the Predict API. However, the model in the index will not be refreshed with new data, because the model is fixed in time.
RCFSummarize is a clustering algorithm based on the Clustering Using REpresentatives (CURE) algorithm. Compared to [k-means](#k-means), which uses random iterations to cluster, RCFSummarize uses a hierarchical clustering technique. The algorithm starts, with a set of randomly selected centroids larger than the centroids' ground truth distribution. During iteration, centroid pairs too close to each other automatically merge. Therefore, the number of centroids (`max_k`) converge to a rational number of clusters that fits ground truth, as opposed to a fixed `k` number of clusters.
### Parameters
| Parameter | Type | Description | Default Value |
| max_k | integer | The max allowed number of centroids. | 2 |
| distance_type | enum, such as `EUCLIDEAN`, `L1`, `L2`, or `LInfinity` | The type of measurement used to measure the distance between centroids. | EUCLIDEAN |
* [Train and predict]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/#train-and-predict)
### Example: Train and predict
The following example estimates cluster centers and provides cluster labels for each sample in a given data frame.
```bash
POST _plugins/_ml/_train_predict/RCF_SUMMARIZE
{
"parameters": {
"centroids": 3,
"max_k": 15,
"distance_type": "L2"
},
"input_data": {
"column_metas": [
{
"name": "d0",
"column_type": "DOUBLE"
},
{
"name": "d1",
"column_type": "DOUBLE"
}
],
"rows": [
{
"values": [
{
"column_type": "DOUBLE",
"value": 6.2
},
{
"column_type": "DOUBLE",
"value": 3.4
}
]
}
]
}
}
```
**Response**
The `rows` parameter within the prediction result has been modified for length. In your response, expect more rows and columns to be contained within the response body.
The Localization algorithm finds subset-level information for aggregate data (for example, aggregated over time) that demonstrates the activity of interest, such as spikes, drops, changes, or anomalies. Localization can be applied in different scenarios, such as data exploration or root cause analysis, to expose the contributors driving the activity of interest in the aggregate data.
ThefollowingexamplecreatesanindexinOpenSearchwiththe[Irisdataset](https://archive.ics.uci.edu/ml/datasets/iris), then trains the data using logistic regression. Lastly, it uses the trained model to predict Iris types separated by row.
This example uses a multi-class logistic regression categorization methodology. Here, the inputs of sepal and petal length and width are used to train the model to categorize centroids based on the `class`, as indicated by the `target` parameter.
**Request**
```bash
{
"parameters": {
"target": "class"
},
"input_query": {
"query": {
"match_all": {}
},
"_source": [
"sepal_length_in_cm",
"sepal_width_in_cm",
"petal_length_in_cm",
"petal_width_in_cm",
"class"
],
"size": 200
},
"input_index": [
"iris_data"
]
}
```
**Response**
The `model_id` will be used to predict the class of the Iris.
```json
{
"model_id":"TOgsf4IByBqD7FK_FQGc",
"status":"COMPLETED"
}
```
#### Predict results
Using the `model_id` of the trained Iris dataset, logistic regression will predict the class of the Iris based on the input data.
```bash
POST _plugins/_ml/_predict/logistic_regression/SsfQaoIBEoC4g4joZiyD
{
"parameters": {
"target": "class"
},
"input_data": {
"column_metas": [
{
"name": "sepal_length_in_cm",
"column_type": "DOUBLE"
},
{
"name": "sepal_width_in_cm",
"column_type": "DOUBLE"
},
{
"name": "petal_length_in_cm",
"column_type": "DOUBLE"
},
{
"name": "petal_width_in_cm",
"column_type": "DOUBLE"
}
],
"rows": [
{
"values": [
{
"column_type": "DOUBLE",
"value": 6.2
},
{
"column_type": "DOUBLE",
"value": 3.4
},
{
"column_type": "DOUBLE",
"value": 5.4
},
{
"column_type": "DOUBLE",
"value": 2.3
}
]
},
{
"values": [
{
"column_type": "DOUBLE",
"value": 5.9
},
{
"column_type": "DOUBLE",
"value": 3.0
},
{
"column_type": "DOUBLE",
"value": 5.1
},
{
"column_type": "DOUBLE",
"value": 1.8
}
]
}
]
}
}
```
**Response**
```json
{
"status":"COMPLETED",
"prediction_result":{
"column_metas":[
{
"name":"result",
"column_type":"STRING"
}
],
"rows":[
{
"values":[
{
"column_type":"STRING",
"value":"Iris-virginica"
}
]
},
{
"values":[
{
"column_type":"STRING",
"value":"Iris-virginica"
}
]
}
]
}
}
```
### Limitations
Convergence metrics are not built into Tribuo's trainers. Therefore, ML Commons cannot indicate the convergence status through the ML Commons API.
