Skip to content

Commit

Permalink
Merge pull request #708 from cklunch/main
Browse files Browse the repository at this point in the history 
API token tutorial update
  • Loading branch information
@cklunch
cklunch authored Dec 31, 2024
2 parents 6a4d764 + 397aa1d commit b28b26a
Show file tree
Hide file tree
Showing 7 changed files with 338 additions and 1,223 deletions.
4 changes: 2 additions & 2 deletions processing_code/01knit-RMD-2-MD_NDSRepo.R
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,15 +16,15 @@ require(markdown)
dirs <- c("R/NEON-general/neon-overview/NEON-download-explore",
"R/AIS-data/AIS-QF-tutorial/clean-NEON-AIS-data",
"R/NEON-general/neon-code-packages/neonUtilities",
"R/NEON-general/neon-overview/neon-maps",
"R/NEON-general/neon-code-packages/NEON-API-Token/neon-api-tokens-tutorial",
"R/Phenocam/phenocam-tools/getting-started-phenocamapi",
"/Other/Concept-intros/test_tabs_figures")

#################### Set up Input Variables #############################

# set directory (order above) that you'd like to build

subDir <- dirs[5]
subDir <- dirs[4]

# Inputs - Where the git repo is on your computer
gitRepoPath <-"~/GitHub/NEON-Data-Skills"
Expand Down
246 changes: 4 additions & 242 deletions ...-general/neon-code-packages/NEON-API-Token/neon-api-tokens-tutorial/neon-api-tokens-0.Rmd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,254 +16,16 @@ urlTitle: neon-api-tokens-tutorial

---

