re-export magrittr pipe operator

Description

re-export magrittr pipe operator

Arguments

Allowed entities: Kolada metadata classes

Description

Allowed entities: Kolada metadata classes

Usage

allowed_entities()

Value

A vector of names of allowed metadata entities, i.e. the correct spelling of all allowed values of the entity parameter in get_metadata.

Compose a query to fetch metadata from the Kolada API. Its use is mainly

Description

Mainly used as a supporting function for get_values but can also be used to create a working URL to paste in your web browser.

Usage

compose_data_query(
  kpi = NULL,
  municipality = NULL,
  period = NULL,
  ou = NULL,
  unit_type = "municipality",
  page = NA,
  per_page = NA,
  version = "v2"
)

Arguments

Value

A string containing a URL to the Kolada REST API.

Compose a query to fetch metadata from the Kolada API.

Description

Mainly used as a supporting function for get_metadata but can also be used to create a working URL to paste in your web browser.

Usage

compose_metadata_query(
  entity = "kpi",
  title = NULL,
  id = NULL,
  municipality = NULL,
  page = NA,
  per_page = NA,
  version = "v2"
)

Arguments

Value

A string containing a URL to the Kolada REST API.

Generate KPI metadata from a Kolada KPI object

Description

Generate KPI metadata from a Kolada KPI object

Usage

generate_kpi_metadata(kpi_df)

Arguments

Value

a Kolada KPI metadata table

Download metadata for a specific entity from the Kolada API

Description

There are five different types of metadata entities in the Kolada database: "kpi", "kpi_groups", "municipality", "municipality_groups", and "ou". For every entity there is a corresponding function get_ENTITY which retrieves a table with the metadata for that entity. The get_ENTITY functions are thin wrappers around get_metadata.

Usage

get_kpi(
  id = NULL,
  max_results = NULL,
  cache = FALSE,
  cache_location = tempdir,
  verbose = FALSE
)

get_kpi_groups(
  id = NULL,
  cache = FALSE,
  max_results = NULL,
  cache_location = tempdir,
  verbose = FALSE
)

get_ou(
  id = NULL,
  municipality = NULL,
  max_results = NULL,
  cache = FALSE,
  cache_location = tempdir,
  verbose = FALSE
)

get_municipality(
  id = NULL,
  cache = FALSE,
  max_results = NULL,
  cache_location = tempdir,
  verbose = FALSE
)

get_municipality_groups(
  id = NULL,
  cache = FALSE,
  max_results = NULL,
  cache_location = tempdir,
  verbose = FALSE
)

Arguments

Value

Returns a tibble with metadata for the specified entity. In rKolada terminology, a table returned by e.g. get_kpi is referred to as a kpi_df and can be passed to functions starting with "kpi" such as kpi_bind_keywords.

Examples

# Download KPI table and store a cache copy of the results in a temporary folder
# (to actually download all available data, don't specify max_results)
if (kolada_available()) {
kpi_df <- get_kpi(cache = TRUE, max_results = 100)
}

Download metadata from the Kolada API

Description

This is a generalized function for downloading metadata from the Kolada API. The function parameters closely mask the names specified in the original API. For further information about the Kolada API specification, please see the official documentation on GitHub.

Usage

get_metadata(
  entity = "kpi",
  title = NULL,
  id = NULL,
  municipality = NULL,
  max_results = NULL,
  cache = FALSE,
  cache_location = tempdir,
  verbose = FALSE
)

Arguments

Value

Returns a tibble with metadata for the specified entity. In rKolada terminology, a table returned by e.g. entity = "kpi" is referred to as a kpi_df and can be passed to functions starting with "kpi" such as kpi_bind_keywords.

See Also

get_kpi, get_kpi_groups, get_municipality, get_municipality_groups, get_ou

Get data from Kolada

Description

Download a table of data from Kolada. Data is selected based on three metadata dimensions: KPI (ID), municipality (ID) and period (years). You must supply arguments for at least two of these three dimensions. If a dimension is omitted, all available data for that dimension will be downloaded.

Usage

get_values(
  kpi = NULL,
  municipality = NULL,
  period = NULL,
  ou = NULL,
  unit_type = "municipality",
  max_results = NULL,
  simplify = TRUE,
  verbose = FALSE
)

Arguments

Value

A tibble containing Kolada values and metadata.

Examples

