CSV

Experimental feature

CSV conversion to BFF, PXF and OMOP CDM data exchange formats is still in the development phase. Please us it with caution.

RoleInput

Accepted inputDelimited clinical text

Main outputBFF, PXF, OMOP-CDM

Notes--search-audit-tsv for ontology lookups

CSV with clinical data as input

Note

This conversion method helps users who don't have the tools or expertise to transform their raw clinical data. It aims to convert essential fields needed for comparing data across studies.

If you use our tool and identify areas for improvement, please contact us or create a GitHub issue. Thank you.

Command-line

When using the convert-pheno command-line interface, simply ensure the correct syntax is provided.

CSV Separator Notice

Please note that the default separator for CSV files is ;. If your file uses a different character (e.g., , or :), please specify it using the --sep option.

    convert-pheno -icsv clinical_data.csv --mapping-file clinical_data_mapping.yaml -obff individuals.json --sep ,

By default, the generated BFF keeps a copy of the source row under info.CSV_columns so users can audit mapped values against the original input. Use --no-source-info to omit that raw source snapshot.

Please refer to the Convert-Pheno tutorial for more information.

How do I emit more than individuals?

Mapping-file conversions can also emit synthesized Beacon datasets and cohorts. Keep -obff to select BFF output, then add --entities and --out-dir:

        convert-pheno -icsv clinical_data.csv --mapping-file clinical_data_mapping.yaml -obff --entities individuals datasets cohorts --out-dir out/

The top-level beacon section of the mapping file can override metadata for these synthesized entities. Raw CSV input does not currently generate first-class Beacon biosamples.

See examples:

Input

• CSV data
• Mapping file

Output

• BFF
• PXF

API

While it is technically possible to perform a transformation via the Convert-Pheno API, we don't think this is how most people will transform CSV files (due to the need of the mapping file). Therefore, we recommend using the command-line version.

If you still want to call the API, the request payload uses explicit conversion, input, and options sections:

    {
      "conversion": "csv2bff",
      "input": {
        "in_file": "clinical_data.csv",
        "mapping_file": "clinical_data_mapping.yaml"
      },
      "options": {
        "sep": ","
      }
    }

Input	CLI	UI	Module	Public API
Beacon v2 Models	YES	YES	YES	YES
CDISC-ODM	YES	YES	YES	NO
CSV	YES	NO	YES	NO
Phenopackets v2	YES	YES	YES	YES
OMOP-CDM	YES	YES	YES	YES
REDCap	YES	YES	YES	NO

Public API = NO here means not recommended as a public HTTP(s) route, even if advanced local or internal setups could still call the module with file-oriented parameters.

In practice, the public API is meant for self-contained JSON payloads such as BFF, PXF, and carefully prepared OMOP-CDM. Mapping-file-based conversions such as CSV, REDCap, and CDISC-ODM are better handled through the CLI.