Skip to contents

NBDCtools

This R package provides functions for working with data released by the NIH Brain Development Cohorts (NBDC) Data Hub, which currently offers data for the ABCD and HBCD studies.

The NBDCtools package is designed to help researchers and data analysts create analysis-ready datasets from the tabulated data released by the ABCD and HBCD studies. Its core functionality is to join selected variables and/or entire tables from the tabulated data files into a single data frame in memory. Additionally, the package offers several functions to assist users in working with the data, including:

  • Transformation functions to convert categorical columns to (ordered or unordered) factors based on the data dictionary and levels table, or to add variable and value labels to a dataset.
  • Filter/subsetting functions to filter by a set of participant/events, filter ABCD events using shorthands, or exclude rows or columns with only missing data.
  • Functions to retrieve and utilize metadata from the studies.
  • A set of utility functions for various use cases.

Installation

IMPORTANT: Besides the NBDCtools main package, users also need to install the accompanying NBDCtoolsData package, which contains the large data dictionary and levels tables used by the NBDCtools package.

To install the latest version of the packages from GitHub, use the following command:

if (!requireNamespace("remotes", quietly = TRUE)) {
  install.packages("remotes")
}
  
remotes::install_github("nbdc-datahub/NBDCtools")
remotes::install_github("nbdc-datahub/NBDCtoolsData")

There are some additional dependencies that are not installed by default, as they are only needed for specific features, such as processing shadow matrices. To install all the dependencies, use the following command:

remotes::install_github("nbdc-datahub/NBDCtools", dependencies = TRUE)

To install a specific version of the package, specify the version number in the remotes::install_github() call. For example, to install version 1.0.0, use the following command:

remotes::install_github("nbdc-datahub/NBDCtools@v1.0.0")
remotes::install_github("nbdc-datahub/NBDCtoolsData@v1.0.0")

NOTE: The NBDCtoolsData package version does not match the NBDCtools package version, i.e., the two package follow different release cycles. For example, the NBDCtools package may not be changed across ABCD/HBCD data releases, but the NBDCtoolsData package is updated with each data release. Therefore, it is recommended to always update the data package to the latest version.

Some package dependencies are not installed by default, as they are only needed for specific features, such as processing shadow matrices. To install these dependencies, use the following command:

# for shadow_bind_data function
install.packages("naniar")

Usage

For a general overview of how to use the R package to handle NBDC datasets, see the Get Started page. To browse the documentation of all available functions, see the Reference page. For more detailed information about different categories of functions, refer to the vignettes.

Issues

If you encounter issues while using this package, please report them by submitting a GitHub issue. Please do not submit any issues related to the ABCD or HBCD data resources themselves (see here for information on how to report issues with the data resource).

Citation

We are currently preparing a paper about NBDCtools. The reference will be added here once the paper is published.