Reference

ssb_kostra_python package

ssb_kostra_python.avrunding module

konverter_dtypes(df, dtype_mapping)

Bruk malen under for dtype_mapping.

Du må angi denne mappingen i forkant for at funksjonen skal kunne konvertere variablene slik du ønsker.

Eksempel:

dtype_mapping = {
    "klassifikasjonsvariabel": ["var1", "var2"],  # Legg inn variablene du vil klassifikasjonsverdier
    "heltall": ["var3", "var4"],  # Legg inn variablene du vil runde av til heltall (kommersiell avrunding)
    "desimaltall_1_des": ["var5", "var6"],  # Legg inn variablene du vil runde til 1 desimal
    "desimaltall_2_des": ["var7", "var8"],  # Legg inn variablene du vil runde til 2 desimaler
    "stringvar": ["var9", "var10"],  # Legg inn variablene du vil konvertere til tekst
    "bool_var": ["var11", "var12"],  # Legg inn variablene du vil konvertere til boolske verdier
}

Merknader:

• Variabler som ikke legges inn her, blir ikke endret.

• Hvis du angir en variabel som ikke finnes i dataframen, får du en advarsel.

• Du kan la lister stå tomme hvis ingen variabler skal konverteres i en gitt gruppe.

Du har for eksempel et datasett “df” med klassifikasjonsvariablene “periode”, “bydelsregion” og “alder”, og i tillegg tellevariabelen “personer”. Da lager du mappingen slik:

dtype_mapping = {

“klassifikasjonsvariabel”: [“periode”, “bydelsregion”, “alder”], “heltall”: [“personer”], “desimaltall_1_des”: [], “desimaltall_2_des”: [], “stringvar”: [], “bool_var”: []}

Mappingen er ikke selve funksjonen, men info til funksjonen. Funksjonen skrives slik:

df_konvertert, dtypes = avrunding.konverter_dtypes(df, dtype_mapping)

Til venstre for likhetstegnet ser du to objekter. Det første, i dette tilfellet “df” er alltid det konverterte datasettet. Den andre, i dette tilfellet “dtypes” er typekartleggingen etter konverteringen. I parentesen til høyre for likhetstegnet ser du argumentene, altså inputen/info til funksjonen. Det første er datasettet som skal konverteres, i dette tilfellet “df”. Det andre er mappingen, i dette tilfellet “dtype_mapping” der du har lagt inn variablene som skal konverteres til de ulike typene.

Return type:

tuple[DataFrame, Series]

Parameters:

• df (DataFrame)

• dtype_mapping (dict[str, list[str]])

print_instruks_konverter_dtypes()

Lager instruks for å lage mapping.

Return type:

str

ssb_kostra_python.enkel_editering module

ssb_kostra_python.hjelpefunksjoner module

definere_klassifikasjonsvariable(inputfil)

Definere klassifikasjonsvariablene i datasettet.

Dette er en funksjon der du definerer klassifikasjonsvariablene i datasettet ditt. I KOMPIS ble klassifikasjonsvariablene automatisk identifisert fordi de var forhåndsdefinert og koplet til en bestemt KLASS-kodeliste. Det er så langt ikke lagt til rette for dette på KOSTRA DAPLA. Dette er en funksjon som inngår i en annen, nemlig regionshierarkifunksjonen, så det er ikke meningen at du skal anvende denne direkte på et datasett, men det er mulig. For at hierarkifunksjonen skal fungere etter hensikten, er det nødvendig at du angir de klassifikasjonsvariablene som KOMMER I TILLEGG til periode- og regionsvariabelen. Det gjør du i et tekstfelt som dukker opp når du kjører hierarkifunksjonen.

Return type:

tuple[list[str], list[str]]

Parameters:

inputfil (DataFrame)

format_fil(df_uformatert)

Formatering av periode- og regionsvariabelen.

Dette er en funksjon du kan bruke til å formatere periode- og regionsvariabelen din. Funksjonen forutsetter at periodevariabelen er kalt ‘periode’. Den forutsetter også at regionsvariabelen heter enten ‘bydelsregion’, ‘kommuneregion’ eller ‘fylkesregion’. Ellers får du feilmelding. Den setter - periode til 4-sifret string-variabel. Ledende null(er) legges til dersom antallet sifre er lavere enn 4. - bydelsregion til 6-sifret string-variabel. Ledende null(er) legges til dersom antallet sifre er lavere enn 4. - kommuneregion til 4-sifret string-variabel. Ledende null(er) legges til dersom antallet sifre er lavere enn 4. - fylkesregion til 6-sifret string-variabel. Ledende null(er) legges til dersom antallet sifre er lavere enn 4.

