diff --git a/_freeze/tutorial-scaffold_googledrive-auth/execute-results/html.json b/_freeze/tutorial-scaffold_googledrive-auth/execute-results/html.json index 8e61468..1118a4b 100644 --- a/_freeze/tutorial-scaffold_googledrive-auth/execute-results/html.json +++ b/_freeze/tutorial-scaffold_googledrive-auth/execute-results/html.json @@ -1,8 +1,8 @@ { - "hash": "0cbdd7735ec4b3a00563c5c9597a3843", + "hash": "3246d47a5a1c48b39c40be4bb45f2247", "result": { "engine": "knitr", - "markdown": "The [`googledrive` R package](https://googledrive.tidyverse.org/) is a package that lets R users directly interact with files on GoogleDrive. This can be extremely useful because it lets all members of a team share the same source data file(s) and guarantees that updates to \"living\" documents are received by all group members the next time they run their R script. This package is technically part of the Tidyverse but is not loaded by running `library(tidyverse)`.\n\nBecause this package requires access to an R user's GoogleDrive, you must \"authenticate\" the `googledrive` package. This essentially tells Google that it is okay if an R package uses your credentials to access and (potentially) modify your Drive content. There are only a few steps to this process but follow along with the below tutorial and we'll get you ready to integrate the Google Drive into your code workflows using the `googledrive` package in no time!\n\n### Prerequisites\n\nTo follow along with this tutorial you will need to take the following steps:\n\n- Download [R](https://cran.r-project.org/)\n- Download [RStudio](https://posit.co/downloads/)\n- Create a Gmail account\n\nFeel free to skip any steps that you have already completed!\n\n### Authorize `googledrive`\n\n\nIn order to connect R with a GoogleDrive, we'll need to authorize `googledrive` to act on our behalf. This only needs to be done once (per computer) so follow along and you'll be building GoogleDrive into your workflows in no time!\n\nFirst, **install the `googledrive` and `httpuv` R packages**. The `googledrive` package's need is self-evident while the `httpuv` package makes the following steps a little easier than `googledrive` makes it alone. Be sure to load the `googledrive` package after you install it!\n\n::: {.cell}\n\n```{.r .cell-code}\n# Install packages\ninstall.packages(c(\"googledrive\", \"httpuv\"))\n\n# Load them\nlibrary(googledrive)\n```\n:::\n\nOnce you've installed the packages we can begin the authentication in R using the `drive_auth` function in the `googledrive` package.\n\n::: {.cell}\n\n```{.r .cell-code}\ngoogledrive::drive_auth(email = \"enter your gmail here!\")\n```\n:::\n\nIf this is your *first time* using `googledrive`, `drive_auth` will kick you to a new tab of your browser (see below for a screen grab of that screen) where you can pick which Gmail you'd like to connect to R.\n\n

\n\n

\n\n**Click the Gmail you want to use** and you will get a second screen where Google tells you that \"Tidyverse API\" wants access to your Google Account. This message is followed by three checkboxes, the first two are grayed out but the third is unchecked.\n\n

\n\n

\n\n:::callout-important\n### NOTE\nThis next bit is vitally important so *carefully* read and follow the next instruction!\n:::\n\nIn this screen, **you must check the unchecked box** to be able to use the `googledrive` R package. If you do not check this box all attempts to use `googledrive` functions will get an error that says \"insufficient permissions\".\n\n

\n\n

\n\nWhile granting access to \"see, edit, create, and \"delete\" all of your Google Drive files\" sounds like a significant security risk, those powers are actually why you're using the `googledrive` package in the first place! You want to be able to download existing Drive files, change them in R on your computer, and then put them back in Google Drive which is exactly what is meant by \"see, edit, create, and delete\".\n\nAlso, this power *only applies to the computer you're currently working on!* Granting access on your work computer allows **only** that computer to access your Drive files. So don't worry about giving access to your Drive to the whole world, that is protected by the same failsafes that you use when you let your computer remember a password to a website you frequent.\n\n*After* you've checked the authorization box, **scroll down and click the \"Continue\" button**.\n\n

\n\n

\n\nThis should result in a plain text page that tells you to close this window and return to R. If you see this message you are ready to use the `googledrive` package!\n\n

\n\n

\n\n\n\n### Problems with Authorization\n\nIf you have tried to use `drive_auth` and *did not* check the box indicated above, you need to make the `googledrive` package ask you again. Using `drive_auth` will not (annoyingly) return you to the place it sent you the first time. However, if you run the following code chunk it should give you another chance to check the needed box.\n\nThe [`gargle` R package](https://gargle.r-lib.org/) referenced below is required for interacting with Google Application Program Interfaces (APIs). This package does the heavy lifting of secure password and token management and is necessary for the `googledrive` authentication chunk below.\n\n\n::: {.cell}\n\n```{.r .cell-code}\ngoogledrive::drive_auth(\n email = gargle::gargle_oauth_email(),\n path = NULL,\n scopes = \"https://www.googleapis.com/auth/drive\",\n cache = gargle::gargle_oauth_cache(),\n use_oob = gargle::gargle_oob_default(),\n token = NULL)\n```\n:::\n\n\nUnfortunately, to use the `googledrive` package you *must* check the box that empowers the package to function as designed. If you're uncomfortable giving the `googledrive` that much power you will need to pivot your workflow away from using GoogleDrive directly. However, NCEAS does offer access to an [internal server called \"Aurora\"](https://nceas.github.io/scicomp-workshop-collaborative-coding/server.html) where data can be securely saved and shared among group members without special authentication like what `googledrive` requires. Reach out to our team if this seems like a more attractive option for your working group and we can offer training on how to use this powerful tool!\n\n### Find and Download Files\n\n\nNow that you've authorized the `googledrive` package, you can start downloading the Google Drive files you need through R! Let's say that you want to download a csv file from a folder or shared drive. You can save the URL of that folder/shared drive to a variable. \n\nThe `googledrive` package makes it straightforward to access Drive folders and files with the `as_id` function. This function allows the full link to a file or folder to serve as a direct connection to that file/folder. Most of the other `googledrive` functions will require a URL that is wrapped with `as_id` in this way. You would replace \"your url here\" with the actual link but make sure it is in quotation marks.\n\n::: {.cell}\n\n```{.r .cell-code}\ndrive_url <- googledrive::as_id(\"your url here\")\n```\n:::\n\nTo list all the contents of this folder, we can use the `drive_ls` function. You will get a dataframe-like object of the files back as the output. An example is shown below in the screenshot. Here, this Google Drive folder contains 4 csv files: `ingredients.csv`, `favorite_soups.csv`, `favorite_fruits.csv` and `favorite_desserts.csv`\n\n::: {.cell}\n\n```{.r .cell-code}\ndrive_folder <- googledrive::drive_ls(path = drive_url)\ndrive_folder\n```\n:::\n\n

\n\n

\n\nIf it has been a while since you've used `googledrive`, it will prompt you to refresh your token. Simply enter the number that corresponds to the correct Google Drive account.\n\n

\n\n

\n\nIf you only want to list files of a certain type, you can specify this in the `type` argument. And let's say that my folder contains a bunch of csv files, but I only want to download the one named \"favorite_desserts.csv\". In that case, I can also put a matching string in the `pattern` argument in order to filter down to 1 file.\n\n::: {.cell}\n\n```{.r .cell-code}\ndrive_folder <- googledrive::drive_ls(path = drive_url,\n type = \"csv\", \n pattern = \"favorite_desserts\")\ndrive_folder\n```\n:::\n\n

\n\n

\n\nOnce we've narrowed down to the file we want, we can download it using `drive_download`. This function takes the file identifier as an argument so we can access it using `drive_folder$id`.\n\n::: {.cell}\n\n```{.r .cell-code}\ngoogledrive::drive_download(file = drive_folder$id)\n```\n:::\n\nThis will automatically download the file to our working directory. If you want, you can specify a different path to download to. Just put the new file path into the `path` argument, replacing the \"your path here\", but keep the quotation marks.\n\n::: {.cell}\n\n```{.r .cell-code}\ngoogledrive::drive_download(file = drive_folder$id, \n path = \"your path here\")\n```\n:::\n\nIf you've downloaded the file before, and you want to overwrite it, there's a handy `overwrite` argument that you can set to `TRUE`. Note that the default is `FALSE`.\n\n::: {.cell}\n\n```{.r .cell-code}\ngoogledrive::drive_download(file = drive_folder$id, \n path = \"your path here\",\n overwrite = T)\n```\n:::\n\nIf there are multiple files in the Drive folder and you want to download them all, you can use a loop like so:\n\n::: {.cell}\n\n```{.r .cell-code}\n# For each file:\nfor(focal_file in drive_folder$name){\n \n # Find the file identifier for that file\n file_id <- subset(drive_folder, name == focal_file)\n\n # Download that file\n drive_download(file = file_id$id, \n path = \"your path here\",\n overwrite = T)\n}\n```\n:::\n\n", + "markdown": "The [`googledrive` R package](https://googledrive.tidyverse.org/) is a package that lets R users directly interact with files on GoogleDrive. This can be extremely useful because it lets all members of a team share the same source data file(s) and guarantees that updates to \"living\" documents are received by all group members the next time they run their R script. This package is technically part of the Tidyverse but is not loaded by running `library(tidyverse)`.\n\nBecause this package requires access to an R user's GoogleDrive, you must \"authenticate\" the `googledrive` package. This essentially tells Google that it is okay if an R package uses your credentials to access and (potentially) modify your Drive content. There are only a few steps to this process but follow along with the below tutorial and we'll get you ready to integrate the Google Drive into your code workflows using the `googledrive` package in no time!\n\n### Prerequisites\n\nTo follow along with this tutorial you will need to take the following steps:\n\n- Download [R](https://cran.r-project.org/)\n- Download [RStudio](https://posit.co/downloads/)\n- Create a Gmail account\n\nFeel free to skip any steps that you have already completed!\n\n### Authorize `googledrive`\n\n\nIn order to connect R with a GoogleDrive, we'll need to authorize `googledrive` to act on our behalf. This only needs to be done once (per computer) so follow along and you'll be building GoogleDrive into your workflows in no time!\n\nFirst, **install the `googledrive` and `httpuv` R packages**. The `googledrive` package's need is self-evident while the `httpuv` package makes the following steps a little easier than `googledrive` makes it alone. Be sure to load the `googledrive` package after you install it!\n\n::: {.cell}\n\n```{.r .cell-code}\n# Install packages\ninstall.packages(c(\"googledrive\", \"httpuv\"))\n\n# Load them\nlibrary(googledrive)\n```\n:::\n\nOnce you've installed the packages we can begin the authentication in R using the `drive_auth` function in the `googledrive` package.\n\n::: {.cell}\n\n```{.r .cell-code}\ngoogledrive::drive_auth(email = \"enter your gmail here!\")\n```\n:::\n\nIf this is your *first time* using `googledrive`, `drive_auth` will kick you to a new tab of your browser (see below for a screen grab of that screen) where you can pick which Gmail you'd like to connect to R.\n\n

\n\n

\n\n**Click the Gmail you want to use** and you will get a second screen where Google tells you that \"Tidyverse API\" wants access to your Google Account. This message is followed by three checkboxes, the first two are grayed out but the third is unchecked.\n\n

\n\n

\n\n:::callout-important\n### NOTE\nThis next bit is vitally important so *carefully* read and follow the next instruction!\n:::\n\nIn this screen, **you must check the unchecked box** to be able to use the `googledrive` R package. If you do not check this box all attempts to use `googledrive` functions will get an error that says \"insufficient permissions\".\n\n

\n\n

\n\nWhile granting access to \"see, edit, create, and \"delete\" all of your Google Drive files\" sounds like a significant security risk, those powers are actually why you're using the `googledrive` package in the first place! You want to be able to download existing Drive files, change them in R on your computer, and then put them back in Google Drive which is exactly what is meant by \"see, edit, create, and delete\".\n\nAlso, this power *only applies to the computer you're currently working on!* Granting access on your work computer allows **only** that computer to access your Drive files. So don't worry about giving access to your Drive to the whole world, that is protected by the same failsafes that you use when you let your computer remember a password to a website you frequent.\n\n*After* you've checked the authorization box, **scroll down and click the \"Continue\" button**.\n\n

\n\n

\n\nThis should result in a plain text page that tells you to close this window and return to R. If you see this message you are ready to use the `googledrive` package!\n\n

\n\n

\n\n\n\n### Problems with Authorization\n\nIf you have tried to use `drive_auth` and *did not* check the box indicated above, you need to make the `googledrive` package ask you again. Using `drive_auth` will not (annoyingly) return you to the place it sent you the first time. However, if you run the following code chunk it should give you another chance to check the needed box.\n\nThe [`gargle` R package](https://gargle.r-lib.org/) referenced below is required for interacting with Google Application Program Interfaces (APIs). This package does the heavy lifting of secure password and token management and is necessary for the `googledrive` authentication chunk below.\n\n\n::: {.cell}\n\n```{.r .cell-code}\ngoogledrive::drive_auth(\n email = gargle::gargle_oauth_email(),\n path = NULL,\n scopes = \"https://www.googleapis.com/auth/drive\",\n cache = gargle::gargle_oauth_cache(),\n use_oob = gargle::gargle_oob_default(),\n token = NULL)\n```\n:::\n\n\nUnfortunately, to use the `googledrive` package you *must* check the box that empowers the package to function as designed. If you're uncomfortable giving the `googledrive` that much power you will need to pivot your workflow away from using GoogleDrive directly. However, NCEAS does offer access to an [internal server called \"Aurora\"](https://lter.github.io/workshop-github/server.html) where data can be securely saved and shared among group members without special authentication like what `googledrive` requires. Reach out to our team if this seems like a more attractive option for your working group and we can offer training on how to use this powerful tool!\n\n### Find and Download Files\n\n\nNow that you've authorized the `googledrive` package, you can start downloading the Google Drive files you need through R! Let's say that you want to download a csv file from a folder or shared drive. You can save the URL of that folder/shared drive to a variable. \n\nThe `googledrive` package makes it straightforward to access Drive folders and files with the `as_id` function. This function allows the full link to a file or folder to serve as a direct connection to that file/folder. Most of the other `googledrive` functions will require a URL that is wrapped with `as_id` in this way. You would replace \"your url here\" with the actual link but make sure it is in quotation marks.\n\n::: {.cell}\n\n```{.r .cell-code}\ndrive_url <- googledrive::as_id(\"your url here\")\n```\n:::\n\nTo list all the contents of this folder, we can use the `drive_ls` function. You will get a dataframe-like object of the files back as the output. An example is shown below in the screenshot. Here, this Google Drive folder contains 4 csv files: `ingredients.csv`, `favorite_soups.csv`, `favorite_fruits.csv` and `favorite_desserts.csv`\n\n::: {.cell}\n\n```{.r .cell-code}\ndrive_folder <- googledrive::drive_ls(path = drive_url)\ndrive_folder\n```\n:::\n\n

\n\n

\n\nIf it has been a while since you've used `googledrive`, it will prompt you to refresh your token. Simply enter the number that corresponds to the correct Google Drive account.\n\n

\n\n

\n\nIf you only want to list files of a certain type, you can specify this in the `type` argument. And let's say that my folder contains a bunch of csv files, but I only want to download the one named \"favorite_desserts.csv\". In that case, I can also put a matching string in the `pattern` argument in order to filter down to 1 file.\n\n::: {.cell}\n\n```{.r .cell-code}\ndrive_folder <- googledrive::drive_ls(path = drive_url,\n type = \"csv\", \n pattern = \"favorite_desserts\")\ndrive_folder\n```\n:::\n\n

\n\n

\n\nOnce we've narrowed down to the file we want, we can download it using `drive_download`. This function takes the file identifier as an argument so we can access it using `drive_folder$id`.\n\n::: {.cell}\n\n```{.r .cell-code}\ngoogledrive::drive_download(file = drive_folder$id)\n```\n:::\n\nThis will automatically download the file to our working directory. If you want, you can specify a different path to download to. Just put the new file path into the `path` argument, replacing the \"your path here\", but keep the quotation marks.\n\n::: {.cell}\n\n```{.r .cell-code}\ngoogledrive::drive_download(file = drive_folder$id, \n path = \"your path here\")\n```\n:::\n\nIf you've downloaded the file before, and you want to overwrite it, there's a handy `overwrite` argument that you can set to `TRUE`. Note that the default is `FALSE`.\n\n::: {.cell}\n\n```{.r .cell-code}\ngoogledrive::drive_download(file = drive_folder$id, \n path = \"your path here\",\n overwrite = T)\n```\n:::\n\nIf there are multiple files in the Drive folder and you want to download them all, you can use a loop like so:\n\n::: {.cell}\n\n```{.r .cell-code}\n# For each file:\nfor(focal_file in drive_folder$name){\n \n # Find the file identifier for that file\n file_id <- subset(drive_folder, name == focal_file)\n\n # Download that file\n drive_download(file = file_id$id, \n path = \"your path here\",\n overwrite = T)\n}\n```\n:::\n\n", "supporting": [], "filters": [ "rmarkdown/pagebreak.lua" diff --git a/_freeze/tutorial-scaffold_quarto-website/execute-results/html.json b/_freeze/tutorial-scaffold_quarto-website/execute-results/html.json index fc3d1f4..71c7a56 100644 --- a/_freeze/tutorial-scaffold_quarto-website/execute-results/html.json +++ b/_freeze/tutorial-scaffold_quarto-website/execute-results/html.json @@ -1,8 +1,8 @@ { - "hash": "ee64e0dc6389a723bc5428a9c201a9f0", + "hash": "85a9913e9f3843d75f69d441584d4f47", "result": { "engine": "knitr", - "markdown": "\n[Quarto](https://quarto.org/) is a new tool developed by RStudio (the company, not the program) to create a more 'what you see is what you get' editor for creating markdown files and products (e.g., books, websites, etc.). Additionally, it includes a visual editor that allows users to insert headings and embed figures via buttons that are intuitively labeled rather than through somewhat arcane HTML text or symbols. While Quarto is still in its infancy, it is rapidly gathering a following due to the aforementioned visual editor and for the ease with which quarto documents and websites can be created.\n\n### Prerequisites\n\nTo follow along with this tutorial you will need to take the following steps:\n\n- Do all of the [pre-workshop steps](https://nceas.github.io/scicomp-workshop-collaborative-coding/#workshop-preparation) relevant to our \"Collaborative Coding with GitHub\" workshop\n- [Download Quarto](https://quarto.org/docs/get-started/)\n\nFeel free to skip any steps that you have already completed!\n\n### Create a Quarto Website R Project\n\nTo begin, **click the \"Project\" button** in the top right of your RStudio session.\n\n\n\nIn the resulting dialogue, **click the \"New Directory\" option.**\n\n

\n\n

\n\nFrom the list of options for project templates, **select \"Quarto Website\".**\n\n

\n\n

\n\n**Pick a title** and **check the \"Create a git repository\" checkbox.** For your title, short but descriptive titles are most effective. Once that is done, click **\"Create Project\"** in the bottom right of the window.\n\n

\n\n

\n\nAfter a few seconds, RStudio should refresh with a Quarto document (such documents have the file extension \".qmd\") and a \"_quarto.yml\" file open.\n\n

\n\n

\n\nPart of Quarto's central philosophy is that all of the formatting of individual .qmd files in a project is governed by the settings created by a singular .yml file. In an R markdown project some of the global settings are set in .yml but other settings are handled within each .Rmd file. This centralization is a key innovation in streamlining projects and is one reason for Quarto's quick popularity.\n\n\n\n### Preparing Project for Web Deployment\n\n\nTo prepare your project for web deployment via GitHub Pages, we have **three** quick steps that we must first complete.\n\n*First*, in the \"_quarto.yml\" file, **add `output-dir: docs` as a subheading beneath the `project:` heading.** Make sure that the indentation is the same as the `type: website` but the new line can be either above or below that line.\n\n

\n\n

\n\n*Second*, **in the \"Terminal\" pane run `touch .nojekyll`.** This creates a file called \".nojekyll\" that is necessary for hosting your website via GitHub Pages. \n\n*Third*, **in the \"Terminal\" pane run `quarto render`.** This processes the template .qmd files you currently have in the repository and prepares them to become actual web pages.\n\nOnce you've done these three things you can move on to creating a GitHub repository so that we can take the necessary steps to having GitHub host your website!\n\n\n\n### Make a New GitHub Repository\n\n\nFrom your GitHub **\"Repositories\"** tab, click the ** green \"New\"** button.\n\n\n\n**Add a title** to your repository and **add a description.** Once you've added these two things, scroll down and click the ** green \"Create repository\" button.**\n\n

\n\n

\nBe sure that you **do not add a README**, **do not add a gitignore**, and **do not add a license.** Adding any of these three will cause a merge conflict when we link the project that you just created with the GitHub repository that you are in the process of creating.\n\n

\n\n

\n\nAfter a few seconds you should be placed on your new repository's landing page which will look like the below image because there isn't anything in your repository (yet).\n\nCopy the link in the field and go back to your RStudio session.\n\n

\n\n

\n\n\n\n### Adding your Project to GitHub\n\n\nThe following steps include a sequence of command line operations that will be relayed in code chunks below. **Unless otherwise stated, all of the following code should be run in \"Terminal\".**\n\nIf you didn't check the \"Create a git repository\" button while creating the R project, you'll need to do that via the command line now. **If you did check that box, you should skip this step!**\n\n::: {.cell}\n\n```{.r .cell-code}\n# Start a git repository on the \"main\" branch\ngit init -b main\n```\n:::\n\n**Stage all of the files in your project to the git repository.** This includes the .yml file, all .qmd files and all of their rendered versions created when you ran `quarto render` earlier. This code is equivalent to checking the box for the files in the \"Git\" pane of RStudio.\n\n::: {.cell}\n\n```{.r .cell-code}\n# Stage all files\ngit add .\n```\n:::\n\nOnce everything has been staged, **you now must commit those staged files** with a message.\n\n::: {.cell}\n\n```{.r .cell-code}\n# Commit all files with the message in quotes\ngit commit -m \"Initial commit\"\n```\n:::\n\nNow that your project files have been committed, you need to **tell your computer where you will be pushing to and pulling from.** Paste the link you copied at the end of the \"Make a New GitHub Repository\" into the code shown in the chunk below (instead of `GITHUB_URL`) and run it.\n\n::: {.cell}\n\n```{.r .cell-code}\n# Tell your computer which GitHub repository to connect to\ngit remote add origin GITHUB_URL\n```\n:::\n\n**Verify that URL** before continuing.\n\n::: {.cell}\n\n```{.r .cell-code}\n# Confirm that URL worked\ngit remote -v\n```\n:::\n\nFinally, **push your commited changes** to the repostory that you set as the remote in the preceding two steps.\n\n::: {.cell}\n\n```{.r .cell-code}\n# Push all of the content to the main branch\ngit push -u origin main\n```\n:::\n\nNow, **go back to GitHub** and refresh the page to see your project content safe and sound in your new GitHub repository!\n\n\n\n\n\n### Deploy Website via GitHub\n\n\nIn order to get your new website actually on the web, we'll need to tell GitHub that we want our website to be accessible at a .github.io URL.\n\nTo do this, **go to the \"Settings\" tab** with a gear icon and click it. You may be prompted to re-enter your GitHub password, do so and you can proceed.\n\n\n\nIn the resulting page, look towards the bottom of the left sidebar of settings categories and **click the \"Pages\" option.** This is at the very bottom of the sidebar in the screen capture below but is towards the middle of all of the settings categories Github offers you.\n\n\n\nScroll down to the middle of this page and where it says \"Branch\" **click the dropdown menu that says \"None\" by default.**\n\n\n\n**Select \"main\"** from the dropdown.\n\n

\n\n

\n\nThis opens up a new dropdown menu where you can select which folder in your repository contains your website's content (it defaults to \"/ (root)\"). Because we specified `output-dir: docs` in the .yml file earlier we can **select \"/docs\" from the dropdown menu.**\n\n

\n\n

\n\nOnce you've told GitHub that you want a website generated from the \"docs\" folder on the main branch, **click the \"Save\" button.**\n\n

\n\n

\n\nFrom this moment your website has begun being deployed by GitHub! You can check the status of the building process by **navigating to the \"Actions\" tab of your repository.**\n\n**Select the \"pages build and deployment workflow\"** in the list of workflows on the bottom righthand side of the page.\n\n\n\nThis **shows you GitHub's building and deployment process as a flowchart.** While it is working on each step there will be an **amber** circle next to the name of that sub-task. When a sub-task is completed, the **amber** circle becomes a **green** circle with a check mark.\n\n\n\nWhen the three steps are complete the **amber** clock symbol next to the \"pages build and deployment\" action will turn into a larger **green** circle with a check mark. This is GitHub's way of telling you that your website is live and accessible to anyone on the internet.\n\n\n\nYou can now visit your website by visiting its dedicated URL. **This URL can be found by returning to the \"Settings\" tab and then scrolling through the sidebar to the \"Pages\" section.**\n\nAlternately, the website for your repository always uses the following composition: *https://**repository owner**.github.io/**repository name**/*\n\n\n\nIf we visit that link, we can see that our website is live!\n\n\n\n#### GitHub Housekeeping\n\nWe recommend a quick housekeeping step now to make it easier to find this URL in the future. **Copy the URL from the Pages setting area and return to the \"Code\" tab of the repository**.\n\nOnce there, **click the small gear icon to the right of the \"About\" header.**\n\n\n\nIn the resulting window, **paste the copied URL into the \"Website\" field.** Once you've pasted it in, **click the** **green** **\"Save changes\" button.**\n\n

\n\n

\n\nThis places the link to your deployed website in an intuitive, easy-to-find location both for interested third parties and yourself in the future.\n\n\n\n\n\n### Adding Website Content\n\n\nNow that you have a live website you can build whatever you'd like! Given the wide range of possibility, we'll only cover how to add a new page but the same process applies to any edit to the living webpage.\n\nTo add a new page **create a new Quarto document.** You can do this by going to the \"File\" menu, entering the \"New File\" options, and selecting \"Quarto Document...\"\n\n

\n\n

\n\nSimilarly to an R markdown file, this will open a new window that lets you enter a title and author as well as decide what format you want to render files to along with some other settings options. **You only need to click the \"Create\" button** in the bottom right of this dialogue (though you can definitely play with the other options and text boxes as you desire).\n\n

\n\n

\n\nAfter a moment, a new .qmd file will open in Quarto's visual editor. **For the purposes of this tutorial, you only need to add a `title` in the top of the file** but for a real website you can add whatever content sparks joy for you!\n\n

\n\n

\n\n**Save that file into your project folder.** Its name can be anything but be sure that you remember what you name it!\n\n

\n\n

\n\n**Add the name of the new Quarto document to the .yml file** in the website navbar area (in this example the file is called \"more-stuff.qmd\").\n\n

\n\n

\n\nOnce you've added the file to the fundamental architecture of your website, you need to tell Quarto to re-build the part of the website that GitHub looks for when it deploys. To do this **run `quarto render` in the Terminal.**\n\nIf you want to *preview* your changes, run `quarto preview` in the Terminal and a new browser window will be displayed showing your current website content. This preview continues until you click the **red** stop sign icon in RStudio so be sure to end it when you're done with the preview!\n\n\n\nRegardless, once you've run either `quarto render` or `quarto preview` **you need to stage and commit all changed files indicated in the Git pane of RStudio**. As a reminder, to stage files you check the box next to them, to commit staged files, type an informative message and press the \"Commit\" button in the right side of the window.\n\n\n\nSwitch back to GitHub and you'll see an **amber** dot next to the commit hash just beneath and to the left of the **green** \"Code\" button.\n\n\n\nWhen the **amber** dot turns into a **green** check mark that means that your edits to your website are now included in the live version of your site!\n\n\n\nWhen you visit your website you may need to refresh the page for your edits to appear but all new visitors will see the updated content when they load the page.\n\n\n\n\n\n### Supplementary Information\n\nQuarto is developing at a rapid pace so quality of life changes and new functionalities are introduced relatively frequently. Additionally, Quarto supports user-created \"extensions\" that can be downloaded in a given project and then used (similar to the way user-developed R packages can be shared) so if you want to do something that Quarto itself doesn't support, chances are you'll be able to find an extension that handles it.\n\n[Quarto's documentation of website creation and formatting](https://quarto.org/docs/websites/) is extremely thorough and is a great resource as you become more comfortable with your new website. We hope this tutorial was useful to you and welcome constructively critical feedback! Please [post an issue](https://github.com/NCEAS/scicomptasks/issues) with any thoughts for improvement that you have.", + "markdown": "\n[Quarto](https://quarto.org/) is a new tool developed by RStudio (the company, not the program) to create a more 'what you see is what you get' editor for creating markdown files and products (e.g., books, websites, etc.). Additionally, it includes a visual editor that allows users to insert headings and embed figures via buttons that are intuitively labeled rather than through somewhat arcane HTML text or symbols. While Quarto is still in its infancy, it is rapidly gathering a following due to the aforementioned visual editor and for the ease with which quarto documents and websites can be created.\n\n### Prerequisites\n\nTo follow along with this tutorial you will need to take the following steps:\n\n- Do all of the [pre-workshop steps](https://lter.github.io/workshop-github/#workshop-preparation) relevant to our \"Collaborative Coding with GitHub\" workshop\n- [Download Quarto](https://quarto.org/docs/get-started/)\n\nFeel free to skip any steps that you have already completed!\n\n### Create a Quarto Website R Project\n\nTo begin, **click the \"Project\" button** in the top right of your RStudio session.\n\n\n\nIn the resulting dialogue, **click the \"New Directory\" option.**\n\n

\n\n

\n\nFrom the list of options for project templates, **select \"Quarto Website\".**\n\n

\n\n

\n\n**Pick a title** and **check the \"Create a git repository\" checkbox.** For your title, short but descriptive titles are most effective. Once that is done, click **\"Create Project\"** in the bottom right of the window.\n\n

\n\n

\n\nAfter a few seconds, RStudio should refresh with a Quarto document (such documents have the file extension \".qmd\") and a \"_quarto.yml\" file open.\n\n

\n\n

\n\nPart of Quarto's central philosophy is that all of the formatting of individual .qmd files in a project is governed by the settings created by a singular .yml file. In an R markdown project some of the global settings are set in .yml but other settings are handled within each .Rmd file. This centralization is a key innovation in streamlining projects and is one reason for Quarto's quick popularity.\n\n\n\n### Preparing Project for Web Deployment\n\n\nTo prepare your project for web deployment via GitHub Pages, we have **three** quick steps that we must first complete.\n\n*First*, in the \"_quarto.yml\" file, **add `output-dir: docs` as a subheading beneath the `project:` heading.** Make sure that the indentation is the same as the `type: website` but the new line can be either above or below that line.\n\n

\n\n

\n\n*Second*, **in the \"Terminal\" pane run `touch .nojekyll`.** This creates a file called \".nojekyll\" that is necessary for hosting your website via GitHub Pages. \n\n*Third*, **in the \"Terminal\" pane run `quarto render`.** This processes the template .qmd files you currently have in the repository and prepares them to become actual web pages.\n\nOnce you've done these three things you can move on to creating a GitHub repository so that we can take the necessary steps to having GitHub host your website!\n\n\n\n### Make a New GitHub Repository\n\n\nFrom your GitHub **\"Repositories\"** tab, click the ** green \"New\"** button.\n\n\n\n**Add a title** to your repository and **add a description.** Once you've added these two things, scroll down and click the ** green \"Create repository\" button.**\n\n

\n\n

\nBe sure that you **do not add a README**, **do not add a gitignore**, and **do not add a license.** Adding any of these three will cause a merge conflict when we link the project that you just created with the GitHub repository that you are in the process of creating.\n\n

\n\n

\n\nAfter a few seconds you should be placed on your new repository's landing page which will look like the below image because there isn't anything in your repository (yet).\n\nCopy the link in the field and go back to your RStudio session.\n\n

\n\n

\n\n\n\n### Adding your Project to GitHub\n\n\nThe following steps include a sequence of command line operations that will be relayed in code chunks below. **Unless otherwise stated, all of the following code should be run in \"Terminal\".**\n\nIf you didn't check the \"Create a git repository\" button while creating the R project, you'll need to do that via the command line now. **If you did check that box, you should skip this step!**\n\n::: {.cell}\n\n```{.r .cell-code}\n# Start a git repository on the \"main\" branch\ngit init -b main\n```\n:::\n\n**Stage all of the files in your project to the git repository.** This includes the .yml file, all .qmd files and all of their rendered versions created when you ran `quarto render` earlier. This code is equivalent to checking the box for the files in the \"Git\" pane of RStudio.\n\n::: {.cell}\n\n```{.r .cell-code}\n# Stage all files\ngit add .\n```\n:::\n\nOnce everything has been staged, **you now must commit those staged files** with a message.\n\n::: {.cell}\n\n```{.r .cell-code}\n# Commit all files with the message in quotes\ngit commit -m \"Initial commit\"\n```\n:::\n\nNow that your project files have been committed, you need to **tell your computer where you will be pushing to and pulling from.** Paste the link you copied at the end of the \"Make a New GitHub Repository\" into the code shown in the chunk below (instead of `GITHUB_URL`) and run it.\n\n::: {.cell}\n\n```{.r .cell-code}\n# Tell your computer which GitHub repository to connect to\ngit remote add origin GITHUB_URL\n```\n:::\n\n**Verify that URL** before continuing.\n\n::: {.cell}\n\n```{.r .cell-code}\n# Confirm that URL worked\ngit remote -v\n```\n:::\n\nFinally, **push your commited changes** to the repostory that you set as the remote in the preceding two steps.\n\n::: {.cell}\n\n```{.r .cell-code}\n# Push all of the content to the main branch\ngit push -u origin main\n```\n:::\n\nNow, **go back to GitHub** and refresh the page to see your project content safe and sound in your new GitHub repository!\n\n\n\n\n\n### Deploy Website via GitHub\n\n\nIn order to get your new website actually on the web, we'll need to tell GitHub that we want our website to be accessible at a .github.io URL.\n\nTo do this, **go to the \"Settings\" tab** with a gear icon and click it. You may be prompted to re-enter your GitHub password, do so and you can proceed.\n\n\n\nIn the resulting page, look towards the bottom of the left sidebar of settings categories and **click the \"Pages\" option.** This is at the very bottom of the sidebar in the screen capture below but is towards the middle of all of the settings categories Github offers you.\n\n\n\nScroll down to the middle of this page and where it says \"Branch\" **click the dropdown menu that says \"None\" by default.**\n\n\n\n**Select \"main\"** from the dropdown.\n\n

\n\n

\n\nThis opens up a new dropdown menu where you can select which folder in your repository contains your website's content (it defaults to \"/ (root)\"). Because we specified `output-dir: docs` in the .yml file earlier we can **select \"/docs\" from the dropdown menu.**\n\n

\n\n

\n\nOnce you've told GitHub that you want a website generated from the \"docs\" folder on the main branch, **click the \"Save\" button.**\n\n

\n\n

\n\nFrom this moment your website has begun being deployed by GitHub! You can check the status of the building process by **navigating to the \"Actions\" tab of your repository.**\n\n**Select the \"pages build and deployment workflow\"** in the list of workflows on the bottom righthand side of the page.\n\n\n\nThis **shows you GitHub's building and deployment process as a flowchart.** While it is working on each step there will be an **amber** circle next to the name of that sub-task. When a sub-task is completed, the **amber** circle becomes a **green** circle with a check mark.\n\n\n\nWhen the three steps are complete the **amber** clock symbol next to the \"pages build and deployment\" action will turn into a larger **green** circle with a check mark. This is GitHub's way of telling you that your website is live and accessible to anyone on the internet.\n\n\n\nYou can now visit your website by visiting its dedicated URL. **This URL can be found by returning to the \"Settings\" tab and then scrolling through the sidebar to the \"Pages\" section.**\n\nAlternately, the website for your repository always uses the following composition: *https://**repository owner**.github.io/**repository name**/*\n\n\n\nIf we visit that link, we can see that our website is live!\n\n\n\n#### GitHub Housekeeping\n\nWe recommend a quick housekeeping step now to make it easier to find this URL in the future. **Copy the URL from the Pages setting area and return to the \"Code\" tab of the repository**.\n\nOnce there, **click the small gear icon to the right of the \"About\" header.**\n\n\n\nIn the resulting window, **paste the copied URL into the \"Website\" field.** Once you've pasted it in, **click the** **green** **\"Save changes\" button.**\n\n

\n\n

\n\nThis places the link to your deployed website in an intuitive, easy-to-find location both for interested third parties and yourself in the future.\n\n\n\n\n\n### Adding Website Content\n\n\nNow that you have a live website you can build whatever you'd like! Given the wide range of possibility, we'll only cover how to add a new page but the same process applies to any edit to the living webpage.\n\nTo add a new page **create a new Quarto document.** You can do this by going to the \"File\" menu, entering the \"New File\" options, and selecting \"Quarto Document...\"\n\n

\n\n

\n\nSimilarly to an R markdown file, this will open a new window that lets you enter a title and author as well as decide what format you want to render files to along with some other settings options. **You only need to click the \"Create\" button** in the bottom right of this dialogue (though you can definitely play with the other options and text boxes as you desire).\n\n

\n\n

\n\nAfter a moment, a new .qmd file will open in Quarto's visual editor. **For the purposes of this tutorial, you only need to add a `title` in the top of the file** but for a real website you can add whatever content sparks joy for you!\n\n

\n\n

\n\n**Save that file into your project folder.** Its name can be anything but be sure that you remember what you name it!\n\n

\n\n

\n\n**Add the name of the new Quarto document to the .yml file** in the website navbar area (in this example the file is called \"more-stuff.qmd\").\n\n

\n\n

\n\nOnce you've added the file to the fundamental architecture of your website, you need to tell Quarto to re-build the part of the website that GitHub looks for when it deploys. To do this **run `quarto render` in the Terminal.**\n\nIf you want to *preview* your changes, run `quarto preview` in the Terminal and a new browser window will be displayed showing your current website content. This preview continues until you click the **red** stop sign icon in RStudio so be sure to end it when you're done with the preview!\n\n\n\nRegardless, once you've run either `quarto render` or `quarto preview` **you need to stage and commit all changed files indicated in the Git pane of RStudio**. As a reminder, to stage files you check the box next to them, to commit staged files, type an informative message and press the \"Commit\" button in the right side of the window.\n\n\n\nSwitch back to GitHub and you'll see an **amber** dot next to the commit hash just beneath and to the left of the **green** \"Code\" button.\n\n\n\nWhen the **amber** dot turns into a **green** check mark that means that your edits to your website are now included in the live version of your site!\n\n\n\nWhen you visit your website you may need to refresh the page for your edits to appear but all new visitors will see the updated content when they load the page.\n\n\n\n\n\n### Supplementary Information\n\nQuarto is developing at a rapid pace so quality of life changes and new functionalities are introduced relatively frequently. Additionally, Quarto supports user-created \"extensions\" that can be downloaded in a given project and then used (similar to the way user-developed R packages can be shared) so if you want to do something that Quarto itself doesn't support, chances are you'll be able to find an extension that handles it.\n\n[Quarto's documentation of website creation and formatting](https://quarto.org/docs/websites/) is extremely thorough and is a great resource as you become more comfortable with your new website. We hope this tutorial was useful to you and welcome constructively critical feedback! Please [post an issue](https://github.com/NCEAS/scicomptasks/issues) with any thoughts for improvement that you have.", "supporting": [], "filters": [ "rmarkdown/pagebreak.lua" diff --git a/_freeze/tutorials/execute-results/html.json b/_freeze/tutorials/execute-results/html.json index cb6b34b..6e66bd9 100644 --- a/_freeze/tutorials/execute-results/html.json +++ b/_freeze/tutorials/execute-results/html.json @@ -1,8 +1,8 @@ { - "hash": "92cc173d83e3f39fedc024ec2cef0ee2", + "hash": "f89020f36e4988ef8c2dc5ecc2cce748", "result": { "engine": "knitr", - "markdown": "---\ntitle: \"Other Tutorials\"\n---\n\n\nSome of the content that we produce is not as detailed as our full workshops but has a wider scope than the content included in our [Coding Tips](https://nceas.github.io/scicomp.github.io/best_practices.html) suggestions. This information can broadly be defined as \"tutorials\" though their depth and scope can vary significantly depending on the topic being tutorialized. As with our [Coding Tips](https://nceas.github.io/scicomp.github.io/best_practices.html), this page is under constant development so please [post an issue](https://github.com/NCEAS/scicomp.github.io/issues) if you have an idea for a tutorial that you'd like to suggest that we create.\n\n## Storing User-Specific Information\n\nWorking groups sometimes need to handle user-specific information in their code. For example, if your group stores your data in the cloud (e.g., in Box, in Dropbox, etc.) each user will have a different \"absolute file path\" to the synced version of the data folder on their personal computer. Similarly, groups may find it valuable to use their email address in the code. While you _could_ simply have each group member add their information (file path, email, etc.) and comment out all but one of them when you work in that script, there is a better option: user-specific JSON files!\n\nThe main advantage of this method is that you and your group members do not have to manually change _any user-specific information_ in scripts just because a different person runs them!\n\n### Prerequisites\n\nTo follow along with this tutorial you will need to take the following steps:\n\n- Download [R](https://cran.r-project.org/)\n- Download [RStudio](https://posit.co/downloads/)\n- Install the `jsonlite` R package\n\nFeel free to skip any steps that you have already completed!\n\n### 1. Create the JSON\n\nFirst, you'll need to use RStudio to create your JSON file by creating a new text file (in the top left of RStudio click \"File\" {{< fa arrow-right >}} \"New File\" {{< fa arrow-right >}} \"Text File\"). In the new text file, add content that looks like this:\n\n::: {.cell}\n\n```{.r .cell-code}\n{\n \"email\":\"my_email@gmail.com\"\n \"dropbox_path\":\"path/to/dropbox-sync/for/me\"\n}\n```\n:::\n\nReplace the content on the _right_ of the colon with your actual information. If desired, you can add as many other pieces of user-specific information as you'd like! Simply follow the `\"info name\":\"info content\"` format and make sure that each piece of information is on its own line.\n\nOne small note here for when you work with your group: all group members need to use _exactly the same name_ to the left of each colon.\n\nYou'll see later when we show an example of this but you can think of the information on the left of the colon as comparable with a column name. It doesn't matter that the text in the \"rows\" will differ between users as long as the script has a consistent \"column\" in which to look for that text.\n\n### 2. Save the JSON with a Consistent Name\n\nThis may seem self-evident but all group members need to use the same file name for this new JSON file. We recommend `user.json` if you are undecided. This will let scripts that refer to the JSON use the same file name regardless of which user is running the code (same spirit as using consistent names for each piece of information in the file.)\n\n### 3. Tell Git to Ignore the JSON\n\nIf you're using version control for your project (which we strongly recommend!), you'll want Git to ignore the fact that this file differs for each user. Navigate to the `.gitignore` file of your project and put in the name of your JSON file as one of the files to ignore. We don't want to push the JSON to GitHub since each person's file will look different (that is our intent after all) and you wouldn't want to accidentally overwrite your teammate's user-specific information or cause a merge conflict.\n\nFor a deeper dive into the `.gitignore` check out [that module](https://nceas.github.io/scicomp-workshop-collaborative-coding/git_ignore.html) of our \"Collaborative Coding with GitHub\" workshop!\n\n### 4. Benefit from the JSON!\n\nIf you've made it through the preceding steps, you can now use the information you stored in the JSON file. You'll need to use the `jsonlite` R package to read in your file but once you've done that, you can access the information inside of it in classic R fashion.\n\nSee an example below:\n\n::: {.cell}\n\n```{.r .cell-code}\n# Load needed library\nlibrary(jsonlite)\n\n# Read in the JSON file\nuser_info <- jsonlite::read_json(\"user.json\")\n\n# Grab the file path out of it\ndropbox <- user_info$dropbox_path\n\n# Use it as you would any other file path\nmy_data <- read.csv(file = file.path(dropbox, \"2024_data.csv\"))\n```\n:::\n\nNow everyone in your group can use the same script because their personal file paths are readily accessible without needing to be hard-coded! The same theory applies to any other piece of information your group finds it valuable to store in the JSON.\n\n#### Help with Absolute File Paths\n\nIdentifying and manually writing out an absolute file path can be cumbersome so we've found a nice work-around (at least for Mac users) that you may find useful. First, in Finder, navigate to the last folder in the file path you'd like to preserve. In the row of folder names in the bottom of the Finder window, right-click the folder name and select \"Copy '\\' as Pathname\".\n\nOnce you've done that, you can simply paste the file path into your JSON file.\n\n

\n\n

\n\n\n\n## Using the `googledrive` R Package\n\nThe [`googledrive` R package](https://googledrive.tidyverse.org/) is a package that lets R users directly interact with files on GoogleDrive. This can be extremely useful because it lets all members of a team share the same source data file(s) and guarantees that updates to \"living\" documents are received by all group members the next time they run their R script. This package is technically part of the Tidyverse but is not loaded by running `library(tidyverse)`.\n\nBecause this package requires access to an R user's GoogleDrive, you must \"authenticate\" the `googledrive` package. This essentially tells Google that it is okay if an R package uses your credentials to access and (potentially) modify your Drive content. There are only a few steps to this process but follow along with the below tutorial and we'll get you ready to integrate the Google Drive into your code workflows using the `googledrive` package in no time!\n\n### Prerequisites\n\nTo follow along with this tutorial you will need to take the following steps:\n\n- Download [R](https://cran.r-project.org/)\n- Download [RStudio](https://posit.co/downloads/)\n- Create a Gmail account\n\nFeel free to skip any steps that you have already completed!\n\n### Authorize `googledrive`\n\n\nIn order to connect R with a GoogleDrive, we'll need to authorize `googledrive` to act on our behalf. This only needs to be done once (per computer) so follow along and you'll be building GoogleDrive into your workflows in no time!\n\nFirst, **install the `googledrive` and `httpuv` R packages**. The `googledrive` package's need is self-evident while the `httpuv` package makes the following steps a little easier than `googledrive` makes it alone. Be sure to load the `googledrive` package after you install it!\n\n::: {.cell}\n\n```{.r .cell-code}\n# Install packages\ninstall.packages(c(\"googledrive\", \"httpuv\"))\n\n# Load them\nlibrary(googledrive)\n```\n:::\n\nOnce you've installed the packages we can begin the authentication in R using the `drive_auth` function in the `googledrive` package.\n\n::: {.cell}\n\n```{.r .cell-code}\ngoogledrive::drive_auth(email = \"enter your gmail here!\")\n```\n:::\n\nIf this is your *first time* using `googledrive`, `drive_auth` will kick you to a new tab of your browser (see below for a screen grab of that screen) where you can pick which Gmail you'd like to connect to R.\n\n

\n\n

\n\n**Click the Gmail you want to use** and you will get a second screen where Google tells you that \"Tidyverse API\" wants access to your Google Account. This message is followed by three checkboxes, the first two are grayed out but the third is unchecked.\n\n

\n\n

\n\n:::callout-important\n### NOTE\nThis next bit is vitally important so *carefully* read and follow the next instruction!\n:::\n\nIn this screen, **you must check the unchecked box** to be able to use the `googledrive` R package. If you do not check this box all attempts to use `googledrive` functions will get an error that says \"insufficient permissions\".\n\n

\n\n

\n\nWhile granting access to \"see, edit, create, and \"delete\" all of your Google Drive files\" sounds like a significant security risk, those powers are actually why you're using the `googledrive` package in the first place! You want to be able to download existing Drive files, change them in R on your computer, and then put them back in Google Drive which is exactly what is meant by \"see, edit, create, and delete\".\n\nAlso, this power *only applies to the computer you're currently working on!* Granting access on your work computer allows **only** that computer to access your Drive files. So don't worry about giving access to your Drive to the whole world, that is protected by the same failsafes that you use when you let your computer remember a password to a website you frequent.\n\n*After* you've checked the authorization box, **scroll down and click the \"Continue\" button**.\n\n

\n\n

\n\nThis should result in a plain text page that tells you to close this window and return to R. If you see this message you are ready to use the `googledrive` package!\n\n

\n\n

\n\n\n\n### Problems with Authorization\n\nIf you have tried to use `drive_auth` and *did not* check the box indicated above, you need to make the `googledrive` package ask you again. Using `drive_auth` will not (annoyingly) return you to the place it sent you the first time. However, if you run the following code chunk it should give you another chance to check the needed box.\n\nThe [`gargle` R package](https://gargle.r-lib.org/) referenced below is required for interacting with Google Application Program Interfaces (APIs). This package does the heavy lifting of secure password and token management and is necessary for the `googledrive` authentication chunk below.\n\n::: {.cell}\n\n```{.r .cell-code}\ngoogledrive::drive_auth(\n email = gargle::gargle_oauth_email(),\n path = NULL,\n scopes = \"https://www.googleapis.com/auth/drive\",\n cache = gargle::gargle_oauth_cache(),\n use_oob = gargle::gargle_oob_default(),\n token = NULL)\n```\n:::\n\nUnfortunately, to use the `googledrive` package you *must* check the box that empowers the package to function as designed. If you're uncomfortable giving the `googledrive` that much power you will need to pivot your workflow away from using GoogleDrive directly. However, NCEAS does offer access to an [internal server called \"Aurora\"](https://nceas.github.io/scicomp-workshop-collaborative-coding/server.html) where data can be securely saved and shared among group members without special authentication like what `googledrive` requires. Reach out to our team if this seems like a more attractive option for your working group and we can offer training on how to use this powerful tool!\n\n### Find and Download Files\n\n\nNow that you've authorized the `googledrive` package, you can start downloading the Google Drive files you need through R! Let's say that you want to download a csv file from a folder or shared drive. You can save the URL of that folder/shared drive to a variable. \n\nThe `googledrive` package makes it straightforward to access Drive folders and files with the `as_id` function. This function allows the full link to a file or folder to serve as a direct connection to that file/folder. Most of the other `googledrive` functions will require a URL that is wrapped with `as_id` in this way. You would replace \"your url here\" with the actual link but make sure it is in quotation marks.\n\n::: {.cell}\n\n```{.r .cell-code}\ndrive_url <- googledrive::as_id(\"your url here\")\n```\n:::\n\nTo list all the contents of this folder, we can use the `drive_ls` function. You will get a dataframe-like object of the files back as the output. An example is shown below in the screenshot. Here, this Google Drive folder contains 4 csv files: `ingredients.csv`, `favorite_soups.csv`, `favorite_fruits.csv` and `favorite_desserts.csv`\n\n::: {.cell}\n\n```{.r .cell-code}\ndrive_folder <- googledrive::drive_ls(path = drive_url)\ndrive_folder\n```\n:::\n\n

\n\n

\n\nIf it has been a while since you've used `googledrive`, it will prompt you to refresh your token. Simply enter the number that corresponds to the correct Google Drive account.\n\n

\n\n

\n\nIf you only want to list files of a certain type, you can specify this in the `type` argument. And let's say that my folder contains a bunch of csv files, but I only want to download the one named \"favorite_desserts.csv\". In that case, I can also put a matching string in the `pattern` argument in order to filter down to 1 file.\n\n::: {.cell}\n\n```{.r .cell-code}\ndrive_folder <- googledrive::drive_ls(path = drive_url,\n type = \"csv\", \n pattern = \"favorite_desserts\")\ndrive_folder\n```\n:::\n\n

\n\n

\n\nOnce we've narrowed down to the file we want, we can download it using `drive_download`. This function takes the file identifier as an argument so we can access it using `drive_folder$id`.\n\n::: {.cell}\n\n```{.r .cell-code}\ngoogledrive::drive_download(file = drive_folder$id)\n```\n:::\n\nThis will automatically download the file to our working directory. If you want, you can specify a different path to download to. Just put the new file path into the `path` argument, replacing the \"your path here\", but keep the quotation marks.\n\n::: {.cell}\n\n```{.r .cell-code}\ngoogledrive::drive_download(file = drive_folder$id, \n path = \"your path here\")\n```\n:::\n\nIf you've downloaded the file before, and you want to overwrite it, there's a handy `overwrite` argument that you can set to `TRUE`. Note that the default is `FALSE`.\n\n::: {.cell}\n\n```{.r .cell-code}\ngoogledrive::drive_download(file = drive_folder$id, \n path = \"your path here\",\n overwrite = T)\n```\n:::\n\nIf there are multiple files in the Drive folder and you want to download them all, you can use a loop like so:\n\n::: {.cell}\n\n```{.r .cell-code}\n# For each file:\nfor(focal_file in drive_folder$name){\n \n # Find the file identifier for that file\n file_id <- subset(drive_folder, name == focal_file)\n\n # Download that file\n drive_download(file = file_id$id, \n path = \"your path here\",\n overwrite = T)\n}\n```\n:::\n\n\n\n\n\n## Building a Website with Quarto\n\n\n[Quarto](https://quarto.org/) is a new tool developed by RStudio (the company, not the program) to create a more 'what you see is what you get' editor for creating markdown files and products (e.g., books, websites, etc.). Additionally, it includes a visual editor that allows users to insert headings and embed figures via buttons that are intuitively labeled rather than through somewhat arcane HTML text or symbols. While Quarto is still in its infancy, it is rapidly gathering a following due to the aforementioned visual editor and for the ease with which quarto documents and websites can be created.\n\n### Prerequisites\n\nTo follow along with this tutorial you will need to take the following steps:\n\n- Do all of the [pre-workshop steps](https://nceas.github.io/scicomp-workshop-collaborative-coding/#workshop-preparation) relevant to our \"Collaborative Coding with GitHub\" workshop\n- [Download Quarto](https://quarto.org/docs/get-started/)\n\nFeel free to skip any steps that you have already completed!\n\n### Create a Quarto Website R Project\n\nTo begin, **click the \"Project\" button** in the top right of your RStudio session.\n\n\n\nIn the resulting dialogue, **click the \"New Directory\" option.**\n\n

\n\n

\n\nFrom the list of options for project templates, **select \"Quarto Website\".**\n\n

\n\n

\n\n**Pick a title** and **check the \"Create a git repository\" checkbox.** For your title, short but descriptive titles are most effective. Once that is done, click **\"Create Project\"** in the bottom right of the window.\n\n

\n\n

\n\nAfter a few seconds, RStudio should refresh with a Quarto document (such documents have the file extension \".qmd\") and a \"_quarto.yml\" file open.\n\n

\n\n

\n\nPart of Quarto's central philosophy is that all of the formatting of individual .qmd files in a project is governed by the settings created by a singular .yml file. In an R markdown project some of the global settings are set in .yml but other settings are handled within each .Rmd file. This centralization is a key innovation in streamlining projects and is one reason for Quarto's quick popularity.\n\n\n\n### Preparing Project for Web Deployment\n\n\nTo prepare your project for web deployment via GitHub Pages, we have **three** quick steps that we must first complete.\n\n*First*, in the \"_quarto.yml\" file, **add `output-dir: docs` as a subheading beneath the `project:` heading.** Make sure that the indentation is the same as the `type: website` but the new line can be either above or below that line.\n\n

\n\n

\n\n*Second*, **in the \"Terminal\" pane run `touch .nojekyll`.** This creates a file called \".nojekyll\" that is necessary for hosting your website via GitHub Pages. \n\n*Third*, **in the \"Terminal\" pane run `quarto render`.** This processes the template .qmd files you currently have in the repository and prepares them to become actual web pages.\n\nOnce you've done these three things you can move on to creating a GitHub repository so that we can take the necessary steps to having GitHub host your website!\n\n\n\n### Make a New GitHub Repository\n\n\nFrom your GitHub **\"Repositories\"** tab, click the ** green \"New\"** button.\n\n\n\n**Add a title** to your repository and **add a description.** Once you've added these two things, scroll down and click the ** green \"Create repository\" button.**\n\n

\n\n

\nBe sure that you **do not add a README**, **do not add a gitignore**, and **do not add a license.** Adding any of these three will cause a merge conflict when we link the project that you just created with the GitHub repository that you are in the process of creating.\n\n

\n\n

\n\nAfter a few seconds you should be placed on your new repository's landing page which will look like the below image because there isn't anything in your repository (yet).\n\nCopy the link in the field and go back to your RStudio session.\n\n

\n\n

\n\n\n\n### Adding your Project to GitHub\n\n\nThe following steps include a sequence of command line operations that will be relayed in code chunks below. **Unless otherwise stated, all of the following code should be run in \"Terminal\".**\n\nIf you didn't check the \"Create a git repository\" button while creating the R project, you'll need to do that via the command line now. **If you did check that box, you should skip this step!**\n\n::: {.cell}\n\n```{.r .cell-code}\n# Start a git repository on the \"main\" branch\ngit init -b main\n```\n:::\n\n**Stage all of the files in your project to the git repository.** This includes the .yml file, all .qmd files and all of their rendered versions created when you ran `quarto render` earlier. This code is equivalent to checking the box for the files in the \"Git\" pane of RStudio.\n\n::: {.cell}\n\n```{.r .cell-code}\n# Stage all files\ngit add .\n```\n:::\n\nOnce everything has been staged, **you now must commit those staged files** with a message.\n\n::: {.cell}\n\n```{.r .cell-code}\n# Commit all files with the message in quotes\ngit commit -m \"Initial commit\"\n```\n:::\n\nNow that your project files have been committed, you need to **tell your computer where you will be pushing to and pulling from.** Paste the link you copied at the end of the \"Make a New GitHub Repository\" into the code shown in the chunk below (instead of `GITHUB_URL`) and run it.\n\n::: {.cell}\n\n```{.r .cell-code}\n# Tell your computer which GitHub repository to connect to\ngit remote add origin GITHUB_URL\n```\n:::\n\n**Verify that URL** before continuing.\n\n::: {.cell}\n\n```{.r .cell-code}\n# Confirm that URL worked\ngit remote -v\n```\n:::\n\nFinally, **push your commited changes** to the repostory that you set as the remote in the preceding two steps.\n\n::: {.cell}\n\n```{.r .cell-code}\n# Push all of the content to the main branch\ngit push -u origin main\n```\n:::\n\nNow, **go back to GitHub** and refresh the page to see your project content safe and sound in your new GitHub repository!\n\n\n\n\n\n### Deploy Website via GitHub\n\n\nIn order to get your new website actually on the web, we'll need to tell GitHub that we want our website to be accessible at a .github.io URL.\n\nTo do this, **go to the \"Settings\" tab** with a gear icon and click it. You may be prompted to re-enter your GitHub password, do so and you can proceed.\n\n\n\nIn the resulting page, look towards the bottom of the left sidebar of settings categories and **click the \"Pages\" option.** This is at the very bottom of the sidebar in the screen capture below but is towards the middle of all of the settings categories Github offers you.\n\n\n\nScroll down to the middle of this page and where it says \"Branch\" **click the dropdown menu that says \"None\" by default.**\n\n\n\n**Select \"main\"** from the dropdown.\n\n

\n\n

\n\nThis opens up a new dropdown menu where you can select which folder in your repository contains your website's content (it defaults to \"/ (root)\"). Because we specified `output-dir: docs` in the .yml file earlier we can **select \"/docs\" from the dropdown menu.**\n\n

\n\n

\n\nOnce you've told GitHub that you want a website generated from the \"docs\" folder on the main branch, **click the \"Save\" button.**\n\n

\n\n

\n\nFrom this moment your website has begun being deployed by GitHub! You can check the status of the building process by **navigating to the \"Actions\" tab of your repository.**\n\n**Select the \"pages build and deployment workflow\"** in the list of workflows on the bottom righthand side of the page.\n\n\n\nThis **shows you GitHub's building and deployment process as a flowchart.** While it is working on each step there will be an **amber** circle next to the name of that sub-task. When a sub-task is completed, the **amber** circle becomes a **green** circle with a check mark.\n\n\n\nWhen the three steps are complete the **amber** clock symbol next to the \"pages build and deployment\" action will turn into a larger **green** circle with a check mark. This is GitHub's way of telling you that your website is live and accessible to anyone on the internet.\n\n\n\nYou can now visit your website by visiting its dedicated URL. **This URL can be found by returning to the \"Settings\" tab and then scrolling through the sidebar to the \"Pages\" section.**\n\nAlternately, the website for your repository always uses the following composition: *https://**repository owner**.github.io/**repository name**/*\n\n\n\nIf we visit that link, we can see that our website is live!\n\n\n\n#### GitHub Housekeeping\n\nWe recommend a quick housekeeping step now to make it easier to find this URL in the future. **Copy the URL from the Pages setting area and return to the \"Code\" tab of the repository**.\n\nOnce there, **click the small gear icon to the right of the \"About\" header.**\n\n\n\nIn the resulting window, **paste the copied URL into the \"Website\" field.** Once you've pasted it in, **click the** **green** **\"Save changes\" button.**\n\n

\n\n

\n\nThis places the link to your deployed website in an intuitive, easy-to-find location both for interested third parties and yourself in the future.\n\n\n\n\n\n### Adding Website Content\n\n\nNow that you have a live website you can build whatever you'd like! Given the wide range of possibility, we'll only cover how to add a new page but the same process applies to any edit to the living webpage.\n\nTo add a new page **create a new Quarto document.** You can do this by going to the \"File\" menu, entering the \"New File\" options, and selecting \"Quarto Document...\"\n\n

\n\n

\n\nSimilarly to an R markdown file, this will open a new window that lets you enter a title and author as well as decide what format you want to render files to along with some other settings options. **You only need to click the \"Create\" button** in the bottom right of this dialogue (though you can definitely play with the other options and text boxes as you desire).\n\n

\n\n

\n\nAfter a moment, a new .qmd file will open in Quarto's visual editor. **For the purposes of this tutorial, you only need to add a `title` in the top of the file** but for a real website you can add whatever content sparks joy for you!\n\n

\n\n

\n\n**Save that file into your project folder.** Its name can be anything but be sure that you remember what you name it!\n\n

\n\n

\n\n**Add the name of the new Quarto document to the .yml file** in the website navbar area (in this example the file is called \"more-stuff.qmd\").\n\n

\n\n

\n\nOnce you've added the file to the fundamental architecture of your website, you need to tell Quarto to re-build the part of the website that GitHub looks for when it deploys. To do this **run `quarto render` in the Terminal.**\n\nIf you want to *preview* your changes, run `quarto preview` in the Terminal and a new browser window will be displayed showing your current website content. This preview continues until you click the **red** stop sign icon in RStudio so be sure to end it when you're done with the preview!\n\n\n\nRegardless, once you've run either `quarto render` or `quarto preview` **you need to stage and commit all changed files indicated in the Git pane of RStudio**. As a reminder, to stage files you check the box next to them, to commit staged files, type an informative message and press the \"Commit\" button in the right side of the window.\n\n\n\nSwitch back to GitHub and you'll see an **amber** dot next to the commit hash just beneath and to the left of the **green** \"Code\" button.\n\n\n\nWhen the **amber** dot turns into a **green** check mark that means that your edits to your website are now included in the live version of your site!\n\n\n\nWhen you visit your website you may need to refresh the page for your edits to appear but all new visitors will see the updated content when they load the page.\n\n\n\n\n\n### Supplementary Information\n\nQuarto is developing at a rapid pace so quality of life changes and new functionalities are introduced relatively frequently. Additionally, Quarto supports user-created \"extensions\" that can be downloaded in a given project and then used (similar to the way user-developed R packages can be shared) so if you want to do something that Quarto itself doesn't support, chances are you'll be able to find an extension that handles it.\n\n[Quarto's documentation of website creation and formatting](https://quarto.org/docs/websites/) is extremely thorough and is a great resource as you become more comfortable with your new website. We hope this tutorial was useful to you and welcome constructively critical feedback! Please [post an issue](https://github.com/NCEAS/scicomptasks/issues) with any thoughts for improvement that you have.\n\n", + "markdown": "---\ntitle: \"Other Tutorials\"\n---\n\n\nSome of the content that we produce is not as detailed as our full workshops but has a wider scope than the content included in our [Coding Tips](https://lter.github.io/scicomp/best_practices.html) suggestions. This information can broadly be defined as \"tutorials\" though their depth and scope can vary significantly depending on the topic being tutorialized. As with our code tips, this page is under constant development so please [post an issue](https://github.com/lter/scicomp/issues) if you have an idea for a tutorial that you'd like to suggest that we create.\n\n## Storing User-Specific Information\n\nWorking groups sometimes need to handle user-specific information in their code. For example, if your group stores your data in the cloud (e.g., in Box, in Dropbox, etc.) each user will have a different \"absolute file path\" to the synced version of the data folder on their personal computer. Similarly, groups may find it valuable to use their email address in the code. While you _could_ simply have each group member add their information (file path, email, etc.) and comment out all but one of them when you work in that script, there is a better option: user-specific JSON files!\n\nThe main advantage of this method is that you and your group members do not have to manually change _any user-specific information_ in scripts just because a different person runs them!\n\n### Prerequisites\n\nTo follow along with this tutorial you will need to take the following steps:\n\n- Download [R](https://cran.r-project.org/)\n- Download [RStudio](https://posit.co/downloads/)\n- Install the `jsonlite` R package\n\nFeel free to skip any steps that you have already completed!\n\n### 1. Create the JSON\n\nFirst, you'll need to use RStudio to create your JSON file by creating a new text file (in the top left of RStudio click \"File\" {{< fa arrow-right >}} \"New File\" {{< fa arrow-right >}} \"Text File\"). In the new text file, add content that looks like this:\n\n::: {.cell}\n\n```{.r .cell-code}\n{\n \"email\":\"my_email@gmail.com\"\n \"dropbox_path\":\"path/to/dropbox-sync/for/me\"\n}\n```\n:::\n\nReplace the content on the _right_ of the colon with your actual information. If desired, you can add as many other pieces of user-specific information as you'd like! Simply follow the `\"info name\":\"info content\"` format and make sure that each piece of information is on its own line.\n\nOne small note here for when you work with your group: all group members need to use _exactly the same name_ to the left of each colon.\n\nYou'll see later when we show an example of this but you can think of the information on the left of the colon as comparable with a column name. It doesn't matter that the text in the \"rows\" will differ between users as long as the script has a consistent \"column\" in which to look for that text.\n\n### 2. Save the JSON with a Consistent Name\n\nThis may seem self-evident but all group members need to use the same file name for this new JSON file. We recommend `user.json` if you are undecided. This will let scripts that refer to the JSON use the same file name regardless of which user is running the code (same spirit as using consistent names for each piece of information in the file.)\n\n### 3. Tell Git to Ignore the JSON\n\nIf you're using version control for your project (which we strongly recommend!), you'll want Git to ignore the fact that this file differs for each user. Navigate to the `.gitignore` file of your project and put in the name of your JSON file as one of the files to ignore. We don't want to push the JSON to GitHub since each person's file will look different (that is our intent after all) and you wouldn't want to accidentally overwrite your teammate's user-specific information or cause a merge conflict.\n\nFor a deeper dive into the `.gitignore` check out [that module](https://nceas.github.io/scicomp-workshop-collaborative-coding/git_ignore.html) of our \"Collaborative Coding with GitHub\" workshop!\n\n### 4. Benefit from the JSON!\n\nIf you've made it through the preceding steps, you can now use the information you stored in the JSON file. You'll need to use the `jsonlite` R package to read in your file but once you've done that, you can access the information inside of it in classic R fashion.\n\nSee an example below:\n\n::: {.cell}\n\n```{.r .cell-code}\n# Load needed library\nlibrary(jsonlite)\n\n# Read in the JSON file\nuser_info <- jsonlite::read_json(\"user.json\")\n\n# Grab the file path out of it\ndropbox <- user_info$dropbox_path\n\n# Use it as you would any other file path\nmy_data <- read.csv(file = file.path(dropbox, \"2024_data.csv\"))\n```\n:::\n\nNow everyone in your group can use the same script because their personal file paths are readily accessible without needing to be hard-coded! The same theory applies to any other piece of information your group finds it valuable to store in the JSON.\n\n#### Help with Absolute File Paths\n\nIdentifying and manually writing out an absolute file path can be cumbersome so we've found a nice work-around (at least for Mac users) that you may find useful. First, in Finder, navigate to the last folder in the file path you'd like to preserve. In the row of folder names in the bottom of the Finder window, right-click the folder name and select \"Copy '\\' as Pathname\".\n\nOnce you've done that, you can simply paste the file path into your JSON file.\n\n

\n\n

\n\n\n\n## Using the `googledrive` R Package\n\nThe [`googledrive` R package](https://googledrive.tidyverse.org/) is a package that lets R users directly interact with files on GoogleDrive. This can be extremely useful because it lets all members of a team share the same source data file(s) and guarantees that updates to \"living\" documents are received by all group members the next time they run their R script. This package is technically part of the Tidyverse but is not loaded by running `library(tidyverse)`.\n\nBecause this package requires access to an R user's GoogleDrive, you must \"authenticate\" the `googledrive` package. This essentially tells Google that it is okay if an R package uses your credentials to access and (potentially) modify your Drive content. There are only a few steps to this process but follow along with the below tutorial and we'll get you ready to integrate the Google Drive into your code workflows using the `googledrive` package in no time!\n\n### Prerequisites\n\nTo follow along with this tutorial you will need to take the following steps:\n\n- Download [R](https://cran.r-project.org/)\n- Download [RStudio](https://posit.co/downloads/)\n- Create a Gmail account\n\nFeel free to skip any steps that you have already completed!\n\n### Authorize `googledrive`\n\n\nIn order to connect R with a GoogleDrive, we'll need to authorize `googledrive` to act on our behalf. This only needs to be done once (per computer) so follow along and you'll be building GoogleDrive into your workflows in no time!\n\nFirst, **install the `googledrive` and `httpuv` R packages**. The `googledrive` package's need is self-evident while the `httpuv` package makes the following steps a little easier than `googledrive` makes it alone. Be sure to load the `googledrive` package after you install it!\n\n::: {.cell}\n\n```{.r .cell-code}\n# Install packages\ninstall.packages(c(\"googledrive\", \"httpuv\"))\n\n# Load them\nlibrary(googledrive)\n```\n:::\n\nOnce you've installed the packages we can begin the authentication in R using the `drive_auth` function in the `googledrive` package.\n\n::: {.cell}\n\n```{.r .cell-code}\ngoogledrive::drive_auth(email = \"enter your gmail here!\")\n```\n:::\n\nIf this is your *first time* using `googledrive`, `drive_auth` will kick you to a new tab of your browser (see below for a screen grab of that screen) where you can pick which Gmail you'd like to connect to R.\n\n

\n\n

\n\n**Click the Gmail you want to use** and you will get a second screen where Google tells you that \"Tidyverse API\" wants access to your Google Account. This message is followed by three checkboxes, the first two are grayed out but the third is unchecked.\n\n

\n\n

\n\n:::callout-important\n### NOTE\nThis next bit is vitally important so *carefully* read and follow the next instruction!\n:::\n\nIn this screen, **you must check the unchecked box** to be able to use the `googledrive` R package. If you do not check this box all attempts to use `googledrive` functions will get an error that says \"insufficient permissions\".\n\n

\n\n

\n\nWhile granting access to \"see, edit, create, and \"delete\" all of your Google Drive files\" sounds like a significant security risk, those powers are actually why you're using the `googledrive` package in the first place! You want to be able to download existing Drive files, change them in R on your computer, and then put them back in Google Drive which is exactly what is meant by \"see, edit, create, and delete\".\n\nAlso, this power *only applies to the computer you're currently working on!* Granting access on your work computer allows **only** that computer to access your Drive files. So don't worry about giving access to your Drive to the whole world, that is protected by the same failsafes that you use when you let your computer remember a password to a website you frequent.\n\n*After* you've checked the authorization box, **scroll down and click the \"Continue\" button**.\n\n

\n\n

\n\nThis should result in a plain text page that tells you to close this window and return to R. If you see this message you are ready to use the `googledrive` package!\n\n

\n\n

\n\n\n\n### Problems with Authorization\n\nIf you have tried to use `drive_auth` and *did not* check the box indicated above, you need to make the `googledrive` package ask you again. Using `drive_auth` will not (annoyingly) return you to the place it sent you the first time. However, if you run the following code chunk it should give you another chance to check the needed box.\n\nThe [`gargle` R package](https://gargle.r-lib.org/) referenced below is required for interacting with Google Application Program Interfaces (APIs). This package does the heavy lifting of secure password and token management and is necessary for the `googledrive` authentication chunk below.\n\n::: {.cell}\n\n```{.r .cell-code}\ngoogledrive::drive_auth(\n email = gargle::gargle_oauth_email(),\n path = NULL,\n scopes = \"https://www.googleapis.com/auth/drive\",\n cache = gargle::gargle_oauth_cache(),\n use_oob = gargle::gargle_oob_default(),\n token = NULL)\n```\n:::\n\nUnfortunately, to use the `googledrive` package you *must* check the box that empowers the package to function as designed. If you're uncomfortable giving the `googledrive` that much power you will need to pivot your workflow away from using GoogleDrive directly. However, NCEAS does offer access to an [internal server called \"Aurora\"](https://lter.github.io/workshop-github/server.html) where data can be securely saved and shared among group members without special authentication like what `googledrive` requires. Reach out to our team if this seems like a more attractive option for your working group and we can offer training on how to use this powerful tool!\n\n### Find and Download Files\n\n\nNow that you've authorized the `googledrive` package, you can start downloading the Google Drive files you need through R! Let's say that you want to download a csv file from a folder or shared drive. You can save the URL of that folder/shared drive to a variable. \n\nThe `googledrive` package makes it straightforward to access Drive folders and files with the `as_id` function. This function allows the full link to a file or folder to serve as a direct connection to that file/folder. Most of the other `googledrive` functions will require a URL that is wrapped with `as_id` in this way. You would replace \"your url here\" with the actual link but make sure it is in quotation marks.\n\n::: {.cell}\n\n```{.r .cell-code}\ndrive_url <- googledrive::as_id(\"your url here\")\n```\n:::\n\nTo list all the contents of this folder, we can use the `drive_ls` function. You will get a dataframe-like object of the files back as the output. An example is shown below in the screenshot. Here, this Google Drive folder contains 4 csv files: `ingredients.csv`, `favorite_soups.csv`, `favorite_fruits.csv` and `favorite_desserts.csv`\n\n::: {.cell}\n\n```{.r .cell-code}\ndrive_folder <- googledrive::drive_ls(path = drive_url)\ndrive_folder\n```\n:::\n\n

\n\n

\n\nIf it has been a while since you've used `googledrive`, it will prompt you to refresh your token. Simply enter the number that corresponds to the correct Google Drive account.\n\n

\n\n

\n\nIf you only want to list files of a certain type, you can specify this in the `type` argument. And let's say that my folder contains a bunch of csv files, but I only want to download the one named \"favorite_desserts.csv\". In that case, I can also put a matching string in the `pattern` argument in order to filter down to 1 file.\n\n::: {.cell}\n\n```{.r .cell-code}\ndrive_folder <- googledrive::drive_ls(path = drive_url,\n type = \"csv\", \n pattern = \"favorite_desserts\")\ndrive_folder\n```\n:::\n\n

\n\n

\n\nOnce we've narrowed down to the file we want, we can download it using `drive_download`. This function takes the file identifier as an argument so we can access it using `drive_folder$id`.\n\n::: {.cell}\n\n```{.r .cell-code}\ngoogledrive::drive_download(file = drive_folder$id)\n```\n:::\n\nThis will automatically download the file to our working directory. If you want, you can specify a different path to download to. Just put the new file path into the `path` argument, replacing the \"your path here\", but keep the quotation marks.\n\n::: {.cell}\n\n```{.r .cell-code}\ngoogledrive::drive_download(file = drive_folder$id, \n path = \"your path here\")\n```\n:::\n\nIf you've downloaded the file before, and you want to overwrite it, there's a handy `overwrite` argument that you can set to `TRUE`. Note that the default is `FALSE`.\n\n::: {.cell}\n\n```{.r .cell-code}\ngoogledrive::drive_download(file = drive_folder$id, \n path = \"your path here\",\n overwrite = T)\n```\n:::\n\nIf there are multiple files in the Drive folder and you want to download them all, you can use a loop like so:\n\n::: {.cell}\n\n```{.r .cell-code}\n# For each file:\nfor(focal_file in drive_folder$name){\n \n # Find the file identifier for that file\n file_id <- subset(drive_folder, name == focal_file)\n\n # Download that file\n drive_download(file = file_id$id, \n path = \"your path here\",\n overwrite = T)\n}\n```\n:::\n\n\n\n\n\n## Building a Website with Quarto\n\n\n[Quarto](https://quarto.org/) is a new tool developed by RStudio (the company, not the program) to create a more 'what you see is what you get' editor for creating markdown files and products (e.g., books, websites, etc.). Additionally, it includes a visual editor that allows users to insert headings and embed figures via buttons that are intuitively labeled rather than through somewhat arcane HTML text or symbols. While Quarto is still in its infancy, it is rapidly gathering a following due to the aforementioned visual editor and for the ease with which quarto documents and websites can be created.\n\n### Prerequisites\n\nTo follow along with this tutorial you will need to take the following steps:\n\n- Do all of the [pre-workshop steps](https://lter.github.io/workshop-github/#workshop-preparation) relevant to our \"Collaborative Coding with GitHub\" workshop\n- [Download Quarto](https://quarto.org/docs/get-started/)\n\nFeel free to skip any steps that you have already completed!\n\n### Create a Quarto Website R Project\n\nTo begin, **click the \"Project\" button** in the top right of your RStudio session.\n\n\n\nIn the resulting dialogue, **click the \"New Directory\" option.**\n\n

\n\n

\n\nFrom the list of options for project templates, **select \"Quarto Website\".**\n\n

\n\n

\n\n**Pick a title** and **check the \"Create a git repository\" checkbox.** For your title, short but descriptive titles are most effective. Once that is done, click **\"Create Project\"** in the bottom right of the window.\n\n

\n\n

\n\nAfter a few seconds, RStudio should refresh with a Quarto document (such documents have the file extension \".qmd\") and a \"_quarto.yml\" file open.\n\n

\n\n

\n\nPart of Quarto's central philosophy is that all of the formatting of individual .qmd files in a project is governed by the settings created by a singular .yml file. In an R markdown project some of the global settings are set in .yml but other settings are handled within each .Rmd file. This centralization is a key innovation in streamlining projects and is one reason for Quarto's quick popularity.\n\n\n\n### Preparing Project for Web Deployment\n\n\nTo prepare your project for web deployment via GitHub Pages, we have **three** quick steps that we must first complete.\n\n*First*, in the \"_quarto.yml\" file, **add `output-dir: docs` as a subheading beneath the `project:` heading.** Make sure that the indentation is the same as the `type: website` but the new line can be either above or below that line.\n\n

\n\n

\n\n*Second*, **in the \"Terminal\" pane run `touch .nojekyll`.** This creates a file called \".nojekyll\" that is necessary for hosting your website via GitHub Pages. \n\n*Third*, **in the \"Terminal\" pane run `quarto render`.** This processes the template .qmd files you currently have in the repository and prepares them to become actual web pages.\n\nOnce you've done these three things you can move on to creating a GitHub repository so that we can take the necessary steps to having GitHub host your website!\n\n\n\n### Make a New GitHub Repository\n\n\nFrom your GitHub **\"Repositories\"** tab, click the ** green \"New\"** button.\n\n\n\n**Add a title** to your repository and **add a description.** Once you've added these two things, scroll down and click the ** green \"Create repository\" button.**\n\n

\n\n

\nBe sure that you **do not add a README**, **do not add a gitignore**, and **do not add a license.** Adding any of these three will cause a merge conflict when we link the project that you just created with the GitHub repository that you are in the process of creating.\n\n

\n\n

\n\nAfter a few seconds you should be placed on your new repository's landing page which will look like the below image because there isn't anything in your repository (yet).\n\nCopy the link in the field and go back to your RStudio session.\n\n

\n\n

\n\n\n\n### Adding your Project to GitHub\n\n\nThe following steps include a sequence of command line operations that will be relayed in code chunks below. **Unless otherwise stated, all of the following code should be run in \"Terminal\".**\n\nIf you didn't check the \"Create a git repository\" button while creating the R project, you'll need to do that via the command line now. **If you did check that box, you should skip this step!**\n\n::: {.cell}\n\n```{.r .cell-code}\n# Start a git repository on the \"main\" branch\ngit init -b main\n```\n:::\n\n**Stage all of the files in your project to the git repository.** This includes the .yml file, all .qmd files and all of their rendered versions created when you ran `quarto render` earlier. This code is equivalent to checking the box for the files in the \"Git\" pane of RStudio.\n\n::: {.cell}\n\n```{.r .cell-code}\n# Stage all files\ngit add .\n```\n:::\n\nOnce everything has been staged, **you now must commit those staged files** with a message.\n\n::: {.cell}\n\n```{.r .cell-code}\n# Commit all files with the message in quotes\ngit commit -m \"Initial commit\"\n```\n:::\n\nNow that your project files have been committed, you need to **tell your computer where you will be pushing to and pulling from.** Paste the link you copied at the end of the \"Make a New GitHub Repository\" into the code shown in the chunk below (instead of `GITHUB_URL`) and run it.\n\n::: {.cell}\n\n```{.r .cell-code}\n# Tell your computer which GitHub repository to connect to\ngit remote add origin GITHUB_URL\n```\n:::\n\n**Verify that URL** before continuing.\n\n::: {.cell}\n\n```{.r .cell-code}\n# Confirm that URL worked\ngit remote -v\n```\n:::\n\nFinally, **push your commited changes** to the repostory that you set as the remote in the preceding two steps.\n\n::: {.cell}\n\n```{.r .cell-code}\n# Push all of the content to the main branch\ngit push -u origin main\n```\n:::\n\nNow, **go back to GitHub** and refresh the page to see your project content safe and sound in your new GitHub repository!\n\n\n\n\n\n### Deploy Website via GitHub\n\n\nIn order to get your new website actually on the web, we'll need to tell GitHub that we want our website to be accessible at a .github.io URL.\n\nTo do this, **go to the \"Settings\" tab** with a gear icon and click it. You may be prompted to re-enter your GitHub password, do so and you can proceed.\n\n\n\nIn the resulting page, look towards the bottom of the left sidebar of settings categories and **click the \"Pages\" option.** This is at the very bottom of the sidebar in the screen capture below but is towards the middle of all of the settings categories Github offers you.\n\n\n\nScroll down to the middle of this page and where it says \"Branch\" **click the dropdown menu that says \"None\" by default.**\n\n\n\n**Select \"main\"** from the dropdown.\n\n

\n\n

\n\nThis opens up a new dropdown menu where you can select which folder in your repository contains your website's content (it defaults to \"/ (root)\"). Because we specified `output-dir: docs` in the .yml file earlier we can **select \"/docs\" from the dropdown menu.**\n\n

\n\n

\n\nOnce you've told GitHub that you want a website generated from the \"docs\" folder on the main branch, **click the \"Save\" button.**\n\n

\n\n

\n\nFrom this moment your website has begun being deployed by GitHub! You can check the status of the building process by **navigating to the \"Actions\" tab of your repository.**\n\n**Select the \"pages build and deployment workflow\"** in the list of workflows on the bottom righthand side of the page.\n\n\n\nThis **shows you GitHub's building and deployment process as a flowchart.** While it is working on each step there will be an **amber** circle next to the name of that sub-task. When a sub-task is completed, the **amber** circle becomes a **green** circle with a check mark.\n\n\n\nWhen the three steps are complete the **amber** clock symbol next to the \"pages build and deployment\" action will turn into a larger **green** circle with a check mark. This is GitHub's way of telling you that your website is live and accessible to anyone on the internet.\n\n\n\nYou can now visit your website by visiting its dedicated URL. **This URL can be found by returning to the \"Settings\" tab and then scrolling through the sidebar to the \"Pages\" section.**\n\nAlternately, the website for your repository always uses the following composition: *https://**repository owner**.github.io/**repository name**/*\n\n\n\nIf we visit that link, we can see that our website is live!\n\n\n\n#### GitHub Housekeeping\n\nWe recommend a quick housekeeping step now to make it easier to find this URL in the future. **Copy the URL from the Pages setting area and return to the \"Code\" tab of the repository**.\n\nOnce there, **click the small gear icon to the right of the \"About\" header.**\n\n\n\nIn the resulting window, **paste the copied URL into the \"Website\" field.** Once you've pasted it in, **click the** **green** **\"Save changes\" button.**\n\n

\n\n

\n\nThis places the link to your deployed website in an intuitive, easy-to-find location both for interested third parties and yourself in the future.\n\n\n\n\n\n### Adding Website Content\n\n\nNow that you have a live website you can build whatever you'd like! Given the wide range of possibility, we'll only cover how to add a new page but the same process applies to any edit to the living webpage.\n\nTo add a new page **create a new Quarto document.** You can do this by going to the \"File\" menu, entering the \"New File\" options, and selecting \"Quarto Document...\"\n\n

\n\n

\n\nSimilarly to an R markdown file, this will open a new window that lets you enter a title and author as well as decide what format you want to render files to along with some other settings options. **You only need to click the \"Create\" button** in the bottom right of this dialogue (though you can definitely play with the other options and text boxes as you desire).\n\n

\n\n

\n\nAfter a moment, a new .qmd file will open in Quarto's visual editor. **For the purposes of this tutorial, you only need to add a `title` in the top of the file** but for a real website you can add whatever content sparks joy for you!\n\n

\n\n

\n\n**Save that file into your project folder.** Its name can be anything but be sure that you remember what you name it!\n\n

\n\n

\n\n**Add the name of the new Quarto document to the .yml file** in the website navbar area (in this example the file is called \"more-stuff.qmd\").\n\n

\n\n

\n\nOnce you've added the file to the fundamental architecture of your website, you need to tell Quarto to re-build the part of the website that GitHub looks for when it deploys. To do this **run `quarto render` in the Terminal.**\n\nIf you want to *preview* your changes, run `quarto preview` in the Terminal and a new browser window will be displayed showing your current website content. This preview continues until you click the **red** stop sign icon in RStudio so be sure to end it when you're done with the preview!\n\n\n\nRegardless, once you've run either `quarto render` or `quarto preview` **you need to stage and commit all changed files indicated in the Git pane of RStudio**. As a reminder, to stage files you check the box next to them, to commit staged files, type an informative message and press the \"Commit\" button in the right side of the window.\n\n\n\nSwitch back to GitHub and you'll see an **amber** dot next to the commit hash just beneath and to the left of the **green** \"Code\" button.\n\n\n\nWhen the **amber** dot turns into a **green** check mark that means that your edits to your website are now included in the live version of your site!\n\n\n\nWhen you visit your website you may need to refresh the page for your edits to appear but all new visitors will see the updated content when they load the page.\n\n\n\n\n\n### Supplementary Information\n\nQuarto is developing at a rapid pace so quality of life changes and new functionalities are introduced relatively frequently. Additionally, Quarto supports user-created \"extensions\" that can be downloaded in a given project and then used (similar to the way user-developed R packages can be shared) so if you want to do something that Quarto itself doesn't support, chances are you'll be able to find an extension that handles it.\n\n[Quarto's documentation of website creation and formatting](https://quarto.org/docs/websites/) is extremely thorough and is a great resource as you become more comfortable with your new website. We hope this tutorial was useful to you and welcome constructively critical feedback! Please [post an issue](https://github.com/NCEAS/scicomptasks/issues) with any thoughts for improvement that you have.\n\n", "supporting": [], "filters": [ "rmarkdown/pagebreak.lua" diff --git a/tutorial-scaffold_googledrive-auth.qmd b/tutorial-scaffold_googledrive-auth.qmd index 0713d2b..fd6bb53 100644 --- a/tutorial-scaffold_googledrive-auth.qmd +++ b/tutorial-scaffold_googledrive-auth.qmd @@ -32,7 +32,7 @@ googledrive::drive_auth( token = NULL) ``` -Unfortunately, to use the `googledrive` package you *must* check the box that empowers the package to function as designed. If you're uncomfortable giving the `googledrive` that much power you will need to pivot your workflow away from using GoogleDrive directly. However, NCEAS does offer access to an [internal server called "Aurora"](https://nceas.github.io/scicomp-workshop-collaborative-coding/server.html) where data can be securely saved and shared among group members without special authentication like what `googledrive` requires. Reach out to our team if this seems like a more attractive option for your working group and we can offer training on how to use this powerful tool! +Unfortunately, to use the `googledrive` package you *must* check the box that empowers the package to function as designed. If you're uncomfortable giving the `googledrive` that much power you will need to pivot your workflow away from using GoogleDrive directly. However, NCEAS does offer access to an [internal server called "Aurora"](https://lter.github.io/workshop-github/server.html) where data can be securely saved and shared among group members without special authentication like what `googledrive` requires. Reach out to our team if this seems like a more attractive option for your working group and we can offer training on how to use this powerful tool! ### Find and Download Files diff --git a/tutorial-scaffold_quarto-website.qmd b/tutorial-scaffold_quarto-website.qmd index 57bdcc6..8b47aac 100644 --- a/tutorial-scaffold_quarto-website.qmd +++ b/tutorial-scaffold_quarto-website.qmd @@ -5,7 +5,7 @@ To follow along with this tutorial you will need to take the following steps: -- Do all of the [pre-workshop steps](https://nceas.github.io/scicomp-workshop-collaborative-coding/#workshop-preparation) relevant to our "Collaborative Coding with GitHub" workshop +- Do all of the [pre-workshop steps](https://lter.github.io/workshop-github/#workshop-preparation) relevant to our "Collaborative Coding with GitHub" workshop - [Download Quarto](https://quarto.org/docs/get-started/) Feel free to skip any steps that you have already completed! diff --git a/tutorials.qmd b/tutorials.qmd index 607130f..6d82c1d 100644 --- a/tutorials.qmd +++ b/tutorials.qmd @@ -2,7 +2,7 @@ title: "Other Tutorials" --- -Some of the content that we produce is not as detailed as our full workshops but has a wider scope than the content included in our [Coding Tips](https://nceas.github.io/scicomp.github.io/best_practices.html) suggestions. This information can broadly be defined as "tutorials" though their depth and scope can vary significantly depending on the topic being tutorialized. As with our [Coding Tips](https://nceas.github.io/scicomp.github.io/best_practices.html), this page is under constant development so please [post an issue](https://github.com/NCEAS/scicomp.github.io/issues) if you have an idea for a tutorial that you'd like to suggest that we create. +Some of the content that we produce is not as detailed as our full workshops but has a wider scope than the content included in our [Coding Tips](https://lter.github.io/scicomp/best_practices.html) suggestions. This information can broadly be defined as "tutorials" though their depth and scope can vary significantly depending on the topic being tutorialized. As with our code tips, this page is under constant development so please [post an issue](https://github.com/lter/scicomp/issues) if you have an idea for a tutorial that you'd like to suggest that we create. ## Storing User-Specific Information diff --git a/workshops.qmd b/workshops.qmd index e2c8eba..bae2f92 100644 --- a/workshops.qmd +++ b/workshops.qmd @@ -6,29 +6,29 @@ In addition to the specific task-based support we offer, we can also create and ## Collaborative Coding with GitHub -### [Workshop Website](https://nceas.github.io/scicomp-workshop-collaborative-coding/) +### [Workshop Website](https://lter.github.io/workshop-github/) - +GitHub logo In synthesis science, collaboration on code products is often integral to the productivity of the group. However, learning to use the software and graphical user interfaces that support this kind of teamwork can be a significant hurdle for teams that are already experts in their subject areas. This workshop is aimed at helping participants gain an understanding of the fundamental purpose and functioning of "version control" systems--specifically [GitHub](https://github.com/)--to help teams more effectively code collaboratively. -The GitHub {{< fa brands github >}} repository for the workshop can be found [here](https://github.com/NCEAS/scicomp-workshop-collaborative-coding). +The GitHub {{< fa brands github >}} repository for the workshop can be found [here](https://github.com/lter/workshop-github). -## Coding in the `tidyverse` +## Coding in the Tidyverse -### [Workshop Website](https://nceas.github.io/scicomp-workshop-tidyverse/) +### [Workshop Website](https://lter.github.io/workshop-tidyverse/) - +Hex logo for the 'tidyverse' R package -For teams that code using the R programming language, the most familiar tools are often part of "base R" meaning that those functions and packages come pre-loaded when R is installed. Relatively recently the `tidyverse` has emerged as a comprehensive suite of packages that can complement base R or serve as an alternative for some tasks. This includes packages like `dplyr` and `tidyr` as well as the perhaps infamous pipe operator (`%>%`) among many other tools. This workshop is aimed at helping participants use the `tidyverse` equivalents of fundamental data wrangling tasks that learners may be used to performing with base R. +For teams that code using the R programming language, the most familiar tools are often part of "base R" meaning that those functions and packages come pre-loaded when R is installed. Relatively recently the Tidyverse has emerged as a comprehensive suite of packages that can complement base R or serve as an alternative for some tasks. This includes packages like `dplyr` and `tidyr` as well as the perhaps infamous pipe operator (`%>%`) among many other tools. This workshop is aimed at helping participants use the Tidyverse equivalents of fundamental data wrangling tasks that learners may be used to performing with base R. -The GitHub {{< fa brands github >}} repository for the workshop can be found [here](https://github.com/NCEAS/scicomp-workshop-tidyverse). +The GitHub {{< fa brands github >}} repository for the workshop can be found [here](https://github.com/lter/workshop-tidyverse). ## R Shiny Apps for Sharing Science ### [Workshop Website](https://njlyon0.github.io/asm-2022_shiny-workshop/) - +Hex logo for the 'shiny' R package One of our team members--Nick Lyon--created a workshop on learning to create R Shiny apps. R Shiny includes a suite of R packages (primarily `shiny`) that allow R users to create interactive apps that can be subsequently deployed to a URL. These apps are most commonly used for data visualization purposes but can also be a neat way of accomplishing other outward-facing tasks without needing to learn a new programming language. This workshop was offered at the 2022 LTER All Scientists' Meeting (ASM) and is aimed at an audience with moderate R capability but limited prior exposure to Shiny. @@ -42,13 +42,13 @@ This workshop also includes a second GitHub {{< fa brands github >}} repository ### [Training Catalog](https://learning.nceas.ucsb.edu/) - +NCEAS logo In addition to the workshops described above, NCEAS offers a variety of other workshops and trainings that may be of interest to you or your group via the [Learning Hub](https://www.nceas.ucsb.edu/learning-hub). While these trainings can be very helpful, it is *important to note that our team may or may not be involved with teaching them.* Also, workshops we create will be hosted on this website rather than on the Learning Hub. ### The Carpentries - +Logo for 'The Carpentries' [The Carpentries](https://carpentries.org/) is another great place to find workshops and tutorials on various data and programming topics. All of their materials are publicly available so even if a workshop isn't being offered, you can visit that site and review the content at your own pace! This can be a nice way of refreshing yourself on the fundamentals of something you have prior experience with or teaching yourself something totally new! For example, the Carpentries include helpful workshops on [using R for ecologists](https://datacarpentry.org/R-ecology-lesson/), [using the "shell" or command line](https://swcarpentry.github.io/shell-novice/), or [handling geospatial data in R](https://datacarpentry.org/r-intro-geospatial/).