From dd4a1172f72e314c282a665199d9028416e0f181 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Tue, 8 Sep 2026 07:43:22 +0000 Subject: [PATCH 1/2] Refresh README for portfolio readme-refresh gate MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Align the first screen with Promise → Proof → Scope → Route: keep four current badges (CRAN, R-CMD-check, pkgdown, Codecov), add live docs routes, document CRAN vs GitHub versions, and replace the vignette-only example with a verified bids_project()/func_scans() quick start. Co-authored-by: bbuchsbaum --- README.Rmd | 81 +++++++++++++++++++++++++++++++++++------------------ README.html | 74 ++++++++++++++++++++++++++++++++++++++++-------- README.md | 76 ++++++++++++++++++++++++++++++++++++------------- 3 files changed, 173 insertions(+), 58 deletions(-) diff --git a/README.Rmd b/README.Rmd index d4d76f1e..5fa276f4 100644 --- a/README.Rmd +++ b/README.Rmd @@ -9,47 +9,77 @@ knitr::opts_chunk$set( collapse = TRUE, comment = "#>", fig.path = "man/figures/README-", - out.width = "100%" + out.width = "100%", + message = FALSE, + warning = FALSE ) ``` # bidser +[![CRAN status](https://www.r-pkg.org/badges/version/bidser)](https://CRAN.R-project.org/package=bidser) [![R-CMD-check](https://github.com/bbuchsbaum/bidser/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/bbuchsbaum/bidser/actions/workflows/R-CMD-check.yaml) +[![pkgdown](https://github.com/bbuchsbaum/bidser/actions/workflows/pkgdown.yaml/badge.svg)](https://bbuchsbaum.github.io/bidser/) [![Codecov test coverage](https://codecov.io/gh/bbuchsbaum/bidser/branch/master/graph/badge.svg)](https://app.codecov.io/gh/bbuchsbaum/bidser?branch=master) -[![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental) -[![CRAN status](https://www.r-pkg.org/badges/version/bidser)](https://CRAN.R-project.org/package=bidser) -[BIDS](https://bids.neuroimaging.io/) in R -- (it's a start!) - -The goal of bidser is to make working with the BIDS neuroimaging format convenient in R. -Current support is strongest for MRI datasets, with explicit query helpers, -metadata inheritance, derivative pipeline discovery, and compatibility-oriented -support for [fmriprep](https://fmriprep.org/en/stable/) workflows. +**bidser** reads and queries [BIDS](https://bids.neuroimaging.io/) +(Brain Imaging Data Structure) neuroimaging projects in R: locate subjects, +sessions, tasks, and files; resolve sidecar metadata; discover derivative +pipelines; and extract fMRIPrep confounds. +[Documentation](https://bbuchsbaum.github.io/bidser/) · +[Getting started](https://bbuchsbaum.github.io/bidser/articles/quickstart.html) · +[Derivatives](https://bbuchsbaum.github.io/bidser/articles/derivatives.html) · +[Confounds](https://bbuchsbaum.github.io/bidser/articles/confounds-and-variables.html) · +[API reference](https://bbuchsbaum.github.io/bidser/reference/) · +[Changelog](NEWS.md) ## Installation +Install the released version from CRAN: + +```r +install.packages("bidser") +``` + +Or the development version from GitHub: + +```r +# install.packages("remotes") +remotes::install_github("bbuchsbaum/bidser") +``` + +CRAN currently publishes 0.5.0; this repository is at 0.5.1. + +## Quick start + +Load a BIDS project and query functional scans with the public entry points +`bids_project()`, `participants()`, `tasks()`, and `func_scans()`: + +```{r} +library(bidser) -Install the development version from [GitHub](https://github.com/) with: +ds_path <- get_example_bids_dataset("ds001") +proj <- bids_project(ds_path) -``` r -# install.packages("devtools") -devtools::install_github("bbuchsbaum/bidser") +participants(proj) +tasks(proj) +head(func_scans(proj, full_path = FALSE)) ``` -## Example -See https://bbuchsbaum.github.io/bidser/articles/quickstart.html +Related APIs include `read_events()`, `query_files()`, `get_metadata()`, +`derivative_pipelines()`, and `create_mock_bids()` for offline fixtures. +See the vignettes linked above for worked examples. ## fMRIPrep confounds -`read_confounds()` selects nuisance regressors from fMRIPrep confound tables. -Rather than hand-listing version-specific column names, use the high-level, -version-robust helpers: +`read_confounds()` selects nuisance regressors from fMRIPrep confound +tables. Prefer the public, version-robust helpers over hand-listed column +names: -``` r +```r # Named, version-robust sets (resolve to whatever columns your dataset has) read_confounds(proj, cvars = confound_set("motion24")) read_confounds(proj, cvars = confound_set("36p")) @@ -62,11 +92,8 @@ list_confound_sets() list_confound_strategies() ``` -Code that previously reached into the unexported `bidser:::DEFAULT_CVARS2` -should switch to the stable public handle `confound_set("legacy_default")`, -which returns the identical 26-name set. See `?read_confounds`, -`?confound_set`, and the *confounds-and-variables* vignette for details. - - - - +Code that previously reached into the unexported +`bidser:::DEFAULT_CVARS2` should switch to the stable public handle +`confound_set("legacy_default")`, which returns the identical 26-name set. +See `?read_confounds`, `?confound_set`, and the +[confounds vignette](https://bbuchsbaum.github.io/bidser/articles/confounds-and-variables.html). diff --git a/README.html b/README.html index 7de35385..1fa8eb59 100644 --- a/README.html +++ b/README.html @@ -606,21 +606,71 @@