Skriv funksjonen slik:

df_formatert = format_fil(df_uformatert)

Her er “df_uformatert” den filen du ønsker å kjøre funksjonen på og rette formatet i. df_formatert er datasettet som spyttes ut, men du kan kalle den det du måtte ønske.

Parameters:

df_uformatert (DataFrame) – Dataframe som skal formateres.

Return type:

DataFrame

Returns:

Dataframe med formatert periode og regionvariabler.

ssb_kostra_python.kommunekorr module

kostra_kommunekorr(year)

Fetches and compiles data on correspondences between municipalities and related classifications for a given year.

The function retrieves the following:

• Municipality classification (KLASS 131) and manually adds Longyearbyen.

• The correspondence between municipality (KLASS 131) and KOSTRA group (KLASS 112). This request is wrapped in a try-except block to catch HTTP 404 errors and raise a descriptive ValueError.

• The correspondence between municipality (KLASS 131) and county (KLASS 104).

The retrieved data is merged into a single DataFrame containing information on:

• Municipality number (komm_nr) and name (komm_navn)

• County number (fylke_nr) and name (fylke_navn)

• KOSTRA group number (kostra_gr) and name (kostra_gr_navn)

• Validity start and end dates for both KOSTRA group and county classifications.

• Additional columns:

  • ‘fylke_nr_eka’: county number prefixed with “EKA”.

  • ‘fylke_nr_eka_m_tekst’: concatenation of ‘fylke_nr_eka’ and the county name.

  • ‘landet’: a static label “EAK Landet”.

  • ‘landet_u_oslo’: a static label “EAKUO Landet uten Oslo” (set to NaN for Oslo, municipality code “0301”).

Parameters:

year (str) – The year (format “YYYY”) for which data should be fetched.

Returns:

A DataFrame with the following columns:

• komm_nr: Municipality number.

• komm_navn: Municipality name.

• fylke_nr: County number.

• fylke_navn: County name.

• fylke_nr_eka: County number prefixed with “EKA”.

• fylke_nr_eka_m_tekst: Combination of fylke_nr_eka and fylke_navn.

• fylke_validFrom: Start date for county classification validity.

• fylke_validTo: End date for county classification validity.

• kostra_gr: KOSTRA group number.

• kostra_gr_navn: KOSTRA group name.

• kostra_validFrom: Start date for KOSTRA group validity.

• kostra_validTo: End date for KOSTRA group validity.

• landet: Static label for the nation.

• landet_u_oslo: Static label for the nation excluding Oslo.

Return type:

DataFrame

Raises:

• ValueError – If the correspondence between municipality and KOSTRA group is not found (e.g., HTTP 404), or if duplicates are detected for municipality numbers after merging the data.

• HTTPError – If an unexpected HTTP error occurs during data retrieval.

Example

>>> df = kostra_kommunekorr("2025")
>>> df['verdi'] = 1000
>>> groups = [
...     ['komm_nr', 'komm_navn'],
...     ['fylke_nr', 'fylke_navn'],
...     ['kostra_gr', 'kostra_gr_navn'],
...     ['landet_u_oslo'],
...     ['landet']
... ]
>>> agg_list = []
>>> for cols in groups:
...     temp = df.groupby(cols)['verdi'].sum().rename('agg_verdi')
...     agg_list.append(temp)
>>> df_agg = pd.DataFrame(pd.concat(agg_list))

ssb_kostra_python.regionshierarki module

gjennomsnitt_aggregerte_regioner(df, cols, denom_col='teller', decimals=None, restore_original_dtype=True, print_types=True, return_report=False)

Aggregerer regioner og beregner gjennomsnitt.

Funksjonen tar et datasett på kommune-, fylkeskommune- eller bydelsnivå og aggregerer det til regionsgrupperinger. Deretter beregnes gjennomsnitt for angitte kolonner, mens øvrige kolonner summeres. Merk at funksjonen ikke er egnet for andeler (f.eks. «andel_skilte»): en enkel snittberegning kan bli misvisende.

