API Reference

# Core installation
pip install vfairness

# With visualization support
pip install vfairness[viz]

# With MLflow integration
pip install vfairness[mlflow]

# Full installation (all optional dependencies)
pip install vfairness[all]

# Core only (numpy, pandas, scipy)
pip install vfairness

# With visualization
pip install vfairness[viz]

# With SVG rendering + dashboards
pip install vfairness[rendering,dashboard]

# With training-time interventions (PyTorch)
pip install vfairness[training]

# With MLOps integrations (MLflow + W&B)
pip install vfairness[mlops]

# Everything
pip install vfairness[all]

# Recommended: New module-based imports
from vfairness.preprocessing import (
    BiasDetector,
    FeatureEngineeringAnalyzer,
    detect_historical_patterns,
    identify_proxy_variables
)

from vfairness.post_processing import (
    # Calibration
    GroupCalibrator, CalibrationAnalyzer, expected_calibration_error,
    # Threshold Optimization
    GroupThresholdOptimizer, MultiObjectiveThresholdOptimizer,
    ThresholdAnalyzer, FairnessConstraintType,
    # Prediction Reweighting
    PredictionReweighter, RejectionOptionClassifier,
    CalibratedEqualizer, DistributionMatcher, ReweightingAnalyzer
)

from vfairness.evaluation import (
    FairnessAnalyzer,
    demographic_parity_difference,
    classification_fairness_report,
    print_report
)

from vfairness.operations import (
    DataBiasValidator,
    ModelFairnessGate,
    FairnessTestSuite
)

# Flat imports also work
from vfairness import FairnessAnalyzer, BiasDetector, GroupCalibrator

# Feature-specific imports
from vfairness import (
    # Classification metrics
    demographic_parity_difference,
    equalized_odds_difference,
    equal_opportunity_difference,
    predictive_parity_difference,

    # Regression metrics
    mae_parity_difference,
    rmse_parity_difference,
    mean_prediction_difference,

    # Ranking metrics
    exposure_parity_difference,
    attention_weighted_rank_fairness,

    # Reports
    classification_fairness_report,
    regression_fairness_report,
    print_report,

    # Statistical validation
    permutation_test,
    bootstrap_ci,
    compute_effect_sizes,
    proportion_z_test,
    fisher_exact_test,
    cohens_h,
    cohens_h_interpretation,
    minimum_detectable_effect,
    power_warning,

    # Auto-discovery
    detect_protected_attributes,
    identify_proxy_features,
    scan_fairness_violations,

    # MLOps
    log_fairness_to_mlflow,
    assert_fairness
)

from vfairness.preprocessing import BiasDetector, FeatureEngineeringAnalyzer

from vfairness import BiasDetector
import pandas as pd

# Your data
df = pd.read_csv('loan_applications.csv')

# Define population benchmarks
benchmarks = {
    'gender': {'Male': 0.49, 'Female': 0.51},
    'race': {'White': 0.60, 'Black': 0.13, 'Hispanic': 0.19, 'Asian': 0.06}
}

# Create detector
detector = BiasDetector(
    df,
    protected_attributes=['gender', 'race', 'age'],
    outcome_column='approved',
    benchmarks=benchmarks,
)

# Run full audit
report = detector.full_audit()

# Print summary
print(report.summary())
print(f"Overall Risk Score: {report.overall_risk_score:.1%}")
print(f"Critical Issues: {len(report.critical_issues)}")

# Get high-risk features
for feature in report.get_high_risk_features():
    print(f"  - {feature}")

from vfairness.preprocessing.bias_detection import SVI_THEMES, get_svi_data_url

# View available themes
for theme, desc in SVI_THEMES.items():
    print(f"{theme}: {desc}")

# Get download URL for SVI data
url = get_svi_data_url(year=2022)

ϕ² = χ² / n
ϕ²_corr = max(0,  ϕ² − (r−1)(k−1) / (n−1))
r̃ = r − (r−1)² / (n−1)
k̃ = k − (k−1)² / (n−1)
V_corr = √( ϕ²_corr / (min(r̃, k̃) − 1) )

where  r = rows,  k = columns,  n = sample size

from vfairness.preprocessing.feature_engineering import FeatureEngineeringAnalyzer

# Create analyzer
analyzer = FeatureEngineeringAnalyzer(
    df=loan_data,
    protected_attributes=['race', 'gender'],
    target_column='approved'
)

# Run comprehensive analysis
report = analyzer.full_analysis()
print(report.summary)

# View risk breakdown
print(f"Critical: {report.risk_summary['critical']}")
print(f"High: {report.risk_summary['high']}")

# Get recommendations
for rec in analyzer.get_feature_recommendations(top_n=5):
    print(f"[{rec['priority']}] {rec['feature']}: {rec['action']}")

# Transform features
X_fair = analyzer.transform(method='correlation_reduction')

# Compare different methods
comparison = analyzer.compare_transformations()
print(comparison)

from vfairness.preprocessing.feature_engineering import compute_feature_correlations

