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.
list_sampling_strategies
Sección titulada «list_sampling_strategies»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.
get_sampling_strategy
Sección titulada «get_sampling_strategy»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.
create_sampling_strategy
Sección titulada «create_sampling_strategy»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).
Esquema de los factores
Sección titulada «Esquema de los factores»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}create_default_strategy
Sección titulada «create_default_strategy»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 %)
update_sampling_strategy
Sección titulada «update_sampling_strategy»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.
delete_sampling_strategy
Sección titulada «delete_sampling_strategy»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 }
Gestión de errores
Sección titulada «Gestión de errores»Validación de factores
Sección titulada «Validación de factores»| 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.
Protección de la estrategia predeterminada
Sección titulada «Protección de la estrategia predeterminada»| 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"} |
Protección de grupos vinculados
Sección titulada «Protección de grupos vinculados»| Situación | Respuesta |
|---|---|
| Eliminar una estrategia con grupos | {"error": "Cannot delete strategy: {count} pool(s) are linked to it"} |
Errores comunes
Sección titulada «Errores comunes»| 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"} |