Du må angi:

1. Klassifikasjonsvariablene i datasettet (utenom periode- og regionsvariabelen). Periode og region blir alltid automatisk registrert som klassifikasjonsvariabler.

2. Kolonnene det skal beregnes gjennomsnitt for.

Eksempel uten forhåndsdefinerte klassifikasjonsvariabler:

gjennomsnittskolonner = ["skilte_separerte"]
df_gjennomsnitt = mapping_hierarki.gjennomsnitt_aggregerte_regioner(
    utvalgte_nokkeltall_kommuner_2024,
    cols=gjennomsnittskolonner,
    denom_col="teller",
    decimals=2,
    restore_original_dtype=False,
    print_types=True,
)
display(df_gjennomsnitt)

Eksempel med forhåndsdefinerte klassifikasjonsvariabler:

from unittest.mock import patch
predefined_input = ""
gjennomsnittskolonner = ["andel_skilte_separerte"]
with patch("builtins.input", return_value=predefined_input):
    df_gjennomsnitt = mapping_hierarki.gjennomsnitt_aggregerte_regioner(
        utvalgte_nokkeltall_kommuner_2024,
        cols=gjennomsnittskolonner,
        denom_col="teller",
        decimals=2,
        restore_original_dtype=False,
        print_types=True,
    )
display(df_gjennomsnitt)

Parameters:

• df (DataFrame) – Input-dataframe for aggregering og gjennomsnittsberegning.

• cols (list[str]) – Liste over kolonner som skal gjennomsnittsberegnes.

• denom_col (str) – Kolonne som fungerer som nevner ved aggregering. Standard er “teller”.

• decimals (int | None) – Antall desimaler å runde til. None runder til nærmeste heltall.

• restore_original_dtype (bool) – Hvis True, gjenopprettes opprinnelig dtype etter beregning.

• print_types (bool) – Hvis True, skrives dtypene ut for debug.

• return_report (bool) – Hvis True, returneres også en rapport over dtype-endringer.

Return type:

DataFrame | tuple[DataFrame, dict[str, dict[str, Any]]]

Returns:

DataFrame, eventuelt sammen med en rapport over dtype-endringer.

hierarki(inputfil, aggregeringstype=None, add_region_names=False)

Hierarkisk aggregering.

Utfører hierarkisk regionsaggregering av inputfilen brukeren angir. Funksjonen fastslår regionsnivået basert på kolonnetittelen for regionsvariabelen (“kommuneregion”, “fylkesregion” eller “bydelsregion”).

Regler:

• «kommuneregion» aggregeres automatisk til «EKA», «EKG» og «EAK(UO)». Det anbefales normalt ikke å aggregere fra «kommuneregion» til «fylkesregion» (fylkeskommuner), men det er mulig ved å overstyre parameteren.

• «fylkesregion» aggregeres automatisk til «EAFKXX» og «EAFK(UO)».

• «bydelsregion» aggregeres automatisk til «EAB».

Eksempler:

# La funksjonen velge aggregeringstype automatisk
df_agg = regionshierarki.hierarki(df)

# Overstyring i kommunedata (ikke anbefalt, men mulig)
df_agg = regionshierarki.hierarki(df, aggregeringstype="kommune_til_fylkeskommune")

For at aggregeringen skal bli korrekt, må du angi klassifikasjonsvariabler i datasettet utover periode- og regionsvariabelen. Disse identifiseres automatisk hvis de er riktig navngitt. I Jupyter vil du få et tekstfelt der du kan skrive inn klassifikasjonsvariablene.

Forhåndsdefinert input i notebook:

from unittest.mock import patch
INPUT_PATCH_TARGET = "builtins.input"
predefined_input = "alder"
with patch(INPUT_PATCH_TARGET, return_value=predefined_input):
    df_aggregert = mapping_hierarki.hierarki(df_ikke_aggregert)
display(df_aggregert)

Merk:

• Denne funksjonen aggregerer ikke regionsnavn. Unngå derfor datasett med egen kolonne for regionsnavn under aggregering. Fest eventuelle regionsnavn etterpå i en egen prosess.

Parametre

