Skip to content

Beacon v2 Models (BFF)

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.

Beacon v2

Entities in Beacon v2 Models

About Beacon v2 Models' entities

Among the seven entity types (also known as entry types) in the Beacon v2 Models, the individuals entity is typically the only one that contains phenotypic data, represented with record-level granularity. Other entities, such as datasets and biosamples, may also hold useful information. However, they generally pose fewer challenges for data conversion, primarily consisting of plain text with fewer nested properties.

As an input, Convert-Pheno 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:

BFF (individuals) as input BFF

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

About JSON data in individuals.json

If the file individuals.json is a JSON array of objects (for which each object corresponds to an individual), the output -opxf file will also be a JSON array.

convert-pheno -ibff individuals.json -opxf phenopacket.json

The concept is to pass the necessary information as a hash (in Perl) or dictionary (in Python).

$bff = {
    data => $my_bff_json_data,
    method => 'bff2pxf'
};

bff = {
     "data" : my_bff_json_data,
     "method" : "bff2pxf"
}

The data will be sent as POST to the API's URL (see more info here). 

{
"data": {...}
"method": "bff2pxf"
}

Please find below examples of data:

{
  "ethnicity": {
    "id": "NCIT:C42331",
    "label": "African"
  },
  "id": "HG00096",
  "info": {
    "eid": "fake1"
  },
  "interventionsOrProcedures": [
    {
      "procedureCode": {
        "id": "OPCS4:L46.3",
        "label": "OPCS(v4-0.0):Ligation of visceral branch of abdominal aorta NEC"
      }
    }
  ],
  "measures": [
    {
      "assayCode": {
        "id": "LOINC:35925-4",
        "label": "BMI"
      },
      "date": "2021-09-24",
      "measurementValue": {
        "quantity": {
          "unit": {
            "id": "NCIT:C49671",
            "label": "Kilogram per Square Meter"
          },
          "value": 26.63838307
        }
      }
    },
    {
      "assayCode": {
        "id": "LOINC:3141-9",
        "label": "Weight"
      },
      "date": "2021-09-24",
      "measurementValue": {
        "quantity": {
          "unit": {
            "id": "NCIT:C28252",
            "label": "Kilogram"
          },
          "value": 85.6358
        }
      }
    },
    {
      "assayCode": {
        "id": "LOINC:8308-9",
        "label": "Height-standing"
      },
      "date": "2021-09-24",
      "measurementValue": {
        "quantity": {
          "unit": {
            "id": "NCIT:C49668",
            "label": "Centimeter"
          },
          "value": 179.2973
        }
      }
    }
  ],
  "sex": {
    "id": "NCIT:C20197",
    "label": "male"
  }
}

{
   "diseases" : [],
   "id" : "phenopacket_id.AUNb6vNX1",
   "measurements" : [
      {
         "assay" : {
            "id" : "LOINC:35925-4",
            "label" : "BMI"
         },
         "value" : {
            "quantity" : {
               "unit" : {
                  "id" : "NCIT:C49671",
                  "label" : "Kilogram per Square Meter"
               },
               "value" : 26.63838307
            }
         }
      },
      {
         "assay" : {
            "id" : "LOINC:3141-9",
            "label" : "Weight"
         },
         "value" : {
            "quantity" : {
               "unit" : {
                  "id" : "NCIT:C28252",
                  "label" : "Kilogram"
               },
               "value" : 85.6358
            }
         }
      },
      {
         "assay" : {
            "id" : "LOINC:8308-9",
            "label" : "Height-standing"
         },
         "value" : {
            "quantity" : {
               "unit" : {
                  "id" : "NCIT:C49668",
                  "label" : "Centimeter"
               },
               "value" : 179.2973
            }
         }
      }
   ],
   "medicalActions" : [
      {
         "procedure" : {
            "code" : {
               "id" : "OPCS4:L46.3",
               "label" : "OPCS(v4-0.0):Ligation of visceral branch of abdominal aorta NEC"
            },
            "performed" : {
               "timestamp" : "1900-01-01T00:00:00Z"
            }
         }
      }
   ],
   "metaData" : null,
   "subject" : {
      "id" : "HG00096",
      "sex" : "MALE",
      "vitalStatus" : {
         "status" : "ALIVE"
      }
   }
}