# Avalikud reitinguandmed Ühiskonnauuringute Instituudi ja Norstati erakondade reitingute alusandmed on avalikult kättesaadavad kompaktse JSON-failina. Fail sisaldab: - üleriigilisi iganädalasi tulemusi; - üleriigilisi nelja nädala koondtulemusi; - nelja nädala tulemusi demograafiliste rühmade lõikes; - iga perioodi valimite suurusi. Autentimist ei ole vaja. - [Ava ratings-compact.json](https://kiir.kusitlus.com/_datasets_public/rk-ratings/ratings-compact.json) - Andmete URL: `https://kiir.kusitlus.com/_datasets_public/rk-ratings/ratings-compact.json` ## LLM-iga kasutamine Sama dokumentatsioon on masinloetava tekstifailina aadressil [rk.kusitlus.com/llms.txt](https://rk.kusitlus.com/llms.txt). Kui tahad lasta LLM-il või koodiagendil andmeid laadida ja analüüsida, anna talle see link. Fail sisaldab nii vormingu täielikku kirjeldust kui ka töötavaid JavaScripti ja Pythoni näiteid. ## Kiire kasutus 1. Laadi JSON-fail ühe päringuga alla. 2. Kontrolli, et `v` oleks `3`. Tundmatu skeemiversiooni korral lõpeta töötlemine veaga. 3. Leia üleriigilised plokid välja `r` ning demograafilised plokid välja `g` kaudu. 4. Jaga reitinguväärtused väljaga `q`. Valimite suurusi ära skaleeri. 5. Vajaduse korral taasta kõiki vastajaid hõlmavad tulemused valijate reitingust ja mittevalijate osakaalust. Faili transporditakse gzip-pakituna päisega `Content-Encoding: gzip`. Brauseri `fetch()` ja Pythoni `requests` pakivad vastuse automaatselt lahti. URL ise lõpeb endiselt laiendiga `.json`. ## Põhiskeem | Väli | Tüüp | Sisu | |---|---|---| | `v` | integer | Skeemiversioon, praegu `3`. | | `q` | integer | Kvantimistegur, praegu `10`. Protsendi saamiseks jaga väärtus teguriga `q`. | | `n` | string | Mittevalijate rea kuvatav nimi. | | `s` | string[] | Valimiridade nimed ja järjekord. | | `p` | string[] | Erakondade täisnimede ühine sõnastik. | | `a` | axis[] | Ühised nädala- ja nelja nädala ajateljed. | | `r` | [blockId, blockId] | Üleriigilise nädala- ja nelja nädala ploki ID-d selles järjekorras. | | `g` | group[] | Demograafilised tunnused, väärtused ja nende plokkide ID-d. | | `b` | block[] | Kõik kvanditud reitinguplokid. | Erakondade sõnastik `p` sisaldab täisnimesid. Lühendite või muude kuvatavate nimede valimine jääb andmete kasutaja ülesandeks. Allpool on ühe perioodiga illustratiivne, kuid struktuurilt täielik näide: ```json { "v": 3, "q": 10, "n": "Mittevalijad", "s": ["total", "voters", "effectiveTotal", "effectiveVoters"], "p": ["Eesti Reformierakond", "Eesti Keskerakond"], "a": [ ["w1", [["2025-W18", "2025.04.29", "2025.05.05"]]], ["w4", [["2025-W15-18", "2025.04.08", "2025.05.05"]]] ], "r": [0, 1], "g": [ ["age_group", "Vanus", [["18–24", 2]]] ], "b": [ [0, [0, 1], [[227], [183]], [210], [[1000], [790], [820], [650]]], [1, [0, 1], [[231], [179]], [205], [[4000], [3180], [3290], [2630]]], [1, [0, 1], [[246], [171]], [224], [[410], [318], [337], [264]]] ] } ``` ## Ajateljed Iga element massiivis `a` on järgmise kujuga: ```json [ "axisName", [ ["waveId", "firstResponseDate", "lastResponseDate"] ] ] ``` Kuupäevad on kujul `YYYY.MM.DD`. Algus- ja lõppkuupäev tähistavad vastava laine esimese ning viimase vastaja tegelikku vastamiskuupäeva. Ajatelje kirjete ja kõigi seda kasutavate andmeridade järjekord on sama. Ajatelje nimi `w1` tähistab iganädalasi ning `w4` nelja nädala koondtulemusi. `waveId` on perioodi stabiilne identifikaator. ## Demograafilised rühmad Iga element massiivis `g` on järgmise kujuga: ```json [ "key", "Kuvatav nimi", [ ["rühma väärtus", 12] ] ] ``` - `key` on stabiilne lähteveeru identifikaator; - teine väärtus on tunnuse kuvatav nimi; - iga rühma väärtus viitab ühele nelja nädala reitinguplokile massiivis `b`. Generaator kaasab rühma väärtuse, kui selle viimase nelja nädala laine kaalumata valim on vähemalt 30. Tunnus jäetakse välja, kui sobivaid väärtusi pole või neid on üle 25. Veebivaade rakendab lisaks oma kuvapoliitikat: kasutab toetatud demograafiliste tunnuste alamhulka ning peidab rühma, kui rohkem kui pool selle viimase 12 laine väärtustest puudub. Andmestiku kasutaja ei pea sama filtrit rakendama. ## Reitinguplokid Iga element massiivis `b` on positsiooniline massiiv: ```json [ 0, [0, 3, 5], [[127, 131], [205, 198], [64, null]], [214, 207], [[1000, 1000], [786, 793], [821, 816], [647, 653]] ] ``` | Indeks | Nimi | Sisu | |---|---|---| | `0` | `axisId` | Ajatelje indeks massiivis `a`. | | `1` | `partyIds` | Ploki erakondade indeksid sõnastikus `p`. | | `2` | `voterRows` | Erakondade kvanditud reitingud valijate seas, üks rida erakonna kohta. | | `3` | `nonvoterRow` | Mittevalijate kvanditud osakaal. | | `4` | `sampleRows` | Valimite suurused välja `s` järjekorras. | `partyIds` ja `voterRows` vastavad üksteisele positsiooni järgi. Iga `voterRows`, `nonvoterRow` ja `sampleRows` rida vastab valitud ajateljele ning peab olema sellega ühepikkune. ## Kvantimine ja puuduvad väärtused Reitingud on ümardatud ühe kümnendkohani ning salvestatud täisarvudena. Kui `q = 10`, tähistab väärtus `127` tulemust `12,7%`: ```javascript const percentage = storedValue / payload.q; ``` `null` tähendab puuduvat väärtust. Jaga teguriga `q` ainult `voterRows` ja `nonvoterRow`; `sampleRows` sisaldab tegelikke valimite suurusi ning seda ei skaleerita. Reitingute avaldamise alampiir on kaalumata valim 30: - kui valijaid on laines alla 30, on selle laine kõik `voterRows` väärtused `null`; - kui kõiki vastajaid on alla 30, on `nonvoterRow` väärtus `null`; - valimiread säilitavad tegelikud loendused ka siis, kui reitingut ei avaldata. ## Mittevalijatega tulemuse taastamine Fail hoiab põhivaatena reitingut valijate seas ja eraldi mittevalijate osakaalu. Erakonna osakaal kõigi vastajate seas taastatakse kvanditud täisarvudega enne teguriga `q` jagamist: ```javascript const inclusive = Math.round( voterOnly * (100 * q - nonvoter) / (100 * q), ); ``` Kui `voterOnly` või `nonvoter` on `null`, on ka tulemus `null`. Mittevalijate enda rida saadakse otse `nonvoterRow` väärtustest. ## Valimid Välja `s` väärtused on: | Nimi | Tähendus | |---|---| | `total` | Kõigi vastajate kaalumata arv. | | `voters` | Valijate kaalumata arv. | | `effectiveTotal` | Kõigi vastajate efektiivne valim pärast kaalumise mõju arvestamist. | | `effectiveVoters` | Valijate efektiivne valim pärast kaalumise mõju arvestamist. | Kõik neli rida on ajateljega samas järjekorras ning puuduv väärtus on `null`. Valijate vaate tavavalim on `voters`, kõiki vastajaid hõlmava vaate tavavalim `total`. Selle veebilehe 95% usaldusvahemikud kasutavad tavavalimit, mitte efektiivset valimit. ## JavaScript Järgmine näide pakib kompaktformaadi väikese lazy reader'i taha. Plokk dekodeeritakse alles selle küsimisel ja ühe korra. Tulemuseks on flat record'ite massiiv, mida saab kohe filtreerida, visualiseerida või CSV-ks teisendada. Väliseid sõltuvusi ei ole vaja. ```javascript const DATA_URL = 'https://kiir.kusitlus.com/_datasets_public/rk-ratings/ratings-compact.json'; function decodeBlock(payload, blockId, { view = 'voters' } = {}) { if (view !== 'voters' && view !== 'all') { throw new Error("view must be 'voters' or 'all'"); } const [axisId, partyIds, voterRows, nonvoterRow, sampleRows] = payload.b[blockId]; const [, axisEntries] = payload.a[axisId]; const percentageScale = 100 * payload.q; return axisEntries.flatMap( ([waveId, startDate, endDate], waveIndex) => { const nonvoterValue = nonvoterRow[waveIndex]; const samples = Object.fromEntries( payload.s.map((name, sampleIndex) => [ name, sampleRows[sampleIndex][waveIndex], ]), ); const rows = partyIds.map((partyId, partyIndex) => { const voterValue = voterRows[partyIndex][waveIndex]; const quantizedRating = view === 'voters' ? voterValue : voterValue === null || nonvoterValue === null ? null : Math.round( voterValue * (percentageScale - nonvoterValue) / percentageScale, ); return { waveId, startDate, endDate, party: payload.p[partyId], rating: quantizedRating === null ? null : quantizedRating / payload.q, ...samples, }; }); if (view === 'all') { rows.push({ waveId, startDate, endDate, party: payload.n, rating: nonvoterValue === null ? null : nonvoterValue / payload.q, ...samples, }); } return rows; }, ); } function createRatingsReader(payload) { if (payload.v !== 3) throw new Error('Unsupported schema version'); const blockCache = new Map(); const groups = new Map( payload.g.map(([key, label, values]) => [ key, { label, blocks: new Map(values) }, ]), ); const readBlock = (blockId, options = {}) => { const view = options.view ?? 'voters'; const cacheKey = `${blockId}:${view}`; if (!blockCache.has(cacheKey)) { blockCache.set(cacheKey, decodeBlock(payload, blockId, { view })); } return blockCache.get(cacheKey); }; const getGroup = (key) => { const group = groups.get(key); if (!group) throw new Error(`Unknown demographic: ${key}`); return group; }; return { demographics: [...groups].map(([key, group]) => ({ key, label: group.label, values: [...group.blocks.keys()], })), weekly: (options) => readBlock(payload.r[0], options), fourWeek: (options) => readBlock(payload.r[1], options), demographicValues: (key) => [...getGroup(key).blocks.keys()], demographic(key, value, options) { const group = getGroup(key); const blockId = group.blocks.get(value); if (blockId === undefined) { throw new Error(`Unknown value for ${key}: ${value}`); } return readBlock(blockId, options).map((row) => ({ ...row, demographicKey: key, demographic: group.label, group: value, })); }, }; } async function loadRatings() { const response = await fetch(DATA_URL); if (!response.ok) { throw new Error(`Ratings request failed: ${response.status}`); } return createRatingsReader(await response.json()); } const ratings = await loadRatings(); const reformLatest = ratings .fourWeek() .filter(({ party, rating }) => party === 'Eesti Reformierakond' && rating !== null ) .slice(-12); const ageValues = ratings.demographicValues('age_group'); const selectedAge = ratings.demographic('age_group', ageValues[0]); console.table(reformLatest); ``` ## Python ja Pandas Paigalda sõltuvused: ```bash python -m pip install pandas requests ``` Allolev näide tagastab tidy-kujulised Pandase DataFrame'id: üks rida ühe perioodi ja erakonna kohta. Kuupäevad on `datetime64` veerud, reiting on protsentides ning valimite suurused on samas reas kohe analüüsiks saadaval. ```python import numpy as np import pandas as pd import requests DATA_URL = ( "https://kiir.kusitlus.com/_datasets_public/" "rk-ratings/ratings-compact.json" ) def decode_periods(payload, axis_id): _, entries = payload["a"][axis_id] periods = pd.DataFrame( entries, columns=["wave_id", "start_date", "end_date"], ) for column in ["start_date", "end_date"]: periods[column] = pd.to_datetime( periods[column], format="%Y.%m.%d", errors="coerce", ) return periods def decode_block(payload, block_id, view="voters"): if view not in {"voters", "all"}: raise ValueError("view must be 'voters' or 'all'") axis_id, party_ids, voter_rows, nonvoter_row, sample_rows = ( payload["b"][block_id] ) periods = decode_periods(payload, axis_id) wave_ids = periods["wave_id"].tolist() parties = [payload["p"][party_id] for party_id in party_ids] quantized = pd.DataFrame( voter_rows, index=parties, columns=wave_ids, dtype="Float64", ) if view == "all": nonvoters = pd.Series( nonvoter_row, index=wave_ids, dtype="Float64", ) scale = 100 * payload["q"] quantized = np.floor( quantized.mul(scale - nonvoters, axis="columns") / scale + 0.5 ) quantized.loc[payload["n"]] = nonvoters ratings = ( quantized.T .rename_axis("wave_id") .reset_index() .melt( id_vars="wave_id", var_name="party", value_name="rating", ) ) ratings["rating"] = ratings["rating"] / payload["q"] samples = ( pd.DataFrame( sample_rows, index=payload["s"], columns=wave_ids, ) .T .rename_axis("wave_id") .reset_index() ) return ( periods .merge(samples, on="wave_id", validate="one_to_one") .merge(ratings, on="wave_id", validate="one_to_many") [[ "wave_id", "start_date", "end_date", "party", "rating", *payload["s"], ]] ) response = requests.get(DATA_URL, timeout=30) response.raise_for_status() payload = response.json() if payload["v"] != 3: raise ValueError("Unsupported schema version") # Vaikimisi on reitingud valijate seas. weekly = decode_block(payload, payload["r"][0]) four_week = decode_block(payload, payload["r"][1]) # Soovi korral taasta kõiki vastajaid hõlmav vaade. four_week_all = decode_block(payload, payload["r"][1], view="all") # Kõik demograafilised lõiked ühes DataFrame'is. demographics = pd.concat( [ decode_block(payload, block_id).assign( demographic_key=key, demographic=label, group=value, ) for key, label, values in payload["g"] for value, block_id in values ], ignore_index=True, ) ``` Tulemusi saab seejärel töödelda tavaliste Pandase operatsioonidega: ```python # Reformierakonna viimased 12 nelja nädala tulemust. reform_latest = ( four_week.loc[four_week["party"] == "Eesti Reformierakond"] .sort_values("end_date") .tail(12) ) # Keskmine toetus erakonniti viimase kuue kuu jooksul. six_month_average = ( four_week.loc[ four_week["end_date"] >= four_week["end_date"].max() - pd.DateOffset(months=6) ] .groupby("party", as_index=False)["rating"] .mean() .sort_values("rating", ascending=False) ) # Vanuserühmade andmed CSV-faili. age_groups = demographics.loc[demographics["demographic_key"] == "age_group"] age_groups.to_csv("ratings-by-age.csv", index=False) ``` ## Allikas Andmete allikas on Ühiskonnauuringute Instituut ja Norstat.