Skip to content

Latest commit

 

History

History
392 lines (321 loc) · 17.7 KB

README.md

File metadata and controls

392 lines (321 loc) · 17.7 KB
Raw

The LinkedIn Fairness Toolkit (LiFT)

Build Status Release License

📣 We've moved from Bintray to Artifactory!

As of version 0.2.2, we are only publishing versions to LinkedIn's Artifactory instance rather than Bintray, which is approaching end of life.

Introduction

The LinkedIn Fairness Toolkit (LiFT) is a Scala/Spark library that enables the measurement of fairness and the mitigation of bias in large-scale machine learning workflows. The measurement module includes measuring biases in training data, evaluating fairness metrics for ML models, and detecting statistically significant differences in their performance across different subgroups. It can also be used for ad-hoc fairness analysis. The mitigation part includes a post-processing method for transforming model scores to ensure the so-called equality of opportunity for rankings (in the presence/absence of position bias). This method can be directly applied to the model-generated scores without changing the existing model training pipeline.

This library was created by Sriram Vasudevan and Krishnaram Kenthapadi (work done while at LinkedIn).

Additional Contributors:

  1. Preetam Nandy

Copyright

Copyright 2020 LinkedIn Corporation All Rights Reserved.

Licensed under the BSD 2-Clause License (the "License"). See License in the project root for license information.

Features

LiFT provides a configuration-driven Spark job for scheduled deployments, with support for custom metrics through User Defined Functions (UDFs). APIs at various levels are also exposed to enable users to build upon the library's capabilities as they see fit. One can thus opt for a plug-and-play approach or deploy a customized job that uses LiFT. As a result, the library can be easily integrated into ML pipelines. It can also be utilized in Jupyter notebooks for more exploratory fairness analyses.

LiFT leverages Apache Spark to load input data into in-memory, fault-tolerant and scalable data structures. It strategically caches datasets and any pre-computation performed. Distributed computation is balanced with single system execution to obtain a good mix of scalability and speed. For example, distance, distribution and divergence related metrics are computed on the entire dataset in a distributed manner, while benefit vectors and permutation tests (for model performance) are computed on scored dataset samples that can be collected to the driver.

The LinkedIn Fairness Toolkit (LiFT) provides the following capabilities:

  1. Measuring Fairness Metrics on Training Data
  2. Measuring Fairness Metrics for Model Performance
  3. Achieving Equality of Opportunity

As part of the model performance metrics, it also contains the implementation of a new permutation testing framework that detects statistically significant differences in model performance (as measured by an arbitrary performance metric) across different subgroups.

High-level details about the parameters, metrics supported and usage are described below. More details about the metrics themselves are provided in the links above.

A list of automatically downloaded direct dependencies are provided here.

Usage

Building the Library

It is recommended to use Scala 2.11.8 and Spark 2.3.0. To build, run the following:

./gradlew build

This will produce a JAR file in the ./lift/build/libs/ directory.

If you want to use the library with Spark 2.4 (and the Scala 2.11.8 default), you can specify this when running the build command.

./gradlew build -PsparkVersion=2.4.3

You can also build an artifact with Spark 2.4 and Scala 2.12.

./gradlew build -PsparkVersion=2.4.3 -PscalaVersion=2.12.11

Tests typically run with the test task. If you want to force-run all tests, you can use:

./gradlew cleanTest test --no-build-cache

To force rebuild the library, you can use:

./gradlew clean build --no-build-cache

Add a LiFT Dependency to Your Project

Please check Artifactory for the latest artifact versions.

Gradle Example

The artifacts are available in LinkedIn's Artifactory instance and in Maven Central, so you can specify either repository in the top-level build.gradle file.

repositories {
    mavenCentral()
    maven {
        url "https://linkedin.jfrog.io/artifactory/open-source/"
    }
}

Add the LiFT dependency to the module-level build.gradle file. Here are some examples for multiple recent Spark/Scala version combinations:

dependencies {
    compile 'com.linkedin.lift:lift_2.3.0_2.11:0.1.4'
}

dependencies {
    compile 'com.linkedin.lift:lift_2.4.3_2.11:0.1.4'
}

dependencies {
    compile 'com.linkedin.lift:lift_2.4.3_2.12:0.1.4'
}

Using the JAR File

Depending on the mode of usage, the built JAR can be deployed as part of an offline data pipeline, depended upon to build jobs using its APIs, or added to the classpath of a Spark Jupyter notebook or a Spark Shell instance. For example:

$SPARK_HOME/bin/spark-shell --jars target/lift_2.3.0_2.11_0.1.4.jar

Usage Examples

Measuring Dataset Fairness Metrics using the provided Spark job

LiFT provides a Spark job for measuring fairness metrics for training data, as well as for the validation or test dataset:

com.linkedin.fairness.eval.jobs.MeasureDatasetFairnessMetrics

This job can be configured using various parameters to compute fairness metrics on the dataset of interest:

