Skip to content

use knitr::kable() tables in vignettes #166

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
dpprdan wants to merge 7 commits into
base: main
Choose a base branch
from
Open

use knitr::kable() tables in vignettes #166

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
628f08e
use knitr::kable() output for dataframes in opencage and customise vi…
dpprdan Jan 25, 2025
238acc7
explicitly install current local version before rendering vignettes
dpprdan Jan 25, 2025
af93643
remove date
dpprdan Jan 25, 2025
20f3446
remove author
dpprdan Jan 25, 2025
6ae0b7c
pre-render vignettes
dpprdan Jan 25, 2025
a15d3f4
update NEWS
dpprdan Jan 25, 2025
5911745
fix lintr issues
dpprdan Jan 25, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions NEWS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@
* `countrycodes` source and script were moved to `data-raw` ([#146](https://github.com/ropensci/opencage/pull/146)).
* Add CITATION.cff and a corresponding GitHub action ([#148](https://github.com/ropensci/opencage/pull/148)).
* Select expressions inside `oc_forward_df()` and `oc_reverse_df()` now use `"column"` instead of `.data$column`, because the latter is [deprecated as of tidyselect v1.2.0](https://tidyselect.r-lib.org/news/index.html#tidyselect-120) ([#150](https://github.com/ropensci/opencage/pull/150)).
* Dataframes in the opencage and customise query vignettes are now rendered with the `knitr::kable()` print method ([#166](https://github.com/ropensci/opencage/pull/166)).
* The opencage code now uses a consistent style (`styler::tidyverse_style()`) and all internal functions are documented ([#153](https://github.com/ropensci/opencage/pull/153)).
* GitHub action workflows have been updated ([#142](https://github.com/ropensci/opencage/issues/142), [#149](https://github.com/ropensci/opencage/pull/149), [#152](https://github.com/ropensci/opencage/pull/152)), [#164](https://github.com/ropensci/opencage/pull/164)).
* Styler, document, and rhub GitHub action workflows have been added ([#153](https://github.com/ropensci/opencage/pull/153), [#164](https://github.com/ropensci/opencage/pull/164)).
Expand Down
262 changes: 132 additions & 130 deletions vignettes/customise_query.Rmd
View file
Open in desktop

Large diffs are not rendered by default.

6 changes: 1 addition & 5 deletions vignettes/customise_query.Rmd.src
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,9 @@
---
title: "Customise your query"
subtitle: "Get more and better results from OpenCage"
author: "Daniel Possenriede, Jesse Sadler, Maëlle Salmon"
date: "`r Sys.Date()`"
description: >
"The OpenCage API supports about a dozen parameters to customise a query and here we will explain how to use them."
output:
rmarkdown::html_vignette:
df_print: kable
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{Customise your query}
%\VignetteEngine{knitr::rmarkdown}
Expand Down
81 changes: 36 additions & 45 deletions vignettes/opencage.Rmd
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,9 @@
---
title: "Introduction to opencage"
subtitle: "Forward and Reverse Geocoding"
author: "Daniel Possenriede, Jesse Sadler, Maëlle Salmon"
date: "2024-12-31"
description: >
"Get started with the opencage R package to geocode with the OpenCage API, either from place name to longitude and latitude (forward geocoding) or from longitude and latitude to the name and address of a location (reverse geocoding)."
output:
rmarkdown::html_vignette:
df_print: kable
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{Introduction to opencage}
%\VignetteEngine{knitr::rmarkdown}
Expand Down Expand Up @@ -111,27 +107,27 @@ Now you can start to geocode. Forward geocoding is from location name(s) to lati

``` r
oc_forward_df(placename = "Sarzeau")
#> # A tibble: 1 × 4
#> placename oc_lat oc_lng oc_formatted
#> <chr> <dbl> <dbl> <chr>
#> 1 Sarzeau 47.5 -2.76 56370 Sarzeau, France
```

|placename | oc_lat| oc_lng|oc_formatted |
|:---------|--------:|-------:|:---------------------|
|Sarzeau | 47.52877| -2.7642|56370 Sarzeau, France |

All geocoding functions are vectorised, i.e. you can geocode multiple locations with one function call.
Note that behind the scenes the requests are still sent to the API one-by-one.


``` r
opera <- c("Palacio de Bellas Artes", "Scala", "Sydney Opera House")
oc_forward_df(placename = opera)
#> # A tibble: 3 × 4
#> placename oc_lat oc_lng oc_formatted
#> <chr> <dbl> <dbl> <chr>
#> 1 Palacio de Bellas Artes 19.4 -99.1 Palacio de Bellas Artes, Avenida Juárez, Barrio Chino, 06050 Mexico City, CMX, M…
#> 2 Scala 40.7 14.6 84010 Scala SA, Italy
#> 3 Sydney Opera House -33.9 151. Sydney Opera House, 2 Macquarie Street, Sydney NSW 2000, Australia
```

|placename | oc_lat| oc_lng|oc_formatted |
|:-----------------------|---------:|---------:|:-------------------------------------------------------------------------------------|
|Palacio de Bellas Artes | 19.43563| -99.14122|Palacio de Bellas Artes, Avenida Juárez, Barrio Chino, 06050 Mexico City, CMX, Mexico |
|Scala | 40.65361| 14.60779|84010 Scala SA, Italy |
|Sydney Opera House | -33.85720| 151.21512|Sydney Opera House, 2 Macquarie Street, Sydney NSW 2000, Australia |

By default, `oc_forward_df()` only returns three results columns: `oc_lat` (for latitude), `oc_lon` (for longitude), and `oc_formatted` (the formatted address).
As you can see, the results columns are all prefixed with `oc_`.
If you specify `oc_forward_df(output = all)`, you will receive all result columns, which are often quite extensive.
Expand All @@ -140,19 +136,14 @@ Which columns you receive exactly depends on the information OpenCage returns fo

``` r
oc_forward_df(placename = opera, output = "all")
#> # A tibble: 3 × 34
#> placename oc_lat oc_lng oc_confidence oc_formatted oc_northeast_lat oc_northeast_lng oc_southwest_lat oc_southwest_lng
#> <chr> <dbl> <dbl> <int> <chr> <dbl> <dbl> <dbl> <dbl>
#> 1 Palacio d… 19.4 -99.1 9 Palacio de … 19.4 -99.1 19.4 -99.1
#> 2 Scala 40.7 14.6 7 84010 Scala… 40.7 14.6 40.6 14.6
#> 3 Sydney Op… -33.9 151. 9 Sydney Oper… -33.9 151. -33.9 151.
#> # ℹ 25 more variables: oc_iso_3166_1_alpha_2 <chr>, oc_iso_3166_1_alpha_3 <chr>, oc_iso_3166_2 <list>,
#> # oc_category <chr>, oc_normalized_city <chr>, oc_type <chr>, oc_borough <chr>, oc_city <chr>, oc_continent <chr>,
#> # oc_country <chr>, oc_country_code <chr>, oc_museum <chr>, oc_neighbourhood <chr>, oc_postcode <chr>, oc_road <chr>,
#> # oc_state <chr>, oc_state_code <chr>, oc_county <chr>, oc_county_code <chr>, oc_political_union <chr>,
#> # oc_village <chr>, oc_attraction <chr>, oc_house_number <chr>, oc_municipality <chr>, oc_suburb <chr>
```

|placename | oc_lat| oc_lng| oc_confidence|oc_formatted | oc_northeast_lat| oc_northeast_lng| oc_southwest_lat| oc_southwest_lng|oc_iso_3166_1_alpha_2 |oc_iso_3166_1_alpha_3 |oc_iso_3166_2 |oc_category |oc_normalized_city |oc_type |oc_borough |oc_city |oc_continent |oc_country |oc_country_code |oc_museum |oc_neighbourhood |oc_postcode |oc_road |oc_state |oc_state_code |oc_county |oc_county_code |oc_political_union |oc_village |oc_attraction |oc_house_number |oc_municipality |oc_suburb |
|:-----------------------|---------:|---------:|-------------:|:-------------------------------------------------------------------------------------|----------------:|----------------:|----------------:|----------------:|:---------------------|:---------------------|:-------------|:-------------------|:------------------|:----------|:----------|:-----------|:-------------|:----------|:---------------|:-----------------------|:----------------|:-----------|:----------------|:---------------|:-------------|:---------|:--------------|:------------------|:----------|:------------------|:---------------|:-----------------------------|:---------|
|Palacio de Bellas Artes | 19.43563| -99.14122| 9|Palacio de Bellas Artes, Avenida Juárez, Barrio Chino, 06050 Mexico City, CMX, Mexico | 19.43598| -99.14090| 19.43495| -99.14162|MX |MEX |MX-CMX |outdoors/recreation |Mexico City |museum |Cuauhtémoc |Mexico City |North America |Mexico |mx |Palacio de Bellas Artes |Barrio Chino |06050 |Avenida Juárez |Mexico City |CMX |NA |NA |NA |NA |NA |NA |NA |NA |
|Scala | 40.65361| 14.60779| 7|84010 Scala SA, Italy | 40.68811| 14.61181| 40.63577| 14.55518|IT |ITA |IT-72, IT-SA |place |Scala |village |NA |NA |Europe |Italy |it |NA |NA |84010 |NA |Campania |CAM |Salerno |SA |European Union |Scala |NA |NA |NA |NA |
|Sydney Opera House | -33.85720| 151.21512| 9|Sydney Opera House, 2 Macquarie Street, Sydney NSW 2000, Australia | -33.85630| 151.21589| -33.85793| 151.21443|AU |AUS |AU-NSW |travel/tourism |Sydney |attraction |Sydney CBD |Sydney |Oceania |Australia |au |NA |Quay Quarter |2000 |Macquarie Street |New South Wales |NSW |NA |NA |NA |NA |Sydney Opera House |2 |Council of the City of Sydney |Sydney |

You can also pass a data frame to `oc_forward_df()`.
By default the results columns are added to the input data frame, which is useful for keeping information associated with the place names that are in separate columns.
If you want a data frame with only the geocoding results, set `bind_cols = FALSE`.
Expand All @@ -162,41 +153,41 @@ If you want a data frame with only the geocoding results, set `bind_cols = FALSE
concert_df <-
data.frame(location = c("Elbphilharmonie", "Concertgebouw", "Suntory Hall"))
oc_forward_df(data = concert_df, placename = location)
#> # A tibble: 3 × 4
#> location oc_lat oc_lng oc_formatted
#> <chr> <dbl> <dbl> <chr>
#> 1 Elbphilharmonie 53.5 9.98 Elbe Philharmonic Hall, Platz der Deutschen Einheit 1, 20457 Hamburg, Germany
#> 2 Concertgebouw 52.4 4.88 Concertgebouw, Concertgebouwplein 2, 1071 LN Amsterdam, Netherlands
#> 3 Suntory Hall 35.7 140. Suntory Hall, Karayan Plaza, Akasaka 1-chome, Minato, 107-6090, Japan
```

|location | oc_lat| oc_lng|oc_formatted |
|:---------------|--------:|----------:|:-----------------------------------------------------------------------------|
|Elbphilharmonie | 53.54129| 9.984206|Elbe Philharmonic Hall, Platz der Deutschen Einheit 1, 20457 Hamburg, Germany |
|Concertgebouw | 52.35620| 4.879045|Concertgebouw, Concertgebouwplein 2, 1071 LN Amsterdam, Netherlands |
|Suntory Hall | 35.66671| 139.741270|Suntory Hall, Karayan Plaza, Akasaka 1-chome, Minato, 107-6090, Japan |

You can use it in a piped workflow as well.


``` r
library(dplyr, warn.conflicts = FALSE)
concert_df %>% oc_forward_df(location)
#> # A tibble: 3 × 4
#> location oc_lat oc_lng oc_formatted
#> <chr> <dbl> <dbl> <chr>
#> 1 Elbphilharmonie 53.5 9.98 Elbe Philharmonic Hall, Platz der Deutschen Einheit 1, 20457 Hamburg, Germany
#> 2 Concertgebouw 52.4 4.88 Concertgebouw, Concertgebouwplein 2, 1071 LN Amsterdam, Netherlands
#> 3 Suntory Hall 35.7 140. Suntory Hall, Karayan Plaza, Akasaka 1-chome, Minato, 107-6090, Japan
```

|location | oc_lat| oc_lng|oc_formatted |
|:---------------|--------:|----------:|:-----------------------------------------------------------------------------|
|Elbphilharmonie | 53.54129| 9.984206|Elbe Philharmonic Hall, Platz der Deutschen Einheit 1, 20457 Hamburg, Germany |
|Concertgebouw | 52.35620| 4.879045|Concertgebouw, Concertgebouwplein 2, 1071 LN Amsterdam, Netherlands |
|Suntory Hall | 35.66671| 139.741270|Suntory Hall, Karayan Plaza, Akasaka 1-chome, Minato, 107-6090, Japan |

## Reverse geocoding

Reverse geocoding works in the opposite direction of forward geocoding: from a pair of coordinates to the name and address most appropriate for the coordinates.


``` r
oc_reverse_df(latitude = 51.5034070, longitude = -0.1275920)
#> # A tibble: 1 × 3
#> latitude longitude oc_formatted
#> <dbl> <dbl> <chr>
#> 1 51.5 -0.128 10 Downing Street, Westminster, London, SW1A 2AA, United Kingdom
```

| latitude| longitude|oc_formatted |
|--------:|---------:|:----------------------------------------------------------------|
| 51.50341| -0.127592|10 Downing Street, Westminster, London, SW1A 2AA, United Kingdom |

Note that all coordinates sent to the OpenCage API must adhere to the [WGS 84](https://en.wikipedia.org/wiki/World_Geodetic_System) (also known as [EPSG:4326](https://epsg.io/4326)) [coordinate reference system](https://en.wikipedia.org/wiki/Spatial_reference_system) in decimal format.
This is the coordinate reference system used by the [Global Positioning System](https://en.wikipedia.org/wiki/Global_Positioning_System).
There is usually no reason to send more than six or seven digits past the decimal.
Expand All @@ -217,11 +208,11 @@ To minimize the number of requests sent to the API {opencage} uses {[memoise](ht
``` r
system.time(oc_reverse(latitude = 10, longitude = 10))
#> user system elapsed
#> 0.01 0.00 1.03
#> 0.00 0.00 0.93

system.time(oc_reverse(latitude = 10, longitude = 10))
#> user system elapsed
#> 0.02 0.00 0.02
#> 0.00 0.00 0.03
```

To clear the cache of all results either start a new R session or call `oc_clear_cache()`.
Expand All @@ -233,7 +224,7 @@ oc_clear_cache()

system.time(oc_reverse(latitude = 10, longitude = 10))
#> user system elapsed
#> 0.01 0.00 1.11
#> 0.01 0.00 0.76
```

As you probably know, cache invalidation is one of the harder things to do in computer science.
Expand Down
6 changes: 1 addition & 5 deletions vignettes/opencage.Rmd.src
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,9 @@
---
title: "Introduction to opencage"
subtitle: "Forward and Reverse Geocoding"
author: "Daniel Possenriede, Jesse Sadler, Maëlle Salmon"
date: "`r Sys.Date()`"
description: >
"Get started with the opencage R package to geocode with the OpenCage API, either from place name to longitude and latitude (forward geocoding) or from longitude and latitude to the name and address of a location (reverse geocoding)."
output:
rmarkdown::html_vignette:
df_print: kable
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{Introduction to opencage}
%\VignetteEngine{knitr::rmarkdown}
Expand Down
14 changes: 5 additions & 9 deletions vignettes/output_options.Rmd
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,9 @@
---
title: "Output options"
subtitle: "Get different kinds of output from OpenCage"
author: "Daniel Possenriede, Jesse Sadler, Maëlle Salmon"
date: "2024-12-31"
description: >
"`oc_forward()`/`oc_reverse()` return lists of various type, namely data frames, JSON, GeoJSON or URLs, depending on the `return` value you specify. The possible `return` values are `df_list`, `json_list`, `geojson_list` and `url_only`."
output:
rmarkdown::html_vignette:
df_print: kable
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{Output options}
%\VignetteEngine{knitr::rmarkdown}
Expand Down Expand Up @@ -188,10 +184,10 @@ oc_forward("Casey Station", return = "json_list")
#>
#> [[1]]$timestamp
#> [[1]]$timestamp$created_http
#> [1] "Tue, 31 Dec 2024 10:46:25 GMT"
#> [1] "Sat, 25 Jan 2025 19:14:52 GMT"
#>
#> [[1]]$timestamp$created_unix
#> [1] 1735641985
#> [1] 1737832492
#>
#>
#> [[1]]$total_results
Expand Down Expand Up @@ -313,10 +309,10 @@ gjsn_lst
#>
#> $timestamp
#> $timestamp$created_http
#> [1] "Tue, 31 Dec 2024 10:46:28 GMT"
#> [1] "Sat, 25 Jan 2025 19:14:54 GMT"
#>
#> $timestamp$created_unix
#> [1] 1735641988
#> [1] 1737832494
#>
#>
#> $total_results
Expand Down
6 changes: 1 addition & 5 deletions vignettes/output_options.Rmd.src
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,9 @@
---
title: "Output options"
subtitle: "Get different kinds of output from OpenCage"
author: "Daniel Possenriede, Jesse Sadler, Maëlle Salmon"
date: "`r Sys.Date()`"
description: >
"`oc_forward()`/`oc_reverse()` return lists of various type, namely data frames, JSON, GeoJSON or URLs, depending on the `return` value you specify. The possible `return` values are `df_list`, `json_list`, `geojson_list` and `url_only`."
output:
rmarkdown::html_vignette:
df_print: kable
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{Output options}
%\VignetteEngine{knitr::rmarkdown}
Expand Down
26 changes: 24 additions & 2 deletions vignettes/precompile.R
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,29 @@
# Precompiled vignettes that depend on API key
# Pre-compile vignettes that depend on API key

pak::local_install() # make sure to use current local version

library(opencage)
library(knitr)

library(knitr) # also load the current version of the package
stopifnot("no OPENCAGE_KEY envvar present" = nzchar(Sys.getenv("OPENCAGE_KEY")))

# write data frames as markdown tables via `knitr::kable()`
knit_print.data.frame <- function(x, ...) { # nolint
res <- paste0(c(kable(x, output = FALSE)), collapse = "\n")
asis_output(res)
}
# register the method
registerS3method("knit_print", "data.frame", knit_print.data.frame)

knit("vignettes/opencage.Rmd.src", "vignettes/opencage.Rmd")
knit("vignettes/customise_query.Rmd.src", "vignettes/customise_query.Rmd")

# reset print method for output_options vignette,
# because kable() doesn't print list columns well
knit_print.data.frame <- function(x, ...) { # nolint
print(x)
}
# register the method
registerS3method("knit_print", "data.frame", knit_print.data.frame)

knit("vignettes/output_options.Rmd.src", "vignettes/output_options.Rmd")