NEON data can be downloaded from either the NEON Data Portal or the NEON API.
When downloading from the Data Portal, you can create a user account. Read
about the benefits of an account on the <a href="https://www.neonscience.org/data/about-data/data-portal-user-accounts" target="_blank">User Account page</a>. You can also use your account to create a token for using the
API. Your token is unique to your account, so don't share it.
```{r setup, echo=FALSE}
Using a token is optional! You can download data without a token, and
without a user account. Using a token when downloading data via the API,
including when using the neonUtilities package, links your downloads to
your user account, as well as enabling faster download speeds. For more
information about token usage and benefits, see the
<a href="https://data.neonscience.org/data-api" target="_blank">NEON API documentation</a> page.

For now, in addition to faster downloads, using a token helps NEON to track
data downloads. Using **anonymized** user information, we can then calculate
data access statistics, such as which data products are downloaded most
frequently, which data products are downloaded in groups by the same users,
and how many users in total are downloading data. This information helps NEON
to evaluate the growth and reach of the observatory, and to advocate for
training activities, workshops, and software development.

Tokens can be used whenever you use the NEON API. In this tutorial, we'll
focus on using tokens with the neonUtilities R package.

<div id="ds-objectives" markdown="1">

## Objectives
After completing this activity, you will be able to:

* Create a NEON API token
* Use your token when downloading data with neonUtilities

## Things You’ll Need To Complete This Tutorial
You will need a version of R (3.4.1 or higher) and, preferably, `RStudio`
loaded on your computer to complete this tutorial.

### Install R Packages

* **neonUtilities:** `install.packages("neonUtilities")`

## Additional Resources

* NEON <a href="http://data.neonscience.org" target="_blank"> Data Portal </a>
* <a href="https://github.com/NEONScience" target="_blank">NEONScience GitHub Organization</a>
* <a href="https://www.neonscience.org/neonDataStackR" target="_blank">neonUtilities tutorial</a>

</div>

If you've never downloaded NEON data using the neonUtilities package before,
we recommend starting with the <a href="https://www.neonscience.org/download-explore-neon-data" target="_blank">Download and Explore tutorial</a> before proceeding with this tutorial.

In the next sections, we'll get an API token from the NEON Data Portal, and
then use it in neonUtilities when downloading data.

## Get a NEON API Token

The first step is create a NEON user account, if you don't have one.
Follow the instructions on the <a href="https://www.neonscience.org/data/about-data/data-portal-user-accounts" target="_blank">Data Portal User Accounts</a> page. If you do already
have an account, go to <a href="https://data.neonscience.org/home" target="_blank">the NEON Data Portal</a>,
sign in, and go to your My Account profile page.

Once you have an account, you can create an API token for yourself. At
the bottom of the My Account page, you should see this bar:

<figure>
<a href="https://raw.githubusercontent.com/NEONScience/NEON-Data-Skills/dev-aten/graphics/NEON-api-token/get-api-token-button.png">
<img src="https://raw.githubusercontent.com/NEONScience/NEON-Data-Skills/dev-aten/graphics/NEON-api-token/get-api-token-button.png" alt="Account page on NEON Data Portal showing Get API Token button."></a>
</figure>

Click the 'GET API TOKEN' button. After a moment, you should see this:

<figure>
<a href="https://raw.githubusercontent.com/NEONScience/NEON-Data-Skills/dev-aten/graphics/NEON-api-token/account-page-token-view.png">
<img src="https://raw.githubusercontent.com/NEONScience/NEON-Data-Skills/dev-aten/graphics/NEON-api-token/account-page-token-view.png" alt="Account page on NEON Data Portal showing API token has been created."></a>
</figure>

Click on the Copy button to copy your API token to the clipboard:

<figure>
<a href="https://raw.githubusercontent.com/NEONScience/NEON-Data-Skills/dev-aten/graphics/NEON-api-token/api-token-copy-button.png">
<img src="https://raw.githubusercontent.com/NEONScience/NEON-Data-Skills/dev-aten/graphics/NEON-api-token/api-token-copy-button.png" alt="Account page on NEON Data Portal showing API token with Copy button highlighted"></a>
</figure>

## Use API token in neonUtilities

In the next section, we'll walk through saving your token somewhere secure but
accessible to your code. But first let's try out using the token the easy way.

First, we need to load the `neonUtilities` package and set the working
directory:

```{r loadStuff, eval=FALSE, comment=NA}
# install neonUtilities - can skip if already installed, but
# API tokens are only enabled in neonUtilities v1.3.4 and higher
# if your version number is lower, re-install
install.packages("neonUtilities")
# load neonUtilities
library(neonUtilities)
# set working directory
wd <- "~/data" # this will depend on your local machine
setwd(wd)
```

NEON API tokens are very long, so it would be annoying to keep pasting the
entire text string into functions. Assign your token an object name:

```{r nameToken, eval=FALSE, comment=NA}
NEON_TOKEN <- "PASTE YOUR TOKEN HERE"
```

Now we'll use the `loadByProduct()` function to download data. Your
API token is entered as the optional `token` input parameter. For
this example, we'll download Plant foliar traits (DP1.10026.001).

```{r getCFC, eval=FALSE, comment=NA}
foliar <- loadByProduct(dpID="DP1.10026.001", site="all",
package="expanded", check.size=F,
token=NEON_TOKEN)
```

You should now have data saved in the `foliar` object; the API
silently used your token. If you've downloaded data without a
token before, you may notice this is faster!

This format applies to all `neonUtilities` functions that involve
downloading data or otherwise accessing the API; you can use the
`token` input with all of them. For example, when downloading
remote sensing data:

```{r getAOP, eval=FALSE, comment=NA}
chm <- byTileAOP(dpID="DP3.30015.001", site="WREF",
year=2017, check.size=F,
easting=c(571000,578000),
northing=c(5079000,5080000),
savepath=wd,
token=NEON_TOKEN)
```

## Token management for open code

Your API token is unique to your account, so don't share it!

If you're writing code that will be shared with colleagues or available
publicly, such as in a GitHub repository or supplemental materials of a
published paper, you can't include the line of code above where we assigned
your token to `NEON_TOKEN`, since your token is fully visible in the code
there. Instead, you'll need to save your token locally on your computer,
and pull it into your code without displaying it. There are a few ways to
do this, we'll show two options here.

* Option 1: Save the token in a local file, and `source()` that file at the
start of every script. This is fairly simple but requires a line of code in
every script.

* Option 2: Add the token to a `.Renviron` file to create an environment
variable that gets loaded when you open R. This is a little harder to set
up initially, but once it's done, it's done globally, and it will work in
every script you run.

## Option 1: Save token in a local file

Open a new, empty R script (.R). Put a single line of code in the script:

```{r scriptToSource, eval=FALSE, comment=NA}
NEON_TOKEN <- "PASTE YOUR TOKEN HERE"
library(htmltools)
```

Save this file in a logical place on your machine, somewhere that won't be
visible publicly. Here, let's call the file `neon_token_source.R`, and
save it to the working directory. Then, at the start of
every script where you're going to use the NEON API, you would run this line
of code:

```{r source, eval=FALSE, comment=NA}
```{r html, echo=FALSE, warning=FALSE, message=FALSE}
source(paste0(wd, "/neon_token_source.R"))
htmltools::includeHTML("https://raw.githubusercontent.com/NEONScience/NEON-Data-Skills/refs/heads/main/tutorials/R/NEON-general/neon-code-packages/NEON-API-Token/neon-api-tokens-tutorial/neon-api-tokens-content.html")
```

