ssb_timeseries.sample_data

The ssb_timeseries.sample_data module provides tools for creating sample timeseries data. These are convenience functions for tests and demos.

POPU06_MAIN_COUNTRIES = ('Denmark', 'Finland', 'Iceland', 'Norway', 'Sweden')

The five Nordic countries reported in POPU06.

Every one of them is projected for 2027 to 2046, the longest span shared by all reporting countries. Denmark, Iceland, Norway and Sweden are projected all the way to 2070.

POPU06_SOURCE = 'https://pxweb.nordicstatistics.org/api/v1/en/Nordic Statistics/Demography/Population projections/POPU06.px'

Table the static POPU06_POPULATION values are copied from.

create_df(*lists, start_date='', end_date='', freq='D', interval=1, separator='_', midpoint=100, variance=10, temporality='AT', decimals=0, implementation='pandas', tz=zoneinfo.ZoneInfo(key='Europe/Oslo'))

Generate sample data for specified date range and permutations over lists.

Parameters:

  • start_date (datetime | str) – The start date of the date range. Optional, default is today - 365 days.

  • end_date (datetime | str) – The end date of the date range. Optional, default is today.

  • *lists (dict | list[str] | tuple | str) – Lists of values to generate combinations from.

  • freq (str) – The frequency of date generation. ‘Y’ for yearly at last day of year, ‘YS’ for yearly at first day of year, ‘M’ for monthly at last day of month, ‘MS’ for monthly at first day of month, ‘W’ for weekly on Sundays, ‘D’ for daily, ‘H’ for hourly, ‘T’ for minutely, ‘S’ for secondly, etc. Optional, default is ‘D’.

  • interval (int) – The interval between dates. ; optionalDefault is 1.

  • separator (str) – The separator used to join combinations. Optional, default is ‘_’.

  • midpoint (int | float) – The midpoint value for generating random data. Optional, default is 100.

  • variance (int | float) – The variance value for generating random data. Optional, default is 10.

  • temporality (str) – The temporality of the data. Default is ‘AT’.

  • decimals (int) – The number of decimal places to round to. Optional, default is 0.

  • implementation (str) – Narwhals supported dataframe library or object type.

  • tz (str | ZoneInfo | None) – Timezone to convert data to after generation; uses DFAULT_TZ if not specified.

Return type:

typing.Any

Returns:

A DataFrame or similar object (Numpy array, Arrow table, dict) containing sample data.

Example

# Generate sample data with no specified start or end date (defaults to +/- infinity)
sample_data = generate_sample_df(List1, List2, freq='D')
date_ranges(start_date, end_date, freq, interval=1, temporality='AT', tz=zoneinfo.ZoneInfo(key='Europe/Oslo'))

Generate a list of dates with a specified frequency.

Return type:

dict[str, list[datetime]]

Parameters:

  • start_date (datetime | str)

  • end_date (datetime | str)

  • freq (str)

  • interval (int)

  • temporality (str)

  • tz (ZoneInfo | str | None)

popu06(countries=None, start_year=None, end_year=None, implementation='pandas', tz=zoneinfo.ZoneInfo(key='Europe/Oslo'))

Return Nordic population projections from the static POPU06 table.

Unlike the randomly generated helpers in this module, the values are real and reproducible. One series is returned per reporting country, so the series names are country names.

Projections are not published for every country for every year. Countries with a shorter projection than the requested period yield None for the missing years.

Parameters:

  • countries (list[str] | tuple[str, ...] | None) – Reporting countries to include, one series each. Defaults to every country in POPU06_POPULATION.

  • start_year (int | None) – First projection year to include. Defaults to the first year in POPU06_YEARS.

  • end_year (int | None) – Last projection year to include. Defaults to the last year in POPU06_YEARS.

  • implementation (str) – Narwhals supported dataframe library or object type.

  • tz (str | ZoneInfo | None) – Timezone of the generated date column.

Return type:

typing.Any

Returns:

A dataframe with a ‘valid_at’ column and one column per country.

Raises:

  • ValueError – If a requested country is not in POPU06_POPULATION.

  • ValueError – If the requested period contains no projection year.

Example

from ssb_timeseries.sample_data import POPU06_MAIN_COUNTRIES, popu06

nordic = popu06(countries=POPU06_MAIN_COUNTRIES, start_year=2030)
random_numbers(rows, cols, decimals=0, midpoint=100, variance=10)

Generate sample dataframe of specified dimensions.

Return type:

ndarray

Parameters:

  • rows (int)

  • cols (int)

  • decimals (int)

  • midpoint (int | float)

  • variance (int | float)

series_names(*args, **kwargs)

Return all permutations of the elements of multiple groups of strings.

Parameters:

  • *args (dict | str | list[str] | tuple) – Each arg in args should be a collection of names to be combined with the other.

  • **kwargs (str) – One option: ‘separator’ defines a character sequence inserted between name elements. Defaults to ‘_’.

Return type:

list[str]

The choice of ‘_’ as default separator is not arbitrary: Some functionality,notably Dataset.vectors(), use series names to create Python variables. A default separator that is valid in a variable name simnplifies that.

Returns:

List of names to be used as series names.

Return type:

list[str]

Raises:

ValueError – If an argument of an invalid type is passed.

Parameters:

  • args (dict | str | list[str] | tuple)

  • kwargs (str)

xyz_at(implementation='pandas')

Return a Temporality.AT compliant dataframe with a year of monthly data for series ‘x’, ‘y’ and ‘z’.

Return type:

typing.Any

Parameters:

implementation (str)

xyz_from_to(implementation='pandas')

Return a Temporality.FROM_TO compliant dataframe with a year of monthly data for series ‘x’, ‘y’ and ‘z’.

Return type:

typing.Any

Parameters:

implementation (str)