Ir al contenido
Base de conocimiento

Herramientas de estrategias de muestreo — Referencia de herramientas MCP

Las herramientas de estrategias de muestreo definen distribuciones demográficas objetivo para crear muestras representativas de encuestados. Una estrategia describe una población: sus factores —dimensiones demográficas con proporciones objetivo— y cómo se evalúa el ajuste a ellos (quality_metric, aggregation_method). La generación de grupos usa esos factores para seleccionar encuestados que se ajusten a su diseño muestral.

Una estrategia contiene solo factores de los encuestados: atributos que se conocen antes de que nadie responda. Un objetivo sobre una respuesta de la encuesta (por ejemplo, una referencia tomada de resultados electorales o de un censo) corresponde al paquete que contiene las respuestas, como objetivo de calibración solo de referencia: consulte set_calibration_targets.

Lista todas las estrategias de muestreo, opcionalmente filtradas por proyecto o por nombre.

Parámetro Tipo Obligatorio Predeterminado Descripción
project_id string No — Filtra por ID de proyecto
name string No — Filtro por subcadena, sin distinguir mayúsculas y minúsculas
limit integer No 100 Número máximo de resultados que se devuelven

Devuelve: { data: [...], count, limit }. Cada elemento incluye id, name, description, project_id, factor_count, quality_metric, created_at.


Obtiene una estrategia de muestreo por su ID, con las definiciones completas de sus factores.

Parámetro Tipo Obligatorio Predeterminado Descripción
strategy_id string Sí — UUID de la estrategia

Devuelve: el objeto completo de la estrategia: id, name, description, project_id, factors, quality_metric, aggregation_method, is_default, created_at, modified_at.


Crea una estrategia de muestreo con factores de distribución demográfica.

Parámetro Tipo Obligatorio Predeterminado Descripción
name string Sí — Nombre de la estrategia
project_id string No — ID del proyecto padre
factors object[] No — Definiciones de los factores de distribución (véase más abajo)
quality_metric string No "rmse" "rmse", "mae", "chi_square" o "max_deviation"; cualquier otro valor se rechaza y no se crea nada
description string No — Descripción de la estrategia

Devuelve: el objeto completo de la estrategia (como get_sampling_strategy).

Cada factor de la matriz factors define una dimensión de los encuestados. Una clave que no figure en el esquema siguiente se rechaza como error de validación (REST 422), de modo que un factor que todavía lleve el campo retirado source falla en lugar de descartarse en silencio:

Campo Tipo Obligatorio Predeterminado Descripción
name string Sí — Nombre visible (p. ej., "Gender")
attribute_path string Sí — Atributo del encuestado (p. ej., "gender", o un atributo personalizado)
target_distribution object Sí — Asignación categoría → proporción. Debe sumar 1,0 (tolerancia de ±0,01)
factor_type string No "discrete" "discrete", "bucketed" o "geographic"
bucket_ranges array No — Para el tipo por tramos: lista de tuplas [min, max, label]
weight float No 1.0 Peso de importancia de este factor

Ejemplo:

{
"name": "Gender",
"attribute_path": "gender",
"target_distribution": {"male": 0.48, "female": 0.50, "other": 0.02},
"factor_type": "discrete",
"weight": 1.0
}

Crea una estrategia con los factores estándar de distribución por género y edad.

Parámetro Tipo Obligatorio Predeterminado Descripción
name string Sí — Nombre de la estrategia
project_id string No — ID del proyecto padre

Devuelve: el objeto completo de la estrategia (como get_sampling_strategy).

Factores predeterminados:

  • Género: hombre 48 %, mujer 50 %, otro 2 %
  • Grupo de edad: 18–24 (15 %), 25–34 (20 %), 35–44 (20 %), 45–54 (18 %), 55–64 (15 %), 65+ (12 %)

Actualiza una estrategia de muestreo existente (actualización parcial: solo cambian los campos proporcionados).

Parámetro Tipo Obligatorio Predeterminado Descripción
strategy_id string Sí — UUID de la estrategia
name string No — Nuevo nombre
description string No — Nueva descripción
factors object[] No — Sustituye todos los factores (no se combinan)
quality_metric string No — Nueva métrica de calidad, una de las cuatro anteriores; cualquier otro valor se rechaza y no cambia nada

Devuelve: el objeto completo de la estrategia (como get_sampling_strategy).

Actualizar una estrategia nunca cambia un grupo ya seleccionado a partir de ella: cada grupo conserva los ajustes de selección con los que se generó, y una actualización del grupo repite la selección frente a los factores actuales de la estrategia con el tamaño guardado en el propio grupo.


Elimina una estrategia de muestreo. Está protegida si es la estrategia predeterminada o tiene grupos vinculados.

Parámetro Tipo Obligatorio Predeterminado Descripción
strategy_id string Sí — UUID de la estrategia

Devuelve: { strategy_id, deleted }


Situación Respuesta
Falta un campo obligatorio {"error": "Each factor must have 'name', 'attribute_path', and 'target_distribution'"}
La distribución no suma 1,0 {"error": "Factor '{name}' target_distribution must sum to 1.0 (got {sum:.3f})"}
Una clave que el esquema de factores no declara (p. ej., source) validation_error (REST 422), que nombra el campo adicional

La validación de factores se aplica tanto a create_sampling_strategy como a update_sampling_strategy.

Situación Respuesta
Modificar la estrategia predeterminada {"error": "Cannot modify the default sampling strategy"}
Eliminar la estrategia predeterminada {"error": "Cannot delete the default sampling strategy"}
Situación Respuesta
Eliminar una estrategia con grupos {"error": "Cannot delete strategy: {count} pool(s) are linked to it"}
Situación Respuesta
Estrategia no encontrada {"error": "Strategy {id} not found"}
No es propietario del proyecto de la estrategia {"error": "forbidden", "detail": "caller is not an owner of this project and lacks an admin role"}