# Compute correlations
matrix = compute_feature_correlations(
    df=data,
    protected_attributes=['gender', 'race'],
    method='auto'  # Auto-selects Pearson, Cramér's V, or point-biserial
)

# View correlation matrix
print(matrix.correlations)

# Get high correlations
high_corr = matrix.get_high_correlations(threshold=0.3)
for feature, attr, corr in high_corr:
    print(f"{feature} ↔ {attr}: {corr:.3f}")

from vfairness.preprocessing.feature_engineering import KNOWN_PROXY_PATTERNS

# Race proxies: zip code, neighborhood, surname, school name
# Gender proxies: first name, title, occupation, field of study
# Age proxies: graduation year, years experience, birth year
# Income proxies: zip code, credit score, education level

from vfairness.preprocessing.feature_engineering import identify_proxy_variables

# Identify proxies
proxies = identify_proxy_variables(
    df=data,
    protected_attributes=['race', 'gender'],
    correlation_threshold=0.3
)

for proxy in proxies:
    print(f"\n{proxy.feature}:")
    print(f"  Risk: {proxy.risk_level.value}")
    print(f"  Correlation: {proxy.correlation:.3f} with {proxy.protected_attribute}")
    print(f"  Type: {proxy.proxy_type.value}")
    for rec in proxy.recommendations:
        print(f"  → {rec}")

from vfairness.preprocessing.feature_engineering import find_proxy_chains

chains = find_proxy_chains(df, 'race', correlation_threshold=0.3)

for chain in chains:
    print(f"Chain: {' → '.join(chain['chain'])}")
    print(f"  Indirect correlation: {chain['indirect_correlation']:.3f}")

from vfairness.preprocessing.feature_engineering import CorrelationReducer

# Create reducer
reducer = CorrelationReducer(
    protected_attributes=['gender', 'race'],
    method='residualize',  # 'residualize', 'decorrelate', 'partial'
    target_correlation=0.1,
    preserve_variance=True
)

# Fit and transform
X_fair = reducer.fit_transform(X)

# Check transformation result
print(f"Correlation before: {reducer.fit_result.correlation_before}")
print(f"Correlation after: {reducer.fit_result.correlation_after}")

from vfairness.preprocessing.feature_engineering import FeatureSuppressor

# Remove discriminatory features
suppressor = FeatureSuppressor(
    protected_attributes=['race'],
    strategy='remove',  # 'remove', 'mask', 'noise', 'bin'
    correlation_threshold=0.3,
    features_to_suppress=['zip_code', 'neighborhood']  # Optional: explicit list
)

X_fair = suppressor.fit_transform(X)
print(f"Features removed: {suppressor.fit_result.features_removed}")

from sklearn.pipeline import Pipeline
from sklearn.preprocessing import StandardScaler
from sklearn.linear_model import LogisticRegression
from vfairness.preprocessing.feature_engineering import CorrelationReducer

# Create fairness-aware pipeline
pipeline = Pipeline([
    ('fair_transform', CorrelationReducer(
        protected_attributes=['gender'],
        method='residualize'
    )),
    ('scaler', StandardScaler()),
    ('classifier', LogisticRegression())
])

# Fit pipeline
pipeline.fit(X_train, y_train)
predictions = pipeline.predict(X_test)

from vfairness.preprocessing.feature_engineering import (
    FeatureEngineeringAnalyzer,
    plot_correlation_heatmap,
    plot_feature_correlation_matrix,
    plot_proxy_risk_chart,
    create_analysis_dashboard
)
import matplotlib.pyplot as plt

# 1. Mixed-measure correlation heatmap (features × protected attributes)
#    Automatically picks Pearson, point-biserial, or Cramér's V per pair
analyzer = FeatureEngineeringAnalyzer(protected_attributes=['gender', 'race', 'age_group'])
analyzer.fit(df)

matrix = analyzer.get_correlation_matrix()   # method='auto' by default
ax = plot_correlation_heatmap(matrix, annotate=True,
                              title='Feature–Attribute Correlations')
plt.savefig('correlation_heatmap.png', dpi=300)

# 2. Pearson-only matrix (numeric features only — classic heatmap)
ax = plot_feature_correlation_matrix(
    df,
    feature_columns=['income', 'credit_score', 'years_employed', 'loan_amount'],
    annotate=True
)
plt.savefig('feature_correlation_matrix.png', dpi=300)

# 3. Proxy risk chart
proxies = analyzer.analyze_proxies()
ax = plot_proxy_risk_chart(proxies, max_features=15)
plt.savefig('proxy_risk_chart.png', dpi=300)

# 4. Comprehensive dashboard
fig = create_analysis_dashboard(
    correlation_matrix=matrix,
    proxy_variables=proxies
)
plt.savefig('feature_analysis_dashboard.png', dpi=300)

from vfairness.rendering import correlation_heatmap_to_svg, proxy_risk_to_svg

