Basic features

Tidy Data Principles in `robonomistClient`

The robonomistClient package follows tidy data principles to ensure that the returned datasets are easy to work with and ready for analysis. This approach helps minimize data preparation time, enabling analysts to focus on insights rather than wrangling data. Below are some of the key principles used:

Long Format: Data is returned in long format whenever possible. This means each row represents a single observation, making it ideal for use with popular analysis and visualization tools in R, such as ggplot2 and the rest of the tidyverse.
Value Variable: In the long format, the measured quantity is captured in a value variable that is always numeric. This ensures consistency across datasets and facilitates easy aggregation, summarization, and visualization.
Time Variable: The time dimension is represented by a date variable of class Date or date and time of class POSIXct. A date variable is positioned consistently in the dataset for ease of use:
- First Day of the Period: For date-based data (e.g., monthly, quarterly), the date represents the first day of the period. For example, “March 2024” is represented as "2024-03-01", making it easy to sort and filter chronologically.
Variable Arrangement: Categorical variables, which represent the grouping dimensions of the data (such as region, industry, or demographic group), are positioned on the left side of the dataset. Additional attributes related to observations may be positioned on the right side of the value variable. This arrangement ensures that categorical identifiers are easily distinguishable from the measurement variables and attributes, improving readability and simplifying analysis.
Consistency: This tidy structure allows the data to seamlessly integrate with typical R workflows and tools for data science, such as dplyr and tidyr. By using consistent formatting, robonomistClient data can easily be reshaped, filtered, and summarized to suit a wide range of analytical needs.

Overview of Datasources

The robonomistClient package is designed to simplify working with data from a wide variety of datasources. It allows you to easily access data in a standardized format, freeing you from worrying about how to extract and wrangle data from different providers.

To see all available datasources:

library(robonomistClient)
#> Loaded robonomistClient 2.2.20
#> ℹ Set to connect wss://data.robonomist.app
#> 
#> ✔ Set to connect wss://data.robonomist.app [48ms]
#> 
#> 
#> 
#> 
#> Attaching package: 'robonomistClient'
#> 
#> 
#> The following object is masked from 'package:utils':
#> 
#>     data
datasources()
#> ℹ Connecting to robonomistServer at wss://data.robonomist.app
#> ✔ Connecting to robonomistServer at wss://data.robonomist.app [586ms]
#> 
#> ℹ Connected successfully to robonomistServer 2.9.24
#> ✔ Connected successfully to robonomistServer 2.9.24 [104ms]
#> 
#> ⠙ Requesting datasources
#> ✔ Requesting datasources [217ms]
#> # Robonomist Server Datasources
#>    dataset         title                                    languages datasource
#>    <r_dataset>     <chr>                                    <iso2>    <chr>     
#>  1 StatFin         Statistics Finland, StatFin database     fi,sv,en  StatFin   
#>  2 StatFin_Passii… Statistics Finland, StatFin archive dat… fi,sv,en  StatFin_P…
#>  3 Vero            Finnish Tax Administration statistical … fi,sv,en  Vero      
#>  4 ec              European Commission's Business and Cons… en        EC        
#>  5 kunnat          Key statistics of municipalities, Stati… fi,sv,en  KuntienAv…
#>  6 kunnat          Financial data reported by municipaliti… fi,sv,en  KuntienTa…
#>  7 paavo           Statistics Finland's Paavo database      fi,sv,en  Paavo     
#>  8 tulli           Finnish Customs, Uljas Statistical Data… fi,sv,en  Tulli     
#>  9 luke            Statistics database of Natural Resource… fi,sv,en  Luke      
#> 10 etk             Finnish Centre for Pensions' statistica… fi,sv,en  ETK       
#> # ℹ 50 more rows
#> # ℹ 1 more variable: available <lgl>

The package keeps the listed datasources automatically up-to-date, ensuring that you always access the most current versions.

Working with Data Tables

All content within robonomistClient is organized as data tables, which are typically tibble objects. The data() function is a flexible way to explore and retrieve data tables.

Listing Data Tables

To list all available data tables:

data()
#> ⠙ Requesting data
#> ℹ Object retrieved from client cache (valid until 2024-11-22 13:35:10.516142).
#> ⠙ Requesting data✔ Requesting data [10ms]
#> # Robonomist Database search results
#>    id                                      title                           lang 
#>    <r_id>                                  <chr>                           <chr>
#>  1 StatFin/adopt/statfin_adopt_pxt_11lv.px Adoptiot muuttujina Vuosi, Syn… fi   
#>  2 StatFin/adopt/statfin_adopt_pxt_11lv.px Adoptioner efter År, Födelsela… sv   
#>  3 StatFin/adopt/statfin_adopt_pxt_11lv.px Adoptions by Year, Country of … en   
#>  4 StatFin/adopt/statfin_adopt_pxt_13qh.px Adoptiot muuttujina Vuosi, Ado… fi   
#>  5 StatFin/adopt/statfin_adopt_pxt_13qh.px Adoptioner efter År, Föräldrar… sv   
#>  6 StatFin/adopt/statfin_adopt_pxt_13qh.px Adoptions by Year, Parents of … en   
#>  7 StatFin/aku/statfin_aku_pxt_12dz.px     Aikuiskoulutukseen osallistumi… fi   
#>  8 StatFin/aku/statfin_aku_pxt_12dz.px     Deltagande i vuxenutbildning (… sv   
#>  9 StatFin/aku/statfin_aku_pxt_12dz.px     Participation in adult educati… en   
#> 10 StatFin/aku/statfin_aku_pxt_12ea.px     Aikuiskoulutukseen osallistumi… fi   
#> # ℹ 174,923 more rows

To browse the tables interactively, you can also open them in the Data Viewer:

View(data())

Retrieving a Specific Data Table

If you know the specific ID of the table, you can easily retrieve it:

df <- data("StatFin/synt/statfin_synt_pxt_12dx.px")
#> ⠙ Requesting data
#> ✔ Requesting data [261ms]
#>

To check the version information (vintage) of a data table, use:

data_vintage("StatFin/synt/statfin_synt_pxt_12dx.px")
#> ⠙ Requesting vintage
#> ✔ Requesting vintage [215ms]
#> 
#> StatFin/synt/statfin_synt_pxt_12dx.px 
#>            "2024-05-27 12:23:00 EEST"

Filtering by Dataset

You can also narrow your search to a specific dataset. For instance, to explore all available tables from the Finnish Tax Administration (Vero):

View(data("Vero/"))  # Opens Data Viewer with the tables
data("Vero/")        # Lists tables in the consoledata("Vero/")

Searching and Retrieving Data

The data() function is convenient because it combines searching and retrieving data into a single function:

Search Mode: If the argument matches multiple table IDs or titles, data() returns a tibble of matched data tables. For instance:

data("väestö")  # Returns multiple matches for 'väestö'
#> ⠙ Requesting data
#> ✔ Requesting data [2s]
#> 
#> # Robonomist Database search results
#>    id                                    title                             lang 
#>    <r_id>                                <chr>                             <chr>
#>  1 StatFin/asas/statfin_asas_pxt_115a.px Asuntokunnat ja asuntoväestö muu… fi   
#>  2 StatFin/asas/statfin_asas_pxt_115y.px Asuntokunnat ja asuntoväestö muu… fi   
#>  3 StatFin/asas/statfin_asas_pxt_115z.px Asuntokunnat ja asuntoväestö muu… fi   
#>  4 StatFin/asas/statfin_asas_pxt_116b.px Asuntokunnat ja asuntoväestö muu… fi   
#>  5 StatFin/asas/statfin_asas_pxt_116e.px Asuntokunnat ja asuntoväestö muu… fi   
#>  6 StatFin/eot/statfin_eot_pxt_11te.px   Itse koettu terveys 16 vuotta tä… fi   
#>  7 StatFin/eot/statfin_eot_pxt_11ty.px   Tyytyväisyys elämään 16 vuotta t… fi   
#>  8 StatFin/eot/statfin_eot_pxt_11ub.px   Tyytyväisyys kotitalouden taloud… fi   
#>  9 StatFin/eot/statfin_eot_pxt_11v2.px   Tyytyväisyys elämään, keskiarvot… fi   
#> 10 StatFin/eot/statfin_eot_pxt_11wp.px   Onnellisuuden tunteet neljän vii… fi   
#> # ℹ 843 more rows

Retrieve Mode: If the argument matches exactly one table ID, data() will directly return that data table:

data("StatFin/synt/statfin_synt_pxt_12dx.px")  # Returns the specific data table
#> ⠙ Requesting data
#> ✔ Requesting data [236ms]
#> 
#> # Robonomist id: StatFin/synt/statfin_synt_pxt_12dx.px
#> # Title:         Väestönmuutokset muuttujina Vuosi ja Tiedot
#> # Last updated:  2024-05-28 08:00:00
#> # Next update:   2025-05-20 08:00:00
#> # A tibble:      3,025 × 3
#>    Vuosi Tiedot                     value
#>  * <chr> <chr>                      <dbl>
#>  1 1749  Elävänä syntyneet          16700
#>  2 1749  Kuolleet                   11600
#>  3 1749  Luonnollinen väestönlisäys  5100
#>  4 1749  Kuntien välinen muutto        NA
#>  5 1749  Maahanmuutto Suomeen          NA
#>  6 1749  Maastamuutto Suomesta         NA
#>  7 1749  Nettomaahanmuutto             NA
#>  8 1749  Solmitut avioliitot         3900
#>  9 1749  Avioerot                      NA
#> 10 1749  Kokonaismuutos                NA
#> # ℹ 3,015 more rows

For more robust usage in production, where consistency is key, it is recommended to use more specific functions:

`data_search()` and `data_get()`

To clearly separate search and retrieval operations:

data_search(): Use this function to search for matching table IDs without downloading the actual data. This is useful for exploring available datasets:

data_search("väestö")
#> ⠙ Requesting search
#> ⠹ Requesting search
#> ✔ Requesting search [2.1s]
#> 
#> # Robonomist Database search results
#>    id                                    title                             lang 
#>    <r_id>                                <chr>                             <chr>
#>  1 StatFin/asas/statfin_asas_pxt_115a.px Asuntokunnat ja asuntoväestö muu… fi   
#>  2 StatFin/asas/statfin_asas_pxt_115y.px Asuntokunnat ja asuntoväestö muu… fi   
#>  3 StatFin/asas/statfin_asas_pxt_115z.px Asuntokunnat ja asuntoväestö muu… fi   
#>  4 StatFin/asas/statfin_asas_pxt_116b.px Asuntokunnat ja asuntoväestö muu… fi   
#>  5 StatFin/asas/statfin_asas_pxt_116e.px Asuntokunnat ja asuntoväestö muu… fi   
#>  6 StatFin/eot/statfin_eot_pxt_11te.px   Itse koettu terveys 16 vuotta tä… fi   
#>  7 StatFin/eot/statfin_eot_pxt_11ty.px   Tyytyväisyys elämään 16 vuotta t… fi   
#>  8 StatFin/eot/statfin_eot_pxt_11ub.px   Tyytyväisyys kotitalouden taloud… fi   
#>  9 StatFin/eot/statfin_eot_pxt_11v2.px   Tyytyväisyys elämään, keskiarvot… fi   
#> 10 StatFin/eot/statfin_eot_pxt_11wp.px   Onnellisuuden tunteet neljän vii… fi   
#> # ℹ 843 more rows

data_get(): Use this function for robust retrieval of a specific data table by its ID. This ensures either a data table or an error is returned, making it more predictable for production use:
```
d <- data_get("StatFin/synt/statfin_synt_pxt_12dx.px")
#> ⠙ Requesting get
#> ✔ Requesting get [475ms]
#> 
```

Handling Time and Labels in Data

Tidy Time Formatting

For most datasources, robonomistClient can automatically format the time dimension for easier analysis. Setting the tidy_time argument to TRUE will:

Name the time dimension time.
Convert it to Date class.
Relocate the time variable to be just before the value column, making it more convenient to work with.

# Without tidy time formatting
data_get("StatFin/ntp/statfin_ntp_pxt_132h.px")
#> ⠙ Requesting get
#> ✔ Requesting get [258ms]
#> 
#> # Robonomist id: StatFin/ntp/statfin_ntp_pxt_132h.px
#> # Title:         Bruttokansantuote ja -tulo sekä tarjonta ja kysyntä
#> #   neljännesvuosittain muuttujina Vuosineljännes, Taloustoimi ja Tiedot
#> # Last updated:  2024-09-18 08:00:00
#> # Next update:   2024-11-29 08:00:00
#> # A tibble:      110,124 × 4
#>    Vuosineljännes Taloustoimi                             Tiedot           value
#>  * <chr>          <chr>                                   <chr>            <dbl>
#>  1 1990Q1         B1GMH Bruttokansantuote markkinahintaan Kausitasoitett… 22885.
#>  2 1990Q1         B1GMH Bruttokansantuote markkinahintaan Alkuperäinen s… 21609 
#>  3 1990Q1         B1GMH Bruttokansantuote markkinahintaan Trendisarja kä… 22902.
#>  4 1990Q1         B1GMH Bruttokansantuote markkinahintaan Työpäiväkorjat… 21459.
#>  5 1990Q1         B1GMH Bruttokansantuote markkinahintaan Kausitasoitett… 35958 
#>  6 1990Q1         B1GMH Bruttokansantuote markkinahintaan Alkuperäinen s… 33888 
#>  7 1990Q1         B1GMH Bruttokansantuote markkinahintaan Trendisarja, v… 36013 
#>  8 1990Q1         B1GMH Bruttokansantuote markkinahintaan Työpäiväkorjat… 33928 
#>  9 1990Q1         B1GMH Bruttokansantuote markkinahintaan Kausitasoitetu…    NA 
#> 10 1990Q1         B1GMH Bruttokansantuote markkinahintaan Trendisarjan v…    NA 
#> # ℹ 110,114 more rows