1. datasetPath: Input data path
2. protectedDatasetPath: Input path to the protected dataset (optional).
                         If not provided, the library attempts to use
                         the right dataset based on the protected attribute.
3. dataFormat: Format of the input datasets. This is the parameter passed
              to the Spark reader's format method. Defaults to avro.
4. dataOptions: A map of options to be used with Spark's reader (optional).
5. uidField: The unique ID field, like a memberId field. It acts as the join key for the primary dataset.
6. labelField: The label field
7. protectedAttributeField: The protected attribute field
8. uidProtectedAttributeField: The uid field (join key) for the protected attribute dataset
9. outputPath: Output data path
10. referenceDistribution: A reference distribution to compare against (optional).
                          Only accepted value currently is UNIFORM.
11. distanceMetrics: Distance and divergence metrics like SKEWS, INF_NORM_DIST,
                    TOTAL_VAR_DIST, JS_DIVERGENCE, KL_DIVERGENCE and
                    DEMOGRAPHIC_PARITY (optional).
12. overallMetrics: Aggregate metrics like GENERALIZED_ENTROPY_INDEX,
                    ATKINSONS_INDEX, THEIL_L_INDEX, THEIL_T_INDEX and
                    COEFFICIENT_OF_VARIATION, along with their corresponding
                    parameters.
13. benefitMetrics: The distance/divergence metrics to use as the benefit
                    vector when computing the overall metrics. Acceptable
                    values are SKEWS and DEMOGRAPHIC_PARITY.

The most up-to-date information on these parameters can always be found here.

The Spark job performs no preprocessing of the input data, and makes assumptions like assuming that the unique ID field (the join key) is stored in the same format in the input data and the protectedAttribute data. This might not be the case for your dataset, in which case you can always create your own Spark job similar to the provided example (described below).

Measuring Model Fairness Metrics using the provided Spark job

LiFT provides a Spark job for measuring fairness metrics for model performance, based on the labels and scores of the test or validation data:

com.linkedin.fairness.eval.jobs.MeasureModelFairnessMetrics

This job can be configured using various parameters to compute fairness metrics on the dataset of interest:

1. datasetPath Input data path
2. protectedDatasetPath Input path to the protected dataset (optional).
                        If not provided, the library attempts to use
                        the right dataset based on the protected attribute.
3. dataFormat: Format of the input datasets. This is the parameter passed
              to the Spark reader's format method. Defaults to avro.
4. dataOptions: A map of options to be used with Spark's reader (optional).
5. uidField The unique ID field, like a memberId field. It acts as the join key for the primary dataset.
6. labelField The label field
7. scoreField The score field
8. scoreType Whether the scores are raw scores or probabilities.
             Accepted values are RAW or PROB.
9. protectedAttributeField The protected attribute field
10. uidProtectedAttributeField The uid field (join key) for the protected attribute dataset.
11. groupIdField An optional field to be used for grouping, in case of ranking metrics
12. outputPath Output data path
13. referenceDistribution A reference distribution to compare against (optional).
                          Only accepted value currently is UNIFORM.
14. approxRows The approximate number of rows to sample from the input data
               when computing model metrics. The final sampled value is
               min(numRowsInDataset, approxRows)
15. labelZeroPercentage The percentage of the sampled data that must
                        be negatively labeled. This is useful in case
                        the input data is highly skewed and you believe
                        that stratified sampling will not obtain sufficient
                        number of examples of a certain label.
16. thresholdOpt An optional value that contains a threshold. It is used
                 in case you want to generate hard binary classifications.
                 If not provided and you request metrics that depend on
                 explicit label predictions (eg. precision), the scoreType
                 information is used to convert the scores into the
                 probabilities of predicting positives. This is used for
                 computing expected positive prediction counts.
17. numTrials Number of trials to run the permutation test for. More trials
              yield results with lower variance in the computed p-value,
              but takes more time
18. seed The random value seed
19. distanceMetrics Distance and divergence metrics that are to be computed.
                    These are metrics such as Demographic Parity
                    and Equalized Odds.
20. permutationMetrics The metrics to use for permutation testing
21. distanceBenefitMetrics The model metrics that are to be used for
                           computing benefit vectors, one for each
                           distance metric specified.
22. performanceBenefitMetrics The model metrics that are to be used for
                              computing benefit vectors, one for each
                              model performance metric specified.
23. overallMetrics The aggregate metrics that are to be computed on each
                   of the benefit vectors generated.

The most up-to-date information on these parameters can always be found here.

The Spark job performs no preprocessing of the input data, and makes assumptions like assuming that the unique ID field (the join key) is stored in the same format in the input data and the protectedAttribute data. This might not be the case for your dataset, in which case you can always create your own Spark job similar to the provided example (described below)

Learning and Applying Equality of Opportunity (EOpp) on Local Datasets

