From f22b3157e9fa25c41eea177005f5ffb6da8db084 Mon Sep 17 00:00:00 2001 From: coatless Date: Tue, 14 May 2024 06:41:26 +0000 Subject: [PATCH] =?UTF-8?q?Deploying=20to=20gh-pages=20from=20@=20coatless?= =?UTF-8?q?/quarto-webr@fc18875470ccc29daec668b4674ed4a33575e506=20?= =?UTF-8?q?=F0=9F=9A=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- demos/qwebr-auto-run.html | 2 +- demos/qwebr-code-cell-options.html | 2 +- demos/qwebr-custom-repository.html | 2 +- demos/qwebr-editor-options.html | 2 +- demos/qwebr-global-cell-defaults.html | 2 +- ...running-execution-interactive-locking.html | 2 +- demos/qwebr-non-interactive-areas.html | 2 +- demos/qwebr-read-only.html | 2 +- ...webr-setting-options-in-document-yaml.html | 2 +- examples/blog/index.html | 4 +- examples/blog/posts/post-with-code/index.html | 2 +- examples/book/example-page.html | 2 +- examples/book/index.html | 6 +- examples/html-document/index.html | 2 +- examples/readme/index.html | 2 +- examples/revealjs/index.html | 2 +- examples/website/example-page.html | 2 +- examples/website/index.html | 2 +- index.html | 2 +- qwebr-acknowledgements.html | 2 +- qwebr-cell-options.html | 2 +- qwebr-code-cell-demos.html | 4 +- qwebr-communication-channels.html | 4 +- qwebr-community-examples.html | 2 +- qwebr-deployment-templates.html | 2 +- qwebr-developer-resources.html | 2 +- qwebr-extension-website.html | 2 +- qwebr-faq.html | 2 +- qwebr-first-steps.html | 2 +- qwebr-internal-cell.html | 4 +- qwebr-loading-data.html | 1526 ++++++++++++++++- qwebr-meta-options.html | 2 +- qwebr-release-notes.html | 5 +- qwebr-theming.html | 2 +- qwebr-troubleshooting.html | 2 +- qwebr-using-r-packages.html | 4 +- search.json | 21 +- tests/index.html | 2 +- tests/qwebr-test-editor-options.html | 2 +- ...br-test-escape-html-output-characters.html | 2 +- tests/qwebr-test-global-cell-options.html | 2 +- tests/qwebr-test-help-documentation.html | 2 +- ...st-interactive-with-keyboard-shortcut.html | 2 +- tests/qwebr-test-internal-cell.html | 2 +- tests/qwebr-test-multiple-cells.html | 2 +- ...br-test-non-interactive-chained-cells.html | 2 +- ...non-interactive-context-with-packages.html | 2 +- ...e-setup-with-packages-and-interactive.html | 2 +- ...t-non-interactive-setup-with-packages.html | 2 +- tests/qwebr-test-output-classes.html | 2 +- tests/qwebr-test-output-graph.html | 2 +- ...test-output-stderr-result-suppression.html | 2 +- tests/qwebr-test-packages-autoload.html | 2 +- tests/qwebr-test-packages-multi.html | 2 +- tests/qwebr-test-repo-key.html | 2 +- tests/qwebr-test-revealjs.html | 2 +- tests/qwebr-test-self-contained.html | 2 +- tests/qwebr-test-service-worker.html | 2 +- tests/qwebr-test-shim-install.html | 2 +- tests/qwebr-test-status-header-no-title.html | 2 +- ...st-status-header-suppressed-html copy.html | 2 +- ...est-status-header-suppressed-revealjs.html | 2 +- tests/qwebr-test-theme-switch.html | 2 +- 63 files changed, 1597 insertions(+), 89 deletions(-) diff --git a/demos/qwebr-auto-run.html b/demos/qwebr-auto-run.html index 2441cfa..8646c1f 100644 --- a/demos/qwebr-auto-run.html +++ b/demos/qwebr-auto-run.html @@ -316,7 +316,7 @@ }; // Store cell data -globalThis.qwebrCellDetails = [{"code":"# Write your name here by replace ___\nname <- \"_____\"\nprint(paste0(\"Hello, \", name, \"!\"))","options":{"label":"unnamed-chunk-1","classes":"","message":"true","editor-font-scale":1,"autorun":"false","dpi":72,"fig-width":7,"context":"interactive","editor-quick-suggestions":"false","comment":"","out-width":"700px","warning":"true","fig-cap":"","results":"markup","editor-max-height":"","out-height":"","output":"true","fig-height":5,"read-only":"false"},"id":1},{"code":"# Write your name here by replace ___\nname <- \"_____\"\nprint(paste0(\"Hello, \", name, \"!\"))","options":{"label":"unnamed-chunk-2","classes":"","message":"true","editor-font-scale":1,"autorun":"true","dpi":72,"fig-width":7,"context":"interactive","editor-quick-suggestions":"false","comment":"","out-width":"700px","warning":"true","fig-cap":"","results":"markup","editor-max-height":"","out-height":"","output":"true","fig-height":5,"read-only":"false"},"id":2},{"code":"data(\"gapminder\", package = \"gapminder\")\nhead(gapminder)","options":{"label":"unnamed-chunk-3","classes":"","message":"true","editor-font-scale":1,"autorun":"true","dpi":72,"fig-width":7,"context":"output","editor-quick-suggestions":"false","comment":"","out-width":"700px","warning":"true","fig-cap":"","results":"markup","editor-max-height":"","out-height":"","output":"true","fig-height":5,"read-only":"false"},"id":3},{"code":"ggplot(gapminder, aes(lifeExp)) + \n geom_density(aes(fill=continent), alpha=1/4) + theme_bw() ","options":{"label":"unnamed-chunk-4","classes":"","message":"true","editor-font-scale":1,"autorun":"true","dpi":72,"fig-width":"5","context":"output","editor-quick-suggestions":"false","comment":"","out-width":"500px","warning":"true","fig-cap":"","results":"markup","editor-max-height":"","out-height":"","output":"true","fig-height":"3","read-only":"false"},"id":4},{"code":"ggplot(gapminder, aes(lifeExp)) + \n theme_bw() ","options":{"label":"unnamed-chunk-5","classes":"","message":"true","editor-font-scale":1,"autorun":"true","dpi":72,"fig-width":"5","context":"interactive","editor-quick-suggestions":"false","comment":"","out-width":"500px","warning":"true","fig-cap":"","results":"markup","editor-max-height":"","out-height":"","output":"true","fig-height":"3","read-only":"false"},"id":5}]; +globalThis.qwebrCellDetails = [{"options":{"comment":"","out-height":"","fig-cap":"","context":"interactive","autorun":"false","message":"true","editor-font-scale":1,"dpi":72,"out-width":"700px","classes":"","results":"markup","read-only":"false","label":"unnamed-chunk-1","fig-height":5,"warning":"true","fig-width":7,"editor-quick-suggestions":"false","output":"true","editor-max-height":""},"code":"# Write your name here by replace ___\nname <- \"_____\"\nprint(paste0(\"Hello, \", name, \"!\"))","id":1},{"options":{"comment":"","out-height":"","fig-cap":"","context":"interactive","autorun":"true","message":"true","editor-font-scale":1,"dpi":72,"out-width":"700px","classes":"","results":"markup","read-only":"false","label":"unnamed-chunk-2","fig-height":5,"warning":"true","fig-width":7,"editor-quick-suggestions":"false","output":"true","editor-max-height":""},"code":"# Write your name here by replace ___\nname <- \"_____\"\nprint(paste0(\"Hello, \", name, \"!\"))","id":2},{"options":{"comment":"","out-height":"","fig-cap":"","context":"output","autorun":"true","message":"true","editor-font-scale":1,"dpi":72,"out-width":"700px","classes":"","results":"markup","read-only":"false","label":"unnamed-chunk-3","fig-height":5,"warning":"true","fig-width":7,"editor-quick-suggestions":"false","output":"true","editor-max-height":""},"code":"data(\"gapminder\", package = \"gapminder\")\nhead(gapminder)","id":3},{"options":{"comment":"","out-height":"","fig-cap":"","context":"output","autorun":"true","message":"true","editor-font-scale":1,"dpi":72,"out-width":"500px","classes":"","results":"markup","read-only":"false","label":"unnamed-chunk-4","fig-height":"3","warning":"true","fig-width":"5","editor-quick-suggestions":"false","output":"true","editor-max-height":""},"code":"ggplot(gapminder, aes(lifeExp)) + \n geom_density(aes(fill=continent), alpha=1/4) + theme_bw() ","id":4},{"options":{"comment":"","out-height":"","fig-cap":"","context":"interactive","autorun":"true","message":"true","editor-font-scale":1,"dpi":72,"out-width":"500px","classes":"","results":"markup","read-only":"false","label":"unnamed-chunk-5","fig-height":"3","warning":"true","fig-width":"5","editor-quick-suggestions":"false","output":"true","editor-max-height":""},"code":"ggplot(gapminder, aes(lifeExp)) + \n theme_bw() ","id":5}]; + + + + + + + + + @@ -358,11 +1399,18 @@

