Mintavételistratégia-eszközök – MCP-eszközreferencia
A mintavételistratégia-eszközök demográfiai céleloszlásokat határoznak meg reprezentatív válaszadói minták létrehozásához. Egy stratégia egy alapsokaságot ír le: a tényezőit – célarányokkal ellátott demográfiai dimenziókat – és azt, hogyan értékeli a rendszer a hozzájuk való illeszkedést (quality_metric, aggregation_method). A válaszadói kör előállítása ezekkel a tényezőkkel választja ki az Ön mintatervének megfelelő válaszadókat.
A stratégia csak válaszadói tényezőket tartalmaz – olyan jellemzőket, amelyek még azelőtt ismertek, hogy bárki válaszolna. Egy kérdőíves válaszra vonatkozó célérték (például egy választási eredményből vagy népszámlálásból származó viszonyítási adat) a válaszokat tartalmazó csomagba tartozik, csak viszonyítási kalibrációs célértékként: lásd a set_calibration_targets eszközt.
list_sampling_strategies
Szekció neve “list_sampling_strategies”Az összes mintavételi stratégia listázása, opcionálisan projekt vagy név szerint szűrve.
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
project_id |
string |
Nem | — | Szűrés projektazonosító szerint |
name |
string |
Nem | — | Kis- és nagybetűt nem megkülönböztető részszöveg-szűrő |
limit |
integer |
Nem | 100 |
A visszaadott találatok legnagyobb száma |
Visszatérési érték: { data: [...], count, limit }. Minden elem tartalmazza az id, name, description, project_id, factor_count, quality_metric és created_at mezőt.
get_sampling_strategy
Szekció neve “get_sampling_strategy”Mintavételi stratégia lekérdezése azonosító alapján, a tényezők teljes definíciójával együtt.
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
strategy_id |
string |
Igen | — | A stratégia UUID-ja |
Visszatérési érték: a teljes stratégiaobjektum: id, name, description, project_id, factors, quality_metric, aggregation_method, is_default, created_at, modified_at.
create_sampling_strategy
Szekció neve “create_sampling_strategy”Mintavételi stratégia létrehozása demográfiai eloszlási tényezőkkel.
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
name |
string |
Igen | — | A stratégia neve |
project_id |
string |
Nem | — | A szülőprojekt azonosítója |
factors |
object[] |
Nem | — | Az eloszlási tényezők definíciói (lásd alább) |
quality_metric |
string |
Nem | "rmse" |
"rmse", "mae", "chi_square" vagy "max_deviation"; minden más értéket a rendszer elutasít, és semmi sem jön létre |
description |
string |
Nem | — | A stratégia leírása |
Visszatérési érték: a teljes stratégiaobjektum (ugyanúgy, mint a get_sampling_strategy esetén).
Tényezőséma
Szekció neve “Tényezőséma”A factors tömb minden tényezője egy válaszadói dimenziót határoz meg. Az alábbi sémában nem szereplő kulcsot a rendszer validációs hibaként utasítja el (REST 422), így a megszüntetett source mezőt még tartalmazó tényező hibát okoz, ahelyett hogy a rendszer csendben elhagyná a mezőt:
| Mező | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
name |
string |
Igen | — | Megjelenített név (pl. "Gender") |
attribute_path |
string |
Igen | — | Válaszadói jellemző (pl. "gender" vagy egy egyéni attribútum) |
target_distribution |
object |
Igen | — | Kategória → arány leképezés. Összegének 1,0-nak kell lennie (±0,01 tűréssel) |
factor_type |
string |
Nem | "discrete" |
"discrete", "bucketed" vagy "geographic" |
bucket_ranges |
array |
Nem | — | Sávos típus esetén: [min, max, label] hármasok listája |
weight |
float |
Nem | 1.0 |
A tényező fontossági súlya |
Példa:
{ "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
Szekció neve “create_default_strategy”Stratégia létrehozása szabványos nem és életkor szerinti eloszlási tényezőkkel.
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
name |
string |
Igen | — | A stratégia neve |
project_id |
string |
Nem | — | A szülőprojekt azonosítója |
Visszatérési érték: a teljes stratégiaobjektum (ugyanúgy, mint a get_sampling_strategy esetén).
Alapértelmezett tényezők:
- Nem: férfi 48%, nő 50%, egyéb 2%
- Korcsoport: 18–24 (15%), 25–34 (20%), 35–44 (20%), 45–54 (18%), 55–64 (15%), 65+ (12%)
update_sampling_strategy
Szekció neve “update_sampling_strategy”Meglévő mintavételi stratégia módosítása (részleges módosítás – csak a megadott mezők változnak).
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
strategy_id |
string |
Igen | — | A stratégia UUID-ja |
name |
string |
Nem | — | Új név |
description |
string |
Nem | — | Új leírás |
factors |
object[] |
Nem | — | Az összes tényező lecserélése (nem összefésülés) |
quality_metric |
string |
Nem | — | Új minőségi mutató, a fenti négy egyike; minden más értéket a rendszer elutasít, és semmi sem változik |
Visszatérési érték: a teljes stratégiaobjektum (ugyanúgy, mint a get_sampling_strategy esetén).
Egy stratégia módosítása soha nem változtat meg egy belőle már kihúzott válaszadói kört: minden válaszadói kör megtartja azokat a mintahúzási beállításokat, amelyekkel előállították, a frissítés pedig a stratégia aktuális tényezői alapján, a válaszadói kör saját tárolt méretével húz újra.
delete_sampling_strategy
Szekció neve “delete_sampling_strategy”Mintavételi stratégia törlése. A rendszer nem engedi törölni, ha a stratégia az alapértelmezett, vagy ha válaszadói körök kapcsolódnak hozzá.
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
strategy_id |
string |
Igen | — | A stratégia UUID-ja |
Visszatérési érték: { strategy_id, deleted }
Hibakezelés
Szekció neve “Hibakezelés”A tényezők validációja
Szekció neve “A tényezők validációja”| Helyzet | Válasz |
|---|---|
| Hiányzó kötelező mező | {"error": "Each factor must have 'name', 'attribute_path', and 'target_distribution'"} |
| Az eloszlás összege nem 1,0 | {"error": "Factor '{name}' target_distribution must sum to 1.0 (got {sum:.3f})"} |
A tényezősémában nem deklarált kulcs (pl. source) |
validation_error (REST 422), amely megnevezi a többletmezőt |
A tényezők validációja a create_sampling_strategy és az update_sampling_strategy eszközre egyaránt vonatkozik.
Az alapértelmezett stratégia védelme
Szekció neve “Az alapértelmezett stratégia védelme”| Helyzet | Válasz |
|---|---|
| Az alapértelmezett stratégia módosítása | {"error": "Cannot modify the default sampling strategy"} |
| Az alapértelmezett stratégia törlése | {"error": "Cannot delete the default sampling strategy"} |
A kapcsolt válaszadói körök védelme
Szekció neve “A kapcsolt válaszadói körök védelme”| Helyzet | Válasz |
|---|---|
| Válaszadói körökkel rendelkező stratégia törlése | {"error": "Cannot delete strategy: {count} pool(s) are linked to it"} |
Gyakori hibák
Szekció neve “Gyakori hibák”| Helyzet | Válasz |
|---|---|
| A stratégia nem található | {"error": "Strategy {id} not found"} |
| Nem tulajdonosa a stratégia projektjének | {"error": "forbidden", "detail": "caller is not an owner of this project and lacks an admin role"} |