From c785b8868678a7cc2557966dc8f6801355ca5428 Mon Sep 17 00:00:00 2001 From: bubux Date: Fri, 19 Jul 2024 22:46:32 +0200 Subject: [PATCH] update vignettes --- .Rbuildignore | 1 + R/{gen_meta_data.R => gen_metadata.R} | 2 +- man/gen_metadata.Rd | 4 +- man/gen_metadata_cube.Rd | 2 +- man/gen_metadata_statistic.Rd | 2 +- man/gen_metadata_table.Rd | 2 +- man/gen_metadata_value.Rd | 2 +- man/gen_metadata_variable.Rd | 2 +- .../api/catalogue/modifieddata-03cbb4.json | 25 --- vignettes/additional_parameter.Rmd | 110 ++++++------ vignettes/restatis.Rmd | 170 ++++-------------- 11 files changed, 103 insertions(+), 219 deletions(-) rename R/{gen_meta_data.R => gen_metadata.R} (99%) delete mode 100644 tests/testthat/modified2/api/catalogue/modifieddata-03cbb4.json diff --git a/.Rbuildignore b/.Rbuildignore index e79efb0..61b9dae 100644 --- a/.Rbuildignore +++ b/.Rbuildignore @@ -9,3 +9,4 @@ ^docs$ ^pkgdown$ ^codecov\.yml$ +^cran-comments\.md$ diff --git a/R/gen_meta_data.R b/R/gen_metadata.R similarity index 99% rename from R/gen_meta_data.R rename to R/gen_metadata.R index 84c1f12..bfca047 100644 --- a/R/gen_meta_data.R +++ b/R/gen_metadata.R @@ -771,7 +771,7 @@ gen_metadata_cube <- function(code = NULL, #' #' @param code String with a maximum length of 15 characters for a database object (GENESIS, regionalstatistik.de, Zensus 2022). Only one code per iteration. #' @param database Character string. Indicator if the GENESIS ('genesis'), Zensus 2022 ('zensus') or regionalstatistik.de ('regio') database is called. Default option is 'all'. -#' @param category Character string. Specify specific GENESIS/regionalstatistik.de object types ('tables', 'statistics' and 'cubes') and specific Zensus 2022 object types ('tables' and 'statistics'). All types that are specific for one database can be used together. Default option is to use all types that are possible for the specific database. +#' @param category Character string. Specifying the specific object type of the object that you want meta data for. No default option - you need to specify the object type. Hint: The functions in 'restatis' often return information on object 'Type'. #' @param area Character string. Indicator from which area of the database the results are called. In general, 'all' is the appropriate solution. Default option is 'all'. Not used for 'statistics'. #' @param error.ignore Boolean. Indicator if the function should stop if an error occurs or no object for the request is found or if it should produce a token as response. Default option is 'FALSE'. #' @param verbose Boolean. Indicator if the output of the function should include detailed messages and warnings. Default option is 'TRUE'. Set the parameter to 'FALSE' to suppress additional messages and warnings. diff --git a/man/gen_metadata.Rd b/man/gen_metadata.Rd index 31e8abc..7d546cb 100644 --- a/man/gen_metadata.Rd +++ b/man/gen_metadata.Rd @@ -1,5 +1,5 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/gen_meta_data.R +% Please edit documentation in R/gen_metadata.R \name{gen_metadata} \alias{gen_metadata} \title{gen_metadata} @@ -20,7 +20,7 @@ gen_metadata( \item{database}{Character string. Indicator if the GENESIS ('genesis'), Zensus 2022 ('zensus') or regionalstatistik.de ('regio') database is called. Default option is 'all'.} -\item{category}{Character string. Specify specific GENESIS/regionalstatistik.de object types ('tables', 'statistics' and 'cubes') and specific Zensus 2022 object types ('tables' and 'statistics'). All types that are specific for one database can be used together. Default option is to use all types that are possible for the specific database.} +\item{category}{Character string. Specifying the specific object type of the object that you want meta data for. No default option - you need to specify the object type. Hint: The functions in 'restatis' often return information on object 'Type'.} \item{area}{Character string. Indicator from which area of the database the results are called. In general, 'all' is the appropriate solution. Default option is 'all'. Not used for 'statistics'.} diff --git a/man/gen_metadata_cube.Rd b/man/gen_metadata_cube.Rd index 665c7f5..dd3a81c 100644 --- a/man/gen_metadata_cube.Rd +++ b/man/gen_metadata_cube.Rd @@ -1,5 +1,5 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/gen_meta_data.R +% Please edit documentation in R/gen_metadata.R \name{gen_metadata_cube} \alias{gen_metadata_cube} \title{gen_metadata_cube} diff --git a/man/gen_metadata_statistic.Rd b/man/gen_metadata_statistic.Rd index 28326df..442d80e 100644 --- a/man/gen_metadata_statistic.Rd +++ b/man/gen_metadata_statistic.Rd @@ -1,5 +1,5 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/gen_meta_data.R +% Please edit documentation in R/gen_metadata.R \name{gen_metadata_statistic} \alias{gen_metadata_statistic} \title{gen_metadata_statistic} diff --git a/man/gen_metadata_table.Rd b/man/gen_metadata_table.Rd index 3214a9b..8c4ef0f 100644 --- a/man/gen_metadata_table.Rd +++ b/man/gen_metadata_table.Rd @@ -1,5 +1,5 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/gen_meta_data.R +% Please edit documentation in R/gen_metadata.R \name{gen_metadata_table} \alias{gen_metadata_table} \title{gen_metadata_table} diff --git a/man/gen_metadata_value.Rd b/man/gen_metadata_value.Rd index a99f338..bfc591f 100644 --- a/man/gen_metadata_value.Rd +++ b/man/gen_metadata_value.Rd @@ -1,5 +1,5 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/gen_meta_data.R +% Please edit documentation in R/gen_metadata.R \name{gen_metadata_value} \alias{gen_metadata_value} \title{gen_metadata_value} diff --git a/man/gen_metadata_variable.Rd b/man/gen_metadata_variable.Rd index 4cabb23..2870d76 100644 --- a/man/gen_metadata_variable.Rd +++ b/man/gen_metadata_variable.Rd @@ -1,5 +1,5 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/gen_meta_data.R +% Please edit documentation in R/gen_metadata.R \name{gen_metadata_variable} \alias{gen_metadata_variable} \title{gen_metadata_variable} diff --git a/tests/testthat/modified2/api/catalogue/modifieddata-03cbb4.json b/tests/testthat/modified2/api/catalogue/modifieddata-03cbb4.json deleted file mode 100644 index 945cd14..0000000 --- a/tests/testthat/modified2/api/catalogue/modifieddata-03cbb4.json +++ /dev/null @@ -1,25 +0,0 @@ -{ - "Ident": { - "Service": "catalogue", - "Method": "modifieddata" - }, - "Status": { - "Code": 0, - "Content": "erfolgreich", - "Type": "Information" - }, - "Parameter": { - "username": "********************", - "password": "********************", - "selection": "61111", - "type": "Alle", - "date": "18.07.2024", - "pagelength": "100", - "language": "de", - "area": "Alle" - }, - "List": [ - null - ], - "Copyright": "© Statistisches Bundesamt (Destatis), 2024" -} diff --git a/vignettes/additional_parameter.Rmd b/vignettes/additional_parameter.Rmd index a750039..863f2a3 100644 --- a/vignettes/additional_parameter.Rmd +++ b/vignettes/additional_parameter.Rmd @@ -1,5 +1,5 @@ --- -title: "Additional Parameters for the Genesis API Call" +title: "Additional Parameters for API Calls with {restatis}" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{vignette-additional_parameter} @@ -7,43 +7,39 @@ vignette: > %\VignetteEncoding{UTF-8} --- - - - ```{r eval=FALSE, echo=FALSE} library(restatis) ``` ## Information -This is a brief overview of the additional parameters for the Genesis API call. These parameters only affect the Genesis API call itself, no further processing. +This is a brief overview of the additional parameters for an API call via {restatis}. These parameters only affect the API call itself, not the data processing. Be aware: Not all parameters are available for all functions. -Not all parameters are available for all functions. +Especially `gen_table()` and `gen_cube()` have a lot of different additional parameters to specify the API call. For a detailed overview, see the following official documents: -Especially `gen_table()` and `gen_cube()` have a lot of different additional parameters to specify the API call. - -For a detailed overview, see the following official document for Genesis: https://www-genesis.destatis.de/genesis/misc/GENESIS-Webservices_Einfuehrung.pdf -For a detailed overview, see the following official document for Zensus: https://ergebnisse2011.zensus2022.de/datenbank/misc/ZENSUS-Webservices_Einfuehrung.pdf +- The GENESIS database: https://www-genesis.destatis.de/genesis/misc/GENESIS-Webservices_Einfuehrung.pdf +- The Zensus 2022 database: https://ergebnisse2011.zensus2022.de/datenbank/misc/ZENSUS-Webservices_Einfuehrung.pdf +- regionalstatistik.de: https://www.regionalstatistik.de/genesis/misc/GENESIS-Webservices_Einfuehrung.pdf ## Short Overview of the Most Used Additional Parameters ### Parameter: Selection & Searchcriterion -The `selection`-parameter is a string that specifies the filter to use for filtering the API call. The criterion to which this parameter is applied is defined by the `searchcriterion`-parameter. The maximum length of the string depends on the function being used, but often varies between 10 and 15 characters. It is possible to use '*' as a placeholder. The default for this parameter is NO filtering. +The `selection` parameter is a string that specifies the filter to use for filtering the API call. The criterion to which this parameter is applied to is defined by the `searchcriterion` parameter. The maximum length of the string depends on the function being used, but often times varies between 10 and 15 characters. It is possible to use '\*' as a placeholder. The default for this parameter is *no* filtering. -The `searchcriterion`-parameter is a string that specifies the criteria to be used by the `selection`-parameter. Possible values depend on the function being used, but are often "code" for filtering based on code, or "content" for filtering based on content description. The default for this parameter is NO filter criterion. Often `searchcriterion`-parameter and `sortcriterion`-parameter have the same possible values. +The `searchcriterion` parameter is a string that specifies the criterion to be used by the `selection` parameter. Possible values depend on the function being used, but are often times "code" for filtering based on code or "content" for filtering based on the content description. The default for this parameter is *no* filter criterion. Often times, the `searchcriterion` parameter and the `sortcriterion` parameter have the same possible values. Examples: ```{r eval=FALSE} # Get the values of the variable "WAM8" which code starts with "WA29" -gen_val2var("WAM8", selection = "WA29*", searchcriterion = "code") +gen_val2var("WAM8", selection = "WA29*", searchcriterion = "code", database = "genesis") -# Same result can be achieved by the following line due to the default of the "searchcriterion"-parameter: -gen_val2var("WAM8", selection = "WA29*") +# The same result can be achieved by the following line due to the default of the "searchcriterion" parameter: +gen_val2var("WAM8", selection = "WA29*", database = "genesis") ``` ### Parameter: Sortcriterion -The `sortcriterion`-parameter is a string that specifies whether the raw output of the API call is sorted according to the specified input. Possible values depend on the function being used, but often "code" for sorting based on code and "content" for sorting based on content description are possible. The default is NO sorting. +The `sortcriterion` parameter is a string that specifies whether the raw output of the API call is sorted according to the specified input. Possible values depend on the function being used, but often times "code" for sorting based on code and "content" for sorting based on the content description are possible. The default is *no* sorting. Examples: ```{r eval=FALSE} @@ -52,7 +48,7 @@ gen_val2var("WAM8", sortcriterion = "code") ``` ### Parameter: Pagelength -The `pagelength`-parameter is a number between 1 and 2500. It indicates the maximum length of the API call output. Default is 100. +The `pagelength` parameter is a number between 1 and 2500. It indicates the maximum length of the API call output. Default is 100. Examples: ```{r eval=FALSE} @@ -61,7 +57,7 @@ gen_val2var("WAM8", pagelength = 2500) ``` ### Parameter: Language -The `language`-parameter is a string. It indicates if the API call output is in German by using "de" or in English by using "en". Default is "de". +The `language` parameter is a string. It indicates if the API call output is in German by using "de" or in English by using "en". Default is "en" (API default is "de" but it is overwritten by {restatis} to being "en"). Examples: ```{r eval=FALSE} @@ -80,7 +76,7 @@ gen_val2var("WAM8", language = "en") | Parameter | Description | | ----------- | ----------- | -| selection | 1-15 characters; filtering based on "code" of the objects; "*"-Notations are possible | +| selection | 1-15 characters; filtering based on "code" of the objects; "*" notations are possible | | pagelength | 1-2500 | | language | "de" / "en" | @@ -88,11 +84,11 @@ gen_val2var("WAM8", language = "en")
gen_catalogue -For cubes: (only Genesis) +For cubes: (only GENESIS and regionalstatistik.de) | Parameter | Description | | ----------- | ----------- | -| selection | 1-10 characters; filtering based on "code" of the objects; "*"-Notations are possible | +| selection | 1-10 characters; filtering based on "code" of the objects; "*" notations are possible | | pagelength | 1-2500 | | language | "de" / "en" | | area | "all" / "public" / "user" | @@ -101,7 +97,7 @@ For statistics: | Parameter | Description | | ----------- | ----------- | -| selection | 1-15 characters; filtering based on searchcriterion; "*"-Notations are possible | +| selection | 1-15 characters; filtering based on searchcriterion; "*" notations are possible | | searchcriterion | "code" / "content" | | sortcriterion | "code" / "content" | | pagelength | 1-2500 | @@ -111,8 +107,8 @@ For tables: | Parameter | Description | | ----------- | ----------- | -| selection | 1-15 characters; filtering based on searchcriterion; "*"-Notations are possible | -| searchcriterion | "code" / "content" (only Zensus) | +| selection | 1-15 characters; filtering based on searchcriterion; "*" notations are possible | +| searchcriterion | "code" / "content" (only Zensus 2022 database) | | sortcriterion | "code" / "top" | | pagelength | 1-2500 | | language | "de" / "en" | @@ -122,8 +118,10 @@ For tables:
gen_cube + see the following official documentation: https://www-genesis.destatis.de/genesis/misc/GENESIS-Webservices_Einfuehrung.pdf -Only available for Genesis +see the following official documentation: https://www.regionalstatistik.de/genesis/misc/GENESIS-Webservices_Einfuehrung.pdf +Only available for GENESIS and regionalstatistik.de
@@ -140,15 +138,15 @@ Only available for Genesis gen_list_jobs | Parameter | Description | | ----------- | ----------- | -| selection | 1-50 characters; filtering based on "code" of the objects or searchcriterion; "*"-Notations are possible | +| selection | 1-50 characters; filtering based on "code" of the objects or searchcriterion; "*" notations are possible | | searchcriterion | "type" / "code" / "time" / "status" | | sortcriterion | "type" / "code" / "time" / "status" | | pagelength | 1-2500 | | language | "de" / "en" | | type | - | -see more in the following official documentation for Genesis: https://www-genesis.destatis.de/genesis/misc/GENESIS-Webservices_Einfuehrung.pdf -see more in the following official documentation for Zensus: https://ergebnisse2011.zensus2022.de/datenbank/misc/ZENSUS-Webservices_Einfuehrung.pdf +- See more in the following official documentation for GENESIS: https://www-genesis.destatis.de/genesis/misc/GENESIS-Webservices_Einfuehrung.pdf +- See more in the following official documentation for regionalstatistik.de: https://www.regionalstatistik.de/genesis/misc/GENESIS-Webservices_Einfuehrung.pdf
@@ -159,25 +157,25 @@ see more in the following official documentation for Zensus: https://ergebnisse2 | language | "de" / "en" | | area | "all" / "public" / "user" *1 | -*1 for Zensus only tables offer the additional parameter "area". +*1 for Zensus 2022 database only tables offer the additional parameter "area".
gen_modified_data | Parameter | Description | | ----------- | ----------- | -| selection | 1-15 characters; filtering based on "code" of the objects; "*"-Notations are possible | +| selection | 1-15 characters; filtering based on "code" of the objects; "*" notations are possible | | pagelength | 1-2500 | | language | "de" / "en" |
gen_objects2stat -For cubes: (only Genesis) +For cubes: (only GENESIS and regionalstatistik.de) | Parameter | Description | | ----------- | ----------- | -| selection | 1-10 characters; filtering based on "code" of the objects; "*"-Notations are possible | +| selection | 1-10 characters; filtering based on "code" of the objects; "*" notations are possible | | area | "all" / "public" / "user" | | pagelength | 1-2500 | | language | "de" / "en" | @@ -186,7 +184,7 @@ For variables: | Parameter | Description | | ----------- | ----------- | -| selection | 1-6 characters; filtering based on searchcriterion; "*"-Notations are possible | +| selection | 1-6 characters; filtering based on searchcriterion; "*" notations are possible | | searchcriterion | "code" / "content" | | sortcriterion | "code" / "content" | | pagelength | 1-2500 | @@ -194,14 +192,15 @@ For variables: | area | "all" / "public" / "user" | | type | - | -see more in the following official documentation for Genesis: https://www-genesis.destatis.de/genesis/misc/GENESIS-Webservices_Einfuehrung.pdf -see more in the following official documentation for Zensus: https://ergebnisse2011.zensus2022.de/datenbank/misc/ZENSUS-Webservices_Einfuehrung.pdf +- See more in the following official documentation for GENESIS: https://www-genesis.destatis.de/genesis/misc/GENESIS-Webservices_Einfuehrung.pdf +- See more in the following official documentation for the Zensus 2022 database: https://ergebnisse2011.zensus2022.de/datenbank/misc/ZENSUS-Webservices_Einfuehrung.pdf +- See more in the following official documentation for regionalstatistik.de: https://www.regionalstatistik.de/genesis/misc/GENESIS-Webservices_Einfuehrung.pdf For tables: | Parameter | Description | | ----------- | ----------- | -| selection | 1-15 characters; filtering based on "code" of the objects; "*"-Notations are possible | +| selection | 1-15 characters; filtering based on "code" of the objects; "*" notations are possible | | pagelength | 1-2500 | | language | "de" / "en" | | area | "all" / "public" / "user" | @@ -209,11 +208,11 @@ For tables:
gen_objects2var -For cubes: (only Genesis) +For cubes: (only GENESIS and regionalstatistik.de) | Parameter | Description | | ----------- | ----------- | -| selection | 1-15 characters; filtering based on "code" of the objects; "*"-Notations are possible | +| selection | 1-15 characters; filtering based on "code" of the objects; "*" notations are possible | | pagelength | 1-2500 | | language | "de" / "en" | | area | "all" / "public" / "user" | @@ -222,7 +221,7 @@ For statistics: | Parameter | Description | | ----------- | ----------- | -| selection | 1-15 characters; filtering based on searchcriterion; "*"-Notations are possible | +| selection | 1-15 characters; filtering based on searchcriterion; "*" notations are possible | | searchcriterion | "code" / "content" | | sortcriterion | "code" / "content" | | pagelength | 1-2500 | @@ -233,7 +232,7 @@ For tables: | Parameter | Description | | ----------- | ----------- | -| selection | 1-15 characters; filtering based on "code" of the objects; "*"-Notations are possible | +| selection | 1-15 characters; filtering based on "code" of the objects; "*" notations are possible | | pagelength | 1-2500 | | language | "de" / "en" | | area | "all" / "public" / "user" | @@ -241,8 +240,10 @@ For tables:
gen_table -see the following official documentation for Genesis: https://www-genesis.destatis.de/genesis/misc/GENESIS-Webservices_Einfuehrung.pdf -see the following official documentation for Zensus: https://ergebnisse2011.zensus2022.de/datenbank/misc/ZENSUS-Webservices_Einfuehrung.pdf + +- See more in the following official documentation for GENESIS: https://www-genesis.destatis.de/genesis/misc/GENESIS-Webservices_Einfuehrung.pdf +- See more in the following official documentation for the Zensus 2022 database: https://ergebnisse2011.zensus2022.de/datenbank/misc/ZENSUS-Webservices_Einfuehrung.pdf +- See more in the following official documentation for regionalstatistik.de: https://www.regionalstatistik.de/genesis/misc/GENESIS-Webservices_Einfuehrung.pdf
@@ -250,7 +251,7 @@ see the following official documentation for Zensus: https://ergebnisse2011.zens gen_var2stat | Parameter | Description | | ----------- | ----------- | -| selection | 1-6 characters; filtering based on searchcriterion; "*"-Notations are possible | +| selection | 1-6 characters; filtering based on searchcriterion; "*" notations are possible | | searchcriterion | "code" / "content" | | sortcriterion | "code" / "content" | | pagelength | 1-2500 | @@ -258,8 +259,9 @@ see the following official documentation for Zensus: https://ergebnisse2011.zens | area | "all" / "public" / "user" | | type | - | -see more in the following official documentation: https://www-genesis.destatis.de/genesis/misc/GENESIS-Webservices_Einfuehrung.pdf -see more in the following official documentation for Zensus: https://ergebnisse2011.zensus2022.de/datenbank/misc/ZENSUS-Webservices_Einfuehrung.pdf +- See more in the following official documentation for GENESIS: https://www-genesis.destatis.de/genesis/misc/GENESIS-Webservices_Einfuehrung.pdf +- See more in the following official documentation for the Zensus 2022 database: https://ergebnisse2011.zensus2022.de/datenbank/misc/ZENSUS-Webservices_Einfuehrung.pdf +- See more in the following official documentation for regionalstatistik.de: https://www.regionalstatistik.de/genesis/misc/GENESIS-Webservices_Einfuehrung.pdf
@@ -267,7 +269,7 @@ see more in the following official documentation for Zensus: https://ergebnisse2 gen_val2var | Parameter | Description | | ----------- | ----------- | -| selection | 1-15 characters; filtering based on searchcriterion; "*"-Notations are possible | +| selection | 1-15 characters; filtering based on searchcriterion; "*" notations are possible | | searchcriterion | "code" / "content" | | sortcriterion | "code" / "content" | | pagelength | 1-2500 | @@ -279,7 +281,7 @@ see more in the following official documentation for Zensus: https://ergebnisse2 gen_val2var2stat | Parameter | Description | | ----------- | ----------- | -| selection | 1-6 characters; filtering based on searchcriterion; "*"-Notations are possible | +| selection | 1-6 characters; filtering based on searchcriterion; "*" notations are possible | | searchcriterion | "code" / "content" | | sortcriterion | "code" / "content" | | pagelength | 1-2500 | @@ -287,8 +289,9 @@ see more in the following official documentation for Zensus: https://ergebnisse2 | area | "all" / "public" / "user" | | type | - | -see more in the following official documentation: https://www-genesis.destatis.de/genesis/misc/GENESIS-Webservices_Einfuehrung.pdf -see more in the following official documentation for Zensus: https://ergebnisse2011.zensus2022.de/datenbank/misc/ZENSUS-Webservices_Einfuehrung.pdf +- See more in the following official documentation for GENESIS: https://www-genesis.destatis.de/genesis/misc/GENESIS-Webservices_Einfuehrung.pdf +- See more in the following official documentation for the Zensus 2022 database: https://ergebnisse2011.zensus2022.de/datenbank/misc/ZENSUS-Webservices_Einfuehrung.pdf +- See more in the following official documentation for regionalstatistik.de: https://www.regionalstatistik.de/genesis/misc/GENESIS-Webservices_Einfuehrung.pdf
@@ -296,7 +299,7 @@ see more in the following official documentation for Zensus: https://ergebnisse2 gen_search_vars | Parameter | Description | | ----------- | ----------- | -| selection | 1-6 characters; filtering based on searchcriterion; "*"-Notations are possible | +| selection | 1-6 characters; filtering based on searchcriterion; "*" notations are possible | | searchcriterion | "code" / "content" | | sortcriterion | "code" / "content" | | pagelength | 1-2500 | @@ -304,8 +307,9 @@ see more in the following official documentation for Zensus: https://ergebnisse2 | area | "all" / "public" / "user" | | type | - | -see more in the following official documentation: https://www-genesis.destatis.de/genesis/misc/GENESIS-Webservices_Einfuehrung.pdf -see more in the following official documentation for Zensus: https://ergebnisse2011.zensus2022.de/datenbank/misc/ZENSUS-Webservices_Einfuehrung.pdf +- See more in the following official documentation for GENESIS: https://www-genesis.destatis.de/genesis/misc/GENESIS-Webservices_Einfuehrung.pdf +- See more in the following official documentation for the Zensus 2022 database: https://ergebnisse2011.zensus2022.de/datenbank/misc/ZENSUS-Webservices_Einfuehrung.pdf +- See more in the following official documentation for regionalstatistik.de: https://www.regionalstatistik.de/genesis/misc/GENESIS-Webservices_Einfuehrung.pdf @@ -323,7 +327,7 @@ see more in the following official documentation for Zensus: https://ergebnisse2 | Parameter | Description | | ----------- | ----------- | -| selection | 1-15 characters; filtering based on "code"; "*"-Notations are possible | +| selection | 1-15 characters; filtering based on "code"; "*" notations are possible | | area | "all" / "public" / "user" | | pagelength | 1-2500 | | language | "de" / "en" | diff --git a/vignettes/restatis.Rmd b/vignettes/restatis.Rmd index 7081100..9fcd96b 100644 --- a/vignettes/restatis.Rmd +++ b/vignettes/restatis.Rmd @@ -7,20 +7,17 @@ vignette: > %\VignetteEncoding{UTF-8} --- - - - -```r +```{r} library(restatis) ``` ## Introduction -This vignette describes the basic workflow for finding, exploring, and retrieving data from the GENESIS API using [restatis](https://correlaid.github.io/restatis/). +This vignette describes the basic workflow for finding, exploring, and retrieving data from the GENESIS, Zensus 2022 or regionalstatistik.de API using [restatis](https://correlaid.github.io/restatis/). -For more details on additional parameters that can be used to specify the Genesis API call, see `vignette("additional_parameter")`. +For more details on additional parameters that can be used to specify the API call, see `vignette("additional_parameter")`. -For the scenario in this vignette, we are going to be a researcher trying to find data on the income of bus drivers, called "Busfahrer". +For the scenario in this vignette, we are going to be a researcher trying to find data on the income of bus drivers, called "Busfahrer" in German. The following example focuses on the GENESIS database, however, it works practically identical for regionalstatistik.de. For the Zensus 2022 database, the functions also work almost similarly to GENESIS and regionalstatistik.de, but have a few quirks (such as that there are no cubes for Zensus 2022 or that you can also authenticate using an API token). ## Premilinary: finding relevant search terms @@ -28,20 +25,9 @@ First, we can and should explore if and how our keyword is represented in the GE To be as broad as possible, we want to search for any term in the database that contains our keyword. To do this, we can use a "*" wildcard at the beginning and end of the search term: +```{r} +restatis::gen_alternative_terms(term = "*busfahrer*", database = "genesis") -```r -gen_alternative_terms(term = "*busfahrer*") -#> $Output -#> [1] "busfahrer" -#> -#> attr(,"Term") -#> [1] "*busfahrer*" -#> attr(,"Language") -#> [1] "de" -#> attr(,"Pagelength") -#> [1] "100" -#> attr(,"Copyright") -#> [1] "© Statistisches Bundesamt (Destatis), 2023" ``` Based on the results, our original keyword "busfahrer" is already specific enough, and no additional specifications are necessary. @@ -49,30 +35,9 @@ Based on the results, our original keyword "busfahrer" is already specific enoug Had we started with the keyword "bus" - the vehicle itself - we can see that the database has several related terms that might be helpful to narrow our search radius further. In this example, it might be helpful to see that there are at least three different types of buses that are searchable: "fernbus", "schienenbus" and "kraftomnibusse". -```r -gen_alternative_terms(term = "*bus*") -#> $Output -#> [1] "Bus" "bus" "busin" -#> [4] "Busse" "busse" "bambus" -#> [7] "bussen" "büsche" "cottbus" -#> [10] "fernbus" "a.bambus" "aubussons" -#> [13] "business" "jadebusen" "busfahrer" -#> [16] "busin.and" "bambusmöbel" "bambuswaren" -#> [19] "bustickets" "f.omnibusse" "buschbohnen" -#> [22] "kraftomnibus" "bambussprossen" "büstenhalter" -#> [25] "kraftomnibusse" "businessschool" "freilandbüsche" -#> [28] "busin.sch.berlin" "doppellumentubus" "bambusflechtstoffen" -#> [31] "flugticket, business" "business-class-tarif" -#> [ reached getOption("max.print") -- omitted 68 entries ] -#> -#> attr(,"Term") -#> [1] "*bus*" -#> attr(,"Language") -#> [1] "de" -#> attr(,"Pagelength") -#> [1] "100" -#> attr(,"Copyright") -#> [1] "© Statistisches Bundesamt (Destatis), 2023" +```{r} +gen_alternative_terms(term = "*bus*", database = "genesis") + ``` ## Search for data objects @@ -80,106 +45,48 @@ gen_alternative_terms(term = "*bus*") Now that we have our specific keyword for our search, we can search the database for exactly that term. We want the results to be ordered so that items with a title that includes our search term are at the top. We also want to explore all object types for now: -```r -search_results <- gen_find( - term = "busfahrer", - detailed = FALSE, - ordering = TRUE, - category = "all" -) -#> Use 'detailed = TRUE' to obtain the complete output. - +```{r} +search_results <- gen_find(term = "busfahrer", + detailed = FALSE, + ordering = TRUE, + category = "all", + database = "genesis") + search_results -#> $Tables -#> # A tibble: 2 × 3 -#> Code Content Object_Type -#> -#> 1 62361-0030 Bruttostundenverdienste, Bruttomonatsverdienste: Deutschland,… Table -#> 2 62361-0034 Bruttojahresverdienste: Deutschland, Jahre, Geschlecht, Berufe Table -#> -#> $Statistics -#> # A tibble: 1 × 3 -#> Code Content Object_Type -#> -#> 1 62361 Verdiensterhebung Statistic -#> -#> $Variables -#> # A tibble: 1 × 3 -#> Code Content Object_Type -#> -#> 1 KB10A5 Berufsgattungen (KB2010), 5-Steller Variable -#> -#> $Cubes -#> # A tibble: 4 × 3 -#> Code Content Object_Type -#> -#> 1 62361BJ013 Verdiensterhebung, Durchschn. Bruttostundenverdienste ohne So… Cube -#> 2 62361BJ010 Verdiensterhebung, Durchschn. Bruttostundenverdienste ohne So… Cube -#> 3 62361BJ019 Verdiensterhebung, Durchschn. Bruttojahresverdienste inkl. So… Cube -#> 4 62361BJ016 Verdiensterhebung, Durchschn. Bruttojahresverdienste inkl. So… Cube -#> -#> attr(,"Term") -#> [1] "busfahrer" -#> attr(,"Language") -#> [1] "de" -#> attr(,"Pagelength") -#> [1] "100" -#> attr(,"Copyright") -#> [1] "© Statistisches Bundesamt (Destatis), 2023" + ``` We can see that we find results for our keyword "busfahrer" in each category of objects (statistics, tables, variables, and cubes). Based on the promising content description of the first cube object, our next step will be to check what it contains before requesting the data. -As a side note, most of the functions in this package will return objects with additional attributes that represent the parameters and additional information of your GENESIS API query. So check the attributes if you ever need help recognising how you got the output. +As a side note, most of the functions in this package will return objects with additional attributes that represent the parameters and additional information of your API query. So check the attributes if you ever need help recognising how you got the output. ## Checking object metadata -To check whether GENESIS data objects are relevant to your interest, you should obtain the metadata for these objects before requesting the data itself. The metadata for each type of object stores different key characteristics that will help you understand what the object is about. +To check whether data objects are relevant to your interest, you should obtain the metadata for these objects before requesting the data itself. The metadata for each type of object stores different key characteristics that will help you understand what the object is about. For our question about the income of bus drivers, we want to check the metadata of the first cube object we got from the find function: -```r -gen_metadata( - code = search_results$Cubes$Code[1], - category = search_results$Cubes$Object_Type[1] -) -#> Error in gen_metadata(code = search_results$Cubes$Code[1], category = search_results$Cubes$Object_Type[1]): could not find function "gen_metadata" +```{r} +gen_metadata(code = search_results$Cubes$Code[1], + category = search_results$Cubes$Object_Type[1], + database = "genesis") + ``` ## Retrieving data -We are now pretty sure that this cube object will help us find information about our research question. The next step is to get the data from the GENESIS API. - -Based on the fact that we want a cube object, we now use the `gen_cube()` function. For other GENESIS object types, use the corresponding functions (e.g., `gen_table()` for tables). - -Important note: It is not possible to get a whole GENESIS statistic object, but it is possible to collect the different related cube objects independently and then try to recombine them. - - -```r -gen_cube(search_results$Cubes$Code[1]) -#> # A tibble: 2,508 × 20 -#> DINSG GES KB10A5 SMONAT VST045_WERT VST045_QUALITAET VST045_GESPERRT -#> * -#> 1 DG GESM KB10-01104 04/2022 31.3 e NA -#> 2 DG GESM KB10-01203 04/2022 21.6 e NA -#> 3 DG GESM KB10-01302 04/2022 17.4 e NA -#> 4 DG GESM KB10-01402 04/2022 15.3 e NA -#> 5 DG GESM KB10-11101 04/2022 12.8 e NA -#> 6 DG GESM KB10-11102 04/2022 13.7 e NA -#> 7 DG GESM KB10-11103 04/2022 23.6 () NA -#> 8 DG GESM KB10-11104 04/2022 30.8 e NA -#> 9 DG GESM KB10-11113 04/2022 21.4 () NA -#> 10 DG GESM KB10-11114 04/2022 0 / NA -#> # ℹ 2,498 more rows -#> # ℹ 13 more variables: `VST045_WERT-VERFAELSCHT` , VST047_WERT , -#> # VST047_QUALITAET , VST047_GESPERRT , `VST047_WERT-VERFAELSCHT` , -#> # VST051_WERT , VST051_QUALITAET , VST051_GESPERRT , -#> # `VST051_WERT-VERFAELSCHT` , VST052_WERT , VST052_QUALITAET , -#> # VST052_GESPERRT , `VST052_WERT-VERFAELSCHT` -``` +We are now pretty sure that this cube object will help us find information about our research question. The next step is to get the data from the API. + +Based on the fact that we want a cube object, we now use the `gen_cube()` function. For other object types, use the corresponding functions (e.g., `gen_table()` for tables). + +Important note: It is not possible to get a whole statistic object, but it is possible to collect the different related cube objects independently and then try to recombine them. + -TODO: Create helpers to decipher column names. +```{r} +gen_cube(search_results$Cubes$Code[1], database = "genesis") + +``` ## Appendix: check for changes in previously collected data @@ -187,15 +94,12 @@ As a small additional step, we would like to check one week later if the collect If we only want to check if something related has been updated, we only need to use the first part of the code until we are sure that it only covers the topic we are interested in. For example, use "62361*" if you want to check if some updated objects have been published for the specific statistic "Verdiensterhebung". -For convenience, the functions have already implemented the most common `date` specifications, such as "week_before", "month_before", or "year_before". If you prefer a fixed date, you can enter it as a string in the format "DD-MM-YYYY". +For convenience, the functions have already implemented the most common `date` specifications, such as "week_before", "month_before", or "year_before". If you prefer a fixed date, you can enter it as a string in the format "DD.MM.YYYY". For example, we might want to check to see if something new has been published about our collected cube object. So we use only the first part of the code "62361*": -```r +```{r} gen_modified_data(code = "62361", date = "week_before") -#> Please note that this date is calculated automatically and may differ -#> from manually entered data. Manually entered data must have -#> the format DD.MM.YYYY. -#> No modified objects found for your code and date. + ```