# SVG from correlation matrix — no Matplotlib needed
matrix = analyzer.get_correlation_matrix()
svg = correlation_heatmap_to_svg(matrix, save_path="corr_heatmap.svg")

# SVG from proxy analysis
proxies = analyzer.analyze_proxies()
svg = proxy_risk_to_svg(proxies, save_path="proxy_risk.svg")

from vfairness.in_processing import (
    # Scikit-learn wrappers
    FairClassifier, FairRegressor,
    # Analyzer
    FairnessTrainingAnalyzer, FairnessTrainingReport,
    # Loss functions (PyTorch)
    DemographicParityLoss, EqualizedOddsLoss, EqualOpportunityLoss,
    AdversarialDebiasingLoss, CounterfactualFairnessLoss,
    # Constraints
    ExponentiatedGradient, GridSearch, ThresholdOptimizer,
    DemographicParityConstraint, EqualizedOddsConstraint,
    # Regularizers
    StatisticalParityRegularizer, HilbertSchmidtRegularizer,
    # Calibrators
    TrainableGroupCalibrator, CalibrationAwareTrainer,
)

# Scikit-learn compatible approach (easiest)
from sklearn.ensemble import RandomForestClassifier
from vfairness.in_processing import FairClassifier

clf = FairClassifier(
    base_estimator=RandomForestClassifier(),
    fairness_constraint='demographic_parity',
    tolerance=0.05
)
clf.fit(X_train, y_train, sensitive_attr=gender)
y_pred = clf.predict(X_test)
print(f"Constraint satisfied: {clf.fairness_result_.constraint_satisfied}")

from sklearn.ensemble import RandomForestClassifier
from vfairness.in_processing import FairClassifier

# Create fair classifier
clf = FairClassifier(
    base_estimator=RandomForestClassifier(n_estimators=100),
    fairness_constraint='equalized_odds',  # or 'demographic_parity', 'equal_opportunity'
    tolerance=0.05,                         # Maximum allowed constraint violation
    method='reductions',                    # 'reductions', 'threshold', 'grid_search'
    max_iterations=50,
    verbose=True
)

# Fit (requires sensitive_attr)
clf.fit(X_train, y_train, sensitive_attr=gender)

# Predict
y_pred = clf.predict(X_test)

# Check fairness results
print(f"Accuracy: {clf.fairness_result_.accuracy:.4f}")
print(f"Violation: {clf.fairness_result_.fairness_violation:.4f}")
print(f"Satisfied: {clf.fairness_result_.constraint_satisfied}")

from sklearn.linear_model import Ridge
from vfairness.in_processing import FairRegressor

reg = FairRegressor(
    base_estimator=Ridge(),
    fairness_constraint='mean_parity',  # 'mean_parity', 'error_parity', 'bounded_loss'
    tolerance=0.1,
    method='reweighting'
)

reg.fit(X_train, y_train, sensitive_attr=group)
y_pred = reg.predict(X_test)

from sklearn.linear_model import LogisticRegression
from vfairness.in_processing import FairnessTrainingAnalyzer

# Create analyzer
analyzer = FairnessTrainingAnalyzer(
    X=X_train, y=y_train, sensitive_attr=gender,
    fairness_constraint='demographic_parity',
    tolerance=0.05
)

# Full analysis
report = analyzer.full_analysis(
    base_estimator=LogisticRegression(),
    include_comparisons=True,
    include_tradeoffs=True
)

# Print summary
print(report.summary())

# Export to JSON
report.to_json('training_analysis.json')

# Render as SVG
report.to_svg('training_report.svg')

import torch
from vfairness.in_processing import DemographicParityLoss

# Create loss function
loss_fn = DemographicParityLoss(
    lambda_fairness=0.1,  # Trade-off parameter
    warmup_epochs=5       # Epochs before applying fairness penalty
)

# Training loop
model = YourModel()
optimizer = torch.optim.Adam(model.parameters())

for epoch in range(num_epochs):
    loss_fn.set_epoch(epoch)

    for x, y, sensitive_attr in dataloader:
        optimizer.zero_grad()
        y_pred = torch.sigmoid(model(x))
        loss = loss_fn(y_pred, y, sensitive_attr)
        loss.backward()
        optimizer.step()

    # End of epoch tracking
    metrics = loss_fn.end_epoch()
    print(f"Epoch {epoch}: Loss={metrics.avg_total_loss:.4f}")

from vfairness.in_processing import AdversarialDebiasingLoss

loss_fn = AdversarialDebiasingLoss(
    lambda_fairness=1.0,
    adversary_hidden_dims=[64, 32],
    n_groups=2,
    use_gradient_reversal=True
)

# Move to GPU if available
loss_fn = loss_fn.to(device)

# Training loop
for x, y, sensitive_attr in dataloader:
    y_pred = torch.sigmoid(model(x))
    loss = loss_fn(y_pred, y, sensitive_attr)
    loss.backward()
    optimizer.step()

    # Monitor adversary accuracy (lower is more fair)
    adv_acc = loss_fn.get_adversary_accuracy(y_pred.detach(), sensitive_attr)

