Tovább a tartalomhoz
Tudástár

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.

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.


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.


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).

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
}

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%)

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.


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 }


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.

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"}
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"}