# Helsinki open data R tools

#### 2017-02-18

# helsinki - tutorial

This R package provides tools to access open data from the Helsinki region in Finland as part of the rOpenGov project.

For contact information and source code, see the github page.

## Available data sources

Helsinki region district maps (Helsingin seudun aluejakokartat)

- Aluejakokartat: kunta, pien-, suur-, tilastoalueet (Helsinki region district maps)
- Äänestysaluejako: (Helsinki region election district maps)
- Source: Helsingin kaupungin Kiinteistövirasto (HKK)

Helsinki Real Estate Department (HKK:n avointa dataa)

- Spatial data from Helsingin kaupungin Kiinteistövirasto (HKK) availabe in the gisfin package, see gisfin tutorial for examples

Helsinki region environmental services (HSY:n avointa dataa)

- Väestötietoruudukko (population grid)
- Rakennustietoruudukko (building information grid)
- SeutuRAMAVA (building land resource information(?))
- Source: Helsingin seudun ympäristöpalvelut, HSY

Service and event information

- Helsinki region Service Map API (Pääkaupunkiseudun Palvelukartta)
- Helsinki Linked Event API

Helsinki Region Infoshare statistics API

- Aluesarjat (original source) (regional time series data)
- Source: Helsinki Region Infoshare statistics API

List of potential data sources to be added to the package can be found here.

## Installation

Release version for general users:

    install.packages("helsinki")

Development version for developers:

    install.packages("devtools")
    library(devtools)
    install_github("helsinki", "ropengov")

Load package.

    library(helsinki)

## Helsinki region district maps

Helsinki region district maps (Helsingin seudun aluejakokartat) and election maps (äänestysalueet) from Helsingin kaupungin Kiinteistövirasto (HKK) are available in the helsinki package with `data(aluejakokartat)`. The data are available as both spatial object (`sp`) and data frame (`df`). These are preprocessed in the gisfin package, and more examples can be found in the gisfin tutorial.

    # Load aluejakokartat and study contents
    data(aluejakokartat)
    str(aluejakokartat, m=2)

    ## List of 2
    ##  $ sp:List of 8
    ##   ..$ kunta            :Formal class 'SpatialPolygonsDataFrame' [package "sp"] with 5 slots
    ##   ..$ pienalue         :Formal class 'SpatialPolygonsDataFrame' [package "sp"] with 5 slots
    ##   ..$ pienalue_piste   :Formal class 'SpatialPointsDataFrame' [package "sp"] with 5 slots
    ##   ..$ suuralue         :Formal class 'SpatialPolygonsDataFrame' [package "sp"] with 5 slots
    ##   ..$ suuralue_piste   :Formal class 'SpatialPointsDataFrame' [package "sp"] with 5 slots
    ##   ..$ tilastoalue      :Formal class 'SpatialPolygonsDataFrame' [package "sp"] with 5 slots
    ##   ..$ tilastoalue_piste:Formal class 'SpatialPointsDataFrame' [package "sp"] with 5 slots
    ##   ..$ aanestysalue     :Formal class 'SpatialPolygonsDataFrame' [package "sp"] with 5 slots
    ##  $ df:List of 8
    ##   ..$ kunta            :'data.frame':    1664 obs. of  7 variables:
    ##   ..$ pienalue         :'data.frame':    33594 obs. of  7 variables:
    ##   ..$ pienalue_piste   :'data.frame':    295 obs. of  3 variables:
    ##   ..$ suuralue         :'data.frame':    6873 obs. of  7 variables:
    ##   ..$ suuralue_piste   :'data.frame':    23 obs. of  3 variables:
    ##   ..$ tilastoalue      :'data.frame':    17279 obs. of  7 variables:
    ##   ..$ tilastoalue_piste:'data.frame':    125 obs. of  3 variables:
    ##   ..$ aanestysalue     :'data.frame':    35349 obs. of  11 variables:

## Helsinki region environmental services

Retrieve data from Helsingin seudun ympäristöpalvelut (HSY) with `get_hsy()`.

### Population grid

Population grid (väestötietoruudukko) with 250m x 250m grid size in year 2013 contains the number of people in different age groups. The most rarely populated grids are left out (0-4 persons), and grids with less than 99 persons are censored with ‘99’ to guarantee privacy.

    sp.vaesto <- get_hsy(which.data="Vaestotietoruudukko", which.year=2013)
    head(sp.vaesto@data)

