Beacon v2 Models

BFF stands for Beacon Friendly Format. The BFF is a data exchange format composed of 7 JSON files. These files correspond to the 7 entities of the Beacon v2 Models.

RoleNative input

Accepted inputindividuals.json array

ConfigurationBuilt in

Best forBeacon v2 individual-level records

Entities in Beacon v2 Models

About Beacon v2 Models' entities

Of the seven entities (a.k.a., entry types) in the Beacon v2 Models, individuals is typically the only one that contains phenotypic data (represented at record-level granularity).

Pheno-Ranker accepts data from the individuals entity, serialized in BFF format (individuals.json).

Browsing BFF JSON data

You can browse a public BFF v2 file with the following JSON viewers:

• JSON Hero
• Datasette

BFF As Input

The examples below show the minimal command-line patterns. For the complete CLI reference, see Usage.

How are BFF arrays compared?

For first-level BFF arrays such as diseases, exposures, interventionsOrProcedures, measures, phenotypicFeatures, and treatments, Pheno-Ranker replaces numeric array indexes with semantic identifiers configured in identity_paths.

From v1.08 onward, users do not need to transpose or manually rewrite nested BFF arrays. Nested arrays are canonicalized automatically from their meaningful content, so equivalent nested objects can match even if their order differs between records.

Cohort mode

Basic run:

pheno-ranker -r individuals.json

The default output is named matrix.txt. It is an N x N matrix with pairwise comparisons for all individuals.

For more information visit the cohort mode page.

Patient mode

Basic run:

pheno-ranker -r individuals.json -t patient.json

The output will be printed to STDOUT and to a file named rank.txt. The matching individuals will be sorted according to their Hamming distance to the reference patient. See additional details in the Patient Mode page.

For more information visit the patient mode page.