Type: Package
Title: Sotkanet Open Data Access and Analysis
Version: 0.10.1
Date: 2024-07-10
Encoding: UTF-8
Description: Access statistical information on welfare and health in Finland from the Sotkanet open data portal https://sotkanet.fi/sotkanet/fi/index.
License: BSD_2_clause + file LICENSE
URL: https://ropengov.github.io/sotkanet/
BugReports: https://github.com/ropengov/sotkanet/issues
Depends: R (≥ 3.2)
Imports: curl, lubridate, RefManageR, digest, frictionless, httr2, magrittr
Suggests: remotes, ggplot2, knitr, testthat (≥ 3.0.0), roxygen2, markdown, kableExtra, rmarkdown, covr, ggrepel
VignetteBuilder: knitr
Config/Needs/website: geofi, dplyr
NeedsCompilation: no
Repository: CRAN
RoxygenNote: 7.3.2
X-schema.org-isPartOf: http://ropengov.org/
X-schema.org-keywords: ropengov
Config/testthat/edition: 3
Packaged: 2024-07-10 08:04:21 UTC; leo
Author: Leo Lahti ORCID iD [aut, cre], Einari Happonen [aut], Joona Lehtomaki [ctb], Juuso Parkkinen [ctb], Vesa Saaristo [ctb], Pyry Kantanen ORCID iD [aut], Aleksi Lahtinen ORCID iD [aut]
Maintainer: Leo Lahti <leo.lahti@iki.fi>
Date/Publication: 2024-07-10 08:20:01 UTC

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

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 (leo.lahti@iki.fi), Einari Happonen, Juuso Parkkinen Joona Lehtomaki, Vesa Saaristo, Pyry Kantanen and Aleksi Lahtinen

References

See citation("sotkanet")

See Also

Useful links:

Examples

library(sotkanet)

Pipe operator

Description

See magrittr::%>% for details.

Usage

lhs %>% rhs

Arguments

lhs

A value or the magrittr placeholder.

rhs

A function call using the magrittr semantics.

Value

The result of calling 'rhs(lhs)'.

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 leo.lahti@iki.fi, 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)

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 leo.lahti@iki.fi, 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 leo.lahti@iki.fi

References

See citation("sotkanet")

Examples

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

## End(Not run)

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 leo.lahti@iki.fi, 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 (csv)

Description

Retrieve data in csv format from given url.

Usage

sotkanet.csv_query(url, user.agent = NULL, ...)

Arguments

url

Sotkanet CSV url

user.agent

User agent defined by the user. Default is "rOpenGov/sotkanet"

...

additional parameters to be passed to test_connection, mainly timeout (in seconds, default is 10)

Value

data.frame

Author(s)

Maintainer: Leo Lahti leo.lahti@iki.fi, Pyry Kantanen

References

See citation("sotkanet")

Retrieve Sotkanet Data (json)

Description

Retrieve data in json format from given url.

Usage

sotkanet.json_query(url, user.agent = NULL, simplifyVector = TRUE, ...)

Arguments

url

Sotkanet JSON url

user.agent

"User agent" defined by the user. Default is "rOpenGov/sotkanet"

simplifyVector

When ´TRUE´ returns a data.frame object and when ´False´ returns a list instead.

...

additional parameters to be passed to test_connection, mainly timeout (in seconds, default is 10)

Value

a data.frame (simplifyVector = TRUE) or a list (simplifyVector = FALSE)

Author(s)

Maintainer: Leo Lahti leo.lahti@iki.fi, Pyry Kantanen

References

See citation("sotkanet")

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)

Calculate fixity checksum for an object

Description

Uses a hash function (md5) on a sotkanet dataset and calculates a digest of the dataset as a character string.

Usage

sotkanet_fixity(data, algorithm = "md5")

Arguments

data

A sotkanet dataset.

algorithm

Algorithm used for calculating the checksum. Default is 'md5', but supports all the algorithms in digest function.

Details

Fixity can be used to make sure that the file has not changed. This is done by calculating a checksum for the dataset that will change if the dataset changes. The default algorithm used to calculate the checksum is md5 hash, but all the algorithms supported by imported digest function are applicable. See the digest function documentation for more details.

This function takes the whole dataset as an input. This means that everything to do with the data is used when calculating the fixity checksum, so for example, if you change the language of the output the checksum will also change.

Value

A character string

See Also

[digest::digest()]

For more info on fixity checksum see: https://www.dpconline.org/handbook/technical-solutions-and-tools/fixity-and-checksums

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 leo.lahti@iki.fi, 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()]

Read cache for sotkanet data.frame

Description

Helper function that reads the cache for saved sotkanet data.frame.

Usage

sotkanet_read_cache(cache, cache_dir, query_hash)

Arguments

cache

a logical whether to do caching.

cache_dir

a path to cache directory.

query_hash

a character used to identify the data.frame.

References

See citation("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 leo.lahti@iki.fi

References

See citation("sotkanet")

Examples

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

## End(Not run)

Write sotkanet data.frame into cache

Description

Helper function that writes the sotkanet data.frame into cache.

Usage

sotkanet_write_cache(cache, cache_dir, query_hash, data)

Arguments

cache

a logical whether to do caching.

cache_dir

a path to cache directory.

query_hash

a character used to identify the data.frame.

data

sotkanet data.frame.

References

See citation("sotkanet")

Test for internet connection, timeout and status

Description

Constructs a function for trying an URL

Usage

test_connection(url = NULL, timeout = 10)

Arguments

url

URL to query

timeout

Timeout time in seconds.

Value

HTTP response or a conditionMessage

Author(s)

Pyry Kantanen (maintainer), Kostas Vasilopoulos

Source

Gracefully failing HTTP request code (slightly adapted by Pyry Kantanen) from RStudio community member kvasilopoulos. Many thanks!

Source of the original RStudio community discussion: https://forum.posit.co/t/internet-resources-should-fail-gracefully/49199

Writes the sotkanet data.frame in datapackage form

Description

A function that turns the data.frame into a datapackage with the metadata added in.

Usage

write_frictionless_metadata(indicators, data)

Arguments

indicators

Dataset identifier

data

The sotkanet data.frame object

Value

datapackage

References

See citation("sotkanet")