On this page

@@ -370,11 +1418,237 @@

On this page

+ + + +

Accessing and Using Data in webR

-

Possible avenues for Data Retrieval

@@ -398,7 +1672,7 @@

Accessing and Using Data in webR

Modified
-

May 12, 2024

+

May 14, 2024

@@ -411,38 +1685,104 @@

Accessing and Using Data in webR

Overview

-

When working with data in webR, there are some tricks to using data in the web environment. This documentation entry guides you through a few changes related to accessing data.

+

When working with webR in a web environment, there are some modifications and considerations required for using data. This documentation entry guides you through a few changes related to accessing data.

+
+

Background: Virtual File System

+

Given the browser-based nature of webR, accessing local files is restricted. To overcome this limitation, webR establishes a virtual file system inside of your browser that is separate from your local file system. Consequently, webR does not have awareness of local file system and its paths. Thus, to use data we need to download it into the virtual file system either through: an R package, a URL using HTTPS, or a Web API.

+

By default, the webR virtual file system’s home directory and initial working directory is /home/web_user. This can be changed using a built-in extension document-level option home-dir.

+
+

Aside

+

While there are methods for mounting pre-built images using the webR’s Mounting Filesystem mechanic, the quarto-webr Extension does not support this option at the moment.

+
+

Accessing Data through R Data Packages

