Distances

Mahalanobis distance

class inFairness.distances.MahalanobisDistances

Base class implementing the Generalized Mahalanobis Distances

Mahalanobis distance between two points X1 and X2 is computed as:

\[\text{dist}(X_1, X_2) = (X_1 - X_2) \Sigma (X_1 - X_2)^{T}\]

fit(sigma)

Fit Mahalanobis Distance metric

Parameters:

sigma (torch.Tensor) – Covariance matrix

forward(X1, X2, itemwise_dist=True)

Computes the distance between data samples X1 and X2

Parameters:

• X1 (torch.Tensor) – Data samples from batch 1 of shape (n_samples_1, n_features)

• X2 (torch.Tensor) – Data samples from batch 2 of shape (n_samples_2, n_features)

• itemwise_dist (bool, default: True) –

  Compute the distance in an itemwise manner or pairwise manner.

  In the itemwise fashion (itemwise_dist=False), distance is computed between the ith data sample in X1 to the ith data sample in X2. Thus, the two data samples X1 and X2 should be of the same shape

  In the pairwise fashion (itemwise_dist=False), distance is computed between all the samples in X1 and all the samples in X2. In this case, the two data samples X1 and X2 can be of different shapes.

Returns:

dist – Distance between samples of batch 1 and batch 2.

If itemwise_dist=True, item-wise distance is returned of shape (n_samples, 1)

If itemwise_dist=False, pair-wise distance is returned of shape (n_samples_1, n_samples_2)

Return type:

torch.Tensor

to(device)

Moves distance metric to a particular device

Parameters:

device (torch.device) –

Sensitive Subspace distance

class inFairness.distances.SensitiveSubspaceDistance

Implements Sensitive Subspace metric base class that accepts the basis vectors of a sensitive subspace, and computes a projection that ignores the sensitive subspace.

The projection from the sensitive subspace basis vectors (A) is computed as:

