Package 'sotkanet'

Title: Sotkanet Open Data Access and Analysis
Description: Access statistical information on welfare and health in Finland from the Sotkanet open data portal <https://sotkanet.fi/sotkanet/fi/index>.
Authors: Leo Lahti [aut, cre] , Einari Happonen [aut], Joona Lehtomaki [ctb], Juuso Parkkinen [ctb], Vesa Saaristo [ctb], Pyry Kantanen [aut] , Aleksi Lahtinen [aut]
Maintainer: Leo Lahti <[email protected]>
License: BSD_2_clause + file LICENSE
Version: 0.10.1
Built: 2024-09-21 05:09:01 UTC
Source: https://github.com/rOpenGov/sotkanet

Help Index

sotkanet: Sotkanet Open Data Access and Analysis

Description

The 'sotkanet' R package aims to make retrieval of sotkanet indicator data easy using R. Sotkanet.fi Statistics and Indicator Bank is maintained by The Finnish Institute for Health and Welfare and it contains data on population welfare and health from 1990 onwards.

sotkanet functions

The main ways to interact with Sotkanet REST API are with the following functions: GetDataSotkanet for downloading data from specific indicator(s), SotkanetIndicators for retrieving metadata on all or user specified indicators as a well defined list and SotkanetIndicatorMetadata as a specialized case returning an untruncated ("raw") output as default.

Attribution and licensing

For citing this package, see citation("sotkanet")

For terms of use of Sotkanet data, see THL Sotkanet REST API documentation (in Finnish).

A short and unofficial English summary of the Finnish Terms of use is as follows: The end user of this package should note that

  • metadata related to regional classifications and indicators is released under a Creative Commons Attribution 4.0 license (CC BY 4.0),

  • statistical data and indicators produced by THL are likewise released under a CC BY 4.0 license,

  • statistical data and indicators produced by other parties than THL should be only used in accordance with a separate agreement.

CC BY 4.0 terms state that when using data accessed through the sotkanet API you should always give appropriate credit to Sotkanet as a data source and include a link to sotkanet website: https://sotkanet.fi. In the case of individual indicators, the producer of the indicator should also be attributed separately.

This information is subject to change and the developers of this package cannot guarantee that information stated here is correct. This unofficial English translation related to data terms of use is provided solely as a convenience to the end user. The user of this package should always check the full text of Sotkanet terms of use from the original source (see the link above to Sotkanet REST API documentation).

Basic information about the package

Package: sotkanet
Type: Package
Version: See sessionInfo() or DESCRIPTION file
Date: 2013-2024
License: BSD 2-clause License
LazyLoad: yes

Author(s)

Leo Lahti ([email protected]), Einari Happonen, Juuso Parkkinen Joona Lehtomaki, Vesa Saaristo, Pyry Kantanen and Aleksi Lahtinen

References

See citation("sotkanet")

See Also

Useful links:

Examples

library(sotkanet)

Retrieve Sotkanet Data

Description

Retrieve selected data and combine into a single table.

Usage

get_sotkanet(
  indicators = NULL,
  years = NULL,
  genders = c("male", "female", "total"),
  regions = NULL,
  region.category = NULL,
  lang = "fi",
  user.agent = NULL,
  cache = TRUE,
  cache_dir = NULL,
  frictionless = FALSE
)

Arguments

indicators

Dataset identifier(s)
years

vector of years, for example '2015:2018' or 'c(2010, 2012, ...)'. Default value is 'NULL', which gives the data from all the available years. You can give indicators their own year range by giving the years in a list. See examples for demonstration.
genders

vector of genders ('male' | 'female' | 'total'). Some datasets do not work with only the gender value 'total' and return an empty data.frame. In these situations it is advised to check out some other alternative.
regions

filter by selected regions only (default: all regions). The region filter has to be given in the language used for the language variable.
region.category

