diff --git a/README.Rmd b/README.Rmd
index d4d76f1..69f6af5 100644
--- a/README.Rmd
+++ b/README.Rmd
@@ -9,47 +9,89 @@ knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
- out.width = "100%"
+ out.width = "100%",
+ message = FALSE,
+ warning = FALSE
)
```
# bidser
+[](https://CRAN.R-project.org/package=bidser)
[](https://github.com/bbuchsbaum/bidser/actions/workflows/R-CMD-check.yaml)
+[](https://bbuchsbaum.github.io/bidser/)
[](https://app.codecov.io/gh/bbuchsbaum/bidser?branch=master)
-[](https://lifecycle.r-lib.org/articles/stages.html#experimental)
-[](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:
-Install the development version from [GitHub](https://github.com/) with:
+```r
+install.packages("bidser")
+```
-``` r
-# install.packages("devtools")
-devtools::install_github("bbuchsbaum/bidser")
+Or the development version from GitHub:
+
+```r
+# install.packages("remotes")
+remotes::install_github("bbuchsbaum/bidser")
```
-## Example
-See https://bbuchsbaum.github.io/bidser/articles/quickstart.html
+CRAN currently publishes 0.5.0; this repository is at 0.5.1.
+
+## Quick start
+
+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)
+
+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)
+func_scans(proj, full_path = FALSE)
+```
+
+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
-`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 +104,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 7de3538..77c5ef4 100644
--- a/README.html
+++ b/README.html
@@ -606,21 +606,78 @@
bidser
-
+
-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
+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)
+
+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(), 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
+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.