# Download data for KPIs for Gross Regional Product ("BRP" in Swedish)
# for three municipalities
if (kolada_available()) {

# If you already know the ID numbers you are looking for,
# you can use these directly as argments.
# Otherwise, use the get_\*() functions in combination with \*_search()
# functions to find good parameter values.
grp_data <- get_values(
  kpi = c("N03700", "N03701"),
  municipality = c("0180", "1480", "1280")
)

# To download OU data instead of Municipality data, set the parameter
# "unit_type" to "ou".
ou_data <- get_values(
 kpi = "N15033",
 ou = "V15E144001101",
 unit_type = "ou"
)
}

Check if the Kolada API is available

Description

Check if the Kolada API is available and if data from the API makes sense. This is primarily useful for programming with rKolada and/or examples.

Usage

kolada_available()

Add keyword columns to a Kolada KPI table

Description

Identify n keywords describing the KPI and add them as new columns. Keywords are inferred from the title field of the table.

Usage

kpi_bind_keywords(kpi_df, n = 2, form = c("wide", "long"))

Arguments

Value

A Kolada KPI metadata table

Examples

if (kolada_available()) {
kpi_df <- get_kpi(id = c("N45933", "U28563")) %>%
  kpi_bind_keywords(n = 3)
}

Describe the KPIs in a Kolada KPI metadata table

Description

Print a human-readable description of each entity of a KPI metadata table (up to a maximum number of rows). Can be printed either directly to the R console or used to populate a R markdown document, which can be useful for documentation purposes.

Usage

kpi_describe(
  kpi_df,
  max_n = 5,
  format = "inline",
  heading_level = 2,
  sub_heading_level = heading_level + 1
)

Arguments

Value

Returns the object passed to the function, invisibly, to be re-used in a pipe.

Extract a vector of KPI ID strings from a Kolada KPI metadata table

Description

This function is primarily intended as a convenient way to pass a (filtered) Kolada KPI metadata table to get_values.

Usage

kpi_extract_ids(kpi_df)

Arguments

Value

A vector of KPI IDs.

Examples

if (kolada_available()) {
# Download Kolada data for the first KPI in the list matching the term "Grundskola" (primary school)
# for the years 2010-2019
# (omit the parameter "max_results" to actually download all data)
kpi_filter <- get_kpi(max_results = 500) %>%
  kpi_search("Grundskola")

# Only keep the top row
kpi_filter <- kpi_filter[1, ]

# Only download 100 observations
# (omit the parameter "max_results" to actually download all data)
kld_data <- get_values(
  kpi = kpi_extract_ids(kpi_filter),
  period = 2010:2019,
  max_results = 100
)
}

Describe the KPIs in a Kolada KPI Group metadata table

Description

Print a human-readable description of each row of a KPI Group metadata table, including member KPIs (up to a maximum number of rows). Can be printed either directly to the R console or used to populate a R markdown document, which can be useful for documentation purposes.

Usage

kpi_grp_describe(
  kpi_grp_df,
  max_n = 5,
  format = "inline",
  heading_level = 2,
  sub_heading_level = heading_level + 1
)

Arguments

Value

Returns the object passed to the function, invisibly, to be re-used in a pipe.

Extract KPI ID strings from a Kolada KPI Group metadata table

Description

This function is primarily intended as a convenient way to pass a (filtered) Kolada KPI Group metadata table to get_values. All IDs of the KPIs contained in each group in the table are extracted.

Usage

kpi_grp_extract_ids(kpi_grp_df)

Arguments

Value

A vector of KPI IDs.

Search a Kolada KPI Group metadata table for group names

Description

Search a Kolada KPI Group metadata table. Only keep rows that contain the search query. Searches group titles and group IDs. Note that this function does not search for individual KPIs contained within KPI groups! To search for KPIs within a KPI group, see examples below for an example using kpi_grp_unnest.

Usage

kpi_grp_search(kpi_grp_df, query)

Arguments

Value

A Kolada KPI Group metadata table

Examples

if (kolada_available()) {
kpi_grp_df <- get_kpi_groups()

# Which KPI groups match the keyword "ekonomi" (economy)?
kpi_grp_df %>% kpi_grp_search("ekonomi")

# Which KPI groups contain KPIs matching the keyword "arbete" (work/labour)?
kpi_grp_df %>%
  kpi_grp_unnest() %>%
  kpi_search("arbete") %>%
  dplyr::count(group_title, sort = TRUE)
}

Create a KPI table from a Kolada KPI Group metadata table

Description

KPI groups are a convenient way to discover sets of KPIs that can be used to highlight different aspects of a policy area. A practical workflow for discovering such sets can be to search through KPI Group metadata using kpi_grp_search to search for keywords and kpi_grp_describe to inspect contents of KPI groups. Once you have created a KPI group table that has been narrowed down to the group/s you are looking for, kpi_grp_unnest is used to create a KPI metadata table for further processing.