filter by one or more of the following 15 valid regions categories (default: all categories)

  • "ALUEHALLINTOVIRASTO"

  • "ELY-KESKUS"

  • "ERVA"

  • "EURALUEET" (Eurozone)

  • "EUROOPPA" (Europe)

  • "HYVINVOINTIALUE" (welfare country)

  • "KUNTA" (municipality)

  • "MAA" (country)

  • "MAAKUNTA" (region)

  • "NUTS1"

  • "POHJOISMAAT" (Nordic countries)

  • "SAIRAANHOITOPIIRI (hospital district)

  • "SEUTUKUNTA"

  • "SUURALUE"

  • "YTA"

lang

Language of the data variables: indicator.title, region.title and indicator.organization.title. Default is Finnish ("fi"), the other options being English ("en") and Swedish ("sv").
user.agent

"User agent" defined by the user. Default is NULL which will then use the package identifier "rOpenGov/sotkanet"
cache

a logical whether to do caching. Defaults is 'TRUE'.
cache_dir

a path to cache directory. 'Null' (default) uses and creates "sotkanet" directory in the temporary directory defined by base R [tempdir()] function. The user can set the cache directory to an existing directory with this argument.
frictionless

a logical whether to return a datapackage, with metadata inside, instead of a data.frame.

Details

THL's open data license and limitation of liability

License

The open data provided by National Institute for Health and Welfare is licensed under CC BY 4.0. This license defines how open data can be utilized. The licensing is based on a decision made by the Director General.

Limitation of Liability

National Institute for Health and Welfare shall not be liable for any loss, legal proceedings, claims, proceedings, demands, costs or damages regardless of their cause or form, which can be directly or indirectly connected to open data or use of open data published by National Institute for Health and Welfare.

Value

Returns a data.frame when frictionless is 'FALSE' and a datapackage when frictionless is 'TRUE'.

Author(s)

Maintainer: Leo Lahti [email protected], Pyry Kantanen

References

See citation("sotkanet")

See Also

For more information about dataset structure, see THL webpage at https://yhteistyotilat.fi/wiki08/pages/viewpage.action?pageId=27557907

THL open data license website: https://yhteistyotilat.fi/wiki08/x/AAadAg

Examples

## Not run: 
dat <- get_sotkanet(indicators = 165)
dat <- get_sotkanet(indicators = c(4,5), genders = c("male", "female"))
dat <- get_sotkanet(indicators = 10012, regions = c("Suomi", "Ruotsi"))
dat <- get_sotkanet(indicators = 10012, region.category = c("POHJOISMAAT"))
dat <- get_sotkanet(indicators = 6, lang = "en")
dat <- get_sotkanet(indicators = 10027, frictionless = TRUE)
dat <- get_sotkanet(indicators = c(4,5,6), years = list("4" = 2000:2010,
                                                        "5" = 2010:2015, "6" = 2015:2020))

## End(Not run)

Retrieve Sotkanet Data (old version)

Description

Retrieve selected data and combine into a single table. (This is an older version of the function. It is advised to use the new [get_sotkanet()] function instead.)

Usage

GetDataSotkanet(
  indicators = NULL,
  years = 1991:2015,
  genders = c("total"),
  regions = NULL,
  region.category = NULL,
  user.agent = NULL
)

Arguments

indicators

Dataset identifier(s)
years

vector of years c(2010, 2012, ... )
genders

vector of genders ('male' | 'female' | 'total')
regions

filter by selected regions only (default: all regions)
region.category

filter by one or more of the following 15 valid regions categories (default: all categories)

  • "ALUEHALLINTOVIRASTO"

  • "ELY-KESKUS"

  • "ERVA"

  • "EURALUEET" (Eurozone)

  • "EUROOPPA" (Europe)

  • "HYVINVOINTIALUE" (welfare country)

  • "KUNTA" (municipality)

  • "MAA" (country)

  • "MAAKUNTA" (region)

  • "NUTS1"

  • "POHJOISMAAT" (Nordic countries)

  • "SAIRAANHOITOPIIRI (hospital district)

  • "SEUTUKUNTA"

  • "SUURALUE"

  • "YTA"

user.agent

"User agent" defined by the user. Default is NULL which will then use the package identifier "rOpenGov/sotkanet"

Details

THL's open data license and limitation of liability

License

