---
title: "sorvi Tutorial"
author: rOpenGov core team
date: "`r Sys.Date()`"
output: 
  rmarkdown::html_vignette:
    toc: true
vignette: >
  %\VignetteIndexEntry{sorvi Tutorial}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

Finnish open (government) data toolkit for R
===========

## Introduction

sorvi package was originally intended for hosting various algorithms for Finnish open goverment data in [R](https://www.r-project.org). After being superseded by later rOpenGov packages that are more specialized in scope (such as [geofi](https://github.com/rOpenGov/geofi), [hetu](https://github.com/rOpenGov/hetu) and [pxweb](https://github.com/rOpenGov/pxweb)), sorvi has now found a new life in hosting various functions that are helpful in rOpenGov package maintenance, authoring and preparing presentations.

## Installation

Install the stable release version from CRAN in R:

```{r install, eval=FALSE}
install.packages("sorvi")
```

Alternatively, use `remotes` package to install the latest development version from GitHub:

```{r install2, eval=FALSE}
library(remotes)
remotes::install_github("ropengov/sorvi")
```

Loading the package in R command line:

```{r test, message=FALSE, warning=FALSE, eval=TRUE}
library(sorvi)
```

## Using the package

The number of functions in this package has been reduced compared to older versions. 

Get download statistics of eurostat-package, by year:

```{r example_download_stats, eval=FALSE}
df <- cran_downloads(pkgs = "eurostat", sum = "by_year", use.cache = FALSE)
df
```

Get download statistics of various rOpenGov packages over time and draw a chart:

```{r example_visualize, eval=FALSE}
packages <- c("eurostat", "giscoR", "sotkanet", "geofi", "sweidnumbr")
plot <- cran_downloads(pkgs = packages, sum = "total", output = "plot", use.cache = FALSE)
plot
```

## Historical mapping and data sets

The sorvi package includes 2 datasets: `sorvi::kunnat1865_2021` for listing municipalities that existed between years 1865-2021, and `sorvi::polygons1909_2009` that contains polygons for most of the municipalities contained by the former dataset. Despite the slightly misleading name, the polygons dataset contains shapes for most municipalities from the 1800s as well, as municipalities and their borders remained relatively unchanged before the 2nd World War and late 1900s-early 2000s municipality mergers. 

While users most definitely can use the datasets directly in their work (and improvements / additions / forks are most welcome!), we have included `get_municipalities()` function for conveniently returning a map of Finland as it existed at a certain point in time.

A simple example of using the `get_municipalities()` function for drawing a map containing Finnish municipalities in 1931:

```{r example_map}
library(ggplot2)
map1931 <- get_municipalities(year = 1931)
ggplot(map1931) + geom_sf()
```

See sorvi article [Finnish historical maps with sorvi R package](https://ropengov.github.io/sorvi/articles/finnish-historical-maps.html) for more information and examples.

## Licensing and Citations

This work can be freely used, modified and distributed under the 
[Two-clause BSD license](https://en.wikipedia.org/wiki/BSD\_licenses).

```{r citation, message=FALSE, eval=TRUE}
citation("sorvi")
```

For data attribution, see dataset documentation.

## Session info

This vignette was created with

```{r sessioninfo, message=FALSE, warning=FALSE}
sessionInfo()
```

To call in the statistician after the experiment is done may be no more than asking him to perform a post-mortem examination: he may be able to say what the experiment died of. ~ Sir Ronald Aylmer Fisher