REDCap

Category: Electronic data capture (EDC) platform

REDCap stands for Research Electronic Data Capture. Its projects define their own fields and coded values, so Convert-Pheno combines a REDCap CSV export, data dictionary, and project mapping file before conversion.

Implementation and validation status

REDCap conversion is implemented and covered by regression tests, including data-dictionary and mapping-file processing. Because projects are free-form, review the project mapping, optional terminology audit, and generated output. Independent validation across diverse REDCap projects remains ongoing.

RoleInput

Accepted inputCSV export, dictionary, mapping file

Main outputBFF, PXF, OMOP-CDM

NotesKeep exports as UTF-8 text files

Project data and dictionary metadata are interpreted through the user mapping

REDCap As Input

REDCap projects are free-form: project authors choose variable names, field types, coded values, and event structures. Convert-Pheno therefore needs three project files:

1. A REDCap data export in CSV format
2. The REDCap data dictionary in CSV format
3. A Convert-Pheno mapping file in YAML or JSON

Export all records and fields. Gzip-compressed CSV inputs are accepted. A REDCap CDISC-ODM export follows the separate CDISC-ODM route.

REDCap export settings

1. In REDCap, choose the report or project export containing all required records and fields.
2. Select CSV / Microsoft Excel (raw data). Raw coded values can be decoded using the REDCap data dictionary; a labels export does not provide the same stable mapping contract.

Select the raw-data CSV export rather than the labels export

3. Leave Combine checkbox options into a single column unchecked. Separate checkbox columns preserve the coded field structure expected by the dictionary and mapping file. Removing line breaks from text values is recommended for a reliable CSV export.

Keep checkbox options in separate columns

4. Download the project's data dictionary as CSV. Keep both CSV files as downloaded text files and create the Convert-Pheno mapping separately.

Keep REDCap text exports as UTF-8 text files

Do not open and resave REDCap CSV exports or dictionaries with spreadsheet software such as Excel before conversion. This can alter UTF-8 text and corrupt characters such as µ, ≥, accents, or degree symbols, breaking dictionary values and ontology mappings.

The mapping file defines how project variables become Beacon individuals and, when configured, first-class biosamples. The Mapping Files guide covers the workflow and complete Mapping V2 contract.

Use REDCap conversion recipes for BFF, PXF, and OMOP-CDM commands.

Output Review

Generated BFF records preserve the original source row under info.REDCap_columns by default. Use --no-source-info when that copy is not needed.

--term-audit records the source row, original and converted labels, converted identifier, ontology, match status, match source, and effective search settings. Review this file when project terms are resolved through the bundled SQLite ontology databases.

Mapping-file routes can also emit biosamples defined by beacon.biosamples.rules and synthesize Beacon datasets and cohorts. Dataset and cohort metadata can be set under their defaults sections.

Longitudinal REDCap data

REDCap event information is retained under BFF info because the Beacon v2 individuals model has no direct longitudinal event structure.

REDCap API support

Convert-Pheno reads REDCap exports; it does not retrieve records through the REDCap API. The Convert-Pheno HTTP(s) API can receive file paths, but the CLI is normally more practical when data, dictionary, and mapping files are required.