### Helsinki building information

Building information grid (rakennustietoruudukko) in Helsinki region on grid-level (500m x 500m): building counts (lukumäärä), built area (kerrosala), usage (käyttötarkoitus), and region efficiency (aluetehokkuus).

    sp.rakennus <- get_hsy(which.data="Rakennustietoruudukko", which.year=2013)
    head(sp.rakennus@data)

### Helsinki building area capacity

Building area capacity per municipal region (kaupunginosittain summattua tietoa rakennusmaavarannosta). Plot with number of buildlings with `spplot()`.

    sp.ramava <- get_hsy(which.data="SeutuRAMAVA_tila", which.year=2013)
    head(sp.ramava@data)
    # Values with less than five units are given as 999999999, set those to zero
    sp.ramava@data[sp.ramava@data==999999999] <- 0
    # Plot number of buildings for each region
    spplot(sp.ramava, zcol="RAKLKM", main="Number of buildings in each 'tilastoalue'", col.regions=colorRampPalette(c('blue', 'gray80', 'red'))(100))

## Service and event information

Function `get_servicemap()` retrieves regional service data from the new Service Map API, that contains data from the Service Map.

    # Search for "puisto" (park) (specify q="query")
    search.puisto <- get_servicemap(query="search", q="puisto")
    # Study results
    str(search.puisto, m=1)

    ## List of 4
    ##  $ count   : num 1891
    ##  $ next    : chr "http://api.hel.fi/servicemap/v1/search/?page=2&q=puisto"
    ##  $ previous: NULL
    ##  $ results :List of 20

    # A lot of results found (count > 1000)
    # Get names for the first 20 results
    sapply(search.puisto$results, function(x) x$name$fi)

    ##  [1] "Mankkaan asukaspuisto"
    ##  [2] "Tapiolan asukaspuisto"
    ##  [3] "Hurtigin puisto"
    ##  [4] "Olarin asukaspuisto"
    ##  [5] "Perkkaan asukaspuisto"
    ##  [6] "Kaupungintalon puisto"
    ##  [7] "Matinkylän asukaspuisto"
    ##  [8] "Kylätalo Palttinan asukaspuisto"
    ##  [9] "Asematien puisto"
    ## [10] "Karakallion asukaspuisto"
    ## [11] "Suvelan asukaspuisto"
    ## [12] "Leppävaaran asukaspuisto"
    ## [13] "Viherkallion asukaspuisto"
    ## [14] "Stenbergin puisto"
    ## [15] "Kasavuoren puisto"
    ## [16] "Nurmilinnunpuisto"
    ## [17] "Itärannan puisto/ Otsonlahdenpuisto"
    ## [18] "Kotitontunpuisto"
    ## [19] "Marketanpuisto"
    ## [20] "Niittykummunpuisto"

    # See what data is given for one service
    names(search.puisto$results[[1]])

    ##  [1] "id"                        "connections"
    ##  [3] "accessibility_properties"  "identifiers"
    ##  [5] "data_source_url"           "name"
    ##  [7] "description"               "provider_type"
    ##  [9] "street_address"            "address_zip"
    ## [11] "phone"                     "email"
    ## [13] "www_url"                   "address_postal_full"
    ## [15] "extensions"                "picture_url"
    ## [17] "picture_caption"           "origin_last_modified_time"
    ## [19] "root_services"             "department"
    ## [21] "organization"              "municipality"
    ## [23] "services"                  "divisions"
    ## [25] "keywords"                  "location"
    ## [27] "object_type"               "score"

    # More results could be retrieved by specifying 'page=2' etc.