from vfairness.in_processing import CounterfactualFairnessLoss

loss_fn = CounterfactualFairnessLoss(
    lambda_fairness=0.1,
    counterfactual_strategy='group_swap',  # 'group_mean', 'group_swap', 'adversarial'
)

# Factory function for easy creation
from vfairness.in_processing import create_fairness_loss

loss_fn = create_fairness_loss(
    'demographic_parity',
    lambda_fairness=0.1,
    warmup_epochs=5
)

from sklearn.linear_model import LogisticRegression
from vfairness.in_processing import (
    ExponentiatedGradient,
    DemographicParityConstraint,
)

# Create constraint
constraint = DemographicParityConstraint(tolerance=0.05)

# Create algorithm
eg = ExponentiatedGradient(
    base_estimator=LogisticRegression(),
    constraint=constraint,
    max_iterations=50,
    verbose=True
)

# Fit
result = eg.fit(X_train, y_train, sensitive_attr=gender)

# Predict
y_pred = eg.predict(X_test)

# Check results
print(f"Accuracy: {result.accuracy:.4f}")
print(f"Violation: {result.final_violation:.4f}")
print(f"Converged: {result.optimization_result.converged}")

from vfairness.in_processing import GridSearch, EqualizedOddsConstraint

gs = GridSearch(
    base_estimator=LogisticRegression(),
    constraint=EqualizedOddsConstraint(tolerance=0.05),
    n_lambda_values=20,
    verbose=True
)

result = gs.fit(X_train, y_train, sensitive_attr=gender)
y_pred = gs.predict(X_test)

from sklearn.ensemble import RandomForestClassifier
from vfairness.in_processing import ThresholdOptimizer, EqualOpportunityConstraint

# First train a standard classifier
base_clf = RandomForestClassifier()
base_clf.fit(X_train, y_train)

# Get probabilities
y_prob_val = base_clf.predict_proba(X_val)[:, 1]

# Optimize thresholds for fairness
optimizer = ThresholdOptimizer(
    constraint=EqualOpportunityConstraint(tolerance=0.05),
    grid_size=100
)
optimizer.fit(y_prob_val, y_val, sensitive_attr=gender_val)

# Apply to test data
y_prob_test = base_clf.predict_proba(X_test)[:, 1]
y_pred_fair = optimizer.predict(y_prob_test, gender_test)

# Get the learned thresholds
print("Thresholds per group:", optimizer.get_thresholds())

import torch.nn.functional as F
from vfairness.in_processing import StatisticalParityRegularizer

regularizer = StatisticalParityRegularizer(strength=0.1)

# In training loop
for x, y, sensitive_attr in dataloader:
    y_pred = torch.sigmoid(model(x))

    # Task loss
    task_loss = F.binary_cross_entropy(y_pred, y)

    # Fairness penalty
    fairness_penalty = regularizer(y_pred, sensitive_attr)

    # Combined loss
    total_loss = task_loss + fairness_penalty
    total_loss.backward()

from vfairness.in_processing import (
    TrainableGroupCalibrator,
    CalibrationAwareTrainer,
)

# Create calibrator
calibrator = TrainableGroupCalibrator(
    n_groups=2,
    method='temperature',  # 'temperature', 'platt', 'beta', 'focal'
    learnable=True
)

# Integrate with model training
trainer = CalibrationAwareTrainer(model, calibrator)

# Training step
losses = trainer.train_step(
    x, y, group_ids,
    optimizer,
    task_loss_fn=F.cross_entropy,
    include_calibration=True
)

print(f"Task loss: {losses['task_loss']:.4f}")
print(f"Calibration loss: {losses['calibration_loss']:.4f}")

from sklearn.linear_model import LogisticRegression
from vfairness.in_processing import FairnessTrainingAnalyzer
from vfairness.rendering import (
    training_report_to_svg,
    training_analysis_report_to_svg,
    method_comparison_to_svg,
    tradeoff_analysis_to_svg
)

# Create analyzer and run full analysis
analyzer = FairnessTrainingAnalyzer(
    X=X_train, y=y_train, sensitive_attr=gender,
    fairness_constraint='demographic_parity',
    tolerance=0.05
)
report = analyzer.full_analysis(base_estimator=LogisticRegression())

# ★ Generate the comprehensive full-page report SVG (new!)
svg = training_analysis_report_to_svg(report, save_path='analysis_report.svg')

# Generate compact dashboard SVG
svg = training_report_to_svg(report, save_path='training_report.svg')

# Or generate individual visualizations
svg = method_comparison_to_svg(
    report.method_comparisons,
    save_path='method_comparison.svg'
)

svg = tradeoff_analysis_to_svg(
    report.tradeoff_analysis,
    save_path='tradeoff.svg'
)

# Use directly from report object
svg = report.to_svg(save_path='full_report.svg')

