Skip to content

Implementation

Components

Convert-Pheno is a toolkit composed of several interfaces around the same Perl core. At the center is the Perl module, which is used by the command-line interface and by the API. A Python interoperability layer is also included in the repository, but the conversion logic itself remains in Perl. The Web App is built on top of the command-line interface.

%%{init: {'theme':'neutral'}}%% graph TB subgraph "Perl" A[Module]--> B[CLI] A[Module]--> C[API] end subgraph "Python / JavaScript" B --> D[Web App UI] end subgraph "Python" A --> |Python Binding| E[Module] E --> F[API] end style A fill: #6495ED, stroke: #6495ED style B fill: #6495ED, stroke: #6495ED style C fill: #6495ED, stroke: #6495ED style D fill: #AFEEEE, stroke: #AFEEEE style E fill: #FFFF33, stroke: #FFFF33 style F fill: #FFFF33, stroke: #FFFF33
Diagram showing Convert-Pheno implementation

Which one should I use?

Most users find the CLI suitable for their needs. Begin by experimenting with the data in the Web App UI Playground.

Power users may want to check the module or the API version.

API scope

The HTTP API is primarily intended for self-contained JSON conversions such as BFF, PXF, and carefully prepared OMOP-CDM payloads.

Mapping-file-based routes such as CSV, REDCap, and CDISC-ODM are still better handled through the CLI, because they depend on extra artifacts like mapping files and data dictionaries rather than on one clean request payload.

Software architecture

The core module is divided into several sub-modules. The main package, Convert::Pheno, handles class initialization and employs the Moo module along with Types::Standard for data validation. In architectural terms, most conversions still use BFF as the internal target or center model: source formats are first mapped to normalized Beacon individuals, and from there can continue to outputs such as PXF or OMOP CDM.

Starting with v0.30, the implementation also uses an explicit internal conversion context and bundle model for BFF output. This matters whenever the input contains information that belongs to more than one Beacon entity. PXF biosample data can now be emitted as first-class biosamples, while datasets and cohorts can be synthesized from the normalized individuals collection. The -obff FILE path is still kept as a backward-compatible individuals-only BFF output mode.

After validation, the user-selected method (for example pxf2bff) is executed, directing the data to the respective independent modules, each tailored for converting a specific input format.

Why Perl?

The choice of Perl as a language is due to its inherent speed in text processing and its use of sigils to distinguish data types within intricate data structures.