Referencia de Métricas

Venturalitica incluye más de 35 métricas organizadas en 7 categorías. Cada métrica está registrada en METRIC_REGISTRY y puede ser referenciada por su clave en archivos de política OSCAL.

---

Categorías de Métricas de un Vistazo

Categoría	Métricas	Descripción
Rendimiento	4	Accuracy, precision, recall y F1 estándar de ML
Equidad (Tradicional)	2	Paridad demográfica, igualdad de oportunidad
Equidad (Alternativa)	2	Probabilidades igualadas, paridad predictiva
Equidad Multiclase	7	Métricas de equidad para clasificación multiclase
Calidad de Datos	4	Impacto dispar, desequilibrio de clases, completitud
Privacidad	4	k-anonymity, l-diversity, t-closeness, minimización de datos
Equidad Causal	4	Contrafactual, descomposición de caminos, awareness

---

Métricas de Rendimiento

Clave de Registro	Función	Descripción
accuracy_score	calc_accuracy	Precisión general de clasificación
precision_score	calc_precision	Valor predictivo positivo
recall_score	calc_recall	Sensibilidad / tasa de verdaderos positivos
f1_score	calc_f1	Media armónica de precisión y recall

Uso en política:

- control-id: model-accuracy
  props:
    - name: metric_key
      value: accuracy_score
    - name: threshold
      value: "0.80"
    - name: operator
      value: ">="

---

Métricas de Equidad (Tradicional)

Estas son las medidas de equidad más utilizadas para clasificación binaria.

demographic_parity_diff

Mide la diferencia en tasas de predicción positiva entre grupos protegidos.

• Fórmula: |P(Y=1|A=a) - P(Y=1|A=b)|
• Valor ideal: 0.0
• Umbral típico: < 0.10
• Requiere: dimension (columna del atributo protegido)

equal_opportunity_diff

Mide la diferencia en tasas de verdaderos positivos (TPR) entre grupos.

• Fórmula: |TPR_a - TPR_b|
• Valor ideal: 0.0
• Umbral típico: < 0.10
• Requiere: dimension, target, prediction

---

Métricas de Equidad (Alternativa)

equalized_odds_ratio

Asegura que tanto TPR como FPR sean iguales entre grupos. Más estricta que la igualdad de oportunidad.

• Fórmula: |TPR_a - TPR_b| + |FPR_a - FPR_b|
• Valor ideal: 0.0
• Umbral típico: < 0.20
• Requiere: dimension, target, prediction
• Referencia: Hardt et al. 2016

predictive_parity

Mide la igualdad de precisión entre grupos. Cuando se emite una predicción positiva, debe ser igualmente fiable independientemente de la pertenencia al grupo.

• Fórmula: |Precision_a - Precision_b|
• Valor ideal: 0.0
• Umbral típico: < 0.10
• Requiere: dimension, target, prediction
• Referencia: Corbett-Davies et al. 2017

---

Métricas de Equidad Multiclase

Para tareas de clasificación multiclase. Consulta Equidad Multiclase para uso detallado.

Clave de Registro	Descripción
multiclass_demographic_parity	Paridad demográfica extendida a multiclase
multiclass_equal_opportunity	Igualdad de oportunidad por clase
multiclass_confusion_metrics	Análisis de matriz de confusión por grupo
weighted_demographic_parity_multiclass	Paridad demográfica ponderada por clase
macro_equal_opportunity_multiclass	Igualdad de oportunidad promediada macro
micro_equalized_odds_multiclass	Probabilidades igualadas promediadas micro
predictive_parity_multiclass	Paridad predictiva por clase

---

Métricas de Calidad de Datos

Clave de Registro	Descripción	Umbral Típico
disparate_impact	Ratio de la Regla de los Cuatro Quintos entre grupos	> 0.80
class_imbalance	Proporción de la clase minoritaria	> 0.20
group_min_positive_rate	Tasa positiva mínima entre grupos	> 0.10
data_completeness	Proporción de valores no nulos	> 0.95

Ejemplo de uso (escenario de préstamos):

- control-id: credit-data-bias
  description: "Disparate impact ratio must satisfy the Four-Fifths Rule"
  props:
    - name: metric_key
      value: disparate_impact
    - name: "input:dimension"
      value: gender
    - name: operator
      value: ">"
    - name: threshold
      value: "0.8"

---

Métricas de Privacidad

Medidas de privacidad alineadas con el RGPD desde venturalitica.assurance.privacy.

k_anonymity

Tamaño mínimo de grupo cuando se conocen los cuasi-identificadores. Previene la re-identificación.

• Fórmula: min(|group|) donde los grupos se definen por cuasi-identificadores
• Valor ideal: >= 5 (recomendación RGPD)
• Requiere: columnas de cuasi-identificadores