inputfilpandas.DataFrame

Må inneholde «periode» og nøyaktig én av regionskolonnene: «kommuneregion» (4 sifre), «fylkesregion» (4 sifre, slutter på «00») eller «bydelsregion» (6 sifre).

aggregeringstypestr | None

Valgfritt. Dersom None, bestemmes automatisk av regionkolonnen:

• kommuneregion -> "kommune_til_landet" (kan overstyres til "kommune_til_fylkeskommune")

• fylkesregion -> "fylkeskommune_til_kostraregion"

• bydelsregion -> "bydeler_til_EAB"

Returnerer

pandas.DataFrame

Opprinnelige rader + aggregerte rader. Eventuell kolonnenavnendring (kommuneregion -> fylkesregion) anvendes.

Kaster

KeyError, ValueError

rtype:

DataFrame

Parameters:

• inputfil (DataFrame)

• aggregeringstype (str | None)

• add_region_names (bool)

Return type:

DataFrame

mapping_bydeler_oslo(year='2015')

Mapping av bydelene i Oslo.

Denne funksjonen er ikke en funksjon du skal anvende direkte på et datasett. Her lages kun en mappingfil som viser hvordan Oslos bydeler inngår i samlebydelen “EAB”. Dette er altså bare en hjelpefunksjon som inngår i en annen funksjon, hierarkifunksjonen, som aggregerer opp bydelsdata til “EAB” kun dersom inputfilen er en bydelsfil.

Return type:

DataFrame

Parameters:

year (str | int)

mapping_fra_fylkeskommune_til_kostraregion(year)

Mapping fra fylkeskommune til KOSTRA-region (EAFK).

Denne funksjonen er ikke en funksjon du skal anvende direkte på et datasett. Her lages kun en mappingfil som viser hvordan fylkeskommunene inngår i de ulike KOSTRA-fylkesgruppene et bestemt år. Dette er altså bare en hjelpefunksjon som inngår i annen funksjon, hierarkifunksjonen, som aggregerer opp fylkeskommunedata til de forskjellige regionsgrupperingene kun dersom inputfilen er en fylkeskommunefil.

Return type:

DataFrame

Parameters:

year (str | int)

mapping_fra_kommune_til_fylkeskommune(year)

Mapping fra kommune til fylkeskommune.

Denne funksjonen er ikke en funksjon du skal anvende direkte på et datasett. Her lages kun en mappingfil som viser hvordan kommunene inngår i de ulike fylkeskommunene et bestemt år. Dette er altså bare en hjelpefunksjon som inngår i annen funksjon, hierarkifunksjonen, som aggregerer opp kommunedata til de forskjellige regionsgrupperingene kun dersom inputfilen er en kommunefil.

Return type:

DataFrame

Parameters:

year (str | int)

mapping_fra_kommune_til_landet(year)

Mapping av kommunene til landet.

Denne funksjonen er ikke en funksjon du skal anvende direkte på et datasett. Her lages kun en mappingfil som viser hvordan kommunene inngår i fylker, Kostra-grupper og landet et bestemt år. Dette er altså bare en hjelpefunksjon som inngår i annen funksjon, hierarkifunksjonen, som aggregerer opp kommunedata til de forskjellige regionsgrupperingene kun dersom inputfilen er en kommunefil.

Return type:

DataFrame

Parameters:

year (str | int)

overfore_data_fra_fk_til_k(inputfil)

Legge fylkeskommunedata over på alle tilhørende kommuner.

Denne funksjonen legger data som kun finnes på fylkes- eller fylkeskommunenivå over på kommunenivå. Eksempel: Hvis forventet levealder for kvinner er 85.3 år i Vestland fylkeskommune (4600) i 2024, kan funksjonen legge 85.3 som forventet levealder for kvinner i alle kommuner i Vestland (46XX).

Også her må du angi klassifikasjonsvariabler utover periode- og regionsvariabelen.

Enkel bruk:

df_kommune = mapping_hierarki.overfore_data_fra_fk_til_k(df_fylke)
display(df_kommune)  # valgfritt

Forhåndsdefinerte klassifikasjonsvariabler:

