---
title: "4 Preparing and Submitting a Trio"
author: "BenchHub Team"
date: "`r Sys.Date()`"
output: BiocStyle::html_document
vignette: >
  %\VignetteIndexEntry{4 Preparing and submitting a Trio}
  %\VignetteEncoding{UTF-8}
  %\VignetteEngine{knitr::rmarkdown}
---

# Preparing and Submitting a Trio

This guide provides step-by-step instructions for preparing and submitting a `Trio` object to the [BenchHub Datasets](https://docs.google.com/spreadsheets/d/1H8hOxL8D0XTquao8vGZ2cr9-XeaFC48SWAdFn0M3fkg/edit?usp=sharing). The recommended workflow is to first build a submission bundle with `writeSubmission()`, review the collected metadata, and then submit it.

The workflow has two common entry points:

-   `writeSubmission()`: interactive helper for preparing and optionally submitting a Trio.
-   `submitTrioSubmission()`: submit Trio to [BenchHub Datasets](https://docs.google.com/spreadsheets/d/1H8hOxL8D0XTquao8vGZ2cr9-XeaFC48SWAdFn0M3fkg/edit?usp=sharing).

```{r load-package}
library(BenchHub)
```

## Step 1: GitHub Personal Access Token (PAT)

A GitHub personal access token is needed for uploading custom metrics to a GitHub gist.

1.  Log in to your GitHub account.
2.  Navigate to **Settings** \> **Developer settings** \> **Personal access tokens** \> **Tokens (classic)**.
3.  Click **Generate new token**.
4.  Select the following scopes:
    -   `gist` (for creating and managing gists)
5.  Click **Generate token** and copy the token.

### Set the PAT in R

Add the token to your environment in R:

``` r
Sys.setenv(GITHUB_PAT = "your_personal_access_token")
```

Replace `"your_personal_access_token"` with the token you copied.

## Step 2: Build the submission bundle

1.  In R, create a `Trio` object and ensure it is properly populated with data, supporting evidence, and metrics.
2.  Use `writeSubmission()` to prepare the Trio submission:

``` r
bundle <- writeSubmission(trio)
```

During the interactive workflow, `writeSubmission()` may prompt you for:

-   dataset metadata such as the dataType, technology and description
-   task information for the Trio
-   mappings between supporting evidence and tasks
-   metric metadata where needed
-   file preparation details, including whether to verify a Figshare article, and
-   optional submission details if you choose to submit immediately.

## Step 3: Submit the Trio

After reviewing the generated bundle, you can submit it with `submitTrioSubmission()`:

``` r
response <- submitTrioSubmission(
  submission = bundle$submission,
  submittedBy = "your.name@example.org"
)
```

If you prefer a single interactive step, you can also let `writeSubmission()` submit at the end:

``` r
bundle <- writeSubmission(
  trio,
  submittedBy = "your.name@example.org",
  submit = TRUE
)
```

## Step 4: Verify the submission

Once you upload the Trio, it will be first uploaded in to Submission_Master sheet. After BenchHub team completed the review and approved, the Trio information will update to Dataset, DatasetTask, DatasetEvidence, DatasetTaskMetric and Metric table. Check the [BenchHub Datasets](https://docs.google.com/spreadsheets/d/1H8hOxL8D0XTquao8vGZ2cr9-XeaFC48SWAdFn0M3fkg/edit?usp=sharing) to ensure your dataset has been added under the submission tables.

## Step 5: Downloading an existing Trio

You can also download a previously submitted Trio by its dataset ID under Dataset sheet:

``` r
trio <- downloadSubmissionTrio("datasetID", cachePath = tempdir())
```

## Notes

-   Ensure you have an active internet connection during the upload process.
-   If you encounter any issues, check that your Figshare URL and submission details are correctly set.

# Session Info

```{r session-info}
sessionInfo()
```