Usage

kpi_grp_unnest(kpi_grp_df)

Arguments

Value

A Kolada KPI metadata table

Examples

if (kolada_available()) {
# Download KPI Group metadata
kpi_grp_df <- get_kpi_groups()

# Create a KPI metadata table from KPI groups matching the term
# "utbidning" (education)
kpi_grp_df %>%
  kpi_grp_search("utbildning") %>%
  kpi_grp_unnest()
}

Simplify a KPI table

Description

Remove all columns from a Kolada KPI metadata table that are monotonous across the table, i.e. columns that contain only one single value. Also remove undocumented columns, i.e. columns that contain unintelligible and undocumented information.

Usage

kpi_minimize(
  kpi_df,
  remove_undocumented_columns = TRUE,
  remove_monotonous_data = TRUE
)

Arguments

Value

A Kolada KPI metadata table

Search for Kolada KPIs using a Kolada KPI table

Description

Search a Kolada KPI metadata table. Only keep rows that contain the search query. Matches against all columns or columns named with the column parameter. For more precise matching, please use dplyr::filter.

Usage

kpi_search(kpi_df, query, column = NULL)

Arguments

Value

A Kolada KPI metadata table

Examples

if (kolada_available()) {
# Search for a single search term in a KPI table
kpis <- get_kpi(id = c("N11002", "N11003", "N11004", "N11005"))
kpi_filter <- kpi_search(kpis, "kostnad")

# Add keywords to a KPI table and search for multiple terms among
# the keywords
kpi_filter <- get_kpi(id = c("N11002", "N11003", "N11004", "N11005")) %>%
  kpi_bind_keywords(n = 3) %>%
  kpi_search(
    query = c("nettokostnad", "öppen"),
    column = c("keyword_1", "keyword_2", "keyword_3")
  )
}

Extract a vector of municipality ID strings from a Kolada municipality table

Description

This function is primarily intended as a convenient way to pass a (filtered) Kolada municipality metadata table to get_values.

Usage

municipality_extract_ids(munic_df)

Arguments

Examples

if (kolada_available()) {
# Download Kolada data for all municipalities of type "L"
# (regions and national total) for KPI "N45933"
munic_filter <- get_municipality() %>%
  municipality_search("L", column = "type")

kld_data <- get_values(
  kpi = "N45933",
  municipality = municipality_extract_ids(munic_filter),
  period = 2022
)
}

Describe the municipalitie in a Kolada Municipality Group metadata table

Description

Print a human-readable description of each row of a Municipality Group metadata table, including member municipalities (up to a maximum number of rows). Can be printed either directly to the R console or used to populate a R markdown document, which can be useful for documentation purposes.

Usage

municipality_grp_describe(
  munic_grp_df,
  max_n = 5,
  format = "inline",
  heading_level = 2,
  sub_heading_level = heading_level + 1
)

Arguments

Value

Returns the object passed to the function, invisibly, to be re-used in a pipe.

Extract municipality ID strings from a Kolada municipality group table

Description

This function is primarily intended as a convenient way to pass a (filtered) Kolada municipality group metadata table to get_values. All IDs of the municipalities contained in each group in the table are extracted.

Usage

municipality_grp_extract_ids(munic_grp_df)

Arguments

Value

A vector of Municipality IDs.

Search a Kolada Municipality Group metadata table for group names

Description

Search a Kolada Municipality Group metadata table. Only keep rows that contain the search query. Searches group titles and group IDs. Note that this function does not search for individual municipalities contained within municipality groups! To search for KPIs within a KPI group, see examples below for an example using municipality_grp_unnest.

Usage

municipality_grp_search(munic_grp_df, query)

Arguments

Value

A Kolada Municipality Group metadata table

Create a municipality table from a Kolada Municipality Group metadata table

Description

Municipality groups are a convenient way to discover pre-rendered sets of municipalities. A practical workflow for discovering such sets can be to search through Municipality Group metadata using municipality_grp_search to search for keywords and municipality_grp_describe to inspect contents of KPI groups. Once you have created a Municipality Group metadata table that has been narrowed down to the group/s you are looking for, municipality_grp_unnest is used to create a municipality metadata table for further processing.

Usage

municipality_grp_unnest(munic_grp_df)

Arguments

Value

A Kolada Municipality metadata table

Examples

