Modeling API

About Model Building

This API function allows for the building of a model by specifying the attribute and the targets to use to build the model. The information about which attributes to use to build the model are passed as part of the body request in the MLContext JSON data structure. For more information see the section MLContext Build Parameters.

Real-Time Anomaly Models

SymetryML support 6 anomaly detection algorithms:

• MFAnomaly: an anomaly model based on a mixture of isolation forest and SymetryML online random forest algorithm.
• OOSPCAModel: Online implementation of Out of sample PCA.
• HBAModel: Online model based on histograms of the input features.
• ECODModel: Empirical Cumulative Distribution Outlier detection
• EVTModel: Extreme value Theory based
• REPCAModel: PCA Reconstruction-Error based. Flags points that violate the learned PCA structure (Q-statistic) and/or sit far from the center along retained principal directions (Hotelling's T²).

These algorithms work in real-time on streaming data and are a type of of unsupervised learning algorithm in the sense that one does not need to provide positive examples of anomalies to the different algorithms. The 3 models use intrinsic values of the inputs features to compute an anomaly scores. To create such models just use the appropriate id - from Model Algorithm ID - when creating them using Build Model rest API.

About Clustering

The following sections describes the KMeans clustering algorithm configuration that needs to be specified when creating a new project.

About Elastic Net AIC

Akaike information criterion (AIC) is a model selection heuristic which allows the user to select the optimal Eta and Lambda hyperparameters for their Elastic Net models using in-sample data. The AIC implementation in SymetryML is corrected for small sample sizes. This adjustment is commonly referred to as AICc. More detailed description of the AIC and small sample correction can be found here. In the context of SymetryML, the use of AIC can be selected by specifying the following extraParameters of the MLContext.

Note, when aicc is enabled. It’s not necessary to specify the lambda and eta parameters separately as they will be chosen by the AIC optimizer.

Model Algorithm Id

The following models are supported. For power regression model to be available a SymetryML project must have some attributes set when it is created. Please consult the Symetry Job section.

About Random Forest

In order to use the Online random forest additional parameters must be specified when creating a SymetryProject. Please consult the Create Project endpoint for details. The following 2 tables describes the hyper parameters available with the SML Random Forest algorithm:

Sample Request/Response

Request:
POST url=http://charm:8080/symetry/rest/c1/projects?pid=irisMeta&type=partition&persist=true
Request:
POST url=http://charm:8080/symetry/rest/c1/projects?pid=irisMeta&type=partition&persist=true

Request Body:
{"rf_target_name":"target","rf_num_classes":"3","rf_complexity":"12"}

Response:
{"statusCode":"CREATED","statusString":"Project Created with id:rfProject","values":{}}

About Kaplan Meier Model

Kaplan Meier (KM) requires three additional parameters to be specified when creating a SymetryML project. Please consult the Create Project endpoint for details.

Sample Request/Response

Request:
POST url=http://charm:8080/symetry/rest/c1/projects?pid=km1&type=cpu&persist=true

Request Body:
{"km_time_column":"time","km_group_column":"groups","km_event_column":"dead"}

Response:
{"statusCode":"CREATED","statusString":"Project Created with id:km1","values":{}}

After enabling your project with KM parameters, building a KM model is as simple calling the Build Model REST Endpoint. At this stage you can optionally set the alpha parameter which controls the width of your confidence intervals. This is done by setting alpha in the extraParameters field of the MLContext.

About Single Pass Logistic Regression

Single Pass Logistic Regression (LR) requires parameters to be specified when creating a SymetryML project. Please consult the Create Project endpoint for details.

Sample Request/Response

Request:
POST url=http://charm:8080/symetry/rest/c1/projects?pid=lr1&type=cpu&persist=true

Request Body:
{"lr_target_column":"target","lr_features":"a1:a2:a3"}

Response:
{"statusCode":"CREATED","statusString":"Project Created with id:lr1","values":{}}

About Power Regression Model

Linear regression assumes that the target attribute is normally distributed. While in real world scenarios this is often not the case, we can still improve the performance of the regression model by transforming the target into something resembling a normal distribution. The method of transforming that is used within SymetryML is the Yeo-Johnson transformation.

SymetryML projects with power transformation enabled will automatically create new attributes representing various power transformations of the target so that they can be modeled against the existing features. These additional target features will have a prefix and separator to easily pinpoint them. (e.g pt_sepal_width^-2.0, pt_sepal_width^-1.8, pt_sepal_width^-1.6, …, pt_sepal_width^1.8, pt_sepal_width^2.0). It’s possible to configure the prefix and separator - pt_ and ^ in our previous example. Please refer to the Power Regression Parameters table for details.

Once a project has learned these transformations, a Power Regression model can be build which would select the optimal transformed target.

To enable Power Regression, please specify the following parameters when creating your project:

Power Regression Parameters

Example of of MLContext used when creating a project that use power transformation:

POST http://charm:8080/symetry/rest/c1/projects>?pid=pt1&type=cpu&persist=false

BODY:
{"sml_project_power_column":"sepal_width","sml_project_power_steps":"5","sml_project_power_min":"-1","sml_project_power_max":"2"}

Power transformation prefix and suffix can be configured in the symetry-rest.txt configuration file. Please consult the Installation Guide - SymetryML REST Configuration for details on configuring that file.

MLContext Build Parameters

MLContext Build Parameters for Matrix

When SymetryML builds new model it might use Matrix inversion. These operations are performed using an implementation of LAPACK (DGETRF and DGETRI) using some third party library using CPU and / or GPU. Matrix inversion can lead to numerical instability problem. The following parameters affect how matrix inversion is computed.

Other MLContext Build Parameters

There are other parameters that control various model building

KMeans Clustering MLContext Build Parameters

When building Kmeans clustering model the following hyper parameters are required:

Elastic Net MLContext Build Parameters

Elastic Net is an extension of the classic MLR algorithm which adds regularization as a way to combat overfitting of your training data. It combines the regularization methods of both Ridge (L-2 norm regularization) and Lasso (L-1 norm regularization). While all three models feature the regularization parameter Lambda, Elastic Net contains one extra parameter, ETA, which controls how close the regularization should be to a pure Ridge regression model (ETA = 0) versus a pure Lasso approach (ETA = 1)

When building Elastic Net, Lasso or Ridge regression model the following hyper parameters are required:

Optional parameters for Elastic Net are the following:

The combined effect of centering the targets (centerY = true) as well as standardize the features (standardize = true) is to get rid of the intercept.

Lastly, Elastic Net models initial weights can be specified in the MLContext in the following format:

ECOD Model MLContext Build Parameters

ECOD stands for Empirical-Cumulative-distribution-based Outlier Detection (https://arxiv.org/pdf/2201.00382.pdf). It uses the CDF of each feature to estimate tail probabilities per dimension for each data point. An outlier score is calculated by aggregating probabilities across dimensions.

EVT Model MLContext Build Parameters

A typical anomaly model outputs an anomaly score for a particular instance with those instances that are further from nominal receiving a higher score. The decision whether to flag something as an anomaly essentially becomes a process of choosing a threshold for this score. Scores above the threshold will be flagged as anomalies and anything below it will be deemed as nominal.

If the distribution of your input data does not change, the threshold method might be sufficient for your needs. However, in the case of dynamically changing distributions more robust approaches should be used. Once such approach is to leverage Extreme Value Theorem (EVT) to compute a distribution of extreme values which we can later be queried to determine whether or not a particular instance is an anomaly. Additional information on the use of EVT for anomaly detection can be found here

REPCA Model MLContext Build Parameters

REPCA stands for Reconstruction-Error PCA. The model fits PCA on the standardized covariance of the input features, retains the top q components needed to reach a target explained-variance ratio, and then flags new points using two complementary statistics:

• Q-statistic (Squared Prediction Error): squared Euclidean distance between a standardized point and its reconstruction after projecting into the q-dimensional PCA subspace and back. Detects points that violate the learned correlation structure or express novel patterns. Its threshold is derived from the Chi-Squared distribution with D - q degrees of freedom.
• Hotelling's T²: Mahalanobis-like distance inside the retained PCA subspace (sum of squared projected scores weighted by the inverse eigenvalues). Detects points that follow the data pattern but are extreme along the principal directions. Its threshold is derived from the F-distribution, which is more accurate than the Chi-Squared approximation for small training samples.

The hybrid score normalizes each statistic by its threshold and returns the max — a point is flagged if either statistic exceeds its own threshold.

The number of retained components q is chosen to reach repca_pca_explained_var but is capped by D - 1 (dimensions) and N / 10 (samples) to keep the model numerically stable.

Principal Component Regression Model MLContext Build Parameters

Principal component regression is a technique based on principal component analysis (PCA). To be more precise, projected features are used in conjunction with linear regression. Two flavors are available.

• I - The traditional approach where the first q principal components are kept, and a linear regression is applied to this q-dimensional space.
• II - An augmented features space is created using the p original features and the p principal components. A model is created by applying Lasso regression. The assumption that the first q principal components are the most important is not necessarily true and other principal components may correlate also with the target. This approach enables to pick up such contributions.

Partial Least Square Regression Model MLContext Build Parameters

Partial least square regression creates a new latent space of size q where q is smaller than p the number of features in which to do the regression. In the approach available, only the coefficients projected back to the original p dimensions are obtained.

Covariance Estimate Model MLContext Build Parameters

Covariance estimate deals with the problem of estimating the actual covariance matrix when only the empirical covariance matrix is available (coming from a sample of the multivariate distribution). The covariance estimators available use different regularization methods.

Build Model Rest API

URL

POST /symetry/rest/{cid}/projects/{pid}/build?modelid={modelid}&algo={algorithm} [body=MLContext]

Query Parameters

HTTP Responses

HTTP Response Entity

None

Sample Request/Response

Request:
POST url="http://charm:8080/symetry/rest/c1/projects/irisTest/build?algo=lda&modelid=testLDA"

Body:
{"targets":["3"],"inputAttributes":["0","1","2"]}

Response Header:
Location: http://charm:8080/symetry/rest/c1/jobs/5

Response:
{"statusCode":"ACCEPTED","statusString":"Job Created","values":{}}

Job Request:
GET url="http://charm:8080/symetry/rest/c1/jobs/5

Job Response:
{"statusCode":"OK","statusString":"Job is finished","values":{}}

Features Reduction Model Building

This API function allows for the building of an optimized model (aka reduced models), where the SymetryML service builds a model using the best attributes for the target specified in the MLContext of the request body. Like the model-building request, the response contains a Location header for the job that was created to service this request. Information about these jobs can be requested and are described in the Symetry Jobs chapter.

URL

POST /symetry/rest/{cid}/projects/{pid}/reduce?heuristic={heuristic}&modelid={modelid}&algo={algorithm}&delta [body=MLContext]

Query Parameters

HTTP Responses

HTTP Response Entity

None

Sample Request/Response

Request:
POST url="http://charm:8080/symetry/rest/c1/projects/irisTest/reduce?modelid=ldaOptimized&algo=lda&heuristic=default&delta=0.001&numIterations=5"

Body:
{"targets":["13"],"inputAttributes":["0","1","2","3","4","5","6","7","8","9","10","11","12","14"]}

Response Header:
Location: http://charm:8080/symetry/rest/c1/jobs/7

Response:
{"statusCode":"ACCEPTED","statusString":"Reduce Job Created","values":{}}

Job Request:
GET url="http://charm:8080/symetry/rest/c1/jobs/7

Job Response:
{"statusCode":"OK","statusString":"Job is finished","values":{}}

Building Sequence Models

Markov Chain Models and Hidden Markov Models are built differently. First, the project must be marked as a “sequence” project. After some data is learned, you can build Markov Chains, Hidden Markov Models, or both. These types of models have input attributes only; they do not have a target.

For Markov Chains, you input attributes to specify the sequence attributes to use. For Hidden Markov Model, you also specify the hidden state that must be categorical. The Observed state can be continuous or categorical. If it is a continuous attribute, normal distribution will be assumed, mean and standard deviation of the data is used.

KMeans Clustering Model Optimization

This rest endpoint allows to find the optimal k for your KMeans clustering model by building many model and then returning the silhouette and WSSSE metrics so that both the silhouette and elbow method can be used to decide which is the optimal k number of cluster that should be used.

URL

POST /symetry/rest/{cid}/projects/{pid}/kmeansOptimize [body=MLContext]

MLContext Build Parameters

HTTP Responses

Sample Request Response KMeans Optimizer

Request:
POST url="http://charm:8080/symetry/rest/c1/projects/p1/kmeansOptimize"

Body:
{
    "targets":[],
    "inputAttributes":[],
    "inputAttributeNames":[],
    "targetAttributeNames":[],
    "extraParameters":
    {
        "kmeans_k_min":"2",
        "kmeans_rnd_seed":"42",
        "kmeans_k_max":"5",
        "kmeans_max_iterations":"1000"
    }
}


Response:
Location: http://charm:8080/symetry/rest/c1/jobs/2

Response once job is finished:
{
    "statusCode":"OK",
    "statusString":"Job is finished",
    "values":{
        "KSVSMap":{
            "values":[
            {
                "kmeans_k_min":"2",
                "kmeans_rnd_seed":"42",
                "kmeans_5_silhouette":"0.24742236190463987",
                "kmeans_5_wssse":"24038.895607683746",
                "kmeans_4_silhouette":"0.2615571675703183",
                "kmeans_3_wssse":"34178.95949179863",
                "kmeans_k_max":"5",
                "kmeans_2_silhouette":"0.24099295660249936",
                "kmeans_4_wssse":"26852.68838040368",
                "kmeans_3_silhouette":"0.21947966456276002",
                "kmeans_max_iterations":"1000",
                "kmeans_2_wssse":"40316.897273276154"
            }
            ]
        }
    }
}

Model Information

This API function retrieves specific information about a model. A ModelInfo JSON data structure is returned. The response contains the type of model, attributes, and targets used by the model, along with specific information based on the type of model (info field).

URL

GET /symetry/rest/{cid}/projects/{pid}/models/{modelid}

HTTP Responses

HTTP Response Entity

Sample Request/Response

Request:
GET url="http://charm:8080/symetry/rest/c1/projects/irisTest/models/ldaOptimized"

Response:
{"statusCode":"OK","statusString":"OK","values":{"modelInfo":{"modelType":"lda","attributeNames":["petal_length","petal_width","sepal_width","petal_length_b1","sepal_lengt_b1","sepal_width_b1","petal_width_b2","sepal_length"],"attributeIndexes":[2,3,1,6,4,5,7,0],"info":{"buildStatus":"\"No Error\"","z0":"18.9666","z1LTz0":"false","z":"\"l0 \u003c- c(3.93801 ,2.43275 ,-8.92229 ,-15.9048 ,0.997005 ,-1.15579 ,-4.66130 ,59.3254 )\n\"","buildTimeNanosec":"6553273","OverallContribution":"4.49040"},"predictInfo":["resZ","res","normZ"],"scoreInfo":["normZ"],"buildTime":54,"modelBuilt":140,"targetNames":["Iris_versicolor"],"targetindexes":[13],"modelId":"ldaOptimized"}}}

Model Info Map Key

The following table enumerates the additional specific keys/value pairs that are returned when asking for model information based on the type of model.

Model Extra - EVTModel

Model Extra - MLR, Ridge, ElasticNet, Lasso

Model Extra - LR

Model Extra - Kmeans

Model Extra - RF

Model Extra - KM

Model Extra ECOD

Model Extra REPCA

Model Extra Principal Component Regression

Model Extra Covariance Estimator

Model Extra Partial Least Square Regression

Get Code for Model

LDA and MLR models allow retrieval of their internal representation as a Java method or SQL function. This API function call can be used with these models to perform predictions. The result is a string that represents the definition of a JAVA method or SQL function.

URL

GET /symetry/rest/{cid}/projects/{pid}/models/{modelid}/code?language=java

Query Parameters

HTTP Responses

HTTP Response Entity

Sample Request/Response

Request:
GET url=http://charm:8080/symetry/rest/c1/projects/irisTest/models/model1/code?language=java

Response:
"{"statusCode":"OK","statusString":"OK","values":{"string":"/* Java Function */\npublic double ldaRed_score(\n\tdouble petal_length,\n\tdouble petal_width,\n\tdouble sepal_width,\n\tdouble petal_length_b1,\n\tdouble sepal_width_b1,\n\tdouble petal_width_b2,\n\tdouble sepal_length)\n{\n\treturn (-8.780458794255027 * petal_length) + \n\t\t(-15.841653689691597 * petal_width) + \n\t\t(2.6264699508510816 * sepal_width) + \n\t\t(-4.283122721819282 * petal_length_b1) + \n\t\t(-1.0747512015680236 * sepal_width_b1) + \n\t\t(58.97284497145444 * petal_width_b2) + \n\t\t(3.4278968694343033 * sepal_length);\n}\n"}}"

EVT Wrapper Management

EVT (Extreme Value Theory) Wrappers allow you to add dynamic thresholding capabilities to any existing model. Instead of using a static threshold for anomaly detection, an EVT Wrapper tracks prediction outputs and uses Extreme Value Theory to dynamically determine whether results should be flagged as anomalies.

When an EVT Wrapper is attached to a model, it monitors a specified result key from predictions and automatically applies EVT-based anomaly detection to that value.

Create EVT Wrapper

Attaches an EVT Wrapper to an existing model for dynamic anomaly thresholding.

URL

POST /symetry/rest/{cid}/projects/{pid}/{modelid}/evtwrapper [body=Map]

Request Body Parameters

Additional EVT parameters from the EVT Model MLContext Build Parameters section can also be included to configure the EVT behavior.

HTTP Responses

Sample Request/Response

Request:
POST url="http://charm:8080/symetry/rest/c1/projects/myProject/myModel/evtwrapper"

Body:
{
    "sml_evt_wrapper_res_key": "anomaly_score",
    "sml_evt_wrapper_model_id": "myModel",
    "evt_warmup_size": "100",
    "evt_alpha": "0.01",
    "evt_quantile": "0.95"
}

Response:
{"statusCode":"OK","statusString":"EVT Wrapper Created","values":{}}

Delete EVT Wrapper

Removes an EVT Wrapper from a model.

URL

DELETE /symetry/rest/{cid}/projects/{pid}/{modelid}/evtwrapper

HTTP Responses

Sample Request/Response

Request:
DELETE url="http://charm:8080/symetry/rest/c1/projects/myProject/myModel/evtwrapper"

Response:
{"statusCode":"OK","statusString":"EVT Wrapper Deleted","values":{}}

Delete a Model

Delete a model from a project

URL

DELETE /symetry/rest/{cid}/projects/{pid}/models/{modelid}

HTTP Responses

Cumulative Incidence Function (CIF)

The cumulative incidence function (CIF) estimates the probability of a specific event occurring by a given time in the presence of competing risks. Unlike standard survival methods, which can overestimate event probabilities by treating competing events as censored, CIF properly accounts for the fact that experiencing one event precludes another. Use the following endpoints to retrieve cause-specific incidence estimates.

Get Total Events

Retrieves the total number of events for specified groups in a CIF model.

URL

POST /symetry/rest/{cid}/projects/{pid}/cif/NtotEvents [body=StringList]

Request Body

Sample Request/Response

Request:
POST url="http://charm:8080/symetry/rest/c1/projects/survivalProject/cif/NtotEvents"

Body:
{
    "values": ["group1", "group2"]
}

Response:
{"statusCode":"OK","statusString":"OK","values":{...}}

Predict At Risk

Predicts the number of subjects at risk at specified time points.

URL

POST /symetry/rest/{cid}/projects/{pid}/cif/predictAtRiskCIF [body=CIFPredictionRequestList]

Request Body

Sample Request/Response

Request:
POST url="http://charm:8080/symetry/rest/c1/projects/survivalProject/cif/predictAtRiskCIF"

Body:
{
    "values": [
        {
            "times": [0.5, 1.0, 2.0, 5.0],
            "k": 1,
            "group": "groupName"
        }
    ]
}

Response:
{"statusCode":"OK","statusString":"OK","values":{...}}

Predict Event

Predicts number of events at specified time points.

URL

POST /symetry/rest/{cid}/projects/{pid}/cif/predictEvent [body=CIFPredictionRequestList]

Request Body

Sample Request/Response

Request:
POST url="http://charm:8080/symetry/rest/c1/projects/survivalProject/cif/predictEvent"

Body:
{
    "values": [
        {
            "times": [0.5, 1.0, 2.0, 5.0],
            "k": 1,
            "group": "groupName"
        }
    ]
}

Response:
{"statusCode":"OK","statusString":"OK","values":{...}}

Kaplan-Meier Survival Analysis

The Kaplan-Meier estimator calculates the probability of surviving beyond a given time, accounting for censored observations. It is best suited for settings with a single event type, as it does not account for competing risks.

Get Survival DataFrames

Retrieves survival data frames from a Kaplan-Meier model.

URL

GET /symetry/rest/{cid}/projects/{pid}/km/getSurvivalFrame

Sample Request/Response

Request:
GET url="http://charm:8080/symetry/rest/c1/projects/survivalProject/km/getSurvivalFrame"

Response:
{"statusCode":"OK","statusString":"OK","values":{...}}

Kaplan-Meier Predict

Performs survival predictions with confidence intervals.

URL

POST /symetry/rest/{cid}/projects/{pid}/km/kaplanmeier [body=KMQueryList]

Request Body

Sample Request/Response

Request:
POST url="http://charm:8080/symetry/rest/c1/projects/survivalProject/km/kaplanmeier"

Body:
{
    "values": [
        {
            "type": "SURVIVAL",
            "group": "groupName",
            "alpha": 0.05,
            "times": [0.5, 1.0, 2.0, 5.0, 10.0]
        }
    ]
}

Response:
{"statusCode":"OK","statusString":"OK","values":{...}}