from vfairness.post_processing import (
    # Calibration
    GroupCalibrator, CalibrationAnalyzer, expected_calibration_error,
    # Threshold Optimization
    GroupThresholdOptimizer, MultiObjectiveThresholdOptimizer, ThresholdAnalyzer,
    # Prediction Reweighting
    PredictionReweighter, RejectionOptionClassifier, CalibratedEqualizer,
    DistributionMatcher, ReweightingAnalyzer
)

from vfairness.post_processing.calibration import (
    # Calibration metrics
    expected_calibration_error,
    calibration_disparity,
    # Group-specific calibration
    GroupCalibrator,
    # Trade-off analysis
    analyze_calibration_fairness_tradeoff,
    recommend_calibration_strategy,
)

# Evaluate calibration across groups
ece_result = expected_calibration_error(y_true, y_prob, gender)
print(f"Overall ECE: {ece_result.overall_value:.3f}")
print(f"ECE Disparity: {ece_result.max_group_disparity:.3f}")

# Apply group-specific calibration
calibrator = GroupCalibrator(method='isotonic')
calibrator.fit(y_true, y_prob, gender)
calibrated_probs = calibrator.transform(y_prob_test, gender_test)

from vfairness.post_processing.calibration import CalibrationAnalyzer

# Create analyzer
analyzer = CalibrationAnalyzer(
    y_true=labels,
    y_prob=probabilities,
    protected_attr=gender,
    attribute_name='gender'
)

# Run full analysis
report = analyzer.full_analysis(context='lending')

# Print summary
print(report.summary())

# Check key findings
print(f"Well Calibrated: {report.is_well_calibrated}")
print(f"Significant Disparity: {report.has_significant_disparity}")
print(f"ECE: {report.overall_metrics['ece']:.4f}")

# Get recommendations
for issue in report.critical_issues:
    print(f"[{issue['type']}] {issue['description']}")

# Fit calibrator and apply to new data
analyzer.fit_calibrator(method='isotonic')
calibrated_probs = analyzer.transform(y_prob_test, gender_test)

# Evaluate improvement
improvement = analyzer.evaluate_calibration_improvement()
print(f"ECE Before: {improvement['before']['overall_ece']:.4f}")
print(f"ECE After: {improvement['after']['overall_ece']:.4f}")
print(f"Improvement: {improvement['improvement']['overall_ece']:.4f}")

from vfairness.post_processing.calibration import PlattScaling

# Platt scaling fits logistic regression: P(y=1|f) = 1/(1 + exp(A*f + B))
calibrator = PlattScaling(regularization=0.0)
calibrator.fit(y_true, y_prob)
calibrated = calibrator.transform(y_prob_test)

# Access fitted parameters
print(f"A: {calibrator.a_:.4f}, B: {calibrator.b_:.4f}")

from vfairness.post_processing.calibration import IsotonicCalibrator

# Isotonic regression: non-parametric, preserves rank ordering
calibrator = IsotonicCalibrator(out_of_bounds='clip')
calibrator.fit(y_true, y_prob)
calibrated = calibrator.transform(y_prob_test)

# Access calibration thresholds
print(f"Number of isotonic segments: {len(calibrator.x_thresholds_)}")

from vfairness.post_processing.calibration import create_calibrator

# Create calibrator by name
calibrator = create_calibrator('isotonic')
calibrator = create_calibrator('platt', regularization=0.1)
calibrator = create_calibrator('beta', parameters='abm')
calibrator = create_calibrator('temperature')
calibrator = create_calibrator('histogram', n_bins=15)

from vfairness.post_processing.calibration import expected_calibration_error

# Compute ECE with group breakdown
result = expected_calibration_error(
    y_true, y_prob,
    protected_attr=gender,  # Optional: group analysis
    n_bins=10,
    strategy='uniform'  # or 'quantile'
)

print(f"Overall ECE: {result.overall_value:.4f}")
print(f"Is well-calibrated: {result.is_well_calibrated}")

# Per-group ECE
for group, ece in result.group_values.items():
    print(f"  {group}: {ece:.4f}")

# ECE disparity between groups
print(f"Max group disparity: {result.max_group_disparity:.4f}")

from vfairness.post_processing.calibration import brier_score_decomposition

# Decompose Brier = Reliability - Resolution + Uncertainty
decomp = brier_score_decomposition(y_true, y_prob, n_bins=10)

print(f"Brier Score: {decomp.brier_score:.4f}")
print(f"  Reliability: {decomp.reliability:.4f}")  # Lower is better
print(f"  Resolution: {decomp.resolution:.4f}")   # Higher is better
print(f"  Uncertainty: {decomp.uncertainty:.4f}") # Fixed for dataset
print(f"Skill Score: {decomp.skill_score:.4f}")   # Improvement over climatology

from vfairness.post_processing.calibration import calibration_disparity

# Comprehensive disparity analysis
result = calibration_disparity(y_true, y_prob, race)

