tutorial_json.qmd

---
title: "Storing User-Specific Information with JSONs"
code-overflow: wrap
---

## Overview 

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 <u>you and your group members do not have to manually change _any user-specific information_ in scripts</u> 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://posit.co/downloads/)
- Install the `ltertools` and `RJSONIO` R packages

Feel free to skip any steps that you have already completed!

### 1. Discuss with Your Group

As in so many facets of collaborative work, the first step is to discuss with your group. While JSONs are useful for storing user-specific information, **you and your group still need to agree on two pieces of information**:

1. <u>What is the name of the JSON file that each person will have?</u>
    - A consistent file name lets all scripts expect the same file even though the _contents_ of that file differ for each user
2. <u>What are the 'column names' that contain the information your group wants to store?</u>
    - Consistent 'column names' allow scripts to find the user-specific content they need under a predictable subheading

We recommend keeping it simple so **consider naming the file "user.json"**. Similarly, **for the 'column names' consider short, all-lowercase names that are succinct and clear** (e.g., `dropbox_path` for each user's path to a local Dropbox sync, `email` for each user's email address, etc.).

### 2. Create the JSON

We have developed the [`ltertools` R package](https://github.com/lter/ltertools)--in part--to store content that is useful to collaborative teams. Among the functions included in that package is one called `make_json` that will make the JSON for each user. It accepts a "named" vector which is straightforward to create.

```{r make-json-1}
# Create the named vector
my_info <- c("dropbox_path" = "~/Users/lyon/Dropbox/LTER Data/", 
             "email" = "lyon@nceas.ucsb.edu")

# Look at it
my_info
```

Once you have that vector prepared, it's time to use `make_json` to actually create the file that stores user-specific information. If you are working in GitHub, we recommend setting the `git_ignore` argument to `TRUE` so that the JSON you create is automatically ignored by Git. This will prevent someone from accidentally sending sensitive (or at least user-specific) information to GitHub. For a deeper dive on this topic, see our GitHub workshop [here](https://lter.github.io/workshop-github/git_ignore.html)

```{r make-json-2}
#| eval: false

# Load package
library(ltertools)

# Make JSON
make_json(x = my_info, file = "user.json", git_ignore = TRUE)
```

### 3. Benefit from the JSON!

Now that all group members have made a JSON with the same internal components, all that is left is to reap the rewards of your forward thinking!

See an example below:

```{r read-json}
#| eval: false

# Load needed library
library(RJSONIO)

# Read in the JSON file
user_info <- RJSONIO::fromJSON(content = "user.json")

# Use its contents!
my_data <- read.csv(file = file.path(user_info$dropbox_path, "2024_data.csv"))

# Syntax is just like how you'd access a column in a dataframe
googledrive::drive_auth(email = user_info$email)
```

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.

### Bonus: Help with Finding File Paths

Identifying and manually writing out the file path you want to preserve in a JSON can be cumbersome so we've found a nice work-around (at least for Mac users) that you may find useful. 

1. Open Finder and navigate to the last folder in the file path (i.e.,  the most nested one)
2. In the row of folder names in the bottom of the Finder window, right-click the folder name and select "Copy '\<folder name\>' as Pathname"
3. Paste this into the vector you plan on giving to `make_json`

<p align="center">
<img src="images/tutorial_jsonlite/jsonlite-1.png" alt = "Demonstration of how to copy the full file path for a specified folder in Mac's Finder. Simply a visual representation of the numbered steps directly above this image" width = "75%"/>
</p>