The open data provided by National Institute for Health and Welfare is licensed under CC BY 4.0. This license defines how open data can be utilized. The licensing is based on a decision made by the Director General.

Limitation of Liability

National Institute for Health and Welfare shall not be liable for any loss, legal proceedings, claims, proceedings, demands, costs or damages regardless of their cause or form, which can be directly or indirectly connected to open data or use of open data published by National Institute for Health and Welfare.

Value

data.frame

Author(s)

Maintainer: Leo Lahti [email protected], Pyry Kantanen

References

See citation("sotkanet")

See Also

For more information about dataset structure, see THL webpage at https://yhteistyotilat.fi/wiki08/pages/viewpage.action?pageId=27557907

THL open data license website: https://yhteistyotilat.fi/wiki08/x/AAadAg

Examples

## Not run: dat <- GetDataSotkanet(indicators = 165)

Crate a Data Bibliography

Description

Crates a bibliography from selected Sotkanet data file.

Usage

sotkanet_cite(id, lang = "fi", format = "Biblatex")

Arguments

id

Indicator id.
lang

Language for the citation. Options are English (en), Finnish (fi) and Swedish (sv).
format

Default is "Biblatex", alternatives are "bibentry" or "Bibtex".

Value

a Biblatex, bibentry or Bibtex object.

References

See citation("sotkanet")

See Also

[utils::bibentry()] [RefManageR::toBiblatex()]

Examples

## Not run: 
SotkanetCite(10013, lang = "en", format = "Biblatex")
SotkanetCite(10012, lang = "fi", format = "Biblatex")
SotkanetCIte(10011, lang = "sv", format = "Biblatex")
SotkanetCite(10013, lang = "en", format = "bibentry")
SotkanetCite(10013, lang = "en", format = "Bibtex")

## End(Not run)

Clean sotkanet Cache

Description

Delete all .rds files from the sotkanet cache directory.

Usage

sotkanet_clean_cache(cache_dir = NULL)

Arguments

cache_dir

A path to the cache directory. If 'NULL' (default) tries to clean default temporary cache directory.

Examples

## Not run: 
SotkanetCleanCache()

## End(Not run)

Sotkanet Indicator Metadata

Description

Retrieves sotkanet indicator metadata.

Usage

sotkanet_indicator_metadata(
  id = NULL,
  type = "raw",
  user.agent = NULL,
  cache = TRUE,
  cache_dir = NULL
)

Arguments

id

Indicator id
type

Parameter passed onto sotkanet_indicators. Default is 'raw' for the whole output but 'table' is also supported
user.agent

"User agent" defined by the user. Default is NULL which will use the default package identifier "rOpenGov/sotkanet"
cache

A logical whether to do caching.
cache_dir

A path to the cache dir.

Details

Data is fetched from 

https://sotkanet.fi/rest/1.1/indicators/<id>

Value

sotkanet indicator metadata as a list object

Author(s)

Maintainer: Pyry Kantanen

References

See citation("sotkanet")

Examples

## Not run: 
x <- sotkanet_indicator_metadata(10012)

## End(Not run)

Sotkanet Indicators

Description

Retrieve Sotkanet indicator metadata

Usage

sotkanet_indicators(
  id = NULL,
  type = "table",
  lang = "fi",
  user.agent = NULL,
  cache = TRUE,
  cache_dir = NULL
)

Arguments

id

Dataset identifier. Default is NULL returning all
type

type output format, either 'table' (default) or 'raw'. Default produces a truncated table with strictly defined columns that are useful in other functions. 'Raw' produces the full output which might be useful for exploratory purposes.
lang

Language of the output.
user.agent

"User agent" defined by the user. Default is NULL which will then use the package identifier "rOpenGov/sotkanet"
cache

a logical whether to do caching.
cache_dir

a path to the cache dir.

Details

Data is fetched from https://sotkanet.fi/rest/1.1/indicators.

Value

