CSV

Category: Tabular source format

CSV is a general delimited-text format rather than a clinical data standard. Convert-Pheno interprets project-specific clinical rows through a required mapping file, then writes BFF, PXF, or the supported OMOP-CDM tables.

Implementation and validation status

CSV conversion to BFF, PXF, and the supported OMOP-CDM tables is implemented and covered by regression tests. Results depend on the project mapping file, so review the mapping, optional terminology audit, and generated output for each dataset.

RoleInput

Accepted inputDelimited clinical text

Main outputBFF, PXF, OMOP-CDM

Notes--term-audit for terminology review

Tabular fields are mapped through BFF before the requested output is written

CSV As Input

CSV input is intended for project-specific clinical tables that do not already follow another supported model. A YAML or JSON mapping file is required to connect source columns and values to Beacon individuals fields and, when the source includes specimen records, first-class biosamples.

CSV separator

The default separator is ;. Use --sep when a file uses a comma, tab, or another delimiter.

Starting with an unfamiliar CSV?

Follow the CSV-to-validated-BFF mapping recipe. It includes a complete Mapping V2 file, terminology auditing, LLM-term checks, and final validation with bff-tools.

Use CSV conversion recipes for BFF, PXF, OMOP-CDM, and multi-entity BFF commands. Mapping semantics are documented under Mapping Files, with ontology lookup behavior under Terminology Search.

CSV to OMOP-CDM

The CSV-to-OMOP route is a focused, schema-aware ETL path. Convert-Pheno maps each source record to its internal BFF representation and then applies the supported BFF-to-OMOP mapping; users do not create the intermediate BFF file.

OMOP output requires the Athena-OHDSI database selected by --ohdsi-db. Generated output is limited to the documented tables and fields and must be reviewed before database loading.

Scope of the ETL path

This route does not automatically profile an unfamiliar CSV or make terminology-curation decisions. The mapping file replaces the source-model definition step; it is not a one-for-one implementation of White Rabbit, Rabbit-in-a-Hat, or Usagi.

Output Review

BFF output preserves each source row under info.CSV_columns by default. Use --no-source-info to omit that copy. Mapping-file routes can map biosamples through beacon.biosamples.rules and synthesize datasets and cohorts, with metadata under the corresponding defaults sections.

Tested source, mapping, and reference-output files are indexed in the t/ fixture guide.