from unittest.mock import patch
INPUT_PATCH_TARGET = "builtins.input"
predefined_input = "ekstra_klassifikasjonsv_1, ekstra_klassifikasjonsv_2"
with patch("builtins.input", return_value=predefined_input):
    df_kommune = mapping_hierarki.overfore_data_fra_fk_til_k(df_fylke)
display(df_kommune)

Return type:

DataFrame

Parameters:

inputfil (DataFrame)

ssb_kostra_python.summere_kjonn module

summere_over_kjonn(inputfil)

Summér statistikkvariabler over kjønn hvis ‘kjonn’ finnes i datasettet.

Parameters:

inputfil (DataFrame) – Datasettet som skal summeres.

Return type:

DataFrame

Returns:

Datasettet summert over kjønn, eller originalt datasett hvis ‘kjonn’ ikke finnes.

ssb_kostra_python.summere_til_aldersgrupperinger module

summere_til_aldersgrupperinger(inputfil, hierarki_path='/buckets/delt-kostra-befolkning-delt/aldershierarki/mapping_aldershierarki.parquet')

Aggregerer individbaserte aldersverdier til forhåndsdefinerte aldersgrupper.

Dette gjøres ved hjelp av KOSTRA-aldersgrupperingshierarkiet, og de aggregerte verdiene slås sammen med originaldatasettet.

Funksjonen:

• Leser inn et aldershierarki fra fil (parquet).

• Tilpasser datatyper og formatering for korrekt kobling.

• Mapper individuelle aldersverdier til aldersgrupper (“from” → “to”).

• Summerer statistikkvariabler (f.eks. antall personer) over aldersgrupper.

• Bevarer øvrige klassifikasjonsvariabler (f.eks. periode, kjønn, region).

• Returnerer et datasett som inneholder både originale aldre og aggregerte aldersgrupper.

Parametere

inputfilpd.DataFrame

Inndatafil med individbaserte eller finmaskede aldersverdier. Forutsetter minst følgende kolonner:

• periode (år)

• alder (3-sifret alderskode)

  • én eller flere statistikkvariabler (f.eks. personer)

hierarki_path : str Filsti til parquet-fil som inneholder aldershierarki.

Forutsetter følgende kolonner:

• periode : år

• from : alder (finmaskert nivå)

• to : aldersgruppe

Returverdier

rename_variabellist[str]

Liste med variabler som erstattes i aggregeringen (for tiden ['alder']).

groupby_variablelist[str]

Klassifikasjonsvariabler som brukes i gruppering ved aggregering (alle klassifikasjonsvariabler unntatt alder).

df_combinedpd.DataFrame

Datasett som inneholder både:

• opprinnelige aldersnivåer

• aggregerte aldersgrupper

med identiske klassifikasjons- og statistikkvariabler.

Merknader

• Kun perioder som finnes i inputfil blir brukt fra hierarkifilen.

• Aldershierarkiet forventes å være entydig per periode og alder.

• Funksjonen forutsetter at hjelpefunksjoner håndterer korrekt identifikasjon av klassifikasjons- og statistikkvariabler.

rtype:

DataFrame

Parameters:

• inputfil (DataFrame)

• hierarki_path (str)

Return type:

DataFrame

ssb_kostra_python.titler_til_klasskoder module

kodelister_navn(df, mappings, *, language='nb', include_future=True, verbose=True)

Med denne funksjonen kan du feste kodenavn på klassifikasjonsvariablene i tråd med KLASS-kodelisten for det ENE året datasettet gjelder.

Funksjonen lager en ekstra kolonne på datasettet ditt med kodenavnene. For at funksjonen skal fungere, må du gi informasjon om kolonnen til klassifikasjonsvariabelen, den tilhørende KLASS-kodelisten, samt tittelen du ønsker på kolonnen med kodenavnene. Kolonnetittel er valgfritt, og dersom du ikke angir noe, blir kolonnetittelen automatisk satt til “kolonne_navn”. For eksempel blir “bydelsregion” satt til “bydelsregion_navn”. Du lager da en såkalt mapping som vist under. Mappingen er en liste bestående av dictionaries, én for hver variabel.

df: Datasettet må inneholde en periodevariabel kalt “periode” med én unik verdi, med andre ord kan ikke datasettet inneholde flere årganger.