-

One approach to accessing data is to store the data inside of an R data package. This kind of R package consists solely of data in an R ready format with the added benefit of help documentation. If the data package is on CRAN, chances are there is a version available for webR on the main repository (warning not a mobile data friendly link) and, thus, can be accessed using install.packages("pkg") or added to the documents packages key. Otherwise, the R package will need to be converted, deployed, and accessed through GitHub Pages by following the advice to setup a custom package repository.

+

The quickest approach for accessing data is to store it inside of an R data package. This kind of R package consists solely of data in an R ready format with the added benefit of help documentation. If the data package is available on CRAN, there’s a good chance a version exists for webR on the main webR package repository (warning not a mobile data friendly link) and, thus, can be accessed using install.packages("pkg") or added to the documents packages key.

+

If the R package is not available on CRAN, then it will need to be compiled for webR, deployed, and accessed through GitHub Pages or r-universe.dev by following the advice on creating a custom webR/R WASM package repository.

Retrieving Data from the Web

-
+
-Note +Important

Before proceeding, take note of the following considerations when working with remote data:

    -
  1. Security Protocol: webR necessitates data retrieval via the HyperText Transfer Protocol Secure (HTTPS) protocol to ensure secure connections and the Cross-Origin Resource Sharing (CORS) being enabled.
    2. +
  2. Security Protocol: webR necessitates data retrieval via the HyperText Transfer Protocol Secure (HTTPS) protocol to ensure secure connections and the Cross-Origin Resource Sharing (CORS) being enabled on the server where the data is being served.
  3. Package Compatibility: In the absence of websockets within webR, packages reliant on {curl} methods may require adaptation or alternative solutions.
-

When retrieving data in webR, it is imperative to always use links that use HyperText Transfer Protocol Secure (HTTPS). From there, the data at the HTTPS URL can be downloaded using the download.file() function and subsequently reading it into R utilizing a relative path. Follow this example:

-
url <- "https://example.com/data.csv"
-download.file(url, "data.csv")
-

This action saves the file into webR’s virtual file system to be read into R’s analysis environment. Replace "https://example.com/data.csv" with the actual URL of your desired data source.

+
+

Hosting Data

+
+

Standalone Repository

+

We suggest creating a GitHub repository that uses GitHub Pages to host the data. By default, GitHub Pages serves data files using the CORS protocol and can quickly be setup to enforce HTTPS URLs by checking a box.

+

You can see an example raw data repository here:

+

https://github.com/coatless/raw-data

+

The corresponding site deployment of the main branch can be seen here:

+

https://coatless.github.io/raw-data/

+
+
+

Alongside the document

+

There may be times when it is not feasible to create a standalone repository to host the data. In cases like this, you may wish to host the data alongside of the document through Quarto’s publishing system. In this case, please add the resources key to the top of the HTML document or inside the project’s _quarto.yml.

+

For my-document.qmd, this would be:

+
---
+title: "quarto-webr document with data"
+format: 
+  html:
+    resources:
+      - my-data.csv         # Include just the CSV
+      - my-data-directory/* # Include all files
+engine: knitr
+filters:
+  - webr
+---
+

For _quarto.yml, this would be:

+
---
+project:
+  type: website
+  resources:
+    - my-data.csv         # Include just the CSV
+    - my-data-directory/* # Include all files
+---
+

Subsequently, reference the data using the URL to where the document is located. For example, if the document is at:

+
https://example.com/folder/my-document.html
+

Then, the data should be accessed using:

+
https://example.com/folder/my-data.csv
+
+
+
+ +
+
+Note +
+
+
+

You may need to publish the document before using the URL. Also, be mindful of data version mismatches, as the data will be fetched from the HTTPS URL instead of being available locally.

+
+
+
+
+
+

Obtain Data

+

We can retrieve data at a URL with HTTPS through using the download.file() function and, subsequently, reading it into R using a relative path. The later can be done using either Base R or Tidyverse functions.

+

For example, if we wanted to work with flights.csv from the nycflights13 R package (Details), we would specify:

+
url <- "https://coatless.github.io/raw-data/flights.csv"
+download.file(url, "flights.csv")
+

This action saves the file into webR’s virtual file system to be read into R’s analysis environment. Replace "https://coatless.github.io/raw-data/flights.csv" and "flights.csv" with the actual URL of your desired data source and desired local file name.

+

Base R

For optimized performance, leverage base R’s read.*() functions, as they do not necessitate additional package dependencies.

-
data <- read.csv("data.csv")
+
data <- read.csv("flights.csv")

Tidyverse

@@ -460,8 +1800,52 @@

Tidyverse

Note that employing tidyverse or readr functions entails additional package downloads at the session’s outset or immediately preceeding the function usage.

-
install.packages("readr")
-data <- readr::read_csv("data.csv")
+
install.packages("readr")
+data <- readr::read_csv("data.csv")
+
+
+

Try it!

+

We’ve setup the above example inside of an interactive cell for your to explore below.

+
+ +
+
+
+ +
+
+
```{webr-r}
+#| autorun: true
+# See where we are in the file system:
+cat("We're currently at:\n")
+getwd()
+
+# View a list of files for the working directory.
+cat("We have the following files present:\n")
+list.files()
+
+# Specify the data URL using HTTPS
+url <- "https://coatless.github.io/raw-data/flights.csv"
+
+# Download the data file from the HTTPS URL and save it as
+# flights.csv
+cat("Download the data ...\n")
+download.file(url, "flights.csv")
+
+# Check for the data.
+cat("After downloading the data, we now have:\n")
+list.files()
+
+# Read the flights data into R
+flights_from_csv <- read.csv("flights.csv")
+
+# See the first few rows of the flights_from_csv data frame.
+cat("Let's view the first 6 observations of data:\n")
+head(flights_from_csv)
+```
+
+
+
@@ -1034,8 +2418,120 @@

Tidyverse

}); + - \ No newline at end of file + \ No newline at end of file diff --git a/qwebr-meta-options.html b/qwebr-meta-options.html index 7c527cb..6a0c903 100644 --- a/qwebr-meta-options.html +++ b/qwebr-meta-options.html @@ -410,7 +410,7 @@

Customization Options

Modified
-

May 12, 2024

+

May 14, 2024

diff --git a/qwebr-release-notes.html b/qwebr-release-notes.html index 35187dd..fd55fa3 100644 --- a/qwebr-release-notes.html +++ b/qwebr-release-notes.html @@ -484,7 +484,7 @@

Release Notes

Modified
-

May 12, 2024

+

May 14, 2024

@@ -552,7 +552,8 @@

Bug fixes

Documentation

    -
  • Updated community examples covering quarto-webr uses in 2024 Q1 (#193).
    • +

  • Updated community examples covering quarto-webr uses in 2024 Q1 (#193).

    • +

  • Improve the data loading documentation page by clarifying the virtual file system usage (#201).

diff --git a/qwebr-theming.html b/qwebr-theming.html index b53ad48..fb76367 100644 --- a/qwebr-theming.html +++ b/qwebr-theming.html @@ -401,7 +401,7 @@

Theming Elements

Modified
-

May 12, 2024

+

May 14, 2024

diff --git a/qwebr-troubleshooting.html b/qwebr-troubleshooting.html index abf5d6d..b53b6fa 100644 --- a/qwebr-troubleshooting.html +++ b/qwebr-troubleshooting.html @@ -387,7 +387,7 @@

Troubleshooting

Modified
-

May 12, 2024

+

May 14, 2024

diff --git a/qwebr-using-r-packages.html b/qwebr-using-r-packages.html index e8548da..846e301 100644 --- a/qwebr-using-r-packages.html +++ b/qwebr-using-r-packages.html @@ -318,7 +318,7 @@ }; // Store cell data -globalThis.qwebrCellDetails = [{"id":1,"options":{"classes":"","editor-max-height":"","comment":"","label":"unnamed-chunk-1","warning":"true","fig-cap":"","out-width":"700px","autorun":"false","fig-height":5,"output":"true","results":"markup","message":"true","editor-quick-suggestions":"false","dpi":72,"read-only":"false","out-height":"","fig-width":7,"context":"interactive","editor-font-scale":1},"code":"# Determine the version of R being used by webR \nmajor_minor_version <- paste(\n R.version$major, \n strsplit(R.version$minor, \".\", fixed = TRUE)[[1L]][1L],\n sep = \".\"\n)\n\n# Obtain a list of packages\nwebr_info <- as.data.frame(\n available.packages(\n contriburl = paste0(\n \"https://repo.r-wasm.org/bin/emscripten/contrib/\", \n major_minor_version\n )\n )\n)\n\n# Obtain the number of R packages built\nn_webr_pkgs <- nrow(webr_info)\n\n# Number of R packages available to webR\ncat(\"There are current\", n_webr_pkgs, \n \"available to use with webR!\\n\")\n\n# Only view the first 6, there's a lot available!\nhead(webr_info[, c(\"Version\", \"License\")])"},{"id":2,"options":{"classes":"","editor-max-height":"","comment":"","label":"unnamed-chunk-2","warning":"true","fig-cap":"","out-width":"700px","autorun":"false","fig-height":5,"output":"true","results":"markup","message":"true","editor-quick-suggestions":"false","dpi":72,"read-only":"false","out-height":"","fig-width":7,"context":"interactive","editor-font-scale":1},"code":"webr::install(\"ggplot2\")"},{"id":3,"options":{"classes":"","editor-max-height":"","comment":"","label":"unnamed-chunk-3","warning":"true","fig-cap":"","out-width":"700px","autorun":"false","fig-height":5,"output":"true","results":"markup","message":"true","editor-quick-suggestions":"false","dpi":72,"read-only":"false","out-height":"","fig-width":7,"context":"interactive","editor-font-scale":1},"code":"library(\"ggplot2\")\n\nggplot(mpg, aes(displ, hwy, colour = class)) + \n geom_point()"}]; +globalThis.qwebrCellDetails = [{"code":"# Determine the version of R being used by webR \nmajor_minor_version <- paste(\n R.version$major, \n strsplit(R.version$minor, \".\", fixed = TRUE)[[1L]][1L],\n sep = \".\"\n)\n\n# Obtain a list of packages\nwebr_info <- as.data.frame(\n available.packages(\n contriburl = paste0(\n \"https://repo.r-wasm.org/bin/emscripten/contrib/\", \n major_minor_version\n )\n )\n)\n\n# Obtain the number of R packages built\nn_webr_pkgs <- nrow(webr_info)\n\n# Number of R packages available to webR\ncat(\"There are current\", n_webr_pkgs, \n \"available to use with webR!\\n\")\n\n# Only view the first 6, there's a lot available!\nhead(webr_info[, c(\"Version\", \"License\")])","id":1,"options":{"autorun":"false","classes":"","context":"interactive","out-height":"","editor-quick-suggestions":"false","editor-max-height":"","output":"true","fig-height":5,"comment":"","read-only":"false","results":"markup","out-width":"700px","label":"unnamed-chunk-1","editor-font-scale":1,"fig-cap":"","message":"true","dpi":72,"warning":"true","fig-width":7}},{"code":"webr::install(\"ggplot2\")","id":2,"options":{"autorun":"false","classes":"","context":"interactive","out-height":"","editor-quick-suggestions":"false","editor-max-height":"","output":"true","fig-height":5,"comment":"","read-only":"false","results":"markup","out-width":"700px","label":"unnamed-chunk-2","editor-font-scale":1,"fig-cap":"","message":"true","dpi":72,"warning":"true","fig-width":7}},{"code":"library(\"ggplot2\")\n\nggplot(mpg, aes(displ, hwy, colour = class)) + \n geom_point()","id":3,"options":{"autorun":"false","classes":"","context":"interactive","out-height":"","editor-quick-suggestions":"false","editor-max-height":"","output":"true","fig-height":5,"comment":"","read-only":"false","results":"markup","out-width":"700px","label":"unnamed-chunk-3","editor-font-scale":1,"fig-cap":"","message":"true","dpi":72,"warning":"true","fig-width":7}}];