Bias and fairness¶
Use the endpoints described below to manage Bias and Fairness. Bias and Fairness testing provides methods to calculate fairness for a binary classification model and attempt to identify any biases in the model's predictive behavior. In DataRobot, bias represents the difference between a model's predictions for different populations (or groups) while fairness is the measure of the model's bias. Select protected features in the dataset and choose fairness metrics and mitigation techniques either before model building or from the Leaderboard once models are built. Bias and Fairness insights help identify bias in a model and visualize the root-cause analysis, explaining why the model is learning bias from the training data and from where.
GET /api/v2/deployments/{deploymentId}/fairnessScoresOverTime/¶
Retrieve fairness scores for all features, or for different classes of a single feature changes over a specific time period.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| start | query | string,null(date-time) | false | Start of the period to retrieve monitoring data, defaults to 7 days ago from the end of the period. Note: this field only accepts top of the hour RFC3339 datetime strings, for example: 2019-08-01T00:00:00Z. |
| end | query | string,null(date-time) | false | End of the period to retrieve monitoring data, defaults to the next top of the hour. Note: this field only accepts top of the hour RFC3339 datetime strings, for example: 2019-08-01T00:00:00Z. |
| bucketSize | query | string | false | Time duration of buckets |
| modelId | query | string | false | The ID of the model to retrieve the statistics for. |
| fairnessMetric | query | string,null | false | The name of the fairness metric to compute fairness over time. |
| protectedFeature | query | string | false | Name of the protected feature. When present, will return per class fairness score of the protected feature, otherwise returning fairness score of all protected features. |
| orderBy | query | string | false | The type of FairnessScore to order the response by. |
| includePrivilegedClass | query | string | false | Always include privileged class in response. |
| onlyStatisticallySignificant | query | string | false | Include only statistically significant attributes. |
| limit | query | integer | false | Max number of features in response. |
| offset | query | integer | false | Number of features to offset in response. |
| deploymentId | path | string | true | Unique identifier of the deployment. |
Enumerated Values¶
| Parameter | Value |
|---|---|
| bucketSize | [PT1H, P1D, P7D, P1M] |
| fairnessMetric | [proportionalParity, equalParity, favorableClassBalance, unfavorableClassBalance, trueUnfavorableRateParity, trueFavorableRateParity, favorablePredictiveValueParity, unfavorablePredictiveValueParity] |
| orderBy | [absoluteFairnessScore, relativeFairnessScore, -absoluteFairnessScore, -relativeFairnessScore] |
| includePrivilegedClass | [false, False, true, True] |
| onlyStatisticallySignificant | [false, False, true, True] |
Example responses¶
200 Response
{
"properties": {
"buckets": {
"description": "Per bucket summary.",
"items": {
"description": "Summary of per feature fairness.",
"properties": {
"metricName": {
"description": "Name of the metric.",
"enum": [
"proportionalParity",
"equalParity",
"favorableClassBalance",
"unfavorableClassBalance",
"trueUnfavorableRateParity",
"trueFavorableRateParity",
"favorablePredictiveValueParity",
"unfavorablePredictiveValueParity"
],
"type": "string"
},
"period": {
"description": "An object with the keys \"start\" and \"end\" defining the period.",
"properties": {
"end": {
"description": "End of the period to retrieve monitoring data, defaults to the next top of the hour. Note: this field only accepts top of the hour RFC3339 datetime strings, for example: ``2019-08-01T00:00:00Z``.",
"format": "date-time",
"type": [
"string",
"null"
]
},
"start": {
"description": "Start of the period to retrieve monitoring data, defaults to 7 days ago from the end of the period. Note: this field only accepts top of the hour RFC3339 datetime strings, for example: ``2019-08-01T00:00:00Z``.",
"format": "date-time",
"type": [
"string",
"null"
]
}
},
"type": "object"
},
"scores": {
"description": "List of per-feature fairness details.",
"items": {
"properties": {
"absoluteValue": {
"description": "Absolute fairness score.",
"type": "number"
},
"classesCount": {
"description": "Count of occurences of the class within the data the fairness is calculated on.",
"type": "integer"
},
"healthyClassesCount": {
"description": "Count of statistically significant classes above fairness threshold.",
"type": "integer"
},
"healthyCount": {
"description": "Total number of classes with fairness score above the threshold.",
"minimum": 0,
"type": "integer"
},
"isStatisticallySignificant": {
"description": "Class is statistically significant.",
"type": "boolean"
},
"label": {
"description": "Name of the feature.",
"type": "string"
},
"message": {
"description": "Explanation message.",
"type": "string"
},
"privilegedClass": {
"description": "Name of the privileged class (the one with the highest fairness score) within the feature.",
"type": "string"
},
"sampleSize": {
"description": "Sample size used for fairness status calculation",
"exclusiveMinimum": 0,
"type": "integer"
},
"totalCount": {
"description": "Total number of classes.",
"minimum": 1,
"type": "integer"
},
"value": {
"description": "Fairness score in relation to the privileged class fairness score.",
"maximum": 1,
"minimum": 0,
"type": "number"
}
},
"type": "object"
},
"type": "array"
}
},
"required": [
"metricName",
"period",
"scores"
],
"type": "object"
},
"type": "array"
},
"fairnessThreshold": {
"description": "Threshold used to compute fairness results.",
"maximum": 1,
"minimum": 0,
"type": "number"
},
"favorableTargetOutcome": {
"description": "Preferable class of target.",
"oneOf": [
{
"type": "boolean"
},
{
"type": "string"
},
{
"type": "integer"
}
]
},
"modelId": {
"description": "Model Id for which fairness is computed.",
"type": "string"
},
"modelPackageId": {
"description": "Model package Id.",
"type": "string"
},
"protectedFeature": {
"description": "Name of the protected feature.",
"type": "string"
},
"summary": {
"description": "Summary of per feature fairness.",
"properties": {
"metricName": {
"description": "Name of the metric.",
"enum": [
"proportionalParity",
"equalParity",
"favorableClassBalance",
"unfavorableClassBalance",
"trueUnfavorableRateParity",
"trueFavorableRateParity",
"favorablePredictiveValueParity",
"unfavorablePredictiveValueParity"
],
"type": "string"
},
"period": {
"description": "An object with the keys \"start\" and \"end\" defining the period.",
"properties": {
"end": {
"description": "End of the period to retrieve monitoring data, defaults to the next top of the hour. Note: this field only accepts top of the hour RFC3339 datetime strings, for example: ``2019-08-01T00:00:00Z``.",
"format": "date-time",
"type": [
"string",
"null"
]
},
"start": {
"description": "Start of the period to retrieve monitoring data, defaults to 7 days ago from the end of the period. Note: this field only accepts top of the hour RFC3339 datetime strings, for example: ``2019-08-01T00:00:00Z``.",
"format": "date-time",
"type": [
"string",
"null"
]
}
},
"type": "object"
},
"scores": {
"description": "List of per-feature fairness details.",
"items": {
"properties": {
"absoluteValue": {
"description": "Absolute fairness score.",
"type": "number"
},
"classesCount": {
"description": "Count of occurences of the class within the data the fairness is calculated on.",
"type": "integer"
},
"healthyClassesCount": {
"description": "Count of statistically significant classes above fairness threshold.",
"type": "integer"
},
"healthyCount": {
"description": "Total number of classes with fairness score above the threshold.",
"minimum": 0,
"type": "integer"
},
"isStatisticallySignificant": {
"description": "Class is statistically significant.",
"type": "boolean"
},
"label": {
"description": "Name of the feature.",
"type": "string"
},
"message": {
"description": "Explanation message.",
"type": "string"
},
"privilegedClass": {
"description": "Name of the privileged class (the one with the highest fairness score) within the feature.",
"type": "string"
},
"sampleSize": {
"description": "Sample size used for fairness status calculation",
"exclusiveMinimum": 0,
"type": "integer"
},
"totalCount": {
"description": "Total number of classes.",
"minimum": 1,
"type": "integer"
},
"value": {
"description": "Fairness score in relation to the privileged class fairness score.",
"maximum": 1,
"minimum": 0,
"type": "number"
}
},
"type": "object"
},
"type": "array"
}
},
"required": [
"metricName",
"period",
"scores"
],
"type": "object"
}
},
"required": [
"buckets",
"fairnessThreshold",
"favorableTargetOutcome",
"modelId",
"modelPackageId",
"summary"
],
"type": "object"
}
Responses¶
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Fairness summary and over time. | FairnessOverTimeResponse |
To perform this operation, you must be authenticated by means of one of the following methods:
BearerAuth
Schemas¶
FairnessOverTimeBucket
{
"description": "Summary of per feature fairness.",
"properties": {
"metricName": {
"description": "Name of the metric.",
"enum": [
"proportionalParity",
"equalParity",
"favorableClassBalance",
"unfavorableClassBalance",
"trueUnfavorableRateParity",
"trueFavorableRateParity",
"favorablePredictiveValueParity",
"unfavorablePredictiveValueParity"
],
"type": "string"
},
"period": {
"description": "An object with the keys \"start\" and \"end\" defining the period.",
"properties": {
"end": {
"description": "End of the period to retrieve monitoring data, defaults to the next top of the hour. Note: this field only accepts top of the hour RFC3339 datetime strings, for example: ``2019-08-01T00:00:00Z``.",
"format": "date-time",
"type": [
"string",
"null"
]
},
"start": {
"description": "Start of the period to retrieve monitoring data, defaults to 7 days ago from the end of the period. Note: this field only accepts top of the hour RFC3339 datetime strings, for example: ``2019-08-01T00:00:00Z``.",
"format": "date-time",
"type": [
"string",
"null"
]
}
},
"type": "object"
},
"scores": {
"description": "List of per-feature fairness details.",
"items": {
"properties": {
"absoluteValue": {
"description": "Absolute fairness score.",
"type": "number"
},
"classesCount": {
"description": "Count of occurences of the class within the data the fairness is calculated on.",
"type": "integer"
},
"healthyClassesCount": {
"description": "Count of statistically significant classes above fairness threshold.",
"type": "integer"
},
"healthyCount": {
"description": "Total number of classes with fairness score above the threshold.",
"minimum": 0,
"type": "integer"
},
"isStatisticallySignificant": {
"description": "Class is statistically significant.",
"type": "boolean"
},
"label": {
"description": "Name of the feature.",
"type": "string"
},
"message": {
"description": "Explanation message.",
"type": "string"
},
"privilegedClass": {
"description": "Name of the privileged class (the one with the highest fairness score) within the feature.",
"type": "string"
},
"sampleSize": {
"description": "Sample size used for fairness status calculation",
"exclusiveMinimum": 0,
"type": "integer"
},
"totalCount": {
"description": "Total number of classes.",
"minimum": 1,
"type": "integer"
},
"value": {
"description": "Fairness score in relation to the privileged class fairness score.",
"maximum": 1,
"minimum": 0,
"type": "number"
}
},
"type": "object"
},
"type": "array"
}
},
"required": [
"metricName",
"period",
"scores"
],
"type": "object"
}
Summary of per feature fairness.
Properties¶
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| metricName | string | true | Name of the metric. | |
| period | TimeRange | true | An object with the keys "start" and "end" defining the period. | |
| scores | [FairnessOverTimeScore] | true | List of per-feature fairness details. |
Enumerated Values¶
| Property | Value |
|---|---|
| metricName | [proportionalParity, equalParity, favorableClassBalance, unfavorableClassBalance, trueUnfavorableRateParity, trueFavorableRateParity, favorablePredictiveValueParity, unfavorablePredictiveValueParity] |
FairnessOverTimeResponse
{
"properties": {
"buckets": {
"description": "Per bucket summary.",
"items": {
"description": "Summary of per feature fairness.",
"properties": {
"metricName": {
"description": "Name of the metric.",
"enum": [
"proportionalParity",
"equalParity",
"favorableClassBalance",
"unfavorableClassBalance",
"trueUnfavorableRateParity",
"trueFavorableRateParity",
"favorablePredictiveValueParity",
"unfavorablePredictiveValueParity"
],
"type": "string"
},
"period": {
"description": "An object with the keys \"start\" and \"end\" defining the period.",
"properties": {
"end": {
"description": "End of the period to retrieve monitoring data, defaults to the next top of the hour. Note: this field only accepts top of the hour RFC3339 datetime strings, for example: ``2019-08-01T00:00:00Z``.",
"format": "date-time",
"type": [
"string",
"null"
]
},
"start": {
"description": "Start of the period to retrieve monitoring data, defaults to 7 days ago from the end of the period. Note: this field only accepts top of the hour RFC3339 datetime strings, for example: ``2019-08-01T00:00:00Z``.",
"format": "date-time",
"type": [
"string",
"null"
]
}
},
"type": "object"
},
"scores": {
"description": "List of per-feature fairness details.",
"items": {
"properties": {
"absoluteValue": {
"description": "Absolute fairness score.",
"type": "number"
},
"classesCount": {
"description": "Count of occurences of the class within the data the fairness is calculated on.",
"type": "integer"
},
"healthyClassesCount": {
"description": "Count of statistically significant classes above fairness threshold.",
"type": "integer"
},
"healthyCount": {
"description": "Total number of classes with fairness score above the threshold.",
"minimum": 0,
"type": "integer"
},
"isStatisticallySignificant": {
"description": "Class is statistically significant.",
"type": "boolean"
},
"label": {
"description": "Name of the feature.",
"type": "string"
},
"message": {
"description": "Explanation message.",
"type": "string"
},
"privilegedClass": {
"description": "Name of the privileged class (the one with the highest fairness score) within the feature.",
"type": "string"
},
"sampleSize": {
"description": "Sample size used for fairness status calculation",
"exclusiveMinimum": 0,
"type": "integer"
},
"totalCount": {
"description": "Total number of classes.",
"minimum": 1,
"type": "integer"
},
"value": {
"description": "Fairness score in relation to the privileged class fairness score.",
"maximum": 1,
"minimum": 0,
"type": "number"
}
},
"type": "object"
},
"type": "array"
}
},
"required": [
"metricName",
"period",
"scores"
],
"type": "object"
},
"type": "array"
},
"fairnessThreshold": {
"description": "Threshold used to compute fairness results.",
"maximum": 1,
"minimum": 0,
"type": "number"
},
"favorableTargetOutcome": {
"description": "Preferable class of target.",
"oneOf": [
{
"type": "boolean"
},
{
"type": "string"
},
{
"type": "integer"
}
]
},
"modelId": {
"description": "Model Id for which fairness is computed.",
"type": "string"
},
"modelPackageId": {
"description": "Model package Id.",
"type": "string"
},
"protectedFeature": {
"description": "Name of the protected feature.",
"type": "string"
},
"summary": {
"description": "Summary of per feature fairness.",
"properties": {
"metricName": {
"description": "Name of the metric.",
"enum": [
"proportionalParity",
"equalParity",
"favorableClassBalance",
"unfavorableClassBalance",
"trueUnfavorableRateParity",
"trueFavorableRateParity",
"favorablePredictiveValueParity",
"unfavorablePredictiveValueParity"
],
"type": "string"
},
"period": {
"description": "An object with the keys \"start\" and \"end\" defining the period.",
"properties": {
"end": {
"description": "End of the period to retrieve monitoring data, defaults to the next top of the hour. Note: this field only accepts top of the hour RFC3339 datetime strings, for example: ``2019-08-01T00:00:00Z``.",
"format": "date-time",
"type": [
"string",
"null"
]
},
"start": {
"description": "Start of the period to retrieve monitoring data, defaults to 7 days ago from the end of the period. Note: this field only accepts top of the hour RFC3339 datetime strings, for example: ``2019-08-01T00:00:00Z``.",
"format": "date-time",
"type": [
"string",
"null"
]
}
},
"type": "object"
},
"scores": {
"description": "List of per-feature fairness details.",
"items": {
"properties": {
"absoluteValue": {
"description": "Absolute fairness score.",
"type": "number"
},
"classesCount": {
"description": "Count of occurences of the class within the data the fairness is calculated on.",
"type": "integer"
},
"healthyClassesCount": {
"description": "Count of statistically significant classes above fairness threshold.",
"type": "integer"
},
"healthyCount": {
"description": "Total number of classes with fairness score above the threshold.",
"minimum": 0,
"type": "integer"
},
"isStatisticallySignificant": {
"description": "Class is statistically significant.",
"type": "boolean"
},
"label": {
"description": "Name of the feature.",
"type": "string"
},
"message": {
"description": "Explanation message.",
"type": "string"
},
"privilegedClass": {
"description": "Name of the privileged class (the one with the highest fairness score) within the feature.",
"type": "string"
},
"sampleSize": {
"description": "Sample size used for fairness status calculation",
"exclusiveMinimum": 0,
"type": "integer"
},
"totalCount": {
"description": "Total number of classes.",
"minimum": 1,
"type": "integer"
},
"value": {
"description": "Fairness score in relation to the privileged class fairness score.",
"maximum": 1,
"minimum": 0,
"type": "number"
}
},
"type": "object"
},
"type": "array"
}
},
"required": [
"metricName",
"period",
"scores"
],
"type": "object"
}
},
"required": [
"buckets",
"fairnessThreshold",
"favorableTargetOutcome",
"modelId",
"modelPackageId",
"summary"
],
"type": "object"
}
Properties¶
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| buckets | [FairnessOverTimeBucket] | true | Per bucket summary. | |
| fairnessThreshold | number | true | maximum: 1 minimum: 0 |
Threshold used to compute fairness results. |
| favorableTargetOutcome | any | true | Preferable class of target. |
oneOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | boolean | false | none |
xor
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none |
xor
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| modelId | string | true | Model Id for which fairness is computed. | |
| modelPackageId | string | true | Model package Id. | |
| protectedFeature | string | false | Name of the protected feature. | |
| summary | FairnessOverTimeBucket | true | Summary of per feature fairness. |
FairnessOverTimeScore
{
"properties": {
"absoluteValue": {
"description": "Absolute fairness score.",
"type": "number"
},
"classesCount": {
"description": "Count of occurences of the class within the data the fairness is calculated on.",
"type": "integer"
},
"healthyClassesCount": {
"description": "Count of statistically significant classes above fairness threshold.",
"type": "integer"
},
"healthyCount": {
"description": "Total number of classes with fairness score above the threshold.",
"minimum": 0,
"type": "integer"
},
"isStatisticallySignificant": {
"description": "Class is statistically significant.",
"type": "boolean"
},
"label": {
"description": "Name of the feature.",
"type": "string"
},
"message": {
"description": "Explanation message.",
"type": "string"
},
"privilegedClass": {
"description": "Name of the privileged class (the one with the highest fairness score) within the feature.",
"type": "string"
},
"sampleSize": {
"description": "Sample size used for fairness status calculation",
"exclusiveMinimum": 0,
"type": "integer"
},
"totalCount": {
"description": "Total number of classes.",
"minimum": 1,
"type": "integer"
},
"value": {
"description": "Fairness score in relation to the privileged class fairness score.",
"maximum": 1,
"minimum": 0,
"type": "number"
}
},
"type": "object"
}
Properties¶
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| absoluteValue | number | false | Absolute fairness score. | |
| classesCount | integer | false | Count of occurences of the class within the data the fairness is calculated on. | |
| healthyClassesCount | integer | false | Count of statistically significant classes above fairness threshold. | |
| healthyCount | integer | false | minimum: 0 |
Total number of classes with fairness score above the threshold. |
| isStatisticallySignificant | boolean | false | Class is statistically significant. | |
| label | string | false | Name of the feature. | |
| message | string | false | Explanation message. | |
| privilegedClass | string | false | Name of the privileged class (the one with the highest fairness score) within the feature. | |
| sampleSize | integer | false | Sample size used for fairness status calculation | |
| totalCount | integer | false | minimum: 1 |
Total number of classes. |
| value | number | false | maximum: 1 minimum: 0 |
Fairness score in relation to the privileged class fairness score. |
TimeRange
{
"description": "An object with the keys \"start\" and \"end\" defining the period.",
"properties": {
"end": {
"description": "End of the period to retrieve monitoring data, defaults to the next top of the hour. Note: this field only accepts top of the hour RFC3339 datetime strings, for example: ``2019-08-01T00:00:00Z``.",
"format": "date-time",
"type": [
"string",
"null"
]
},
"start": {
"description": "Start of the period to retrieve monitoring data, defaults to 7 days ago from the end of the period. Note: this field only accepts top of the hour RFC3339 datetime strings, for example: ``2019-08-01T00:00:00Z``.",
"format": "date-time",
"type": [
"string",
"null"
]
}
},
"type": "object"
}
An object with the keys "start" and "end" defining the period.
Properties¶
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| end | string,null(date-time) | false | End of the period to retrieve monitoring data, defaults to the next top of the hour. Note: this field only accepts top of the hour RFC3339 datetime strings, for example: 2019-08-01T00:00:00Z. |
|
| start | string,null(date-time) | false | Start of the period to retrieve monitoring data, defaults to 7 days ago from the end of the period. Note: this field only accepts top of the hour RFC3339 datetime strings, for example: 2019-08-01T00:00:00Z. |