Csomageszközök – MCP-eszközreferencia
A csomag egy projektet, egy kérdőívet és az adott kérdőív kampányainak egy nem üres kiválasztott részhalmazát kapcsolja össze pontosan egy lineáris Bronz → Ezüst → Arany adatkészlet-lánccal. Ezek az eszközök magát a csomagot és a minőségi értékelését kezelik; a csomaghoz kötött szakaszműveleteket (előállítás, kódolás + súlyozás, finomítás, export) lásd az Adatkészlet-eszközök oldalon.
create_bundle
Szekció neve “create_bundle”Adatfolyam-csomag létrehozása.
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
name |
string |
Igen | — | A csomag neve |
project_id |
string |
Igen | — | A tulajdonos projekt (írási jogosultság szükséges) |
questionnaire_id |
string |
Igen | — | Az a kérdőív, amelynek befejezett kitöltései a Bronz adatkészletet táplálják |
campaign_ids |
string[] |
Igen | — | A mérendő kampányok részhalmaza. Legalább egyet meg kell nevezni: a csomag mérési alapja az általa kiválasztott kampányok kitöltései |
Visszatérési érték: { bundle_id, name }
list_bundles
Szekció neve “list_bundles”Az adatfolyam-csomagok listázása, opcionálisan egyetlen projektre szűrve.
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
project_id |
string |
Nem | — | Szűkítés az adott projekt csomagjaira |
Visszatérési érték:
{ "items": [ { "id": "...", "name": "Wave 1", "project_id": "...", "questionnaire_id": "...", "campaign_ids": ["..."], "chain": { "bronze": {"dataset_id": "...", "status": "ready"}, "silver": {"dataset_id": "...", "status": "processing"} } } ], "count": 1}A chain kulcsai azok a szakaszok, amelyekhez van adatkészlet (bronze/silver/gold); az a szakasz, amelyhez még nincs adatkészlet, egyszerűen hiányzik – kezelje missing állapotúként.
clone_bundle
Szekció neve “clone_bundle”Egy csomag kész adatkészleteinek és receptjeinek mély másolása egy független változatba.
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
bundle_id |
string |
Igen | — | A forráscsomag |
name |
string |
Nem | "{source} (copy)" |
A klón neve |
Visszatérési érték: { bundle_id, cloned_stages } – a cloned_stages felsorolja, mely szakaszoknak (bronze/silver/gold) volt másolható kész adatkészlete.
A klón minden kész szakasz bájtra azonos másolatából indul, és ugyanazokat a szakaszrecepteket viszi magával (a kódolási kiválasztást és a hozzá tartozó dimenzió-kódkönyvet, a súlyozási célértékeket, a finomítási mezőspecifikációkat), így az eredeti csomag érintése nélkül, függetlenül származtatható újra – például más súlyozási célértékekkel. Így vethetők össze ugyanannak a nyers előállításnak a változatai (eltérő súlyozás, eltérő finomítás).
delete_bundle
Szekció neve “delete_bundle”Egy csomag és az adatkészlet-láncának törlése.
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
bundle_id |
string |
Igen | — | A törlendő csomag |
Visszatérési érték: { success: true }
A törlés logikai (soft delete): a rendszer a csomagot és a lánc adatkészleteit azonnal töröltként jelöli meg, a mögöttes adatfájlokat pedig nem sokkal később egy háttérben futó karbantartási folyamat takarítja el.
Minőségi eszközök
Szekció neve “Minőségi eszközök”A minőséget a csomag szintjén méri a rendszer, nem az egyes adatkészleteken. A négy reprezentativitási mérés közül három a csomag újra hozzárendelhető aktuális stratégiájához (current_strategy_id) viszonyít – rendeljen hozzá egyet, mielőtt measured állapotot várna tőlük. A rake-súlyozott kalibrációs célérték a súlyozás utasítása, nem viszonyítási alap: ha a súlyozott eredményt ahhoz a specifikációhoz mérnénk, amelyre a súlyozás irányult, egy sikeres rake-súlyozás eleve jó pontszámot kapna. A csak viszonyítási kalibrációs célérték ennek az ellentéte: olyan külső adat, amelyre a súlyozás soha nem irányult, ezért a mintát ehhez méri a rendszer.
get_bundle_quality
Szekció neve “get_bundle_quality”A csomag reprezentativitási története egyetlen hívásban – egyetlen minta végigkövetve a tervezési szándéktól a leszállítható eredményig:
- Stratégia → válaszadói kör (
selection) – megvalósította-e a mintavétel a tervet? Külön-külön minden olyan válaszadói körre, amelyből a csomag kampányai merítettek; összesítve csak akkor, ha egyetlen stratégián osztoznak. Az értékelés minden tagnak a válaszadói kör kiválasztásakor rögzített értékein alapul; az a válaszadói kör, amelynek nincs hiánytalan rögzítése,not_measurableértéket ad (pool_has_no_complete_snapshot) - Stratégia → tényleges (
fielded) – mennyire tért el a megvalósult alap a súlyozás előtt? Kampányonkénti bontással; amíg nincs hozzárendelt stratégia,no_strategy - Stratégia → súlyozott (
weighted) – helyreállította-e a súlyozás a tervet? Ugyanahhoz a stratégiához mér, mint a (2), így a kettő pontosan annyiban különbözik, amennyit a súlyozás visszanyert - Válaszadói kör → tényleges (
fielding_shift) – mit tett hozzá maga a terepmunka? A válaszadói körhöz viszonyít, csak a válaszadói körből származó kitöltéseken, ezért más kérdésre felel, mint az (1)–(3), és nem negyedik pont azok skáláján - Válaszminőség (
response) – entrópia, egyenes vonalú válaszadás, Cronbach-alfa, egyetértési torzítás, nemválaszolás (lásd a Minőségi mutatók referenciáját)
Mellettük az excluded_profile azt írja le, mit távolított el a csomagonkénti teljességi küszöb ahhoz képest, amit megtartott – a stratégia saját tényezői szerint összevetve, mert a sorok két darabszámából nem derül ki, hogy egy vágás okozott-e torzítást. Üres kizárt halmaz esetén az érték empty, nem nulla eltérés.
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
bundle_id |
string |
Igen | — | A csomag UUID-ja |
Visszatérési érték: { quality: {...} } – az öt mérés, valamint az excluded_profile és a lánc-, illetve stratégiakörnyezet. Mindegyik hordoz egy state értéket (measured, not_measurable, no_strategy, no_weighted_factors, empty, not_derived, processing, invalidated, error) egy reason mezővel, így egyetlen nem mérhető vagy hibás mérés sem takarja el a többit, és a nulla soha nem téveszthető össze egy osztályzattal. A mért adatok tartalmazzák az összpontszámot, az összetett hibát és a tényezőnkénti eltéréselemzést; a súlyozott adatok emellett a weighting_diagnostics mezőt is hordozzák (dizájnhatás, effektív mintanagyság) – a visszanyerés varianciaköltségét. A fielded és a weighted egyaránt tartalmaz benchmarks mezőt: minden csak viszonyítási kalibrációs célértéket kategóriánként a súlyozatlan és a súlyozott mintához mérve, a stratégia szerinti osztályzat mellett, és soha nem annak összetett értékében; ezeket akár van aktuális stratégia, akár nincs, kiértékeli a rendszer. A weighted emellett a raking_reached mezőt is hordozza: minden rake-súlyozott célérték súlyozott arányát a saját célértékéhez képest, ami azt mutatja, mennyire jutott közel hozzá a rake-súlyozás, és soha nem osztályzat. Az a viszonyítás, amely olyan oszlopra vonatkozik, amelyen az aktuális Ezüst adatkészletet rake-súlyozták (a szerepe a származtatás után változott meg), a következő származtatásig a weighted alatt a raking_reached, nem pedig a benchmarks mezőben jelenik meg, mivel azokat a súlyokat erre illesztették. A comparison_ready csak addig true, amíg a csomag Bronz és Ezüst adatkészlete is létezik és ready állapotú – pontosan ekkor válaszol a compare_bundle_quality elutasítás helyett; a függőben lévő, sikertelen vagy érvénytelenített Ezüst adatkészletnek is van azonosítója, ezért ezt a jelzőt olvassa, ne az adatkészlet-azonosítókat.
A régebbi előállítási sémaverzióval előállított Bronz adatkészletet a rendszer nem értékeli: a fielded, a fielding_shift, a response, az excluded_profile és a weighted egyaránt not_measurable értéket ad bronze_schema_stale okkal, amíg a Bronz adatkészletet újra elő nem állítják (create_bronze_dataset), és az Ezüst adatkészletet újra nem származtatják. A selection nem olvas adatkészletet, így azt továbbra is értékeli a rendszer.
compare_bundle_quality
Szekció neve “compare_bundle_quality”A csomag láncának Bronz–Ezüst reprezentativitási összehasonlítása a csomag aktuális stratégiájához mérve. A mérvadó szám a recovery mező: a súlyozott átlagos hiba egyszerű különbsége azokon a stratégiatényezőkön, amelyeket mindkét oldalon mértek, így az eltérő abszolút szinteken elért azonos hibacsökkenés azonos számot ad, és két csomag összevethető. Ha a két mérésnek nincs közös mért tényezője, az érték null egy recovery_reason mezővel, nem pedig 0.0 – semmi sem volt összevethető, ami nem ugyanaz, mint hogy a súlyozás semmit sem ért el.
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
bundle_id |
string |
Igen | — | A csomag UUID-ja |
Visszatérési érték: { comparison: {...} }, amely tartalmazza a recovery értéket (a fent leírt összesített számot) és a recovery_per_factor mezőt – ugyanazt a kivonást tényezőnként, hibaegységben. Mindkettő hibakülönbség, nem százalék: a pozitív érték azt jelenti, hogy a súlyozás ennyivel csökkentette a hibát. Tényezőnkénti százalékot itt nem lehet értelmesen megadni, mert a nevezője a Bronz adatkészlet hibája lenne, vagyis éppen az a mennyiség, amelyet a súlyozásnak a nulla felé kell szorítania. Előbb a Bronz és az Ezüst adatkészletnek is ready állapotúnak kell lennie; a még nem kész lánc ütközési hibával (REST-en 409 a {"error": "conflict"} törzzsel) bukik el, nem validációs hibával – fejezze be vagy futtassa újra a származtatást, majd végezze el az összehasonlítást.
Az összehasonlítás saját state értéke measured, ha mindkét oldalt értékelte a rendszer. no_strategy, ha a csomagnak nincs aktuális stratégiája, és not_measurable bronze_schema_stale okkal, ha a Bronz adatkészletet régebbi előállítási sémaverzióval állították elő; mindkét esetben a bronze, a silver és a recovery értéke null, a hívás pedig sikeres. Az elavult állapot a Bronz adatkészlet újbóli előállításával (create_bronze_dataset) és az Ezüst adatkészlet újbóli származtatásával szüntethető meg.
get_bundle_coding
Szekció neve “get_bundle_coding”A csomag nyitott válaszainak kódolási állapota: mit lehet kódolni, mely kérdéseket választotta ki az elemző, és – minden kiválasztott kérdéshez – a javasolt dimenziók, azok kategóriái, hogy melyek vannak kiválasztva, és hogy a hitelesítő adat nélküli, korlátozott útvonal hozta-e létre őket. Olvassa el, mielőtt kiválaszt vagy újraszármaztat.
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
bundle_id |
string |
Igen | — | A csomag UUID-ja |
Visszatérési érték: { candidates, kinds, selected, discovered, units, awaiting_review, coding_outcome, bronze_status, silver_status, pending_review }.
candidates– minden nyitott szöveges egység, amelyet a csomag Bronz adatkészlete kínál, mindegyik{unit_key, title, control_type, roster_block_id, columns}alakban. Csak aTextareajöhet szóba, és az itteni megjelenés semmit sem jelent a kódolásra nézve: hogy mit tartalmaz az oszlop, az az elemző besorolása (kinds), és az egységet be kell sorolni, mielőtt kiválasztható lenne. AzEditboxa QML-ben numerikus bevitel (minimumot és maximumot követel meg), így a válaszai darabszámok és összegek, nem pedig kódkönyvvel leírható szöveg. A Roster egyetlen jelölt, amelynekcolumnsmezője megnevezi az általa összevont Bronz-oszlopokat; a QuestionGroup alkérdései és a Matrix cellái külön-külön jelöltek maradnak.kinds– az elemző által jelöltenként megadott választípus, alapértelmezés nélkül továbbítva:descriptive(szöveges, jelentés szerint kódolva),nominal(rögzített szókészlet, pontos érték szerint kódolva) vagyidentifier(személyt vagy rekordot nevez meg, soha nem kódolják). A bejegyzés nélküli jelölt besorolatlan, és nem választható ki; anullazt jelenti, hogy semmit sem soroltak még be. Itt írásvédett: az elemző a Balansorban sorol be, és egyetlen eszköz sem ír típust.selected– a mentett egységválasztás, alapértelmezés nélkül továbbítva: anulljelentése „még nincs kiválasztva”, a[]jelentése „kiválasztva: semmi”. Csak az utóbbi valakinek a döntése.discovered– minden kódolt egységhez egy{column: dimension label}leképezést rendel – annak rögzítése, hogy a legutóbbi származtatás ténylegesen mely oszlopokat hozta létre.units– az egységenkénti dimenzióállapot, egységkulcs szerint. Mindegyik tartalmazza areviewed(döntött-e már valaki arról, mely dimenziókból lesznek oszlopok?), aselected(a kiválasztott dimenzióazonosítók; áttekintés előttnull, „áttekintve, semmit sem választottak” esetén[]), adegraded(a javaslat a hitelesítő adat nélküli útvonalról származik – ez különbözteti meg a valódi egydimenziós eredményt attól az egyetlen dimenziótól, amelyet ez az útvonal ad), azanswered/missingés adimensionsmezőt. Minden dimenzió hordozza a helyénekidazonosítóját, alabelcímkét, a rögzítettcolumnnevet, azorigineredetet (proposed/authored/degraded, illetve a nominális egység egyetlen pontosérték-dimenziója eseténverbatim), hogyselectedállapotú-e, acategorieskategóriákat{id, label}alakban (verbatimdimenziónál csak{id}, amelynek-1kategóriája a fenntartott egyéb), az oszloponkénti hozzárendelésicountsdarabszámokat és azoverlapértéket – azt, hogy egy válasz az adott dimenzió saját kategóriái közül átlagosan hánynak a küszöbét lépi még át, ami a kódkönyvről árul el valamit, nem a válaszadókról.awaiting_review– azok a kiválasztott egységek, amelyek dimenzióit még senki sem tekintette át. Ezek az egységek nem hoznak létre kódolt oszlopot, a származtatás mégis sikeres, ezért kapnak külön nevet ahelyett, hogy ki kellene következtetni.coding_outcome– mit próbált meg a legutóbbi származtatás, és miből nem kapott oszlopot:{attempted, coded, lost}, ahol mindenlostbejegyzés{unit_key, kind}alakú, akindértéke pedignot_codable,unclassifiedvagyno_column. Egy egység kudarca nem buktatja el a származtatást – a többi egység oszlopai valódi munka –, így enélkül a veszteségnek semmilyen jele nem lenne: az adatkészletreadyállapotú, a fentidiscoveredpedig egy korábbi származtatásból továbbra is megnevezi az egységet, mert ezt a leképezést szándékosan megőrzi a rendszer a futtatások között. Ellenőrizze, mielőtt egy Ezüst adatkészletet késznek jelentene. Anullazt jelenti, hogy a származtatás semmit sem rögzített, ami nem ugyanaz, mint hogy semmi sem veszett el: minden Ezüst adatkészlet, amelyet e mező bevezetése előtt származtattak, ebben az állapotban van, és az üreslostlista az az érték, amely azt mondja, hogy egy futtatás semmit sem veszített. A veszteség okát a rendszer szándékosan akindértékre szűkíti – a mögöttes üzenet tetszőleges szöveg lehet, és ez az eszköz soha nem ad ki semmit, ami válaszadói választ hordozhatna.- A
bronze_statusazért áll asilver_statusmellett, mert az ürescandidateskétféle dolgot jelenthet – még nem állítottak elő Bronz adatkészletet, vagy ez a kérdőív egyáltalán nem tesz fel nyitott szöveges kérdést –, és ezeket a lista önmagában nem tudja megkülönböztetni. pending_review–true, amíg bármelyik döntés függőben van: kész Bronz jelöltekkel, de egységválasztás nélkül, vagy dimenzió-áttekintésre váró kiválasztott egység.
Ez az eszköz soha nem ad ki szó szerinti válaszadói szöveget. Egy kategóriából csak az azonosítója és a címkéje jelenik meg, a dimenziónkénti mintaválaszok pedig egyáltalán nem – mindkettő a kutató saját áttekintőfelületére való a Balansorban. A nominális egység kategóriacímkéi válaszadói válaszok, ezért a kategóriái azonosítóként, darabszámokkal és címke nélkül jelennek meg.
Az egységválasztás MCP-n/REST-en keresztül írható az alábbi set_coding_selection eszközzel, mert a kérdésről szóló, bármely modell futtatása előtt meghozott döntés. Egy oszlop besorolása, a dimenziók kiválasztása, átnevezése és a kategóriáik szerkesztése nem írható, és nem is lesz az – ezek a kutató saját adatairól és a generált tartalomról szóló döntések, és szándékosan egyetlen csatornán sincs hozzájuk eszköz. Az adatfolyamot vezérlő ügynöknek a pending_review: true értéket és az awaiting_review listát a felhasználója elé kell tárnia, ahelyett hogy átlépne rajtuk egy újraszármaztatással. A teljes munkafolyamatot lásd a Nyitott kérdések kódolása oldalon.
set_coding_selection
Szekció neve “set_coding_selection”Annak beállítása, hogy a csomag mely nyitott szöveges egységeit kódolja kategóriákba. A választás csomagonkénti elemzési döntés az Ezüst receptjén, nem a kérdőív tulajdonsága, és csak olyan oszlopokat nevezhet meg, amelyeket az elemző már descriptive vagy nominal típusúnak sorolt be (lásd a get_bundle_coding kinds mezőjét).
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
bundle_id |
string |
Igen | — | A csomag UUID-ja |
selected |
string[] |
Igen | — | A kódolási egységkulcsok teljes halmaza, amely lecseréli a korábbit; a get_bundle_coding candidates mezője által kínált szókészletből |
Visszatérési érték: { bundle_id, selected }.
Menedzseri jogosultság és azonosított felhasználó szükséges – a csak szolgáltatási tokennel hívókat elutasítja a rendszer, így egy felügyelet nélküli futtatás senki nevében sem választhat. Tárja a kutató elé a jelölteket és azok kinds típusát, és az ő válaszát írja be, ne válasszon helyette. A besorolatlan vagy identifier típusúnak besorolt egységet a rendszer az okkal együtt elutasítja, és az eszköz semmit sem ír; az ügynök nem tud besorolni, ezért kérje meg a kutatót, hogy tegye meg az Ezüst oldal kódolási választójában.
A lista a teljes halmaz, amely lecseréli a korábbit, nem változáslista, és az üres lista döntés („semmit sem kódolunk”), nem kihagyás. Azt a kulcsot, amely nem jelölt a csomag Bronz adatkészletében, a rendszer elutasítja – ideértve egy Roster egyetlen iterációjának oszlopnevét is, amely valódi oszlopnak tűnik, de semmit sem vonna össze; olvassa újra a jelöltlistát, és helyette az összevont egységkulcsot válassza. A kiválasztás módosítása az Ezüst adatkészlet bemenete: érvényteleníti a kész Ezüst adatkészletet és mindent, ami ráépül, és a következő származtatáskor lép érvénybe (a már futó származtatás azzal a kiválasztással fut tovább, amellyel elindult).
Egy kalibrációs célérték mögött álló egység kiválasztásának visszavonását a rendszer itt nem utasítja el – ez az ütközés a származtatáskor jelentkezik, amely weighting_factor_deselected hibával utasít el, így a recept bármilyen sorrendben javítható.
assign_bundle_strategy
Szekció neve “assign_bundle_strategy”A csomag aktuális mintavételi stratégiájának hozzárendelése (vagy törlése) – ez az a viszonyítási alap, amelyhez a selection, a fielded és a weighted is mér. Menedzseri jogosultság és azonosított felhasználó szükséges (a csak szolgáltatási tokennel hívókat elutasítja a rendszer); a stratégia hozzárendeléséhez a stratégia saját projektjéhez is hozzáférés kell. Az újbóli hozzárendelés mindhárom mérést újraszámolja; a kalibrációs célértékeket, amelyek a súlyozás utasításai, nem érinti.
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
bundle_id |
string |
Igen | — | A csomag UUID-ja |
strategy_id |
string |
Nem | null |
A hozzárendelendő stratégia; a null törli a hozzárendelést |
Visszatérési érték: { bundle_id, strategy_id, strategy_name }
A mintavételi stratégia csak válaszadói tényezőket tartalmaz. Ha a mintát egy kérdőíves válaszra vonatkozó külső adathoz szeretné mérni (például a pártpreferenciát egy választási eredményhez), vegye fel azt ehhez a csomaghoz csak viszonyítási kalibrációs célértékként a set_calibration_targets eszközzel.
set_calibration_targets
Szekció neve “set_calibration_targets”A csomag kalibrációs célértékeinek szerkesztése – ez az a szerkeszthető specifikáció, amelyre a derive_silver/code_open_ends súlyoz, valamint a csak viszonyítási célértékek, amelyekhez a csomag minősége mér. A rake-súlyozott célérték a súlyozás utasítása, nem a viszonyítási alap: a súlyozott mérés az aktuális stratégiához mér, így a tervet elvétő kalibrációscélérték-halmaz az attól a tervtől mért távolságként jelenik meg, nem pedig tökéletes pontszámként a saját céljához képest. A rendszer egyszer tölti fel az aktuális stratégia tényezőiből, amikor egy kutató először nyitja meg az Ezüst szakaszt a Balansorban; onnantól független az aktuális stratégiától. Menedzseri jogosultság és azonosított felhasználó szükséges.
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
bundle_id |
string |
Igen | — | A csomag UUID-ja |
weighting |
object |
Nem | — | A teljes blokk, amely lecseréli a korábbit: {use_strategy_factors, factors} |
factors |
array |
Nem | — | Rövidítés a weighting={factors, use_strategy_factors: false} helyett – egy puszta tényezőlista megadása önmagában lemondás az élő stratégia követéséről |
Minden tényező {column, target_distribution, name?, factor_type?, bucket_ranges?, role?} alakú – a column egy, a kódolt adatkeretben már meglévő puszta oszlopot nevez meg (Bronz-válasz- vagy válaszadóijellemző-oszlopot, kódolt nyitott válasz dimenziót vagy többválasztós opcióindikátort), a target_distribution pedig minden értékhez hozzárendeli a célarányát (összegük 1,0).
A role értéke raked (az alapértelmezett: az Ezüst adatkészlet származtatása a célérték felé súlyoz) vagy benchmark (nem súlyoz rá a rendszer; a get_bundle_quality a terepen megvalósult és a súlyozott mintát méri hozzá). Bármely célérték-oszlop bármelyik szerepet felveheti, a válaszadói jellemzőket is beleértve. A hívás a teljes listát lecseréli, ezért olvassa ki az aktuális célértékeket a get_bundle eszközzel (ott minden célérték megadja a role értékét), és mindegyiket a szerepével együtt küldje vissza: a role nélkül küldött célértéket a rendszer rake-súlyozottként menti. Azt a listát, amelyben minden célérték viszonyítási, a rendszer weighting_factor_none_raked hibával elutasítja, mert a rake-súlyozásnak nem lenne mire súlyoznia.
A célérték egy válaszadói egyéni attribútumot is megnevezhet. Ennek oszlopa _custom_<key>, ahol a <key> az attribútum kulcsa a válaszadói rekordon (_custom_region a custom_attributes.region esetén). Egyéni attribútum csak akkor kerül be egy adatkészletbe, ha a csomag egy mintavételistratégia-tényezője vagy egy kalibrációs célértéke hivatkozik rá, így egy célérték révén kerül be egy új attribútum az adatkészletbe: nem kell már a Bronz adatkészletben lennie. Hogy a Bronz adatkészlet mely attribútumokat tartalmazza, azt a get_dataset_schema custom_attribute_keys mezőjéből olvashatja ki.
Visszatérési érték: { bundle_id, weighting, warnings }. A warnings a sikeres mentéshez fűzött megjegyzések listája, amely üres, ha nincs mit mondani. Egy bejegyzést tartalmaz, ha a mentett célértékek olyan egyéni attribútumra súlyoznak, amellyel a csomag Bronz adatkészletét nem állították elő: az Ezüst származtatása előtt állítsa elő újra a Bronz adatkészletet (create_bronze_dataset), különben a rendszer a származtatást weighting_attributes_not_extracted hibával elutasítja. Ha a csomag egyetlen válaszadója sem rendelkezik ilyen nevű attribútummal, a név hibás; azt javítsa ki. Ha még nincs Bronz adatkészlet, figyelmeztetés sincs, mert az első előállítás minden megnevezett attribútumot kiír. A szöveg ugyanaz a mondat, amelyet a kutató akkor lát, amikor a Balansorban menti a célértékeket.
A válaszkód-ellenőrzés
Szekció neve “A válaszkód-ellenőrzés”Minden mentés ellenőrzi minden célérték kulcsait a csomag kérdőívén, mindkét szerepnél, a Balansorban és MCP-n/REST-en egyaránt. Egy válaszoszlop kulcsának a kérdés egyik opcióját kell megneveznie, opciókód ("1") vagy opciócímke ("Yes") szerint; egy viszonyítási célérték elgépelt kódját a rendszer különben nem létező eltérésként értékelné.
| Eset | Eredmény |
|---|---|
| Olyan kulcs, amelyet a kérdés nem kínál | Elutasítva (400), megnevezve a célértéket, az oszlopot, a nem illeszkedő kulcsokat, valamint az elfogadott kódokat és címkéket: Target 'Recommend' targets keys that are neither an option code nor an option label of 'q_cp07': 'Exit interview' offers no option ['Maybe'] and accepts, by code or label: 1 (Yes), 2 (No). |
| Olyan oszlop, amelynek opciói nem neveznek meg minden értéket (csúszka, szabad szöveg), vagy nem olvasható kérdőív | Mentve, egy warnings bejegyzéssel, amely szerint a kulcsokat nem ellenőrizte a rendszer |
Válaszadóijellemző-oszlop (_demographic_*, _custom_*), kódolt nyitott válasz dimenziója vagy sávokra bontott célérték |
Ez a szabály nem ellenőrzi (az alábbi előzetes ellenőrzés és a származtatás továbbra is érvényes) |
Előzetes ellenőrzés
Szekció neve “Előzetes ellenőrzés”Az alábbi feltételeket a rendszer ütközési hibával utasítja el, mielőtt bármit kiírna – ez ugyanaz az előzetes ellenőrzés, amelyet maga az Ezüst-származtatás is lefuttat:
- olyan célérték, amely elutasított vagy a legutóbbi kódolási futtatásból azóta eltűnt kódolási kategóriát nevez meg;
- olyan célérték, amely nyers többválasztós válaszoszlopot nevez meg. Ez az oszlop a kiválasztott opciók kombinációját tárolja, így minden megfigyelt kombinációból külön súlyozási cella lenne. Helyette az opciónkénti indikátoroszlopokat célozza – opciónként egy célértékkel;
- két célérték ugyanarra az oszlopra vagy névre;
- olyan lista, amelyben minden célérték csak viszonyítási, miközben a célértékek alkotják a teljes súlyozási halmazt (a
use_strategy_factorsértékefalse, ahogy afactorsrövidítésnél is), így a rake-súlyozásnak nem lenne mire súlyoznia (weighting_factor_none_raked). Az a csomag, amely még követi a stratégiáját, a stratégia tényezőire rake-súlyoz, és tartalmazhat kizárólag viszonyítási célértékeket.
preview_calibration_targets_copy
Szekció neve “preview_calibration_targets_copy”Előnézet egy másik csomag kalibrációs célértékeinek ebbe a csomagba másolásához. Jelzi, hogy a forrás célértékei közül melyek illeszkednek erre a csomagra és melyek nem, és semmit sem ír. A másoláshoz fésülje össze az addable tartalmát a csomag aktuális célértékeivel, és mentse az eredményt a set_calibration_targets eszközzel, amelynek ellenőrzései a mentéskor újra lefutnak. Menedzseri jogosultság, írási hozzáférés ehhez a csomaghoz és olvasási hozzáférés a forráscsomaghoz szükséges; az a forrás, amelyet nem olvashat, pontosan úgy válaszol, mint egy nem létező. A Balansor Ezüst oldala ugyanezt a műveletet Másolás másik csomagból néven kínálja, amely kitölti a szerkesztőt, és semmit sem ment, amíg Ön nem menti.
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
bundle_id |
string |
Igen | — | Az a csomag, amelybe a rendszer a célértékeket másolná |
source_bundle_id |
string |
Igen | — | Az a csomag, amelynek célértékeit másolja |
Visszatérési érték: { bundle_id, source_bundle_id, addable, rejected }. Az addable az illeszkedő célértékeket tartalmazza, mindegyiket a role értékével. A rejected a többit, mindegyiket name, column, role, egy olvasható detail és egy reason mezővel:
reason |
Jelentés |
|---|---|
no_bronze |
Ennek a csomagnak még nincs Bronz adatkészlete, így nincs oszloplista, amelyhez ellenőrizni lehetne; előbb állítsa elő a Bronz adatkészletet |
column_missing |
Az oszlop sem a csomag Bronz adatkészletében nincs meg, sem válaszadói jellemző (_demographic_<field>, _custom_<key>), sem kódolt dimenzió a kódkönyvében |
unknown_code |
Egy kulcs nem olyan opció, amelyet a csomag kérdőíve az adott oszlopon kínál (a válaszkód-ellenőrzés) |
preflight:<code> |
A célérték itt elbukna egy előzetes ellenőrzési feltételen, például preflight:weighting_factor_duplicated, ha ennek a csomagnak már van ilyen nevű vagy oszlopú célértéke. A csupa viszonyítási lista itt nem ok: az a végül mentett listára vonatkozik |
Szakaszműveletek
Szekció neve “Szakaszműveletek”Az előállítás, a kódolás + súlyozás, a finomítás és az export mind egy bundle_id paraméterrel hívható az Adatkészlet-eszközökkel. Egy jellemző folyamat:
create_bundle→ abundle_idmegszerzésecreate_bronze_dataset(bundle_id)→ a Bronz adatkészlet előállításacode_open_ends(bundle_id)(vagy az álneve, aderive_silver) → kódolja a nyitott válaszokat, majd a kalibrációs célértékekre súlyoz, és így előállítja az Ezüst adatkészletetcreate_gold_dataset(bundle_id, operations=[...])→ az Ezüst adatkészlet finomítása Arany adatkészletté a műveletkatalógus segítségévelexport_dataset(dataset_id, format)→ bármely kész szakasz exportálásaget_bundle_quality(bundle_id)→ a reprezentativitási történet bármikor
run_bundle_pipeline
Szekció neve “run_bundle_pipeline”A 2–4. lépés egyetlen hívásban. Minden lépés ugyanaz a fent felsorolt eszköz, így ugyanazok az adatkészletek jönnek létre és ugyanazok az auditesemények keletkeznek, és minden elutasítást, amelyet egy önálló szakasz adna, itt változatlanul megkap – kiegészítve a stopped_at_step mezővel, amely megnevezi, melyik szakaszból ered a leállás.
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
bundle_id |
string |
Igen | — | Az a csomag, amelynek láncát futtatni kell |
include_demographics |
boolean |
Nem | true |
Az előállított Bronz-sorok kiegészítése a válaszadók demográfiai adataival. A false értéket a rendszer named_attributes_require_enrichment hibával elutasítja, ha a csomag egyéni attribútumot nevez meg (lásd: create_bronze_dataset) |
gold_name |
string |
Nem | — | Az Arany adatkészlet neve. Alapértelmezés: "{bundle_name} — Gold"; magát az Arany receptet továbbra is a csomag saját tárolt receptje adja |
Visszatérési érték: { task_id, status, step, bundle_id, bronze_dataset_id, silver_dataset_id }. Kérdezze le a task_id állapotát a get_task_status eszközzel, amíg a futtatás el nem éri a completed, partial vagy failed állapotot; a lekérdezés jelzi, melyik szakasznál tart a futtatás, és a befejezés után minden szakasz adatkészlet-azonosítóját (bronze_dataset_id, silver_dataset_id, gold_dataset_id), valamint a gold_skipped mezőt: a tárolt Arany recept azon bejegyzéseit, amelyeket az összeállítás félretett, mert az Ezüst adatkészletben már nincs meg az oszlopuk – abban az alakban, amelyet a create_gold_dataset skipped néven ad vissza. Üres, ha semmit sem tett félre.
Várakozás közben csak a Bronz adatkészlet előállítása és az Ezüst-származtatás sorba állítása történik meg. Az Arany adatkészlet előállítása nem indulhat el, amíg az Ezüst adatkészlet nem ready állapotú, ehhez pedig percekig tartó kódolás és súlyozás kell, ezért az Arany lépés a származtatás befejezése után magától fut le, a futtatás pedig végig lekérdezhető marad.
Két tudnivaló:
- A leállás megtartja, ami elkészült. A Bronz adatkészlet a csomag Bronz adatkészlete, akár követte Arany adatkészlet, akár nem, így a rendszer semmit sem von vissza. Az újrafuttatás ugyanazokon a sorokon folytatódik, ahelyett hogy megkettőzne egy szakaszt.
- A teljes lánc jogosultságait a rendszer még az összeállítás előtt ellenőrzi. A lánc az átjáró- és az MI-asszisztens-előfizetési szintet is érinti (a kódoló származtatáshoz az utóbbi kell), így a csak az elsőt lefedő előfizetést a rendszer már az elején elutasítja, ahelyett hogy egy olyan Bronz adatkészletet adna át, amelyből nem tud származtatni.
Kapcsolódó dokumentáció
Szekció neve “Kapcsolódó dokumentáció”- Adatkészlet-eszközök – az előállítás, a kódolás + súlyozás, a finomítás és az export paraméterei
- Minőségi mutatók referenciája – a mutatók definíciói, képletei és értelmezési küszöbei
- Adatelemzési útmutató – a csomagok adatfolyam-táblája a kutató szemszögéből
- Nyitott kérdések kódolása – hogyan működik a nyitott válaszok kódolása az Ezüst-származtatáson belül