fair_seldonian.constraints package

Submodules

fair_seldonian.constraints.bounds module

fair_seldonian.constraints.bounds.eval_math_bound(l_x, u_x, l_y=None, u_y=None, operator=None)[source]
Parameters:

  • l_x (Bound | None)

  • u_x (Bound | None)

  • l_y (Bound | None)

  • u_y (Bound | None)

  • operator (str | None)

Return type:

tuple[Bound | None, Bound | None]

fair_seldonian.constraints.bounds.eval_abs_bound(l_x, u_x)[source]
Parameters:

  • l_x (Bound | None) – lower bound

  • u_x (Bound | None) – upper bound

Returns:

lower and upper bound of abs operation

Return type:

tuple[Bound | None, Bound | None]

fair_seldonian.constraints.bounds.eval_div_bound(l_x, u_x, l_y, u_y)[source]
Parameters:

  • l_x (Bound | None) – lower bound of left child

  • u_x (Bound | None) – upper bound of left child

  • l_y (Bound | None) – lower bound of right child

  • u_y (Bound | None) – upper bound of right child

Returns:

lower and upper bound of div operation

Return type:

tuple[Bound | None, Bound | None]

fair_seldonian.constraints.bounds.eval_multiply_bound(l_x, u_x, l_y, u_y)[source]
Parameters:

  • l_x (Bound | None) – lower bound of left child

  • u_x (Bound | None) – upper bound of left child

  • l_y (Bound | None) – lower bound of right child

  • u_y (Bound | None) – upper bound of right child

Returns:

lower and upper bound of multiply operation

Return type:

tuple[Bound | None, Bound | None]

fair_seldonian.constraints.bounds.eval_subtract_bound(l_x, u_x, l_y, u_y)[source]
Parameters:

  • l_x (Bound | None) – lower bound of left child

  • u_x (Bound | None) – upper bound of left child

  • l_y (Bound | None) – lower bound of right child

  • u_y (Bound | None) – upper bound of right child

Returns:

lower and upper bound of subtract operation

Return type:

tuple[Bound | None, Bound | None]

fair_seldonian.constraints.bounds.eval_add_bound(l_x, u_x, l_y, u_y)[source]
Parameters:

  • l_x (Bound | None) – lower bound of left child

  • u_x (Bound | None) – upper bound of left child

  • l_y (Bound | None) – lower bound of right child

  • u_y (Bound | None) – upper bound of right child

Returns:

lower and upper bound of add operation

Return type:

tuple[Bound | None, Bound | None]

fair_seldonian.constraints.expression_tree module

class fair_seldonian.constraints.expression_tree.ExprTree(value)[source]

Bases: object

An expression tree node of the constraint tree

Parameters:

value (str)

fair_seldonian.constraints.expression_tree.is_operator(element)[source]
Parameters:

element (str)

Return type:

bool

fair_seldonian.constraints.expression_tree.is_mod(element)[source]
Parameters:

element (str)

Return type:

bool

fair_seldonian.constraints.expression_tree.is_func(element)[source]
Parameters:

element (str)

Return type:

bool

fair_seldonian.constraints.expression_tree.construct_expr_tree_base(rev_polish_notation: str, node_class: None = None) → ExprTree[source]
fair_seldonian.constraints.expression_tree.construct_expr_tree_base(rev_polish_notation: str, node_class: type[_NodeT]) → _NodeT

Returns root of constructed tree for given postfix expression

Parameters:

  • rev_polish_notation (str) – string with space as delimiter ‘ ‘

  • node_class (type[ExprTree] | None) – the tree node class to use (default: ExprTree)

Returns:

ExprTree node

Return type:

ExprTree

fair_seldonian.constraints.expression_tree.eval_expr_tree_base(t_node, Y, predicted_Y, T)[source]

A utility function to evaluate estimate of the expression tree

Parameters:

  • t_node (ExprTree | None) – ExprTree node

  • Y (Array | None) – pandas::Series

  • predicted_Y (torch.Tensor | None) – tensor

  • T (Array | None) – pandas::Series

Returns:

estimate value: float

Return type:

Bound | None

fair_seldonian.constraints.expression_tree.eval_expr_tree_conf_interval_base(t_node, Y, predicted_Y, T, delta, inequality, candidate_safety_ratio, predict_bound, modified_h)[source]

To evaluate confidence interval of the expression tree

Parameters:

  • t_node (ExprTree | None) – ExprTree node

  • Y (Array) – pandas::Series The true labels of the dataset

  • predicted_Y (torch.Tensor) – tensor The predicted labels of the dataset

  • T (Array) – pandas::Series The sensitive attributes of the dataset

  • delta (float) – float in [0, 1] The significance level

  • inequality (Inequality) – Enum The inequality to be used - Hoeffding/T-test

  • candidate_safety_ratio (float | None) – The candidate to safety ratio used in the experiment

  • predict_bound (bool) – Whether we are finding bound for candidate or safety data

  • modified_h (bool) – Whether modified confidence bound is used

Returns:

upper and lower bound of the estimate of the constraint

Return type:

tuple[Bound | None, Bound | None]

fair_seldonian.constraints.expression_tree.inorder(t_node)[source]

A utility function to log inorder traversal

Parameters:

t_node (ExprTree | None) – ExprTree node

Returns:

None

Return type:

None

fair_seldonian.constraints.expression_tree_ext module

class fair_seldonian.constraints.expression_tree_ext.ExprTree(value)[source]

Bases: ExprTree

Extended expression tree node with delta tracking

Parameters:

value (str)