Function `get_linkedevents()` retrieves regional event data from the new Linked Events API.

    # Searh for current events
    events <- get_linkedevents(query="event")
    # Get names for the first 20 results
    sapply(events$data, function(x) x$name$fi)

    ##  [1] "Ennakkoluulijat"                  "Pieni alkusoitto"
    ##  [3] "Pieni alkusoitto"                 "Pieni alkusoitto"
    ##  [5] "Muusikkotapaaminen"               "Pieni alkusoitto"
    ##  [7] "Muusikkotapaaminen"               "Ennakkoluulijat"
    ##  [9] "Pieni alkusoitto"                 "Pieni alkusoitto"
    ## [11] "Muusikkotapaaminen"               "Ennakkoluulijat"
    ## [13] "Pieni alkusoitto"                 "Pieni alkusoitto"
    ## [15] "Ennakkoluulijat"                  "Yhdessä!-kamarimusiikkikonsertti"
    ## [17] "Kamarimusiikkia kaupungintalolla" "Kamarimusiikkia kaupungintalolla"
    ## [19] "Kenraaliharjoitus"                "Kenraaliharjoitus"

    # See what data is given for the first event
    names(events$data[[1]])

    ##  [1] "id"                  "location"            "keywords"
    ##  [4] "super_event"         "event_status"        "external_links"
    ##  [7] "offers"              "data_source"         "publisher"
    ## [10] "sub_events"          "in_language"         "audience"
    ## [13] "custom_data"         "origin_id"           "created_time"
    ## [16] "last_modified_time"  "date_published"      "start_time"
    ## [19] "end_time"            "super_event_type"    "provider"
    ## [22] "location_extra_info" "description"         "info_url"
    ## [25] "headline"            "short_description"   "name"
    ## [28] "secondary_headline"  "@id"                 "@context"
    ## [31] "@type"               "image"

## Helsinki Region Infoshare statistics API

Function `get_hri_stats()` retrieves data from the Helsinki Region Infoshare statistics API.

    # Retrieve list of available data
    stats.list <- get_hri_stats(query="")
    # Show first results
    head(stats.list)

    ##                                      NULL
    ##             "L113_viheralue_kaupunginosa"
    ##                                      NULL
    ##                      "L32_yksikkopaastot"
    ##                                      NULL
    ##                   "J1_loppusijoitettavat"
    ##                                      NULL
    ##                    "I13_maailman_paastot"
    ##                                      NULL
    ##       "J13_sekajatteen_maara_kiinteistot"
    ##  Helsingin väestö äidinkielen mukaan 1.1.
    ## "aluesarjat_a03s_hki_vakiluku_aidinkieli"

Specify a dataset to retrieve. The output is currently a three-dimensional array.

    # Retrieve a specific dataset
    stats.res <- get_hri_stats(query=stats.list[1])
    # Show the structure of the results
    str(stats.res)

    ##  num [1:6, 1:34] 11606 5607 2.07 0.65 0.15 ...
    ##  - attr(*, "dimnames")=List of 2
    ##   ..$ muuttuja  : chr [1:6] "Asukkaita" "Asukastiheys (hlö/km2)" "Maapinta-ala (km2)" "Viheralueiden pinta-ala (km2)" ...
    ##   ..$ peruspiiri: chr [1:34] "Vironniemi" "Ullanlinna" "Kampinmalmi" "Taka-Töölö" ...

The implementation will be updated and more examples will be added in the near future.

### Citation

**Citing the data:** See `help()` to get citation information for each data source individually.

Citing the R package:

    citation("helsinki")

    Kindly cite the helsinki R package as follows:

      (C) Juuso Parkkinen, Leo Lahti and Joona Lehtomaki 2014.
      helsinki R package

    A BibTeX entry for LaTeX users is

      @Misc{,
        title = {helsinki R package},
        author = {Juuso Parkkinen and Leo Lahti and Joona Lehtomaki},
        year = {2014},
      }

    Many thanks for all contributors! For more info, see:
    https://github.com/rOpenGov/helsinki

### Session info

This vignette was created with

    sessionInfo()

    ## R version 3.3.2 (2016-10-31)
    ## Platform: x86_64-apple-darwin13.4.0 (64-bit)
    ## Running under: macOS Sierra 10.12.3
    ##
    ## locale:
    ## [1] C/en_US.UTF-8/en_US.UTF-8/C/en_US.UTF-8/en_US.UTF-8
    ##
    ## attached base packages:
    ## [1] stats     graphics  grDevices utils     datasets  methods   base
    ##
    ## other attached packages:
    ## [1] helsinki_0.9.29 RCurl_1.95-4.8  bitops_1.0-6    maptools_0.8-39
    ## [5] sp_1.2-3
    ##
    ## loaded via a namespace (and not attached):
    ##  [1] Rcpp_0.12.9     lattice_0.20-34 digest_0.6.12   grid_3.3.2
    ##  [5] magrittr_1.5    evaluate_0.10   stringi_1.1.2   rmarkdown_0.9.6
    ##  [9] rjson_0.2.15    tools_3.3.2     stringr_1.1.0   foreign_0.8-67
    ## [13] yaml_2.1.14     htmltools_0.3.5 knitr_1.15.1