---
title: "Getting Started with pepr"
author: "Nathan Sheffield"
date: "`r Sys.Date()`"
output: 
  rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting Started with pepr}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

# Introduction to `pepr`

`pepr` is the official R package for the [pepkit](https://pep.databio.org/) suite, a collection of tools that interface with *portable encapsulated projects*, or PEPs. [PEP format](https://pep.databio.org/) defines a structure for organizing project metadata using a `yaml` file. `pepr` allows you to read any PEP-formatted project metadata (and potentially even actual sample data) into R, providing you a convenient user interface to interact with and share project metadata. 

## Installing `pepr`

You can install `pepr` in the usual way. Currently from GitHub (but we target a CRAN release at some point).

```
devtools::install_github('pepkit/pepr')
```

## Loading an example project

Load `pepr` and read in your project. We have provided a basic example to show you how it works. You can use this to get the file path to a built-in example project configuration `yaml` file:


```{r,collapse=TRUE}
library('pepr')
NOT_CRAN <- identical(tolower(Sys.getenv("NOT_CRAN")), "true")
branch = "master"
projectConfigFile = system.file("extdata",
	paste0("example_peps-", branch),
	"example_basic",
	"project_config.yaml",
	package="pepr")
```

Loading your project metadata into R is a single line of code:

```{r}
p = pepr::Project(file=projectConfigFile)
```

That's it! You now have a `Project` object, *p*, to interact with in `R`. You can also use PEPhub registry paths to fetch them online:

```{r, eval=NOT_CRAN}
p2 = pepr::pullProject(registryPath='databio/example:default')
```

To fetch private PEPs, use PEPhub Client to login and generate an authentication token. Or, login to PEPhub and generate a new key to save it locally:

```{r, eval=FALSE}
pepr::saveJWT('*your authetication token goes here*')
```

You should then be able to fetch your private PEPs by registry path.

## Interfacing with your `pepr::Project` object in R

Now you can interface with that project object to grab both sample-level and project-level metadata. Here's how you can access the metadata. If you just run the `show()` function on your object, you'll get a simple report telling you a few basic stats, like where the project came from and how many samples it has:

```{r}
p
```

To get the sample table out of the project, you use the `samples()` function:

```{r,collapse=TRUE}
sampleTable(p)
```

And you can also access the project configuration metadata with the `config()` function:

```{r}
config(p)
```

If you would like to save your project to a new directory, use the `saveProject()` function:

```{r, eval=NOT_CRAN}
saveProject(p2, outputDir=tempdir())
```

Follow the other vignettes for more advanced capabilities of `pepr`.