ssb_befolkning_fagfunksjoner.klass_utils package¶

ssb_befolkning_fagfunksjoner.klass_utils.change_mapping module¶

get_klass_change_mapping(classification, target_date=None, from_date=None, to_date=None)¶

Normalise codes from different time to a specified target date based on KLASS change tables.

Parameters:

classification (KlassClassification) – A KlassClassification object.
target_date (date | None) – The date you want to normalize into.
from_date (date | None) – The oldest date in the dataset
to_date (date | None) – The newest date in the dataset

Return type:

Series

Returns:

A pandas series mapping existing to normalized codes, with existing codes as index labels, and normalized codes as values. The index can contain duplicated labels.

Raises:

ValueError – if the target_date is older than the from_date or older than the Klass classifcation if no from_date is set.

ssb_befolkning_fagfunksjoner.klass_utils.komm_nr module¶

get_komm_nr_changes(from_date=datetime.date(1980, 1, 1), to_date=None, target_date=None)¶

Load municipality code (komm_nr) changes from KLASS.

Parameters:

from_date (str | date) – str | datetime.date Lower bound date for change history to include. Defaults to 1980-01-01.
to_date (str | date | None) – str | datetime.date | None Upper bound date for change history to include. Defaults to today.
target_date (str | date | None) – str | datetime.date | None Target date for municipality code mappings. Defaults to today.

Return type:

tuple[DataFrame, DataFrame]

Returns:

tuple[pd.DataFrame, pd.DataFrame]: A tuple (changes, splits) with mappings from old_code to new_code. Split into codes that map to exactly one new code, and codes that map to multiple new codes.

Raises:

ValueError – If any of the input parameters are not the correct type.

update_komm_nr(original_codes, year, validate=True)¶

Update municipality codes based on KLASS change tables.

This function: - Applies recursive updates from the old_code → new_code mappings until the latest code is reached. - Replaces missing values with ‘0000’ and logs their count. - Logs the number of updated municipality codes and a distribution table. - Checks for municipality splits and logs warnings if any are found. - Validates that all updated codes exist in the official KLASS list for the given year.

Parameters:

original_codes (Series) – pd.Series A pandas Series containing the original municipality codes.
year (int | str) – int | str The year for which to apply the KLASS mappings.
validate (bool) – bool Boolean flag which determines whether to run validation or not (default = True).

Return type:

Series

Returns:

pd.Series[str]: A pandas Series containing the updated municipality codes.

validate_komm_nr(codes, year)¶

Validate that all codes exist in the KLASS codelist for the given year.

Return type:

None

Parameters:

codes (Series)
year (int | str)

ssb_befolkning_fagfunksjoner.klass_utils.level_mapping module¶

aggregate_codes(codes, to_level, *, version=None, classification=None, date=None, keep_others=False)¶

Overloads:

codes (pd.Series), to_level (int | str), version (None), classification (klass.KlassClassification), date (datetime.date), keep_others (bool) → pd.Series
codes (pd.Series), to_level (int | str), version (klass.KlassVersion), classification (None), date (None), keep_others (bool) → pd.Series

Parameters:

codes (Series)
to_level (int | str)
version (KlassVersion | None)
classification (KlassClassification | None)
date (date | None)
keep_others (bool)

Return type:

Series

Aggregates codes to selected level with Klass.

Parameters:

codes (Series) – A series with codes, that you want to aggregate.
to_level (int | str) – The level you want to aggregate up to. Either a index (like “1”) or a label (like “NUTS 3”).
version (KlassVersion | None) – The Klass version you want to use, or
classification (KlassClassification | None) – the Klass classification you want to use, and
date (date | None) – a date where the klass version you want to use is valid.
keep_others (bool) – Do you want to keep codes that are above level you want to aggregate to or sentinel values?

Returns:

A series where the values are aggregated to the select level.

Raises:

ValueError – If neither a Klass version is given or a class classification and a date is given. If no Klass version is valid at the given date. If the selected level is not found.

Return type:

Series

get_klass_level_map(to_level, *, version=None, classification=None, date=None)¶

Overloads:

to_level (int | str), version (None), classification (klass.KlassClassification), date (datetime.date) → pd.Series
to_level (int | str), version (klass.KlassVersion), classification (None), date (None) → pd.Series

Parameters:

to_level (int | str)
version (KlassVersion | None)
classification (KlassClassification | None)
date (date | None)

Return type:

Series

Creates a mapping to a level in a Klass version, from all children codes.

Parameters:

to_level (int | str) – The level you want to aggregate up to. Either a index (like “1”) or a label (like “NUTS 3”).
version (KlassVersion | None) – The Klass version you want to use, or
classification (KlassClassification | None) – the Klass classification you want to use, and
date (date | None) – a date where the Klass version you want to use is valid.

Returns:

A series where the index contains children codes, and the values contains the targeted parent code.

Raises:

ValueError – If neither a Klass version is given or a class classification and a date is given. If no Klass version is valid at the given date. If the selected level is not found.

Return type:

Series

ssb_befolkning_fagfunksjoner.klass_utils.loaders module¶

load_country_codes()¶

Load KLASS correspondence table for country codes.

Return type:: dict[str, str]

load_komm_nr(year)¶

Load KLASS codelist for municipalities.

Return type:: dict[str, str]
Parameters:: year (int | str)

load_verdensinndeling(year)¶

Load and transform KLASS world division codes to regional groups.

Return type:: dict[str, int]
Parameters:: year (int | str)

ssb_befolkning_fagfunksjoner.klass_utils.mappers module¶

map_to_country_codes(alpha_3_col)¶

Convert a Series of ISO alpha-3 codes to SSB-3 codes.

Parameters:: alpha_3_col (Series) – pd.Series A pandas series of citizenships that may contain scalars (e.g., “NOR”) or sequences (e.g., [“NOR”, “SWE”]).
Return type:: Series
Returns:: pd.Series