bidser

-

R-CMD-check Codecov test coverage Lifecycle: experimental CRAN status

+

CRAN status R-CMD-check pkgdown Codecov test coverage

-

BIDS in R – (it’s a -start!)

-

The goal of bidser is to make working with the BIDS neuroimaging -format convenient in R. Currently there is support for MRI data and some -support for some fmriprep -derivatives.

+

bidser reads and queries BIDS (Brain Imaging Data +Structure) neuroimaging projects in R: locate subjects, sessions, tasks, +and files; resolve sidecar metadata; discover derivative pipelines; and +extract fMRIPrep confounds.

+

Documentation · Getting +started · Derivatives +· Confounds +· API +reference · Changelog

Installation

-

Install the development version from GitHub with:

-
# install.packages("devtools")
-devtools::install_github("bbuchsbaum/bidser")
-

Example

-

See https://bbuchsbaum.github.io/bidser/articles/quickstart.html

+

Install the released version from CRAN:

+
install.packages("bidser")
+

Or the development version from GitHub:

+
# install.packages("remotes")
+remotes::install_github("bbuchsbaum/bidser")
+

CRAN currently publishes 0.5.0; this repository is at 0.5.1.

+

Quick start

+

Load a BIDS project and query functional scans with the public entry +points bids_project(), participants(), +tasks(), and func_scans():

+
library(bidser)
+
+ds_path <- get_example_bids_dataset("ds001")
+proj <- bids_project(ds_path)
+
+participants(proj)
+#>  [1] "01" "02" "03" "04" "05" "06" "07" "08" "09" "10" "11" "12" "13" "14" "15"
+#> [16] "16"
+tasks(proj)
+#> [1] "balloonanalogrisktask"
+head(func_scans(proj, full_path = FALSE))
+#> [1] "sub-01/func/sub-01_task-balloonanalogrisktask_run-01_bold.nii.gz"
+#> [2] "sub-01/func/sub-01_task-balloonanalogrisktask_run-02_bold.nii.gz"
+#> [3] "sub-01/func/sub-01_task-balloonanalogrisktask_run-03_bold.nii.gz"
+#> [4] "sub-02/func/sub-02_task-balloonanalogrisktask_run-01_bold.nii.gz"
+#> [5] "sub-02/func/sub-02_task-balloonanalogrisktask_run-02_bold.nii.gz"
+#> [6] "sub-02/func/sub-02_task-balloonanalogrisktask_run-03_bold.nii.gz"
+

Related APIs include read_events(), +query_files(), get_metadata(), +derivative_pipelines(), and create_mock_bids() +for offline fixtures. See the vignettes linked above for worked +examples.

+

fMRIPrep confounds

+

read_confounds() selects nuisance regressors from +fMRIPrep confound tables. Prefer the public, version-robust helpers over +hand-listed column names:

+
# Named, version-robust sets (resolve to whatever columns your dataset has)
+read_confounds(proj, cvars = confound_set("motion24"))
+read_confounds(proj, cvars = confound_set("36p"))
+
+# PCA + raw denoising strategies (recommended modern default)
+read_confounds(proj, cvars = confound_strategy("pcabasic80"))
+
+# Discover what is available
+list_confound_sets()
+list_confound_strategies()
+

