rphg_walkthrough.Rmd

---
title: "Introduction to rPHG"
output:
  BiocStyle::html_document:
    toc: false
    fig_caption: true
    toc_float: true
    number_sections: false
vignette: >
  %\VignetteIndexEntry{Introduction to rPHG}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
  %\usepackage[utf8]{inputenc}
  %\usepackage{float}
editor_options:
  markdown:
    wrap: 70
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(
  fig.path = "figure/graphics-",
  cache.path = "cache/graphics-",
  fig.align = "center",
  external = TRUE,
  echo = TRUE,
  warning = FALSE
)

library(rPHG)
logFile    <- tempfile(fileext = ".txt")
configFile <- tempfile()
rPHG:::createConfigFile(configFile)
```

The basic workflow of the `rPHG` package is as follows:

1.  Create a connection object
2.  Select a PHG "method"
3.  Read data into the R environment
4.  Analyze and visualize data retrieval

This document introduces you to `rPHG`'s methods and grammar, and
shows you how to apply them to the previously mentioned workflow.

## Creating connection objects

PHG databases can be connected through two primary sources:

-   local
-   server

Local connections are for databases set up to use PostgreSQL or SQLite
management systems, typically located either on a local machine or
hosted on a high performance compute cluster which are accessed via
the PHG API.

Conversely, server connections are for databases served on publicly
available web services leveraging Breeding API (BrAPI) endpoints for
data retrieval. For example,
[demo.hub.maizegenetics.net](demo.hub.maizegenetics.net) is a publicly
available PHG database housing information many known diversity
populations in maize.

### Establishing a local connection

To set up a local connection, prior knowledge about how configuration
files are set up is needed. If you would like more information about
this topic, please see the vignette "[Overview of configuration
files](rphg_config_files.html)"

We can supply a path to a valid configuration file to the constructor,
`PHGLocalCon()`:

```{r, echo=TRUE, eval=TRUE}
configFile |> PHGLocalCon()
```

Here, our configuration file path (`configFilePath`) is parsed to
create an object of type `PHGLocalCon`.

### Establishing a server connection

If you would like to use a PHG web service, we can use the following
similar method:

```{r, echo=TRUE, eval=TRUE}
"phg.maizegdb.org" |> PHGServerCon()
```

Here, a URL pointing to a PHG web service is supplied to the
constructor `PHGServerCon()` which will be parsed to create an object
of type `PHGServerCon`.

## PHG Methods

```{r, echo=TRUE, eval=TRUE}
configFile |> 
    PHGLocalCon() |> 
    showPHGMethods()
```

```{r, echo=TRUE, eval=TRUE}
configFile |> 
    PHGLocalCon() |> 
    PHGMethod("PATH_METHOD")
```

## Reading data

### Read samples (e.g. taxa)

```{r, echo=TRUE, eval=TRUE}
configFile |> 
    PHGLocalCon() |> 
    PHGMethod("PATH_METHOD") |> 
    readSamples()
```

### Read reference ranges

```{r, echo=TRUE, eval=TRUE}
configFile |> 
    PHGLocalCon() |> 
    PHGMethod("PATH_METHOD") |> 
    readRefRanges()
```

### Read haplotype ID matrix

```{r, echo=TRUE, eval=TRUE}
configFile |> 
    PHGLocalCon() |> 
    PHGMethod("PATH_METHOD") |> 
    readHaplotypeIds()
```

## `PHGDataSet` objects

```{r, echo=TRUE, eval=TRUE, message=FALSE}
configFile |> 
    PHGLocalCon() |> 
    PHGMethod("PATH_METHOD") |> 
    readPHGDataSet()
```