National Institutes of Health Brain Development Cohorts Data Hub Tools

A suite of functions to work with data from the National Institutes of Health Brain Development Cohorts Data Hub. The package provides tools to create, clean, process, and filter datasets and associated metadata. These utilities are intended to simplify reproducible data-preparation for future research.

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 stable version of the main package from CRAN, and the data package from r-universe, use the following command:

install.packages("NBDCtools")
install.packages("NBDCtoolsData", repos = "https://nbdc-datahub.r-universe.dev")

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:

install.packages("NBDCtools", dependencies = TRUE)
# or some specific dependencies
install.packages("naniar") # e.g. shadow matrix processing

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/[email protected]")
remotes::install_github("nbdc-datahub/[email protected]")

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.

Using tarballs to install

On every new release page of the NBDCtools and NBDCtoolsData, you can find the source tarballs (tar.gz files) for the corresponding release. If compute environments do not have internet access, you can download the tarballs on a different machine and transfer them to the target environment. Then, use the following command to install the packages from the local tarball files:

install.packages("path/to/NBDCtools_x.y.z.tar.gz", repos = NULL, type = "source")
install.packages("path/to/NBDCtoolsData_x.y.z.tar.gz", repos = NULL, type = "source")

However, please make sure that all dependencies are already installed in the target environment, as the installation from tarballs does not resolve dependencies automatically, for example, please see the list of dependencies in the DESCRIPTION Imports and Suggests fields.

Usage

For a general overview of how to download data from the NBDC Data Hub and use this R package to create custom 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.