Code that previously reached into the unexported +bidser:::DEFAULT_CVARS2 should switch to the stable public +handle confound_set("legacy_default"), which returns the +identical 26-name set. See ?read_confounds, +?confound_set, and the confounds +vignette.

diff --git a/README.md b/README.md index 89855906..4abe21e5 100644 --- a/README.md +++ b/README.md @@ -5,41 +5,79 @@ +[![CRAN +status](https://www.r-pkg.org/badges/version/bidser)](https://CRAN.R-project.org/package=bidser) [![R-CMD-check](https://github.com/bbuchsbaum/bidser/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/bbuchsbaum/bidser/actions/workflows/R-CMD-check.yaml) +[![pkgdown](https://github.com/bbuchsbaum/bidser/actions/workflows/pkgdown.yaml/badge.svg)](https://bbuchsbaum.github.io/bidser/) [![Codecov test coverage](https://codecov.io/gh/bbuchsbaum/bidser/branch/master/graph/badge.svg)](https://app.codecov.io/gh/bbuchsbaum/bidser?branch=master) -[![Lifecycle: -experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental) -[![CRAN -status](https://www.r-pkg.org/badges/version/bidser)](https://CRAN.R-project.org/package=bidser) -[BIDS](https://bids.neuroimaging.io/) in R – (it’s a start!) +**bidser** reads and queries [BIDS](https://bids.neuroimaging.io/) +(Brain Imaging Data Structure) neuroimaging projects in R: locate +subjects, sessions, tasks, and files; resolve sidecar metadata; discover +derivative pipelines; and extract fMRIPrep confounds. -The goal of bidser is to make working with the BIDS neuroimaging format -convenient in R. Current support is strongest for MRI datasets, with -explicit query helpers, metadata inheritance, derivative pipeline -discovery, and compatibility-oriented support for -[fmriprep](https://fmriprep.org/en/stable/) workflows. +[Documentation](https://bbuchsbaum.github.io/bidser/) · [Getting +started](https://bbuchsbaum.github.io/bidser/articles/quickstart.html) · +[Derivatives](https://bbuchsbaum.github.io/bidser/articles/derivatives.html) +· +[Confounds](https://bbuchsbaum.github.io/bidser/articles/confounds-and-variables.html) +· [API reference](https://bbuchsbaum.github.io/bidser/reference/) · +[Changelog](NEWS.md) ## Installation -Install the development version from [GitHub](https://github.com/) with: +Install the released version from CRAN: ``` r -# install.packages("devtools") -devtools::install_github("bbuchsbaum/bidser") +install.packages("bidser") ``` -## Example +Or the development version from GitHub: + +``` r +# install.packages("remotes") +remotes::install_github("bbuchsbaum/bidser") +``` + +CRAN currently publishes 0.5.0; this repository is at 0.5.1. + +## Quick start + +Load a BIDS project and query functional scans with the public entry +points `bids_project()`, `participants()`, `tasks()`, and +`func_scans()`: + +``` r +library(bidser) + +ds_path <- get_example_bids_dataset("ds001") +proj <- bids_project(ds_path) + +participants(proj) +#> [1] "01" "02" "03" "04" "05" "06" "07" "08" "09" "10" "11" "12" "13" "14" "15" +#> [16] "16" +tasks(proj) +#> [1] "balloonanalogrisktask" +head(func_scans(proj, full_path = FALSE)) +#> [1] "sub-01/func/sub-01_task-balloonanalogrisktask_run-01_bold.nii.gz" +#> [2] "sub-01/func/sub-01_task-balloonanalogrisktask_run-02_bold.nii.gz" +#> [3] "sub-01/func/sub-01_task-balloonanalogrisktask_run-03_bold.nii.gz" +#> [4] "sub-02/func/sub-02_task-balloonanalogrisktask_run-01_bold.nii.gz" +#> [5] "sub-02/func/sub-02_task-balloonanalogrisktask_run-02_bold.nii.gz" +#> [6] "sub-02/func/sub-02_task-balloonanalogrisktask_run-03_bold.nii.gz" +``` -See +Related APIs include `read_events()`, `query_files()`, `get_metadata()`, +`derivative_pipelines()`, and `create_mock_bids()` for offline fixtures. +See the vignettes linked above for worked examples. ## fMRIPrep confounds `read_confounds()` selects nuisance regressors from fMRIPrep confound -tables. Rather than hand-listing version-specific column names, use the -high-level, version-robust helpers: +tables. Prefer the public, version-robust helpers over hand-listed +column names: ``` r # Named, version-robust sets (resolve to whatever columns your dataset has) @@ -57,5 +95,5 @@ list_confound_strategies() Code that previously reached into the unexported `bidser:::DEFAULT_CVARS2` should switch to the stable public handle `confound_set("legacy_default")`, which returns the identical 26-name -set. See `?read_confounds`, `?confound_set`, and the -*confounds-and-variables* vignette for details. +set. See `?read_confounds`, `?confound_set`, and the [confounds +vignette](https://bbuchsbaum.github.io/bidser/articles/confounds-and-variables.html). From c4a655afe1890a1f12f51c8f8a56fe61935f1dd8 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Tue, 8 Sep 2026 07:47:24 +0000 Subject: [PATCH 2/2] Make README quick start offline with create_mock_bids() Avoid get_example_bids_dataset() in the documented install path: it needs Suggests-only httr and network access. Use the exported create_mock_bids() fixture so the quick start runs after install.packages("bidser"). Co-authored-by: bbuchsbaum --- README.Rmd | 28 ++++++++++++++++++++-------- README.html | 51 +++++++++++++++++++++++++++++---------------------- README.md | 42 +++++++++++++++++++++++++----------------- 3 files changed, 74 insertions(+), 47 deletions(-) diff --git a/README.Rmd b/README.Rmd index 5fa276f4..69f6af58 100644 --- a/README.Rmd +++ b/README.Rmd @@ -55,23 +55,35 @@ CRAN currently publishes 0.5.0; this repository is at 0.5.1. ## Quick start -Load a BIDS project and query functional scans with the public entry points -`bids_project()`, `participants()`, `tasks()`, and `func_scans()`: +Build an offline mock project (no Suggests packages or downloads), then query +it with the public entry points `participants()`, `tasks()`, and +`func_scans()`. Point the same helpers at a real tree via `bids_project()`: ```{r} library(bidser) -ds_path <- get_example_bids_dataset("ds001") -proj <- bids_project(ds_path) +proj <- create_mock_bids( + project_name = "demo", + participants = c("01", "02"), + file_structure = data.frame( + subid = c("01", "02"), + datatype = "func", + task = "rest", + run = "01", + suffix = "bold.nii.gz", + fmriprep = FALSE, + stringsAsFactors = FALSE + ) +) participants(proj) tasks(proj) -head(func_scans(proj, full_path = FALSE)) +func_scans(proj, full_path = FALSE) ``` -Related APIs include `read_events()`, `query_files()`, `get_metadata()`, -`derivative_pipelines()`, and `create_mock_bids()` for offline fixtures. -See the vignettes linked above for worked examples. +Related APIs include `read_events()`, `query_files()`, `get_metadata()`, and +`derivative_pipelines()`. For a downloaded example dataset see +[Getting started](https://bbuchsbaum.github.io/bidser/articles/quickstart.html). ## fMRIPrep confounds diff --git a/README.html b/README.html index 1fa8eb59..77c5ef4c 100644 --- a/README.html +++ b/README.html @@ -626,31 +626,38 @@

Installation

remotes::install_github("bbuchsbaum/bidser")

CRAN currently publishes 0.5.0; this repository is at 0.5.1.

Quick start

-

Load a BIDS project and query functional scans with the public entry -points bids_project(), participants(), -tasks(), and func_scans():

+

Build an offline mock project (no Suggests packages or downloads), +then query it with the public entry points participants(), +tasks(), and func_scans(). Point the same +helpers at a real tree via bids_project():

library(bidser)
 
-ds_path <- get_example_bids_dataset("ds001")
-proj <- bids_project(ds_path)
-
-participants(proj)
-#>  [1] "01" "02" "03" "04" "05" "06" "07" "08" "09" "10" "11" "12" "13" "14" "15"
-#> [16] "16"
-tasks(proj)
-#> [1] "balloonanalogrisktask"
-head(func_scans(proj, full_path = FALSE))
-#> [1] "sub-01/func/sub-01_task-balloonanalogrisktask_run-01_bold.nii.gz"
-#> [2] "sub-01/func/sub-01_task-balloonanalogrisktask_run-02_bold.nii.gz"
-#> [3] "sub-01/func/sub-01_task-balloonanalogrisktask_run-03_bold.nii.gz"
-#> [4] "sub-02/func/sub-02_task-balloonanalogrisktask_run-01_bold.nii.gz"
-#> [5] "sub-02/func/sub-02_task-balloonanalogrisktask_run-02_bold.nii.gz"
-#> [6] "sub-02/func/sub-02_task-balloonanalogrisktask_run-03_bold.nii.gz"
+proj <- create_mock_bids( + project_name = "demo", + participants = c("01", "02"), + file_structure = data.frame( + subid = c("01", "02"), + datatype = "func", + task = "rest", + run = "01", + suffix = "bold.nii.gz", + fmriprep = FALSE, + stringsAsFactors = FALSE + ) +) + +participants(proj) +#> [1] "01" "02" +tasks(proj) +#> [1] "rest" +func_scans(proj, full_path = FALSE) +#> [1] "sub-01/func/sub-01_task-rest_run-01_bold.nii.gz" +#> [2] "sub-02/func/sub-02_task-rest_run-01_bold.nii.gz"

Related APIs include read_events(), -query_files(), get_metadata(), -derivative_pipelines(), and create_mock_bids() -for offline fixtures. See the vignettes linked above for worked -examples.

+query_files(), get_metadata(), and +derivative_pipelines(). For a downloaded example dataset +see Getting +started.

fMRIPrep confounds

read_confounds() selects nuisance regressors from fMRIPrep confound tables. Prefer the public, version-robust helpers over diff --git a/README.md b/README.md index 4abe21e5..f84ea430 100644 --- a/README.md +++ b/README.md @@ -45,33 +45,41 @@ CRAN currently publishes 0.5.0; this repository is at 0.5.1. ## Quick start -Load a BIDS project and query functional scans with the public entry -points `bids_project()`, `participants()`, `tasks()`, and -`func_scans()`: +Build an offline mock project (no Suggests packages or downloads), then +query it with the public entry points `participants()`, `tasks()`, and +`func_scans()`. Point the same helpers at a real tree via +`bids_project()`: ``` r library(bidser) -ds_path <- get_example_bids_dataset("ds001") -proj <- bids_project(ds_path) +proj <- create_mock_bids( + project_name = "demo", + participants = c("01", "02"), + file_structure = data.frame( + subid = c("01", "02"), + datatype = "func", + task = "rest", + run = "01", + suffix = "bold.nii.gz", + fmriprep = FALSE, + stringsAsFactors = FALSE + ) +) participants(proj) -#> [1] "01" "02" "03" "04" "05" "06" "07" "08" "09" "10" "11" "12" "13" "14" "15" -#> [16] "16" +#> [1] "01" "02" tasks(proj) -#> [1] "balloonanalogrisktask" -head(func_scans(proj, full_path = FALSE)) -#> [1] "sub-01/func/sub-01_task-balloonanalogrisktask_run-01_bold.nii.gz" -#> [2] "sub-01/func/sub-01_task-balloonanalogrisktask_run-02_bold.nii.gz" -#> [3] "sub-01/func/sub-01_task-balloonanalogrisktask_run-03_bold.nii.gz" -#> [4] "sub-02/func/sub-02_task-balloonanalogrisktask_run-01_bold.nii.gz" -#> [5] "sub-02/func/sub-02_task-balloonanalogrisktask_run-02_bold.nii.gz" -#> [6] "sub-02/func/sub-02_task-balloonanalogrisktask_run-03_bold.nii.gz" +#> [1] "rest" +func_scans(proj, full_path = FALSE) +#> [1] "sub-01/func/sub-01_task-rest_run-01_bold.nii.gz" +#> [2] "sub-02/func/sub-02_task-rest_run-01_bold.nii.gz" ``` Related APIs include `read_events()`, `query_files()`, `get_metadata()`, -`derivative_pipelines()`, and `create_mock_bids()` for offline fixtures. -See the vignettes linked above for worked examples. +and `derivative_pipelines()`. For a downloaded example dataset see +[Getting +started](https://bbuchsbaum.github.io/bidser/articles/quickstart.html). ## fMRIPrep confounds