Her er et eksempel. Vi har et datasett med klassifikasjonsvariablene “periode”, “bydelsregion” og “alder” og statistikkvariabelen “personer”. Vi ønsker å feste kodenavn på “bydelsregion” og “alder”. Bydelene er knyttet til KLASS-liste 241 og alder er tilknyttet KLASS-liste 248. “select_level” settes alltid til 1. Først lager vi mappingen.

mapping_klassifikasjonsvariable = [{“code_col”: “bydelsregion”, “klass_id”: 241, “name_col_out”: “bydelsregion_navn”, “select_level”: 1},

{“code_col”: “alder”, “klass_id”: 248, “name_col_out”: “alder_navn”, “select_level”: 1},]

Når mappingen er laget, kjøres funksjonskoden slik:

df_med_kodenavn, sammendrag = titler_til_klasskoder.kodelister_navn( df_uten_kodenavn, mappings=mapping_klassifikasjonsvariable, language=”nb”, include_future=True, verbose=True, ) display(df_med_kodenavn)

Funksjonen genererer to objekter til venstre for likhetstegnet. “df_med_kodenavn” er datasettet med kolonner for kodenavnene. Sammendraget av operasjonen ligger i “sammendrag”. I parentesen finner vi “df_uten_kodenavn”, som er det opprinnelige datasettet. Mappingen ligger i “mappings”, den definerte vi manuelt i forkant. Siden KLASS-kodene er lagret på tre språk, velger vi i utgangspunktet “nb” for bokmål. “include_future” settes til “True” som en forhåndsinnstilling. Det samme gjelder “verbose”, settes til “True”. Til slutt kan vi sette display(df_med_kodenavn) for å se det endelige datasettet.

Apply multiple (code_col, klass_id) mappings for the year in df['periode'].

Parameters:

• df (DataFrame) – Must contain 'periode' with exactly one unique year.

• mappings (list[dict[str, Any]]) –

  List of dictionaries. Each dict has the following keys::

  {

  “code_col”: “kommunenr”, # required “klass_id”: 131, # required “name_col_out”: “kommunenr_navn”, # optional; default <code_col>_navn “select_level”: 1, # optional

  }

• language (Literal['nb', 'nn', 'en']) – Language code passed to KLASS. {“nb”, “nn”, “en”}, default “nb”.

• include_future (bool) – Whether to include future codes in KLASS. default True

• verbose (bool) – Whether to print diagnostic messages. default True

Returns:

df_out: Original DF with each name column inserted right after its code column.

diag: Per-pair diagnostics keyed by code_col (or code_col|klass_id if duplicates).

Return type:

tuple[DataFrame, dict[str, Any]]

Raises:

ValueError – If 'periode' is missing or contains multiple unique years.

mapping_regionsnavn(inputfil, *, language='nb', region_col=None, name_suffix='_navn')

Denne funksjonen kan du bruke til å feste regionsnavn på regionskodene dine.

Så lenge regionsvariabelen heter “bydelsregion”, “kommuneregion” eller “fylkesregion”, vil funksjonen feste riktig regionsnavn fra KLASS for det året datasettet gjelder. Dersom regionsvariabelen heter noe annet enn dette, må den omdøpes til riktig regionsnivå.

Funksjonen henter regionsnavn fra følgende KLASS-kodelister:

“kommuneregion”: 231 “fylkesregion”: 232 “bydelsregion”: 241

Denne funksjonen bør du bruke ETTER at du har utført hierarkiaggregeringen, og IKKE før. Grunnen til dette er at hierarkiaggregeringsfunksjonen fungerer til å aggregere regionskodene, men ikke regionsnavnene. Om du trenger å se regionsnavn både før og etter regionsaggregering, kan du da feste regionsnavn i første omgang, fjerne dem i forkant av regionsaggregeringen, og feste dem igjen etter at regionsaggregeringen er utført.

Slik bruker du funksjonen:

df_regionsnavn = titler_til_klasskoder.mapping_regionsnavn(df_uten_regionsnavn)

Datasettet til venstre for likhetstegnet er datasettet som genereres med regionsnavn tilhørende regionskoden. I parentesen ligger datasettet du ønsker å føre regionsnavn på.

Return type:

DataFrame

Parameters:

• inputfil (DataFrame)

• language (Literal['nb', 'nn', 'en'])

• region_col (str | None)

• name_suffix (str)

ssb_kostra_python.validering module