\[P^{'} = I - (A (A A^{T})^{-1} A^{T})\]

compute_projection_complement(basis_vectors)

Compute the projection complement of the space defined by the basis_vectors:

projection complement given basis vectors (A) is computed as:

\[P^{'} = I - (A (A A^{T})^{-1} A^{T})\]

Parameters:

basis_vectors (torch.Tensor) – Basis vectors of the sensitive subspace Dimension (d, k) where d is the data features dimension and k is the number of protected dimensions

Returns:

projection complement – Projection complement computed as described above. Shape (d, d) where d is the data feature dimension

Return type:

torch.Tensor

fit(basis_vectors)

Fit Sensitive Subspace Distance metric

Parameters:

basis_vectors (torch.Tensor) – Basis vectors of the sensitive subspace

SVD Sensitive Subspace

class inFairness.distances.SVDSensitiveSubspaceDistance

Sensitive Subspace metric that uses SVD to find the basis vectors of the sensitive subspace. The metric learns a subspace from a set of user-curated comparable data samples.

Proposed in Section B.2 of Training individually fair ML models with sensitive subspace robustness

References

Yurochkin, Mikhail, Amanda Bower, and Yuekai Sun. “Training individually fair ML models with sensitive subspace robustness.” arXiv preprint arXiv:1907.00020 (2019).

compute_basis_vectors(X_train, n_components)

Compute basis vectors using SVD

fit(X_train, n_components, autoinfer_device=True)

Fit SVD Sensitive Subspace distance metric parameters

Parameters:

• X_train (torch.Tensor | List[torch.Tensor]) – Training data containing comparable data samples. If only one set of comparable data samples is provided, the input should be a torch.Tensor of shape \((N, D)\). For multiple sets of comparable data samples a list of shape \([ (N_1, D), \cdots, (N_x, D)]\) can be provided.

• n_components (int) – Desired number of latent variable dimensions

• autoinfer_device (bool) – Should the distance metric be automatically moved to an appropriate device (CPU / GPU) or not? If set to True, it moves the metric to the same device X_train is on. If set to False, keeps the metric on CPU.

EXPLORE: Embedded Xenial Pairs Logistic Regression

class inFairness.distances.EXPLOREDistance

Implements the Embedded Xenial Pairs Logistic Regression metric (EXPLORE) defined in Section 2.2 of Two Simple Ways to Learn Individual Fairness Metrics from Data.

EXPLORE defines the distance in the input space to be of the form:

\[d_x(x_1, x_2) := \langle \phi(x_1) - \phi(x_2), \Sigma (\phi(x_1) - \phi(x_2)) \rangle\]

where \(\phi(x)\) is an embedding map and \(\Sigma\) is a semi-positive definite matrix.

The metric expects the data to be in the form of triplets \(\{(x_{i_1}, x_{i_2}, y_i)\}_{i=1}^{n}\) where \(y_i \in \{0, 1\}\) indicates whether the human considers \(x_{i_1}\) and \(x_{i_2}\) comparable (\(y_i = 1\) indicates comparable) or not.

References

Mukherjee, Debarghya, Mikhail Yurochkin, Moulinath Banerjee, and Yuekai Sun. “Two simple ways to learn individual fairness metrics from data.” In International Conference on Machine Learning, pp. 7097-7107. PMLR, 2020.

fit(X1, X2, Y, iters, batchsize, autoinfer_device=True)

Fit EXPLORE distance metric

Parameters:

• X1 (torch.Tensor) – first set of input samples

• X2 (torch.Tensor) – second set of input samples

• Y (torch.Tensor) – \(y_i\) vector containing 1 if corresponding elements from X1 and X2 are comparable, and 0 if not

• iters (int) – number of iterations of SGD to compute the \(\Sigma\) matrix

• batchsize (int) – batch size of each iteration

• autoinfer_device (bool) – Should the distance metric be automatically moved to an appropriate device (CPU / GPU) or not? If set to True, it moves the metric to the same device X1 is on. If set to False, keeps the metric on CPU.

Logistic Regression Sensitive Subspace distance metric

class inFairness.distances.LogisticRegSensitiveSubspace

Implements the Softmax Regression model based fair metric as defined in Appendix B.1 of “Training individually fair ML models with sensitive subspace robustness” paper.

This metric assumes that the sensitive attributes are discrete and observed for a small subset of training data. Assuming data of the form \((X_i, K_i, Y_i)\) where \(K_i\) is the sensitive attribute of the i-th subject, the model fits a softmax regression model to the data as:

\[\mathbb{P}(K_i = l\mid X_i) = \frac{\exp(a_l^TX_i+b_l)}{\sum_{l=1}^k \exp(a_l^TX_i+b_l)},\ l=1,\ldots,k\]

Using the span of the matrix \(A=[a_1, \cdots, a_k]\), the fair metric is trained as:

\[d_x(x_1,x_2)^2 = (x_1 - x_2)^T(I - P_{\text{ran}(A)})(x_1 - x_2)\]

References

Yurochkin, Mikhail, Amanda Bower, and Yuekai Sun. “Training individually fair ML models with sensitive subspace robustness.” arXiv preprint arXiv:1907.00020 (2019).

fit(data_X: Tensor, data_SensitiveAttrs: Tensor | None = None, protected_idxs: Iterable[int] | None = None, keep_protected_idxs: bool = True, autoinfer_device: bool = True)

Fit Logistic Regression Sensitive Subspace distance metric

Parameters:

• data_X (torch.Tensor) – Input data corresponding to either \(X_i\) or \((X_i, K_i)\) in the equation above. If the variable corresponds to \(X_i\), then the y_train parameter should be specified. If the variable corresponds to \((X_i, K_i)\) then the protected_idxs parameter should be specified to indicate the sensitive attributes.

• data_SensitiveAttrs (torch.Tensor) – Represents the sensitive attributes ( \(K_i\) ) and is used when the X_train parameter represents \(X_i\) from the equation above. Note: This parameter is mutually exclusive with the protected_idxs parameter. Specififying both the data_SensitiveAttrs and protected_idxs parameters will raise an error

• protected_idxs (Iterable[int]) – If the X_train parameter above represents \((X_i, K_i)\), then this parameter is used to provide the indices of sensitive attributes in X_train. Note: This parameter is mutually exclusive with the protected_idxs parameter. Specififying both the data_SensitiveAttrs and protected_idxs parameters will raise an error

• keep_protected_indices (bool) – True, if while training the model, protected attributes will be part of the training data Set to False, if for training the model, protected attributes will be excluded Default = True

• autoinfer_device (bool) – Should the distance metric be automatically moved to an appropriate device (CPU / GPU) or not? If set to True, it moves the metric to the same device X_train is on. If set to False, keeps the metric on CPU.

property logistic_regression_models

Logistic Regression models trained by the metric to predict each sensitive attribute given inputs. The property is a list of logistic regression models each corresponding to \(\mathbb{P}(K_i = l\mid X_i)\). This property can be used to measure the performance of the logistic regression models.

Protected Euclidean Distance

class inFairness.distances.ProtectedEuclideanDistance

fit(protected_attributes, num_attributes)

Fit Protected Euclidean Distance metric

Parameters:

• protected_attributes (Iterable[int]) – List of attribute indices considered to be protected. The metric would ignore these protected attributes while computing distance between data points.

• num_attributes (int) – Total number of attributes in the data points.

forward(x, y, itemwise_dist=True)

Parameters:

y (x,) – a B x D matrices

Returns:

B x 1 matrix with the protected distance camputed between x and y

to(device)

Moves distance metric to a particular device

Parameters:

device (torch.device) –

Euclidean Distance

class inFairness.distances.EuclideanDistance

forward(x, y, itemwise_dist=True)

Subclasses must override this method to compute particular distances

Returns:

distance between two inputs

Return type:

Tensor

Wasserstein Distance

class inFairness.distances.WassersteinDistance

computes a batched Wasserstein Distance for pairs of sets of items on each batch in the tensors with dimensions B, N, D and B, M, D where B and D are the batch and feature sizes and N and M are the number of items on each batch.

Currently only supporting distances inheriting from :class: MahalanobisDistances.

transforms an Mahalanobis Distance object so that the forward method becomes a differentiable batched Wasserstein distance between sets of items. This Wasserstein distance will use the underlying Mahalanobis distance as pairwise cost function to solve the optimal transport problem.

for more information see equation 2.5 of the reference bellow

References

Amanda Bower, Hamid Eftekhari, Mikhail Yurochkin, Yuekai Sun: Individually Fair Rankings. ICLR 2021

forward(X1: Tensor, X2: Tensor)

computes a batch wasserstein distance implied by the cost function represented by an underlying mahalanobis distance.

Parameters:

• X1 (torch.Tensor) – Data sample of shape (B, N, D)

• X2 (torch.Tensor) – Data sample of shape (B, M, D)

Returns:

dist – Wasserstein distance of shape (B) between batch samples in X1 and X2

Return type:

torch.Tensor