From 0fce97265efc683fd4aef849a44d671d01aec512 Mon Sep 17 00:00:00 2001 From: njlyon0 Date: Wed, 1 May 2024 14:49:44 -0400 Subject: [PATCH 01/11] Moving JSON tutorial before `googledrive` tutorial --- _freeze/tutorials/execute-results/html.json | 5 +++-- tutorials.qmd | 8 ++++---- 2 files changed, 7 insertions(+), 6 deletions(-) diff --git a/_freeze/tutorials/execute-results/html.json b/_freeze/tutorials/execute-results/html.json index c4b3f4b..b8eb452 100644 --- a/_freeze/tutorials/execute-results/html.json +++ b/_freeze/tutorials/execute-results/html.json @@ -1,7 +1,8 @@ { - "hash": "2be9084b05279a8d579ff2c4502a2bb4", + "hash": "1ccc12cb61d1f42398fe45eaffc8897b", "result": { - "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## 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\n- [Download RStudio](https://www.rstudio.com/products/rstudio/download/)\n\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## Using the `jsonlite` R Package\n\nThe above section shows how R users can access their data stored on Google Drive, but how about other types of cloud storage like Box or Dropbox? If your data or your team's data is synced to the cloud through those tools, we recommend that all group members store relevant file paths in their own respective JSON file. Then everyone can read those file paths using the [`jsonlite` R package](https://cran.r-project.org/web/packages/jsonlite/index.html)! \n\nThe main advantage of this method is that you and your group members do not have to manually change the file paths in each script whenever a different person runs it!\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\n- [Download RStudio](https://www.rstudio.com/products/rstudio/download/)\n\n- Make sure you have access to your cloud storage files on your local machine\n\nFeel free to skip any steps that you have already completed!\n\n### Copy the desired file paths\n\nFirst, navigate to the folder(s) that contain the files that you and your team most frequently need to access. Copy the absolute path to each needed folder. On Mac, you can right-click and then \"Copy ... as Pathname\" (see below).\n\n

\n\n

\n\nIf you have multiple paths, feel free to paste them into an empty text file for now.\n\n### Create the JSON file\n\nOnce you have the absolute file paths, open RStudio to the main working directory for your project. At the top left corner, click on File -> New File -> Text File. \n\nType the following lines into the file, except replace `YOUR_ABSOLUTE_PATH` with your path. Keep the quotation marks around the path. \n\n::: {.cell}\n\n```{.r .cell-code}\n{\n\"data_path\":\"YOUR_ABSOLUTE_PATH\"\n}\n```\n:::\n\nYou can customize the name of this path but make sure everyone in your team have the same name(s)! For example, if `data_path` refers to the folder containing all of the data for the group, then everyone should have a `data_path` in their own respective JSON file pointing to the same data folder. The absolute file path will be unique for each person, though. \n\nIf you have multiple paths, you can save them like so:\n\n::: {.cell}\n\n```{.r .cell-code}\n{\n\"raw_data_path\":\"YOUR_ABSOLUTE_PATH\",\n\"tidy_data_path\":\"YOUR_ABSOLUTE_PATH\"\n}\n```\n:::\n\nSave this file as `paths.json` in your main working directory. \n\n### Put the JSON file in `gitignore`\n\nNavigate to the `gitignore` file of your project and list `paths.json` as one of the files to ignore. We don't want to push this file to GitHub since everyone's own `paths.json` will look different and you wouldn't want to accidentally overwrite your teammate's custom absolute path!\n\n### Install `jsonlite`\n\nIf you don't have `jsonlite` already, install it with:\n\n::: {.cell}\n\n```{.r .cell-code}\ninstall.packages(\"jsonlite\")\n```\n:::\n\n### Access your files in cloud storage\n\nNow whenever you want to access the files for your group, you can load `jsonlite` and run its `read_json()` function. If your path was not saved as `data_path` then in the code below, make sure to replace `data_path` with the actual name.\n\n::: {.cell}\n\n```{.r .cell-code}\n# Load jsonlite\nlibrary(\"jsonlite\")\n\n# Get the path to your files\npath_to_data <- jsonlite::read_json(\"paths.json\")$data_path\n```\n:::\n\nAnd `path_to_data` will contain the path to the folder where all your relevant files live! \n\nIf you combine this path with the [`file.path()` function](https://nceas.github.io/scicomp.github.io/best_practices.html#preserve-file-paths-as-objects-using-file.path) then you'll have a powerful, flexible tool for managing file paths!\n\nFor example, if `example.csv` lives in the folder that `path_to_data` points to, then you **and your team members** can read `example.csv` like so:\n\n::: {.cell}\n\n```{.r .cell-code}\n# Read the csv reproducibly\nexample <- read.csv(file = file.path(path_to_data, \"example.csv\"))\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- [Download R](https://cran.r-project.org/)\n\n- [Download RStudio](https://www.rstudio.com/products/rstudio/download/)\n\n- [Download Quarto](https://quarto.org/docs/get-started/)\n\n- [Install `git`](https://happygitwithr.com/install-git.html)\n\n- [Create a GitHub Account](https://github.com/)\n\n- [Connect `git` to GitHub](https://njlyon0.github.io/asm-2022_github-workshop/setup.html#connecting-programs)\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", + "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## Using the `jsonlite` R Package\n\nThe above section shows how R users can access their data stored on Google Drive, but how about other types of cloud storage like Box or Dropbox? If your data or your team's data is synced to the cloud through those tools, we recommend that all group members store relevant file paths in their own respective JSON file. Then everyone can read those file paths using the [`jsonlite` R package](https://cran.r-project.org/web/packages/jsonlite/index.html)! \n\nThe main advantage of this method is that you and your group members do not have to manually change the file paths in each script whenever a different person runs it!\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\n- [Download RStudio](https://www.rstudio.com/products/rstudio/download/)\n\n- Make sure you have access to your cloud storage files on your local machine\n\nFeel free to skip any steps that you have already completed!\n\n### Copy the desired file paths\n\nFirst, navigate to the folder(s) that contain the files that you and your team most frequently need to access. Copy the absolute path to each needed folder. On Mac, you can right-click and then \"Copy ... as Pathname\" (see below).\n\n

\n\n

\n\nIf you have multiple paths, feel free to paste them into an empty text file for now.\n\n### Create the JSON file\n\nOnce you have the absolute file paths, open RStudio to the main working directory for your project. At the top left corner, click on File -> New File -> Text File. \n\nType the following lines into the file, except replace `YOUR_ABSOLUTE_PATH` with your path. Keep the quotation marks around the path. \n\n::: {.cell}\n\n```{.r .cell-code}\n{\n\"data_path\":\"YOUR_ABSOLUTE_PATH\"\n}\n```\n:::\n\nYou can customize the name of this path but make sure everyone in your team have the same name(s)! For example, if `data_path` refers to the folder containing all of the data for the group, then everyone should have a `data_path` in their own respective JSON file pointing to the same data folder. The absolute file path will be unique for each person, though. \n\nIf you have multiple paths, you can save them like so:\n\n::: {.cell}\n\n```{.r .cell-code}\n{\n\"raw_data_path\":\"YOUR_ABSOLUTE_PATH\",\n\"tidy_data_path\":\"YOUR_ABSOLUTE_PATH\"\n}\n```\n:::\n\nSave this file as `paths.json` in your main working directory. \n\n### Put the JSON file in `gitignore`\n\nNavigate to the `gitignore` file of your project and list `paths.json` as one of the files to ignore. We don't want to push this file to GitHub since everyone's own `paths.json` will look different and you wouldn't want to accidentally overwrite your teammate's custom absolute path!\n\n### Install `jsonlite`\n\nIf you don't have `jsonlite` already, install it with:\n\n::: {.cell}\n\n```{.r .cell-code}\ninstall.packages(\"jsonlite\")\n```\n:::\n\n### Access your files in cloud storage\n\nNow whenever you want to access the files for your group, you can load `jsonlite` and run its `read_json()` function. If your path was not saved as `data_path` then in the code below, make sure to replace `data_path` with the actual name.\n\n::: {.cell}\n\n```{.r .cell-code}\n# Load jsonlite\nlibrary(\"jsonlite\")\n\n# Get the path to your files\npath_to_data <- jsonlite::read_json(\"paths.json\")$data_path\n```\n:::\n\nAnd `path_to_data` will contain the path to the folder where all your relevant files live! \n\nIf you combine this path with the [`file.path()` function](https://nceas.github.io/scicomp.github.io/best_practices.html#preserve-file-paths-as-objects-using-file.path) then you'll have a powerful, flexible tool for managing file paths!\n\nFor example, if `example.csv` lives in the folder that `path_to_data` points to, then you **and your team members** can read `example.csv` like so:\n\n::: {.cell}\n\n```{.r .cell-code}\n# Read the csv reproducibly\nexample <- read.csv(file = file.path(path_to_data, \"example.csv\"))\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\n- [Download RStudio](https://www.rstudio.com/products/rstudio/download/)\n\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- [Download R](https://cran.r-project.org/)\n\n- [Download RStudio](https://www.rstudio.com/products/rstudio/download/)\n\n- [Download Quarto](https://quarto.org/docs/get-started/)\n\n- [Install `git`](https://happygitwithr.com/install-git.html)\n\n- [Create a GitHub Account](https://github.com/)\n\n- [Connect `git` to GitHub](https://njlyon0.github.io/asm-2022_github-workshop/setup.html#connecting-programs)\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/tutorials.qmd b/tutorials.qmd index b62872c..ac94d9a 100644 --- a/tutorials.qmd +++ b/tutorials.qmd @@ -4,14 +4,14 @@ 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. -## Using the `googledrive` R Package - -{{< include /tutorial-scaffold_googledrive-auth.qmd >}} - ## Using the `jsonlite` R Package {{< include /tutorial-scaffold_jsonlite.qmd >}} +## Using the `googledrive` R Package + +{{< include /tutorial-scaffold_googledrive-auth.qmd >}} + ## Building a Website with Quarto {{< include /tutorial-scaffold_quarto-website.qmd >}} From 2ff3b8b3ca20b1ac1e0b0e6157b34d737d5fd31c Mon Sep 17 00:00:00 2001 From: njlyon0 Date: Wed, 1 May 2024 14:51:38 -0400 Subject: [PATCH 02/11] Renamed JSON tutorial heading --- _freeze/tutorials/execute-results/html.json | 4 ++-- tutorials.qmd | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/_freeze/tutorials/execute-results/html.json b/_freeze/tutorials/execute-results/html.json index b8eb452..cd854da 100644 --- a/_freeze/tutorials/execute-results/html.json +++ b/_freeze/tutorials/execute-results/html.json @@ -1,8 +1,8 @@ { - "hash": "1ccc12cb61d1f42398fe45eaffc8897b", + "hash": "1d34c38c70c714dd3fece0c9644af8ca", "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## Using the `jsonlite` R Package\n\nThe above section shows how R users can access their data stored on Google Drive, but how about other types of cloud storage like Box or Dropbox? If your data or your team's data is synced to the cloud through those tools, we recommend that all group members store relevant file paths in their own respective JSON file. Then everyone can read those file paths using the [`jsonlite` R package](https://cran.r-project.org/web/packages/jsonlite/index.html)! \n\nThe main advantage of this method is that you and your group members do not have to manually change the file paths in each script whenever a different person runs it!\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\n- [Download RStudio](https://www.rstudio.com/products/rstudio/download/)\n\n- Make sure you have access to your cloud storage files on your local machine\n\nFeel free to skip any steps that you have already completed!\n\n### Copy the desired file paths\n\nFirst, navigate to the folder(s) that contain the files that you and your team most frequently need to access. Copy the absolute path to each needed folder. On Mac, you can right-click and then \"Copy ... as Pathname\" (see below).\n\n

\n\n

\n\nIf you have multiple paths, feel free to paste them into an empty text file for now.\n\n### Create the JSON file\n\nOnce you have the absolute file paths, open RStudio to the main working directory for your project. At the top left corner, click on File -> New File -> Text File. \n\nType the following lines into the file, except replace `YOUR_ABSOLUTE_PATH` with your path. Keep the quotation marks around the path. \n\n::: {.cell}\n\n```{.r .cell-code}\n{\n\"data_path\":\"YOUR_ABSOLUTE_PATH\"\n}\n```\n:::\n\nYou can customize the name of this path but make sure everyone in your team have the same name(s)! For example, if `data_path` refers to the folder containing all of the data for the group, then everyone should have a `data_path` in their own respective JSON file pointing to the same data folder. The absolute file path will be unique for each person, though. \n\nIf you have multiple paths, you can save them like so:\n\n::: {.cell}\n\n```{.r .cell-code}\n{\n\"raw_data_path\":\"YOUR_ABSOLUTE_PATH\",\n\"tidy_data_path\":\"YOUR_ABSOLUTE_PATH\"\n}\n```\n:::\n\nSave this file as `paths.json` in your main working directory. \n\n### Put the JSON file in `gitignore`\n\nNavigate to the `gitignore` file of your project and list `paths.json` as one of the files to ignore. We don't want to push this file to GitHub since everyone's own `paths.json` will look different and you wouldn't want to accidentally overwrite your teammate's custom absolute path!\n\n### Install `jsonlite`\n\nIf you don't have `jsonlite` already, install it with:\n\n::: {.cell}\n\n```{.r .cell-code}\ninstall.packages(\"jsonlite\")\n```\n:::\n\n### Access your files in cloud storage\n\nNow whenever you want to access the files for your group, you can load `jsonlite` and run its `read_json()` function. If your path was not saved as `data_path` then in the code below, make sure to replace `data_path` with the actual name.\n\n::: {.cell}\n\n```{.r .cell-code}\n# Load jsonlite\nlibrary(\"jsonlite\")\n\n# Get the path to your files\npath_to_data <- jsonlite::read_json(\"paths.json\")$data_path\n```\n:::\n\nAnd `path_to_data` will contain the path to the folder where all your relevant files live! \n\nIf you combine this path with the [`file.path()` function](https://nceas.github.io/scicomp.github.io/best_practices.html#preserve-file-paths-as-objects-using-file.path) then you'll have a powerful, flexible tool for managing file paths!\n\nFor example, if `example.csv` lives in the folder that `path_to_data` points to, then you **and your team members** can read `example.csv` like so:\n\n::: {.cell}\n\n```{.r .cell-code}\n# Read the csv reproducibly\nexample <- read.csv(file = file.path(path_to_data, \"example.csv\"))\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\n- [Download RStudio](https://www.rstudio.com/products/rstudio/download/)\n\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- [Download R](https://cran.r-project.org/)\n\n- [Download RStudio](https://www.rstudio.com/products/rstudio/download/)\n\n- [Download Quarto](https://quarto.org/docs/get-started/)\n\n- [Install `git`](https://happygitwithr.com/install-git.html)\n\n- [Create a GitHub Account](https://github.com/)\n\n- [Connect `git` to GitHub](https://njlyon0.github.io/asm-2022_github-workshop/setup.html#connecting-programs)\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://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\nThe above section shows how R users can access their data stored on Google Drive, but how about other types of cloud storage like Box or Dropbox? If your data or your team's data is synced to the cloud through those tools, we recommend that all group members store relevant file paths in their own respective JSON file. Then everyone can read those file paths using the [`jsonlite` R package](https://cran.r-project.org/web/packages/jsonlite/index.html)! \n\nThe main advantage of this method is that you and your group members do not have to manually change the file paths in each script whenever a different person runs it!\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\n- [Download RStudio](https://www.rstudio.com/products/rstudio/download/)\n\n- Make sure you have access to your cloud storage files on your local machine\n\nFeel free to skip any steps that you have already completed!\n\n### Copy the desired file paths\n\nFirst, navigate to the folder(s) that contain the files that you and your team most frequently need to access. Copy the absolute path to each needed folder. On Mac, you can right-click and then \"Copy ... as Pathname\" (see below).\n\n

\n\n

\n\nIf you have multiple paths, feel free to paste them into an empty text file for now.\n\n### Create the JSON file\n\nOnce you have the absolute file paths, open RStudio to the main working directory for your project. At the top left corner, click on File -> New File -> Text File. \n\nType the following lines into the file, except replace `YOUR_ABSOLUTE_PATH` with your path. Keep the quotation marks around the path. \n\n::: {.cell}\n\n```{.r .cell-code}\n{\n\"data_path\":\"YOUR_ABSOLUTE_PATH\"\n}\n```\n:::\n\nYou can customize the name of this path but make sure everyone in your team have the same name(s)! For example, if `data_path` refers to the folder containing all of the data for the group, then everyone should have a `data_path` in their own respective JSON file pointing to the same data folder. The absolute file path will be unique for each person, though. \n\nIf you have multiple paths, you can save them like so:\n\n::: {.cell}\n\n```{.r .cell-code}\n{\n\"raw_data_path\":\"YOUR_ABSOLUTE_PATH\",\n\"tidy_data_path\":\"YOUR_ABSOLUTE_PATH\"\n}\n```\n:::\n\nSave this file as `paths.json` in your main working directory. \n\n### Put the JSON file in `gitignore`\n\nNavigate to the `gitignore` file of your project and list `paths.json` as one of the files to ignore. We don't want to push this file to GitHub since everyone's own `paths.json` will look different and you wouldn't want to accidentally overwrite your teammate's custom absolute path!\n\n### Install `jsonlite`\n\nIf you don't have `jsonlite` already, install it with:\n\n::: {.cell}\n\n```{.r .cell-code}\ninstall.packages(\"jsonlite\")\n```\n:::\n\n### Access your files in cloud storage\n\nNow whenever you want to access the files for your group, you can load `jsonlite` and run its `read_json()` function. If your path was not saved as `data_path` then in the code below, make sure to replace `data_path` with the actual name.\n\n::: {.cell}\n\n```{.r .cell-code}\n# Load jsonlite\nlibrary(\"jsonlite\")\n\n# Get the path to your files\npath_to_data <- jsonlite::read_json(\"paths.json\")$data_path\n```\n:::\n\nAnd `path_to_data` will contain the path to the folder where all your relevant files live! \n\nIf you combine this path with the [`file.path()` function](https://nceas.github.io/scicomp.github.io/best_practices.html#preserve-file-paths-as-objects-using-file.path) then you'll have a powerful, flexible tool for managing file paths!\n\nFor example, if `example.csv` lives in the folder that `path_to_data` points to, then you **and your team members** can read `example.csv` like so:\n\n::: {.cell}\n\n```{.r .cell-code}\n# Read the csv reproducibly\nexample <- read.csv(file = file.path(path_to_data, \"example.csv\"))\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\n- [Download RStudio](https://www.rstudio.com/products/rstudio/download/)\n\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- [Download R](https://cran.r-project.org/)\n\n- [Download RStudio](https://www.rstudio.com/products/rstudio/download/)\n\n- [Download Quarto](https://quarto.org/docs/get-started/)\n\n- [Install `git`](https://happygitwithr.com/install-git.html)\n\n- [Create a GitHub Account](https://github.com/)\n\n- [Connect `git` to GitHub](https://njlyon0.github.io/asm-2022_github-workshop/setup.html#connecting-programs)\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/tutorials.qmd b/tutorials.qmd index ac94d9a..f723ce9 100644 --- a/tutorials.qmd +++ b/tutorials.qmd @@ -4,7 +4,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. -## Using the `jsonlite` R Package +## Storing User-Specific Information {{< include /tutorial-scaffold_jsonlite.qmd >}} From cd63aed235a76e907907322b45bf392597c39d56 Mon Sep 17 00:00:00 2001 From: njlyon0 Date: Wed, 1 May 2024 14:58:39 -0400 Subject: [PATCH 03/11] Updated JSON tutorial overview --- .../tutorial-scaffold_jsonlite/execute-results/html.json | 5 +++-- tutorial-scaffold_jsonlite.qmd | 8 +++----- 2 files changed, 6 insertions(+), 7 deletions(-) diff --git a/_freeze/tutorial-scaffold_jsonlite/execute-results/html.json b/_freeze/tutorial-scaffold_jsonlite/execute-results/html.json index 52f101e..7191ff2 100644 --- a/_freeze/tutorial-scaffold_jsonlite/execute-results/html.json +++ b/_freeze/tutorial-scaffold_jsonlite/execute-results/html.json @@ -1,7 +1,8 @@ { - "hash": "c0f63e8f7edc4c7bbdaeaab27ed88ab8", + "hash": "4a024c0dd720ca48431e239b2afb17de", "result": { - "markdown": "The above section shows how R users can access their data stored on Google Drive, but how about other types of cloud storage like Box or Dropbox? If your data or your team's data is synced to the cloud through those tools, we recommend that all group members store relevant file paths in their own respective JSON file. Then everyone can read those file paths using the [`jsonlite` R package](https://cran.r-project.org/web/packages/jsonlite/index.html)! \n\nThe main advantage of this method is that you and your group members do not have to manually change the file paths in each script whenever a different person runs it!\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\n- [Download RStudio](https://www.rstudio.com/products/rstudio/download/)\n\n- Make sure you have access to your cloud storage files on your local machine\n\nFeel free to skip any steps that you have already completed!\n\n### Copy the desired file paths\n\nFirst, navigate to the folder(s) that contain the files that you and your team most frequently need to access. Copy the absolute path to each needed folder. On Mac, you can right-click and then \"Copy ... as Pathname\" (see below).\n\n

\n\n

\n\nIf you have multiple paths, feel free to paste them into an empty text file for now.\n\n### Create the JSON file\n\nOnce you have the absolute file paths, open RStudio to the main working directory for your project. At the top left corner, click on File -> New File -> Text File. \n\nType the following lines into the file, except replace `YOUR_ABSOLUTE_PATH` with your path. Keep the quotation marks around the path. \n\n\n::: {.cell}\n\n```{.r .cell-code}\n{\n\"data_path\":\"YOUR_ABSOLUTE_PATH\"\n}\n```\n:::\n\n\nYou can customize the name of this path but make sure everyone in your team have the same name(s)! For example, if `data_path` refers to the folder containing all of the data for the group, then everyone should have a `data_path` in their own respective JSON file pointing to the same data folder. The absolute file path will be unique for each person, though. \n\nIf you have multiple paths, you can save them like so:\n\n\n::: {.cell}\n\n```{.r .cell-code}\n{\n\"raw_data_path\":\"YOUR_ABSOLUTE_PATH\",\n\"tidy_data_path\":\"YOUR_ABSOLUTE_PATH\"\n}\n```\n:::\n\n\nSave this file as `paths.json` in your main working directory. \n\n### Put the JSON file in `gitignore`\n\nNavigate to the `gitignore` file of your project and list `paths.json` as one of the files to ignore. We don't want to push this file to GitHub since everyone's own `paths.json` will look different and you wouldn't want to accidentally overwrite your teammate's custom absolute path!\n\n### Install `jsonlite`\n\nIf you don't have `jsonlite` already, install it with:\n\n\n::: {.cell}\n\n```{.r .cell-code}\ninstall.packages(\"jsonlite\")\n```\n:::\n\n\n### Access your files in cloud storage\n\nNow whenever you want to access the files for your group, you can load `jsonlite` and run its `read_json()` function. If your path was not saved as `data_path` then in the code below, make sure to replace `data_path` with the actual name.\n\n\n::: {.cell}\n\n```{.r .cell-code}\n# Load jsonlite\nlibrary(\"jsonlite\")\n\n# Get the path to your files\npath_to_data <- jsonlite::read_json(\"paths.json\")$data_path\n```\n:::\n\n\nAnd `path_to_data` will contain the path to the folder where all your relevant files live! \n\nIf you combine this path with the [`file.path()` function](https://nceas.github.io/scicomp.github.io/best_practices.html#preserve-file-paths-as-objects-using-file.path) then you'll have a powerful, flexible tool for managing file paths!\n\nFor example, if `example.csv` lives in the folder that `path_to_data` points to, then you **and your team members** can read `example.csv` like so:\n\n\n::: {.cell}\n\n```{.r .cell-code}\n# Read the csv reproducibly\nexample <- read.csv(file = file.path(path_to_data, \"example.csv\"))\n```\n:::", + "engine": "knitr", + "markdown": "Working 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://www.rstudio.com/products/rstudio/download/)\n- Install the `jsonlite` R package\n\nFeel free to skip any steps that you have already completed!\n\n### Copy the desired file paths\n\nFirst, navigate to the folder(s) that contain the files that you and your team most frequently need to access. Copy the absolute path to each needed folder. On Mac, you can right-click and then \"Copy ... as Pathname\" (see below).\n\n

\n\n

\n\nIf you have multiple paths, feel free to paste them into an empty text file for now.\n\n### Create the JSON file\n\nOnce you have the absolute file paths, open RStudio to the main working directory for your project. At the top left corner, click on File -> New File -> Text File. \n\nType the following lines into the file, except replace `YOUR_ABSOLUTE_PATH` with your path. Keep the quotation marks around the path. \n\n\n::: {.cell}\n\n```{.r .cell-code}\n{\n\"data_path\":\"YOUR_ABSOLUTE_PATH\"\n}\n```\n:::\n\n\nYou can customize the name of this path but make sure everyone in your team have the same name(s)! For example, if `data_path` refers to the folder containing all of the data for the group, then everyone should have a `data_path` in their own respective JSON file pointing to the same data folder. The absolute file path will be unique for each person, though. \n\nIf you have multiple paths, you can save them like so:\n\n\n::: {.cell}\n\n```{.r .cell-code}\n{\n\"raw_data_path\":\"YOUR_ABSOLUTE_PATH\",\n\"tidy_data_path\":\"YOUR_ABSOLUTE_PATH\"\n}\n```\n:::\n\n\nSave this file as `paths.json` in your main working directory. \n\n### Put the JSON file in `gitignore`\n\nNavigate to the `gitignore` file of your project and list `paths.json` as one of the files to ignore. We don't want to push this file to GitHub since everyone's own `paths.json` will look different and you wouldn't want to accidentally overwrite your teammate's custom absolute path!\n\n### Install `jsonlite`\n\nIf you don't have `jsonlite` already, install it with:\n\n\n::: {.cell}\n\n```{.r .cell-code}\ninstall.packages(\"jsonlite\")\n```\n:::\n\n\n### Access your files in cloud storage\n\nNow whenever you want to access the files for your group, you can load `jsonlite` and run its `read_json()` function. If your path was not saved as `data_path` then in the code below, make sure to replace `data_path` with the actual name.\n\n\n::: {.cell}\n\n```{.r .cell-code}\n# Load jsonlite\nlibrary(\"jsonlite\")\n\n# Get the path to your files\npath_to_data <- jsonlite::read_json(\"paths.json\")$data_path\n```\n:::\n\n\nAnd `path_to_data` will contain the path to the folder where all your relevant files live! \n\nIf you combine this path with the [`file.path()` function](https://nceas.github.io/scicomp.github.io/best_practices.html#preserve-file-paths-as-objects-using-file.path) then you'll have a powerful, flexible tool for managing file paths!\n\nFor example, if `example.csv` lives in the folder that `path_to_data` points to, then you **and your team members** can read `example.csv` like so:\n\n\n::: {.cell}\n\n```{.r .cell-code}\n# Read the csv reproducibly\nexample <- read.csv(file = file.path(path_to_data, \"example.csv\"))\n```\n:::", "supporting": [], "filters": [ "rmarkdown/pagebreak.lua" diff --git a/tutorial-scaffold_jsonlite.qmd b/tutorial-scaffold_jsonlite.qmd index da605f7..4ca141f 100644 --- a/tutorial-scaffold_jsonlite.qmd +++ b/tutorial-scaffold_jsonlite.qmd @@ -1,16 +1,14 @@ -The above section shows how R users can access their data stored on Google Drive, but how about other types of cloud storage like Box or Dropbox? If your data or your team's data is synced to the cloud through those tools, we recommend that all group members store relevant file paths in their own respective JSON file. Then everyone can read those file paths using the [`jsonlite` R package](https://cran.r-project.org/web/packages/jsonlite/index.html)! +Working 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! -The main advantage of this method is that you and your group members do not have to manually change the file paths in each script whenever a different person runs it! +The 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! ### Prerequisites To follow along with this tutorial you will need to take the following steps: - [Download R](https://cran.r-project.org/) - - [Download RStudio](https://www.rstudio.com/products/rstudio/download/) - -- Make sure you have access to your cloud storage files on your local machine +- Install the `jsonlite` R package Feel free to skip any steps that you have already completed! From b4f949e34bcb4b8931d9748f38aad1279cfaaaeb Mon Sep 17 00:00:00 2001 From: njlyon0 Date: Wed, 1 May 2024 15:10:00 -0400 Subject: [PATCH 04/11] Fleshed out new first chunk of tutorial (make a JSON file) --- .../execute-results/html.json | 4 +- tutorial-scaffold_jsonlite.qmd | 56 ++++++++++++++++--- 2 files changed, 51 insertions(+), 9 deletions(-) diff --git a/_freeze/tutorial-scaffold_jsonlite/execute-results/html.json b/_freeze/tutorial-scaffold_jsonlite/execute-results/html.json index 7191ff2..0d1e33b 100644 --- a/_freeze/tutorial-scaffold_jsonlite/execute-results/html.json +++ b/_freeze/tutorial-scaffold_jsonlite/execute-results/html.json @@ -1,8 +1,8 @@ { - "hash": "4a024c0dd720ca48431e239b2afb17de", + "hash": "0f1ecb822394794917a3ec85dcfb9cd9", "result": { "engine": "knitr", - "markdown": "Working 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://www.rstudio.com/products/rstudio/download/)\n- Install the `jsonlite` R package\n\nFeel free to skip any steps that you have already completed!\n\n### Copy the desired file paths\n\nFirst, navigate to the folder(s) that contain the files that you and your team most frequently need to access. Copy the absolute path to each needed folder. On Mac, you can right-click and then \"Copy ... as Pathname\" (see below).\n\n

\n\n

\n\nIf you have multiple paths, feel free to paste them into an empty text file for now.\n\n### Create the JSON file\n\nOnce you have the absolute file paths, open RStudio to the main working directory for your project. At the top left corner, click on File -> New File -> Text File. \n\nType the following lines into the file, except replace `YOUR_ABSOLUTE_PATH` with your path. Keep the quotation marks around the path. \n\n\n::: {.cell}\n\n```{.r .cell-code}\n{\n\"data_path\":\"YOUR_ABSOLUTE_PATH\"\n}\n```\n:::\n\n\nYou can customize the name of this path but make sure everyone in your team have the same name(s)! For example, if `data_path` refers to the folder containing all of the data for the group, then everyone should have a `data_path` in their own respective JSON file pointing to the same data folder. The absolute file path will be unique for each person, though. \n\nIf you have multiple paths, you can save them like so:\n\n\n::: {.cell}\n\n```{.r .cell-code}\n{\n\"raw_data_path\":\"YOUR_ABSOLUTE_PATH\",\n\"tidy_data_path\":\"YOUR_ABSOLUTE_PATH\"\n}\n```\n:::\n\n\nSave this file as `paths.json` in your main working directory. \n\n### Put the JSON file in `gitignore`\n\nNavigate to the `gitignore` file of your project and list `paths.json` as one of the files to ignore. We don't want to push this file to GitHub since everyone's own `paths.json` will look different and you wouldn't want to accidentally overwrite your teammate's custom absolute path!\n\n### Install `jsonlite`\n\nIf you don't have `jsonlite` already, install it with:\n\n\n::: {.cell}\n\n```{.r .cell-code}\ninstall.packages(\"jsonlite\")\n```\n:::\n\n\n### Access your files in cloud storage\n\nNow whenever you want to access the files for your group, you can load `jsonlite` and run its `read_json()` function. If your path was not saved as `data_path` then in the code below, make sure to replace `data_path` with the actual name.\n\n\n::: {.cell}\n\n```{.r .cell-code}\n# Load jsonlite\nlibrary(\"jsonlite\")\n\n# Get the path to your files\npath_to_data <- jsonlite::read_json(\"paths.json\")$data_path\n```\n:::\n\n\nAnd `path_to_data` will contain the path to the folder where all your relevant files live! \n\nIf you combine this path with the [`file.path()` function](https://nceas.github.io/scicomp.github.io/best_practices.html#preserve-file-paths-as-objects-using-file.path) then you'll have a powerful, flexible tool for managing file paths!\n\nFor example, if `example.csv` lives in the folder that `path_to_data` points to, then you **and your team members** can read `example.csv` like so:\n\n\n::: {.cell}\n\n```{.r .cell-code}\n# Read the csv reproducibly\nexample <- read.csv(file = file.path(path_to_data, \"example.csv\"))\n```\n:::", + "markdown": "Working 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://www.rstudio.com/products/rstudio/download/)\n- Install the `jsonlite` R package\n\nFeel free to skip any steps that you have already completed!\n\n### 1. Create the JSON file\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\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\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----\n\nOnce you have the absolute file paths, open RStudio to the main working directory for your project. At the top left corner, click on File -> New File -> Text File. \n\nType the following lines into the file, except replace `YOUR_ABSOLUTE_PATH` with your path. Keep the quotation marks around the path. \n\n\n::: {.cell}\n\n```{.r .cell-code}\n{\n\"data_path\":\"YOUR_ABSOLUTE_PATH\"\n}\n```\n:::\n\n\nYou can customize the name of this path but make sure everyone in your team have the same name(s)! For example, if `data_path` refers to the folder containing all of the data for the group, then everyone should have a `data_path` in their own respective JSON file pointing to the same data folder. The absolute file path will be unique for each person, though. \n\nIf you have multiple paths, you can save them like so:\n\n\n::: {.cell}\n\n```{.r .cell-code}\n{\n\"raw_data_path\":\"YOUR_ABSOLUTE_PATH\",\n\"tidy_data_path\":\"YOUR_ABSOLUTE_PATH\"\n}\n```\n:::\n\n\nSave this file as `paths.json` in your main working directory. \n\n### Put the JSON file in `gitignore`\n\nNavigate to the `gitignore` file of your project and list `paths.json` as one of the files to ignore. We don't want to push this file to GitHub since everyone's own `paths.json` will look different and you wouldn't want to accidentally overwrite your teammate's custom absolute path!\n\n### Install `jsonlite`\n\nIf you don't have `jsonlite` already, install it with:\n\n\n::: {.cell}\n\n```{.r .cell-code}\ninstall.packages(\"jsonlite\")\n```\n:::\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n---\n\n\n\n\n\n\n### Copy the desired file paths\n\nFirst, navigate to the folder(s) that contain the files that you and your team most frequently need to access. Copy the absolute path to each needed folder. On Mac, you can right-click and then \"Copy ... as Pathname\" (see below).\n\n

\n\n

\n\nIf you have multiple paths, feel free to paste them into an empty text file for now.\n\n\n### Access your files in cloud storage\n\nNow whenever you want to access the files for your group, you can load `jsonlite` and run its `read_json()` function. If your path was not saved as `data_path` then in the code below, make sure to replace `data_path` with the actual name.\n\n\n::: {.cell}\n\n```{.r .cell-code}\n# Load jsonlite\nlibrary(\"jsonlite\")\n\n# Get the path to your files\npath_to_data <- jsonlite::read_json(\"paths.json\")$data_path\n```\n:::\n\n\nAnd `path_to_data` will contain the path to the folder where all your relevant files live! \n\nIf you combine this path with the [`file.path()` function](https://nceas.github.io/scicomp.github.io/best_practices.html#preserve-file-paths-as-objects-using-file.path) then you'll have a powerful, flexible tool for managing file paths!\n\nFor example, if `example.csv` lives in the folder that `path_to_data` points to, then you **and your team members** can read `example.csv` like so:\n\n\n::: {.cell}\n\n```{.r .cell-code}\n# Read the csv reproducibly\nexample <- read.csv(file = file.path(path_to_data, \"example.csv\"))\n```\n:::", "supporting": [], "filters": [ "rmarkdown/pagebreak.lua" diff --git a/tutorial-scaffold_jsonlite.qmd b/tutorial-scaffold_jsonlite.qmd index 4ca141f..3cd65ac 100644 --- a/tutorial-scaffold_jsonlite.qmd +++ b/tutorial-scaffold_jsonlite.qmd @@ -12,17 +12,26 @@ To follow along with this tutorial you will need to take the following steps: Feel free to skip any steps that you have already completed! -### Copy the desired file paths +### 1. Create the JSON file -First, navigate to the folder(s) that contain the files that you and your team most frequently need to access. Copy the absolute path to each needed folder. On Mac, you can right-click and then "Copy ... as Pathname" (see below). +First, 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: -

- -

+```{r create-json} +#| eval: false -If you have multiple paths, feel free to paste them into an empty text file for now. +{ + "email":"my_email@gmail.com" + "dropbox_path":"path/to/dropbox-sync/for/me" +} +``` + +Replace 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. + +One 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. -### Create the JSON file +You'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. + +---- Once you have the absolute file paths, open RStudio to the main working directory for your project. At the top left corner, click on File -> New File -> Text File. @@ -59,6 +68,39 @@ If you don't have `jsonlite` already, install it with: install.packages("jsonlite") ``` + + + + + + + + + + + + + + + +--- + + + + + + +### Copy the desired file paths + +First, navigate to the folder(s) that contain the files that you and your team most frequently need to access. Copy the absolute path to each needed folder. On Mac, you can right-click and then "Copy ... as Pathname" (see below). + +

+ +

+ +If you have multiple paths, feel free to paste them into an empty text file for now. + + ### Access your files in cloud storage Now whenever you want to access the files for your group, you can load `jsonlite` and run its `read_json()` function. If your path was not saved as `data_path` then in the code below, make sure to replace `data_path` with the actual name. From 68490beec35228dd230781e3e13ed65f9eb6d02e Mon Sep 17 00:00:00 2001 From: njlyon0 Date: Wed, 1 May 2024 15:30:33 -0400 Subject: [PATCH 05/11] Finished first pass at new tutorial --- .../execute-results/html.json | 4 +- tutorial-scaffold_jsonlite.qmd | 56 +++++++++++++------ 2 files changed, 40 insertions(+), 20 deletions(-) diff --git a/_freeze/tutorial-scaffold_jsonlite/execute-results/html.json b/_freeze/tutorial-scaffold_jsonlite/execute-results/html.json index 0d1e33b..e1f6ece 100644 --- a/_freeze/tutorial-scaffold_jsonlite/execute-results/html.json +++ b/_freeze/tutorial-scaffold_jsonlite/execute-results/html.json @@ -1,8 +1,8 @@ { - "hash": "0f1ecb822394794917a3ec85dcfb9cd9", + "hash": "e3b444e08db0792cadcc1eeb6506360a", "result": { "engine": "knitr", - "markdown": "Working 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://www.rstudio.com/products/rstudio/download/)\n- Install the `jsonlite` R package\n\nFeel free to skip any steps that you have already completed!\n\n### 1. Create the JSON file\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\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\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----\n\nOnce you have the absolute file paths, open RStudio to the main working directory for your project. At the top left corner, click on File -> New File -> Text File. \n\nType the following lines into the file, except replace `YOUR_ABSOLUTE_PATH` with your path. Keep the quotation marks around the path. \n\n\n::: {.cell}\n\n```{.r .cell-code}\n{\n\"data_path\":\"YOUR_ABSOLUTE_PATH\"\n}\n```\n:::\n\n\nYou can customize the name of this path but make sure everyone in your team have the same name(s)! For example, if `data_path` refers to the folder containing all of the data for the group, then everyone should have a `data_path` in their own respective JSON file pointing to the same data folder. The absolute file path will be unique for each person, though. \n\nIf you have multiple paths, you can save them like so:\n\n\n::: {.cell}\n\n```{.r .cell-code}\n{\n\"raw_data_path\":\"YOUR_ABSOLUTE_PATH\",\n\"tidy_data_path\":\"YOUR_ABSOLUTE_PATH\"\n}\n```\n:::\n\n\nSave this file as `paths.json` in your main working directory. \n\n### Put the JSON file in `gitignore`\n\nNavigate to the `gitignore` file of your project and list `paths.json` as one of the files to ignore. We don't want to push this file to GitHub since everyone's own `paths.json` will look different and you wouldn't want to accidentally overwrite your teammate's custom absolute path!\n\n### Install `jsonlite`\n\nIf you don't have `jsonlite` already, install it with:\n\n\n::: {.cell}\n\n```{.r .cell-code}\ninstall.packages(\"jsonlite\")\n```\n:::\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n---\n\n\n\n\n\n\n### Copy the desired file paths\n\nFirst, navigate to the folder(s) that contain the files that you and your team most frequently need to access. Copy the absolute path to each needed folder. On Mac, you can right-click and then \"Copy ... as Pathname\" (see below).\n\n

\n\n

\n\nIf you have multiple paths, feel free to paste them into an empty text file for now.\n\n\n### Access your files in cloud storage\n\nNow whenever you want to access the files for your group, you can load `jsonlite` and run its `read_json()` function. If your path was not saved as `data_path` then in the code below, make sure to replace `data_path` with the actual name.\n\n\n::: {.cell}\n\n```{.r .cell-code}\n# Load jsonlite\nlibrary(\"jsonlite\")\n\n# Get the path to your files\npath_to_data <- jsonlite::read_json(\"paths.json\")$data_path\n```\n:::\n\n\nAnd `path_to_data` will contain the path to the folder where all your relevant files live! \n\nIf you combine this path with the [`file.path()` function](https://nceas.github.io/scicomp.github.io/best_practices.html#preserve-file-paths-as-objects-using-file.path) then you'll have a powerful, flexible tool for managing file paths!\n\nFor example, if `example.csv` lives in the folder that `path_to_data` points to, then you **and your team members** can read `example.csv` like so:\n\n\n::: {.cell}\n\n```{.r .cell-code}\n# Read the csv reproducibly\nexample <- read.csv(file = file.path(path_to_data, \"example.csv\"))\n```\n:::", + "markdown": "Working 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://www.rstudio.com/products/rstudio/download/)\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\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\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\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### Put the JSON file in `gitignore`\n\n\n\n### Install `jsonlite`\n\nIf you don't have `jsonlite` already, install it with:\n\n\n::: {.cell}\n\n```{.r .cell-code}\ninstall.packages(\"jsonlite\")\n```\n:::\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n---\n\n\n\n\n\n\n### Copy the desired file paths\n\nFirst, navigate to the folder(s) that contain the files that you and your team most frequently need to access. Copy the absolute path to each needed folder. On Mac, you can right-click and then \"Copy ... as Pathname\" (see below).\n\n

\n\n

\n\nIf you have multiple paths, feel free to paste them into an empty text file for now.\n\n\n### Access your files in cloud storage\n\nNow whenever you want to access the files for your group, you can load `jsonlite` and run its `read_json()` function. If your path was not saved as `data_path` then in the code below, make sure to replace `data_path` with the actual name.\n\n\n::: {.cell}\n\n```{.r .cell-code}\n# Load jsonlite\nlibrary(\"jsonlite\")\n\n# Get the path to your files\npath_to_data <- jsonlite::read_json(\"paths.json\")$data_path\n```\n:::\n\n\nAnd `path_to_data` will contain the path to the folder where all your relevant files live! \n\nIf you combine this path with the [`file.path()` function](https://nceas.github.io/scicomp.github.io/best_practices.html#preserve-file-paths-as-objects-using-file.path) then you'll have a powerful, flexible tool for managing file paths!\n\nFor example, if `example.csv` lives in the folder that `path_to_data` points to, then you **and your team members** can read `example.csv` like so:\n\n\n::: {.cell}\n\n```{.r .cell-code}\n# Read the csv reproducibly\nexample <- read.csv(file = file.path(path_to_data, \"example.csv\"))\n```\n:::", "supporting": [], "filters": [ "rmarkdown/pagebreak.lua" diff --git a/tutorial-scaffold_jsonlite.qmd b/tutorial-scaffold_jsonlite.qmd index 3cd65ac..e4d4ec1 100644 --- a/tutorial-scaffold_jsonlite.qmd +++ b/tutorial-scaffold_jsonlite.qmd @@ -12,7 +12,7 @@ To follow along with this tutorial you will need to take the following steps: Feel free to skip any steps that you have already completed! -### 1. Create the JSON file +### 1. Create the JSON First, 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: @@ -31,34 +31,54 @@ One small note here for when you work with your group: all group members need You'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. ----- +### 2. Save the JSON with a Consistent Name -Once you have the absolute file paths, open RStudio to the main working directory for your project. At the top left corner, click on File -> New File -> Text File. +This 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.) -Type the following lines into the file, except replace `YOUR_ABSOLUTE_PATH` with your path. Keep the quotation marks around the path. +### 3. Tell Git to Ignore the JSON -```{r create-json-1, eval = F} -{ -"data_path":"YOUR_ABSOLUTE_PATH" -} -``` +If 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. -You can customize the name of this path but make sure everyone in your team have the same name(s)! For example, if `data_path` refers to the folder containing all of the data for the group, then everyone should have a `data_path` in their own respective JSON file pointing to the same data folder. The absolute file path will be unique for each person, though. +For 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! -If you have multiple paths, you can save them like so: +### 4. Benefit from the JSON! -```{r create-json-2, eval = F} -{ -"raw_data_path":"YOUR_ABSOLUTE_PATH", -"tidy_data_path":"YOUR_ABSOLUTE_PATH" -} +If 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. + +See an example below: +```{r read-json} +#| eval: false + +# Load needed library +library(jsonlite) + +# Read in the JSON file +user_info <- jsonlite::read_json("user.json") + +# Grab the file path out of it +dropbox <- user_info$dropbox_path + +# Use it as you would any other file path +my_data <- read.csv(file = file.path(dropbox, "2024_data.csv")) ``` -Save this file as `paths.json` in your main working directory. +Now 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. + +#### Help with Absolute File Paths + +Identifying 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". + +Once you've done that, you can simply paste the file path into your JSON file. + +

+ +

+ +---- ### Put the JSON file in `gitignore` -Navigate to the `gitignore` file of your project and list `paths.json` as one of the files to ignore. We don't want to push this file to GitHub since everyone's own `paths.json` will look different and you wouldn't want to accidentally overwrite your teammate's custom absolute path! + ### Install `jsonlite` From ad4ecac44231d5e3184dec422d4cd4cecfab55f7 Mon Sep 17 00:00:00 2001 From: njlyon0 Date: Wed, 1 May 2024 15:40:56 -0400 Subject: [PATCH 06/11] Deleted superseded content from the old framing of the tutorial --- .../execute-results/html.json | 4 +- tutorial-scaffold_jsonlite.qmd | 75 +------------------ 2 files changed, 5 insertions(+), 74 deletions(-) diff --git a/_freeze/tutorial-scaffold_jsonlite/execute-results/html.json b/_freeze/tutorial-scaffold_jsonlite/execute-results/html.json index e1f6ece..d5922c3 100644 --- a/_freeze/tutorial-scaffold_jsonlite/execute-results/html.json +++ b/_freeze/tutorial-scaffold_jsonlite/execute-results/html.json @@ -1,8 +1,8 @@ { - "hash": "e3b444e08db0792cadcc1eeb6506360a", + "hash": "c257d7f536b60ee9de5dabfadd0a2724", "result": { "engine": "knitr", - "markdown": "Working 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://www.rstudio.com/products/rstudio/download/)\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\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\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\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### Put the JSON file in `gitignore`\n\n\n\n### Install `jsonlite`\n\nIf you don't have `jsonlite` already, install it with:\n\n\n::: {.cell}\n\n```{.r .cell-code}\ninstall.packages(\"jsonlite\")\n```\n:::\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n---\n\n\n\n\n\n\n### Copy the desired file paths\n\nFirst, navigate to the folder(s) that contain the files that you and your team most frequently need to access. Copy the absolute path to each needed folder. On Mac, you can right-click and then \"Copy ... as Pathname\" (see below).\n\n

\n\n

\n\nIf you have multiple paths, feel free to paste them into an empty text file for now.\n\n\n### Access your files in cloud storage\n\nNow whenever you want to access the files for your group, you can load `jsonlite` and run its `read_json()` function. If your path was not saved as `data_path` then in the code below, make sure to replace `data_path` with the actual name.\n\n\n::: {.cell}\n\n```{.r .cell-code}\n# Load jsonlite\nlibrary(\"jsonlite\")\n\n# Get the path to your files\npath_to_data <- jsonlite::read_json(\"paths.json\")$data_path\n```\n:::\n\n\nAnd `path_to_data` will contain the path to the folder where all your relevant files live! \n\nIf you combine this path with the [`file.path()` function](https://nceas.github.io/scicomp.github.io/best_practices.html#preserve-file-paths-as-objects-using-file.path) then you'll have a powerful, flexible tool for managing file paths!\n\nFor example, if `example.csv` lives in the folder that `path_to_data` points to, then you **and your team members** can read `example.csv` like so:\n\n\n::: {.cell}\n\n```{.r .cell-code}\n# Read the csv reproducibly\nexample <- read.csv(file = file.path(path_to_data, \"example.csv\"))\n```\n:::", + "markdown": "Working 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\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\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\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\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", "supporting": [], "filters": [ "rmarkdown/pagebreak.lua" diff --git a/tutorial-scaffold_jsonlite.qmd b/tutorial-scaffold_jsonlite.qmd index e4d4ec1..a1c94d3 100644 --- a/tutorial-scaffold_jsonlite.qmd +++ b/tutorial-scaffold_jsonlite.qmd @@ -6,8 +6,8 @@ The main advantage of this method is that you and your group members do not h To follow along with this tutorial you will need to take the following steps: -- [Download R](https://cran.r-project.org/) -- [Download RStudio](https://www.rstudio.com/products/rstudio/download/) +- Download [R](https://cran.r-project.org/) +- Download [RStudio](https://posit.co/downloads/) - Install the `jsonlite` R package Feel free to skip any steps that you have already completed! @@ -46,6 +46,7 @@ For a deeper dive into the `.gitignore` check out [that module](https://nceas.gi If 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. See an example below: + ```{r read-json} #| eval: false @@ -73,73 +74,3 @@ Once you've done that, you can simply paste the file path into your JSON file.

- ----- - -### Put the JSON file in `gitignore` - - - -### Install `jsonlite` - -If you don't have `jsonlite` already, install it with: - -```{r install-json, eval = F} -install.packages("jsonlite") -``` - - - - - - - - - - - - - - - - ---- - - - - - - -### Copy the desired file paths - -First, navigate to the folder(s) that contain the files that you and your team most frequently need to access. Copy the absolute path to each needed folder. On Mac, you can right-click and then "Copy ... as Pathname" (see below). - -

- -

- -If you have multiple paths, feel free to paste them into an empty text file for now. - - -### Access your files in cloud storage - -Now whenever you want to access the files for your group, you can load `jsonlite` and run its `read_json()` function. If your path was not saved as `data_path` then in the code below, make sure to replace `data_path` with the actual name. - -```{r read-json-1, eval = F} -# Load jsonlite -library("jsonlite") - -# Get the path to your files -path_to_data <- jsonlite::read_json("paths.json")$data_path -``` - -And `path_to_data` will contain the path to the folder where all your relevant files live! - -If you combine this path with the [`file.path()` function](https://nceas.github.io/scicomp.github.io/best_practices.html#preserve-file-paths-as-objects-using-file.path) then you'll have a powerful, flexible tool for managing file paths! - -For example, if `example.csv` lives in the folder that `path_to_data` points to, then you **and your team members** can read `example.csv` like so: - -```{r read-json-2, eval = F} -# Read the csv reproducibly -example <- read.csv(file = file.path(path_to_data, "example.csv")) -``` \ No newline at end of file From 89f3cfb7b8d0627dd29105b20fac87b2f48902c5 Mon Sep 17 00:00:00 2001 From: njlyon0 Date: Wed, 1 May 2024 15:41:13 -0400 Subject: [PATCH 07/11] Fixed deprecated RStudio download link --- .../execute-results/html.json | 5 +++-- tutorial-scaffold_googledrive-auth.qmd | 6 ++---- 2 files changed, 5 insertions(+), 6 deletions(-) diff --git a/_freeze/tutorial-scaffold_googledrive-auth/execute-results/html.json b/_freeze/tutorial-scaffold_googledrive-auth/execute-results/html.json index 33f1b82..8e61468 100644 --- a/_freeze/tutorial-scaffold_googledrive-auth/execute-results/html.json +++ b/_freeze/tutorial-scaffold_googledrive-auth/execute-results/html.json @@ -1,7 +1,8 @@ { - "hash": "db1f6caa9f258819e8007c3729f865f7", + "hash": "0cbdd7735ec4b3a00563c5c9597a3843", "result": { - "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\n- [Download RStudio](https://www.rstudio.com/products/rstudio/download/)\n\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---\ntitle: \"googledrive-fxns\"\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", + "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", "supporting": [], "filters": [ "rmarkdown/pagebreak.lua" diff --git a/tutorial-scaffold_googledrive-auth.qmd b/tutorial-scaffold_googledrive-auth.qmd index ee120bf..0713d2b 100644 --- a/tutorial-scaffold_googledrive-auth.qmd +++ b/tutorial-scaffold_googledrive-auth.qmd @@ -6,10 +6,8 @@ Because this package requires access to an R user's GoogleDrive, you must "authe To follow along with this tutorial you will need to take the following steps: -- [Download R](https://cran.r-project.org/) - -- [Download RStudio](https://www.rstudio.com/products/rstudio/download/) - +- Download [R](https://cran.r-project.org/) +- Download [RStudio](https://posit.co/downloads/) - Create a Gmail account Feel free to skip any steps that you have already completed! From 5b34dc54129acb387962b97622be3c6ca6c89c20 Mon Sep 17 00:00:00 2001 From: njlyon0 Date: Wed, 1 May 2024 15:41:53 -0400 Subject: [PATCH 08/11] Streamlined Quarto website 'prerequisites' to just refer people to our GitHub workshop setup instructions (figure those will always reflect our most up-to-date guidance) --- .../execute-results/html.json | 5 +++-- tutorial-scaffold_quarto-website.qmd | 11 +---------- 2 files changed, 4 insertions(+), 12 deletions(-) diff --git a/_freeze/tutorial-scaffold_quarto-website/execute-results/html.json b/_freeze/tutorial-scaffold_quarto-website/execute-results/html.json index 8e72799..fc3d1f4 100644 --- a/_freeze/tutorial-scaffold_quarto-website/execute-results/html.json +++ b/_freeze/tutorial-scaffold_quarto-website/execute-results/html.json @@ -1,7 +1,8 @@ { - "hash": "1a3682d4c66bfe9e91f4b6d5abd95654", + "hash": "ee64e0dc6389a723bc5428a9c201a9f0", "result": { - "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- [Download R](https://cran.r-project.org/)\n\n- [Download RStudio](https://www.rstudio.com/products/rstudio/download/)\n\n- [Download Quarto](https://quarto.org/docs/get-started/)\n\n- [Install `git`](https://happygitwithr.com/install-git.html)\n\n- [Create a GitHub Account](https://github.com/)\n\n- [Connect `git` to GitHub](https://njlyon0.github.io/asm-2022_github-workshop/setup.html#connecting-programs)\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.", + "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.", "supporting": [], "filters": [ "rmarkdown/pagebreak.lua" diff --git a/tutorial-scaffold_quarto-website.qmd b/tutorial-scaffold_quarto-website.qmd index 8f7f5e8..57bdcc6 100644 --- a/tutorial-scaffold_quarto-website.qmd +++ b/tutorial-scaffold_quarto-website.qmd @@ -5,18 +5,9 @@ To follow along with this tutorial you will need to take the following steps: -- [Download R](https://cran.r-project.org/) - -- [Download RStudio](https://www.rstudio.com/products/rstudio/download/) - +- 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 - [Download Quarto](https://quarto.org/docs/get-started/) -- [Install `git`](https://happygitwithr.com/install-git.html) - -- [Create a GitHub Account](https://github.com/) - -- [Connect `git` to GitHub](https://njlyon0.github.io/asm-2022_github-workshop/setup.html#connecting-programs) - Feel free to skip any steps that you have already completed! ### Create a Quarto Website R Project From fb7a193599e47d446febb5698fbf356320193bf2 Mon Sep 17 00:00:00 2001 From: njlyon0 Date: Wed, 1 May 2024 15:42:52 -0400 Subject: [PATCH 09/11] Renamed the JSON tutorial to reflect its new framing and re-rendered the tutorial page --- _freeze/tutorials/execute-results/html.json | 4 ++-- tutorial-scaffold_jsonlite.qmd => tutorial_json.qmd | 0 tutorials.qmd | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) rename tutorial-scaffold_jsonlite.qmd => tutorial_json.qmd (100%) diff --git a/_freeze/tutorials/execute-results/html.json b/_freeze/tutorials/execute-results/html.json index cd854da..cb6b34b 100644 --- a/_freeze/tutorials/execute-results/html.json +++ b/_freeze/tutorials/execute-results/html.json @@ -1,8 +1,8 @@ { - "hash": "1d34c38c70c714dd3fece0c9644af8ca", + "hash": "92cc173d83e3f39fedc024ec2cef0ee2", "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\nThe above section shows how R users can access their data stored on Google Drive, but how about other types of cloud storage like Box or Dropbox? If your data or your team's data is synced to the cloud through those tools, we recommend that all group members store relevant file paths in their own respective JSON file. Then everyone can read those file paths using the [`jsonlite` R package](https://cran.r-project.org/web/packages/jsonlite/index.html)! \n\nThe main advantage of this method is that you and your group members do not have to manually change the file paths in each script whenever a different person runs it!\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\n- [Download RStudio](https://www.rstudio.com/products/rstudio/download/)\n\n- Make sure you have access to your cloud storage files on your local machine\n\nFeel free to skip any steps that you have already completed!\n\n### Copy the desired file paths\n\nFirst, navigate to the folder(s) that contain the files that you and your team most frequently need to access. Copy the absolute path to each needed folder. On Mac, you can right-click and then \"Copy ... as Pathname\" (see below).\n\n

\n\n

\n\nIf you have multiple paths, feel free to paste them into an empty text file for now.\n\n### Create the JSON file\n\nOnce you have the absolute file paths, open RStudio to the main working directory for your project. At the top left corner, click on File -> New File -> Text File. \n\nType the following lines into the file, except replace `YOUR_ABSOLUTE_PATH` with your path. Keep the quotation marks around the path. \n\n::: {.cell}\n\n```{.r .cell-code}\n{\n\"data_path\":\"YOUR_ABSOLUTE_PATH\"\n}\n```\n:::\n\nYou can customize the name of this path but make sure everyone in your team have the same name(s)! For example, if `data_path` refers to the folder containing all of the data for the group, then everyone should have a `data_path` in their own respective JSON file pointing to the same data folder. The absolute file path will be unique for each person, though. \n\nIf you have multiple paths, you can save them like so:\n\n::: {.cell}\n\n```{.r .cell-code}\n{\n\"raw_data_path\":\"YOUR_ABSOLUTE_PATH\",\n\"tidy_data_path\":\"YOUR_ABSOLUTE_PATH\"\n}\n```\n:::\n\nSave this file as `paths.json` in your main working directory. \n\n### Put the JSON file in `gitignore`\n\nNavigate to the `gitignore` file of your project and list `paths.json` as one of the files to ignore. We don't want to push this file to GitHub since everyone's own `paths.json` will look different and you wouldn't want to accidentally overwrite your teammate's custom absolute path!\n\n### Install `jsonlite`\n\nIf you don't have `jsonlite` already, install it with:\n\n::: {.cell}\n\n```{.r .cell-code}\ninstall.packages(\"jsonlite\")\n```\n:::\n\n### Access your files in cloud storage\n\nNow whenever you want to access the files for your group, you can load `jsonlite` and run its `read_json()` function. If your path was not saved as `data_path` then in the code below, make sure to replace `data_path` with the actual name.\n\n::: {.cell}\n\n```{.r .cell-code}\n# Load jsonlite\nlibrary(\"jsonlite\")\n\n# Get the path to your files\npath_to_data <- jsonlite::read_json(\"paths.json\")$data_path\n```\n:::\n\nAnd `path_to_data` will contain the path to the folder where all your relevant files live! \n\nIf you combine this path with the [`file.path()` function](https://nceas.github.io/scicomp.github.io/best_practices.html#preserve-file-paths-as-objects-using-file.path) then you'll have a powerful, flexible tool for managing file paths!\n\nFor example, if `example.csv` lives in the folder that `path_to_data` points to, then you **and your team members** can read `example.csv` like so:\n\n::: {.cell}\n\n```{.r .cell-code}\n# Read the csv reproducibly\nexample <- read.csv(file = file.path(path_to_data, \"example.csv\"))\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\n- [Download RStudio](https://www.rstudio.com/products/rstudio/download/)\n\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- [Download R](https://cran.r-project.org/)\n\n- [Download RStudio](https://www.rstudio.com/products/rstudio/download/)\n\n- [Download Quarto](https://quarto.org/docs/get-started/)\n\n- [Install `git`](https://happygitwithr.com/install-git.html)\n\n- [Create a GitHub Account](https://github.com/)\n\n- [Connect `git` to GitHub](https://njlyon0.github.io/asm-2022_github-workshop/setup.html#connecting-programs)\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://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", "supporting": [], "filters": [ "rmarkdown/pagebreak.lua" diff --git a/tutorial-scaffold_jsonlite.qmd b/tutorial_json.qmd similarity index 100% rename from tutorial-scaffold_jsonlite.qmd rename to tutorial_json.qmd diff --git a/tutorials.qmd b/tutorials.qmd index f723ce9..607130f 100644 --- a/tutorials.qmd +++ b/tutorials.qmd @@ -6,7 +6,7 @@ Some of the content that we produce is not as detailed as our full workshops but ## Storing User-Specific Information -{{< include /tutorial-scaffold_jsonlite.qmd >}} +{{< include /tutorial_json.qmd >}} ## Using the `googledrive` R Package From fdf9606f173048497086ba0726997746f8d01acd Mon Sep 17 00:00:00 2001 From: njlyon0 Date: Wed, 1 May 2024 15:48:28 -0400 Subject: [PATCH 10/11] Re-rendered the whole website to make sure all changes are reflected --- _freeze/best_practices/execute-results/html.json | 3 ++- .../file-paths/execute-results/html.json | 3 ++- .../pkg-loading/execute-results/html.json | 1 + .../github-connect/execute-results/html.json | 1 + .../googledrive-auth/execute-results/html.json | 5 ++++- .../googledrive-fxns/execute-results/html.json | 1 + .../execute-results/html.json | 1 + _freeze/portfolio/execute-results/html.json | 5 ++--- _freeze/shiny-server/execute-results/html.json | 1 + .../execute-results/html.json | 15 --------------- _freeze/tutorial_json/execute-results/html.json | 15 +++++++++++++++ _freeze/tutorial_server/execute-results/html.json | 1 + 12 files changed, 31 insertions(+), 21 deletions(-) delete mode 100644 _freeze/tutorial-scaffold_jsonlite/execute-results/html.json create mode 100644 _freeze/tutorial_json/execute-results/html.json diff --git a/_freeze/best_practices/execute-results/html.json b/_freeze/best_practices/execute-results/html.json index 7a522ea..c0cfd2d 100644 --- a/_freeze/best_practices/execute-results/html.json +++ b/_freeze/best_practices/execute-results/html.json @@ -1,7 +1,8 @@ { "hash": "45d24fbb8426460b460df2b391399b7f", "result": { - "markdown": "---\ntitle: \"Coding Tips\"\n---\n\n\n\n\n### Welcome!\n\nThis page contains the collected best practice tips of the NCEAS Scientific Computing Support Team. More will be added over time and feel free to post [an issue](https://github.com/NCEAS/scicomp.github.io/issues) if you have a specific request for a section to add to this document.\n\nPlease feel free to reach out to our team (see [here](https://nceas.github.io/scicomp.github.io/staff.html)) if you have any questions about this best practices manual and/or need help implementing some of this content.\n\nCheck the headings below or in the table of contents on the right of this page to see which tips and tricks we have included so far and we hope this page is a useful resource to you and your team!\n\n## R Scripts versus R Markdowns\n\n\nWhen coding in R, either R scripts (.R files) or R markdowns (.Rmd files) are viable options but they have different advantages and disadvantages that we will cover below.\n\n### R Scripts - Positives\n\nR scripts' greatest strength is their flexibility. They allow you to format a file in whatever way is most intuitive to you. Additionally, R scripts can be cleaner for `for` loops insofar as they need not be concerned with staying within a given code chunk (as would be the case for a .Rmd). Developing a new workflow can be swiftly accomplished in an R script as some or all of the code in a script can be run by simply selecting the desired lines rather than manually running the desired chunks in a .Rmd file. Finally, R scripts can also be a better home for custom functions that can be `source`d by another file (even a .Rmd!) for making repeated operations simpler to read.\n\n### R Scripts - Potential Weaknesses\n\nThe benefit of extreme flexibility in R scripts can sometimes be a disadvantage however. We've all seen (and written) R scripts that have few or no comments or where lines of code are densely packed without spacing or blank lines to help someone new to the code understand what is being done. R scripts can certainly be written in a way that is accessible to those without prior knowledge of what the script accomplishes but they do not *enforce* such structure. This can make it easy, especially when we're feeling pressed for time, to exclude structure that helps our code remain reproducible and understandable.\n\n### R Markdowns - Positives\n\nR markdown files' ability to \"knit\" as HTML or PDF documents makes them extremely useful in creating outward-facing reports. This is particularly the case when the specific code is less important to communicate than visualizations and/or analyses of the data but .Rmd files do facilitate `echo`ing the code so that report readers can see how background operations were accomplished. The code chunk structure of these files can also nudge users towards including valuable comments (both between chunks and within them) though of course .Rmd files do not enforce such non-code content.\n\n### R Markdowns - Potential Weaknesses\n\nR markdowns can fail to knit due to issues even when the code within the chunks works as desired. Duplicate code chunk names or a failure to install LaTeX can be a frustrating hurdle to overcome between functioning code and a knit output file. When code must be re-run repeatedly (as is often the case when developing a new workflow) the stop-and-start nature of running each code chunk separately can also be a small irritation.\n\n### Script vs. Markdown Summary\n\nTaken together, both R scripts and R markdown files can empower users to write reproducible, transparent code. However, both file types have some key limitations that should be taken into consideration when choosing which to use as you set out to create a new code product.\n\n\n\n

\n\n

\n\n## File Paths\n\n\nThis section contains our recommendations for handling **file paths**. When you code collaboratively (e.g., with GitHub), accounting for the difference between your folder structure and those of your colleagues becomes critical. Ideally your code should be completely agnostic about (1) the operating system of the computer it is running on (i.e., Windows vs. Mac) and (2) the folder structure of the computer. We can--fortunately--handle these two considerations relatively simply.\n\nThis may seem somewhat dry but it is worth mentioning that failing to use relative file paths is a significant hindrance to reproducibility (see [Trisovic et al. 2022](https://www.nature.com/articles/s41597-022-01143-6)).\n\n### 1. Preserve File Paths as Objects Using `file.path`\n\nDepending on the operating system of the computer, the slashes between folder names are different (`\\` versus `/`). The `file.path` function automatically detects the computer operating system and inserts the correct slash. We recommend using this function and assigning your file path to an object.\n\n::: {.cell}\n\n```{.r .cell-code}\nmy_path <- file.path(\"path\", \"to\", \"my\", \"file\")\nmy_path\n```\n\n::: {.cell-output .cell-output-stdout}\n```\n[1] \"path/to/my/file\"\n```\n:::\n:::\n\nOnce you have that path object, you can use it everywhere you import or export information to/from the code (with another use of `file.path` to get the right type of slash!).\n\n::: {.cell}\n\n```{.r .cell-code}\n# Import\nmy_raw_data <- read.csv(file = file.path(my_path, \"raw_data.csv\"))\n\n# Export\nwrite.csv(x = data_object, file = file.path(my_path, \"tidy_data.csv\"))\n```\n:::\n\n### 2. Create Necessary Sub-Folders in the Code with `dir.create`\n\nUsing `file.path` guarantees that your code will work regardless of the upstream folder structure but what about the folders that you need to export or import things to/from? For example, say your `graphs.R` script saves a couple of useful exploratory graphs to the \"Plots\" folder, how would you guarantee that everyone running `graphs.R` *has* a \"Plots folder\"? You can use the `dir.create` function to create the folder in the code (and include your path object from step 1!).\n\n::: {.cell}\n\n```{.r .cell-code}\n# Create needed folder\ndir.create(path = file.path(my_path, \"Plots\"), showWarnings = FALSE)\n\n# Then export to that folder\nggplot2::ggsave(filename = file.path(my_path, \"Plots\", \"my_plot.png\"))\n```\n:::\n\nThe `showWarnings` argument of `dir.create` simply warns you if the folder you're creating already exists or not. There is no negative to \"creating\" a folder that already exists (nothing is overwritten!!) but the warning can be confusing so we can silence it ahead of time.\n\n### File Paths Summary\n\nWe strongly recommend following these guidelines so that your scripts work regardless of (1) the operating system, (2) folders \"upstream\" of the working directory, and (3) folders within the project. This will help your code by flexible and reproducible when others are attempting to re-run your scripts!\n\nAlso, for more information on how to read files in cloud storage locations such as Google Drive, Box, Dropbox, etc., please refer to our [Other Tutorials](https://nceas.github.io/scicomp.github.io/tutorials.html).\n\n\n\n

\n\n

\n\n## Good Naming Conventions\n\nWhen you first start working on a project with your group members, figuring out what to name your folders/files may not be at the top of your priority list. However, following a good naming convention will allow team members to quickly locate files and figure out what they contain. The organized naming structure will also allow new members of the group to be onboarded more easily! \n\nHere is a summary of some naming tips that we recommend. These were taken from the [Reproducibility Best Practices module](https://lter.github.io/ssecr/mod_reproducibility.html#naming-tips) in the LTER's SSECR course. Please feel free to refer to the aforementioned link for more information.\n\n- Names should be informative\n - An ideal file name should give some information about the file’s contents, purpose, and relation to other project files.\n - For example, if you have a bunch of scripts that need to be run in order, consider adding step numbers to the start of each file name (e.g., \"01_harmonize_data.R\" or \"step01_harmonize_data.R\"). \n- Names should avoid spaces and special characters\n - Spaces and special characters (e.g., é, ü, etc.) in folder/file names may cause errors when someone with a Windows computer tries to read those file paths. You can replace spaces with delimiters like underscores or hyphens to increase machine readability. \n- Follow a consistent naming convention throughout!\n - If you and your group members find a naming convention that works, stick with it! Having a consistent naming convention is key to getting new collaborators to follow it. \n \n\n\n\n## Package Loading\n\n\nLoading packages / libraries in R can be cumbersome when working collaboratively because there is no guarantee that you all have the same packages installed. While you could comment-out an `install.packages()` line for every package you need for a given script, we recommend using the R package `librarian` to greatly simplify this process!\n\n`librarian::shelf()` accepts the names of all of the packages--either CRAN or GitHub--installs those that are missing in that particular R session and then attaches all of them. See below for an example:\n\nTo load packages typically you'd have something like the following in your script:\n\n::: {.cell}\n\n```{.r .cell-code}\n## Install packages (if needed)\n# install.packages(\"tidyverse\")\n# install.packages(\"devtools\")\n# devtools::install_github(\"NCEAS/scicomptools\")\n\n# Load libraries\nlibrary(tidyverse); library(scicomptools)\n```\n:::\n\nWith `librarian::shelf()` however this becomes *much* cleaner! In addition to being fewer lines, using `librarian` also removes the possibility that someone running your code misses one of the packages that your script depends on and then the script breaks for them later on. `librarian::shelf()` automatically detects whether a package is installed, installs it if necessary, and then attaches the package.\n\nIn essence, `librarian::shelf()` wraps `install.packages()`, `devtools::install_github()`, and `library()` into a single, human-readable function.\n\n::: {.cell}\n\n```{.r .cell-code}\n# Install and load packages!\nlibrarian::shelf(tidyverse, NCEAS/scicomptools)\n```\n:::\n\nWhen using `librarian::shelf()`, package names do not need to be quoted and GitHub packages can be installed without the additional steps of installing the `devtools` package and using `devtools::install_github()` instead of `install.packages()`.\n\n", + "engine": "knitr", + "markdown": "---\ntitle: \"Coding Tips\"\n---\n\n\n\n\n### Welcome!\n\nThis page contains the collected best practice tips of the NCEAS Scientific Computing Support Team. More will be added over time and feel free to post [an issue](https://github.com/NCEAS/scicomp.github.io/issues) if you have a specific request for a section to add to this document.\n\nPlease feel free to reach out to our team (see [here](https://nceas.github.io/scicomp.github.io/staff.html)) if you have any questions about this best practices manual and/or need help implementing some of this content.\n\nCheck the headings below or in the table of contents on the right of this page to see which tips and tricks we have included so far and we hope this page is a useful resource to you and your team!\n\n## R Scripts versus R Markdowns\n\n\nWhen coding in R, either R scripts (.R files) or R markdowns (.Rmd files) are viable options but they have different advantages and disadvantages that we will cover below.\n\n### R Scripts - Positives\n\nR scripts' greatest strength is their flexibility. They allow you to format a file in whatever way is most intuitive to you. Additionally, R scripts can be cleaner for `for` loops insofar as they need not be concerned with staying within a given code chunk (as would be the case for a .Rmd). Developing a new workflow can be swiftly accomplished in an R script as some or all of the code in a script can be run by simply selecting the desired lines rather than manually running the desired chunks in a .Rmd file. Finally, R scripts can also be a better home for custom functions that can be `source`d by another file (even a .Rmd!) for making repeated operations simpler to read.\n\n### R Scripts - Potential Weaknesses\n\nThe benefit of extreme flexibility in R scripts can sometimes be a disadvantage however. We've all seen (and written) R scripts that have few or no comments or where lines of code are densely packed without spacing or blank lines to help someone new to the code understand what is being done. R scripts can certainly be written in a way that is accessible to those without prior knowledge of what the script accomplishes but they do not *enforce* such structure. This can make it easy, especially when we're feeling pressed for time, to exclude structure that helps our code remain reproducible and understandable.\n\n### R Markdowns - Positives\n\nR markdown files' ability to \"knit\" as HTML or PDF documents makes them extremely useful in creating outward-facing reports. This is particularly the case when the specific code is less important to communicate than visualizations and/or analyses of the data but .Rmd files do facilitate `echo`ing the code so that report readers can see how background operations were accomplished. The code chunk structure of these files can also nudge users towards including valuable comments (both between chunks and within them) though of course .Rmd files do not enforce such non-code content.\n\n### R Markdowns - Potential Weaknesses\n\nR markdowns can fail to knit due to issues even when the code within the chunks works as desired. Duplicate code chunk names or a failure to install LaTeX can be a frustrating hurdle to overcome between functioning code and a knit output file. When code must be re-run repeatedly (as is often the case when developing a new workflow) the stop-and-start nature of running each code chunk separately can also be a small irritation.\n\n### Script vs. Markdown Summary\n\nTaken together, both R scripts and R markdown files can empower users to write reproducible, transparent code. However, both file types have some key limitations that should be taken into consideration when choosing which to use as you set out to create a new code product.\n\n\n\n

\n\n

\n\n## File Paths\n\n\nThis section contains our recommendations for handling **file paths**. When you code collaboratively (e.g., with GitHub), accounting for the difference between your folder structure and those of your colleagues becomes critical. Ideally your code should be completely agnostic about (1) the operating system of the computer it is running on (i.e., Windows vs. Mac) and (2) the folder structure of the computer. We can--fortunately--handle these two considerations relatively simply.\n\nThis may seem somewhat dry but it is worth mentioning that failing to use relative file paths is a significant hindrance to reproducibility (see [Trisovic et al. 2022](https://www.nature.com/articles/s41597-022-01143-6)).\n\n### 1. Preserve File Paths as Objects Using `file.path`\n\nDepending on the operating system of the computer, the slashes between folder names are different (`\\` versus `/`). The `file.path` function automatically detects the computer operating system and inserts the correct slash. We recommend using this function and assigning your file path to an object.\n\n::: {.cell}\n\n```{.r .cell-code}\nmy_path <- file.path(\"path\", \"to\", \"my\", \"file\")\nmy_path\n```\n\n::: {.cell-output .cell-output-stdout}\n\n```\n[1] \"path/to/my/file\"\n```\n\n\n:::\n:::\n\nOnce you have that path object, you can use it everywhere you import or export information to/from the code (with another use of `file.path` to get the right type of slash!).\n\n::: {.cell}\n\n```{.r .cell-code}\n# Import\nmy_raw_data <- read.csv(file = file.path(my_path, \"raw_data.csv\"))\n\n# Export\nwrite.csv(x = data_object, file = file.path(my_path, \"tidy_data.csv\"))\n```\n:::\n\n### 2. Create Necessary Sub-Folders in the Code with `dir.create`\n\nUsing `file.path` guarantees that your code will work regardless of the upstream folder structure but what about the folders that you need to export or import things to/from? For example, say your `graphs.R` script saves a couple of useful exploratory graphs to the \"Plots\" folder, how would you guarantee that everyone running `graphs.R` *has* a \"Plots folder\"? You can use the `dir.create` function to create the folder in the code (and include your path object from step 1!).\n\n::: {.cell}\n\n```{.r .cell-code}\n# Create needed folder\ndir.create(path = file.path(my_path, \"Plots\"), showWarnings = FALSE)\n\n# Then export to that folder\nggplot2::ggsave(filename = file.path(my_path, \"Plots\", \"my_plot.png\"))\n```\n:::\n\nThe `showWarnings` argument of `dir.create` simply warns you if the folder you're creating already exists or not. There is no negative to \"creating\" a folder that already exists (nothing is overwritten!!) but the warning can be confusing so we can silence it ahead of time.\n\n### File Paths Summary\n\nWe strongly recommend following these guidelines so that your scripts work regardless of (1) the operating system, (2) folders \"upstream\" of the working directory, and (3) folders within the project. This will help your code by flexible and reproducible when others are attempting to re-run your scripts!\n\nAlso, for more information on how to read files in cloud storage locations such as Google Drive, Box, Dropbox, etc., please refer to our [Other Tutorials](https://nceas.github.io/scicomp.github.io/tutorials.html).\n\n\n\n

\n\n

\n\n## Good Naming Conventions\n\nWhen you first start working on a project with your group members, figuring out what to name your folders/files may not be at the top of your priority list. However, following a good naming convention will allow team members to quickly locate files and figure out what they contain. The organized naming structure will also allow new members of the group to be onboarded more easily! \n\nHere is a summary of some naming tips that we recommend. These were taken from the [Reproducibility Best Practices module](https://lter.github.io/ssecr/mod_reproducibility.html#naming-tips) in the LTER's SSECR course. Please feel free to refer to the aforementioned link for more information.\n\n- Names should be informative\n - An ideal file name should give some information about the file’s contents, purpose, and relation to other project files.\n - For example, if you have a bunch of scripts that need to be run in order, consider adding step numbers to the start of each file name (e.g., \"01_harmonize_data.R\" or \"step01_harmonize_data.R\"). \n- Names should avoid spaces and special characters\n - Spaces and special characters (e.g., é, ü, etc.) in folder/file names may cause errors when someone with a Windows computer tries to read those file paths. You can replace spaces with delimiters like underscores or hyphens to increase machine readability. \n- Follow a consistent naming convention throughout!\n - If you and your group members find a naming convention that works, stick with it! Having a consistent naming convention is key to getting new collaborators to follow it. \n \n\n\n\n## Package Loading\n\n\nLoading packages / libraries in R can be cumbersome when working collaboratively because there is no guarantee that you all have the same packages installed. While you could comment-out an `install.packages()` line for every package you need for a given script, we recommend using the R package `librarian` to greatly simplify this process!\n\n`librarian::shelf()` accepts the names of all of the packages--either CRAN or GitHub--installs those that are missing in that particular R session and then attaches all of them. See below for an example:\n\nTo load packages typically you'd have something like the following in your script:\n\n::: {.cell}\n\n```{.r .cell-code}\n## Install packages (if needed)\n# install.packages(\"tidyverse\")\n# install.packages(\"devtools\")\n# devtools::install_github(\"NCEAS/scicomptools\")\n\n# Load libraries\nlibrary(tidyverse); library(scicomptools)\n```\n:::\n\nWith `librarian::shelf()` however this becomes *much* cleaner! In addition to being fewer lines, using `librarian` also removes the possibility that someone running your code misses one of the packages that your script depends on and then the script breaks for them later on. `librarian::shelf()` automatically detects whether a package is installed, installs it if necessary, and then attaches the package.\n\nIn essence, `librarian::shelf()` wraps `install.packages()`, `devtools::install_github()`, and `library()` into a single, human-readable function.\n\n::: {.cell}\n\n```{.r .cell-code}\n# Install and load packages!\nlibrarian::shelf(tidyverse, NCEAS/scicomptools)\n```\n:::\n\nWhen using `librarian::shelf()`, package names do not need to be quoted and GitHub packages can be installed without the additional steps of installing the `devtools` package and using `devtools::install_github()` instead of `install.packages()`.\n\n", "supporting": [], "filters": [ "rmarkdown/pagebreak.lua" diff --git a/_freeze/modules_best-practices/file-paths/execute-results/html.json b/_freeze/modules_best-practices/file-paths/execute-results/html.json index 94f6c0f..c939b54 100644 --- a/_freeze/modules_best-practices/file-paths/execute-results/html.json +++ b/_freeze/modules_best-practices/file-paths/execute-results/html.json @@ -1,7 +1,8 @@ { "hash": "0b74bcb0ee0f9019d9c30ea7a67b3169", "result": { - "markdown": "\nThis section contains our recommendations for handling **file paths**. When you code collaboratively (e.g., with GitHub), accounting for the difference between your folder structure and those of your colleagues becomes critical. Ideally your code should be completely agnostic about (1) the operating system of the computer it is running on (i.e., Windows vs. Mac) and (2) the folder structure of the computer. We can--fortunately--handle these two considerations relatively simply.\n\nThis may seem somewhat dry but it is worth mentioning that failing to use relative file paths is a significant hindrance to reproducibility (see [Trisovic et al. 2022](https://www.nature.com/articles/s41597-022-01143-6)).\n\n### 1. Preserve File Paths as Objects Using `file.path`\n\nDepending on the operating system of the computer, the slashes between folder names are different (`\\` versus `/`). The `file.path` function automatically detects the computer operating system and inserts the correct slash. We recommend using this function and assigning your file path to an object.\n\n\n::: {.cell}\n\n```{.r .cell-code}\nmy_path <- file.path(\"path\", \"to\", \"my\", \"file\")\nmy_path\n```\n\n::: {.cell-output .cell-output-stdout}\n```\n[1] \"path/to/my/file\"\n```\n:::\n:::\n\n\nOnce you have that path object, you can use it everywhere you import or export information to/from the code (with another use of `file.path` to get the right type of slash!).\n\n\n::: {.cell}\n\n```{.r .cell-code}\n# Import\nmy_raw_data <- read.csv(file = file.path(my_path, \"raw_data.csv\"))\n\n# Export\nwrite.csv(x = data_object, file = file.path(my_path, \"tidy_data.csv\"))\n```\n:::\n\n\n### 2. Create Necessary Sub-Folders in the Code with `dir.create`\n\nUsing `file.path` guarantees that your code will work regardless of the upstream folder structure but what about the folders that you need to export or import things to/from? For example, say your `graphs.R` script saves a couple of useful exploratory graphs to the \"Plots\" folder, how would you guarantee that everyone running `graphs.R` *has* a \"Plots folder\"? You can use the `dir.create` function to create the folder in the code (and include your path object from step 1!).\n\n\n::: {.cell}\n\n```{.r .cell-code}\n# Create needed folder\ndir.create(path = file.path(my_path, \"Plots\"), showWarnings = FALSE)\n\n# Then export to that folder\nggplot2::ggsave(filename = file.path(my_path, \"Plots\", \"my_plot.png\"))\n```\n:::\n\n\nThe `showWarnings` argument of `dir.create` simply warns you if the folder you're creating already exists or not. There is no negative to \"creating\" a folder that already exists (nothing is overwritten!!) but the warning can be confusing so we can silence it ahead of time.\n\n### File Paths Summary\n\nWe strongly recommend following these guidelines so that your scripts work regardless of (1) the operating system, (2) folders \"upstream\" of the working directory, and (3) folders within the project. This will help your code by flexible and reproducible when others are attempting to re-run your scripts!\n\nAlso, for more information on how to read files in cloud storage locations such as Google Drive, Box, Dropbox, etc., please refer to our [Other Tutorials](https://nceas.github.io/scicomp.github.io/tutorials.html).", + "engine": "knitr", + "markdown": "\nThis section contains our recommendations for handling **file paths**. When you code collaboratively (e.g., with GitHub), accounting for the difference between your folder structure and those of your colleagues becomes critical. Ideally your code should be completely agnostic about (1) the operating system of the computer it is running on (i.e., Windows vs. Mac) and (2) the folder structure of the computer. We can--fortunately--handle these two considerations relatively simply.\n\nThis may seem somewhat dry but it is worth mentioning that failing to use relative file paths is a significant hindrance to reproducibility (see [Trisovic et al. 2022](https://www.nature.com/articles/s41597-022-01143-6)).\n\n### 1. Preserve File Paths as Objects Using `file.path`\n\nDepending on the operating system of the computer, the slashes between folder names are different (`\\` versus `/`). The `file.path` function automatically detects the computer operating system and inserts the correct slash. We recommend using this function and assigning your file path to an object.\n\n\n::: {.cell}\n\n```{.r .cell-code}\nmy_path <- file.path(\"path\", \"to\", \"my\", \"file\")\nmy_path\n```\n\n::: {.cell-output .cell-output-stdout}\n\n```\n[1] \"path/to/my/file\"\n```\n\n\n:::\n:::\n\n\nOnce you have that path object, you can use it everywhere you import or export information to/from the code (with another use of `file.path` to get the right type of slash!).\n\n\n::: {.cell}\n\n```{.r .cell-code}\n# Import\nmy_raw_data <- read.csv(file = file.path(my_path, \"raw_data.csv\"))\n\n# Export\nwrite.csv(x = data_object, file = file.path(my_path, \"tidy_data.csv\"))\n```\n:::\n\n\n### 2. Create Necessary Sub-Folders in the Code with `dir.create`\n\nUsing `file.path` guarantees that your code will work regardless of the upstream folder structure but what about the folders that you need to export or import things to/from? For example, say your `graphs.R` script saves a couple of useful exploratory graphs to the \"Plots\" folder, how would you guarantee that everyone running `graphs.R` *has* a \"Plots folder\"? You can use the `dir.create` function to create the folder in the code (and include your path object from step 1!).\n\n\n::: {.cell}\n\n```{.r .cell-code}\n# Create needed folder\ndir.create(path = file.path(my_path, \"Plots\"), showWarnings = FALSE)\n\n# Then export to that folder\nggplot2::ggsave(filename = file.path(my_path, \"Plots\", \"my_plot.png\"))\n```\n:::\n\n\nThe `showWarnings` argument of `dir.create` simply warns you if the folder you're creating already exists or not. There is no negative to \"creating\" a folder that already exists (nothing is overwritten!!) but the warning can be confusing so we can silence it ahead of time.\n\n### File Paths Summary\n\nWe strongly recommend following these guidelines so that your scripts work regardless of (1) the operating system, (2) folders \"upstream\" of the working directory, and (3) folders within the project. This will help your code by flexible and reproducible when others are attempting to re-run your scripts!\n\nAlso, for more information on how to read files in cloud storage locations such as Google Drive, Box, Dropbox, etc., please refer to our [Other Tutorials](https://nceas.github.io/scicomp.github.io/tutorials.html).", "supporting": [], "filters": [ "rmarkdown/pagebreak.lua" diff --git a/_freeze/modules_best-practices/pkg-loading/execute-results/html.json b/_freeze/modules_best-practices/pkg-loading/execute-results/html.json index bfa5757..8f5c582 100644 --- a/_freeze/modules_best-practices/pkg-loading/execute-results/html.json +++ b/_freeze/modules_best-practices/pkg-loading/execute-results/html.json @@ -1,6 +1,7 @@ { "hash": "ea1d300bfc65af384c36509a735900c2", "result": { + "engine": "knitr", "markdown": "\nLoading packages / libraries in R can be cumbersome when working collaboratively because there is no guarantee that you all have the same packages installed. While you could comment-out an `install.packages()` line for every package you need for a given script, we recommend using the R package `librarian` to greatly simplify this process!\n\n`librarian::shelf()` accepts the names of all of the packages--either CRAN or GitHub--installs those that are missing in that particular R session and then attaches all of them. See below for an example:\n\nTo load packages typically you'd have something like the following in your script:\n\n\n::: {.cell}\n\n```{.r .cell-code}\n## Install packages (if needed)\n# install.packages(\"tidyverse\")\n# install.packages(\"devtools\")\n# devtools::install_github(\"NCEAS/scicomptools\")\n\n# Load libraries\nlibrary(tidyverse); library(scicomptools)\n```\n:::\n\n\nWith `librarian::shelf()` however this becomes *much* cleaner! In addition to being fewer lines, using `librarian` also removes the possibility that someone running your code misses one of the packages that your script depends on and then the script breaks for them later on. `librarian::shelf()` automatically detects whether a package is installed, installs it if necessary, and then attaches the package.\n\nIn essence, `librarian::shelf()` wraps `install.packages()`, `devtools::install_github()`, and `library()` into a single, human-readable function.\n\n\n::: {.cell}\n\n```{.r .cell-code}\n# Install and load packages!\nlibrarian::shelf(tidyverse, NCEAS/scicomptools)\n```\n:::\n\n\nWhen using `librarian::shelf()`, package names do not need to be quoted and GitHub packages can be installed without the additional steps of installing the `devtools` package and using `devtools::install_github()` instead of `install.packages()`.\n", "supporting": [], "filters": [ diff --git a/_freeze/modules_tutorials/github-connect/execute-results/html.json b/_freeze/modules_tutorials/github-connect/execute-results/html.json index 3e93b6c..74a77ee 100644 --- a/_freeze/modules_tutorials/github-connect/execute-results/html.json +++ b/_freeze/modules_tutorials/github-connect/execute-results/html.json @@ -1,6 +1,7 @@ { "hash": "87d419837b2e5b1cb69cb0bc6e260ff3", "result": { + "engine": "knitr", "markdown": "\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\n::: {.cell}\n\n```{.r .cell-code}\n# Start a git repository on the \"main\" branch\ngit init -b main\n```\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\n::: {.cell}\n\n```{.r .cell-code}\n# Stage all files\ngit add .\n```\n:::\n\n\nOnce everything has been staged, **you now must commit those staged files** with a message.\n\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\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\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\n**Verify that URL** before continuing.\n\n\n::: {.cell}\n\n```{.r .cell-code}\n# Confirm that URL worked\ngit remote -v\n```\n:::\n\n\nFinally, **push your commited changes** to the repostory that you set as the remote in the preceding two steps.\n\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\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", "supporting": [], "filters": [ diff --git a/_freeze/modules_tutorials/googledrive-auth/execute-results/html.json b/_freeze/modules_tutorials/googledrive-auth/execute-results/html.json index 9883bd8..6f940d8 100644 --- a/_freeze/modules_tutorials/googledrive-auth/execute-results/html.json +++ b/_freeze/modules_tutorials/googledrive-auth/execute-results/html.json @@ -1,8 +1,11 @@ { "hash": "3fde62c40fe7ac0792286608d3336563", "result": { + "engine": "knitr", "markdown": "\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\n::: {.cell}\n\n```{.r .cell-code}\n# Install packages\ninstall.packages(c(\"googledrive\", \"httpuv\"))\n\n# Load them\nlibrary(googledrive)\n```\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\n::: {.cell}\n\n```{.r .cell-code}\ngoogledrive::drive_auth(email = \"enter your gmail here!\")\n```\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

", - "supporting": [], + "supporting": [ + "googledrive-auth_files" + ], "filters": [ "rmarkdown/pagebreak.lua" ], diff --git a/_freeze/modules_tutorials/googledrive-fxns/execute-results/html.json b/_freeze/modules_tutorials/googledrive-fxns/execute-results/html.json index dbe717c..e6ad45c 100644 --- a/_freeze/modules_tutorials/googledrive-fxns/execute-results/html.json +++ b/_freeze/modules_tutorials/googledrive-fxns/execute-results/html.json @@ -1,6 +1,7 @@ { "hash": "0efea0999008606750af05957b3fc20e", "result": { + "engine": "knitr", "markdown": "\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\n::: {.cell}\n\n```{.r .cell-code}\ndrive_url <- googledrive::as_id(\"your url here\")\n```\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\n::: {.cell}\n\n```{.r .cell-code}\ndrive_folder <- googledrive::drive_ls(path = drive_url)\ndrive_folder\n```\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\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

\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\n::: {.cell}\n\n```{.r .cell-code}\ngoogledrive::drive_download(file = drive_folder$id)\n```\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\n::: {.cell}\n\n```{.r .cell-code}\ngoogledrive::drive_download(file = drive_folder$id, \n path = \"your path here\")\n```\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\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\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\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", "supporting": [], "filters": [ diff --git a/_freeze/onboard-scaffold_team_coding/execute-results/html.json b/_freeze/onboard-scaffold_team_coding/execute-results/html.json index 9435953..c06d6f9 100644 --- a/_freeze/onboard-scaffold_team_coding/execute-results/html.json +++ b/_freeze/onboard-scaffold_team_coding/execute-results/html.json @@ -1,6 +1,7 @@ { "hash": "5852a8c1c451eb7cffb927e431517a97", "result": { + "engine": "knitr", "markdown": "---\ntitle: \"Team Coding: 5 Essentials\"\n---\n\n\nHave you ever had trouble running someone else's code or re-running your own old code? Working in a synthesis group can bring up challenges like these as members try to run workflows written by others or written by themselves at the last in-person meeting months ago. To make the process easier and more reproducible, here is a list of our top 5 best practices to follow as you collaborate on scripts that address your group's scientific questions. These are merely suggestions but we hope that they help facilitate seamless synthesis science!\n\n## 1. Prioritize 'Future You'\n\nIf something takes more time now but will work better in the long run, **invest the time now** to save yourself heartache in the future. This can apply to taking the time to make a document listing the scripts in a given workflow, adding descriptive comments in an existing script, and many other contexts. By investing this time now, you will save 'future you' from unnecessary labor.\n\n## 2. Always Leave Comments\n\n**Leave enough comments in your code** so that other members of your team (and 'future you'!) can understand what your script does. This is a crucial habit that will benefit you immensely. By making your code more human-readable, you open the door for improved communication among team members. This makes it easier for people who weren't involved in your workflow to jump in and give feedback if necessary or to onboard new team members who join later in the project. Plus, it is less of a hassle to edit and maintain well-commented code in the future; you can make changes without spending too much time deciphering each line of code.\n\n## 3. Use Relative File Paths\n\nWhen coding collaboratively, accounting for the difference between your folder structure and those of your colleagues becomes critical. For example, if you read in a data file using its absolute file path (e.g. \"/users/my_name/documents/project/data/raw_data/example.csv\"), only you will be able to successfully run that line of code and--by extension--your entire script! Also, the slashes between folder names are different depending on each person's computer operating system, which means even a relative file path will only work for your teammates that share your computer brand.\n\nIf you're an R user, there are two quick things you can do in your code to avoid these problems:\n\n### Relative Paths -- **Use the `dir.create` function [in your script]{.underline}** to create any necessary folders. \nNeed a data folder? Use `dir.create(\"data\")` and you'll create an empty data folder. Anyone else running your code will create the same folder and you can safely assume that part of the file path going forward.\n\n### Operating System Differences -- **Use the `file.path` function with folder names without slashes.** \nReading in data? Use `file.path(\"data\", \"raw_data\", \"site_a.csv\")` and `file.path` will automatically sense the computer's operating system and insert the correct slashes for each user.\n\nFor example, if you are already working in the directory called \"project\", then you can access example.csv using this relative file path: data/raw_data/example.csv. You can improve beyond even that by using the `file.path` function to automatically detect the computer operating system and insert the correct slash for you and anyone else running the code. We recommend using this function and assigning your file path to an object so you can use it anytime.\n\n\n::: {.cell}\n\n```{.r .cell-code}\nmy_path <- file.path(\"data\", \"raw_data\")\nmy_raw_data <- read.csv(file = file.path(my_path, \"example.csv\"))\n```\n:::\n\n\n## 4. Store Raw Data in the Cloud\n\nIf you're a GitHub user, you may be tempted to store your data files there, but GitHub limits the size of files allowed in repositories. Adding files larger than 50MB will receive a warning, and files larger than 100MB will be blocked. If you're working with big datasets or spatial data, you can exceed this limit pretty fast. \n\nTo avoid this, we recommend instead that you **store your raw data files in the cloud** and make them available to everyone in your group. For example, you can create a folder for raw data in a Shared Google Drive (which we can create for you!). Then, you can download the data using the `googledrive` R package or with any other Google Drive API in your preferred language. \n\n## 5. Meta-Document\n\nDocumenting every individual script is important, but it's also well worth the time and effort to **document the big picture of your workflow**. As you continue to build on your workflow, it can be hard to keep track of each script's role and how they relate to each other. You might need to update a script upstream and then try to figure out what other scripts downstream need to be updated next in order to account for the new edits. If you're not using a workflow management software, then it's best to thoroughly document how each script fits into the larger workflow. The README is a great place to document each step along the way.\n", "supporting": [], "filters": [ diff --git a/_freeze/portfolio/execute-results/html.json b/_freeze/portfolio/execute-results/html.json index 99d2097..9125887 100644 --- a/_freeze/portfolio/execute-results/html.json +++ b/_freeze/portfolio/execute-results/html.json @@ -1,10 +1,9 @@ { "hash": "2f56ea2947c31d237f0b2f9caa6e8778", "result": { + "engine": "knitr", "markdown": "---\ntitle: \"Portfolio\"\n---\n\n\n## Data Synthesizing\n\nWorking groups have often asked our team to synthesize and wrangle data from various heterogeneous datasets. For example, the [Plant Reproduction working group](https://lternet.edu/working-groups/identifying-environmental-drivers-of-plant-reproduction-across-lter-sites/) had their own plant species data that they compiled from literature and expert knowledge. To get more data, we pulled from the [TRY plant trait database](https://www.try-db.org/TryWeb/Home.php) and wrangled the dataset. After fixing the TRY column headers, values and units, we combined synonymous columns together with the working group's original dataset. We ended up with a comprehensive, tidy dataset that covered over 100 plant species. \n\nIn another example, the [Soil Phosphorus working group](https://lternet.edu/working-groups/soil-p-control-of-c-and-n/) had gathered a bunch of soil nutrient datasets that all had different column headers and units. To combine these datasets together, we standardized the column headers via a data key, which consisted of a spreadsheet connecting the old column names to the new combined column names. Then we were able to synthesize the separate csv files into one master dataset. \n\nData synthesizing remains one of our most popular requests so please do not hesitate to reach out to us if we can help with this task, no matter how big or small. \n\n## Spatial Analyses & Wrangling\n\nOur team has been instrumental in acquiring, wrangling, and summarizing spatial data. For the [Silica Exports working group](https://lternet.edu/working-groups/from-poles-to-tropics-a-multi-biome-synthesis-investigating-the-controls-on-river-si-exports/) we developed a workflow (see [here](https://github.com/lter/lterwg-si-export)) that accomplishes the following tasks:\n\n1. Creates shapefiles that identify the drainage basin linked to several hundred stream gages\n\n2. \"Cookie cuts\" spatial data within those drainage basins (e.g., land cover, lithology, precipitation, etc.)\n\n3. Summarizes that extracted data both as rasters and as data tables for use as explanatory variables in other analyses\n\nWe are comfortable working with such data and can help your team acquire and/or process spatial data if that is of interest!\n\n## Figures for Publication\n\nAdditionally, our team is available to help your group create visualizations for publications! We have generated many figures for the Plant Reproduction working group's paper on mast seeding synchrony using `ggplot`. Please feel free to reach out to us for help on visualizations when your team has reached the writing stage in your project. \n\n## Project Websites\n\nOur team also helped build [a website](https://lter.github.io/som-website/index.html) for the [Soil Organic Matter (SOM) working group](https://lternet.edu/working-groups/advancing-soil-organic-matter-research/). One of this group's primary products was a synthesized data package containing observed data, modifications of that data, and models based on them. The website operates in part to publicize this data product but also to provide a central location for other resources developed by or important to the SOM group. \n\nFor your group we can (if desired):\n\n- Build a website using [Quarto](https://quarto.org/)\n - All website content creation can be done via RStudio which your group may already be somewhat familiar with\n - Quarto also offers a new \"visual editor\" that lets you format text as you would in any word processor (i.e., Microsoft Word, Pages, etc.)\n- Maintain the website **OR** help *you* to maintain it\n - Quarto is written entirely in \"Markdown syntax\" which makes it easily maintained by either our team or yours depending on your preference\n - We have also created a [tutorial on making websites with Quarto](https://nceas.github.io/scicomp.github.io/tutorials.html#building-a-website-with-quarto) that you are welcome to explore!\n\n## R Packages\n\n\n\n#### `scicomptools`\n\nWhile much of the work we do is specific to a given working group or task, sometimes we realize afterwards that our functions have the potential to be useful beyond the scope for which they were initially written. To that end, we have created the R package [`scicomptools`](https://github.com/NCEAS/scicomptools#readme)!\n\n##### Package Description\n\nThis package contains a diverse mix of functions for everything from repetitive data wrangling tasks to checking whether you have a token attached for GitHub. In addition, functions that we wrote that are deprecated (usually because their internal workings have been superseded by packages on CRAN) are removed from the package but retained in the GitHub repository in case they are useful to you! **All functions--both live and deprecated--are summarized in the README on the [GitHub repository](https://github.com/NCEAS/scicomptools) so take a look!**\n\n##### Installation Instructions\n\nTo install the package in R, use the following:\n\n\n::: {.cell}\n\n```{.r .cell-code}\ninstall.packages(\"scicomptools\")\n```\n:::\n\n\n\n\n#### `HERON`\n\nWhen we've developed enough custom functions for a working group's workflow, we can move those functions into its very own R package! For example, we've created a package for the Silica Exports working group called `HERON` (\"HElpers for River ObservatioN\"). \n\n##### Package Description\n\nThis package contains several helper functions that are integral to the group's workflow, which includes identifying inflection points (i.e., hills & valleys) in trendlines and running separate regressions on each chunk of the line between such points. `HERON` is meant to be used for workflows involving the `EGRET` and `SiZer` R packages.\n\n##### Installation Instructions\n\nTo install the package in R, use the following:\n\n\n::: {.cell}\n\n```{.r .cell-code}\n# install.packages(\"devtools\")\ndevtools::install_github(\"lter/HERON\")\n```\n:::\n\n\n## R Shiny Apps\n\n\n\nOur team created another R package--`lterpalettefinder`--to extract color palettes from user-supplied photos. To help non-R users still explore this package and have fun pulling color palettes from photos, we created [this standalone Shiny app](https://cosima.nceas.ucsb.edu/lterpalettefinder-shiny/). This app lets anyone interact with `lterpalettefinder` via their browser with no R experience required!\n\nWe have also built apps to help working groups visualize data or present survey results in an interactive, visually-appealing format. Shiny apps can also include useful 'overview' portions that serve as an excellent landing page for third parties to your group's activities!\n\n\n", - "supporting": [ - "portfolio_files" - ], + "supporting": [], "filters": [ "rmarkdown/pagebreak.lua" ], diff --git a/_freeze/shiny-server/execute-results/html.json b/_freeze/shiny-server/execute-results/html.json index 114b8f4..8c9d766 100644 --- a/_freeze/shiny-server/execute-results/html.json +++ b/_freeze/shiny-server/execute-results/html.json @@ -1,6 +1,7 @@ { "hash": "e7f27b4540a1cd8130d897690e1a3ed4", "result": { + "engine": "knitr", "markdown": "---\ntitle: \"Deploy Shiny Apps\"\nengine: knitr\n---\n\n:::callout-note\nPlease note that the following instructions for deploying Shiny apps are meant to serve as internal documentation and will only work if you have `sudo` power on the SciComp team's Shiny server.\n\nFeel free to [contact us](https://nceas.github.io/scicomp.github.io/staff.html) if you have a LTER-related Shiny app that you would like to deploy on our server!\n:::\n\nSciComp team members can deploy LTER-related Shiny apps on our server at: [https://shiny.lternet.edu/](https://shiny.lternet.edu/)\n\nTo deploy your working app, first make sure that all the files live at a GitHub repository. Once our sysadmin Nick Outin has made you an account on the server, you can log in via SSH. \n\n## Log In\n\nFor Mac users, open the Terminal app and type the following command, replacing `` with your own username. \n\n::: {.cell}\n\n```{.bash .cell-code}\nssh @shiny.lternet.edu\n```\n:::\n\n\nWindows users can log in with [PuTTY](https://www.chiark.greenend.org.uk/~sgtatham/putty/), using shiny.lternet.edu as the host name. \n\nCheck out [NCEAS' guide to using SSH](https://help.nceas.ucsb.edu/NCEAS/Computing/connecting_to_linux_using_ssh) for additional help. \n\n## Set Up Proper Permissions\n\n### Join `shiny-apps`\n\nA `shiny-apps` user group has been created in this server. Set up the proper permissions for your account by adding yourself to this group with this command. \n\n::: {.cell}\n\n```{.bash .cell-code}\nsudo usermod -aG shiny-apps \n```\n:::\n\n\nTo decipher this command a bit: `sudo` will enable you to run commands as a user with full control and privileges. The `usermod` command is used to modify user account details. The basic syntax is:\n\n::: {.cell}\n\n```{.bash .cell-code}\nusermod [OPTIONS] \n```\n:::\n\n\nThe `-G` option will add the user to a supplementary group. The `-aG` combined options will add the user to the new supplementary group while also leaving them in the other supplementary group(s) they were already a part of.\n\n:::callout-note\nAs an FYI, the apps on the server will run as the user `shiny`, so `shiny` is also in the `shiny-apps` user group. \n:::\n\n### Allow Access to Your Home Directory\n\nAdditionally, you need to allow `shiny` access to your user home directory by running:\n\n::: {.cell}\n\n```{.bash .cell-code}\nsudo chmod a+x /home/\n```\n:::\n\n\nThis `chmod` (change mode) command is used to control file permissions. Basic syntax:\n\n::: {.cell}\n\n```{.bash .cell-code}\nchmod [OPTIONS] MODE FILE/DIRECTORY\n```\n:::\n\n\nThere are two \"modes\" that you can use to set permissions: Symbolic and Octal mode. The Symbolic mode uses operators and letters. For example, the `a` option denotes all the owner/groups the file/directory belongs to. The `+` operator grants the permission, and the letter `x` stands for the execute permission. \n\n\n## Tell `git` Who You Are\n\nNow that your account has the proper permissions, use the `git config` commands to tell `git` who you are.\n\n\n::: {.cell}\n\n```{.bash .cell-code}\ngit config --global user.name \"\"\ngit config --global user.email \"\"\n```\n:::\n\n\nReplace `` and `` with your own credentials. You can check to see if you entered your details correctly by entering `git config --list`.\n\n## Copy Your App to the Server\n\nThe easiest way to get all the files for your app to the server is by `git clone`. \n\nIf you like, you can create a folder named \"github\" to store all your future apps. For example, in the screenshot below, I created a \"github\" folder using the `mkdir` command in my home directory.\n\nTo check that the folder was created, I can list all the files/folders in my current directory with `ls`. Since I want my app to be inside the \"github\" folder, I used the `cd` command to change into that directory. \n\nFinally, `git clone` the GitHub repo that has all the files for your app. Here, I am cloning the [`lterpalettefinder-shiny`](https://github.com/lter/lterpalettefinder-shiny) repo to my local directory on the virtual machine as `lterpalettefinder`.\n\n\n\n:::callout-tip\nYou can go one level above the current directory by typing `cd ..`\n:::\n\n## Install Necessary R Packages\n\nAfter you cloned the repository for your app, you can start installing the necessary R packages! To make these packages available for all users, you will want to execute commands with the `root` user's privileges by typing the `sudo -i` command. Then open R by simply typing \"R\" and install packages with the usual `install.packages()` function. \n\n\n\n### Missing Dependencies? \n\nIf you run into an error installing a R package, it's likely because the server does not have the required dependencies installed yet. \n\nFor example, I wanted to install the `lterpalettefinder` R package, but I got lots of errors on missing dependencies instead. \n\n\n\nI saw that the `curl` dependency was missing, so I attempted to install that. However, R gives me another error. \n\n\n\nLooking closer, it asks me to install `libcurl4-openssl-dev` first. To install this Ubuntu package, I exited R with `q()` and logged off `root` with `exit`. Once I'm back in my own user profile, I can use the `sudo apt install` command to install `libcurl4-openssl-dev`.\n\n\n\nIf you get these prompts to restart services, you can tap Return/Enter to continue the installation. \n\n\n\n\n\nAfterwards, `libcurl4-openssl-dev` installed successfully, and then I can finally install the missing `curl` dependency in R! \n\n\n\nYou can repeat a similar process to find and install the rest of the required dependencies before you are able to install certain R packages. \n\n## Symlink to Deployed Folder\n\nSince all the Shiny apps are located under **/srv/shiny-server/**, how can we deploy the app we have in our local directory? We can create a symlink (symbolic link) between the local directory and **/srv/shiny-server/**. A symlink is essentially a pointer to other folders.\n\nCreate the link by running this command:\n\n::: {.cell}\n\n```{.bash .cell-code}\nsudo ln -s \n```\n:::\n\n\nReplace `` with your own directory and replace `` with the file path of where you would like your app to deploy. \n\nFor example, the actual `lterpalettefinder` app lives under my home directory, but it needs to be deployed under **/srv/shiny-server/**, so I ran this command to link the two:\n\n\n\nNow **/srv/shiny-server/lterpalettefinder** points to **/home/anchen/github/lterpalettefinder**! \n\nYou can check the current symlinks by navigating to **/srv/shiny-server/** and typing `ls -l`. \n\n:::callout-note\nThe name of the deployed folder corresponds to the URL: https://shiny.lternet.edu/\\/\n:::\n\n## Debug App and Check its Live Link\n\nIf everything goes right, your app will be live at https://shiny.lternet.edu/\\/! If not, don't worry and try troubleshooting what went wrong. Remember to check file paths and required R packages. ", "supporting": [], "filters": [ diff --git a/_freeze/tutorial-scaffold_jsonlite/execute-results/html.json b/_freeze/tutorial-scaffold_jsonlite/execute-results/html.json deleted file mode 100644 index d5922c3..0000000 --- a/_freeze/tutorial-scaffold_jsonlite/execute-results/html.json +++ /dev/null @@ -1,15 +0,0 @@ -{ - "hash": "c257d7f536b60ee9de5dabfadd0a2724", - "result": { - "engine": "knitr", - "markdown": "Working 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\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\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\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\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", - "supporting": [], - "filters": [ - "rmarkdown/pagebreak.lua" - ], - "includes": {}, - "engineDependencies": {}, - "preserve": {}, - "postProcess": true - } -} \ No newline at end of file diff --git a/_freeze/tutorial_json/execute-results/html.json b/_freeze/tutorial_json/execute-results/html.json new file mode 100644 index 0000000..d4805de --- /dev/null +++ b/_freeze/tutorial_json/execute-results/html.json @@ -0,0 +1,15 @@ +{ + "hash": "c257d7f536b60ee9de5dabfadd0a2724", + "result": { + "engine": "knitr", + "markdown": "Working 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\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\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\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\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", + "supporting": [], + "filters": [ + "rmarkdown/pagebreak.lua" + ], + "includes": {}, + "engineDependencies": {}, + "preserve": {}, + "postProcess": true + } +} \ No newline at end of file diff --git a/_freeze/tutorial_server/execute-results/html.json b/_freeze/tutorial_server/execute-results/html.json index 14e1667..7804366 100644 --- a/_freeze/tutorial_server/execute-results/html.json +++ b/_freeze/tutorial_server/execute-results/html.json @@ -1,6 +1,7 @@ { "hash": "986188c60cdd21b2947f38446e102d79", "result": { + "engine": "knitr", "markdown": "---\ntitle: \"Server Tutorial\"\n---\n\n\n## Overview\n\nWorking on [NCEAS' Server](https://aurora.nceas.ucsb.edu/) is similar to working on an entirely separate computer from the laptop or desktop computer on which you typically work. This means that you need to go through the steps of connecting GitHub to your \"RStudio\" again for the instance of RStudio accessed through Aurora. GitHub's Personal Access Token is referred to as \"token\" hereafter for simplicity. Note that our server also runs other analytical tools such as JupyterHub for python users.\n\nOften the reason to engage with the server is to increase the scale of your analyses far beyond what your personal computer can handle. There are other advantages such as:\n\n- **Storage Capacity** -- More disk space & faster storage\n- **Computing Power** -- More CPUs & RAM (384GB!!)\n- **Security** -- Nightly backups and data are distributed across multiple drives\n- **Collaboration** -- Shared data & consistent software versions accessible to everyone on your team\n\n## Server Workflow\n\nBefore diving into the process of getting set up on and using the server, it will be helpful to briefly consider what a workflow involving the server \"looks\" like! When you are working on the server you will need to consider what is stored on your personal computer (bottom left), on GitHub (bottom right), and on NCEAS' server (top).\n\nTo simplify, let's focus on (1) where your data live and (2) where your code lives.\n\n

\n\n

\n\n### Data\n\nYour data (or at least some of it) is likely on your personal computer. Those specific files are only accessible to you and you almost certainly have a file path to those data (i.e., levels of nested folders) that is unique to you. Even if you share the data file with someone on your team--via email or a cloud storage device--they will likely have to tweak any code that you share to ensure that the file paths are correct for their computer.\n\nWhen you involve the server, all of your group's data can live in a folder on the server within the `shares` folder. Only your group will have access to the data in that subfolder of `shares` . A huge advantage of this is that everyone in your group will now have the exact same file path to the data while working on the server.\n\nThis means that there is *no chance* that you can be working in the \"wrong\" version of the data (i.e., one that is outdated, doesn't reflect new metadata, etc.) because everyone is using the exact same file(s) rather than emailing static copies of data that may become outdated without warning.\n\n### Code\n\nWe strongly recommend that you use [GitHub](https://github.com/) to manage your code to streamline the use of either the server or your personal computer while collaborating with other group members.\n\nIf you are unfamiliar with git, it is a \"version control system\" that allows line-by-line tracking of changes to code. GitHub add features to git to enable multiple people to share and work on the same code which is very useful in collaborative contexts like working groups. Git and GitHub are not really meant to track or store data (though it can do this in a somewhat limited way) so notice that the **yellow** \"Data\" folder is absent from the bottom right part of the triangle. We offer [an entire workshop on GitHub](https://nceas.github.io/scicomp-workshop-collaborative-coding/) that we are happy to offer to your group if that is of interest so just let us know!\n\nAssuming that you use GitHub, your code (and its history) will be preserved there. You can then write or edit code either on your personal computer or on the server. Regardless of where you make the changes, so long as you connect both your personal computer and your server profile to your GitHub account, you will have a centralized place for all of your code that is accessible to both workspaces.\n\nNotice that on the server, your code will be in your subfolder of the `home` folder on the server. Only you can access this folder and you will be leveraging GitHub to share your code with others! This means that everyone in your group can have their own code files while every copy of those scripts can use the file path in the `shares` folder to access the data files. In other words, use GitHub to share your code stored in your home folder and your group shared folder to share data.\n\nA final advantage in the 'code' realm is that the server has a consistent version of R, RStudio, and `git` (the program underpinning GitHub) so there is no chance that a software version difference can affect different members of your group differently.\n\n## Getting Set Up\n\n### Necessary Software\n\nThe only software that you will need on your personal computer to get set up on NCEAS' server is RStudio!\n\nYou likely have worked in the \"Console\" tab of RStudio (where run lines and outputs appear; see below) but RStudio has another tab to the right of the \"Console\" called \"Terminal\" which offers RStudio users access to the **command line** (a.k.a. the **shell**). If you are a veteran command line user you may prefer to use the standalone Terminal app on MacOS or [PuTTY](https://www.chiark.greenend.org.uk/~sgtatham/putty/) on Windows but for the sake of keeping your tool kit streamlined, we'll walk through getting set up on NCEAS' server using only RStudio's Terminal tab.\n\n

\n\n

\n\nThe Terminal does not accept R syntax (and the Console doesn't accept Terminal syntax) so you may notice that some of the code we'll walk you through below is formatted differently than you would write an R script.\n\n

\n\n

\n\n### Get Invited!\n\nIn order to access the server (and follow the instructions below) we'll need to create an account on the server for you. Please email [someone on our team](https://nceas.github.io/scicomp.github.io/staff.html) or **scicomp@nceas.ucsb.edu** so that we can contact NCEAS' IT team and get an invite email sent to you.\n\nIn that email, please include the name and email addresses of all of your team members who want to access the server. After that information has been received, NCEAS' IT team will create accounts for all of those people and will send you an invitation email to set up your account on the server.\n\nAn example of what that email may look like is included below but there are two key pieces of information:\n\n1. Your username\n2. Your temporary password (covered by a **red bar** in the screenshot).\n\nIf you have not received that email, check your Spam folder for emails from Thomas Hetmank (hetmank@nceas.ucsb.edu) or Nick Outin (outin@nceas.ucsb.edu). If you have not received the email and it is not in your Spam, reach out to our team and we will work to get an invite sent to you.\n\n

\n\n

\n\n### Setting your Password\n\n#### Note on this Step of the Set Up\n\nNote that _you only have to set your password once!_ For security, when we create your account on the server we create a temporary password that can only be used once (see the invite email screenshot above). So, when you first login to the server by following the instructions below, you'll need to create a \"real\" (i.e., non-temporary) password. Subsequent sign-ins to the server do not require this 'Setting your Password' section at all!\n\nIn the following instructions we use text formatting to explain what you should type.\n\n1. Text `like this` should be typed into the Terminal tab of Rstudio\n\n - Run it by pressing \"enter\" or \"return\"\n - Note that typing these commands into an R script or R Markdown *will not work* because it will attempt to run in the Console rather than the Terminal\n\n2. Text wrapped by brackets `[like this]` should also be typed in the Terminal tab **BUT** you should replace the text in brackets in a user-specific way that is clarified in the nearby text\n\n#### Password Setting Instructions\n\n1. In the Terminal pane of RStudio, you will \"ssh\" into the server by running the following code: `ssh [your username]@aurora.nceas.ucsb.edu`. It is \"@aurora\" because **the name of the server is Aurora**.\n\n2. You will need to enter `yes` to accept the server's SSH key.\n\n3. You will then be prompted to enter your `[temporary password]` (see the above email example). **Note that the cursor will not advance as you type but it is registering your entries!** There will be no indication that you are typing (such as: \"•••••••••\"). This throws off many users so hopefully this note helps set your mind at ease!\n\nNext, you will be prompted to change your \"expired\" password. We consider your temporary password to be expired as soon as you use it because sharing passwords via email is not secure and this \"expiration\" lets you set the password to something that only you know at the outset of your time in the server. **Note again that the cursor will not advance as you type but it is working!** \n\n4. To update your password, (i) enter your `[temporary password]`, then (ii) `[your strong new password]` and finally (iii) re-type `[your strong new password]` to confirm it. Note that your new password should not be \"your strong new password\" {{< fa face-smile >}}\n\n5. You are all set up! Run `exit` to log out of the server in the Terminal tab.\n\n## Accessing the Server\n\n1. Use your favorite web browser (e.g., Firefox, Chrome, etc.) to access Aurora at [aurora.nceas.ucsb.edu](https://aurora.nceas.ucsb.edu/) and click \"Login to RStudio Server\"\n\n

\n\n

\n\n2. Sign in with your username and the password that you created in the \"Getting Set Up\" section of this tutorial.\n\n

\n\n

\n\nYou should now be in something that looks very much like RStudio but is housed in a tab on your browser!\n\n

\n\n

\n\nIf the above steps have not resulted in successfully accessing Aurora, consult [NCEAS' instructions on first login](https://help.nceas.ucsb.edu/NCEAS/Computing/first_login_to_nceas_analytical_server) and/or [SSH-specific instructions for Mac vs. Windows](https://help.nceas.ucsb.edu/NCEAS/Computing/connecting_to_linux_using_ssh.html) and/or email us!\n\n## Connecting GitHub\n\nAs stated at the beginning of this tutorial, we cannot overstate how strongly we suggest integrating [GitHub](https://github.com/) into your collaborative coding process. We are happy to work through [our GitHub tutorial](https://nceas.github.io/scicomp-workshop-collaborative-coding/) if that is of interest though you may find walking through the materials at your own pace helpful even without a formal workshop!\n\nWhen setting up `git`/GitHub on your personal computer, you normally have to install R, RStudio, `git`, and make an account on GitHub. When working on the server, R, RStudio, and `git` are already successfully installed and ready for you to use. So, to begin connecting your server profile with GitHub you need only follow these steps:\n\n1. **[Create a GitHub account](https://happygitwithr.com/github-acct.html)** using the web browser of your choosing.\n\n2. Install and load the `usethis` and `gitcreds` packages \n\n\n::: {.cell}\n\n```{.r .cell-code}\ninstall.packages(c(\"usethis\", \"gitcreds\"))\nlibrary(usethis); library(gitcreds)\n```\n:::\n\n\n3. Tell the server your GitHub username and email\n\n\n::: {.cell}\n\n```{.r .cell-code}\nusethis::use_git_config(user.name = \"Your GitHub Username\",\n user.email = \"Your GitHub Email\")\n```\n:::\n\n\n4A. Create a Personal Access Token (PAT) on GitHub for your server profile. Note: running the below line of code will open a browser window for you to create a token on GitHub! For additional information, see [GitHub's PAT Tutorial](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) or the [Happy Git with R PAT Tutorial](https://happygitwithr.com/https-pat.html).\n\n\n::: {.cell}\n\n```{.r .cell-code}\nusethis::create_github_token()\n## Be sure to copy the token when you're done!!!\n## It will be a long string of letters and numbers\n```\n:::\n\n\n4B. Before you navigate away from the token page, copy the token and paste it somewhere safe for the rest of these setup instructions. If you close or leave the window without copying the token, you will not be able to see the token again so you'd have to make a new one to complete the next step.\n\n5. Next, give your server profile the token you just created! Running the below line of code will prompt you to paste your token into the Console and hit enter. Note that your token *should not* be in quotes when you give it to the Console.\n\n\n::: {.cell}\n\n```{.r .cell-code}\ngitcreds::gitcreds_set()\n```\n:::\n\n\nAt the end of the above steps your token should be set! You should now be able to interact with code that you can access on GitHub directly from the server.\n\n6. Finally, in the Terminal pane of RStudio you need to tell the server to \"remember\" your token for some set amount of time.\n\n\n::: {.cell}\n\n```{.bash .cell-code}\ngit config --global credential.helper 'cache --timeout=10000000'\n```\n:::\n\n\nThe `timeout` bit of that argument is the amount of time in minutes you want your token to be remembered. You can't set it to remember your token forever so 10 million minutes (just over 19 years) should be long enough that you don't need to worry about this again.\n\n## Uploading Data\n\n### Via RStudio\n\nIf you are uploading a single file, it may be most convenient to use RStudio's data upload capabilities. In the \"Files\" pane (default is top right but it may differ on your computer), you can click the button that is a white rectangle with a **yellow** circle with an upward facing arrow inside of it. In the below image the relevant button is in a **red** square.\n\n

\n\n

\n\nClicking that button allows you to choose (1) where you want the uploaded file to go and (2) which file you want to upload.\n\n

\n\n

\n\nYou can also download data via the RStudio interface. To download a file, check the box next to it in the \"Files\" pane.\n\n

\n\n

\n\nOnce the box is checked, click the gear icon then click the \"Export...\" option (about halfway down). In the image below this option is surrounded by a **red** square\n\n

\n\n

\n\nIn the resulting box you can choose to rename the file before downloading to your local computer. After renaming the file (or keeping its original name), click the \"Download\" button and the download should begin after a moment.\n\n

\n\n

\n\nThese methods are effective for one or a few files being up/downloaded to the same directory but can quickly become cumbersome if you want to handle many files or a few files to several different folders.\n\n### Via sFTP Software\n\nIf you want to upload or download many files we recommend using sFTP software (secure File Transfer Protocol). We use [Cyberduck](https://cyberduck.io/) internally, though there are alternatives like [WinSCP](https://winscp.net/eng/index.php). Both programs are free to use and more than capable of uploading and download many files to/from the server quickly and easily.\n\nOnce you have installed one of these programs, you can sign in to the server from the sFTP program using your server username and password and can then upload or download files from your personal computer in the same way as you would move files among folders within your personal computer.\n\n#### Cyberduck Set Up Tutorial\n\nHere we briefly demonstrate how to set up a connection between Cyberduck and NCEAS' Server. Note that you must have already installed Cyberduck to follow these steps.\n\n1. In the Cyberduck window, click the \"Open Connection\" button with an icon of a globe with a plus sign. In the below image the button has a **red** square around it.\n\n

\n\n

\n\n2. In the resulting window, input the following information:\n\n - \"Server\" -- \"aurora.nceas.ucsb.edu\"\n - \"Username\" -- whatever your username on the server is\n - \"Password\" -- your password to the server\n - \"Port\" -- change it to \"22\" (it will start as \"21\")\n\n

\n\n

\n\n3. Also, click the dropdown menu at the top that says \"FTP (File Transfer Protocol) and select \"SFTP (SSH File Transfer Protocol)\" from the set of available options.\n\n

\n\n

\n\n4. Once you've input the above information, click the \"Connect\" button and you should have access to the server! You can now click around the different folders you have access to and upload or download from there.\n\n- To download: click the files/folders that you want and they should begin downloading to your personal computer\n- To upload: drag and drop the files where you want them\n\n### Via the Command Line\n\nIf you are more comfortable with a CLI (Command Line Interface) you can also use that method of uploading/downloading. The command line includes the Terminal pane in RStudio, Terminal app for Macs, PuTTY, and gitBash among others. CLI can be a great tool to leverage filenames or types to filter specific files you would like to upload / download. Text in code chunks below are command line commands and any bracketed text `[like this]` should be replaced by some user-specific information before running.\n\nThis portion of the tutorial is focused on using the command line to interact with the server. That said, if you're interested in the command line more generally or for other purposes, please reach out to [our team](https://nceas.github.io/scicomp.github.io/staff.html)!\n\n#### CLI Option A: `scp`\n\nThe `scp` command can be used to *upload* a file or folder from your computer to the server.\n\n1A. Navigate to the folder on your computer containing the file(s) you want to upload\n\n\n::: {.cell}\n\n```{.bash .cell-code}\ncd [folder]\n```\n:::\n\n\n- Note that if the folder name has spaces you'll need to \"escape\" the space by using a backslash (`\\`)\n\n\n::: {.cell}\n\n```{.bash .cell-code}\ncd [folder\\ name]\n```\n:::\n\n\n2A. Now you can upload that file to the server!\n\n\n::: {.cell}\n\n```{.bash .cell-code}\nscp [file_name] [user]@aurora.nceas.ucsb.edu:/[path/to/destination_folder/]\n```\n:::\n\n\nIf instead you'd like to upload all of the files in a folder, do the following:\n\n1B. Navigate to the folder containing the folder on your computer you want to upload (using `cd`)\n\n\n::: {.cell}\n\n```{.bash .cell-code}\ncd [folder]\n```\n:::\n\n\n2B. Use `scp` with the recursive option (`-r`) to upload all of the files in that folder\n\n\n::: {.cell}\n\n```{.bash .cell-code}\nscp -r [folder] [user]@aurora.nceas.ucsb.edu:/[path/to/destination_folder/]\n```\n:::\n\n\n- Note that this uploads all of the files in the folder *not* the folder itself so you may want to create a new folder on the server to upload your local folder's contents into.\n\nFinally, note that you can also *download* files from the server to your local machine by simply switching the order of the machines:\n\n\n::: {.cell}\n\n```{.bash .cell-code}\nscp [user]@aurora.nceas.ucsb.edu:/[path/to/server_folder/file_name] [local_folder] \n```\n:::\n\n\n#### CLI Option B: `sftp`\n\nThe `get` command can be used to *download* a file.\n\n1. Connect to the server\n\n\n::: {.cell}\n\n```{.bash .cell-code}\nsftp [user]@aurora.nceas.ucsb.edu:/home/shares\n```\n:::\n\n\nYour prompt at the shell should now have switched to `sftp>` and although it is the same window you are now looking at the files on the server! Try it by typing the `ls` command at the prompts. This will list all the files and folders within the `shares` folder on Aurora.\n\n2. Enter your group's folder in the `shares` folder\n\n\n::: {.cell}\n\n```{.bash .cell-code}\ncd [your_group_folder]\n```\n:::\n\n\n3. If needed, continue using `cd` to get to the subfolder you want to access. Remember to \"escape\" any spaces in the folder name with backslashes!\n\n\n::: {.cell}\n\n```{.bash .cell-code}\ncd [subfolder]\n```\n:::\n\n\nNote that most of the bash command will work, so you can use `ls` to list files and `pwd` to check your current path.\n\n4. When you are in the folder containing the file(s) you want, download the file you want\n\n\n::: {.cell}\n\n```{.bash .cell-code}\nget [file_name_server]\n```\n:::\n\n\n5. You can also upload a local file to the server by using the `put` sFTP command\n\n\n::: {.cell}\n\n```{.bash .cell-code}\nput [file_name_local]\n```\n:::\n\n\n6. When you are done downloading, close the connection to the server\n\n\n::: {.cell}\n\n```{.bash .cell-code}\nexit\n```\n:::\n", "supporting": [], "filters": [ From b386a184dcb4f9c0e6bf3f27e6d3d6df8b5b0b2c Mon Sep 17 00:00:00 2001 From: njlyon0 Date: Wed, 1 May 2024 15:57:33 -0400 Subject: [PATCH 11/11] Tweaking website render GitHub Action to run on pull requests --- .github/workflows/publish.yml | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 77d7fc0..182fe98 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -1,7 +1,11 @@ on: - workflow_dispatch: push: - branches: main + branches: [main, master] + pull_request: + branches: [main, master] + release: + types: [published] + workflow_dispatch: name: Quarto Publish