# 📖 Koodikirja ja Muuttujasanasto (Codebook)
## Suomen arjen infrastruktuuri-, energia- ja elinkustannusshokki 2020–2026: Avoimen datan pitkittäistutkimus ja tilastollinen kulutusklusterimallinnus

**Pysyvä DOI (Zenodo / DataCite):** [10.5281/zenodo.22858118](https://doi.org/10.5281/zenodo.22858118)  
**Tekijä:** Tommi Pelkonen / Pelkosen Paja Tmi (ORCID: [0009-0004-9426-8809](https://orcid.org/0009-0004-9426-8809))  
**Julkaisuverkko:** [https://sahkorepolainen.fi/tutkimus](https://sahkorepolainen.fi/tutkimus)  
**Lisenssi:** Creative Commons Nimeä 4.0 Kansainvälinen (CC BY 4.0)

---

## 1. Yleiskatsaus ja Tiedostorakenne

Tämä koodikirja määrittelee tutkimusaineiston kaikkien taulukoiden muuttujat, tietotyypit, mittayksiköt, arvoalueet ja lähteet. Aineisto koostuu viidestä (5) standardoidusta CSV-tiedostosta ja kahdesta (2) päätietovarannon JSON-tiedostosta.

Kaikki CSV-tiedostot noudattavat RFC 4180 -standardia:
- Merkistökoodaus: UTF-8 (ilman BOM-merkkiä)
- Erotinmerkki: pilkku (`,`)
- Desimaalierotin: piste (`.`)
- Puuttuva havainto: tyhjä merkkijono tai `—`

---

## 2. Tiedostokohtaiset Muuttujakuvaukset

### 2.1 Valtakunnallinen Aikasarja
**Tiedosto:** `suomen_arjen_infrastruktuuri_ja_energiahinnat_2020_2026.csv`  
**Kuvaus:** Suomen arjen energian, liikkumisen ja perusinfrastruktuurin vuosittainen kehitys 2020–2026.

| Sarake | Tyyppi | Yksikkö | Lähde | Kuvaus ja Arvoalue |
| :--- | :--- | :--- | :--- | :--- |
| `vuosi` | Integer | YYYY | — | Tilastovuosi. Arvot: `2020`–`2026`. |
| `sahkon_kokonaiskulutus_twh` | Float | TWh | Fingrid | Suomen vuotuinen sähkön kokonaisbruttokulutus. Arvot: `79.8`–`86.8`. |
| `tuulivoimakapasiteetti_mw` | Integer | MW | Fingrid | Suomeen asennettu tuulivoimateho vuoden lopussa. Arvot: `2586`–`8900`. |
| `porssisahko_spot_ka_snt_kwh` | Float | snt/kWh | Nord Pool | Nord Pool Day-Ahead FI -aluehinnan aritmeettinen vuosikeskiarvo (sis. alv). Arvot: `2.80`–`15.40`. |
| `porssisahko_max_tunti_snt_kwh` | Float | snt/kWh | Nord Pool | Vuoden korkein yksittäinen tuntispothinta (sis. alv). Arvot: `25.4`–`235.0`. |
| `negatiiviset_tunnit_kpl` | Integer | kpl | Nord Pool | Tuntien lukumäärä vuodessa, jolloin spot-hinta oli alle 0,00 snt/kWh. Arvot: `4`–`612`. |
| `fossiilivapaan_sahkon_osuus_pct` | Float | % | Fingrid | Ydin-, vesi-, tuuli- ja aurinkovoiman yhteenlaskettu osuus sähköntuotannosta. Arvot: `82.0`–`96.5`. |
| `bensiini_95e10_eur_l` | Float | €/litra | Tilastokeskus | 95E10-kuluttajabensiinin painotettu vuosikeskihinta. Arvot: `1.42`–`2.22`. |
| `diesel_eur_l` | Float | €/litra | Tilastokeskus | Dieselin painotettu kuluttajahinta. Arvot: `1.32`–`2.28`. |
| `sahkoauto_kotilataus_eur_100km` | Float | €/100km | Laskennallinen | Kulutus 20 kWh/100km yösähkön spot-hinnalla + siirtotaksa + vero. Arvot: `1.76`–`4.28`. |
| `talousvesi_ka_eur_m3` | Float | €/m³ | VVY | Puhtaan talousveden keskimääräinen kuutiohinta Suomessa. Arvot: `1.80`–`2.35`. |
| `jatevesi_ka_eur_m3` | Float | €/m³ | VVY | Jäteveden keskimääräinen kuutiohinta Suomessa. Arvot: `2.70`–`3.60`. |
| `kansalaispulssi_energiahuoli_ka_10` | Float | 1–10 | VNK / FSD | Kansalaispulssin kysymys q46: Huoli energian ja polttoaineiden hinnoista (keskiarvo asteikolla 1–10). Arvot: `2.8`–`5.3`. |
| `datakeskusten_osuus_sahkosta_pct` | Float | % | Fingrid / Arvio | Datakeskusten arvioitu osuus Suomen sähkön kokonaiskulutuksesta. Arvot: `1.2`–`7.2`. |

---

### 2.2 Standardoidut Kulutusklusterit
**Tiedosto:** `standardoidut_kulutusklusterit_kustannukset_2020_2026.csv`  
**Kuvaus:** Energiaviraston virallisiin tyyppikäyttäjästandardeihin (K1, L1, L2) ja Motivan normeihin perustuvat neljä tyyppikotitaloutta ja niiden vuotuiset menot 2020–2026.

| Sarake | Tyyppi | Yksikkö | Kuvaus |
| :--- | :--- | :--- | :--- |
| `klusteri_id` | String | Tunniste | Standardoitu klusteritunnus: `klusteri_A_suorasahko_maaseutu`, `klusteri_B_lampopumppu_taajama`, `klusteri_C_maalampo_aurinko_kaupunki`, `klusteri_D_kerrostalo_kaukolampo`. |
| `klusteri_nimi` | String | Teksti | Klusterin selkokielinen nimi ja aluetyyppi. |
| `viitestandardi_energiavirasto` | String | Standardi | Energiaviraston virallinen tyyppikäyttäjäkoodi (`L1`, `L2`, `K1`) tai Motiva-normi. |
| `asumismuoto` | String | Teksti | Rakennustyyppi, asuinpinta-ala ja päälämmitysmuoto. |
| `vuosikulutus_kwh` | Integer | kWh | Standardoitu vuotuinen sähkönkulutus (esim. `18000`, `12000`, `7500`, `2000`). |
| `verkkoyhtio` | String | Nimi | Esimerkkijakeluverkkoyhtiö ja verkkotyyppi (esim. Caruna maaseutu, Elenia taajama, Helen kaupunki). |
| `liikkumisen_referenssi` | String | Teksti | Kotitalouden ajosuorite ja ajoneuvokanta (km/v ja käyttövoima). |
| `vuosi` | Integer | YYYY | Tarkasteluvuosi (`2020`–`2026`). |
| `energialasku_eur` | Float | €/v | Vuotuinen sähköenergialasku spot-keskihinnalla. |
| `siirtomaksu_eur` | Float | €/v | Volyymipohjainen sähkönsiirtomaksu ja valtion sähkövero I (2,79 snt/kWh). |
| `perusmaksut_eur` | Float | €/v | Pääsulakekohtaiset kiinteät kuukausittaiset perusmaksut vuodessa (ei riipu kulutuksesta). |
| `liikkumiskulu_eur` | Float | €/v | Kotitalouden vuotuiset polttoneste- tai kotilatauskustannukset. |
| `kokonaiskulu_vuosi_eur` | Float | €/v | Vuotuiset pakolliset energia-, siirto- ja liikkumiskulut yhteensä. |
| `kulu_kk_keskiarvo_eur` | Float | €/kk | Kuukausittainen keskimääräinen infrakulu. |
| `osuus_viitetuloista_pct` | Float | % | Menojen osuus kahden aikuisen tilastollisista mediaaninettotuloista. |

---

### 2.3 Maakuntakohtainen Energiainframatriisi
**Tiedosto:** `maakuntakohtainen_energiainfra_2020_2026.csv`  
**Kuvaus:** 18 Manner-Suomen maakunnan rekisterifaktat ja Kansalaispulssin asenne- ja sopeutumisindikaattorit.

| Sarake | Tyyppi | Lähde | Kuvaus |
| :--- | :--- | :--- | :--- |
| `maakunta_koodi` | Integer | Tilastokeskus | Virallinen maakuntatunnus (1–18). |
| `maakunta_nimi` | String | Tilastokeskus | Maakunnan virallinen nimi (esim. Kainuu, Uusimaa, Pirkanmaa). |
| `haavoittuvuusindeksi_100` | Float | Malli | Monikriteerinen energiainfra-haavoittuvuusindeksi (asteikko 0–100). |
| `haavoittuvuusluokka` | String | Malli | Sanallinen luokitus: `Korkea haavoittuvuus`, `Kohtalainen haavoittuvuus`, `Matala haavoittuvuus`. |
| `paaverkkoyhtio` | String | Energiavirasto | Maakunnan määräävä jakeluverkkoyhtiö tai verkkorakenne. |
| `suora_sahkolammitys_pct` | Float | Tilastokeskus | Suoran sähkölämmityksen osuus pientaloista (%). |
| `puu_ja_oljylammitys_pct` | Float | Tilastokeskus | Puu- ja öljylämmityksen osuus rakennuskannasta (%). |
| `kaukolampo_pct` | Float | Tilastokeskus | Kaukolämmön osuus koko asuntokannasta (%). |
| `lampopumppujen_yleisyys_pct` | Float | SULPU / Stat | Lämpöpumppujen peittävyys pientaloissa (%). |
| `veden_keskihinta_eur_m3` | Float | VVY | Maakunnan painotettu talous- ja jäteveden kuutiohinta (€/m³). |
| `arvioitu_vuosikulu_eur` | Float | Malli | Tyypillisen pientalon vuotuinen pakollinen infrakustannus (€/v). |
| `kansalaispulssi_vastaajia_n` | Integer | VNK / FSD | Kansalaispulssin vastaajamäärä maakunnassa kumulatiivisesti (N = 287...7 792). |
| `energiahuoli_ka_10` | Float | VNK / FSD | Kansalaispulssi q46: Energian hintahuoli (asteikko 1–10). |
| `vahentanyt_autoilua_pct` | Float | VNK / FSD | Kansalaispulssi q48_4: Autoilua karsineiden vastaajien osuus (%). |
| `lyhentanyt_suihkuaikaa_pct` | Float | VNK / FSD | Kansalaispulssi q48_1: Suihkuaikaa lyhentäneiden vastaajien osuus (%). |
| `laskenut_huonelampotilaa_pct` | Float | VNK / FSD | Kansalaispulssi q48_2: Sisälämpötilaa laskeneiden vastaajien osuus (%). |

---

### 2.4 Pohjoismainen Energiakriisivertailu
**Tiedosto:** `pohjoismainen_energiakriisi_vertailu.csv`  
**Kuvaus:** Suomen, Ruotsin, Norjan ja Tanskan kotitalouksien sähköriippuvuuden, valtion tukimekanismien ja säästöpuskureiden vertailu.

| Sarake | Tyyppi | Kuvaus |
| :--- | :--- | :--- |
| `maa` | String | Vertailumaa: `Suomi`, `Ruotsi`, `Norja`, `Tanska`. |
| `suoran_sahkolammityksen_osuus_pct` | Float | Suoran sähkölämmityksen osuus asuntokannasta (%). |
| `tukimekanismi_kriisissa` | String | Keskeinen valtion kriisitukimalli kotitalouksille vuosina 2022–2023. |
| `hintavolatiliteetti_eur_mwh` | Float | Tuntihintojen keskihajonta kriisikuukausina (€/MWh). |
| `kotitalouksien_saastopuskuri_eur` | Integer | Kotitalouksien mediaanisäästöpuskuri pankkitileillä (€). |
| `siirtoverkon_vakaus_pisteet` | Integer | Kantaverkon vakausindeksi (asteikko 0–100). |
| `keskeinen_haavoittuvuus` | String | Maakohtainen suurin rakenteellinen energiamarkkinariski. |

---

### 2.5 Energiamarkkinoiden Shokkiaikajana
**Tiedosto:** `geopoliittiset_shokit_2020_2026.csv`  
**Kuvaus:** 15 keskeistä geopolitiikan, markkinoiden ja sääntelyn murroskohtaa 2020–2026.

| Sarake | Tyyppi | Kuvaus |
| :--- | :--- | :--- |
| `paivamaara_tai_kausi` | String | Tapahtuma-aika (YYYY-MM-DD tai kausi). |
| `tapahtuma_ja_shokki` | String | Tapahtuman tiivis otsikko ja luonnehdinta. |
| `luokka` | String | Luokitus: `GLOBAALI TALOUS`, `GEOPOLITIIKKA`, `SOTA & GEOPOLITIIKKA`, `ENERGIA-ASE`, `INFRASTRUKTUURI`, `MARKKINAKRIISI`, `OMAVARAISUUS`, `SÄÄ & VOIMALAT`, `TEOLLISUUS`. |
| `hintavaikutus_markkinoilla` | String | Välitön vaikutus pörssihintoihin, futuureihin tai polttoaineisiin. |
| `kansallinen_ohjaus_ja_reaktio` | String | Suomen hallituksen, viranomaisten tai kantaverkon toimenpiteet. |

---

## 3. Matemaattiset Laskentakaavat

### 3.1 Kotitalouden Vuotuinen Kokonaiskustannus ($C_{tot}$)
$$C_{tot} = C_{energy} + C_{trans} + C_{fixed} + C_{mobility} + C_{water}$$

- $C_{energy} = \frac{E_{annual} \cdot \bar{P}_{spot}}{100}$ (€/v)
- $C_{trans} = \frac{E_{annual} \cdot (T_{variable} + Tax_{elec})}{100}$ (€/v), missä $Tax_{elec} = 2{,}79387\text{ snt/kWh}$ (alv 25,5 %)
- $C_{fixed} = 12 \cdot P_{month\_fixed}$ (€/v)
- $C_{mobility}$: Polttomoottorilla $\frac{D_{km}}{100} \cdot Consumption_{l} \cdot P_{fuel}$; sähköautolla $\frac{D_{km}}{100} \cdot E_{100km} \cdot \frac{\bar{P}_{night} + T_{variable} + Tax_{elec}}{100}$

### 3.2 Alueellinen Haavoittuvuusindeksi ($HPI_{region}$)
$$HPI = 0{,}35 \cdot z(P_{fixed}) + 0{,}30 \cdot z(Share_{elec\_heat}) + 0{,}20 \cdot z(Distance_{km}) + 0{,}15 \cdot z(Price_{water})$$
Standardoidut pistemäärät ($z$-pisteet) skaalataan välille $0\dots 100$.

---
*© 2026 Tommi Pelkonen / Pelkosen Paja Tmi. Lisenssi: CC BY 4.0.*