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.
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.
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 ,
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:
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 workflow, 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.