from venturalitica.metrics.privacy import calc_k_anonymity

k = calc_k_anonymity(df, quasi_identifiers=["age", "gender", "zipcode"])
assert k >= 5, "GDPR recommends k >= 5"

l_diversity

Mínimo de valores distintos de un atributo sensible por grupo de cuasi-identificadores.

• Fórmula: min(valores distintos en sensitive_attribute por grupo QI)
• Valor ideal: >= 2

t_closeness

Diferencia máxima de distribución entre grupos usando la Distancia del Transporte de Tierra (Earth Mover Distance).

• Fórmula: max(EMD entre distribuciones de grupo)
• Valor ideal: < 0.15
• Referencia: Li et al. 2007

data_minimization

Cumplimiento del Artículo 5 del RGPD — proporción de columnas no sensibles.

• Fórmula: (total_columns - sensitive_columns) / total_columns
• Valor ideal: >= 0.70

from venturalitica.metrics.privacy import calc_data_minimization_score

score = calc_data_minimization_score(
    df,
    sensitive_columns=["age", "income", "health_status"]
)

---

Métricas de Equidad Causal

Métricas avanzadas desde venturalitica.assurance.causal.

Clave de Registro	Descripción
path_decomposition	Descompone caminos causales para identificar discriminación directa vs indirecta
counterfactual_fairness	Prueba si cambiar un atributo protegido cambiaría el resultado
fairness_through_awareness	Asegura que individuos similares reciban predicciones similares
causal_fairness_diagnostic	Diagnóstico integral combinando múltiples pruebas causales

---

Alias para LLM y Benchmarks

Estos son alias de conveniencia que usan calc_mean internamente:

Clave de Registro	Caso de Uso
bias_score	Puntuación general de sesgo para salidas de LLM
stereotype_preference_rate	Detección de estereotipos en texto generado
category_bias_score	Sesgo por categoría en evaluaciones de benchmarks

---

Métricas ESG / QA Financiero

Métricas especializadas para análisis de reportes ESG:

Clave de Registro	Descripción
classification_distribution	Distribución de clasificaciones ESG
report_coverage	Cobertura de requisitos de reporte
provenance_completeness	Completitud de la cadena de procedencia de datos
chunk_diversity	Diversidad de fragmentos de texto en Pipeline RAG
subtitle_diversity	Diversidad de encabezados de sección en reportes

---

Jerarquía de Métricas de Equidad

Diferentes métricas capturan distintos conceptos de equidad, ordenados por nivel de exigencia:

Demographic Parity (menos estricta)
    |  Mismas tasas de aprobacion entre grupos
    v
Equal Opportunity (media)
    |  Mismo TPR entre grupos
    v
Equalized Odds (mas estricta)
    |  Mismo TPR Y FPR entre grupos
    v
Predictive Parity (ortogonal)
       Misma precision entre grupos

En la práctica, un sistema puede aprobar la paridad demográfica y al mismo tiempo fallar en probabilidades igualadas. Elige las métricas alineadas con tu contexto de riesgo:

• Crédito / Contratación: Equalized odds + predictive parity
• Salud: Equalized odds + métricas de privacidad (k-anonymity >= 5)
• Auditoría integral: Todas las métricas en conjunto

---

Uso de Métricas en Políticas OSCAL

Cada métrica puede ser referenciada en una política OSCAL a través de la propiedad metric_key:

assessment-plan:
  metadata:
    title: "Custom Fairness Policy"
  control-implementations:
    - description: "Fairness Controls"
      implemented-requirements:
        - control-id: my-check
          props:
            - name: metric_key
              value: equalized_odds_ratio    # <-- Registry key
            - name: threshold
              value: "0.20"
            - name: operator
              value: "<"
            - name: "input:dimension"
              value: gender                  # <-- Protected attribute

Consulta la Guía de Autoría de Políticas para la referencia completa del formato OSCAL.

---

Agregar Métricas Personalizadas

Para registrar una nueva métrica:

1. Crea la función en el módulo correspondiente bajo venturalitica/assurance/:

   def calc_my_metric(df, **kwargs) -> float:
       # Validate inputs
       if "dimension" not in kwargs:
           raise ValueError("Missing 'dimension' parameter")
       # Calculate and return
       return value

2. Regístrala en venturalitica/metrics/__init__.py:

   METRIC_REGISTRY["my_metric"] = calc_my_metric

3. Úsala en tu política OSCAL a través de metric_key: my_metric.

---

Referencias

• Fairlearn — Biblioteca de equidad de Microsoft
• AI Fairness 360 — Métricas de equidad de IBM
• Artículo 5 del RGPD — Principio de minimización de datos
• OSCAL — Open Security Controls Assessment Language