data.frame (type = "table) or a list (type = "raw")

Author(s)

Leo Lahti [email protected], Pyry Kantanen

References

See citation("sotkanet")

Examples

## Not run: 
sotkanet.indicators <- sotkanet_indicators(type = "table", lang = "fi")

## End(Not run)

Interactive function for get_sotkanet

Description

A simple interactive function, that helps with downloading Sotkanet data

Usage

sotkanet_interactive(code = NULL)

Arguments

code

A unique identifier for the dataset of interest.

See Also

[get_sotkanet()]

Sotkanet Regions

Description

Retrieves sotkanet regions data.

Usage

sotkanet_regions(
  type = "table",
  lang = "fi",
  user.agent = NULL,
  cache = TRUE,
  cache_dir = NULL
)

Arguments

type

type output format, either 'table' (default) or 'raw'. Default produces a truncated table with strictly defined columns that are useful in other functions. 'Raw' produces the full output which might be useful for exploratory purposes.
lang

Language of the output.
user.agent

"User agent" defined by the user. Default is NULL which will then use the package identifier "rOpenGov/sotkanet"
cache

a logical whether to do caching.
cache_dir

a path to the cache directory.

Details

Data is fetched from https://sotkanet.fi/rest/1.1/regions.

Value

data.frame

Author(s)

Maintainer: Leo Lahti [email protected]

References

See citation("sotkanet")

Examples

## Not run: 
sotkanet.regions <- sotkanet_regions(type = "table", lang = "fi")

## End(Not run)

Sotkanet Indicator Metadata. (old version)

Description

Retrieves sotkanet indicator metadata. (This is an older version of the function. It is advised to use the new [sotkanet_indicator_metadata()] function instead.)

Usage

SotkanetIndicatorMetadata(id = NULL, type = "raw", user.agent = NULL)

Arguments

id

Indicator id
type

Parameter passed onto SotkanetIndicators. Default is 'raw' for the whole output but 'table' is also supported
user.agent

"User agent" defined by the user. Default is NULL which will use the default package identifier "rOpenGov/sotkanet"

Details

Data is fetched from 

https://sotkanet.fi/rest/1.1/indicators/<id>

Value

sotkanet indicator metadata as a list object

Author(s)

Maintainer: Pyry Kantanen

References

See citation("sotkanet")

Examples

## Not run: 
x <- SotkanetIndicatorMetadata(10013)

## End(Not run)

Sotkanet Indicators (old version)

Description

Retrieve Sotkanet indicator metadata. (This is an older version of the function. It is advised to use the new [sotkanet_indicators()] function instead.)

Usage

SotkanetIndicators(id = NULL, type = "table", user.agent = NULL)

Arguments

id

Dataset identifier. Default is NULL returning all
type

type output format, either 'table' (default) or 'raw'. Default produces a truncated table with strictly defined columns that are useful in other functions. 'Raw' produces the full output which might be useful for exploratory purposes.
user.agent

"User agent" defined by the user. Default is NULL which will then use the package identifier "rOpenGov/sotkanet"

Details

Data is fetched from https://sotkanet.fi/rest/1.1/indicators.

Value

data.frame (type = "table) or a list (type = "raw")

Author(s)

Leo Lahti [email protected], Pyry Kantanen

References

See citation("sotkanet")

Examples

## Not run: 
sotkanet.indicators <- SotkanetIndicators(type = "table")

## End(Not run)

Sotkanet Regions (old version)

Description

Retrieves sotkanet regions data. (This is an older version of the function. It is advised to use the new [sotkanet_regions()] function instead.)

Usage

SotkanetRegions(type = "table", user.agent = NULL)

Arguments

type

type output format, either 'table' (default) or 'raw'. Default produces a truncated table with strictly defined columns that are useful in other functions. 'Raw' produces the full output which might be useful for exploratory purposes.
user.agent

"User agent" defined by the user. Default is NULL which will then use the package identifier "rOpenGov/sotkanet"

Details

Data is fetched from https://sotkanet.fi/rest/1.1/regions.

Value

data.frame

Author(s)

Maintainer: Leo Lahti [email protected]

References

See citation("sotkanet")

Examples

## Not run: 
sotkanet.regions <- SotkanetRegions(type = "table")

## End(Not run)