An example is provided in EOppUtilsTest for applying the EOpp transformation to local datasets. We provide two simulated datasets TrainingData.csv and ValidationData.csv each containing 1M samples. The workflow is provided as a test function eOppTransformationTest() consisting of the following steps:

  1. Learning position bias corrected EOpp transformation using the training data
  2. Applying the EOpp transformation on the validation data
  3. Checking EOpp in the transformed validation data with position bias
  4. Checking the (optional) score distribution preserving property of the EOpp transformation

Custom Spark jobs built on LiFT

If you are implementing your own driver program to measure dataset metrics, here's how you can make use of LiFT:

object MeasureDatasetFairnessMetrics { 
  def main(progArgs: Array[String]): Unit = { 
    // Get spark session
    val spark = SparkSession 
      .builder() 
      .appName(getClass.getSimpleName) 
      .getOrCreate() 
 
    // Parse args
    val args = MeasureDatasetFairnessMetricsCmdLineArgs.parseArgs(progArgs) 
 
    // Load and preprocess data
    val df = spark.read.format(args.dataFormat)
      .load(args.datasetPath)
      .select(args.uidField, args.labelField)
 
    // Load protected data and join
    val joinedDF = ...
    joinedDF.persist 

    // Obtain reference distribution (optional). This can be used to provide a
    // custom distribution to compare the dataset against.
    val referenceDistrOpt = ...
 
    // Passing in the appropriate parameters to this API computes and writes 
    // out the fairness metrics 
    FairnessMetricsUtils.computeAndWriteDatasetMetrics(distribution,
      referenceDistrOpt, args) 
  } 
}

A complete example for the above can be found here.

In the case of measuring model metrics, a similar Spark job can be implemented:

object MeasureModelFairnessMetrics { 
  def main(progArgs: Array[String]): Unit = { 
    // Get spark session
    val spark = SparkSession 
      .builder() 
      .appName(getClass.getSimpleName) 
      .getOrCreate() 
 
    // Parse args
    val args = MeasureModelFairnessMetricsCmdLineArgs.parseArgs(progArgs) 
 
    // Load and preprocess data
    val df = spark.read.format(args.dataFormat)
      .load(args.datasetPath)
      .select(args.uidField, args.labelField)
 
    // Load protected data and join
    val joinedDF = ...
    joinedDF.persist 

    // Obtain reference distribution (optional). This can be used to provide a
    // custom distribution to compare the dataset against.
    val referenceDistrOpt = ...
 
    // Passing in the appropriate parameters to this API computes and writes 
    // out the fairness metrics 
    FairnessMetricsUtils.computeAndWriteModelMetrics(
      joinedDF, referenceDistrOpt, args) 
  } 
}

A complete example for the above can be found here.

Contributions

If you would like to contribute to this project, please review the instructions here.

Acknowledgments

Implementations of some methods in LiFT were inspired by other open-source libraries. LiFT also contains the implementation of a new permutation testing framework. Discussions with several LinkedIn employees influenced aspects of this library. A full list of acknowledgements can be found here.

Citations

If you publish material that references the LinkedIn Fairness Toolkit (LiFT), you can use the following citations:

@inproceedings{vasudevan20lift,
    author       = {Vasudevan, Sriram and Kenthapadi, Krishnaram},
    title        = {{LiFT}: A Scalable Framework for Measuring Fairness in ML Applications},
    booktitle    = {Proceedings of the 29th ACM International Conference on Information and Knowledge Management},
    series       = {CIKM '20},
    year         = {2020},
    pages        = {},
    numpages     = {8}
}

@misc{lift,
    author       = {Vasudevan, Sriram and Kenthapadi, Krishnaram},
    title        = {The LinkedIn Fairness Toolkit ({LiFT})},
    howpublished = {\url{https://github.com/linkedin/lift}},
    month        = aug,
    year         = 2020
}

If you publish material that references the permutation testing methodology that is available as part of LiFT, you can use the following citation:

@inproceedings{diciccio20evaluating,
    author       = {DiCiccio, Cyrus and Vasudevan, Sriram and Basu, Kinjal and Kenthapadi, Krishnaram and Agarwal, Deepak},
    title        = {Evaluating Fairness Using Permutation Tests},
    booktitle    = {Proceedings of the 26th ACM SIGKDD International Conference on Knowledge Discovery and Data Mining},
    series       = {KDD '20},
    year         = {2020},
    pages        = {},
    numpages     = {11}
}

If you publish material that references the equality of opportunity methodology that is available as part of LiFT, you can use the following citation:

@misc{nandy21mitigation,
   author        = {Preetam Nandy and Cyrus Diciccio and Divya Venugopalan and Heloise Logan and Kinjal Basu and Noureddine El Karoui},
   title         = {Achieving Fairness via Post-Processing in Web-Scale Recommender Systems}, 
   year          = {2021},
   eprint        = {2006.11350},
   archivePrefix = {arXiv}
}