Then you'll be able to use `token=NEON_TOKEN` when you run `neonUtilities`
functions, and you can share your code without accidentally sharing your
token.

## Option 2: Save token to the R environment

To create a persistent environment variable, we use a `.Renviron` file.
Before creating a file, check which directory R is using as your home
directory:

```{r getdir, eval=FALSE, comment=NA}
# For Windows:
Sys.getenv("R_USER")
# For Mac/Linux:
Sys.getenv("HOME")
```

Check the home directory to see if you already have a `.Renviron` file, **using
the file browse pane in RStudio**, or using another file browse method with
hidden files shown. Files that begin with `.` are hidden by default, but
RStudio recognizes files that begin with `.R` and displays them.

<figure>
<a href="https://raw.githubusercontent.com/NEONScience/NEON-Data-Skills/dev-aten/graphics/NEON-api-token/R-environ-file-browse.png">
<img src="https://raw.githubusercontent.com/NEONScience/NEON-Data-Skills/dev-aten/graphics/NEON-api-token/R-environ-file-browse.png" alt="File browse pane in RStudio showing .Renviron file."></a>
<figcaption>Screenshot of file browse pane with .Renviron file.
</figcaption>
</figure>

If you already have a `.Renviron` file, open it and follow the instructions
below to add to it. If you don't have one, create one using File -> New File
-> Text File in the RStudio menus.

Add one line to the text file. In this option, there are no quotes around the
token value.

```{r Renviron, eval=FALSE, comment=NA}
NEON_TOKEN=PASTE YOUR TOKEN HERE
```

Save the file as `.Renviron`, in the RStudio home directory identified above.
Double check the spelling, this will not work if you have a typo. Re-start
R to load the environment.

Once your token is assigned to an environment variable, use the function
`Sys.getenv()` to access it. For example, in `loadByProduct()`:

```{r useEnvtToken, eval=FALSE, comment=NA}
foliar <- loadByProduct(dpID="DP1.10026.001", site="all",
package="expanded", check.size=F,
token=Sys.getenv("NEON_TOKEN"))
```


332 changes: 332 additions & 0 deletions ...neon-code-packages/NEON-API-Token/neon-api-tokens-tutorial/neon-api-tokens-0.md
View file

Large diffs are not rendered by default.

76 changes: 0 additions & 76 deletions ...ral/neon-code-packages/NEON-API-Token/neon-api-tokens-tutorial/neon-api-tokens-tutorial.R
View file

This file was deleted.

Loading

0 comments on commit b28b26a

Please sign in to comment.