print(f"ECE Disparity: {result.ece_disparity:.4f}")
print(f"MCE Disparity: {result.mce_disparity:.4f}")
print(f"Most miscalibrated: {result.most_miscalibrated_group}")
print(f"Significant disparity: {result.has_significant_disparity}")

# Recommendations
for rec in result.recommendations:
    print(f"  - {rec}")

from vfairness.post_processing.calibration import GroupCalibrator

# Fit group-specific calibrators
calibrator = GroupCalibrator(
    method='isotonic',          # Calibration method
    min_group_size=50,          # Min samples for group-specific
    fallback_strategy='global'  # For small groups: 'global', 'borrow', 'none'
)

calibrator.fit(y_true_train, y_prob_train, protected_attr_train)
calibrated_probs = calibrator.transform(y_prob_test, protected_attr_test)

# Get calibration improvement report
result = calibrator.get_calibration_result()
print(f"Overall ECE improvement: {result.overall_improvement:.4f}")

for group, improvement in result.improvement.items():
    pre_ece = result.pre_calibration_ece[group]
    post_ece = result.post_calibration_ece[group]
    print(f"  {group}: {pre_ece:.3f} → {post_ece:.3f} (Δ={improvement:.3f})")

from vfairness.post_processing.calibration import IntersectionalCalibrator
import pandas as pd

# Create intersectional groups (e.g., gender × race)
intersectional_attrs = pd.DataFrame({
    'gender': gender,
    'race': race
})

# Calibrate with hierarchical borrowing for small groups
calibrator = IntersectionalCalibrator(
    method='isotonic',
    min_group_size=30,
    borrowing_strategy='hierarchical'  # Borrow from parent groups
)

calibrator.fit(y_true, y_prob, intersectional_attrs)
calibrated = calibrator.transform(y_prob_test, intersectional_attrs_test)

from vfairness.post_processing.calibration import analyze_calibration_fairness_tradeoff

# Analyze trade-off at different thresholds
result = analyze_calibration_fairness_tradeoff(
    y_true, y_prob, gender,
    fairness_metric='fpr_parity',  # or 'fnr_parity', 'demographic_parity'
    thresholds=[0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9]
)

print(f"Trade-off severity: {result.tradeoff_severity}")
print(f"Base rate disparity: {result.base_rate_disparity:.3f}")

# Current model position
print(f"Current ECE: {result.current_point.calibration_error:.3f}")
print(f"Current fairness violation: {result.current_point.fairness_violation:.3f}")

# Recommendations
for rec in result.recommendations:
    print(f"  - {rec}")

from vfairness.post_processing.calibration import (
    analyze_calibration_fairness_tradeoff,
    plot_tradeoff_curve
)
import matplotlib.pyplot as plt

# 1. Compute the frontier
result = analyze_calibration_fairness_tradeoff(
    y_true, y_prob, gender,
    fairness_metric='fpr_parity',
    thresholds=[t / 20 for t in range(1, 20)]  # 0.05 to 0.95
)

# 2. Visualise: frontier + current model position
ax = plot_tradeoff_curve(
    result,
    highlight_current=True,      # Mark current operating point
    show_dominated=True,         # Show dominated region
    annotate_extremes=True       # Label the frontier endpoints
)
plt.title("Calibration–Fairness Pareto Frontier")
plt.xlabel("Calibration Error (ECE)")
plt.ylabel("Fairness Violation (FPR disparity)")
plt.savefig("pareto_frontier.png", dpi=300)

# 3. Find the closest frontier point to a target
target = result.nearest_pareto_point(
    max_calibration_error=0.05,
    max_fairness_violation=0.08
)
print(f"Recommended threshold: {target.threshold:.2f}")
print(f"ECE: {target.calibration_error:.3f}")
print(f"Fairness violation: {target.fairness_violation:.3f}")

from vfairness.post_processing.calibration import recommend_calibration_strategy

# Get context-aware recommendation
rec = recommend_calibration_strategy(
    y_true, y_prob, gender,
    context='lending'  # or 'risk_assessment', 'healthcare', 'hiring', 'general'
)

print(f"Strategy: {rec.strategy}")
print(f"Priority: {rec.priority}")
print(f"Rationale: {rec.rationale}")
if rec.expected_improvement:
    print(f"Expected ECE improvement: {rec.expected_improvement:.3f}")
if rec.tradeoff_warning:
    print(f"Warning: {rec.tradeoff_warning}")

from vfairness.post_processing.calibration import impossibility_diagnostics

# Diagnose impossibility theorem conditions
diag = impossibility_diagnostics(y_true, y_prob, race)

print(f"Base rates differ: {diag['base_rates_differ']}")
print(f"Impossibility theorem applies: {diag['impossibility_applies']}")
print(f"Base rate disparity: {diag['base_rate_disparity']:.3f}")
print(f"\nExplanation: {diag['explanation']}")

from vfairness import (
    plot_reliability_diagram,
    plot_group_calibration,
    create_calibration_dashboard
)
import matplotlib.pyplot as plt

