Overview

biotrace is the R integration package for the BioTrace GitHub Action. BioTrace traces biological results from data and code to figures and scientific claims. It runs as a GitHub Action referenced by uses: rotsl/biotrace@v1 in a workflow file.

This R package does not ship or run the upstream TypeScript engine. The engine runs only through GitHub. The package provides:

R helpers to write and validate a BioTrace configuration YAML file
R helpers to write the GitHub workflow YAML that calls the upstream Action
An R reader for the JSON report BioTrace produces
A command-line interface (biotrace) that wraps the same R API
A conservative GitHub integration helper that can trigger an existing BioTrace workflow

library(biotrace)

Quick start in a fresh project

# Initialise .github/biotrace.yml and .github/workflows/biotrace.yml
use_biotrace()

use_biotrace() writes two files and refuses to overwrite them. The workflow file references the upstream Action as uses: rotsl/biotrace@v1. To regenerate after editing, pass overwrite = TRUE:

use_biotrace(overwrite = TRUE)

Configuration

The smallest valid BioTrace configuration is:

version: 1

default_biotrace_config()
#> $version
#> [1] 1
default_biotrace_config_text()
#> [1] "version: 1\n"

You can validate any BioTrace configuration file against the upstream JSON Schema (a verbatim copy of the schema published by rotsl/biotrace ships under inst/extdata/schemas/):

validate_biotrace_config(".github/biotrace.yml")

A validation failure produces a structured error pointing at the offending field. Pass return_errors = TRUE to collect every violation instead of throwing on the first one.

Workflows

biotrace_workflow_text() returns the workflow YAML as a character vector. It is deterministic and parsable by yaml::yaml.load():

cat(biotrace_workflow_text(), sep = "\n")
#> # Generated by the biotrace R package. Do not edit by hand;
#> # regenerate with biotrace::use_biotrace().
#> name: BioTrace
#> 
#> on:
#>   pull_request:
#>     types:
#>       - opened
#>       - synchronize
#>       - reopened
#>       - ready_for_review
#> 
#> permissions:
#>   contents: read
#>   pull-requests: write
#>   issues: write
#>   checks: write
#> 
#> jobs:
#>   biotrace:
#>     runs-on: ubuntu-latest
#>     steps:
#>       - uses: actions/checkout@v7
#>         with:
#>           fetch-depth: 0
#> 
#>       - id: biotrace
#>         uses: rotsl/biotrace@v1
#>         with:
#>           config: .github/biotrace.yml
#>           github-token: ${{ github.token }}
#>           fail-on: error
#>           ai-enabled: "false"
#> 
#>       - if: always()
#>         uses: actions/upload-artifact@v7
#>         with:
#>           name: biotrace-report
#>           path: ${{ steps.biotrace.outputs.report-path }}

Reports

When BioTrace runs in CI it writes a JSON report. read_biotrace_report() reads that file into an S3 object of class biotrace_report:

report <- read_biotrace_report(
  system.file("extdata", "example-report.json", package = "biotrace")
)
print(report)
#> BioTrace report: warning
#> Reproducibility score: 82/100
#> Generated at: 2026-08-20T10:30:00Z
#> Findings: 3 total, 0 blocking
#>   by severity: info=1, warning=2, error=0
#> Files checked: 4
#> Claims checked: 2
#> Figures checked: 3
#> Source: /tmp/RtmpXT7xR6/Rinst84817a393e6/biotrace/extdata/example-report.json
summary(report)
#> $status
#> [1] "warning"
#> 
#> $score
#> [1] 82
#> 
#> $findings_count
#> [1] 3
#> 
#> $blocking_findings_count
#> [1] 0
#> 
#> $files_checked
#> [1] 4
#> 
#> $claims_checked
#> [1] 2
#> 
#> $figures_checked
#> [1] 3
#> 
#> $generated_at
#> [1] "2026-08-20T10:30:00Z"
#> 
#> $findings_by_severity
#>    info warning   error 
#>       1       2       0 
#> 
#> $source
#> [1] "/tmp/RtmpXT7xR6/Rinst84817a393e6/biotrace/extdata/example-report.json"
#> 
#> attr(,"class")
#> [1] "biotrace_report_summary"

GitHub integration

run_biotrace_github() is a thin wrapper around the GitHub REST API. It can list workflows, list recent runs of the BioTrace workflow, or dispatch the workflow. It reads a token from GITHUB_TOKEN (or GH_TOKEN, or any env var you name) and never writes the token to disk.

# Preview the request that would be issued, without sending it.
run_biotrace_github("rotsl/biotrace-r",
                    action = "trigger",
                    dry_run = TRUE)

Command line interface

After installation, the biotrace command is available on PATH:

biotrace --help
biotrace --version
biotrace init
biotrace config validate .github/biotrace.yml
biotrace report biotrace-report.json
biotrace github run --repo rotsl/biotrace-r --action trigger --dry-run

The CLI does not provide a biotrace check subcommand. There is no local execution of the upstream TypeScript engine in this package, so offering a check command would be misleading. The closest equivalent is biotrace github run, which talks to GitHub.