# With tidy time formatting
data_get("StatFin/ntp/statfin_ntp_pxt_132h.px", tidy_time = TRUE)
#> ⠙ Requesting get
#> ✔ Requesting get [253ms]
#> 
#> # Robonomist id: StatFin/ntp/statfin_ntp_pxt_132h.px
#> # Title:         Bruttokansantuote ja -tulo sekä tarjonta ja kysyntä
#> #   neljännesvuosittain muuttujina Vuosineljännes, Taloustoimi ja Tiedot
#> # Last updated:  2024-09-18 08:00:00
#> # Next update:   2024-11-29 08:00:00
#> # A tibble:      110,124 × 4
#>    Taloustoimi                             Tiedot              time        value
#>  * <chr>                                   <chr>               <date>      <dbl>
#>  1 B1GMH Bruttokansantuote markkinahintaan Kausitasoitettu ja… 1990-01-01 22885.
#>  2 B1GMH Bruttokansantuote markkinahintaan Alkuperäinen sarja… 1990-01-01 21609 
#>  3 B1GMH Bruttokansantuote markkinahintaan Trendisarja käypii… 1990-01-01 22902.
#>  4 B1GMH Bruttokansantuote markkinahintaan Työpäiväkorjattu s… 1990-01-01 21459.
#>  5 B1GMH Bruttokansantuote markkinahintaan Kausitasoitettu ja… 1990-01-01 35958 
#>  6 B1GMH Bruttokansantuote markkinahintaan Alkuperäinen sarja… 1990-01-01 33888 
#>  7 B1GMH Bruttokansantuote markkinahintaan Trendisarja, viite… 1990-01-01 36013 
#>  8 B1GMH Bruttokansantuote markkinahintaan Työpäiväkorjattu s… 1990-01-01 33928 
#>  9 B1GMH Bruttokansantuote markkinahintaan Kausitasoitetun ja… 1990-01-01    NA 
#> 10 B1GMH Bruttokansantuote markkinahintaan Trendisarjan volyy… 1990-01-01    NA 
#> # ℹ 110,114 more rows

The tidy_time argument defaults to TRUE for all datasources that provide a consistent schema for time variables.

Working with Labels and Codes

Some datasources provide both labelled and coded versions of data tables. By default, labels are included, but you can control this using the labels argument:

# Retrieve data without labels (useful when working with coded data)
data_get("StatFin/ntp/statfin_ntp_pxt_132h.px", labels = FALSE)
#> ⠙ Requesting get
#> ✔ Requesting get [242ms]
#> 
#> # Robonomist id: StatFin/ntp/statfin_ntp_pxt_132h.px
#> # Title:         Bruttokansantuote ja -tulo sekä tarjonta ja kysyntä
#> #   neljännesvuosittain muuttujina Vuosineljännes, Taloustoimi ja Tiedot
#> # Last updated:  2024-09-18 08:00:00
#> # Next update:   2024-11-29 08:00:00
#> # A tibble:      110,124 × 4
#>    Vuosineljännes Taloustoimi Tiedot               value
#>  * <chr>          <chr>       <chr>                <dbl>
#>  1 1990Q1         B1GMH       kausitcp            22885.
#>  2 1990Q1         B1GMH       tasmcp              21609 
#>  3 1990Q1         B1GMH       trendicp            22902.
#>  4 1990Q1         B1GMH       tyopcp              21459.
#>  5 1990Q1         B1GMH       kausitvv2015        35958 
#>  6 1990Q1         B1GMH       tasmvv2015          33888 
#>  7 1990Q1         B1GMH       trendivv2015        36013 
#>  8 1990Q1         B1GMH       tyopvv2015          33928 
#>  9 1990Q1         B1GMH       vol_kk_kausitvv2015    NA 
#> 10 1990Q1         B1GMH       vol_kk_trendivv2015    NA 
#> # ℹ 110,114 more rows

Tidy Data Principles in robonomistClient