# Basic reliability diagram
ax = plot_reliability_diagram(y_true, y_prob, n_bins=10, show_histogram=True)
plt.title("Model Calibration")
plt.savefig("reliability_diagram.png", dpi=300)

# Group-specific calibration
ax = plot_group_calibration(y_true, y_prob, gender, n_bins=10)
plt.title("Calibration by Gender")
plt.savefig("group_calibration.png", dpi=300)

# Comprehensive dashboard (before and after calibration)
fig = create_calibration_dashboard(
    y_true, y_prob, gender,
    calibrated_probs=calibrated_probs  # Optional: show improvement
)
plt.savefig("calibration_dashboard.png", dpi=300)

from vfairness.rendering import reliability_diagram_to_svg, pareto_frontier_to_svg

svg = reliability_diagram_to_svg(y_true, y_prob, n_bins=10, save_path="reliability.svg")

svg = pareto_frontier_to_svg(
    calibration_errors=[0.05, 0.08, 0.12, 0.03],
    fairness_violations=[0.10, 0.06, 0.03, 0.12],
    labels=["Platt", "Isotonic", "Beta", "Temperature"],
    save_path="pareto.svg"
)

from vfairness.post_processing import (
    GroupThresholdOptimizer,
    MultiObjectiveThresholdOptimizer,
    ThresholdAnalyzer,
    FairnessConstraintType
)

# Single-constraint optimization
optimizer = GroupThresholdOptimizer(
    constraint=FairnessConstraintType.DEMOGRAPHIC_PARITY,
    tolerance=0.05  # Allow 5% disparity
)
optimizer.fit(y_true, y_prob, sensitive_attr)
result = optimizer.get_optimal_thresholds()
# {'male': 0.52, 'female': 0.47}

# Multi-objective optimization (Pareto frontier)
multi_opt = MultiObjectiveThresholdOptimizer(
    constraints=[
        FairnessConstraintType.DEMOGRAPHIC_PARITY,
        FairnessConstraintType.EQUALIZED_ODDS
    ],
    n_thresholds=50  # Resolution of search
)
pareto_solutions = multi_opt.fit(y_true, y_prob, sensitive_attr)

# Comprehensive analysis
analyzer = ThresholdAnalyzer(y_true, y_prob, sensitive_attr)
report = analyzer.full_analysis()
print(report.summary())

from vfairness.post_processing import MultiObjectiveThresholdOptimizer

optimizer = MultiObjectiveThresholdOptimizer(
    constraints=[
        FairnessConstraintType.DEMOGRAPHIC_PARITY,
        FairnessConstraintType.EQUAL_OPPORTUNITY
    ],
    n_thresholds=100
)

# Get Pareto-optimal solutions
pareto_solutions = optimizer.fit(y_true, y_prob, sensitive_attr)

# Each solution includes:
# - thresholds: Dict[str, float] per-group thresholds
# - accuracy: float overall accuracy
# - fairness_metrics: Dict[str, float] per-constraint violation
# - is_pareto_optimal: bool

from vfairness.post_processing import ThresholdAnalyzer

analyzer = ThresholdAnalyzer(y_true, y_prob, sensitive_attr)

# Full analysis across all threshold configurations
report = analyzer.full_analysis()
print(report.summary())

# Compare specific threshold configurations
comparison = analyzer.compare_thresholds([
    {'male': 0.5, 'female': 0.5},   # Equal threshold
    {'male': 0.52, 'female': 0.47}  # Optimized for DP
])

# Sensitivity analysis
sensitivity = analyzer.threshold_sensitivity(
    base_thresholds={'male': 0.5, 'female': 0.5},
    perturbation_range=0.1
)

from vfairness.post_processing import (
    PredictionReweighter,
    RejectionOptionClassifier,
    CalibratedEqualizer,
    DistributionMatcher,
    ReweightingAnalyzer
)

# Simple multiplicative reweighting
reweighter = PredictionReweighter(
    method='multiplicative',
    constraint='demographic_parity'
)
reweighter.fit(y_true, y_prob, sensitive_attr)
y_prob_fair = reweighter.transform(y_prob, sensitive_attr)

# Rejection Option Classification (ROC)
roc = RejectionOptionClassifier(
    theta=0.1,  # Only modify predictions within ±0.1 of threshold
    constraint='demographic_parity'
)
roc.fit(y_true, y_prob, sensitive_attr)
y_pred_fair = roc.predict(y_prob, sensitive_attr)

from vfairness.post_processing import RejectionOptionClassifier

roc = RejectionOptionClassifier(
    theta=0.1,  # Critical region: [0.5 - θ, 0.5 + θ]
    constraint='demographic_parity'
)
roc.fit(y_true, y_prob, sensitive_attr)

# Returns binary predictions (not probabilities)
y_pred_fair = roc.predict(y_prob, sensitive_attr)

from vfairness.post_processing import CalibratedEqualizer