if (kolada_available()) {
# Download Municipality Group metadata
# (skip the parameter "max_results" to actually download all available data)
munic_grp_df <- get_municipality_groups(max_results = 100)

# Create a Municipality metadata table from municipality groups matching the
# term "Arboga"
munic_grp_df %>%
  municipality_grp_search("arboga") %>%
  municipality_grp_unnest()
}

Convert a vector of municipality ids to municipality names

Description

Given a vector of municipality IDs/codes, return a named vector of names of municipalities or regions. Codes of municipalities and regions follow the Swedish standard for municipality codes. The codes extracted can be used e.g. to pass as a parameter to get_values. This function is the inverse to municipality_name_to_id.

Usage

municipality_id_to_name(munic_df, id, remove_na = FALSE)

Arguments

Value

A vector of Municipality names.

See Also

municipality_extract_ids, municipality_name_to_id

Examples

if (kolada_available()) {
munic_df <- get_municipality()
municipality_id_to_name(munic_df, c("1280", "1281", "0180", "1280"))
}

Convert a vector of municipality names to municipality ids

Description

Given a vector of names of municipalities or regions, return a named vector of municipality IDs/codes. Codes of municipalities and regions follow the Swedish standard for municipality codes. The codes extracted can be used e.g. to pass as a parameter to get_values. This function is the inverse to municipality_id_to_name.

Usage

municipality_name_to_id(munic_df, municipality, remove_na = FALSE)

Arguments

Value

A vector of Municipality IDs.

See Also

municipality_extract_ids, municipality_id_to_name

Examples

if (kolada_available()) {
munic_df <- get_municipality()
munic_df %>%
  municipality_name_to_id(c("Arboga", "Lund", "Stockholm", "Arboga"))
}

Search a Kolada municipality metadata table

Description

Search a Kolada municipality metadata table. Only keep rows that contain the search query. Note that some a quer might be both the name, or part of a name, of a municipality and part of the name of a region. Thus, a search might return rows for both municipalities and regions. To avoid this you can use dplyr::filter to filter the type column to keep only "K" (municipalities) or "L" (regions) rows. See also examples below for an alternative approach avoiding any direct calls to filter.

Usage

municipality_search(munic_df, query, column = NULL)

Arguments

Value

A Kolada Municipality metadata table

Examples

if (kolada_available()) {
# Search for a single search term in a municipality table
munic_df <- get_municipality()
municipality_search(munic_df, "Arboga")

# Only keep columns with type == "K" (keep municipalities, drop regions)
munic_filter <- get_municipality(cache = TRUE) %>%
  municipality_search("K", column = "type")
}

Search a Kolada Organizational Unit metadata table

Description

Search a Kolada Organizational Unit metadata table. Only keep rows that contain the search query. Matches against all columns or columns named with the column parameter. For more precise matching, please use dplyr::filter.

Usage

ou_search(ou_df, query, column = NULL)

Arguments

Value

A Kolada Organizational Unit metadata table

Examples

if (kolada_available()) {
# Search for all OUs matching the search term "skola" (school)
# (skip the parameter "max_results" to actually download all data)
ou_df <- get_ou(max_results = 100)
ou_search(ou_df, "skola")

# Only keep OU entities matching "skola" but not "förskola" (preschool)
# located in Gothenburg municipality and starting with an "A" using
# regex matching
ou_filter <- get_ou(municipality = "1480") %>%
  ou_search("^A", column = "title") %>%
  ou_search("[^(för)]skola")
}

Create KPI long-form descriptions to add to a plot

Description

In a Kolada values table, only KPI ID names are preserved. But in plots you often want to add a legend to explain what each KPI ID represents. But since KPI explanations are mostly relatively wordy, ggplot2 legends are under-dimensioned for this task. values_legend returns a string which can conveniently be used as caption to a plot instead.

Usage

values_legend(values_df, kpi_df)

Arguments

Value

A string which should be used as caption in a plot.

Simplify a Kolada values table

Description

Simplify a Kolada values table, i.e as created by get_values, by removing columns that contain monotonous data, i.e. that contain only one value for all observations.

Usage

values_minimize(values_df)

Arguments

Value

A Kolada values table

Examples

# Download values for all available years of a given KPI for
# Malmö municipality (code 1280)
if (kolada_available()) {
vals <- get_values(kpi = "N45933", municipality = "1280", simplify = TRUE)
# (Returns a table with 5 rows and 8 columns)

# Remove columns with no information to differentiate between rows
values_minimize(vals)
# (Returns a table with 5 rows and 4 columns)
}