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.

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

dataframe_cell_editor_mvp(df, *, preview_rows=30, log_rows=None)

Interactive, user-friendly dataframe cell editor for Jupyter notebooks.

This function launches an ipywidgets-based UI that allows non-technical users to safely edit individual cell values in a pandas DataFrame, with strong guardrails to prevent accidental bulk edits and with full change logging.

Workflow:

• Filter rows using exact-match filters on classification variables.

• Review the filtered slice (editing is only allowed if ≤ 250 rows).

• Commit controlled cell edits with a required reason.

• Preview the updated dataframe and change log.

The original input dataframe is never modified. All edits are applied to an internal working copy.

Key features:

• Designed for large dataframes (hundreds to millions of rows).

• Exact-match, AND-only filtering on classification variables.

• Editing allowed only on small slices (≤ 250 rows).

• Supports editing numeric, boolean, and string statistical variables.

• Safe type coercion based on column dtype (e.g. Int64, Float64, string).

• Optional setting of missing values (NaN / pd.NA where supported).

• Required reason for every committed edit.

• Full, row-level change log created at edit time.

• Automatic UI refresh after each commit:

  • filtered slice preview

  • edited dataframe preview

  • change log

Parameters:

• df (DataFrame) – The input dataframe to be edited. This dataframe is not modified.

• preview_rows (int) – Number of rows to display in the “Edited dataframe (preview)” panel. This is a preview only; the full edited dataframe is still available via the returned function.

• log_rows (int | None) – If None, display the full change log in the UI. If an integer, display only the last log_rows entries in the UI.

Return type:

Callable[[], tuple[DataFrame, DataFrame]]

User interface behavior:

• Filtering is performed using text inputs with exact string matching.

• Filters are combined using logical AND.

• If the filter matches more than 250 rows, editing is blocked until the filter is narrowed.

• Users may apply edits to either all matched rows, or a selected subset within the filtered slice.

• Each edit operation modifies exactly one column per commit.

• After each commit:

  • a confirmation message is shown

  • the preview table updates automatically

  • the edited dataframe preview refreshes

  • the change log refreshes

Returns: - get_results: A zero-argument function that returns the current edited dataframe and the full change log.

Example:

get_results = enkel_editering.dataframe_cell_editor_mvp(df_to_be_edited)
df_edited, change_log_df = get_results()
display(df_edited)
display(change_log_df)

Where:

• df_edited (pandas.DataFrame): The fully edited dataframe (original unchanged).

• change_log_df (pandas.DataFrame): One row per committed cell edit, including timestamp, user,

  row identifier, column edited, old value, new value, reason, and a snapshot of classification variables.

Notes

• Intended for interactive use in Jupyter environments.

• Relies on ipywidgets and a live kernel.

• Builds upon definere_klassifikasjonsvariable() to identify classification vs statistical variables.

• Persistence (saving edited data or logs to disk) is intentionally left out and can be added later if needed.

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.

Raises:

ValueError – If no valid region column is found.

konvertere_komma_til_punktdesimal(inputfil)

Konvertere komma til punktdesimal i datasettet.

Return type:

DataFrame

Parameters:

inputfil (DataFrame)

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:

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

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 = mapping_hierarki.hierarki(df)

# Overstyring i kommunedata (ikke anbefalt, men mulig)
df_agg = mapping_hierarki.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)

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)

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:

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

Parameters:

• inputfil (DataFrame)

• hierarki_path (str)

Return type:

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

ssb_kostra_python.titler_til_klasskoder module

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

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:

A tuple containing

Raises:

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

ssb_kostra_python.validering module

show_toggle(df, mask, title, *, preview_rows=15)

Renders a compact toggle to reveal offending rows on demand.

• Always shows a title

• Shows a ToggleButton if there are rows; clicking displays a preview table

Return type:

None

Parameters:

• df (DataFrame)

• mask (Series)

• title (str)

• preview_rows (int)

validering(inputfil, klassifikasjonsvariable=None)

Alle enkeltsjekkene samlet i én funksjon. Denne funksjonen er den som skal kjøres for å validere datasettet ditt.

Denne funksjonen kjører flere sjekker etter hverandre. Funksjonen trenger å vite filen som skal undersøkes (inputfil) og klassifikasjonsvariablene som inngår i datasettet (klassifikasjonsvariable). Om du ikke har definert klassifikasjonsvariablene i tidligere i løpet, kan du skrive koden for eksempel slik:

klassifikasjonsvariable = [‘periode’, ‘bydelsregion’, ‘helsekontroller’] mapping_hierarki.validering(navn_på_din_fil, klassifikasjonsvariable)

Return type:

None

Parameters:

• inputfil (DataFrame)

• klassifikasjonsvariable (list[str] | None)