Drift Calculator API

About the Drift Calculator

A drift calculator is a named, reusable object that detects data drift between a set of reference projects and the projects you want to score. It is fit once against reference data and then reused to score any number of projects, so the reference statistics are computed a single time rather than on every request.

This is the stateful counterpart to the one-shot Data Drift Detection endpoint:

Use the one-shot endpoint for an ad-hoc comparison of two projects. Use a drift calculator for ongoing monitoring, where the same baseline is scored against new data repeatedly.

Lifecycle

A drift calculator is always used in the same order:

1. Create it with POST /{cid}/driftCalculator?id={id}, supplying its configuration.
2. Fit it against one or more reference projects with POST /{cid}/driftCalculator/{dcid}/fit. This computes the score thresholds.
3. Calculate drift for the projects you want to score with POST /{cid}/driftCalculator/{dcid}/calculate.

Info, List and Delete are management operations and can be called at any point after creation. A calculator must be fit before it can calculate.

Configuration Parameters

The create request body holds up to three independent MLContext configurations, one per section key. All three are optional; omit any section the calculator will not use.

Note: pca_reconstruction here is a section key in this request body. Do not confuse it with pca_reconstruction_error, which is a value of the drift_metric parameter on the one-shot endpoint. mahalanobis is used in both roles — as a section key here and as a drift_metric value there.

General Drift Parameters

These go in the extraParameters map of the drift section. All values are strings.

Create

Creates a named drift calculator. The calculator is not usable until it has been fit.

URL

POST /symetry/rest/{cid}/driftCalculator?id={id}

Query Parameters

Request Body

A JSON object with up to three keys — drift, mahalanobis and pca_reconstruction — each holding an MLContext. See Configuration Parameters. Any omitted key defaults to an empty MLContext.

HTTP Responses

HTTP Response Entity

Sample Request/Response

Request:
POST url="http://charm:8080/symetry/rest/c1/driftCalculator?id=dc1"

Body:
{"drift":{"extraParameters":{"drift_threshold_type":"std","drift_update_reference":"false","prefix":"drift","drift_max_reference_update":"0","drift_delete_on_cleanup":"true"}},"mahalanobis":{"extraParameters":{"drift_metric":"mahalanobis","drift_pca_explained_var":"0.95","drift_sensitivity":"strict"}}}

Response:
{"statusCode":"CREATED","statusString":"Drift Detector created with id [dc1] for customer [c1]","values":{"string":"dc1"}}

Fit

Fits the calculator against one or more reference projects, computing the score thresholds it will use when calculating drift.

URL

POST /symetry/rest/{cid}/driftCalculator/{dcid}/fit [body=StringList]

Request Body

A StringList of reference project names.

HTTP Responses

HTTP Response Entity

scoreThresholdValues holds one 4-element array per reference project, ordered [pcaScore, pcaThreshold, mahalanobisScore, mahalanobisThreshold]. The two thresholds are identical across every entry — they describe the fitted calculator, not the individual project. featuresUse is populated only when a feature subset is in play.

Sample Request/Response

Request:
POST url="http://charm:8080/symetry/rest/c1/driftCalculator/dc1/fit"

Body:
{"values":["baseline_prj_0","baseline_prj_1","baseline_prj_2"]}

Response:
{"statusCode":"OK","statusString":"Fit done","values":{"dcfitresult":{"scoreThresholdValues":[[1.446197277540101,1.5411297181850343,6.1574693732769274,6.772459022565492],[0.4316696569278699,1.5411297181850343,0.05628595924314145,6.772459022565492],[0.43287084814230387,1.5411297181850343,0.5248063735727675,6.772459022565492]]}}}

Calculate

Scores one or more projects against the fitted calculator.

URL

POST /symetry/rest/{cid}/driftCalculator/{dcid}/calculate [body=DriftCalculatorCalculateContext]

Request Body

A DriftCalculatorCalculateContext. projects lists the projects to score; features optionally restricts the calculation to a subset of the attributes the calculator was fit on. Pass an empty features array to use all of them.

HTTP Responses

HTTP Response Entity

Each map carries exactly four keys:

A project has drifted on a given metric when its result exceeds the corresponding threshold.

Sample Request/Response

Request:
POST url="http://charm:8080/symetry/rest/c1/driftCalculator/dc1/calculate"

Body:
{"projects":["production_prj_0","production_prj_1"],"features":[]}

Response:
{"statusCode":"OK","statusString":"calculate done","values":{"KSVDMap":{"values":[{"datadrift_pca_result":48.34386230518053,"datadrift_pca_threshold":1.5411297181850343,"datadrift_mahalanobis_result":3.4050385192815624,"datadrift_mahalanobis_threshold":6.772459022565492},{"datadrift_pca_result":91.91243029315874,"datadrift_pca_threshold":1.5411297181850343,"datadrift_mahalanobis_result":79.13540840798673,"datadrift_mahalanobis_threshold":6.772459022565492}]}}}

In this example both projects have drifted on PCA reconstruction error (48.3 and 91.9 against a threshold of 1.54); only the second has drifted on Mahalanobis distance (79.1 against 6.77, versus 3.41 for the first).

Info

Returns the configuration of a drift calculator, including the attributes it was fit on.

URL

GET /symetry/rest/{cid}/driftCalculator/{dcid}/info

HTTP Responses

HTTP Response Entity

The three parameter maps echo back the key/value pairs supplied in the corresponding section of the create request body.

Sample Request/Response

Request:
GET url="http://charm:8080/symetry/rest/c1/driftCalculator/dc1/info"

Response:
{"statusCode":"OK","statusString":"info returned","values":{"dcinfo":{"inputAttributes":["attr_a","attr_b"],"driftParameters":{"drift_threshold_type":"std","drift_update_reference":"false","prefix":"drift","drift_max_reference_update":"0","drift_delete_on_cleanup":"true"},"mahalanobisParameters":{"drift_metric":"mahalanobis","drift_pca_explained_var":"0.95","drift_sensitivity":"strict"},"pcaRecParameters":{}}}}

List

Lists the drift calculators belonging to a customer.

URL

GET /symetry/rest/{cid}/driftCalculators

HTTP Responses

HTTP Response Entity

Sample Request/Response

Request:
GET url="http://charm:8080/symetry/rest/c1/driftCalculators"

Response:
{"statusCode":"OK","statusString":"list returned","values":{"stringList":{"values":["dc1","dc2"]}}}

Delete

Deletes a drift calculator and releases its resources.

URL

DELETE /symetry/rest/{cid}/driftCalculator/{dcid}

HTTP Responses

HTTP Response Entity

None.

Sample Request/Response

Request:
DELETE url="http://charm:8080/symetry/rest/c1/driftCalculator/dc1"

Response:
{"statusCode":"OK","statusString":"cleanup done","values":{}}