brapiR2: A Tidyverse-Native Client for the BrAPI v2 (Breeding API) Specification

[josh45-source]

Submitting Author Name: Joash Joshua Ayo
Submitting Author Github Handle: @josh45-source
Repository: https://github.com/josh45-source/brapiR2
Version submitted: 0.1.0
Submission type: Standard
Editor: @robitalec
Reviewers: TBD

Archive: TBD
Version accepted: TBD
Language: en

---

• Paste the full DESCRIPTION file inside a code block below:

Package: brapiR2
Title: A Tidyverse-Native Client for the BrAPI v2 (Breeding API) Specification
Version: 0.1.0
Authors@R: 
    person("Joash Joshua", "Ayo", , "joashjoshua789@gmail.com", role = c("aut", "cre"),
           comment = c(ORCID = "0009-0007-1642-0172"))
Description: Provides pipe-friendly, stateless access to every endpoint in the 
    Breeding API (BrAPI) v2.1 specification. Covers all four BrAPI modules 
    Core, Germplasm, Phenotyping, and Genotyping returning tidy tibbles ready 
    for analysis. Features include automatic pagination, async search handling, 
    response caching, parallel batch fetching, and convenience functions for 
    genomic selection workflows (e.g. dosage matrix extraction). Designed for 
    plant breeders and bioinformaticians who need programmatic access to 
    BreedBase, BMS, EBS, GIGWA, Germinate, and any BrAPI-compliant server.
License: MIT + file LICENSE
URL: https://github.com/josh45-source/brapiR2,
    https://josh45-source.github.io/brapiR2/
BugReports: https://github.com/josh45-source/brapiR2/issues
Encoding: UTF-8
Language: en-US
Roxygen: list(markdown = TRUE)
Depends:
    R (>= 4.1.0)
RoxygenNote: 7.3.3
Imports:
    cli (>= 3.6.0),
    dplyr (>= 1.1.0),
    glue (>= 1.6.0),
    httr2 (>= 1.0.0),
    jsonlite (>= 1.8.0),
    purrr (>= 1.0.0),
    rlang (>= 1.1.0),
    tibble (>= 3.2.0),
    tidyr (>= 1.3.0),
    tidyselect (>= 1.2.0)
Suggests:
    AGHmatrix,
    BGLR,
    furrr (>= 0.3.0),
    future (>= 1.33.0),
    httptest2,
    knitr,
    lme4,
    metan,
    rappdirs,
    rmarkdown,
    rrBLUP,
    sommer,
    testthat (>= 3.0.0),
    withr
Config/testthat/edition: 3
VignetteBuilder: knitr

Scope

• Please indicate which category or categories from our package fit policies this package falls under:

  • data retrieval
  • data extraction
  • data munging
  • data deposition
  • data validation and testing
  • workflow automation
  • version control
  • citation management and bibliometrics
  • scientific software wrappers
  • field and lab reproducibility tools
  • database software bindings
  • geospatial data
  • translation
  • rOpenSci internal tools

• Explain how and why the package falls under these categories (briefly, 1-2 sentences):

brapiR2 is a data retrieval package providing programmatic access to plant breeding databases via the Breeding API (BrAPI) v2.1 specification. It retrieves phenotypic trial data, genotypic variant data, germplasm records, and pedigree information from BrAPI-compliant servers (BreedBase, BMS, EBS, GIGWA, Germinate) and returns them as tidy tibbles ready for analysis in R.

• Who is the target audience and what are scientific applications of this package?

The target audience is plant breeders, quantitative geneticists, and bioinformaticians who need programmatic, reproducible access to breeding databases. BrAPI is adopted by CGIAR centers (CIMMYT, IRRI, CIP, ICRISAT), national breeding programs, and private breeding companies worldwide.

Scientific applications include:

• Pulling phenotypic trial data for spatial analysis and multi-environment modelling

• Extracting genotypic data as dosage matrices for genomic prediction (rrBLUP, BGLR, sommer)

• Batch retrieval of germplasm pedigree information for genetic studies

• Building reproducible data access pipelines, replacing manual web portal downloads

• Are there other R packages that accomplish the same thing? If so, how does yours differ or meet our criteria for best-in-category?