left: ExprTree | None
right: ExprTree | None
delta: float
add_delta(delta)[source]
Parameters:

delta (float)

Return type:

None

fair_seldonian.constraints.expression_tree_ext.construct_expr_tree(rev_polish_notation, delta, check_bound, check_constant)[source]

Returns root of constructed tree for given postfix expression

Parameters:

  • rev_polish_notation (str) – string with space as delimiter ‘ ‘

  • delta (float)

  • check_bound (bool)

  • check_constant (bool)

Returns:

ExprTree node

Return type:

ExprTree

fair_seldonian.constraints.expression_tree_ext.configure_delta(t_node, delta, check_bound, check_constant)[source]
Parameters:
Return type:

None

fair_seldonian.constraints.expression_tree_ext.add_deltas_constant(t_node, delta)[source]
Parameters:
Return type:

None

fair_seldonian.constraints.expression_tree_ext.add_deltas(t_node, delta)[source]
Parameters:
Return type:

None

fair_seldonian.constraints.expression_tree_ext.check_node_dup(t_node, hash_map)[source]
Parameters:
Return type:

None

fair_seldonian.constraints.expression_tree_ext.is_constant(t_node_value)[source]
Parameters:

t_node_value (str)

Return type:

bool

fair_seldonian.constraints.expression_tree_ext.change_deltas(t_node, hash_map)[source]
Parameters:
Return type:

None

fair_seldonian.constraints.expression_tree_ext.change_delta_value(t_node, element, delta)[source]
Parameters:
Return type:

None

fair_seldonian.constraints.expression_tree_ext.eval_expr_tree(t_node, Y=None, predicted_Y=None, T=None)[source]
Parameters:

  • t_node (_BaseExprTree | None)

  • Y (Array | None)

  • predicted_Y (torch.Tensor | None)

  • T (Array | None)

Return type:

Bound | None

fair_seldonian.constraints.expression_tree_ext.eval_expr_tree_conf_interval(t_node, Y, predicted_Y, T, inequality, candidate_safety_ratio, predict_bound, modified_h)[source]
Parameters:
Return type:

tuple[Bound | None, Bound | None]

fair_seldonian.constraints.expression_tree_ext.inorder_ext(t_node)[source]
Parameters:

t_node (ExprTree | None)

Return type:

None

fair_seldonian.constraints.inequalities module

fair_seldonian.constraints.inequalities.group_mask(T, group)[source]

Boolean mask of rows whose sensitive attribute equals group (cached).

Parameters:

  • T (Array)

  • group (str)

Return type:

Array

fair_seldonian.constraints.inequalities.eval_estimate(element, Y, predicted_Y, T)[source]

Estimates the value of the base variable. Assumes that Y and predicted_y contain 0,1 binary classification. Suppose we are calculating for FP(A). Assume X to be an indicator function defined only in case type=A s.t. x_i = 1 if FP occurred for ith datapoint and x_i = 0 otherwise. Our data samples can be assumed to be independent and identically distributed. Our estimate of p, hat{p} = 1/n * sum(x_i). We can safely count this as binomial random variable. E[hat{p}] = 1/n * np = p. As we do not know p, we approximate it to hat{p}.

Parameters:

  • element (str) – expr_tree node

  • Y (Array) – pandas::Series

  • predicted_Y (torch.Tensor) – tensor

  • T (Array) – pandas::Series

Returns:

estimate value: float

Return type:

torch.Tensor

fair_seldonian.constraints.inequalities.eval_func_bound(element, Y, predicted_Y, T, delta, inequality, candidate_safety_ratio, predict_bound, modified_h)[source]
Parameters:
Return type:

tuple[Bound, Bound]

class fair_seldonian.constraints.inequalities.Inequality(*values)[source]

Bases: Enum

The Enum defining the inequality type. Currently, it supports T-test and Hoeffding.

T_TEST = 1
HOEFFDING_INEQUALITY = 2
fair_seldonian.constraints.inequalities.get_num_of_elements(element, Y)[source]
Parameters:

  • element (str)

  • Y (Array)

Return type:

int

fair_seldonian.constraints.inequalities.eval_hoeffding(estimate, num_of_elements, delta)[source]
Parameters:

  • estimate (Bound)

  • num_of_elements (int)

  • delta (float)

Return type:

tuple[Bound, Bound]

fair_seldonian.constraints.inequalities.predict_hoeffding(estimate, safety_size, delta)[source]
Parameters:

  • estimate (Bound)

  • safety_size (float)

  • delta (float)

Return type:

tuple[Bound, Bound]

fair_seldonian.constraints.inequalities.predict_hoeffding_modified(estimate, num_of_elements, safety_size, delta)[source]
Parameters:

  • estimate (Bound)

  • num_of_elements (float)

  • safety_size (float)

  • delta (float)

Return type:

tuple[Bound, Bound]

fair_seldonian.constraints.inequalities.get_variance(element, estimate, predicted_Y, T, num_of_elements)[source]
Parameters:

  • element (str)

  • estimate (Bound)

  • predicted_Y (torch.Tensor)

  • T (Array)

  • num_of_elements (int)

Return type:

float

fair_seldonian.constraints.inequalities.eval_t_test(estimate, variance, num_of_elements, delta)[source]
Parameters:

  • estimate (Bound)

  • variance (float)

  • num_of_elements (int)

  • delta (float)

Return type:

tuple[Bound, Bound]

fair_seldonian.constraints.inequalities.predict_t_test(estimate, variance, safety_size, delta)[source]
Parameters:
Return type:

tuple[Bound, Bound]

Module contents