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

# QBMS
<!-- https://shields.io/ -->
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), 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.

## Breeding Management System
Breeding Management System ([BMS](https://bmspro.io/)) is an information management system developed by the Integrated Breeding Platform to help breeders manage the breeding process, from programme planning to decision-making. The BMS is customizable for most crop breeding programs, and comes pre-loaded with curated ontology terms for many crops (bean, cassava, chickpea, cowpea, groundnut, maize, rice, sorghum, soybean, wheat, and others). The BMS is available as a cloud application, which can be installed on local or remote servers and accessed by multiple users.

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

> _From BMS version 25 onward, users must possess the necessary permissions to utilize the BrAPI services. [This table](https://ibplatform.atlassian.net/wiki/spaces/BMS/pages/2870968321/v25+BMS+permissions+required+for+using+BrAPI+services) outlines the permissions needed for accessing specific services._

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

# config your BMS connection (by providing your BMS login page URL)
set_qbms_config("https://bms.icarda.org/ibpworkbench/controller/auth/login")

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

# list supported crops in the current bms server
list_crops()

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

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

# select a breeding program by name
set_program("Wheat International Nurseries")

# list all studies/trials in the selected program
list_trials()

# filtered by year of starting date
list_trials(2022)

# select a specific study/trial by name
set_trial("IDYT39")

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

# select a specific environment/location by name
set_study("IDYT39 Environment Number 9")

# select a specific study by location name (first match)
studies <- list_studies()
set_study(studies[studies$locationName == "Amlaha", "studyName"][1])

# retrieve data, general information, and germplasm list 
# of the selected environment/location
data <- get_study_data()
info <- get_study_info()
germplasm <- get_germplasm_list()

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

# get the pedigree table
pedigree_table <- get_pedigree_table(germplasm, "germplasmName", "pedigree")

# retrieve multi-environment trial data of the selected study/trial
MET <- get_trial_data()

# retrieve all environments/locations information in the selected program
program_studies <- get_program_studies()

# retrieve observations data of given germplasm aggregated from all trials 
# in the selected program
# e.g., https://www.croptrust.org/news-events/campaigns/jabal-durum-wheat-variety/
germplasm_observations <- get_germplasm_data("Jabal")

# retrieve germplasm attributes for a given germplasm in a crop
germplasm_attributes <- get_germplasm_attributes("Jabal")

```