Yes. QBMS (on CRAN, ~9,400 downloads) is the primary existing R client for BrAPI. brapiR2 differs in design philosophy and scope:

Feature	brapiR2	QBMS
Design	Stateless, functional, pipe-friendly	Stateful, menu-driven (set_program() > set_trial() > set_study())
BrAPI v2 coverage	Full spec — all four modules	Partial (phenotyping focus)
Genotyping endpoints	Native variants, call sets, allele matrices, dosage extraction	Limited (via GIGWA wrapper)
Return type	Always tibbles	Mixed lists / data frames
Caching	Built-in, configurable TTL	None
Parallel fetching	Via furrr	Sequential

The two packages are complementary rather than competing: QBMS is well suited to interactive exploration, while brapiR2 targets reproducible scripting and pipeline building where composable, side-effect-free functions matter. Genotyping module coverage is the strongest differentiator.

There was also an older brapi package by CIP-RIU on GitHub targeting BrAPI v1, which appears unmaintained.

• (If applicable) Does your package comply with our guidance around Ethics, Data Privacy and Human Subjects Research?

Yes. brapiR2 accesses only plant breeding data (phenotypic measurements, genotypic markers, germplasm records). No human subjects data is involved. Authentication credentials are held in explicit connection objects passed as function arguments; they are never stored globally, written to disk, or logged.

• If you made a pre-submission inquiry, please paste the link to the corresponding issue, forum post, or other discussion, or @tag the editor you contacted.

Pre-submission inquiry: #782 - confirmed in scope by @maurolepore.

• Explain reasons for any pkgcheck items which your package is unable to pass.

All required pkgcheck items pass (latest run on commit b1037238: package name available, contributing file, roxygen2, URL and BugReports fields, HTML vignette, all functions have examples, website present, CI present, coverage 98.1%, R CMD check clean).

The remaining 👀 item is "Some goodpractice linters failed". For transparency, these are:

• Cyclocomplexity ≥ 15 - fetch_allele_matrix_pages (18) and brapi_get_dosage_matrix (16). These handle multi-page allele-matrix retrieval and genotype-string-to-dosage conversion across phased, unphased, and missing call formats respectively. I am happy to refactor them further if reviewers prefer.
• lintr (42 items) - predominantly stylistic toString() versus paste(collapse = ) (16), paste() versus paste0() for collapsing (16), plus a small number of <<- uses in cache handling and file.path() suggestions. Straightforward to address on request.
• Duplicated @param documentation - partially addressed via an @inheritParams template for the shared con argument; some duplication remains across module files.
• Unused internal functions / spelling - I will audit and clean these up.

