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

Beacon entity context; Pheno-Ranker directly reads the individuals collection.

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

Run This Format

Desktop

1. Select New analysis, then choose cohort or patient mode.
2. Open User files and select individuals.json as the reference cohort.
3. In patient mode, also select the target record.
4. Select Run analysis.

No configuration file is required. See the Desktop guide for the visual workflow.

CLI

For cohort mode:

pheno-ranker -r individuals.json

For patient mode:

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

The commands create matrix.txt and rank.txt, respectively. Continue with Cohort Mode, Patient Mode, or the full CLI Reference.

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.