---
title: "Germinate Example"
author: "Khaled Al-Shamaa"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Germinate Example}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

## QBMS
This R package assists breeders in linking data systems with their analytic pipelines, a crucial step in digitizing breeding processes. It supports querying and retrieving phenotypic and genotypic data from systems like [EBS](https://ebs.excellenceinbreeding.org/), [BMS](https://bmspro.io/), [BreedBase](https://breedbase.org), [Germinate](https://germinateplatform.github.io/get-germinate/) and [GIGWA](https://github.com/SouthGreenPlatform/Gigwa2) (using [BrAPI](https://brapi.org/) calls). Extra helper functions support environmental data sources, including [TerraClimate](https://www.climatologylab.org/terraclimate.html) and FAO [HWSDv2](https://gaez.fao.org/pages/hwsd) soil database.

## Germinate
[Germinate](https://germinateplatform.github.io/get-germinate/) is an open source plant database infrastructure and application programming platform on which complex data from genetic resource collections can be stored, queried and visualized using common, reusable, programming components. Germinate utilises modern web and database standards to provide a common architecture and high performance web-based user interface and analytics functionality across a wide variety of data types including: passport, phenotypic, field trial, pedigree, genetic, climatic, geographic location data as well as user-submitted annotations. In addition, it provides links to an expanding variety of external visualization and analysis tools such as [Helium](https://ics.hutton.ac.uk/helium/) for pedigree visualization, [Flapjack](https://ics.hutton.ac.uk/flapjack/) for graphical genotyping and [CurlyWhirly](https://ics.hutton.ac.uk/curlywhirly/) for 3D coordinate data.

## BrAPI
The Breeding API ([BrAPI](https://brapi.org/)) project is an effort to enable interoperability among plant breeding databases. BrAPI is a standardized RESTful web service API specification for communicating plant breeding data. This community driven standard is free to be used by anyone interested in plant breeding data management.

## _Connect to a Germinate server_

```r
# load the QBMS library
library(QBMS)

# configure your Germinate server connection
set_qbms_config(url = "https://germinate.hutton.ac.uk/demo/#/home", 
                engine = "germinate", 
                no_auth = TRUE, 
                page_size = 9999)

# login using your account (interactive mode)
# login()
# or pass your username and password as parameters (batch mode)
# login("username", "password")

# list existing crops on the current server
list_crops()

# select a crop by name
set_crop("Cactuar")

# list all breeding programs in the selected crop
list_programs()

# select a breeding program by name
set_program("Germinate")

# list all trials in the selected program
list_trials()

# select a specific trial by name
set_trial("GWAS data")

# list all studies (environments/locations) in the selected trial
list_studies()

```

## _Work with Phenotypic Data_

```r
# select a specific study by name
set_study("Sample Phenotype Data")

# retrieve general information and metadata for the selected study
info <- get_study_info()

# retrieve the germplasm list for the selected study
geno <- get_germplasm_list()

# retrieve attributes for a specified germplasm
attr <- get_germplasm_attributes("CACTUAR-3")

# retrieve study data
data <- get_study_data()

# get observation variable ontology in the selected study/trial
ontology <- get_trial_obs_ontology()

```

## _Work with Genotypic Data_

```r
# select a specific study by name
set_study("Sample Genotype Data Subset 2")

# list all variant sets in the selected study
list_variantsets()

# select a specific active variant set by name
set_variantset("Sample Genotype Data Subset 2")

# retrieve the selected variant set marker matrix
snps <- get_variantset()

# get marker position information
map <- get_marker_map()

```

## _Work with Pedigree Data_

```r
# select a specific study by name
set_trial("Default pedigree experiment")

# get the pedigree table for the selected trial
ped <- get_trial_pedigree()

```