Unused Suggests - AGHmatrix, BGLR, lme4, metan, rrBLUP, and sommer are declared but show no function calls under static analysis, because the vignettes using them are eval = FALSE (they demonstrate downstream genomic selection workflows against a user's own server data). They are listed so readers know what to install to run the vignette code. Happy to drop them and move that guidance into vignette prose if reviewers prefer.

Glad to address any or all of the above during review, I did not want to make further stylistic changes unilaterally before a reviewer had seen the code.

Technical checks

Confirm each of the following by checking the box.

• I have read the rOpenSci packaging guide.
• I have read the author guide and I expect to maintain this package for at least 2 years or to find a replacement.

This package:

• does not violate the Terms of Service of any service it interacts with.
• has a CRAN and OSI accepted license.
• contains a README with instructions for installing the development version.
• includes documentation with examples for all functions, created with roxygen2.
• contains a vignette with examples of its essential functions and uses.
• has a test suite.
• has continuous integration, including reporting of test coverage.

On the ToS point specifically: the BrAPI specification is published under a Creative Commons Attribution licence and the BrAPI community explicitly encourages third-party client development. brapiR2 has been submitted to the BrAPI compatible software registry at brapi.org. Integration tests run against the public BrAPI test server at https://test-server.brapi.org, which is provided by the BrAPI project for exactly this purpose, and are guarded by skip_on_cran() and skip_if_offline().

Use of Generative AI

• Generative AI tools were used to produce some of the material in this submission.

Claude Code (Anthropic's AI coding assistant) was used as a development aid throughout. Specifically:

• Code scaffolding - initial function structures, roxygen2 skeletons, and test file templates, which were then reviewed and iteratively refined against the live BrAPI test server.
• Debugging - diagnosing issues surfaced by devtools::check() and integration testing (non-ASCII characters, missing import directives, test expectations for cli output, a cli string-interpolation bug in brapi_fetch_parallel()).
• CI/CD - GitHub Actions workflow files.

Verification: devtools::check() passes with 0 errors and 0 warnings; 231 tests pass (117 integration tests against the live test server, 114 mocked tests using local_mocked_bindings()), giving 98.1% coverage; all function outputs were manually reviewed against live server responses. The package architecture, API design decisions (stateless connection objects, tibble-only returns, one function per BrAPI endpoint, transparent pagination), and domain logic were directed by me.

The design history, architectural rationale, and the role of AI tooling are documented in DESIGN.md, added at the request of the editorial board during pre-submission. Full development history: https://github.com/josh45-source/brapiR2/commits/main

Publication options

• Do you intend for this package to go on CRAN?
• Do you intend for this package to go on Bioconductor?

Note: in the pre-submission inquiry I indicated an intention to submit to CRAN after review. I am no longer planning to do so in the near term, and would prefer to focus on the rOpenSci review and on maintaining the package on GitHub / R-universe. If that changes I will raise it with the handling editor rather than submitting during review.

• Do you wish to submit an Applications Article about your package to Methods in Ecology and Evolution?

Code of conduct

• I agree to abide by rOpenSci's Code of Conduct during the review process and in maintaining my package should it be accepted.

[ropensci-review-bot]

Thanks for submitting to rOpenSci, our editors and @ropensci-review-bot will reply soon. Type @ropensci-review-bot help for help.

[ropensci-review-bot]

🚀

Error: Submission template must have space before closing '---' in YAML header

👋

[ropensci-review-bot]

Five most similar rOpenSci packages

• drake 'A Pipeline Toolkit for Reproducible Computation at Scale' (v7.13.11, released 2024-12-04)
• ruODK 'An R Client for the ODK Central API' (No releases to date.)
• tidyhydat 'Extract and Tidy Canadian 'Hydrometric' Data' (v1.0.1, released 2026-06-11)
• chopin 'Spatial Parallel Computing by Hierarchical Data Partitioning' (v0.9.9-5, released 2026-04-03)
• patentsview 'An R Client to the 'PatentsView' API' (v1.0.0, released 2026-02-26)

Five most similar CRAN packages

• LLMR 'Interface for Large Language Model APIs in R' (v0.8.6, published 2026-07-10)
• brightspaceR 'Access D2L 'Brightspace' Data Sets via the 'BDS' API' (v0.1.0, published 2026-03-12)
• QBMS 'Query the Breeding Management System(s)' (v2.0.0, published 2025-07-31)
• rPDBapi 'A Comprehensive Interface for Accessing the Protein Data Bank' (v3.0.1, published 2026-03-08)
• sensortowerR 'Interface to 'Sensor Tower' Mobile App Intelligence API' (v1.0.1, published 2026-05-14)

---

Matches are generated by the 'pkgmatch' package, based on inverse-term frequencies; see the main function documentation for details.

[maurolepore]

For the record I invoked ping editors from the pre-submission yesterday

[robitalec]

@ropensci-review-bot assign @robitalec as editor

[ropensci-review-bot]

Assigned! @robitalec is now the editor

[robitalec]

@ropensci-review-bot check package

[ropensci-review-bot]

Thanks, about to send the query.

[ropensci-review-bot]

🚀

Editor check started

👋

[ropensci-review-bot]

Checks for brapiR2 (v0.1.0)

git hash: 92c4f491

• ✔️ Package name is available
• ✔️ has a 'contributing' file.
• ✔️ uses 'roxygen2'.
• ✔️ 'DESCRIPTION' has a URL field.
• ✔️ 'DESCRIPTION' has a BugReports field.
• ✔️ Package has at least one HTML vignette
• ✔️ All functions have examples.
• ✔️ Repository has a website
• ✔️ Package has continuous integration checks.
• ✔️ Package coverage is 98.1%.
• ✔️ R CMD check found no errors.
• ✔️ R CMD check found no warnings.
• 👀 Some goodpractice linters failed.

(Checks marked with 👀 may be optionally addressed.)

Package License: MIT + file LICENSE

---

1. Package Dependencies

Details of Package Dependency Usage (click to open)

The table below tallies all function calls to all packages ('ncalls'), both internal (r-base + recommended, along with the package itself), and external (imported and suggested packages). 'NA' values indicate packages to which no identified calls to R functions could be found. Note that these results are generated by an automated code-tagging system which may not be entirely accurate.

type	package	ncalls
internal	base	133
internal	brapiR2	73
internal	utils	11
imports	purrr	15
imports	rlang	15
imports	httr2	14
imports	glue	8
imports	dplyr	3
imports	cli	2
imports	jsonlite	2
imports	tidyr	2
imports	tibble	1
imports	tidyselect	1
suggests	future	3
suggests	furrr	2
suggests	AGHmatrix	NA
suggests	BGLR	NA
suggests	httptest2	NA
suggests	knitr	NA
suggests	lme4	NA
suggests	metan	NA
suggests	rappdirs	NA
suggests	rmarkdown	NA
suggests	rrBLUP	NA
suggests	sommer	NA
suggests	testthat	NA
suggests	withr	NA
linking_to	NA	NA

Click below for tallies of functions used in each package. Locations of each call within this package may be generated locally by running 's <- pkgstats::pkgstats(<path/to/repo>)', and examining the 'external_calls' table.

base

list (44), body (19), drop (7), dir (6), single (6), c (5), for (4), if (4), names (3), return (3), unlist (3), as.matrix (2), character (2), intersect (2), is.null (2), length (2), paste0 (2), seq_len (2), url (2), version (2), as.integer (1), as.numeric (1), lapply (1), list.files (1), order (1), q (1), raw (1), row (1), seq_along (1), setdiff (1), strsplit (1)

brapiR2

brapi_req (7), brapi_observations (3), brapi_allele_matrix (2), brapi_cache_path (2), brapi_cache_read (2), brapi_get_pages (2), brapi_cache_clear (1), brapi_cache_enable (1), brapi_call_sets (1), brapi_calls (1), brapi_connection (1), brapi_crosses (1), brapi_crossing_projects (1), brapi_endpoints (1), brapi_events (1), brapi_fetch_parallel (1), brapi_germplasm (1), brapi_germplasm_attributes (1), brapi_germplasm_detail (1), brapi_germplasm_pedigree (1), brapi_germplasm_progeny (1), brapi_get (1), brapi_get_dosage_matrix (1), brapi_get_marker_map (1), brapi_images (1), brapi_lists (1), brapi_locations (1), brapi_login (1), brapi_login_oauth2 (1), brapi_methods (1), brapi_observation_units (1), brapi_observation_variables (1), brapi_people (1), brapi_ping (1), brapi_poll_search (1), brapi_post_search (1), brapi_program (1), brapi_programs (1), brapi_reference_sets (1), brapi_references (1), brapi_samples (1), brapi_scales (1), brapi_search_calls (1), brapi_search_germplasm (1), brapi_search_observations (1), brapi_search_variables (1), brapi_search_variants (1), brapi_seasons (1), brapi_seed_lots (1), brapi_server_info (1), brapi_set_token (1), brapi_shared_params (1), brapi_studies (1), brapi_study (1), brapi_study_data (1), brapi_traits (1), brapi_trial (1), brapi_trials (1), brapi_variant_sets (1), brapi_variants (1), fetch_allele_matrix_pages (1)

purrr

compact (12), map (3)

rlang

%||% (13), hash (1), warn (1)

httr2

resp_body_json (7), request (3), resp_status (3), req_perform (1)

utils

data (11)

glue

glue (8)

dplyr

bind_rows (1), filter (1), mutate (1)

future

plan (2), multisession (1)

cli

cli_abort (2)

furrr

future_map_dfr (2)

jsonlite

fromJSON (1), toJSON (1)

tidyr

pivot_wider (2)

tibble

as_tibble_row (1)

tidyselect

where (1)

---

2. Statistical Properties

This package features some noteworthy statistical properties which may need to be clarified by a handling editor prior to progressing.

Details of statistical properties (click to open)

The package has:

• code in R (100% in 10 files) and
• 1 authors
• 3 vignettes
• no internal data file
• 10 imported packages
• 55 exported functions (median 3 lines of code)
• 10 non-exported functions in R (median 22 lines of code)

---

Statistical properties of package structure as distributional percentiles in relation to all current CRAN packages
The following terminology is used:

• loc = "Lines of Code"
• fn = "function"
• exp/not_exp = exported / not exported

All parameters are explained as tooltips in the locally-rendered HTML version of this report generated by the checks_to_markdown() function

The final measure (fn_call_network_size) is the total number of calls between functions (in R), or more abstract relationships between code objects in other languages. Values are flagged as "noteworthy" when they lie in the upper or lower 5th percentile.

measure	value	percentile	noteworthy
files_R	10	74.8
files_vignettes	3	94.4
files_tests	13	95.8
loc_R	703	79.6
loc_vignettes	386	73.0
loc_tests	1350	91.3
num_vignettes	3	95.0
n_fns_r	65	89.1
n_fns_r_exported	55	92.5
n_fns_r_not_exported	10	80.9
n_fns_per_file_r	6	88.4
num_params_per_fn	2	51.4
loc_per_fn_r	6	51.8
loc_per_fn_r_exp	3	46.4
loc_per_fn_r_not_exp	22	91.6
doclines_per_fn_exp	16	51.0
doclines_per_fn_not_exp	10	96.1	TRUE
fn_call_network_size	71	85.0

---

2a. Network visualisation

Click to see the interactive network visualisation of calls between objects in package

---

3. goodpractice and other checks

Details of goodpractice checks (click to open)

3a. Continuous Integration Badges

GitHub Workflow Results

id	name	conclusion	sha	run_number	date
30121033174	pkgcheck	failure	92c4f4	8	2026-07-24
30121033156	pkgdown	success	92c4f4	11	2026-07-24
30121033134	R-CMD-check	success	92c4f4	12	2026-07-24

---

3b. goodpractice results

Test coverage with covr

Package coverage: 98.08

Cyclocomplexity with cyclocomp

The following functions have cyclocomplexity >= 15:

function	cyclocomplexity
fetch_allele_matrix_pages	18
brapi_get_dosage_matrix	16

Static code analyses with lintr

lintr found the following 42 potential issues:

message	number of times
Avoid implicit assignments in function calls.	1
Avoid undesirable operator <<-.	5
Construct file paths with file.path(...) instead of paste0(x, "/", y, "/", z).	2
expect_named(x, n) is better than expect_identical(names(x), n)	2
toString(.) is more expressive than paste(., collapse = ", ").	16
Use paste(), not paste0(), to collapse a character vector when sep= is not used.	16

Other goodpractice checks

✖️ All internal functions are used
✖️ Avoid duplicated @param documentation across functions
✖️ No misspelled words in documentation
✖️ All URLs are reachable

---

Package Versions

package	version
pkgstats	0.2.4.1
pkgcheck	0.1.3.13

---

Editor-in-Chief Instructions:

This package is in top shape and may be passed on to a handling editor.

This package has some noteworthy properties, see 'Package Statistics' details above.

[robitalec]

Editor checks:

• Documentation: The package has sufficient documentation available online (README, pkgdown docs) to allow for an assessment of functionality and scope without installing the package. In particular,
  • Is the case for the package well made?
  • Is the reference index page clear (grouped by topic if necessary)?
  • Are vignettes readable, sufficiently detailed and not just perfunctory?
• Fit: The package meets criteria for fit and overlap.
• Installation instructions: Are installation instructions clear enough for human users?
• Tests: If the package has some interactivity / HTTP / plot production etc. are the tests using state-of-the-art tooling?
• Contributing information: Is the documentation for contribution clear enough e.g. tokens for tests, playgrounds?
• License: The package has a CRAN or OSI accepted license.
• Project management: Are the issue and PR trackers in a good shape, e.g. are there outstanding bugs, is it clear when feature requests are meant to be tackled?

---

Editor comments

Thank you @josh45-source for sharing your work with rOpenSci!
I'm excited to be working with you as editor on this Software Peer Review submission.

Thanks for your clear comparison with the {QBMS} package. I think the differences regarding design, endpoint and API coverage and return types are well described here and in the README to give potential users relevant info for picking the suitable package for their application. For completeness, there also seems to be a package from the same authors as {brapi} for BrAPI v2: https://github.com/mverouden/brapir-v2. It has not been updated in ~4 years.

See below for my numbered comments listed with the prefix "EC". In your reply to my comments and future reviewer comments, can you please link to the relevant commit and the comment is addressed?

For example: Commit (link) addresses EC(number) by (some description).

I've left the vignettes check above open for now because I think that should be addressed before reviewers start. I will begin the search for reviewers while you address these initial comments.

Thank you!

Detailed comments

Documentation

• EC1: The vignettes could use more descriptive text in addition to the series of code chunks. For example, headers like "Step 4: Imputation (Optional but Recommended)" are followed up with only a code chunk. I would have anticipated some information and guidance on the nuances of "optional but recommended". This is an important place to communicate your design decisions and the relevant domain knowledge that have helped shaped the package. It might be helpful to read the Advice on writing vignettes from the R Packages book.
• EC2: Also from the R Packages book, there is a helpful discussion of how to deal with packages that are listed in Suggests for vignette only code here. Are these packages large or overly challenging to install for the purposes of showing the evaluated code chunks? An alternative would be to use an article instead of a vignette, see here. I think a user would benefit from seeing the output of these code chunks instead of eval=FALSE.
• EC3: For your {pkgdown} website, it might be useful to follow the recommendations here to automatically generate a "Get Started" page that would be outside of the dropdown list of articles. I noticed it felt a bit lost in the middle of the dropdown and it would be nice if it was easier for a new user to find.
• EC4: The README.md is out of sync with the README.Rmd. The {usethis} function use_readme_rmd uses a git hook to notify the user when these files are out of sync. You could consider using that to remind you when these files are out of sync. Because the current state (README.md is more recently changed than README.Rmd) will snag if you install the hook first, you might want to update the changes from README.md to README.Rmd, render, commit, then install the hook if you choose to.
• EC5: I think users could benefit from more details regarding managing credentials securely, especially e.g. illustrating the option to use the {keyring} package. See this Posit post about managing credentials which has sections for the {keyring} package and using .Renviron.
• EC6: There may need to be some clarification regarding contributing a new endpoint: your CONTRIBUTING.md file indicates manual editing of the NAMESPACE file which seems to be in contradiction to the NAMESPACE file stating do not edit by hand. Can you provide more details to help potential contributors?

DESCRIPTION

• EC7: Section 1.7.1 of the Packaging Guide notes that "If your package provides access to a data source, we require that DESCRIPTION contains both (1) A brief identification and/or description of the organisation responsible for issuing data; and (2) The URL linking to a public-facing page providing, describing, or enabling data access (which may often differ from URL leading directly to data source)." Could you ensure the URL to the BrAPI is included in the DESCRIPTION?

pkgcheck

• EC8: I see two issues in the pkgcheck action in the repository. Since the package is not on CRAN, the badge could be removed from the README. urlchecker returns:
  • 404 for the CRAN status badge
  • 404 for the QBMS link

Building

• EC9: I see two issues when building the package locally:

✖ brapiR2-package.R:9: @importFrom must be only 1 line long, not 2.
ℹ The first line is "cli cli_progress_bar cli_progress_update
  cli_progress_done"
✖ brapiR2-package.R:12: @importFrom must be only 1 line long, not 3.
ℹ The first line is "httr2 request req_headers req_url_path_append
  req_url_query"

Testing

• EC10: I see failing tests locally when I don't have {future} and {furrr} installed (e.g. test-cache-mocked.R) because they are listed in Suggests. These are used for the parallel functionality highlighted in the comparison with {QBMS}. This could be addressed by using the skip_if_not_installed function or by moving them to Imports. The {future} vignette "A Future for R: Best Practices for Package Developers" also has helpful information for depending on {future} in a package.

Lints

• EC11: As you mention, some lints are related to indentation and other stylistic differences. You could consider using a tool like Air or Jarl for automatically catching and/or fixing these.