Author: Nathan Sheffield
Date: 2023-11-21

# Getting Started with pepr

#### Nathan Sheffield

#### 2023-11-21

# Introduction to `pepr`

`pepr` is the official R package for the pepkit suite, a collection of tools that interface with portable encapsulated projects, or PEPs. PEP format 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:

    library('pepr')
    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:

    p = pepr::Project(file=projectConfigFile)

    ## Loading config file: /tmp/RtmpoymTo9/Rinstb3055bff7/pepr/extdata/example_peps-master/example_basic/project_config.yaml

That’s it! You’ve now have a `Project` object, p, to interact with in `R`.

## 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:

    p

    ## PEP project object. Class:  Project
    ##   file:
    ## /tmp/RtmpoymTo9/Rinstb3055bff7/pepr/extdata/example_peps-master/example_basic/project_config.yaml
    ##   samples:  2

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

    sampleTable(p)
    ##    sample_name      protocol                file
    ## 1:      frog_1 anySampleType data/frog1_data.txt
    ## 2:      frog_2 anySampleType data/frog2_data.txt

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

    config(p)

    ## Config object. Class: Config
    ##  pep_version: 2.0.0
    ##  sample_table:
    ## /tmp/RtmpoymTo9/Rinstb3055bff7/pepr/extdata/example_peps-master/example_basic/sample_table.csv
    ##  name: example_basic

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