equalizer = CalibratedEqualizer(
    calibration_method='isotonic',  # 'platt', 'isotonic', 'beta'
    fairness_constraint='equalized_odds'
)
equalizer.fit(y_true, y_prob, sensitive_attr)
y_prob_fair = equalizer.transform(y_prob, sensitive_attr)

from vfairness.post_processing import ReweightingAnalyzer

analyzer = ReweightingAnalyzer(y_true, y_prob, sensitive_attr)

# Compare all methods
report = analyzer.full_analysis()
print(report.summary())
print(f"Recommended method: {report.best_method}")

# Output:
# Reweighting Analysis Report
# ==================================================
# Analyzed 5 reweighting methods
# Recommended method: rejection_option
#
# Recommendations:
#   • For maximum fairness improvement, use 'distribution_matching'
#   • 'rejection_option' preserves accuracy best (no accuracy loss)
#   • Overall recommendation: 'rejection_option' provides the best trade-off

from vfairness.evaluation import (
    FairnessAnalyzer,
    demographic_parity_difference,
    classification_fairness_report,
    print_report
)

from vfairness import FairnessAnalyzer
import numpy as np

# Sample data
y_true = np.array([1, 0, 1, 0, 1, 0, 1, 0] * 50)
y_pred = np.array([1, 0, 1, 1, 1, 0, 0, 0] * 50)
gender = np.array(['M', 'M', 'M', 'M', 'F', 'F', 'F', 'F'] * 50)

# Create analyzer
analyzer = FairnessAnalyzer(
    y_true=y_true,
    y_pred=y_pred,
    sensitive_attr=gender,
    fair_explainer=True
)

# Compute single metric
dp = analyzer.demographic_parity_difference()
print(f"Demographic Parity Difference: {dp:.3f}")

# Compute with confidence interval
result = analyzer.demographic_parity_difference(
    include_ci=True,
    n_bootstrap=5000,
    confidence_level=0.95
)
print(f"Value: {result.value:.3f}")
print(f"95% CI: [{result.ci_lower:.3f}, {result.ci_upper:.3f}]")

# Generate full report
report = analyzer.get_report(include_ci=True)
print(f"Fairness Score: {report['assessment']['fairness_score']:.1%}")

# Enable FairExplAIner via constructor
analyzer = FairnessAnalyzer(
    y_true, y_pred, sensitive_attr,
    fair_explainer=True
)

# Or enable after creation
analyzer.enable_fair_explainer()

# Get explanation for a specific metric
explanation = analyzer.explain_metric('demographic_parity_difference')
print(explanation.summary)        # Plain-language summary
print(explanation.recommendation)  # Actionable next steps

import pandas as pd
from vfairness import BiasDetector
from vfairness.explainer import FairnessExplainer

# 1. Run an analysis
df = pd.read_csv("loan_applications.csv")
detector = BiasDetector(protected_features=["gender", "ethnicity"])
report = detector.full_audit(df)

# 2. Get the explanation  (Option A — convenience method)
explanation = detector.get_explanation(report)

# 3. Inspect the ExplanationReport
print(explanation.title)          # "Bias Audit Explanation"
print(explanation.severity)       # "medium"
print(explanation.summary)        # one-paragraph narrative
print(explanation.recommendations)# ["Review representation ...", ...]

# 4. Iterate individual metric explanations
for metric in explanation.explanations:
    print(f"{metric.metric_name}: {metric.severity}")
    print(f"  → {metric.recommendation}")

# 5. Serialise to dict (for dashboards / APIs)
data = explanation.to_dict()

from vfairness.explainer import FairnessExplainer, ExplanationReport
from vfairness.evaluation.vfairness_metrics.explainer import MetricExplanation

def _explain_my_result(result) -> ExplanationReport:
    return ExplanationReport(
        title="My Custom Analysis",
        summary=f"Custom analysis found score={result.score:.2f}.",
        explanations=[
            MetricExplanation(
                metric_name="Custom Score",
                definition="My custom fairness metric.",
                interpretation_guide="Lower is better.",
                value=result.score,
                evaluation="Within acceptable range.",
                recommendation="No action needed.",
                severity="info",
            )
        ],
        severity="info",
        recommendations=["Continue monitoring."],
    )

# Register it
FairnessExplainer.register("MyCustomResult", _explain_my_result)

# Now it works with your type
explanation = FairnessExplainer.explain(my_result)

from vfairness import demographic_parity_difference_with_ci

result = demographic_parity_difference_with_ci(
    y_true, y_pred, sensitive_attr,
    min_group_size=30,
    n_bootstrap=5000,
    confidence_level=0.95,
    method='auto',  # 'bootstrap', 'bayesian', or 'auto'
    random_state=42
)

# Returns StatisticalResult object
print(f"Point Estimate: {result.point_estimate:.3f}")
print(f"95% CI: [{result.lower_bound:.3f}, {result.upper_bound:.3f}]")
print(f"Standard Error: {result.standard_error:.4f}")
print(f"Method: {result.method_used}")
print(f"Interval Type: {result.interval_type}")  # 'confidence' or 'credible'